QualityCentral web services guide

By: John Kaster

Abstract: Documentation on the QualityCentral (QC) web service interfaces

This is a working document for using the QualityCentral (QC) Web Service.

The client interface for the web service is documented here. The web service does evolve in a backward-compatible way, so be sure to check it for updates if you're implementing a new client.

    Using the web service

When you look at the documented interface listed above, you will note that many of the routines return a Base64Binary type. The return value for these methods is a compressed XML version of ClientDataset data packet. To find out more about XML datapackets for ClientDataset, see the article the express way to the Internet, Part 2.

For Delphi, C++Builder, or Kylix applications, you can directly assign the uncompressed and unencoded version of this result set to a ClientDataSet component's XMLData property.

    Session IDs

Almost every method in QC requires a session ID parameter. You can retrieve a session ID by calling the login method in with your registered QC email address and password. SessionIDs are actually returns as a column of a single user record that includes things like your userid, sysop level, email, ... everything you can change on the options dialog except your password. You will need to extract the session ID value from this data packet.

The session IDs returns are compressed with Zlib. The Delphi code submission for encoding and compressing listed below provides routines that will handle Session IDs. Once you have extracted the session ID, you can pass that as a plain-text string to all the methods that require it. Currently, your session ID is active for 90 minutes. If you make another call within 90 minutes, your session ID will be refreshed and good for another 90 minutes.

If your session ID expires, a SOAP fault will be returned. If this occurs, you can trap that exception and log back in to retrieve a new session ID. Once you have an active session ID, you're ready to call the methods of the web service.

    SOAP Faults

If a method is not yet implemented, you will receive a SOAP fault indicating that it is not yet implemented.

    Methods to note

The names of most of the methods are self-explanatory. One that is important for writing your own web service client to QC is LastInterfaceChange. This will return the date and time of the last change made to the client web service interface. Additional parameters may be added to existing methods, and new methods may appear. It is not likely that a change that breaks the current interface will be required. However, since this is a beta, it's certainly possible some interface incompatibilities may happen.

If you're writing your own client, the CurrentClientVersion method is probably of less interest than the above method since it returns the version of the current GUI client :-).

GetOutline returns the outline areas for all projects. It is an internally-related dataset. You will need to filter this outline based on the active project.

GetProjects returns the list of all projects.

    Available source code

These source code routines may help you when writing your own web service client for QualityCentral.

This is the only code snippet currently available for Java

import java.io.*;

import java.util.zip.InflaterInputStream;

import javax.mail.internet.MimeUtility;

InputStream in = new InflaterInputStream( MimeUtility.decode(

new ByteArrayInputStream( bytes ), "base64" ) );

    Writing a client

When you write a client, you must first login and retrieve a session ID to use for most of the available web service methods. See the notes on Session IDs above.

    Use the test user

To help eliminate garbage data in QC, a test user and test areas have been created. When you are testing creation or editing of reports, use the test user. You can login as the test user with the following information:

Email: test@borland.com
Password: test

Please use the "Test project" area for client testing purposes. Data in this area will be periodically removed. We'll probably leave them active for 72 hours or so, depending on how loaded with data the test area gets.

    Argument values calling GetLookup

Some of the word values you can pass to the lookup table are documented here. Check back for updates to this list.

Value

Description

Project

List of public projects - pass ID from this column to everything requiring a project.

Platform

List of all platforms. NULL project columns belong to all projects, otherwise the ID from the corresponding project's record indicates it belongs to a project. ID is stored when a platform is asked for.

Version

Lists all versions. Project column indicates what project that version is for. lookup_value is stored.

Type

Lists all Types. Lookup_value is stored.

Severity

Lists the severity lookups. Lookup_value is stored.

Status

Lists the statuses. ID is stored.

Resolution

Lists all the resolutions. ID is stored.

    Miscellaneous notes

If you pass an empty string for the lookup name you will get all the lookups (this is the way the current client works, then they are programmatically assigned their own ClientDataSets on the client).

The sort id that comes back for a lookup_name/project tuple are unique, and change the sort order of the tree view. The lastDays argument that many of the methods accept is for items that have been created or modified in the last <NumberOfDays>

For GetAttachment, you can specify a list of files with a <cr><lf> pair separating each file name. Wildcards are not currently accepted -- the file name must be specific. If you want all the files just send the empty string.

The user information is returned as part of the login process when you get the session id. It is a superset of what GetUserInformation will probably be. GetUserInfo is for getting the public information of another user.

In the GUI client, this is only used for the Sysop level to hide things non-Sysop users can't do (even if they tried the service always checks that the sessionid belongs to a sysop), and stop them from editing/deleteing based on the user_id. If you look at things like user_id (which more than likely will not be returned in the GetUserInformation since no one else needs to know my user_id) it is never passed back to the service. The user id is always determine from the sessionid returned from the Login method.

Server Response from: ETNASC04