September 30, 2009

TestTrack SDK Helpful Hints – Creating a Defect from Scratch Part II

Helix ALM
In my last post we looked at how to set the fields when you create a defect from scratch using the TestTrack SDK. In this post we are going to take a look at setting the Reported By records, setting workflow events and setting the source control files.

Reported by Records

The Report by Record refers to the "Detail" tab on the defect window. This tab contains four sections:
  • Detail
  • Steps to reproduce
  • Computer config
  • File Attachments
Figure 1 below illustrates the Reported By section of a sample defect. [caption id="attachment_1068" align="aligncenter" width="400" caption="Figure 1 - Reported By Fields"]reportedby[/caption] In previous posts I have mentioned that, when it comes to the TestTrack SDK, it helps sometimes to think about how you would approach the same task using the client. Setting the Reported By record is no different. Some of you may be wondering why can't you simply do something like this:
ttDefect.foundby = "Jones, Casey"
This would make sense, it looks just like the other fields we set in the previous post. However, when you look at a defect in the client or at Figure 1 above, you notice that you can set multiple report by records. Figure 1 shows a defect with four Reported By records. This is a feature in TestTrack that allows you to track a single item through the workflow, but keep track of every report of the defect, request for a feature, etc. So simply setting a field would not work. What if you wanted to add multiple Report By records, or what if you are editing an existing defect and you want to add a new one? Reported By records are handled as arrays of CReportByRecord.  The CReportByRecord contains fields that make up the Reported By record you see in the client. The manner in which the report by record is set depends on the language. Using C#, you can do something like this:
ttDefect.reportbyrecord[0] = new CReportByRecord();
ttDefect.reportbyrecord[0].foundby = "Casey, Jones";
ttDefect.reportbyrecord[0].datefound = Convert.ToDateTime("12/08/2009");
ttDefect.reportbyrecord[0].comments = "The Description is all about details";
Using Java, however, I have found that I have to first create and set the CReportedByRecord array and its fields.
CReportedByRecord[] ttReportBy = new CReportedByRecord[1];
ttReportBy[0].setFoundby(Jones, Casey);
ttReportBy[0].setDatefound(datefound); <----Use the Calendar class to set date objects
ttReportBy[0].setComments("This defect was added using Java");

ttDefect.setReportedbylist(ttReportBy);

Workflow

A very common question that comes up is how to set the state of the defect via SOAP. Some folks expect that it should be done the same way standard fields are set, like this:
ttDefect.state = "Fixed";
However, this is not the case. Again, take a look at a defect in the client, and see how the state is set. States are set by performing a workflow event. If you open a defect in TestTrack and click the "Workflow" tab, you may see several events listed there. The same applies when adding a defect via SOAP, you have to build an event (or events) in order to set the status of the defect. It should be noted that if you are adding a defect from scratch, and you need to set it to a state that requires several events to get there, you will need to add each event. Again, think about how you would move the defect to the desired state if you were using the TestTrack client. Setting the workflow events for the defect is very much like setting the Reported By record. The defect object has an eventlist property, which is an array of the class CEvent. The CEvent class has fields which are the fields you would see in the event dialog. This example shows how to set a defect's status to "Fixed" using C#:
CEvent[] ttEvents = new CEvent[2];
ttEvents[0] = new CEvent();
ttEvents[0].name = "Fix";
ttEvents[0].resultingstate = "Fixed";
ttEvents[0].notes = "Event performed via SOAP";
ttEvents[0].assigntolist = userList; <--- This is a string array, to accomodate multiple assignments.
ttDefect.eventlist = ttEvents;
Custom Fields The CEvent class also has a fieldlist property, which is an array of the CField class. This is how custom fields for an event are handled. Setting the custom fields here is just like we did in the previous post.

SCC Files

This is something that most of you will not need, but I am including it for those of you that want to write a plug-in for your source code control system. The CDefect class has a property called pSCCFileList, which is an array of the CSCCFileRecord class. Following is an example of setting the source control file using C#:
CSCCFileRecord[] sccFiles = new CSCCFileRecord[1];
sccFiles[0] = new CSCCFileRecord();
sccFiles[0].mstrFileName = "WysiCorp::WysiCorp/WysiCRM/code/client/Main.cpp";
sccFiles[0].mstrFixedRevision = "5";
sccFiles[0].mdateFixedTimestamp = Convert.ToDateTime("08/12/2009 6:45:00 PM");
sccFiles[0].mdateFixedTimestampSpecified = true;
ttDefect.pSCCFileList = sccFiles;
It should be noted that the mstrFileName should be set in a way that makes sense in regards to the source control tool. In the example above, the format used is one that TestTrack uses for files stored in Surround SCM. The format is <branch name>::<full path to file>, but for other source control systems it may be different. If you are doing this for a tool where TestTrack has an out of the box integration, I recommend attaching a file from source control to a defect and noting how TestTrack sets the file name. Setting the file name properly will help you to access source control commands for that file from TestTrack (if the tool is supported).

Conclusion

While it took me two posts, I have covered most of what is needed to create a defect from scratch using the TestTrack SOAP API. There may be some deviations based on the language you use, but this provides you with an explanation of what is needed to set the various parts that make up a defect in TestTrack. While these posts covered creating defects, it should provide a general idea on how to handle other items that are tracked in TestTrack, like test cases or requirements.

More Reading