For a general overview of how the Project Tracker Web Service API works, and what it is useful for, see api-overview.pdf. For a detailed explanation of the individual API functions, read on.
Concepts
Web Service Client: An application that calls the Web Service API to perform a task.
WSDL: The Web Service description language.
WSDL file: A WSDL document that describes a particular Web Service
WSDL2Java: A tool provided by Apache Axis (http://ws.apache.org/axis) that generates Java stubs/skeletons from a WSDL file.
Using the Web Service API
The 4.5 release of CollabNet Enterprise Edition supports Web Service Clients that use Java Axis 1.3. A typical pattern to develop the Web Service Client is as follows:
-
Download the WSDL files that define the Web Service API(links to WSDL files are on the CEE API home page).
-
Run WSDL2Java to generate the stub classes
-
Develop the client application
-
Compile and run the client application
Develop the client application
A part of developing to client application is calling the Web Service APIs. The stub classes generated by the WSDL2Java tool make this task relatively simple. A typical usage of the stub classes is as follows:
public class Tester {
public static void main(String [] args) throws Exception {
// Make a service
EngineConfiguration engineConfiguration = ...;
<Service> service = new <ServiceLocator>(engineConfiguration);
// Now use the service to get a stub which implements the SDI.
URL portAddress = ...;
<Remote> port = service.get<Remote>(portAddress);
// Make the actual call
<Type> object = new <Type>(...);
port.<operation>(object);
}
}
where
-
<Service> is an interface generated by WSDL2Java that extends the javax.xml.rpc.Service,
-
<ServiceLocator> is the implementation of <Service> and
-
<Remote> is the actual interface that exposes the API operations (such as <operation> in the above example).
-
<Type> is a Java Bean generated by WSDL2Java to represent XML types defined in the WSDL schema.
-
EngineConfiguration contains the necessary information for Axis to generate the appropriate SOAP headers for authentication/authorization
-
portAddress is the URL of the web service.
You can download a sample project for the Project Tracker Web Servcies. The provides a few useful classes that can be used in the development of client applications:
-
com.collabnet.sample.common.WebServiceClient: Subclasses of this class can use convenience methods to construct an appropriate EngineConfiguration object, to obtain the portAddress of a Web Service.
-
com.collabnet.sample.common.UserIdentifier: This object represents a identifier composed of a CollabNet user's login name, the domain name and the project name the user is connecting to. These pieces of information are used to (a) authenticate the user and (b) authorize the user to perform Web Service calls. The project information is also used to identify the project context of the Web Service operation.
-
com.collabnet.sample.common.Handler: A simple callback handler to provide password information for users.
Applications calling the CollabNet Web Service API can be built with the help of these classes. For an example, see the SystemStatusTest application in the sample project.
Web Services
The following is the list of Web Services (and their end-points):
| Web Service |
Minimum security URL |
Extended security URL |
| Dispatcher |
AXIS/ws-sec-min/ws/Dispatcher |
AXIS/ws-sec-ext/ws/Dispatcher |
| SystemStatus |
AXIS/ws-sec-min/ws/SystemStatus |
AXIS/ws-sec-ext/ws/SystemStatus |
| Metadata |
AXIS/ws-sec-min/tracker/Metadata |
AXIS/ws-sec-ext/tracker/Metadata |
| Attribute |
AXIS/ws-sec-min/tracker/Attribute |
AXIS/ws-sec-ext/tracker/Attribute |
| Attachment |
AXIS/ws-sec-min/tracker/Attachment |
AXIS/ws-sec-ext/tracker/Attachment |
| ArtifactHistory |
AXIS /ws-sec-min/tracker/ArtifactHistory |
AXIS /ws-sec-ext/tracker/ArtifactHistory |
| Query |
AXIS/ws-sec-min/tracker/Query |
AXIS/ws-sec-ext/tracker/Query |
where AXIS is ${SERVER}/axis/services, e.g., http://my.server.com/axis/services. In minimum security mode the user name and password are sent as clear text; in extended security mode the password is encrypted. To use extended security the server needs to be configured (e.g., key and certificate need to be installed) and the client must also have a key/certificate. By default the server is configured to use minimum security. (Note that over SSL (https) the entire message is encrypted, including the username and password.)
The Dispatcher Web Service
The Dispatcher Web Service provides a very flexible interface to CollabNet Enterprise Edition. The Web Service itself is not specific to Project Tracker; however, currently, only Project Tracker related operations have been exposed through this service.
The Dispatcher Web Service consists of a single operation, execute which takes an XML document as input and returns an XML document as output.
Supported Document Types
The requestDocument can be of a few well defined types and for a given requestDocument type the returned document is a specific type. The table below shows the operations (i.e. request Document types) and return values (i.e. response Document types) for the Dispatcher service.
Request document (rootNode) - Response document (rootNode)
getArtifactList - artifactList
getArtifactById - artifactList
updateArtifactList - artifactList
createArtifactList - artifactList
getNextPage - artifactList
loadMetadata - loadMetadataResponse
saveMetadata - loadMetadata
removeMetadata - removeMetadataResponse
The sections below describe the documents in more detail.
Describing artifacts
Project Tracker is a powerful artifact-tracking system which allows users to define custom artifact types. Project Tracker Web Services describes these artifacts using a dynamic XML schema which adapts to fit the specific types of artifacts you are describing.
To get the XSD schema associated with your specific artifact type definitions, call the 'getSchema' method. The content of some of the documents in this API are project specific, but the document root node is always project independent. For example, the root node of the artifactList document is <artifactList> (in the urn:ws.tracker.collabnet.com namespace), but the content is project specific, e.g.:
<artifactList xmlns="urn:ws.tracker.collabnet.com">
<dalm:requirement xmlns:dalm="urn:vendor.com">
...
</dalm:requirement>
</artifactList>
In the above snippet <dalm:requirement> is the XML Name of an artifact type used in the particular project and urn:vendor.com is the namespace URI of the namespace of the artifact type.
Declaring project and domain in the API
The project and the domain the API is executed against is declared in the SOAP header (as part of authentication/authorization). Any operations that may need to perform operations on multiple projects (such as getProjectInfo in SystemStatus) also takes a project argument.
Document API: getArtifactList
The getArtifactList document is used to query Project Tracker for matching artifact instances.
Schema
Figure 1 getArtifactList schema
Figure 2 getArtifactList: Attribute condition detail
The schema document is at getArtifactList.xsd.
Description
The document contains a query definition (either an ad-hoc query definition or a reference to a Project defined query). Note that the adhoc query currently does not support cross-project queries.
Project dependency
Project independent document
Document API: artifactList
The artifactList document is returned to a number of requests (including the getArtifactList request).
Description
The artifactList document contains the following components:
-
A set of artifacts. These artifacts can be of any type (but same type artifacts grouped together).
-
Some paging information. This information is used when requesting subsequent pages of the result.
-
And optionally a failure report. This report contains information about failures the Project Tracker system encountered while processing a request.
Note that this schema is project specific because it depends on the artifact types used by the project.
Notes:
-
There are a number of Project Tracker generic attributes in each artifact: modification, creation information, artifact id, attachments and comments. These are in the urn:ws.tracker.collabnet.com namespace, so tools that only care about such attributes can be authored in a project independent way.
-
Instead of returning all attachments in an artifactList document, only the attachment ids are returned and a separate set of getAttachment calls need to be executed to obtain all attachments associated with an artifact.
-
The tag name and namespace URI of the artifact types and the artifact attributes: These correspond to the XML names and namespace URIs associated with artifact types and attributes.
-
The schema snippet also shows how different attribute types are represented:
-
Text (short, long) are represented as xs:strings
-
Date is represented as xs:long. All dates are expressed as long values since January 1, 1970 UTC.
-
Single select attributes are represented as xs:strings with an enumeration constraint
-
Multi select attributes are represented as xs:strings with an enumeration constraint and they can occur 0 or more times in the document.
-
Artifact types/attributes that are imported from the global artifact/attribute pool have their original namespace.
The following schema snippet provides more details for the failureReport node:
Figure 4 Failure report
Notes:
A failureReport consists of a number of failureReport nodes. Each failureReport contains a reason (an enumeration) and the representation of the artifact that failed.
Project dependency
Schema snippet is project specific as it depends on the xml names and namespaces of artifact types and attributes used in the project.
Document API: getArtifactByID
This request can be used if the id of the artifact is known.
Description
This document contains the following:
Project dependency
Schema snippet is project independent.
Document API: getNextPage
This request can be used to retrieve additional pages of a resultset generated by getArtifactList.
Description
The next page request consists of a pageInfo node. This node is returned in an artifactList document if there are more pages of results. So, a client that wants to get the next page of an artifactList needs to create a getNextPage document and copy the pageInfo node from the artifactList document. Once the last 'page' is retrieved, subsequent call to getNextPage will return an artifactList document with no artifacts. The internals of the pageInfo node is not part of the API because the client does not need to manipulate it.
Project dependency
Schema snippet is not project specific.
Document API: updateArtifactList
The updateArtifactList request is used to update existing Project Tracker artifacts.
Description
The document contains a listing of all artifacts that need to be updated. Note that artifacts of different types can be updated in a single request.
When an artifact specified in the updateArtifactList is updated in Project Tracker, the following assumptions are made:
Note: The maximum number of artifacts that can be updated in a single call is 25.
Project dependency
Schema snippet is project specific.
Document API: createArtifactList
This request is used to create new artifacts in Project Tracker.
Description
The createArtifactList document contains a set of artifacts to create. During creation the following tags are ignored:
- modifiedOn, modifiedBy, lastReadOn: these are only meaningful during update requests
- createOn, attachment: These is only meaningful during a read like operation.
The correlationId element can be used to uniquely mark each new artifact. When the result is returned in the form of an artifactList document, the input artifacts and the returned artifacts can be matched up.
Note: The maximum number of artifacts that can be updated in a single call is 25.
Project dependency
Schema is project specific.
Document API: loadMetadata
This document is sent by an application that installs global artifact types, attributes and domain defined queries, such as a project template archive injector.
Schema
Figure 9 loadMetadata request
Figure 10 Artifact types
Figure 11 Attribute groups within an artifact type
Figure 12 Attributes within an attribute group
Figure 13 Attribute detail: List type attribute
Figure 14 Attribute detail: State attribute
Figure 15 Attribute detail: State attribute - Transition Matrix
Figure 16 Queries
The schema is at loadMD.xsd.
Description
The document contains the following components:
-
List of global artifacts: The definition of global artifacts.
-
List of named queries (DDQs)
-
A number of optional predicate tags. These tags are produced by the saveMetadata operation and these are expected to be used by external validators.
-
hasArtifactTemplates: true if the project has artifact templates.
-
hasReports: true if the project has reports.
-
hasPersonalQueries: true if the project has personal queries
Note that loadMetadata may not successfully execute - e.g., if an attribute definition is incorrect the attribute may not be created. The failure behavior of loadMetadata is the following:
-
Attempt to create all artifact types and attributes. Failure to create an artifact type and/or attribute will be recorded.
-
If there are any failures during attribute creation, then the loadMetadataResponse document will contain the list of all failed artifact types and/or attributes with some information about the cause of the failure.
-
Finally, DDQs are created and failure to create a DDQ is recorded.
-
If there are any failures during DDQ creation then the loadMetadataResponse document will contain the list of failed DDQs with some information about the cause of the failure.
Project dependency
This is a project independent document
Document API: saveMetadata
Returns the metadata for a given project as a loadMetadata document. In other words, the response to saveMetadata can be sent to the system to reload the saved metadata.
Schema
Figure 17 saveMetadata schema
The schema document is at saveMD.xsd.
Description
The saveMetadata operation returns the project tracker metadata contained in the specified project.
Project dependency
This is a project independent document
Document API: removeMetadata
This operation can remove project tracker metadata associated with a partially installed project template. If the project template does not exist then an error condition is returned. If the project template exists but it is fully installed, then the operation does not change the metadata and returns an error code.
Schema
Figure 18 Remove metadata operation
The schema is at removeMD.xsd.
Description
The removeMetadata document simply contains a namespace. All artifact types, attributes and DDQs that are in the namespace are deleted from the system.
Note that for the remove to work the namespace must be in an incomplete state.
Project dependency
This is a project independent document
Document API: getSchema
This request is used to obtain the schema for a given project/domain.
Schema
Figure 19 getSchema operation
Description
The getSchema document requests the schema associated with a particular Project Tracker project.
Document API: schema
This document is returned for a getSchema request.
Schema
Figure 20 getSchema response
Description
The schema document contains a sequence of schemaComponents. Each schemaComponent specifies a schema document as follows:
-
A relativePath that contains suggestions the document on the local system. The relative path is important, because the xs:schema documents (see below) refer to each other through relative paths.
-
An pt:xsdschema document. This document specifies the schema for a given namespace; it may include or import other schema documents (using xs:include and xs:import). If other schema documents are included/imported, then they are either referred to using a relative path or using an absolute URL. If a relative path is used, then the included/imported schema must also be present in the schema document. If an absolute URL is used, then it is assumed that the schema is located at that URL.
ArtifactHistory Web Service
