API Guide. SilkCentral Test Manager

Transcription

1 API Guide SilkCentral Test Manager 2008

2 Borland Software Corporation 8303 N. Mopac Expressway, Suite A-300 Austin, TX Borland Software Corporation may have patents and/or pending patent applications covering subject matter in this document. Please refer to the product CD or the About dialog box for the list of applicable patents. The furnishing of this document does not give you any license to these patents. Copyright Borland Software Corporation and/or its subsidiaries. All Borland brand and product names are trademarks or registered trademarks of Borland Software Corporation in the United States and other countries. All other marks are the property of their respective owners. March 2008 PDF

3 Contents Introduction 1 Overview Chapter 1 Creating Plug-Ins 3 Overview Plug-In Species Compilation Deployment Distribution Chapter 2 Source Control Integration 5 Overview Interfaces & Classes Conventions Configuring Source Control Plug-ins Chapter 3 Issue Tracking Integration 15 Overview Web Service Interface Java API Interface Integrating Third-Party Issue Tracking Chapter 4 Requirements Management Integration 33 Overview Deploying the API Requirements Plug-In API Interfaces for External RMS Chapter 5 Third-Party Test Type Integration 41 Overview Plug-In Implementation Structure of the API Sample Code Configuration XML File Deployment Chapter 6 SilkCentral Web Service Interface 51 SilkCentral Web Services Web Services Quick Start Administration Web Services Test Manager Web Services Issue Manager Web Services Index 91 SilkCentral Test Manager API Guide iii

4 iv SilkCentral Test Manager API Guide

5 Introduction About this manual This manual provides the information you need to create and deploy plug-ins to integrate third-party tools into Borland SilkCentral Test Manager (Test Manager). It contains Web service specifications, API descriptions, and explains how to integrate plug-ins within Test Manager. This chapter contains the following sections: Section Overview 1 Page Overview An API concept has been implemented for SilkCentral Test Manager for the integration of third-party applications. With SilkCentral s API s, you can now integrate your existing source-control, issue-tracking, and requirementsmanagement tools by configuring Test Manager plug-ins. A number of sample plug-ins ship with Test Manager For a complete description of the SilkCentral Test Manager Java API, please refer to the Test Manager API Specification, available in Test Manager s GUI on Help/Documentation/Test Manager API Specification. SilkCentral Test Manager API Guide 1

6 INTRODUCTION Overview 2 SilkCentral Test Manager API Guide

7 1 Creating 1Chapter Plug-Ins Introduction What you will learn This chapter explains how to create plug-ins for SilkCentral Test Manager. This chapter contains the following sections: Section Page Overview 3 Plug-In Species 3 Compilation 4 Deployment 4 Distribution 4 Overview This chapter describes how to create plug-ins for SilkCentral Test Manager. Only the tasks common for all plug-in types (aka species) are discussed. For information about a specific plug-in, see the specific documentation: Source Control Integration Issue Tracking Integration Requirements Management Integration Third-Party Test Type Integration Plug-In Species SilkCentral (which includes Test Manager) provides several plug-in API s (e.g., for source control Integration). Such a specific API is called a species. SilkCentral Test Manager API Guide 3

8 1 CREATING PLUG-INS Compilation Compilation For developing and compiling plug-ins, use Java version 1.5.0_07. This is important for compatibility reasons with SilkCentral Test Manager s Java runtime environment. Deployment When you create your plug-in classes (and implement a species API) you need to create a plug-in package (a jar or zip). If your plug-in has no further dependencies (or depends on libraries, that are already part of SilkCentral), just create a jar file that contains your classes. If your plug-in depends on additional libraries, put them and your self-created jar file into a zip archive. Place the created file into the plug-ins directory located at <application server installation directory>\plugins\. Note You need to restart the application server and the front-end server for the newly deployed plug-in to become available in Test Manager (see the SilkCentral Administration Module Online Help for information about restarting servers). Distribution As the plug-in species are known by SilkCentral, it s also known which servers (execution, application, front-end) require which species. Each plug-in can be installed on the application server SilkCentral automatically distributes the correct plug-ins to each server. 4 SilkCentral Test Manager API Guide

9 2 Source 2Chapter Control Integration Introduction What you will learn This chapter explains how to configure custom source control plug-ins for Test Manager. This chapter contains the following sections: Section Page Overview 5 Interfaces & Classes 6 Conventions 7 Configuring Source Control Plug-ins 8 Overview Source Control profiles enable Test Manager to integrate with external source control systems. The source control systems for which default plug-ins ship with Test Manager are: Borland StarTeam (StarTeam) - see the SilkCentral Administration Module Online Help Serena Version Manager (PVCS ) - see the SilkCentral Administration Module Online Help Concurrent Version System (CVS) - see CVS Plug-In Microsoft Visual SourceSafe (MSVSS) - see the SilkCentral Administration Module Online Help Universal Naming Convention (UNC) (file-system access) - see the SilkCentral Administration Module Online Help Subversion - see Subversion Plug-In SilkCentral Test Manager API Guide 5

10 2 SOURCE CONTROL INTEGRATION Interfaces & Classes Plug-ins for other source control systems are available from Borland s download area, in the SilkCentral Test Manager menu ( downloads/download_silk.html): With Test Manager s API, custom source control plug-ins can be configured, allowing you to define where Test Manager s execution servers should retrieve program sources for test execution. Please refer to the SilkCentral Test Manager Online Help for information about defining source control information for test containers/test definitions. Note See the SilkCentral Administration Module Online Help for details on configuring the default plug-ins that ship with Test Manager. Interfaces & Classes SourceControlProfile AbstractSourceContro lprofile VersionControlProfile AbstractVersionContr olprofile SourceControlProfileD ata SourceControlExcepti on SourceControlProfileF actory Note Refer to the JavaDoc (Help/Documentation/Test Manager API Specification) for full details regarding available Java classes and methods. SilkCentral distinguishes between two types of source control systems: SourceControlProfile and VersionControlProfile. The difference is that SourceControlProfiles are non-versioned, VersionControlProfiles are versioned. This specifies most methods, such as listing the source control system s content or getting the files from the source control system to a local directory. This implements convenient methods by using other methods, the SourceControlProfile specifies. Overriding methods here is mostly because of performance reasons. This adds features like check-in/check-out and label support to the SourceControlProfile. Implements methods that only use other VersionControlProfile methods and that are common for most implementations. This provides data that the user enters, which are needed to access the source control system. The most common data are hostname, port, username, and password. As there can always be a problem, each method that is intended to access the source control system may throw a SourceControlException (checked). This exception contains error code, so the caller receives an indication as to what caused the problem. Provides a static method to get an instance of a SourceControlProfile. 6 SilkCentral Test Manager API Guide

11 2 SOURCE CONTROL INTEGRATION Conventions SourceCodeControlInf o Contains data that is required for accessing the Source control system. This is used for other applications that integrate with SilkCentral and require access to the source control system. This class was designed to contain the information required for connecting via the Microsoft SCC API. Conventions Each Implementation must provide a default constructor and, optionally, a constructor with a SourceControlProfileData as a parameter. If this constructor is not provided, a bean setter for sourcecontrolprofiledata must be provided. As each interface method specifies the SourceControlException that is to be thrown, it s not allowed to throw a RuntimeException in any method used by the interface. SilkCentral Test Manager API Guide 7

12 2 SOURCE CONTROL INTEGRATION Configuring Source Control Plug-ins Configuring Source Control Plug-ins Before you can configure a source control plug-in within Test Manager, you need to deploy the plug-in. See Creating Plug-Ins for detailed information. Subversion Plug-In Adding Subversion profiles Subversion manages versions by using transaction numbers. With each commit, the transaction number is incremented. What other source control systems call labels are called tags in Subversion. These tags are encoded in the Subversion URL. Example: Additionally to the Subversion URL you may have a tag MyHost/svn/MyApp/tags/build1012. Test Manager supports Subversion tags as follows: If a Subversion URL contains the trunk directory, you can define e.g. a label tags/build1012. This label will then replace trunk in the Subversion URL. Note If the Subversion URL doesn t contain trunk and you define a label, Test Manager throws an error. Procedure To create a Subversion source control profile: 1 Select the Source Control tab from Administration/Configuration in the menu tree. The Source Control page appears, listing all of the source control profiles that have been created for the system. 2 Click the New Profile button to open the New Source Control Profile dialog. 3 Enter a name (e.g., Subversion) for the name for the new profile. This is the name that is displayed in the Test Manager GUI. 4 Select Subversion from the Source control system drop-down list. 5 Enter the URL of the Subversion repository you wish to access. If you do not know the URL of the repository, please consult your Subversion administrator. 6 Enter a valid Subversion user name and password. These credentials will be used to access your Subversion repository. 7 Enter the working folder to which Test Manager s execution server should copy the source files. The working folder must be a local path (e.g., C:\TempSources\). 8 SilkCentral Test Manager API Guide

13 2 SOURCE CONTROL INTEGRATION Configuring Source Control Plug-ins 8 Enter the project path you want this profile to use (optional). This is the path inside the repository that should be used as the root path. Alternately, you can click the Browse button next to the Project path field to connect to the Subversion system with the credentials you ve entered. If the connection is successful, the Select Project Path dialog will appear. Select the desired project path in the tree view and click OK. Leaving this field empty sets the project path to the root directory. 9 Click OK once you have finished entering the source control profile information; or click Cancel to abort the operation. If you click OK, Test Manager will attempt a trial connection to Subversion using the information you have provided. Note If an error occurs, please review the repository path and the Subversion login credentials you ve provided. Or consult your Subversion administrator. 10 If the trial connection to Subversion is successful, you will be returned to the Source Control page, where the new profile will be listed. Editing Subversion profiles Procedure To modify a Subversion source control profile: 1 Select the Source Control tab from Administration/Configuration in the menu tree. The Source Control page appears, listing all of the source control profiles that have been created for the system. 2 Select the name of the Subversion source control profile. 3 The Edit Source Control Profile dialog appears. From here you can: - Edit the name of the profile. This is the name that is displayed in the Test Manager GUI. - Edit the URL of the Subversion repository you wish to access. If you do not know the URL of the repository, please consult your Subversion administrator. SilkCentral Test Manager API Guide 9

14 2 SOURCE CONTROL INTEGRATION Configuring Source Control Plug-ins Deleting Subversion profiles - Edit the Subversion user name and password. These credentials are used to access your Subversion repository. - Edit the working folder to which Test Manager s execution server should copy the source files. The working folder must be a local path (e.g., C:\TempSources\.) - Edit the project path you want this profile to use. This is the path inside the repository that should be used as the root path. Alternately, you can click the Browse button next to the Project path field to connect to the Subversion system with the credentials you ve entered. If the connection is successful, the Select Project Path dialog will appear. Select the desired project path in the tree view and click OK. 4 Click OK once you have finished editing source control profile information; or click Cancel to abort the operation. If you click OK, Test Manager will attempt a trial connection to Subversion using the information you have provided. Note If an error occurs, please review the credentials and the repository path you have supplied. Or consult your Subversion administrator. 5 If the trial connection to Subversion is successful, you will be returned to the Source Control page. Procedure To remove a Subversion source control profile: 1 Select the Source Control tab from Administration/Configuration in the menu tree. The Source Control page appears, listing all of the source control profiles that have been created for the system. 2 Select the Delete icon of the Subversion source control profile. 3 A confirmation dialog appears, asking you to confirm the deletion. Click Yes to remove the selected profile; or click No to abort the deletion. 4 If you click Yes, you will be returned to the Source Control page, where the deleted profile will no longer be listed. CVS Plug-In Adding CVS profiles Procedure To create a CVS source control profile: 1 Select the Source Control tab from Administration/Configuration in the menu tree. The Source Control page appears, listing all of the source control profiles that have been created for the system. 10 SilkCentral Test Manager API Guide

15 2 SOURCE CONTROL INTEGRATION Configuring Source Control Plug-ins 2 Click the New Profile button to open the New Source Control Profile dialog. 3 Enter a name (e.g., CVS) for the new profile. This is the name that will be displayed in the Test Manager GUI. 4 Select CVS from the Source control system drop-down list. 5 In the Host field, specify the CVS server (name or IP address). 6 In the Port field, specify the port that is to be connected to. 7 In the Method field, specify the connection method. Currently, only the ext connection method has been tested. This makes the Port setting optional. 8 Enter the URL of the CVS Repository you wish to access (e.g., /var/lib/ cvs). If you do not know the URL of the repository, please consult your CVS administrator. 9 Enter a valid CVS User name and Password. These credentials will be used to access your CVS repository. Note that these settings are optional when using the ext connection method. 10 Specify the CVS Module that is to be used. 11 Enter the working folder to which Test Manager s execution server should copy the source files. The working folder must be a local path (e.g., C:\TempSources\). 12 Enter the project path you want this profile to use (optional). Alternately, you can click the Browse button next to the Project path field to connect to the CVS system with the credentials you ve entered. If the connection is successful, the Select Project Path dialog will appear. Select the desired project path in the tree view and click OK. Leaving this field empty sets the project path to the root directory. 13 Click OK once you have finished entering the source control profile information; or click Cancel to abort the operation. If you click OK, Test Manager will attempt a trial connection to CVS using the information you have provided. Note If an error occurs, please review the repository path and the CVS login credentials you have supplied. Or consult your CVS administrator. SilkCentral Test Manager API Guide 11

16 2 SOURCE CONTROL INTEGRATION Configuring Source Control Plug-ins 14 If the trial connection to CVS is successful, you will be returned to the Source Control page, where the new profile will be listed. Editing CVS profiles Procedure To modify a CVS source control profile: 1 Select the Source Control tab from Administration/Configuration in the menu tree. The Source Control page appears, listing all of the source control profiles that have been created for the system. 2 Select the name of the CVS source control profile. 3 The Edit Source Control Profile dialog appears. From here you can: - Edit the name of the profile. This is the name that is displayed in the Test Manager GUI. - Edit the CVS server (name or IP address) in the Host field. - Edit the port that is to be connected to in the Port field. - Edit the connection method in the Method field. Currently, only the ext connection method has been tested. This makes the Port setting optional. - Edit the URL of the CVS Repository you wish to access. - Edit your CVS User name and Password. Note that these settings are optional when using the ext connection method. - Edit the CVS Module that is to be used. - Edit the working folder to which Test Manager s execution server should copy the source files. The working folder must be a local path (e.g., C:\TempSources\.) 12 SilkCentral Test Manager API Guide

17 2 SOURCE CONTROL INTEGRATION Configuring Source Control Plug-ins Deleting CVS profiles - Edit the project path that you want this profile to use. Alternately, you can click the Browse button next to the Project path field to connect to the CVS system with the credentials you ve entered. If the connection is successful, the Select Project Path dialog will appear. Select the desired project path in the tree view and click OK. 4 Click OK once you have finished editing source control profile information; or click Cancel to abort the operation. If you click OK, Test Manager will attempt a trial connection to CVS using the information you have provided. Note If an error occurs, please review the credentials and repository path you have supplied. Or consult your CVS administrator. 5 If the trial connection to CVS is successful, you will be returned to the Source Control page. Procedure To remove a CVS source control profile: 1 Select the Source Control tab from Administration/Configuration in the menu tree. The Source Control page appears, listing all of the source control profiles that have been created for the system. 2 Select the Delete icon of the CVS source control profile. 3 A confirmation dialog appears, asking you to confirm the deletion. Click Yes to remove the selected profile; or click No to abort the deletion. If you click Yes, you will be returned to the Source Control page, where the deleted profile will no longer be listed. SilkCentral Test Manager API Guide 13

18 2 SOURCE CONTROL INTEGRATION Configuring Source Control Plug-ins 14 SilkCentral Test Manager API Guide

19 3 Issue 3Chapter Tracking Integration Introduction What you will learn This chapter explains how to integrate third-party issue-tracking systems into SilkCentral Test Manager. This chapter contains the following sections: Section Page Overview 15 Web Service Interface 16 Java API Interface 29 Integrating Third-Party Issue Tracking 30 Overview The interfaces discussed in this chapter are required for creating plug-ins for SilkCentral Test Manager that enable the integration of a third-party (external) Issue Tracking System (ITS) into SilkCentral Test Manager. Two types of integration are offered: Web Service Interface Java API Interface The issue tracking software packages that are currently supported by Test Manager out of the box are: Borland SilkCentral Issue Manager (Issue Manager) - see the SilkCentral Administration Module Online Help Borland StarTeam (StarTeam) - see the SilkCentral Administration Module Online Help SilkCentral Test Manager API Guide 15

20 3 ISSUE TRACKING INTEGRATION Web Service Interface Rational ClearQuest - see the SilkCentral Administration Module Online Help Issue Tracking Web Service - see Web Service Interface Bugzilla - see Bugzilla Web Service Interface Interface description The interface the WSDL is based on is pasted below. This interface also contains the documentation for the methods and types. The following Java code explains the interface, but does not imply that the web service has to be written in Java. Important: The web service needs to provide the same SOAP API as described in the WSDL specification, regardless of the programming language it is written in. Note The Web service interface currently only allows the creation of new issues. If you want to assign existing issues to test definitions, you should use the Java API (see Java API Interface ). /** * This interface is used to generate the WSDL of the Web Service a customer can implement * to integrate any, in the first place not supported, Issue Tracking System. * * The WSDL document will be generated out of this interface using Apache Axis Java2WSDL tool * */ public interface IssueTrackingSOAPInterface { /** * This method returns an ID that is used for all actions during a session to identify the user. The returned value will be passed to the other methods as parameter. user password a sessionid which is used for all other actions to determine the user */ public long logonuser(string user, String password) throws IssueTrackingServiceException; /** * Will be called when starting to enter a new issue 16 SilkCentral Test Manager API Guide

21 3 ISSUE TRACKING INTEGRATION Web Service Interface sessionid a (temporary) id for the new issue */ public String newissue(long sessionid) throws IssueTrackingServiceException; /** * Returns all IssueField objects of the (temporary) issue with the provided issueid. * The IssueField objects contain the current values of the fields. sessionid issueid */ public IssueField[] getfields(long sessionid, String issueid) throws IssueTrackingServiceException; /** * This method is used to synchronize with the current states of the external tracking tool. sessionid issueids array containing the ids of the requested issues state info of requested issues [0] id, [1] state, [2] longvalue (changedat) */ public String[][] getstates(long sessionid, String[] issueids) throws IssueTrackingServiceException; /** *This method is used to get all possible states an issue may have to do a mapping between internal and external states. sessionid all states an issue may have in this profile */ public String[] getpossiblestates(long sessionid) throws IssueTrackingServiceException; /** * This method is called if a field with type SELECT_ FIELD has dependent fields and was changed. * e.g.: The field "Product" has a depending field "Release". If "Product" changes, the IssueField * for "Release" has to be returned containing the proper options for the selected product. SilkCentral Test Manager API Guide 17

22 3 ISSUE TRACKING INTEGRATION Web Service Interface sessionid issueid (temporary) id of the issue field that has changed all fields of the issue that have changed (eg. other options) due to the change of the submitted field */ public IssueField[] fieldchanged(long sessionid, String issueid, IssueField field) throws IssueTrackingServiceException; /** * this method stores the issue with the values which are submitted in the fields array. * sessionid id the (temporary) id of the issue fields array of fields containing the values to store new id of the issue after storing into the tracking system */ public String store(long sessionid, String id, IssueField[] fields) throws IssueTrackingServiceException; /** * This method returns the Http link to the issue with the submitted id if available. sessionid id http link to the issue, null if either no link is available or the id is invalid */ public String getlink(long sessionid, String id) throws IssueTrackingServiceException; /** * Not used in this version. May be used in a future version to speed up the update process. product only infos of issues linked to this product will be returned changedsince timemillis, only infos of issues changed after will be returned. * Can be ignored by implementing services if not supported, * but then all issues of this product will be returned (may slow down updates). 18 SilkCentral Test Manager API Guide

23 3 ISSUE TRACKING INTEGRATION Web Service Interface array with actual infos about the changed issues */ public IssueInfo[] getchanges(string product, long changedsince) throws IssueTrackingServiceException; } The ComplexType IssueField corresponds to the following definition. /** * An IssueField represents one input field in the issue tracking dialog. name A unique name for the field (ID) type The GUI type of the field. SelectBox = 1, Checkbox = 2, TextField = 3, TextArea = 4 (handled as TextField in this version) value The current value of the field. options The options for a field of type SelectBox (type = 1) label The label for the field shown in the dialog required Defines whether the user has to enter a value for this field or if it can be left blank length The maximum number of characters that can be entered in a TextField or TextArea dependent Array of names of other fields whose content depend on the selection of this field. Used for SelectBoxes (type = 1) */ The ComplexType IssueInfo is not used in this version as the method getchanges is not yet called. WSDL specification A WSDL file (contents pasted below) describes the SOAP-API that must be implemented to enable integration. You need to host a Web Service implementing this WSDL. Here is the specification of the web service interface. This file was generated using the Apache tool Java2WSDL. <?xml version="1.0" encoding="utf-8"?> <wsdl:definitions targetnamespace=" issuetracking" xmlns=" xmlns:apachesoap=" xmlns:impl=" xmlns:intf=" xmlns:soapenc=" xmlns:wsdl=" xmlns:wsdlsoap=" xmlns:xsd=" SilkCentral Test Manager API Guide 19

24 3 ISSUE TRACKING INTEGRATION Web Service Interface <wsdl:types> <schema targetnamespace=" issuetracking" xmlns=" <import namespace=" encoding/"/> <complextype name="issuefield"> <sequence> <element name="name" nillable="true" type="xsd:string"/ > <element name="type" type="xsd:int"/> <element name="value" nillable="true" type="xsd:string"/> <element maxoccurs="unbounded" name="options" nillable="true" type="xsd:string"/> <element name="label" nillable="true" type="xsd:string"/> <element name="isrequired" type="xsd:boolean"/> <element name="maxlength" type="xsd:int"/> <element maxoccurs="unbounded" name="dependent" nillable="true" type="xsd:string"/> </sequence> </complextype> <complextype name="arrayofissuefield"> <complexcontent> <restriction base="soapenc:array"> <attribute ref="soapenc:arraytype" wsdl:arraytype="impl:issuefield[]"/> </restriction> </complexcontent> </complextype> <complextype name="issuetrackingserviceexception"> <sequence/> </complextype> <complextype name="arrayof_xsd_string"> <complexcontent> <restriction base="soapenc:array"> <attribute ref="soapenc:arraytype" wsdl:arraytype="xsd:string[]"/> </restriction> </complexcontent> </complextype> <complextype name="arrayofarrayof_xsd_string"> <complexcontent> <restriction base="soapenc:array"> <attribute ref="soapenc:arraytype" wsdl:arraytype="xsd:string[][]"/> </restriction> </complexcontent> </complextype> 20 SilkCentral Test Manager API Guide

25 3 ISSUE TRACKING INTEGRATION Web Service Interface <complextype name="issueinfo"> <sequence> <element name="id" nillable="true" type="xsd:string"/> <element name="status" nillable="true" type="xsd:string"/> <element name="synopsis" nillable="true" type="xsd:string"/> <element name="product" nillable="true" type="xsd:string"/> <element name="component" nillable="true" type="xsd:string"/> <element name="platform" nillable="true" type="xsd:string"/> <element name="url" nillable="true" type="xsd:string"/> <element name="changedon" type="xsd:long"/> <element name="changedby" nillable="true" type="xsd:string"/> </sequence> </complextype> <complextype name="arrayofissueinfo"> <complexcontent> <restriction base="soapenc:array"> <attribute ref="soapenc:arraytype" wsdl:arraytype="impl:issueinfo[]"/> </restriction> </complexcontent> </complextype> </schema> </wsdl:types> <wsdl:message name="getchangesrequest"> <wsdl:part name="product" type="xsd:string"/> <wsdl:part name="changedsince" type="xsd:long"/> </wsdl:message> <wsdl:message name="fieldchangedresponse"> <wsdl:part name="fieldchangedreturn" type="impl:arrayofissuefield"/> </wsdl:message> <wsdl:message name="getfieldsresponse"> <wsdl:part name="getfieldsreturn" type="impl:arrayofissuefield"/> </wsdl:message> <wsdl:message name="getpossiblestatesresponse"> <wsdl:part name="getpossiblestatesreturn" type="impl:arrayof_xsd_string"/> </wsdl:message> <wsdl:message name="logonuserresponse"> <wsdl:part name="logonuserreturn" type="xsd:long"/> </wsdl:message> <wsdl:message name="getstatesresponse"> SilkCentral Test Manager API Guide 21

26 3 ISSUE TRACKING INTEGRATION Web Service Interface <wsdl:part name="getstatesreturn" type="impl:arrayofarrayof_xsd_string"/> </wsdl:message> <wsdl:message name="getpossiblestatesrequest"> <wsdl:part name="sessionid" type="xsd:long"/> </wsdl:message> <wsdl:message name="newissueresponse"> <wsdl:part name="newissuereturn" type="xsd:string"/> </wsdl:message> <wsdl:message name="getchangesresponse"> <wsdl:part name="getchangesreturn" type="impl:arrayofissueinfo"/> </wsdl:message> <wsdl:message name="logonuserrequest"> <wsdl:part name="user" type="xsd:string"/> <wsdl:part name="password" type="xsd:string"/> </wsdl:message> <wsdl:message name="getfieldsrequest"> <wsdl:part name="sessionid" type="xsd:long"/> <wsdl:part name="issueid" type="xsd:string"/> </wsdl:message> <wsdl:message name="storeresponse"> <wsdl:part name="storereturn" type="xsd:string"/> </wsdl:message> <wsdl:message name="getstatesrequest"> <wsdl:part name="sessionid" type="xsd:long"/> <wsdl:part name="issueids" type="impl:arrayof_xsd_ string"/> </wsdl:message> <wsdl:message name="getlinkrequest"> <wsdl:part name="sessionid" type="xsd:long"/> <wsdl:part name="id" type="xsd:string"/> </wsdl:message> <wsdl:message name="newissuerequest"> <wsdl:part name="sessionid" type="xsd:long"/> </wsdl:message> <wsdl:message name="issuetrackingserviceexception"> <wsdl:part name="fault" type="impl:issuetrackingserviceexception"/> </wsdl:message> <wsdl:message name="fieldchangedrequest"> <wsdl:part name="sessionid" type="xsd:long"/> <wsdl:part name="issueid" type="xsd:string"/> <wsdl:part name="field" type="impl:issuefield"/> </wsdl:message> <wsdl:message name="getlinkresponse"> <wsdl:part name="getlinkreturn" type="xsd:string"/> </wsdl:message> <wsdl:message name="storerequest"> 22 SilkCentral Test Manager API Guide

27 3 ISSUE TRACKING INTEGRATION Web Service Interface <wsdl:part name="sessionid" type="xsd:long"/> <wsdl:part name="id" type="xsd:string"/> <wsdl:part name="fields" type="impl:arrayofissuefield"/> </wsdl:message> <wsdl:porttype name="issuetrackingporttype"> <wsdl:operation name="getfields" parameterorder="sessionid issueid"> <wsdl:input message="impl:getfieldsrequest" name="getfieldsrequest"/> <wsdl:output message="impl:getfieldsresponse" name="getfieldsresponse"/> <wsdl:fault message="impl:issuetrackingserviceexception" name="issuetrackingserviceexception"/> </wsdl:operation> <wsdl:operation name="store" parameterorder="sessionid id fields"> <wsdl:input message="impl:storerequest" name="storerequest"/> <wsdl:output message="impl:storeresponse" name="storeresponse"/> <wsdl:fault message="impl:issuetrackingserviceexception" name="issuetrackingserviceexception"/> </wsdl:operation> <wsdl:operation name="logonuser" parameterorder="user password"> <wsdl:input message="impl:logonuserrequest" name="logonuserrequest"/> <wsdl:output message="impl:logonuserresponse" name="logonuserresponse"/> <wsdl:fault message="impl:issuetrackingserviceexception" name="issuetrackingserviceexception"/> </wsdl:operation> <wsdl:operation name="newissue" parameterorder="sessionid"> <wsdl:input message="impl:newissuerequest" name="newissuerequest"/> <wsdl:output message="impl:newissueresponse" name="newissueresponse"/> <wsdl:fault message="impl:issuetrackingserviceexception" name="issuetrackingserviceexception"/> </wsdl:operation> <wsdl:operation name="getstates" parameterorder="sessionid issueids"> SilkCentral Test Manager API Guide 23

28 3 ISSUE TRACKING INTEGRATION Web Service Interface <wsdl:input message="impl:getstatesrequest" name="getstatesrequest"/> <wsdl:output message="impl:getstatesresponse" name="getstatesresponse"/> <wsdl:fault message="impl:issuetrackingserviceexception" name="issuetrackingserviceexception"/> </wsdl:operation> <wsdl:operation name="getpossiblestates" parameterorder="sessionid"> <wsdl:input message="impl:getpossiblestatesrequest" name="getpossiblestatesrequest"/> <wsdl:output message="impl:getpossiblestatesresponse" name="getpossiblestatesresponse"/> <wsdl:fault message="impl:issuetrackingserviceexception" name="issuetrackingserviceexception"/> </wsdl:operation> <wsdl:operation name="fieldchanged" parameterorder="sessionid issueid field"> <wsdl:input message="impl:fieldchangedrequest" name="fieldchangedrequest"/> <wsdl:output message="impl:fieldchangedresponse" name="fieldchangedresponse"/> <wsdl:fault message="impl:issuetrackingserviceexception" name="issuetrackingserviceexception"/> </wsdl:operation> <wsdl:operation name="getlink" parameterorder="sessionid id"> <wsdl:input message="impl:getlinkrequest" name="getlinkrequest"/> <wsdl:output message="impl:getlinkresponse" name="getlinkresponse"/> <wsdl:fault message="impl:issuetrackingserviceexception" name="issuetrackingserviceexception"/> </wsdl:operation> <wsdl:operation name="getchanges" parameterorder="product changedsince"> <wsdl:input message="impl:getchangesrequest" name="getchangesrequest"/> <wsdl:output message="impl:getchangesresponse" name="getchangesresponse"/> <wsdl:fault message="impl:issuetrackingserviceexception" name="issuetrackingserviceexception"/> </wsdl:operation> 24 SilkCentral Test Manager API Guide

29 3 ISSUE TRACKING INTEGRATION Web Service Interface </wsdl:porttype> <wsdl:binding name="issuetrackingsoapbinding" type="impl:issuetrackingporttype"> <wsdlsoap:binding style="rpc" transport=" schemas.xmlsoap.org/soap/http"/> <wsdl:operation name="getfields"> <wsdlsoap:operation soapaction=""/> <wsdl:input name="getfieldsrequest"> <wsdlsoap:body encodingstyle=" schemas.xmlsoap.org/soap/encoding/" namespace=" scc.segue.com/issuetracking" use="encoded"/> </wsdl:input> <wsdl:output name="getfieldsresponse"> <wsdlsoap:body encodingstyle=" schemas.xmlsoap.org/soap/encoding/" namespace=" scc.segue.com/issuetracking" use="encoded"/> </wsdl:output> <wsdl:fault name="issuetrackingserviceexception"> <wsdlsoap:fault encodingstyle=" schemas.xmlsoap.org/soap/encoding/" namespace=" scc.segue.com/issuetracking" use="encoded"/> </wsdl:fault> </wsdl:operation> <wsdl:operation name="store"> <wsdlsoap:operation soapaction=""/> <wsdl:input name="storerequest"> <wsdlsoap:body encodingstyle=" schemas.xmlsoap.org/soap/encoding/" namespace=" scc.segue.com/issuetracking" use="encoded"/> </wsdl:input> <wsdl:output name="storeresponse"> <wsdlsoap:body encodingstyle=" schemas.xmlsoap.org/soap/encoding/" namespace=" scc.segue.com/issuetracking" use="encoded"/> </wsdl:output> <wsdl:fault name="issuetrackingserviceexception"> <wsdlsoap:fault encodingstyle=" schemas.xmlsoap.org/soap/encoding/" namespace=" scc.segue.com/issuetracking" use="encoded"/> </wsdl:fault> </wsdl:operation> <wsdl:operation name="logonuser"> <wsdlsoap:operation soapaction=""/> <wsdl:input name="logonuserrequest"> <wsdlsoap:body encodingstyle=" schemas.xmlsoap.org/soap/encoding/" namespace=" scc.segue.com/issuetracking" use="encoded"/> </wsdl:input> <wsdl:output name="logonuserresponse"> SilkCentral Test Manager API Guide 25

30 3 ISSUE TRACKING INTEGRATION Web Service Interface <wsdlsoap:body encodingstyle=" schemas.xmlsoap.org/soap/encoding/" namespace=" scc.segue.com/issuetracking" use="encoded"/> </wsdl:output> <wsdl:fault name="issuetrackingserviceexception"> <wsdlsoap:fault encodingstyle=" schemas.xmlsoap.org/soap/encoding/" namespace=" scc.segue.com/issuetracking" use="encoded"/> </wsdl:fault> </wsdl:operation> <wsdl:operation name="newissue"> <wsdlsoap:operation soapaction=""/> <wsdl:input name="newissuerequest"> <wsdlsoap:body encodingstyle=" schemas.xmlsoap.org/soap/encoding/" namespace=" scc.segue.com/issuetracking" use="encoded"/> </wsdl:input> <wsdl:output name="newissueresponse"> <wsdlsoap:body encodingstyle=" schemas.xmlsoap.org/soap/encoding/" namespace=" scc.segue.com/issuetracking" use="encoded"/> </wsdl:output> <wsdl:fault name="issuetrackingserviceexception"> <wsdlsoap:fault encodingstyle=" schemas.xmlsoap.org/soap/encoding/" namespace=" scc.segue.com/issuetracking" use="encoded"/> </wsdl:fault> </wsdl:operation> <wsdl:operation name="getstates"> <wsdlsoap:operation soapaction=""/> <wsdl:input name="getstatesrequest"> <wsdlsoap:body encodingstyle=" schemas.xmlsoap.org/soap/encoding/" namespace=" scc.segue.com/issuetracking" use="encoded"/> </wsdl:input> <wsdl:output name="getstatesresponse"> <wsdlsoap:body encodingstyle=" schemas.xmlsoap.org/soap/encoding/" namespace=" scc.segue.com/issuetracking" use="encoded"/> </wsdl:output> <wsdl:fault name="issuetrackingserviceexception"> <wsdlsoap:fault encodingstyle=" schemas.xmlsoap.org/soap/encoding/" namespace=" scc.segue.com/issuetracking" use="encoded"/> </wsdl:fault> </wsdl:operation> <wsdl:operation name="getpossiblestates"> <wsdlsoap:operation soapaction=""/> <wsdl:input name="getpossiblestatesrequest"> 26 SilkCentral Test Manager API Guide

31 3 ISSUE TRACKING INTEGRATION Web Service Interface <wsdlsoap:body encodingstyle=" schemas.xmlsoap.org/soap/encoding/" namespace=" scc.segue.com/issuetracking" use="encoded"/> </wsdl:input> <wsdl:output name="getpossiblestatesresponse"> <wsdlsoap:body encodingstyle=" schemas.xmlsoap.org/soap/encoding/" namespace=" scc.segue.com/issuetracking" use="encoded"/> </wsdl:output> <wsdl:fault name="issuetrackingserviceexception"> <wsdlsoap:fault encodingstyle=" schemas.xmlsoap.org/soap/encoding/" namespace=" scc.segue.com/issuetracking" use="encoded"/> </wsdl:fault> </wsdl:operation> <wsdl:operation name="fieldchanged"> <wsdlsoap:operation soapaction=""/> <wsdl:input name="fieldchangedrequest"> <wsdlsoap:body encodingstyle=" schemas.xmlsoap.org/soap/encoding/" namespace=" scc.segue.com/issuetracking" use="encoded"/> </wsdl:input> <wsdl:output name="fieldchangedresponse"> <wsdlsoap:body encodingstyle=" schemas.xmlsoap.org/soap/encoding/" namespace=" scc.segue.com/issuetracking" use="encoded"/> </wsdl:output> <wsdl:fault name="issuetrackingserviceexception"> <wsdlsoap:fault encodingstyle=" schemas.xmlsoap.org/soap/encoding/" namespace=" scc.segue.com/issuetracking" use="encoded"/> </wsdl:fault> </wsdl:operation> <wsdl:operation name="getlink"> <wsdlsoap:operation soapaction=""/> <wsdl:input name="getlinkrequest"> <wsdlsoap:body encodingstyle=" schemas.xmlsoap.org/soap/encoding/" namespace=" scc.segue.com/issuetracking" use="encoded"/> </wsdl:input> <wsdl:output name="getlinkresponse"> <wsdlsoap:body encodingstyle=" schemas.xmlsoap.org/soap/encoding/" namespace=" scc.segue.com/issuetracking" use="encoded"/> </wsdl:output> <wsdl:fault name="issuetrackingserviceexception"> <wsdlsoap:fault encodingstyle=" schemas.xmlsoap.org/soap/encoding/" namespace=" scc.segue.com/issuetracking" use="encoded"/> SilkCentral Test Manager API Guide 27

32 3 ISSUE TRACKING INTEGRATION Web Service Interface </wsdl:fault> </wsdl:operation> <wsdl:operation name="getchanges"> <wsdlsoap:operation soapaction=""/> <wsdl:input name="getchangesrequest"> <wsdlsoap:body encodingstyle=" schemas.xmlsoap.org/soap/encoding/" namespace=" scc.segue.com/issuetracking" use="encoded"/> </wsdl:input> <wsdl:output name="getchangesresponse"> <wsdlsoap:body encodingstyle=" schemas.xmlsoap.org/soap/encoding/" namespace=" scc.segue.com/issuetracking" use="encoded"/> </wsdl:output> <wsdl:fault name="issuetrackingserviceexception"> <wsdlsoap:fault encodingstyle=" schemas.xmlsoap.org/soap/encoding/" namespace=" scc.segue.com/issuetracking" use="encoded"/> </wsdl:fault> </wsdl:operation> </wsdl:binding> <wsdl:service name="issuetrackingservice"> <wsdl:port binding="impl:issuetrackingsoapbinding" name="issuetrackingport"> <wsdlsoap:address location=" issuetracking.endpoint"/> </wsdl:port> </wsdl:service> </wsdl:definitions> Configuring a Web Service profile Once your custom issue tracking Web service is hosted, you can configure an issue tracking profile in Test Manager. Procedure To configure a Web service issue tracking profile in Test Manager: 1 Select Administration/Configuration from the menu tree. 2 Select the Issue Tracking tab. 3 Click the New Profile button. The New Issue Tracking Profile dialog appears. 4 On the New Issue Tracking Profile dialog, select Issue Tracking Web Service from the Type drop-down list box. 5 In the Endpoint edit field, enter the URL of your hosted Web service. 6 Enter a valid Login name and Password into the respective fields, according to the values that have been implemented in the Web service. 28 SilkCentral Test Manager API Guide

33 3 ISSUE TRACKING INTEGRATION Java API Interface 7 Enter a meaningful Name and Description for the new issue tracking profile and click OK to confirm your settings. The new issue tracking profile is now available when entering issues in Test Manager. Java API Interface Note Refer to the JavaDoc (Help/Documentation/Test Manager API Specification) for full details regarding available Java classes and methods. Build environment Add the library scc.jar to your classpath, as it contains the interfaces you have to extend from. The jar file can be found in the lib directory of the Test Manager installation directory. You must extend two interfaces/classes: com.segue.scc.published.api.issuetracking.issuetrackingprofile com.segue.scc.published.api.issuetracking.issue Classes/Interfaces IssueTrackingProfile IssueTrackingData Issue IssueTrackingProfile (ITP) contains the methods that are required to access the ITS. The ITP accesses the ITS and interacts closely with the Issue. This gives information regarding the configured ITP. The ITP uses the data gathered here to access the ITS (e.g., user/password or the hostname/port of the ITS). Represents the issue itself (contains the data describing the issue). The issue is created when the user creates a new issue that is to be stored in the external ITS. Most of the data is contained in the ITF s. SilkCentral Test Manager API Guide 29

34 3 ISSUE TRACKING INTEGRATION Integrating Third-Party Issue Tracking IssueTrackingField IssueTrackingProfileE xception ITF s are provided by the issue. As they can be dependent upon each other, some notifications for changing the context are available. Only the field values that the user enters when creating a new issue in the external ITS should be returned. Any method can throw this exception with a message that helps the user identify their mistake. Integrating Third-Party Issue Tracking Issue tracking profiles enable Test Manager to integrate with external issue tracking systems. The issue tracking software packages that are currently supported by Test Manager out of the box are: SilkCentral Issue Manager (version 4.0 and higher) - see the SilkCentral Administration Module Online Help Rational ClearQuest - see the SilkCentral Administration Module Online Help SilkCentral Issue Manager see the SilkCentral Administration Module Online Help Issue Tracking Web Service - see Web Service Interface Bugzilla - see Bugzilla Plug-ins for other issue tracking systems may be available from Borland s download area, in the SilkCentral Test Manager menu ( Defining issue tracking profiles allows you to link test definitions within the Test Plan unit to issues in third-party issue-tracking systems. Linked issue states are updated periodically from the third-party issue tracking system. Refer to Creating Plug-Ins for detailed information regarding the deployment of your custom issue tracking profiles. Bugzilla The BugZilla plug-in relies on SilkCentral s Java API for integration. The Bugzilla integration has been tested with Bugzilla Modifications to your Bugzilla installation are not required to enable integration. SilkCentral Test 30 SilkCentral Test Manager API Guide

35 3 ISSUE TRACKING INTEGRATION Integrating Third-Party Issue Tracking Manager communicates with Bugzilla via Bugzilla s Web GUI (using Jakarta Common s HttpClient library). Note See the sources of com.segue.scc.issuetracking.bugzilla.bugzillaprofile and com.segue.scc.issuetracking.bugzilla.bugzillaissue to see how these elements fit together. Adding a Bugzilla profile Procedure To add a Bugzilla profile: 1 Select the Issue Tracking tab from Administration/Configuration in the menu tree. The Issue Tracking page appears, listing all the issue tracking profiles that have been created for the system. 2 Click the New Profile button to open the New Issue Tracking Profile page. 3 On the New Issue Tracking Profile dialog, enter a name for the new profile. This is the name that will be displayed in lists where issue tracking profiles are available for selection. 4 Enter a description for the new profile (this is only used for GUI display purposes). 5 Select Bugzilla from the Type drop list. 6 Enter the valid login and password that will be used to access Bugzilla. 7 Enter the URL of your Bugzilla installation (e.g., cgi-bin/bugzilla/). Note The URL must end with a slash ( / ) to establish a connection to Bugzilla. 8 Click OK when you have finished entering the profile information; or click Cancel to abort the operation. If you have clicked OK, Test Manager will attempt a trial connection to the Bugzilla installation using SilkCentral Test Manager API Guide 31

36 3 ISSUE TRACKING INTEGRATION Integrating Third-Party Issue Tracking the information you have provided. If an error occurs, please review the login credentials and the URL that you have supplied, or consult your Bugzilla administrator. 9 If the trial connection to Bugzilla is successful, a confirmation dialog appears, asking you if you want to map internal issue states to the states of the newly defined profile. If you select Yes, please proceed with step 3 of the following procedure. Click No if you want to map issue states later. Mapping issue states After defining a Bugzilla profile, you should map the existing issue states of Bugzilla to the states of Test Manager. Doing this enables Test Manager to list issues correctly when querying internal and external issues. Procedure To map issue states: 1 Select the Issue Tracking tab from Administration/Configuration in the menu tree. The Issue Tracking page appears, listing all of the issue tracking profiles that have been created for the system. 2 Click the Edit state mapping icon of the Bugzilla profile. 3 The Status Mapping dialog appears, listing all of bugzilla s existing issue states. These states are listed in the External column. Test Manager s internal issue states are available in the drop lists in the Internal column. Map internal issue states to corresponding external issue states by selecting the respective entries from the drop list. 4 Once you have mapped each external issue state to an internal state, click OK to save your settings; or click Cancel to abort the operation. 32 SilkCentral Test Manager API Guide

37 4 Requirements 4Chapter Management Integration Introduction What you will learn This chapter explains how to integrate Test Manager s requirements management functionality with third-party requirements management systems. This chapter contains the following sections: Section Page Overview 33 Deploying the API 34 Requirements Plug-In API 34 Interfaces for External RMS 40 Overview Test Manager can be integrated with any third-party Requirements Management System (RMS) tool to link and synchronize requirements. This chapter describes a Java application programming interface that enables you to implement third-party plug-ins for synchronization of requirements in Test Manager with the requirements of a third-party Requirements Management System via Web services. This chapter describes the interfaces that identify a requirement plug-in and the required Web service that provides access to the third-party and its deployment. A jar or zip-file is provided following the standard plug-in concept of Test Manager, which is automatically deployed to all front-end servers and, thereby enabling access to third-party tools for configuration and synchronization. This plug-in implements a specified interface that allows Test Manager to identify it SilkCentral Test Manager API Guide 33

38 4 REQUIREMENTS MANAGEMENT INTEGRATION Deploying the API as a requirements plug-in and provides the required login properties to log in to a Web service that gives access to the third-party tool. Note Refer to the JavaDoc (Help/Documentation/Test Manager API Specification) for full details regarding available Java classes and methods. Deploying the API Packaging Deployment The plug-in implementation is packaged in a zip archive and needs to (at least indirectly) implement the RMPlugInConfiguration interface (com.segue.tm.published.api.requirements.rmpluginconfiguration) to be integrated. The plug-in contains the Java code base and possibly also an XML configuration file. This code base may be contained in an arbitrarily named Java archive file (.jar) or directly in.class files within folders representing the Java package structure. The plug-in zip archive resides in the Plugins subdirectory under the Test Manager installation directory. To integrate plug-ins residing in this directory, restart your application server and front-end server via SilkCentral Service Manager (hot deployment is not currently supported). Each time an archive is modified these two servers must be restarted. The archive is uploaded automatically to execution servers. Note Never remove a plug-in archive while a Test Manager project is configured to use the plug-in for third-party requirements integration. Requirements Plug-In API RMPlugInConfiguratio n Interface This interface from package com.segue.tm.published.api.requirements must be implemented by a class in the plug-in package. public interface RMPlugInConfiguration { /** * name of the Requirement Management System this plug-in supports */ public String getrmsname(); /** * URL of the web-service that provides access to the Requirement Management System */ public String geturl(); 34 SilkCentral Test Manager API Guide

39 4 REQUIREMENTS MANAGEMENT INTEGRATION Requirements Plug-In API PropertyProvider Interface /** * PropertyProvider, that provides all properties required to login to the * Requirement Management System */ public PropertyProvider getloginproperties(); } The geturl() method provides a string that contains the URL of a Web service that implements the RMService (com.segue.tm.published.webservice.requirements.rmservice) interface. This service may already be part of the third-party requirements management system or must be provided and installed separately. Sample URL: The getloginproperties() method provides an object that implements the PropertyProvider (com.segue.scc.published.api.propertyprovider) interface, which provides all required properties for a successful login to the service from the geturl() method. This interface from the com.segue.scc.published.api package provides access to a set of properties. public interface PropertyProvider { final static int PROPERTY_TYPE_NUMBER = 1; final static int PROPERTY_TYPE_STRING = 2; final static int PROPERTY_TYPE_PASSWORD = 3; final static int PROPERTY_TYPE_FILE = 4; /** * Get the available property names. available property names */ String[] getproperties(); /** * Get the type of a property. See the PROPERTY_TYPE_* constants in the interface for valid * properties. You will only get properties as a parameter, that have been retrieved by * {@link #getproperties()}. propertyname the type of a property */ int getpropertytype(string propertyname); /** * Get the default data for a property, if nothing is set yet. If this method returns null, * there is no default data. propertyname a property got by {@link #getproperties()} the default data for a property, if nothing is set yet. null, if there is no default data */ String getdefaultvalue(string propertyname); } This interface supports four types of properties (number, string, password, and file). SilkCentral Test Manager API Guide 35

40 4 REQUIREMENTS MANAGEMENT INTEGRATION Requirements Plug-In API RMService Interface The getproperties() method provides a string array with the names of all properties. The getpropertytype() method additionally provides the corresponding type for each of these properties. This interface from the com.segue.tm.published.webservice.requirements package provides all methods required by Test Manager to interact with a thirdparty RMS Web service. Test Manager s configuration and requirement units use this Web service interface in their configuration and synchronization dialogs as well as in the synchronization process itself. public interface RMService { ////////////////////////////////////////////////// // session methods ////////////////////////////////////////////////// /** * This method returns an Id (sessionid) that is used for all actions during a session to identify the user loginproperties map of keys (names of login properties) and their values sessionid as String RMServiceException */ public String login(map loginproperties) throws RMServiceException; /** * This method closes the actual user session. RMServiceException */ public void logout() throws RMServiceException; ////////////////////////////////////////////////// // project methods ////////////////////////////////////////////////// /** * sessionid projectid project for provided project id RMServiceException */ public Project getproject(string sessionid, String projectid) throws RMServiceException; /** * sessionid array of all existing projects RMServiceException */ public Project[] getprojects(string sessionid) throws RMServiceException; /** * sessionid current active project 36 SilkCentral Test Manager API Guide

41 4 REQUIREMENTS MANAGEMENT INTEGRATION Requirements Plug-In API RMServiceException */ public Project getcurrentproject(string sessionid) throws RMServiceException; /** * changes current active project to project with id equal to provided project id sessionid projectid RMServiceException */ public void setcurrentproject(string sessionid, String projectid) throws RMServiceException; /** * locks current active project sessionid RMServiceException */ public void lockproject(string sessionid) throws RMServiceException; /** * unlocks current active project sessionid RMServiceException */ public void unlockproject(string sessionid) throws RMServiceException; ////////////////////////////////////////////////// // requirement type methods ////////////////////////////////////////////////// /** * sessionid all requirement types of current active project RMServiceException */ public RequirementType[] getrequirementtypes(string sessionid) throws RMServiceException; /** * sessionid requirementtypeid requirement type with id equal to provided requirement type id RMServiceException */ public RequirementType getrequirementtype(string sessionid, String requirementtypeid) throws RMServiceException; ////////////////////////////////////////////////// // requirement methods ////////////////////////////////////////////////// /** * sessionid requirementid if requirementid is null, this call will return the root * requirements of the project SilkCentral Test Manager API Guide 37

42 4 REQUIREMENTS MANAGEMENT INTEGRATION Requirements Plug-In API requirement children of requirement with provided requirement id RMServiceException */ public Requirement[] getrequirementchildren(string sessionid, String requirementid) throws RMServiceException; /** * sessionid requirementid requirement with id equal to provided requirement id RMServiceException */ public Requirement getrequirement(string sessionid, String requirementid) throws RMServiceException; /** * inserts or updates requirement. if requirement was new, the new generated requirement id is returned. * if some sort of locking has to be done, the requirement objects does it within itself sessionid requirement to be saved id of requirement RMServiceException */ public String updaterequirement(string sessionid, Requirement requirement) throws RMServiceException; /** * deletes requirement. if requirement has children, they are only deleted if recursiv is true, * otherwise method fails. sessionid requirementid recursiv boolean, that determins, if existing children shall be deleted too id of requirement RMServiceException */ public String deleterequirement(string sessionid, String requirementid, boolean recursiv) throws RMServiceException; ////////////////////////////////////////////////// // property methods ////////////////////////////////////////////////// /** * sessionid requirementtypeid string array of all property ids for provided requirement type id RMServiceException */ public String[] getpropertyids(string sessionid, String requirementtypeid) throws RMServiceException; /** * sessionid requirementtypeid propertyid 38 SilkCentral Test Manager API Guide

43 4 REQUIREMENTS MANAGEMENT INTEGRATION Requirements Plug-In API property meta info for a specific property (string id from getpropertyids() ) RMServiceException */ public PropertyMetaInfo getpropertyinfo(string sessionid, String requirementtypeid, String propertyid) throws RMServiceException; /** * sessionid requirementid propertyid property value of property from requirement with provided property and requirement id RMServiceException */ public PropertyValue getproperty(string sessionid, String requirementid, String propertyid) throws RMServiceException; /** * updates property. if some sort of locking has to be done, the property objects does it within itself sessionid requirementid property property id of updated property RMServiceException */ public String updateproperty(string sessionid, String requirementid, PropertyValue property) throws RMServiceException; ////////////////////////////////////////////////// // property test ////////////////////////////////////////////////// /** * sessionid requirementid all assigned tests of requirement with provided requiremnt id RMServiceException */ public Test[] getassignedtests(string sessionid, String requirementid) throws RMServiceException; /** * assigns test with provided test id to requirement with provided requirement id sessionid requirementid testid RMServiceException */ public void assigntest(string sessionid, String requirementid, String testid) throws RMServiceException; /** * unassigns test with provided test id from requirement with provided requirement id sessionid requirementid testid RMServiceException */ SilkCentral Test Manager API Guide 39

44 4 REQUIREMENTS MANAGEMENT INTEGRATION Interfaces for External RMS public void unassigntest(string sessionid, String requirementid, String testid) throws RMServiceException; } Interfaces for External RMS SilkCentral Test Manager itself also supports the RMService interface (com.segue.tm.published.webservice.requirements) and provides to other tools, via this Web service, access to Test Manager s Requirements unit. This enables other tools to retrieve and manipulate Test Manager s requirements data. For detailed information on this interface see the RMService Interface section of the Requirements Plug-In API. 40 SilkCentral Test Manager API Guide

45 5 Third-Party 5Chapter Test Type Integration Introduction What you will learn This chapter explains how to integrate third-party test types into SilkCentral Test Manager. This chapter contains the following sections: Section Page Overview 41 Plug-In Implementation 42 Structure of the API 44 Sample Code 45 Configuration XML File 48 Deployment 49 Overview Test Manager enables you to create custom plug-ins for test types beyond the standard set of available test types, which includes SilkPerformer, SilkTest, manual tests, NUnit, JUnit, and Windows Scripting (WSH). Upon creating a new test-type plug-in, your custom test type becomes available in the Type dropdown list alongside the standard test types that are available for creating new test definitions in Test Manager. SilkCentral Test Manager API Guide 41

46 5 THIRD-PARTY TEST TYPE INTEGRATION Plug-In Implementation This chapter describes a Java application programming interface that can be used to implement third-party plug-ins for automated execution of test types that are not supported in the standard Test Manager product. A plug-in specifies which properties are required for configuring a test definition and implementing execution of a test. Meta information about properties is defined via an Configuration XML File. The goal of the plug-in approach is to support tests based on common testing frameworks like JUnit and NUnit, or script languages (WSH), for easy customization of Test Manager to your specific testing environment. Test Manager s well-defined public API allows you to implement a proprietary solution that meets your automated test needs. Test Manager is open and extensible to any third-party tool that can be invoked from a Java implementation or via command line call. Note Refer to the JavaDoc (Help/Documentation/Test Manager API Specification) for full details regarding available Java classes and methods. Plug-In Implementation The principles of the API are based on widely known Java Beans concepts. This allows developers to easily implement test launch plug-ins. To avoid putting textual information in Java code, meta information about properties is defined in an XML file. The plug-in implementation is packaged in a zip archive and implements a callback interface so that it can be integrated. Other interfaces are in turn provided by the plug-in framework and allow the implementation to access information or return results. 42 SilkCentral Test Manager API Guide

47 5 THIRD-PARTY TEST TYPE INTEGRATION Plug-In Implementation Packaging Passing parameters to the plug-in The plug-in is packaged in a zip archive that contains the Java codebase and the XML configuration file. The archive also contains some test launch plug-in implementations. The codebase may be contained in a Java archive file (.jar) or directly in.class files within folders representing the Java package structure. The TestLaunchBean plug-in class follows the Bean standard and implements the TestLaunchBean interface. The XML configuration file in the.zip archive has the same name as this class. This allows you to package multiple plug-ins and XML files in a single archive. The plug-in interface provides full access to all custom parameters that have been defined in Test Manager s Test Planning unit (as explained in the SilkCentral Test Manager Online Help, in the Parameters section). Only custom parameters are supported for third-party test types. The plug-in cannot specify predefined Parameters; the plug-in implementation determines if and how parameters are defined for specific test definitions. Use the getparametervaluestrings() method in the TestLaunchPluginContext interface to obtain a container with mappings from parameter names (key) to their values (represented as String). See Structure of the API below for more details. For JUnit test types, any JUnit test class can access a custom parameter of the underlying test definition as a Java system property; the launcher passes these parameters to the executing virtual machine using the -D VM argument. SilkCentral Test Manager API Guide 43

48 5 THIRD-PARTY TEST TYPE INTEGRATION Structure of the API Structure of the API TestLaunchBean This is the interface that is implemented by each test launch plug-in that is integrated into Test Manager. Custom plug-ins need to implement this interface in order to be integrated into Test Manager. Directly implement this interface if a derivation from AbstractTestLaunchBean is not possible, as this class is more convenient to use. If an external process should be started, derive from ExtProcessTestLaunchBean instead. Any method get<<property-name>> defines a property displayed in the GUI when creating or editing a test definition based on that plug-in. For each there must be a corresponding set<<property-name>> method. In the plug-in configuration file additional meta information for each property can be defined (e.g., textual description, default value, range). An instance of an implementing class is associated with a test definition and created on the execution server before this test definition is executed. Next the initialize method and all set<<property-name>> methods are called, supplying all property input the user has entered for a test definition to the plug-in. Finally the execute method is called, where the actual execution work has to be implemented. 44 SilkCentral Test Manager API Guide

49 5 THIRD-PARTY TEST TYPE INTEGRATION Sample Code ExtProcessTestLaunc hbean Other interfaces Properties Information about properties is gathered from code (get<<property-name>>) and the XML file. Note that the first character of the property name is lowercase, a getscript method defines a property named script. This name must be used in the XML file. A property s type is defined by the type of the return value of the get method. The following property types are supported: String and File. This is a convenience class for test launch plug-in subclasses used to launch an external process. Plug-ins may derive from this class instead of implementing TestLaunchBean if the plug-in needs to launch an external process. This class provides a #runexternalprocess method that accomplishes the start of an arbitrary external executable. In addition to providing stdout, stderr log info, this process is automatically stopped when the framework demands termination. This typically occurs when a user aborts an execution manually, a specified timeout has expired, or an execution server shuts down. Other interfaces shown in the above diagram enable plug-ins to access Test Manager information. See the JavaDoc (Help/Documentation/Test Manager API Specification) documentation for details. Sample Code /** * TestManager 8.1 Execution Plugin Launching SilkPerformer.Net Explorer */ public class DotNetExplorerLauncher extends ExtProcessTestLaunchBean { private File mscript; private File mexecuteable; private String mtestcase; /** * Called to execute a test definition and invoke the plugin's test execution implementation. * Is invoked at times specified by some schedule within the execution part or by "run-once". time The (logical) timestamp milliseconds after the epoch identifying this execution. context Container for holding results of the current run. InterruptedException if the {@link #terminate} method was called while execution was * in progress. */ public boolean execute(long time, TestLaunchResultDrain context) throws InterruptedException { // checking input parameters if (mscript == null mscript.getname().length() < 4) { context.getlog().println("severity_error: No script property set for this test definition "+gettestdefname()+"."); context.publishmessage(testlaunchresultdrain.severity_fatal, "No script property set for this test definition."); SilkCentral Test Manager API Guide 45

50 5 THIRD-PARTY TEST TYPE INTEGRATION Sample Code return false; } else if (mscript.getname().indexof(".nef") == -1) { context.getlog().println("severity_error: Invalid script property set for this test definition "+gettestdefname()+"..netexplorer files must end with.nef"); context.publishmessage(testlaunchresultdrain.severity_fatal, "Invalid script property set for this test definition..netexplorer files must end with.nef"); return false; } else if (mexecuteable == null mexecuteable.getname().length() < 4) { context.getlog().println("severity_error: No executeable property set for this test definition "+gettestdefname()+"."); context.publishmessage(testlaunchresultdrain.severity_fatal, "No executeable property set for this test definition."); return false; } try { // building commandline String outputfilename = null; File workingdir = context.gettempresultsdir(); File srcpath = mscript; if (!(context instanceof UnitTestTestLaunchResultDrain)) { srcpath = sourceaccess().getlocalpath(mscript.getpath()); } outputfilename = workingdir.getabsolutepath() + System.getProperty("file.separator") + "output"; String[] cmdline = new String[4]; cmdline[0] = mexecuteable.getabsolutepath(); cmdline[1] = srcpath.getabsolutepath(); if (mtestcase!= null && mtestcase.length() > 0) { cmdline[2] = mtestcase; } else { cmdline[2] = "*"; } cmdline[3] = outputfilename; String info = "executing: '"+cmdline[0]+" "+cmdline[1]+" "+cmdline[2]+" "+cmdline[3]+"'"; context.publishmessage(testlaunchresultdrain.severity_info, info); // executing commandline int processexitcode = runexternalprocess(cmdline, null, workingdir, context.getlog()); // checking process exitcodes if (processexitcode!= 0) { String codeasstring = "Unkown"; switch (processexitcode) { case 1: codeasstring = "NoCommandLine"; break; case -1: codeasstring = "FileNotFound"; break; case -2: codeasstring = "FileNotAccessable"; break; case -3: codeasstring = "TestCaseNotFound"; break; case -4: codeasstring = "CannotWriteOutputFile"; break; case -5: codeasstring = "CreateProject"; break; case -6: codeasstring = "CreateProjectExists"; break; 46 SilkCentral Test Manager API Guide

51 5 THIRD-PARTY TEST TYPE INTEGRATION Sample Code case -7: codeasstring = "OpenProject"; break; case -8: codeasstring = "OpenProjectDontExists"; break; case -9: codeasstring = "ProjectOpened"; break; default: codeasstring = "Unknown"; break; } context.publishmessage(testlaunchresultdrain.severity_error, "Process return code was " + String.valueOf(processExitCode) + " ("+codeasstring+")."); context.updateerrors(1, 0); } // checking stdout if(stdoutreport()!= null && stdoutreport().length() > 0) { context.publishmessage(testlaunchresultdrain.severity_info, stdoutreport()); context.getlog().println("severity_info: "+stdoutreport()); } // checking stderr if(stderrreport()!= null && stderrreport().length() > 0) { context.publishmessage(testlaunchresultdrain.severity_error, stderrreport()); context.getlog().println("severity_error: "+stderrreport()); context.updateerrors(1, 0); } // parsing resultfile if existing File xmlresultfile = new File(outputFileName+".xml"); if (xmlresultfile.exists()) { parsevuserreportxmlfile(xmlresultfile, context); } else { context.publishmessage(testlaunchresultdrain.severity_warning, "No xml resultfile found ("+xmlresultfile.getname()+")"); context.updateerrors(0, 1); } } catch (IOException e) { // executing commandline may have thrown a IOException context.publishmessage(testlaunchresultdrain.severity_fatal, e.getmessage()); context.updateerrors(1, 0); e.printstacktrace(context.getlog()); return false; } return true; } // DO NOT REMOVE get/set methods, they are called by via reflection public File getscript() { return mscript; } public void setscript(file script) { mscript = script; } public File getexecuteable() { return mexecuteable; } public void setexecuteable(file executeable) SilkCentral Test Manager API Guide 47

52 5 THIRD-PARTY TEST TYPE INTEGRATION Configuration XML File { } mexecuteable = executeable; public String gettestcase() { return mtestcase; } public void settestcase(string testcase) { mtestcase = testcase; } Configuration XML File Sample configuration file Plug-in meta information <?xml version="1.0" encoding="utf-8"?> <!-- Meta information for the test definition type --> <TestLaunchPlugin id="dotnetexp" label=".netexplorer" description="a SilkPerformer -.NetExplorer test" version="1.0" > <!-- Meta information for properties --> <Properties> <script label="script" isoptional="false" description="the script to be executed." openbrowser="true" issourcecontrol="true" filenamespec="*.nef" /> <executeable label="executeable" isoptional="false" description="the path to SilkPerformer.NetExplorer executeable (NetExplorer.exe)." openbrowser="true" issourcecontrol="false" filenamespec="netexplorer.exe" /> <testcase label="testcase" isoptional="true" description="the testcase to be executed." maxlength="256" editmultiline="false" ispassword="false" /> </Properties> </TestLaunchPlugin> Plug-in meta information generally provides information about the plug-in and test definition type. Available information types are: id - An internal string that is unique among all installed plug-ins identifying this type. 48 SilkCentral Test Manager API Guide

53 5 THIRD-PARTY TEST TYPE INTEGRATION Deployment label - The GUI text displayed in the choice list and edit dialogs for this type. description - Additional textual information describing this test definition type. version - Distinguishes different versions of a type. General property meta information String property meta information File property meta information For editable properties there is general information that is the same for each property type (in addition to the type-specific information). The name of a property must match those defined in the code by get<<propertyname>> methods, with the first character in lowercase (e.g., script). label - The text displayed in the GUI. description - Additional textual information describing the property. isoptional - A value of true indicates that user input is not required. default - The default value for the property when creating a new test definition. This value must match the property type. maxlength - Denotes the maximum length the user can enter. editmultiline - Denotes if the edit field should have multiple rows. ispassword - A value of true hides the user input as ***. For specified file values, non version-controlled files with absolute paths on the execution server are distinguished from version-controlled files. Files under source control are always relative to the root directory of the test container and are typically used to specify a test source to be executed. Absolute paths need to exist on the execution server, typically specifying a tool or resource used to invoke the test on the execution server. openbrowser - A value of true indicates that a browser should be opened to select the file from the files in a test container. issourcecontrol - A value of true indicates that the file originates from a source control system. filenamespec - Denotes a restriction for allowed file names as known from the standard Windows file browse dialog. Deployment The plug-in zip archive must reside in the Plugins subdirectory within the Test Manager installation directory. To integrate plug-ins residing in this directory, restart your Application Server and Front-end Server via SilkCentral Service Manager (hot deployment is not supported currently). Each time an archive is modified, these two servers must be restarted. The archive is uploaded automatically to execution servers. SilkCentral Test Manager API Guide 49

54 5 THIRD-PARTY TEST TYPE INTEGRATION Deployment Note Never remove a plug-in archive after a test definition based on that plug-in has been created. 50 SilkCentral Test Manager API Guide

55 6 SilkCentral 6Chapter Web Service Interface Introduction What you will learn This chapter explains the Web Service interfaces that are available with SilkCentral Test Manager. This chapter contains the following sections: Section Page SilkCentral Web Services 51 Web Services Quick Start 54 Administration Web Services 60 Test Manager Web Services 65 Issue Manager Web Services 87 SilkCentral Web Services Web Services don t require setup; they are enabled by default on each front-end server. For example, if is the URL that you use to access SilkCentral, then is the base URL you use to access available Web Services. When you access the base URL using your browser, you are presented with a simple HTML list of all available Web Services. This list is provided by Apache Axis the SOAP stack that SilkCentral uses ( This basic Web page provides links to WSDL (Web Service Definition Language) standardized XML files, where each file describes the interface of a single Web Service. These files are not human readable. For this reason, SOAPenabled clients (e.g., SilkPerformer Java Explorer) read WSDL files and thereby SilkCentral Test Manager API Guide 51

56 6 SILKCENTRAL WEB SERVICE INTERFACE SilkCentral Web Services retrieve information required for invoking methods on corresponding Web Services. Session handling SilkCentral data is protected against unauthorized access. Login credentials must be provided before data access is granted. This is true not only when working with the HTML front-end, but also for communication with Test Manager via SOAP calls. The first step in querying data, or applying configuration changes for SilkCentral Test Manager, is authentication. When authentication is successful, a user session is created that allows execution of subsequent operations in the context of that user login. When accessing Test Manager via a Web browser, session information is not visible to the user; the browser (using cookies) handles session information. In contrast to using SilkCentral via HTML, SOAP calls must handle information manually. Authentication via Web Services is done through the SOAP call logonuser() of Web Service sccsystem. The method call returns a session identifier that references the session created on the server and at the same time is used as a key to access SilkCentral in the context of that session. 52 SilkCentral Test Manager API Guide

57 6 SILKCENTRAL WEB SERVICE INTERFACE SilkCentral Web Services Services hosted by SilkCentral Each subsequent SOAP call that requires a session for execution takes such an identifier as one of its parameters, checks its validity, and executes in the context of the corresponding session. The following (Java) code sample shows simple access to SilkCentral Test Manager via Web Services and demonstrates use of the session identifier: long sessionid = sccsystem.logonuser("admin", "admin"); Project[] projects = sccentities.getprojects(sessionid); A SilkCentral session created via Web Services cannot be ended explicitly. Instead, sessions end automatically when they're not used for a period of time. As soon as a session times out on a server, subsequent SOAP calls attempting to use the session throw exceptions. A demonstration client is available for download from downloads/download_silk.html under the SilkCentral Test Manager link. This demo project utilizes Test Manager s execution Web Service, helping you to get familiar with Test Manager s Web Service interface. The following table lists the available SilkCentral Web Services. Note The WSDL URL also lists system-internal Web Services which are not intended for creating Web Services clients. This document describes only the published Web Services. WS Name WSDL URL Description sccsystem /services/sccsystem?wsdl This is the root service that provides authentication and simple utility methods. sccentities /services/sccentities?wsdl This service provides access to the Project and Product entities on the SilkCentral platform. tmrequirementsmanagement /services/ tmrequirementsmanagement?wsdl This service provides access to the Requirements unit of SilkCentral Test Manager. tmplanning /services/tmplanning?wsdl This service provides access to the Test Plan unit of SilkCentral Test Manager. It also enables starting executions and fetching execution results. SilkCentral Test Manager API Guide 53

58 6 SILKCENTRAL WEB SERVICE INTERFACE Web Services Quick Start tmexecution /services/tmexecution?wsdl This service provides access to the Execution unit of SilkCentral Test Manager. scim /services/scim?wsdl This service provides access to SilkCentral Issue Manager. Web Services Quick Start Prerequisites This section provides a basic tutorial so that a user may quickly get started using the SilkCentral Test Manager Web services. The reader should have satisfied the following prerequisites before attempting to develop Web services clients: Basic knowledge of Object Oriented Programming (OOP). Java experience would be helpful, since examples will be given in that language. A developer with no Java but C++, C#, Python, or Perl experience should still be able to easily follow the Quick Start. Experience in manipulating collections such as HashMaps and Lists is desirable. JUnit tests are briefly mentioned. This Java testing framework is not required, but would be helpful to the developer. Introductory exposure to Web services technology. This document is not meant to be an instruction course in Web services, SOAP, etc. The reader should have already, at a minimum, coded and successfully ran a "Hello World!" Web service client. Understand SilkCentral Test Manager s Web services architecture (see SilkCentral Web Services ). Zero to Web Services Client in 60 Seconds Overview Make sure you have Java SDK 1.5+ installed and in your PATH. It would be helpful to have the JUnit jar in your classpath. It can be downloaded here Download the Axis Web services library from 54 SilkCentral Test Manager API Guide

59 6 SILKCENTRAL WEB SERVICE INTERFACE Web Services Quick Start Unpack and put all jars in the lib directory in your classpath, it will be helpful to use an environment variable AXISCLASSPATH for this. Run this command, pointing to the WSDL of the desired Web service: java -cp %AXISCLASSPATH% org.apache.axis.wsdl.wsdl2java -o. -d Session -p package.structure.you.want.to.use.for.your.client.yourwebservice -t Look for the automatically generated Java class YourWebServiceTestCase. This class is all ready for you to "turn the crank" and exercise every method YourWebService provides. You need only replace the default empty variables. For example, the empty String username, password in a login(string username, String password) call should be replaced with the actual username, password values to be used. This class is a JUnit test, but one could simply copy/paste code into a simple main method Java driver class in order to build a client. That's it, your Web service client stub is ready! Details Web services typically use a SOAP over HTTP protocol. In this scenario, SOAP envelopes are sent "over the wire". When collections and other complex objects are bundled in SOAP envelopes, the ASCII data structures can become difficult to read and edit. Novice developers should not try to build Web service clients by direct manipulation of SOAP envelopes without a compelling reason to do so. Experienced developers typically do not build Web service clients at the SOAP envelope level. Doing so is tedious and error prone. For this reason, all major programming languages provide Web service development kits for this purpose. Axis is the most widely used Java kit. gsoap is the most common tool for C++ and C. Others exist for Perl, Python, etc. Regardless of the implementation language (Java, C++, C#, Perl, Python, etc.), building Web service clients follows a general, simple, pattern: 1 Point a development kit tool to the Web service WSDL 2 Get a client stub returned from the above step 1. 3 Edit the client stub generated in step 2 to obtain a full-blown client. Axis follows the general pattern. Here, the WSDL2Java tool is used to build the client stubs from the WSDL. Detailed information on how to use the WSDL2Java can be found here A brief description of the switches used in the above summary is as follows: -o: The output directory of the client stubs -d: The scope of the Web services connection -p: Use package structure for namespaces, deploy to this package structure -t: Output a JUnit test case class for the Web service SilkCentral Test Manager API Guide 55

60 6 SILKCENTRAL WEB SERVICE INTERFACE Web Services Quick Start It is always a good idea to generate the JUnit test case class. This class will not only provide code that binds to the Web service, but will output test code that exercises every single method of the service. This is a tremendous time-saver for the developer. The WSDL2Java tool will generate several classes to support a client to the Web service. If YourWebService is the name of the service, then one can expect the following classes to be output: YourWebService: An interface representing YourWebService YourWebServiceService: An interface representing the YourWebService Locator YourWebServiceServiceLocator: A YourWebService Locator, implements YourWebServiceService YourWebServiceSoapBindingStub: A client stub that handles the serialization of YourWebService POJOs YourWebServiceServiceTestCase: A JUnit test case that exercises all methods of YourWebService Serializeable Objects: Client-side objects corresponding to the objects YourWebService uses. The author recommends renaming the interfaces and implementing classes to more human-readable form: YourWebServiceService => becomes IYourWebServiceLocator (Leading "I" indicates "Interface"). YourWebServiceServiceLocator => becomes YourWebServiceLocator, implements IYourWebServiceLocator YourWebService => becomes IYourWebService The Axis generated JUnit test case is extremely valuable to the developer. It is a ready to run "out-of-the-box" client. One need only change the default initialized variables to reflect valid ones for the web service. It also provides binding code that uses the locator to start the "Find-Bind-Execute" SOA cycle. Let's look at an excerpt from the test case provided for the tmrequirementsmanagement Web service: /* default test automatically generated by WSDL2Java */ public void test2tmrequirementsmanagementlogin() throws Exception { com.borland.tm.webservices.tmrequirementsmanagement.tmrequirementsmanage mentsoapbindingstub binding; try { binding = (com.borland.tm.webservices.tmrequirementsmanagement.tmrequirementsmanag ementsoapbindingstub) new com.borland.tm.webservices.tmrequirementsmanagement.requirementsservicel ocator().gettmrequirementsmanagement(); } catch (javax.xml.rpc.serviceexception jre) { 56 SilkCentral Test Manager API Guide

61 6 SILKCENTRAL WEB SERVICE INTERFACE Web Services Quick Start if(jre.getlinkedcause()!=null) jre.getlinkedcause().printstacktrace(); throw new junit.framework.assertionfailederror("jax-rpc ServiceException caught: " + jre); } assertnotnull("binding is null", binding); // Time out after a minute binding.settimeout(60000); // Test operation try { java.lang.string value = null; value = binding.login(new java.util.hashmap()); } catch (com.borland.tm.webservices.tmrequirementsmanagement.rmserviceexception e1) { throw new junit.framework.assertionfailederror("rmserviceexception Exception caught: " + e1); } // TBD - validate results } Note how the JUnit test provides code for binding and logging in! The developer only need fill in the default HashMap to complete the code for logging in. Thus, if creating a POJO Web service client, a simple copy/paste/edit would provide ready-made bind and login methods: public TmrequirementsmanagementSoapBindingStub getbinding() throws Exception { TmrequirementsmanagementSoapBindingStub binding; try { binding = (TmrequirementsmanagementSoapBindingStub) new RequirementsServiceLocator().gettmrequirementsmanagement(); } catch (ServiceException jre) { // Handle error } if(binding == null) { // handle error here System.err.println("binding is null."); System.exit(0); } // Time out after a minute binding.settimeout(60000); return binding; } public String login(string username, String password) { // mbinding = getbinding() already obtained // Now get msessionid member variable try { HashMap map = new HashMap(); map.put("username", username); map.put("password", password); msessionid = mbinding.login(map); } SilkCentral Test Manager API Guide 57

62 6 SILKCENTRAL WEB SERVICE INTERFACE Web Services Quick Start catch (RMServiceException e1) { // Handle error here } return msessionid; } What We Have Learned So Far Working Web service clients can be obtained quickly with toolkits. Web service client toolkits are available for major programming languages. Axis is a toolkit for Java. The Axis WSDL2Java can produce a client stub in seconds. The WSDL2Java provided test case provides code for binding and consuming Web service methods. Full-blown clients can be rapidly built by copy/paste/edit of the WSDL2Java test case methods. An Example Use Case: Add Requirement to SilkCentral Test Manager Prerequisites The "Zero to Client in 60 Seconds" steps were followed for the tmrequirementsmanagement Web service. A working POJO or JUnit class with binding, logging-in, and other tmrequirementsmanagement methods has been created using the above copy/paste/edit procedure. The developer has read the SilkCentral Test Manager API Guide (this document). Details Below are the steps required to add a requirement: 1 Bind to the service using login method and a property map of user credentials. 2 Save session ID obtained from 1 above. 3 Construct a requirements object containing desired data. 4 Call updaterequirement method with session ID and object from 3. 5 Save returned requirement ID from 4 above. 6 Create PropertyValue array of requirement properties. 7 Call updateproperties method with array from 5 above. The WSDL2Java would have created the above mentioned Web service objects: Requirement PropertyValue 58 SilkCentral Test Manager API Guide

63 6 SILKCENTRAL WEB SERVICE INTERFACE Web Services Quick Start In fact, one can now simply use the OOP methods of the above objects to consume the Web service. No messy construction of SOAP envelopes needed! Below are excerpts of the code needed to carry out the use case. /** propertyid for requirement risk */ public static final String PROPERTY_RISK = "Risk"; "Reviewed"; "Priority"; "Obsolete"; /** propertyid for requirement reviewed */ public static final String PROPERTY_REVIEWED = /** propertyid for requirement priority */ public static final String PROPERTY_PRIORITY = /** propertyid for requirement obsolete property */ public static final String PROPERTY_OBSOLETE = // Construct Top Level Requirement Requirement toplevelrequirement = new Requirement(); toplevelrequirement.setname("tmreqmgt TopLevelReq"); toplevelrequirement.setdescription("tmreqmgt TopLevel Desc"); PropertyValue proprisk = new PropertyValue("1", PROPERTY_ RISK, null); PropertyValue proppriority = new PropertyValue("1", PROPERTY_PRIORITY, null); PropertyValue[] properties = new PropertyValue[]{propRisk, proppriority}; /* First add requirement skeleton, get its ID * mwebservice is a binding stub, see above getbinding() snippet * msessionid is the stored session ID, see above login() snippet */ String requirementid = mwebservice.updaterequirement(msessionid, toplevelrequirement, null); propvalue); // Now loop through and set properties for(propertyvalue propvalue: properties) { propvalue.setrequirementid(requirementid); mwebservice.updateproperty(msessionid, requirementid, } // Add Child Requirement Requirement childrequirement = new Requirement(); childrequirement.setname("tmreqmgt ChildReq"); childrequirement.setdescription("tmreqmgt ChildLevel Desc"); childrequirement.setparentid(requirementid); proprisk = new PropertyValue("2", PROPERTY_RISK, null); proppriority = new PropertyValue("2", PROPERTY_PRIORITY, null); properties = new PropertyValue[]{propRisk, proppriority}; String childreqid = mwebservice.updaterequirement(msessionid, childrequirement, null); // Now loop through and set properties for(propertyvalue propvalue: properties) { propvalue.setrequirementid(requirementid); mwebservice.updateproperty(msessionid, childreqid, propvalue); } SilkCentral Test Manager API Guide 59

64 6 SILKCENTRAL WEB SERVICE INTERFACE Administration Web Services // Print Results System.out.println("Login Successful with msessionid: " + msessionid); System.out.println("Top Level Requirement ID: " + requirementid); System.out.println("Child Requirement ID: " + childreqid); Getting Fancy: Parsing Excel and Word Files Once basic Web service consumption has been mastered, one can graduate to more fancy techniques such as parsing Excel files for Requirements. Again, toolkits exist to parse Excel files for a variety of programming languages. One such toolkit for Java is Jakarta-POI POI is a Java API to access Microsoft format files. POI can be downloaded and put into a development project's classpath. The POI web site provides numerous examples, a user forum, and so on. Administration Web Services Web Service "sccsystem" This is the root service. It provides an authentication method and simple utility methods. The service s WSDL file is available at /services/sccsystem?wsdl. Long logonuser (String username, String plainpwd) Logs on with a given username and password. The returned session identifier can be used in subsequent calls. It acts as a unique key. The session created with the method expires when it is not used for a period of time. username - The login username plainpwd - The password of the specified username A unique identifier (used as a key) that identifies the session created with the method. 60 SilkCentral Test Manager API Guide

65 6 SILKCENTRAL WEB SERVICE INTERFACE Administration Web Services String converttoreadabletime (long time) Converts a given time (number of milliseconds since midnight, January 1, 1970 UTC) to a human-readable string representation. The returned format is "YYYY-MM-DD HH:MM:SS.MMM". time - The time to convert (specified in milliseconds since midnight, January 1, 1970 UTC) Human-readable string representation of the given time (based on UTC). Long convertfromreadabletime (String time) Converts a given date/time to the number of milliseconds since midnight, January 1, 1970 UTC. time - Date/time to be converted (based on UTC) using the format "YYYY- MM-DD HH:MM:SS.MMM". Number of milliseconds since midnight, January 1, 1970 UTC. AppModule[] getapplicationmodules (long sessionid) Retrieves the list of application modules installed (Test Manager, etc.). sessionid - The unique ID of the actual session An array of all installed application modules. String getrepositoryinstanceid (long sessionid) Retrieves the repository instance ID that was defined when the repository was created. A repository ID is used in ALM URIs to uniquely identify Test Manager requirements and test definitions across multiple Test Manager SilkCentral Test Manager API Guide 61

66 6 SILKCENTRAL WEB SERVICE INTERFACE Administration Web Services repositories (see SilkCentral Administration Module Online Help for detailed information). sessionid - The unique ID of the actual session, returned by logonuser. The repository instance ID. Web Service "sccentities" This service provides access to the two main entities that exist on the SCA level Project and Product. The service s WSDL file is available at /services/sccentities?wsdl. Project[] getprojects (long sessionid) Retrieves all defined projects. sessionid - The unique ID of the actual session An array of all found projects. Project[] getprojectsforuser (long sessionid, int userid, int appmoduleid) Retrieves all defined projects that meet the specified filter criteria. sessionid - The unique ID of the actual session userid - The unique identifier of the user for whom projects are to be returned (or -1 if projects for all users are to be returned). appmoduleid - The unique identifier of the application module that projects are to be returned for (or -1 if projects for all modules are to be returned). An array of all projects found. String[] getprojectnames (long sessionid) Retrieves all project names associated with the given project. 62 SilkCentral Test Manager API Guide

67 6 SILKCENTRAL WEB SERVICE INTERFACE Administration Web Services sessionid - The unique ID of the actual session An array of all project names. String[] getproducts (long sessionid) Retrieves all project names associated with the given project. sessionid - The unique ID of the actual session An array of all project names. String[] getversions (long sessionid, String product) Retrieves all version names associated with the given product. sessionid - The unique ID of the actual session product - The name of the product for which version information is to be obtained. An array of all version names. String[] getbuilds (long sessionid, String product, String version) Retrieves all build names associated with the given product. sessionid - The unique ID of the actual session product - The name of the product to which the given version belongs. version - The version name for which available build information is to be obtained An array of all version names. SilkCentral Test Manager API Guide 63

68 6 SILKCENTRAL WEB SERVICE INTERFACE Administration Web Services String[] getplatforms (long sessionid) Retrieves all platform names associated with the given project. sessionid - The unique ID of the actual session An array of all platform names. String[] getcomponents (long sessionid, String product) Retrieves all component names associated with the given product. sessionid - The unique ID of the actual session product - The name of the product for which component information is to be obtained. An array of all component names. Boolean addbuild (long sessionid, String product, String version, String build, String descr, boolean isactive) Adds a new build to a given version of a product. sessionid - The unique ID of the actual session product - The name of the product the given version belongs to. version - The name of the version to which a new build is to be added build - The name of the build to add. descr - A human-readable description of the added build isactive - If true, the added build is active and available. True if the addition was successful. 64 SilkCentral Test Manager API Guide

69 6 SILKCENTRAL WEB SERVICE INTERFACE Test Manager Web Services Test Manager Web Services Web Service "tmrequirements management" This service provides access to the Requirements unit of SilkCentral Test Manager. The service s WSDL file is available at /services/tmrequirementsmanagement?wsdl. Class Project Holds general information about a project (ID, name, and description). Fields: String ID: The unique project ID. String name: Name of the project. String description: Description of the project. Class PropertyMetaInfo Holds general information about a property. This information includes the type of the value, if the property is required, a default value, and more. Fields: static String[] mtypelabels static int PROPERTY_TYPE_BOOLEAN static int PROPERTY_TYPE_CHAR static int PROPERTY_TYPE_DATE static int PROPERTY_TYPE_DOUBLE static int PROPERTY_TYPE_EDIT static int PROPERTY_TYPE_FLOAT static int PROPERTY_TYPE_LIST static int PROPERTY_TYPE_NORMAL static int PROPERTY_TYPE_NUMBER static int PROPERTY_TYPE_PASSWORD static int PROPERTY_TYPE_SET static int PROPERTY_TYPE_STRING: Available types of a property value. static int PROPERTY_TYPE_TEXT SilkCentral Test Manager API Guide 65

70 6 SILKCENTRAL WEB SERVICE INTERFACE Test Manager Web Services Class PropertyValue Holds general information about a property value (ID, requirementid, value, and type). Fields: String propertyid String requirementid String value int type static int PROPERTY_TYPE_TEXT Class Requirement Holds general information about a requirement (name, description, ID, parent ID, ID of an externally linked requirement, and type ID). Fields: String name String description String ID String parentid String externalid: ID of an externally linked requirement String typeid Class RequirementType Holds general information about a requirement type (ID, name, and description). Fields: String ID: The unique requirement type ID. String name: Name of the requirement type. String description: Description of the requirement type. 66 SilkCentral Test Manager API Guide

71 6 SILKCENTRAL WEB SERVICE INTERFACE Test Manager Web Services public String login (Map loginproperties) This method returns an ID (sessionid) that is required for all calls to this service to identify the user session. loginproperties - Map of keys (names of login properties) and their values. SilkCentral Test Manager requires username and password (property names are case-sensitive) for session login. sessionid as a string. public Project getproject (String sessionid, String projectid) This method returns the project for the provided projectid. sessionid - The unique ID of the actual session projectid - The unique ID of the project Project for the provided project ID. public Project[] getprojects (String sessionid) This method returns all existing and available projects. sessionid - The unique ID of the actual session Array of all existing projects. public Project getcurrentproject (String sessionid) This method returns the active project. sessionid - The unique ID of the actual session SilkCentral Test Manager API Guide 67

72 6 SILKCENTRAL WEB SERVICE INTERFACE Test Manager Web Services The active project. public void setcurrentproject (String sessionid, String projectid) This method sets the project with the provided projectid as the active project. sessionid - The unique ID of the actual session projectid - The unique ID of the project Void. public void lockproject (String sessionid) This method locks the active project. sessionid - The unique ID of the actual session. Void. public void unlockproject (String sessionid) This method unlocks the active project. sessionid - The unique ID of the actual session. Void. public RequirementType[] getrequirementtypes (String sessionid) This method returns all requirement types of the current project. sessionid - The unique ID of the actual session 68 SilkCentral Test Manager API Guide

73 6 SILKCENTRAL WEB SERVICE INTERFACE Test Manager Web Services Null - No other requirement types are supported in SilkCentral Test Manager. public RequirementType getrequirementtype (String sessionid, String requirementtypeid) This method returns the requirement type for the provided requirement type ID. sessionid - The unique ID of the actual session requirementtypeid - ID of the requirement type Null - No other requirement types are supported in SilkCentral Test Manager. public Requirement[] gettoplevelrequirements (String sessionid, String requirementtypeid) This method returns all top level requirements of the provided requirement type and current project. sessionid - The unique ID of the actual session requirementtypeid - ID of the requirement type All top level requirements of the provided requirement type. public Requirement getrequirement (String sessionid, String requirementid) This method returns the requirement for the provided requirement ID. sessionid - The unique ID of the actual session requirementid - The unique ID of the requirement that is to be returned Requirement with the ID that matches the provided requirement ID. public Requirement[] getrequirementchildren (String sessionid, String requirementid) This method returns all child requirements of the provided requirement. SilkCentral Test Manager API Guide 69

74 6 SILKCENTRAL WEB SERVICE INTERFACE Test Manager Web Services sessionid - The unique ID of the actual session. RequirementID - The unique ID of the requirement from which you want to get the children. Requirement children of the requirement with the provided requirement ID. public String updaterequirement (String sessionid, Requirement requirement, String prevsiblingid) This method creates or updates the provided requirement. If the requirement must be created, the new generated requirement ID will be returned. If locking must be performed, the requirement object itself handles it. To create a new requirement, simply supply a Requirement object with an empty string for requirementid. Note Updating the requirement.parentid doesn t reassign a child requirement to a different parent requirement. To assign a child requirement to a new parent requirement, you need to create a new child requirement. The most efficient way to perform this action is to re-set the requirementid to an empty string and define the new parentid before calling updaterequirement. sessionid - The unique ID of the actual session requirement - The Requirement object of the requirement that is to be updated prevsiblingid - (Optional) If supported, the ID of the previous sibling requirement, null or "" if not supported or this is the first sibling. ID of the requirement. public void deleterequirement (String sessionid, String requirementid, boolean recursiv) This method deletes the provided requirement. If the requirement has children, they are only deleted if recursiv is true, otherwise the method fails and the requirement itself is not deleted. sessionid - The unique ID of the actual session 70 SilkCentral Test Manager API Guide

75 6 SILKCENTRAL WEB SERVICE INTERFACE Test Manager Web Services requirementid - The unique ID of the requirement that is to be deleted recursiv - Boolean that determines if existing children are to be deleted Void. public String[] getpropertyids (String sessionid, String requirementtypeid) This method returns the property ID s of all defined properties for the provided requirement type. sessionid - The unique ID of the actual session requirementtypeid - ID of the requirement type String array of all property ID s for the provided requirement type ID. public PropertyMetaInfo getpropertyinfo (String sessionid, String requirementtypeid, String propertyid) This method returns the meta information for a property of a requirement type. sessionid - The unique ID of the actual session requirementtypeid - ID of the requirement type propertyid ID of the property that is to be retrieved Property meta info for a specific property (string ID from getpropertyids() ). public PropertyValue getproperty (String sessionid, String requirementid, String propertyid) This method returns the property value for a provided property ID and requirement. sessionid - The unique ID of the actual session requirementid - ID of the requirement propertyid ID of the property that is to be retrieved SilkCentral Test Manager API Guide 71

76 6 SILKCENTRAL WEB SERVICE INTERFACE Test Manager Web Services Property value of a property of the requirement with the provided property and requirement ID. public void updateproperties (String sessionid, String requirementid, PropertyValue[] properties) This method updates all provided property values. If some sort of locking must be performed, the property objects perform it within themselves. sessionid - The unique ID of the actual session requirementid - ID of the requirement that is to be updated properties - List of properties that are to be updated Void. public String updateproperty (String sessionid, String requirementid, PropertyValue property) This method updates the property value. If locking must be performed, the property objects perform it within themselves. sessionid - The unique ID of the actual session requirementid ID of the requirement that is to be updated property Property that is to be updated Property ID of the updated property. public Test[] getassignedtests (String sessionid, String requirementid) This method returns all assigned tests for the provided requirement. sessionid - The unique ID of the actual session requirementid ID of the requirement from which you want to get the assigned tests 72 SilkCentral Test Manager API Guide

77 6 SILKCENTRAL WEB SERVICE INTERFACE Test Manager Web Services All assigned tests of the requirement that has the provided requirement ID. public void assigntest (String sessionid, String requirementid, String testid) This method assigns the test with the provided test ID to the requirement with the provided requirement ID. sessionid - The unique ID of the actual session requirementid Requirement ID that is to be assigned to the test ID testid Test definition ID that is to be assigned to the requirement public void unassigntest (String sessionid, String requirementid, String testid) This method unassigns the test with the provided test ID from the requirement with the provided requirement ID. sessionid - The unique ID of the actual session requirementid Requirement ID that is to be unassigned from the test ID testid Test definition ID that is to be unassigned from the requirement Void. WebService tmplanning This service provides access to the Test Plan unit of SilkCentral Test Manager. It also enables starting executions and fetching execution results. The service s WSDL file is available at services/tmplanning?wsdl. Class CustomStepProperty Holds general information about a custom step (ID, name, sequence, and value). Fields: int ID String name SilkCentral Test Manager API Guide 73

78 6 SILKCENTRAL WEB SERVICE INTERFACE Test Manager Web Services int sequence String value Class Execution Holds general information about a test execution. Fields: int build: The ID of the build of the application which was testet with this execution. long duration: The total duration of this execution in milliseconds. int errors: The number of errors that occurred with this execution. String[] executioninfos: An array of addtional execution infos as string. String executionserver: The hostname of the execution server. com.segue.scc.webservice.namedentity[] files: An array of files that are saved with this execution. NodeProperty[] properties: An array of properties that where actually set with this execution. int status: The result status of this execution. SuccessMeasure[] successmeasures: The success measures of this execution. long testdefinitionid: The ID of the test definition the result of this execution belongs to. long time: The start time of the execution in milliseconds from 1/1/1970. int warnings: The number of warnings that occurred with this execution. Class ManualTestStep Holds general information about a manual test step. Fields: String description String expectedresult String name CustomStepProperty[] properties int steppos 74 SilkCentral Test Manager API Guide

79 6 SILKCENTRAL WEB SERVICE INTERFACE Test Manager Web Services Class NodeFilter Holds general information about a filter. Fields: String createdby: The user login with which to filter for test planning nodes. String testdefinitiontype: The type of test definitions to filter. int testplanningfilterid: The ID of a saved filter to use for getting children of a node. Class NodeParameter Holds general information about a parameter. Fields: boolean isinherited: True if it is an inherited value. int type: Type of the parameter - to get possible values: NodeParameterValue String value: The current value of the property. Class NodeProperty Holds general information about a node property. Fields: int inheretedfrom: The ID of the node where this value is inherited from. String value: The current value of the property. Class PropertyValue Holds general information about a property value. Fields: String propertytypeid String propertyid String name String value int type SilkCentral Test Manager API Guide 75

80 6 SILKCENTRAL WEB SERVICE INTERFACE Test Manager Web Services Class TestPlanningNode Holds general information about a test planning node. Fields: int kind: A test planning node may either be a test container, a folder, or a test definition. static int KIND_FOLDER static int KIND_FOLDER_LINKED static int KIND_TEST_CONTAINER static int KIND_TEST_CONTAINER_LINKED static int KIND_TEST_DEFINITION_LINKED static int KIND_TEST_DEFINTION PropertyValue[] propertyvalues: All property values which are set for the given node of the test planning tree. long login(map loginproperties) loginproperties - A property (key,value) map of login data, e.g. ("username", "admin"). An ID (session ID) that is required for all calls to this service to identify the user session. void setcurrentproject(long ID, String projectid) ID - The session ID projectid - The ID of the project to be made active in Test Manager. Void. Project[] getprojects(long ID) ID - The session ID 76 SilkCentral Test Manager API Guide

81 6 SILKCENTRAL WEB SERVICE INTERFACE Test Manager Web Services An array of Project objects containing descriptive data for every project in Test Manager. Project getcurrentproject(long ID) Gets the currently active Test Manager project. ID - The session ID A Project object containing data about the active project. Project getproject(long ID, String projectid) ID - The session ID projectid - The ID of the Project to be retrieved. A Project object containing descriptive data of the desired project. public NamedEntity[] gettestcontainers (long ID, int projectid) This call is used to get the test container nodes of the test planning tree for the given project. ID - The session ID projectid - The ID of the project for which the test containers are requested. A named entity array with ID, name, and description of all test containers of the project with the given projectid. SilkCentral Test Manager API Guide 77

82 6 SILKCENTRAL WEB SERVICE INTERFACE Test Manager Web Services public int addmanualtest (long ID, int testcontainerid, String name, String description, ManualTestStep[] steps, NodeParameter[] params) Adds a manual test definition as a child to a test container. Warning This method is currently not working as intended and should NOT be used. Use addnode or addchildnode instead to create manual test definitions. ID - The session ID testcontainerid - The ID of the test container which is to be the parent of the new manual test definition. name - The name of the new manual test definition. description - A description of the new manual test definition. steps - The steps of the new manual test definition. params - The parameter of the new manual test definition. Node ID of the created manual test definition. public CustomStepProperty[] getcustomsteppropertynames (long ID, int projectid) This call is used to get the names of the custom step properties. ID The session ID projectid The ID of the project for your request A list of custom step properties that are defined on the project level. TestPlanningNode getnode(long ID, String nodeid) Retrieves a TestPlanningNode from Test Manager with its PropertyValue child array fully populated. ID - The session ID. nodeid - The internally used ID of the node to be retrieved. 78 SilkCentral Test Manager API Guide

83 6 SILKCENTRAL WEB SERVICE INTERFACE Test Manager Web Services A TestPlanningNode object containing an array of child PropertyValue objects describing the node. public TestPlanningNode[] getchildnodes (long ID, int projectid, int parentnodeid, NodeFilter filter) Gets the child nodes of a defined node in the test planning tree. This includes all the visible child nodes of the visible parent but does not include any non-visible (indirect) child nodes in folders below the visible parent. To get all direct and indirect child nodes this call will need to be used recursively to step down the test planning tree. ID - The session ID. projectid - The ID of the project for your request. parentnodeid - The ID of the parent node for which you request the child nodes. An array with all direct child nodes of the given parent node of the project with the given projectid. String[] getnodetypeids(long ID) ID - The session ID. A String array containing the unique IDs of every type of test planning node currently supported by Test Manager. PropertyValue getproperty(long ID, String nodeid, String propertyid) ID - The session ID. nodeid - The ID of node associated with the property. propertyid - The ID of the property to be retrieved from a given node. The PropertyValue associated with the given unique propertyid and nodeid pair. SilkCentral Test Manager API Guide 79

84 6 SILKCENTRAL WEB SERVICE INTERFACE Test Manager Web Services String[] getpropertyids(long ID) ID - The session ID. An array of the unique property IDs that can be used with the various PropertyValue methods. String[] getpropertyids (long ID, String nodetypeid, String propertytypeid) ID - The session ID. nodetypeid - The ID of the type of node (e.g., "Test Folder", "SilkTest") associated with the property. propertytypeid - The ID of the type of node (e.g., "_node_properties_" for basic node properties such as name and description) associated with the property. The property values available for web service read/write access for the given types of node and property. PropertyMetaInfo getpropertyinfo(long ID, String nodetypeid, String propertyid) ID - The session ID. nodetypeid - The ID of the type of node (e.g., "Test Folder", "SilkTest") associated with the property. propertyid - The ID of property (e.g., "_junit_classpath" for a JUnit classpath property). The meta information of a property value for a given type of node. String[] getpropertytypeids(long ID, String nodetypeid) ID - The session ID. 80 SilkCentral Test Manager API Guide

85 6 SILKCENTRAL WEB SERVICE INTERFACE Test Manager Web Services nodetypeid - The ID of the type of node (e.g., "Test Folder", "SilkTest") associated with the property. The IDs of all propertytypes (e.g., "_sc_" for success conditions) for a given test planning node type. public int addnode (long ID, int parentnodeid, TestPlanningNode node, boolean throwerroronduplicate) This call adds a new child node to the given parent node. ID - The session ID. parentnodeid - The ID of the parent node. node - The node to be added as a child of the given parent node. throwerroronduplicate - If a childnode with the same name already exists an exception will be thrown if throwerroronduplicate=true. If throwerroronduplicate=false, the nodeid of the existing node will be returned The ID of the added child node. public int updatenode (long ID, TestPlanningNode node) This call updates a specific node in the test planning tree. ID- The session ID. node - The node to be updated, utilizing its member PropertyValue objects. True, if the update was successful. False, otherwise. boolean deletenode (long ID, int nodeid) This call deletes a node and its whole subtree. ID- The session ID. nodeid - The ID of the node to be deleted. SilkCentral Test Manager API Guide 81

86 6 SILKCENTRAL WEB SERVICE INTERFACE Test Manager Web Services True if the delete operation was successful, false otherwise. boolean updateproperties(long ID, PropertyValue[] properties) Updates all property values in an array. ID- The session ID. properties - An array of properties to be updated, each specifying its associated node through its nodeid member. True, if the update was successful for the entire array. False, otherwise. boolean updateproperty(long ID, PropertyValue property) Updates all property values associated with a given node. ID- The session ID. property - The property to be updated, specifying its associated node through its nodeid member. True, if the update was successful for the property. False, otherwise. boolean deleteproperty (long ID, PropertyValue property) Deletes a given property from its associated node. ID - The session ID. property - The property to be deleted from its parent node. This PropertyValue object must have its identifying nodeid set as well as its other identifying information. True if the delete operation was successful, false otherwise. 82 SilkCentral Test Manager API Guide

87 6 SILKCENTRAL WEB SERVICE INTERFACE Test Manager Web Services public boolean startexecution (long sessionid, int executiondefid, String version, String build, String execserverhostname, int execserverport) Starts an execution definition with the given ID on the specified execution server with the defined port and stores the results with the specified version and build information. long sessionid - The unique ID of the actual session int executiondefid - An execution definition ID String version - The name of the version that is running on the given execserverhostname String build - The name of the build that is running on the given execserverhostname String execserverhostname - Hostname of the machine where the application is to be tested int execserverport - The port where the execution server can be connected. True if the execution request was successfully queued, false otherwise. boolean uploadtestplan(long ID, int projectid, String content) WebService tmexecution Uploads a test plan to a project. The String content must contain a valid XML Test Manager test plan. ID - The session ID. projectid - The ID of the project to which the test plan elements will be created. content - A String containing the test plan in XML format True, if the upload was successful, false otherwise. This service provides access to the Execution unit of SilkCentral Test Manager. The service s WSDL file is available at /services/tmexecution?wsdl. Class ExecutionNode Represents an object in the execution tree, which is either a folder or an execution definition. Additionally, it can also be the root node in the tree (project SilkCentral Test Manager API Guide 83

88 6 SILKCENTRAL WEB SERVICE INTERFACE Test Manager Web Services node). You should never create your own root node, as the root node is created automatically by SilkCentral Test Manager. Fields: static int KIND_EXECUTIONDEFINITION: Predefined node type for an execution definition in the execution tree. static int KIND_FOLDER: Predefined node type for a folder node in the execution tree. static int KIND_PROJECTROOT: Predefined node type for the root node in the execution tree. public PropertyMetaInfo getpropertyinfo(long sessionid, int kind, String id) Retrieves the PropertyMetaInfo for a property of a node. sessionid - The unique ID of the current session. kind - The property type, which can be one of the following: - 2 = Folder - 3 = ExecutionDefinition id - The property ID. Use the getpropertyids method to get a list of valid IDs for a property. PropertyMetaInfo. public int addnode(long sessionid, ExecutionNode node, int parentid) Adds a node to the execution tree. A node can be either an execution definition or a folder. sessionid - The unique ID of the current session. node - Value object of the node. See Class ExecutionNode. parentid - Parent node ID. Use -1 to add the node to the root folder. Unique node ID. 84 SilkCentral Test Manager API Guide

89 6 SILKCENTRAL WEB SERVICE INTERFACE Test Manager Web Services public ExecutionNode getnode(long sessionid, int nodeid) Gets the node, specified with the nodeid, from the execution tree. sessionid - The unique ID of the current session. nodeid - ID of the node. ExecutionNode (see Class ExecutionNode ). public void updatenode(long sessionid, ExecutionNode node) Updates an existing node in the execution tree. Use case: Get a node -> modify properties -> update node. sessionid - The unique ID of the current session. node - Value object of the node. See Class ExecutionNode. public void deletenode(long sessionid, int nodeid) Deletes a node and all its children from the execution tree. sessionid - The unique ID of the current session. nodeid - ID of the node. public int getcurrentproject(long sessionid) Gets the current project ID. sessionid - The unique ID of the current session. The ID of the currently active project. SilkCentral Test Manager API Guide 85

90 6 SILKCENTRAL WEB SERVICE INTERFACE Test Manager Web Services public void setcurrentproject(long sessionid, int projectid) Sets the current project. sessionid - The unique ID of the current session. projectid - The ID of the project that you want to set as current. public ExecutionNode[] getchildnodes(long sessionid, int parentnodeid) Gets the child nodes of a parent node in the execution tree. sessionid - The unique ID of the current session. parentnodeid - The ID of the parent node for which you want to fetch the child nodes. An array of execution nodes (see Class ExecutionNode ). An ExecutionNode can be a folder or an execution definition. public String[] getpropertyids(long sessionid, int kind) Gets a list of all valid properties of a node in the execution tree. sessionid - The unique ID of the current session. kind - The property type, which can be one of the following: - 2 = Folder - 3 = ExecutionDefinition All valid properties of a node in the execution tree. public ExecutionNode getexecutionrootnode(long sessionid, int projectid) Searches for the root node in the execution tree. If there is no root node a new one is created. 86 SilkCentral Test Manager API Guide

91 6 SILKCENTRAL WEB SERVICE INTERFACE Issue Manager Web Services sessionid - The unique ID of the current session. projectid - The ID of the project of which you want to retrieve the root node. The root node (see Class ExecutionNode ) of the execution tree. Issue Manager Web Services WebService "scim" This service provides access to SilkCentral Issue Manager. The service s WSDL file is available at services/scim?wsdl. public Project[] getprojects (long sessionid) long sessionid - The unique ID of the actual session An array of initialized Issue Manager projects that are available to the user. public String[] getissuetypes (long sessionid, int projectid) long sessionid - The unique ID of the actual session int projectid - The ID of the project Array of the three issue types. public String[] getproducts (long sessionid, int projectid) long sessionid - The unique ID of the actual session int projectid - The ID of the project An array of product names that are configured for the provided Issue Manager project. SilkCentral Test Manager API Guide 87

92 6 SILKCENTRAL WEB SERVICE INTERFACE Issue Manager Web Services public String[] getreleases (long sessionid, int projectid, String product) long sessionid - The unique ID of the actual session String product - The product name int projectid - The ID of the project An array of release names that are configured for the provided product. public String[] getplatforms (long sessionid, int projectid) long sessionid - The unique ID of the actual session int projectid - The ID of the project An array of availble platform names. public String[] getcomponents (long sessionid, int projectid, String product, String issuetype) long sessionid - The unique ID of the actual session int projectid - The ID of the project String product - The product name String issuetype - Name of the issue type An array of available component names that are configured for the provided product, depending on the provided issue type. issuetype BUG and ENHANCEMENT will return all Software components. issuetype DOC- ISSUE will return all Documentation components. 88 SilkCentral Test Manager API Guide

93 6 SILKCENTRAL WEB SERVICE INTERFACE Issue Manager Web Services public String[] getseverities (long sessionid, int projectid, String product,string issuetype) long sessionid - The unique ID of the actual session int projectid - The ID of the project String product - The product name String issuetype - The issue type for which the severities are to be returned An array of values that can be used for entering an issue in the given project when the provided IssueType/Product is selected. public int savenewissue (long sessionid, int projectid, String issuetype, String product, String release, String platform, String component, String severity, String synopsis, String description) long sessionid - The unique ID of the actual session int projectid - The ID of the project String issuetype - The issue type String product - The product name String release - The release name String platform - The platform name String component - The component name String severity - The severity of the new issue String synopsis - A name or short description of the new issue String description - The description of the new issue The issue number of the newly generated issue. SilkCentral Test Manager API Guide 89

94 6 SILKCENTRAL WEB SERVICE INTERFACE Issue Manager Web Services 90 SilkCentral Test Manager API Guide

95 Index B Bugzilla Adding a Bugzilla profile 31 C Creating plug-ins 3 CVS Adding profiles 10 Deleting profiles 13 Editing profiles 12 D Demonstration client Web service 53 I Issue tracking Configuring a Web Service profile 28 Web Service Interface 16 Issue tracking integration Bugzilla 30 Interfaces & Classes 29 Issue tracking profiles Mapping SilkCentral Issue Manager issue states 32 Issue-tracking integration 15 J Java API Interface 29 P S Deploying the API 34 Plug-In API 34 SilkCentral Web Services 51 Administration Web Services 60 Issue Manager Web Services 87 Test Manager Web Services 65 Source control integration Interfaces & Classes 6 Source control plug-ins 5 Source control profiles Adding CVS profiles 10 Adding Subversion profiles 8 Deleting CVS profiles 13 Deleting Subversion profiles 10 Editing CVS profiles 12 Editing Subversion profiles 9 StarTeam 5, 15 Subversion Adding profiles 8 Deleting profiles 10 Editing profiles 9 Label support 8 Tags 8 T Test type integration 41 Configuration XML File 48 Deployment 49 Sample Code 45 Structure of the API 44 Plug-ins Compiling 4 Creating 3 Deploying 4 Distributing 4 R Requirements management integration 33 SilkCentral Test Manager API Guide 91

96 92 SilkCentral Test Manager API Guide

97 SilkCentral Test Manager API Guide 93

98 94 SilkCentral Test Manager API Guide

99 SilkCentral Test Manager API Guide 95

100 96 SilkCentral Test Manager API Guide