API Guide. SilkCentral Test Manager

(1)

SilkCentral

®

Test Manager

(2)

Austin, TX 78759-8374 http://www.borland.com

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 © 2004-2008 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)

Introduction

1

Overview . . . . 1

Chapter 1 Creating Plug-Ins

3

Overview . . . . 3 Plug-In Species . . . . 3 Compilation . . . . 4 Deployment . . . . 4 Distribution . . . . 4

Chapter 2 Source Control Integration

5

Overview . . . . 5

Interfaces & Classes . . . . 6

Conventions . . . . 7

Configuring Source Control Plug-ins . . . . 8

Chapter 3 Issue Tracking Integration

15

Overview . . . 15

Web Service Interface. . . 16

Java API Interface. . . 29

Integrating Third-Party Issue Tracking . . . 30

Chapter 4 Requirements Management

Integration

33

Overview . . . 33

Deploying the API . . . 34

Requirements Plug-In API . . . 34

Interfaces for External RMS. . . 40

Chapter 5 Third-Party Test Type

Integration

41

Overview . . . 41

Plug-In Implementation . . . 42

Structure of the API . . . 44

Sample Code . . . 45

Configuration XML File . . . 48

Deployment . . . 49

Chapter 6 SilkCentral Web Service

Interface

51

SilkCentral Web Services . . . 51

Web Services Quick Start . . . 54

Administration Web Services . . . 60

Test Manager Web Services . . . 65

Issue Manager Web Services . . . 87

(4)

(5)

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:

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 requirements-management 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.

Section Page

(6)

(7)

1

Chapt er

1

Creating Plug-Ins

Introduction This chapter explains how to create plug-ins for SilkCentral Test Manager. What you will learn This chapter contains the following sections:

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.

Section Page Overview 3 Plug-In Species 3 Compilation 4 Deployment 4 Distribution 4

(8)

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.

(9)

2

Chapt er

2

Source Control Integration

Introduction This chapter explains how to configure custom source control plug-ins for Test Manager.

What you will learn This chapter contains the following sections:

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”

Overview 5

Interfaces & Classes 6

Conventions 7

(10)

Plug-ins for other source control systems are available from Borland’s download area, in the SilkCentral Test Manager menu (http://www.borland.com/

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

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.

SourceControlProfile 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.

AbstractSourceContro lProfile

This implements convenient methods by using other methods, the

SourceControlProfile specifies. Overriding methods here is mostly because of performance reasons.

VersionControlProfile This adds features like check-in/check-out and label support to the SourceControlProfile.

AbstractVersionContr olProfile

Implements methods that only use other VersionControlProfile methods and that are common for most implementations.

SourceControlProfileD ata

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.

SourceControlExcepti on

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.

SourceControlProfileF actory

(11)

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.

(12)

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

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 http://MyHost/svn/MyApp/trunk you may have a tag http:// 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. Adding Subversion

profiles

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\).

(13)

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:

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

(14)

- 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.

Deleting Subversion profiles

Procedure To remove a Subversion source control profile:

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:

(15)

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.

(16)

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:

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\.)

(17)

- 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.

Deleting CVS profiles Procedure To remove a CVS source control profile:

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.

(18)

(19)

3

Chapt er

3

Issue Tracking Integration

Introduction This chapter explains how to integrate third-party issue-tracking systems into SilkCentral Test Manager.

What you will learn This chapter contains the following sections:

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

• Borland StarTeam® (StarTeam) - see the SilkCentral Administration

Overview 15

Web Service Interface 16 Java API Interface 29 Integrating Third-Party Issue Tracking 30

(20)

• 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.

* @param user * @param password

* @return a sessionID which is used for all other actions to determine the user

*/

public long logonUser(String user, String password) throws IssueTrackingServiceException;

/**

(21)

* @param sessionID

* @return 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.

* @param sessionID * @param issueID * @return */

public IssueField[] getFields(long sessionID, String issueID) throws IssueTrackingServiceException;

/**

* This method is used to synchronize with the current states of the external tracking tool.

* @param sessionID

* @param issueIDs array containing the ids of the requested issues

* @return 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.

* @param sessionID

* @return 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.

(22)

* @param sessionID

* @param issueID (temporary) id of the issue * @param field that has changed

* @return 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.

*

* @param sessionID

* @param id the (temporary) id of the issue

* @param fields array of fields containing the values to store

* @return 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.

* @param sessionID * @param id

* @return 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.

* @param product only infos of issues linked to this product will be returned

* @param 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).

(23)

* @return 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.

* @param name A unique name for the field (ID)

* @param type The GUI type of the field. SelectBox = 1, Checkbox = 2, TextField = 3, TextArea = 4 (handled as TextField in this version)

* @param value The current value of the field. * @param options The options for a field of type SelectBox (type = 1)

* @param label The label for the field shown in the dialog

* @param required Defines whether the user has to enter a value for this field or if it can be left blank * @param length The maximum number of characters that can be entered in a TextField or TextArea

* @param 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="http://scc.segue.com/ issuetracking" xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:apachesoap="http://xml.apache.org/xml-soap" xmlns:impl="http://scc.segue.com/issuetracking" xmlns:intf="http://scc.segue.com/issuetracking" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:wsdlsoap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

(24)

<wsdl:types> <schema targetNamespace="http://scc.segue.com/ issuetracking" xmlns="http://www.w3.org/2001/XMLSchema"> <import namespace="http://schemas.xmlsoap.org/soap/ encoding/"/> <complexType name="IssueField"> <sequence>

(25)

<element name="Id" nillable="true" type="xsd:string"/> <element name="Status" nillable="true"

type="xsd:string"/>

<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>

(26)

<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>

(27)

<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">

(28)

<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>

(29)

</wsdl:portType>

<wsdl:binding name="IssueTrackingSOAPBinding" type="impl:IssueTrackingPortType">

<wsdlsoap:binding style="rpc" transport="http:// schemas.xmlsoap.org/soap/http"/> <wsdl:operation name="getFields"> <wsdlsoap:operation soapAction=""/> <wsdl:input name="getFieldsRequest"> <wsdlsoap:body encodingStyle="http:// schemas.xmlsoap.org/soap/encoding/" namespace="http:// scc.segue.com/issuetracking" use="encoded"/> </wsdl:input> <wsdl:output name="getFieldsResponse"> <wsdlsoap:body encodingStyle="http:// schemas.xmlsoap.org/soap/encoding/" namespace="http:// scc.segue.com/issuetracking" use="encoded"/> </wsdl:output> <wsdl:fault name="IssueTrackingServiceException"> <wsdlsoap:fault encodingStyle="http:// schemas.xmlsoap.org/soap/encoding/" namespace="http:// scc.segue.com/issuetracking" use="encoded"/> </wsdl:fault> </wsdl:operation> <wsdl:operation name="store"> <wsdlsoap:operation soapAction=""/> <wsdl:input name="storeRequest"> <wsdlsoap:body encodingStyle="http:// schemas.xmlsoap.org/soap/encoding/" namespace="http:// scc.segue.com/issuetracking" use="encoded"/> </wsdl:input> <wsdl:output name="storeResponse"> <wsdlsoap:body encodingStyle="http:// schemas.xmlsoap.org/soap/encoding/" namespace="http:// scc.segue.com/issuetracking" use="encoded"/> </wsdl:output> <wsdl:fault name="IssueTrackingServiceException"> <wsdlsoap:fault encodingStyle="http:// schemas.xmlsoap.org/soap/encoding/" namespace="http:// scc.segue.com/issuetracking" use="encoded"/> </wsdl:fault> </wsdl:operation> <wsdl:operation name="logonUser"> <wsdlsoap:operation soapAction=""/> <wsdl:input name="logonUserRequest"> <wsdlsoap:body encodingStyle="http:// schemas.xmlsoap.org/soap/encoding/" namespace="http:// scc.segue.com/issuetracking" use="encoded"/> </wsdl:input> <wsdl:output name="logonUserResponse">

(30)

<wsdlsoap:body encodingStyle="http:// schemas.xmlsoap.org/soap/encoding/" namespace="http:// scc.segue.com/issuetracking" use="encoded"/> </wsdl:output> <wsdl:fault name="IssueTrackingServiceException"> <wsdlsoap:fault encodingStyle="http:// schemas.xmlsoap.org/soap/encoding/" namespace="http:// scc.segue.com/issuetracking" use="encoded"/> </wsdl:fault> </wsdl:operation> <wsdl:operation name="newIssue"> <wsdlsoap:operation soapAction=""/> <wsdl:input name="newIssueRequest"> <wsdlsoap:body encodingStyle="http:// schemas.xmlsoap.org/soap/encoding/" namespace="http:// scc.segue.com/issuetracking" use="encoded"/> </wsdl:input> <wsdl:output name="newIssueResponse"> <wsdlsoap:body encodingStyle="http:// schemas.xmlsoap.org/soap/encoding/" namespace="http:// scc.segue.com/issuetracking" use="encoded"/> </wsdl:output> <wsdl:fault name="IssueTrackingServiceException"> <wsdlsoap:fault encodingStyle="http:// schemas.xmlsoap.org/soap/encoding/" namespace="http:// scc.segue.com/issuetracking" use="encoded"/> </wsdl:fault> </wsdl:operation> <wsdl:operation name="getStates"> <wsdlsoap:operation soapAction=""/> <wsdl:input name="getStatesRequest"> <wsdlsoap:body encodingStyle="http:// schemas.xmlsoap.org/soap/encoding/" namespace="http:// scc.segue.com/issuetracking" use="encoded"/> </wsdl:input> <wsdl:output name="getStatesResponse"> <wsdlsoap:body encodingStyle="http:// schemas.xmlsoap.org/soap/encoding/" namespace="http:// scc.segue.com/issuetracking" use="encoded"/> </wsdl:output> <wsdl:fault name="IssueTrackingServiceException"> <wsdlsoap:fault encodingStyle="http:// schemas.xmlsoap.org/soap/encoding/" namespace="http:// scc.segue.com/issuetracking" use="encoded"/> </wsdl:fault> </wsdl:operation> <wsdl:operation name="getPossibleStates"> <wsdlsoap:operation soapAction=""/> <wsdl:input name="getPossibleStatesRequest">

(31)

<wsdlsoap:body encodingStyle="http:// schemas.xmlsoap.org/soap/encoding/" namespace="http:// scc.segue.com/issuetracking" use="encoded"/> </wsdl:input> <wsdl:output name="getPossibleStatesResponse"> <wsdlsoap:body encodingStyle="http:// schemas.xmlsoap.org/soap/encoding/" namespace="http:// scc.segue.com/issuetracking" use="encoded"/> </wsdl:output> <wsdl:fault name="IssueTrackingServiceException"> <wsdlsoap:fault encodingStyle="http:// schemas.xmlsoap.org/soap/encoding/" namespace="http:// scc.segue.com/issuetracking" use="encoded"/> </wsdl:fault> </wsdl:operation> <wsdl:operation name="fieldChanged"> <wsdlsoap:operation soapAction=""/> <wsdl:input name="fieldChangedRequest"> <wsdlsoap:body encodingStyle="http:// schemas.xmlsoap.org/soap/encoding/" namespace="http:// scc.segue.com/issuetracking" use="encoded"/> </wsdl:input> <wsdl:output name="fieldChangedResponse"> <wsdlsoap:body encodingStyle="http:// schemas.xmlsoap.org/soap/encoding/" namespace="http:// scc.segue.com/issuetracking" use="encoded"/> </wsdl:output> <wsdl:fault name="IssueTrackingServiceException"> <wsdlsoap:fault encodingStyle="http:// schemas.xmlsoap.org/soap/encoding/" namespace="http:// scc.segue.com/issuetracking" use="encoded"/> </wsdl:fault> </wsdl:operation> <wsdl:operation name="getLink"> <wsdlsoap:operation soapAction=""/> <wsdl:input name="getLinkRequest"> <wsdlsoap:body encodingStyle="http:// schemas.xmlsoap.org/soap/encoding/" namespace="http:// scc.segue.com/issuetracking" use="encoded"/> </wsdl:input> <wsdl:output name="getLinkResponse"> <wsdlsoap:body encodingStyle="http:// schemas.xmlsoap.org/soap/encoding/" namespace="http:// scc.segue.com/issuetracking" use="encoded"/> </wsdl:output> <wsdl:fault name="IssueTrackingServiceException"> <wsdlsoap:fault encodingStyle="http:// schemas.xmlsoap.org/soap/encoding/" namespace="http:// scc.segue.com/issuetracking" use="encoded"/>

(32)

</wsdl:fault> </wsdl:operation> <wsdl:operation name="getChanges"> <wsdlsoap:operation soapAction=""/> <wsdl:input name="getChangesRequest"> <wsdlsoap:body encodingStyle="http:// schemas.xmlsoap.org/soap/encoding/" namespace="http:// scc.segue.com/issuetracking" use="encoded"/> </wsdl:input> <wsdl:output name="getChangesResponse"> <wsdlsoap:body encodingStyle="http:// schemas.xmlsoap.org/soap/encoding/" namespace="http:// scc.segue.com/issuetracking" use="encoded"/> </wsdl:output> <wsdl:fault name="IssueTrackingServiceException"> <wsdlsoap:fault encodingStyle="http:// schemas.xmlsoap.org/soap/encoding/" namespace="http:// 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="http:// 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.

(33)

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

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 IssueTrackingProfile (ITP) contains the methods that are required to access the ITS. The ITP accesses the ITS and interacts closely with the Issue.

IssueTrackingData 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).

Issue 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.

(34)

IssueTrackingField 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.

IssueTrackingProfileE xception

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

• Rational® ClearQuest® - see the SilkCentral Administration Module

Online Help

• SilkCentral® Issue Manager 3.3 - see the SilkCentral Administration

• 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 (http://

www.borland.com/downloads/download_silk.html):

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 2.18.3. Modifications to your Bugzilla installation are not required to enable integration. SilkCentral Test

(35)

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., http://bugzillaserver/

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

(36)

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

(37)

4

Chapt er

4

Requirements Management

Integration

Introduction This chapter explains how to integrate Test Manager’s requirements

management functionality with third-party requirements management systems. What you will learn This chapter contains the following sections:

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

Overview 33

Deploying the API 34 Requirements Plug-In API 34 Interfaces for External RMS 40

(38)

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.

methods.

Deploying the API

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.

Packaging 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.

Deployment 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 {

/** *

* @return name of the Requirement Management System this plug-in supports

*/

public String getRMSName(); /**

*

* @return URL of the web-service that provides access to the Requirement Management System

*/

(39)

/** *

* @return 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: http://hostname:port/services/sampleRMSAppService 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.

PropertyProvider Interface

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. * @return 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()}. * @param propertyName

* @return 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.

* @param propertyName a property got by {@link #getProperties()} * @return 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).

(40)

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.

RMService Interface This interface from the com.segue.tm.published.webservice.requirements package provides all methods required by Test Manager to interact with a third-party 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

* @param loginProperties map of keys (names of login properties) and their values

* @return sessionID as String * @throws RMServiceException */

public String login(Map loginProperties) throws RMServiceException; /**

* This method closes the actual user session. * @throws RMServiceException

*/

public void logout() throws RMServiceException; ////////////////////////////////////////////////// // project methods ////////////////////////////////////////////////// /** * * @param sessionId * @param projectId

* @return project for provided project id * @throws RMServiceException

*/

public Project getProject(String sessionId, String projectId) throws RMServiceException;

/** *

* @param sessionId

* @return array of all existing projects * @throws RMServiceException

*/

public Project[] getProjects(String sessionId) throws RMServiceException;

/** *

* @param sessionId

(41)

* @throws RMServiceException */

public Project getCurrentProject(String sessionId) throws RMServiceException;

/**

* changes current active project to project with id equal to provided project id

* @param sessionId * @param projectId

public void setCurrentProject(String sessionId, String projectId) throws RMServiceException;

/**

* locks current active project * @param sessionId

public void lockProject(String sessionId) throws RMServiceException; /**

* unlocks current active project * @param sessionId

public void unlockProject(String sessionId) throws RMServiceException; //////////////////////////////////////////////////

// requirement type methods

////////////////////////////////////////////////// /**

*

* @param sessionId

* @return all requirement types of current active project * @throws RMServiceException

*/

public RequirementType[] getRequirementTypes(String sessionId) throws RMServiceException;

/** *

* @param sessionId * @param requirementTypeId

* @return requirement type with id equal to provided requirement type id

public RequirementType getRequirementType(String sessionId, String requirementTypeId) throws RMServiceException;

////////////////////////////////////////////////// // requirement methods ////////////////////////////////////////////////// /** * * @param sessionId

* @param requirementId if requirementID is null, this call will return the root

(42)

* @return requirement children of requirement with provided requirement id

public Requirement[] getRequirementChildren(String sessionId, String requirementId) throws RMServiceException;

/** *

* @param sessionId * @param requirementId

* @return requirement with id equal to provided requirement id * @throws 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

* @param sessionId

* @param requirement to be saved * @return id of requirement * @throws 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. * @param sessionId * @param requirementId

* @param recursiv boolean, that determins, if existing children shall be deleted too

* @return id of requirement * @throws RMServiceException */

public String deleteRequirement(String sessionId, String requirementId, boolean recursiv) throws RMServiceException; ////////////////////////////////////////////////// // property methods ////////////////////////////////////////////////// /** * * @param sessionId * @param requirementTypeId

* @return string array of all property ids for provided requirement type id

public String[] getPropertyIds(String sessionId, String requirementTypeId) throws RMServiceException;

/** *

* @param sessionId

* @param requirementTypeId * @param propertyId

(43)

* @return property meta info for a specific property (string id from getPropertyIds() )

public PropertyMetaInfo getPropertyInfo(String sessionId, String requirementTypeId, String propertyId) throws RMServiceException; /**

*

* @param sessionId * @param requirementId * @param propertyId

* @return property value of property from requirement with provided property and requirement id

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

* @param sessionId * @param requirementId * @param property

* @return property id of updated property * @throws RMServiceException

*/

public String updateProperty(String sessionId, String requirementId, PropertyValue property) throws RMServiceException;

////////////////////////////////////////////////// // property test ////////////////////////////////////////////////// /** * * @param sessionId * @param requirementId

* @return all assigned tests of requirement with provided requiremnt id

public Test[] getAssignedTests(String sessionId, String requirementId) throws RMServiceException;

/**

* assigns test with provided test id to requirement with provided requirement id * @param sessionId * @param requirementId * @param testId * @throws RMServiceException */

public void assignTest(String sessionId, String requirementId, String testId) throws RMServiceException;

/**

* unassigns test with provided test id from requirement with provided requirement id * @param sessionId * @param requirementId * @param testId * @throws RMServiceException */

(44)

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”