Seapine Labs
Personal tools

TestTrack SOAP SDK Best Practices

From Seapine Labs

Jump to: navigation, search

Contents

[edit] Purpose

The following are a collection of recommendations to help you maximize the performance, scalability and maintainability of your SOAP scripts.

These are based on our years of experience in developing against the SDK for Seapine customers and internal samples.

If you're not familiar with SOAP or the TestTrack SDK, or simply don't have the time to write your own scripts email Seapine Services and we can help.

[edit] Getting Started

Before you start programming, there are some things to think about.

What are you trying to accomplish?

While the SDK is very robust, it cannot do everything. The SDK is mainly for working with items, like defects, test cases, and test runs. It is not for configuration. For example, you cannot create a project, set project options, configure the workflow, etc. with the SDK. The most configuration you will be able to do with the SDK is add values to a pop-up menu.

Language of choice?

Since the SDK is SOAP-based, you have a lot of choices for the language. Choose wisely! You will be tempted to choose a language that you are comfortable with, but it may be one that requires more work. Let’s take Python, for example. You can write SOAP with Python, but it requires you to create the XML files to submit a request and then read the XML file to get the response. With something like Java, you only need a couple of lines to accomplish what would take you tens of lines. Sometimes, however, depending on the specific situation, you do not have a choice.

Web Server

The SOAP SDK is a web service, so that means you will need a web server. If you are successfully running the web client, then the same web server should be able to successfully run the SOAP SDK as well. Each web server and each version of the web server may require different settings. For example, in IIS 6 (and probably later) you have to add the MIME type to handle WSDL files, otherwise you will get a 404 error. The actual API is an executable CGI that by default resides in the scripts alias. Just like the TestTrack Web CGI. If you are able to reference the WSDL but cannot connect to the ttsoapcgi.exe, you may need to review the TestTrack installation guide, specifically the instructions for setting up the script alias in the web installation section.

Installing the SDK

There isn’t a separate installer for the TestTrack SOAP SDK; it is part of the server installer. One of the options in the installer is “TestTrack Server installation with Web and SOAP components”. But chances are you have already installed TestTrack, or you may want to run the SDK on a web server on a separate machine from the TestTrack Server, and you’d rather not reinstall everything. In that case, run the TestTrack installer and choose “Custom installation” instead. On the next window, you can select to only install the SOAP components. During the install you will be prompted to enter the TestTrack Server and port number information.

Getting Help

Hopefully, the posts here will be of great help to you.

Here are some of the resources available to you:

SDK Page on the Seapine labs:

http://labs.seapine.com/TestTrackSDK.php

More information on getting started:

http://labs.seapine.com/SDKStart.php

SDK documentation - complete documentation of all the requests and types.

http://labs.seapine.com/SDKDocs/2009/TTSOAP2009.html

Language-specific tutorials:

http://labs.seapine.com/wiki/index.php/Category:TestTrack_SDK_Tutorials

SDK examples:

http://labs.seapine.com/wiki/index.php/Category:SDK_Examples

Examples using TestTrack triggers:

http://labs.seapine.com/wiki/index.php/Category:Triggers_-_TestTrack

Share your knowledge!

Last thing I want to mention is that you can also post examples. The labs page is meant to be more of a community for Seapine users. You can register, create an account, and post any articles that you feel would help other users. Maybe there isn’t a tutorial for your language of choice or you want to add information to an existing article. Feel free to add to what is already there or create a new article

[edit] Logging in

When approaching a programming task using the TestTrack SDK, it is sometimes helpful to first think about how you perform the same task using the TestTrack client. The process is often very similar and can help you understand why things need to be done a certain way when using the SDK.

With logging in, think about that process when you log in using the TestTrack client. The process is as follows:

  • Open the TestTrack client.
  • Select the server to connect to.
  • Provide your username.
  • Provide your password.
  • Connect and get list of projects
  • Select the project and log in.

So this same process using pseudo code may look something like this: 

//Open the TestTrack client.
ttSoap = new ttsoapcgi
//Select the server to connect to.
ttSoap.URL = http://webserver/scripts/ttsoapcgi.exe

//Provide your username.
//Provide your password.
//Connect and get list of projects

ProjectArray = ttSoap.GetProjectList(username, password)
for each project in ProjectArray
     if project.name = "Sample Project"
          myProject = project
//Select the project and log in.
ttSoap.ProjectLogon(myProject, username, password)


It’s worth noting that this is not the only way to log in using the SDK. Instead of looping through all of the available projects for the user, you can build the project object and then pass it to the ProjectLogon() method. This would look something like this: 

ttSoap = new ttsoapcgi//Define soap object
ttSoap.URL = http://webserver/scripts/ttsoapcgi.exe
myProject = new Project
myDatabase = new Database
myDatabase.name = "Sample Project"
//Database options specify the functionality to have available for
//access once logged in.
myDatabaseOps = new DatabaseOptions[2]
myDatabaseOps[0] = "TestTrack Pro"
myDatabaseOps[1] = "TestTrack TCM"
myDatabase.DatabaseOptions = myDatabaseOps
myProject.Database = myDatabase
ttSoap.ProjectLogon(myProject, username, password)

So, which one is better? It really depends on the use case. Here are some things of note in regards to the first method:

The projects returned in the array are only those that the user has access to. The obvious benefit is that you do not attempt to log in to a project that the user does not have access to.

If the project is set up for TestTrack Pro and TestTrack TCM access, the project object will be returned with both data options. This is regardless of the license access the user has and could potentially cause a problem when you try to log in. An error may be returned if the user does not have a license to log in to either TestTrack Pro or TestTrack TCM. If you know that the user only has a license for one of them, you could reset the data options array to only contain one element. Something like this: 

ProjectArray = ttSoap.GetProjectList(username, password)
for each project in ProjectArray
     if project.name = "Sample Project"
          myProject = project

myDatabaseOps = new DatabaseOptions[1]
myDatabaseOps[0] = "TestTrack Pro"
myProject.Database.DatabaseOptions = myDatbaseOps

Here are some things of note in regards to the second method:

Make sure the user has access to the project object you are building. This method allows you to specify which data options you want to use (i.e., which license(s) to use). Whichever way you decide to use, make sure you only grab the licenses that you need. If the application you are writing is only going to work with defects, why grab a TestTrack TCM license?

[edit] Performance & Scalability

[edit] Filter Table List Queries By Column

To improve performance and reduce network traffic, never call getRecordListForTable without providing column filters.

The following code will retrieve every column of data for every defect in your project. Based on your configuration, this could easily return a couple hundred pieces of data for each record.

CRecordListSoap list = engine.getRecordListForTable(l, "Defect", "", null);

Typically you only need 5-10 pieces of data for each record, so specify those when making the call. 

// This is much better, you only need a few pieces of data
CTableColumn[] atc = new CTableColumn[2];
atc[0] = new CTableColumn();
atc[0].name = "Number";
atc[1] = new CTableColumn();
atc[1].name = "Status";

CRecordListSoap list = engine.getRecordListForTable(l, "Defect", "", atc);

[edit] Filter Table List Queries By TestTrack Filter

Where at all possible, provide a filter parameter to the getRecordListForTable call.

If you're writing a script to update a recently modified issue for example, create a private filter for your SOAP user to limit results to issues modified within the last hour or day.

If you're script operates on defects of Type == Feature Request create a filter to match that logic.

Never retrieve more data than you need!

[edit] Account for Timing when running from a Trigger

A very common use for the SDK is to trigger external actions via script using the TestTrack triggering mechanism.

Let's say you've created a trigger to fire every time a defect enters the Closed state. The trigger executes a script that uses the SDK to go back into TestTrack and update the record that caused the trigger to fire. Here is [|one such example].

In the scenario above, if you close 20 defects at once you'll get 20 executions of the trigger mechanism. There are several reasons that timing is critical here:

  • Each trigger execution will consume a license. For each of the trigger executions your script will run and consume a license. This can quickly eat up your license count and cause future trigger executions to fail.
  • TestTrack doesn't wait indefinitely to execute a trigger. TestTrack will wait 30 seconds for successful execution of the trigger. Any longer and it's assumed to have hung and is terminated. This comes into play where you've reached the server OS's concurrent process limit. The OS asks TestTrack to wait for a process to free up, but if it doesn't happen within that 30 second window it will be terminated by the TestTrack server.

[edit] Data Integrity

[edit] Setting Drop-down Field Values

  • Field values are case-sensitive. Check your case when passing the desired value.

For example, the code below will not work as expected if the Priority's drop-down value is P1 - Serious. The Priority field value will not be changed, because the specific value does not exist (notice the s vs. S).

defect.priority = "P1 - serious";
  • To "empty" a drop-down field, set it's value to an empty string.

For example, the following lines of code will not work as expected. 

// This will optimized out by the XML serializer and not pass to the TT Server.
((CDropdownField)defect.customFieldList[0]).value = null;

// This will look for a specific drop-down value of "<not set>."
((CDropdownField)defect.customFieldList[0]).value = "<not set>";

[edit] SOAP Must Respect User Edit Locks

Updating defects and other data through SOAP requires edit access to the object, no different than making the change from a TestTrack client.

If someone else is "editing" the object from a client, your SOAP script will not be able to make any changes to that object. Keep this in mind when running scripts in scenarios where the object might be locked.

A classic example of this is found in the TestTrack trigger functionality. Given that a defect edit (or Apply) is what triggered the SOAP script, it should not be a surprise when the defect is still locked when your script is attempting to make its updates.

[edit] Script Maintenance

[edit] Create an Exclusive TestTrack User for Background SOAP Applications

If you have a background SOAP application that runs on a regular basis, we recommend that you create an exclusive, dedicated user account for the SOAP application.

Creating a dedicated user provides the following advantages:

  • Simplify security management and protect real user accounts. Rather than using complex encryption to hide the user/pwd from developers of the script(s), let the TestTrack security model protect data access by limiting the permissions of the dedicated account. It's important that you prevent this user from logging in through any mechanism other than the SOAP SDK.
  • Isolate changes made by your automated scripts. When you review the TestTrack history table or audit log, you can easily distinguish between changes made by your SOAP script versus a TestTrack user.
  • Ensure uninterrupted access to TestTrack. With a dedicated SOAP account, you can be sure that nobody else is using that account when the background process is run.

[edit] Misc.

[edit] Understand Licensing

SOAP licensing works differently than and separate from client access licensing. Whereas client access is governed by the type of license, all SOAP licensing is done under a floating model.

Every license contains a client access license based on it's type (floating or named) plus a floating license for SOAP access.

For example, if you've purchased 25 named licenses and 10 floating licenses, from a SOAP perspective you have 35 floating licenses for concurrent access through the SDK.




Retrieved from "http://labs.seapine.com/wiki/index.php/TestTrack_SOAP_SDK_Best_Practices"

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