SDK Java Tutorial

From Seapine Labs

This article includes everything you ever wanted to know about writing SOAP-based TestTrack SDK applications in Java! Don't like Java? Use the C#, VB or Python tutorials. Be sure to check out the TestTrack SDK Help pages for more information.

Want Seapine to write your SOAP app for you? Email us!

Contents 1 Getting Started 2 Create a Connection 3 Query Objects 3.1 getObject 4 Create Object 5 Update Object 6 Update Custom Field 7 Update Status 8 Add File Attachment 9 Troubleshooting

[edit] Getting Started

You must install the TestTrack SDK as part of your server installation. If you haven't done this, you'll need to run the TestTrack installer for the version you have installed. Once installed, there are two files of interest.

• http://yourserver/cgi-bin/ttsoapcgi.exe - CGI Executable that all TestTrack SDK commands go through. It's not important to understand CGI, just know where this file was installed.

• http://server/ttsoapcgi.wsdl - The WSDL file that defines the language you use when talking to the CGI executable. Anyone that uses the TestTrack SDK uses this wsdl, there is no need to generate a specific wsdl for your installation. Everything is genericized so that, no matter how you customize TestTrack, this one wsdl file will handle it.

Once you've installed the TestTrack SDK, generate the stub code from the wsdl.

Finally, import the namespace and you're ready to roll!

import com.seapine.testtrackpro.ttpsoap.*;

[edit] Create a Connection

The TestTrack SDK requires authentication before you can retrieve and save data.

// Set the URL, based on your SDK installation.
java.net.URL url = new URL("http://127.0.0.1:80/cgi-bin/ttsoapcgi.exe");

// Create the connection.
TtsoapcgiStub cgiengine = new TtsoapcgiStub(url, new TtsoapcgiLocator());

// Fetch a list of projects you have access to.
CProject[] aproject = cgiengine.getProjectList( "administrator", "");

// Or, build your own.
CProject project = new CProject();
CDatabase db = new CDatabase();
db.setName("MyProject");
project.setDatabase(db);
CProjectDataOption[] apdo = new CProjectDataOption[2];
apdo[0] = new CProjectDataOption();
apdo[0].setName("TestTrack Pro"); // add TTP functionality.
apdo[1] = new CProjectDataOption();
apdo[1].setName("TestTrack TCM"); // add TCM functionality.
project.setOptions(apdo);

// Login.
long lSession = cgiengine.ProjectLogon( project, "administrator", "");

   ...do some stuff...

// When you're finished, log off.
cgiengine.DatbaseLogoff(lSession);

Things to Know:

• You cannot logon via the TestTrack SDK if you are already logged in via one of the TestTrack clients. It's best to use a dedicated account for your SDK scripting, this ensures you'll always be able to login.
• If you do not explicitly call DatabaseLogoff, your user will remain logged in until the TestTrack SDK times out. This could present a problem if you try to re-run the script inside that timeframe. It's important to use try/catch exception handling to ensure that an exception in your program doesn't skip logging you off.
• The CProjectDataOption array governs what licenses you use and functionality you have access to. For example, you can't use a TestTrack TCM license if you don't specify one in the CProjectDataOption array.

[edit] Query Objects

There are two ways to retrieve data through the TestTrack SDK. You can explicitly call a getObject method or you can call the getRecordListForTable method.

[edit] getObject

Calling the get method on an object is useful when you know exactly which object you need. For performance reasons, this is not recommended when you want to extract data from multiple objects of the same type.

When calling getRecordListForTable you must specify both the object type you want to query and an array of fields you want to retrieve. Optionally, you can also specify a filter that you've pre-configured in TestTrack.

All of this information can be hard-coded as shown in the previous example, or dynamically passed as shown below.

Things to Know:

• TableColumn elements use the field's Short Label value.
• Pretty much anything you can view in a list view column within the GUI clients, you can retrieve through getRecordListForTable.

[edit] Create Object

Adding an object is simply a matter of creating a new instance and calling the addObject method.

For example, to create a defect:

Things to Know:

• When setting drop-down list values, you must match exactly (case-sensitive) with an existing value in the drop-down list.

[edit] Update Object

Before updating an object, you must first lock it for editing by calling editObject.

Things to Know:

• You cannot edit an object that is being edited by another user. For example, if someone else had defect #11 open for edit in their client, the example above would fail.
• If you successfully lock a defect for edit, that lock remains until you save it, cancel the save or logout. You should use try/catch exception handling to ensure that you release the lock as soon as possible.

[edit] Update Custom Field

Things to Know:

• The customfieldlist array holds the base-class CField objects, which must be casted as appropriate before you can set a value. In the example, 'My Custom' is a text field so we casted to CStringField. See the TestTrack SDK Types page for a full list of supported field types.

[edit] Update Status

TestTrack calculates state based on event history. This means you can't simply set a value to change state. Instead, you have to apply the necessary events to move the object into the desired state.

[edit] Add File Attachment

[edit] Troubleshooting

With Java, using the TestTrack SDK can be really simple or really frustrating. Following are some tools that can help you deubg issues.

• MS SOAP Toolkit - This is a small app from Microsoft that helps you trace SOAP requests. Start a formatted trace, point your SOAP client toward the tools listening port, then have the tool redirect to the real webv server port. With that configured, you can intercept the response/request loop and see exactly what is being communicated to the TestTrack Server.

• soap UI - A free tool that lets you send raw SOAP envelopes. Seapine sometimes use this internally to debug issues, since you can control the data being being sent. Going through C#, you're depending on their parser to translate objects into XML and pass those to the server.

• Known Axis 1.4 Issue - There is a known parsing issue in Axis 1.4, that you'll probably need to patch.