Seapine Labs

Getting Started

Keep the following information in mind before you get started with the TestTrack SDK:

  • A network connection must be made to the SOAP server before any requests can be sent to the server. Create a SOAP server object with methods that correspond to the available TestTrack methods. This is similar to how CORBA, EJB, or any remote object paradigm works.

  • A SOAP user must first login to the TestTrack Server with a valid username and password. This information is authenticated by the server.

  • A successful login returns a cookie that is used for all subsequent connections. The cookie is the value returned by the DatabaseLogon function, which is then passed as an argument to most other functions so that the SOAP server knows the request is coming from a logged in user and who that user is.

  • Every method, except getProjectList and projectLogon, require a cookie as an input parameter. Other methods will fail if you do not obtain a valid cookie via the projectLogon method. If you do not know what projects are available to log into, call the getProjectList method before logging on.

  • The username and password specified during the SOAP login will fail if that user does not have proper command level security. The user must be in a security group that allows login via SOAP.

  • Command-level security is also enforced on each SOAP operation call. For example if the SOAP user does not have AddDefect command level security, a call to the AddDefect operation will fail.

  • The SOAP client should always call the DatabaseLogoff method after completing its work. If you forget to logoff, the SOAP connection stays open, using a SOAP license. The SOAP connection is eventually dropped because of inactivity.

  • If there is no activity for a specified time period the SOAP connection is automatically dropped. To change the time period login to the TestTrack Server Admin Utility. Click Server Options then select the Server tab. Change the SOAP User Settings and click OK to save the changes. Refer to the TestTrack Server Admin Guide for information.

Connecting to the SOAP server

A network connection must be made to the SOAP server before any requests can be sent. Create a SOAP server object with methods that correspond to the available TestTrack methods. This is similar to how CORBA, EJB, or any remote object paradigm works.

The following Microsoft C# example is provided to help you get started with TestTrack and SOAP.

  1. The first step is to add a new Web Reference. This should point to the ttsoapcgi.wsdl file installed on the computer hosting the TestTrack SOAP Server. For example, if the .wsdl file is installed on your local computer the new Web Reference path will be http://localhost/ttsoapcgi.wsdl.

  2. You can start using the SOAP SDK after the Web Reference is set up. You should first create a ttsoapcgi object, which will be used to make calls into SOAP.For example, ttsoapcgi svr = new ttsoapcgi();

  3. Specify the connection address to the SOAP CGI. By default, the SOAP connection points to http://127.0.0.1:80/scripts/ttsoapcgi.exe. Unless the Soap CGI is installed locally, this path will not work.

    To make a change call svr.Url = http://myserver.wysicorp.com:8080/scripts/ttsoapcgi.exe

  4. You are now are ready to login and begin making calls.
  • If you know the name of the TestTrack project you want to connect to use long lCookie = svr.ProjectLogon( 'MyProject', 'administrator', '');

  • If you do not know the project name, or want to view a list of available projects, use CProject[] adb = svr.getProjectList();
    You can browse the array of projects and select one to connect to.
  1. After you log in, you must keep track of the cookie that was sent back from the successful ProjectLogon call. This cookie defines your current authenticated session and is required for all other calls into SOAP.

  2. Remember to logoff after you finish with your SOAP calls. Svr.DatabaseLogoff();

    If you do not log off, the connection remains active. The SOAP license cannot be used by other users until SOAP times out, which is defined using the TestTrack Pro Server Admin Utility, is reached.

WSDL file

WSDL (Web Services Description Language) is a specification that defines how to describe web services in common XML grammar. The WSDL file contains URL addresses to the SOAP Server location. For the TestTrack SDK, this is the address of the server that is hosting the SOAP API. The server address is configured during the installation process.

WSDL and stub code generation

Writing client applications to take advantage of SOAP functionality takes a surprisingly small amount of code. This is due to the use of WSDL stub code generation utility programs that come with most SOAP toolkits. The utility reads in the WSDL file that is installed on the web server and creates stub classes specific to that WSDL file. The classes are used by the client application to handle all the XML serialization/deserialization and network communication. This significantly reduces the amount of effort required by the developer.

Want to find out more? Read David Baird's Perl Usage of the TestTrack Pro SOAP Interface information on the CM Crossroads Configuration Management wiki.

SOAP CGI

The SOAP CGI accepts requests from SOAP clients and author appropriate responses. The encoded responses are returned to the requesting SOAP client.

Note: Middle initial support was added to several user type requests, such as getUser or deleteUser, in TestTrack 7.6. If you are using an older WSDL against TestTrack Pro 7.6 the requests will still work. However, you will need to make some changes for these functions after you re-generate stub files.

Finding input fields

To find the input fields for a SOAP call, you can look at the corresponding section of the WSDL file. For example, let’s look at the saveUser operation.

<operation name="saveUser">
<input message="tns:saveUserRequest"/>
<output message="tns:saveUserResponse"/>
</operation>

<message name="saveUserRequest">
<part name="cookie" type="xsd:long"/>
<part name="firstName" type="xsd:string"/>
<part name="lastName" type="xsd:string"/>
<part name="pUser" type="ttns:CUser"/>
</message>

<message name="saveUserResponse">
<part name="result" type="xsd:int"/>
</message>

The second line, <input message=”tns:saveUserRequest”/> means that we need to look at the saveUserRequest message to find the input fields. In this case, the input fields that need to be included in the function call are cookie, firstName, lastName, and pUser.

Error Codes

0: Unknown Error
1: Invalid Database
2: Missing Parameter
5: Not Allowed
6: Record Not Found
7: Edit Record Not Found
8: User Already Logged In
9: Server Not Found
10: Communication Error
11: Invalid Parameter
12: Database Error
13: Max Concurrent Users
16: General Error
17: Not Logged In
19: No License Found
21: License In Use
22: Record Locked
23: Data Validation Error
72: Max Soap Users
74: Multiple Records Found
75: Admin Lock Not Obtained
77: Invalid Table
86: Duplicate Name
108: Inactive User
127: Communication Error With License Server
135: Not Allowed License Server
140: No License Type Assigned
148: Password Change Required
237: Workflow Not Defined
239: Audit Logging Enabled

Useful links

TestTrack Wiki
SDK 2008.2 Messages and Types
Main Page


Issue Management Software | Source Code Control Software | Test Case Management