PT WS Functions: The Project Tracker Web Service API
Product: / Products this applies to (e.g. CollabNet Enterprise Edition 4.5+)Component: / CEE HELM API
Last review:
Author:
Summary: / One or two sentence summary of the article.
Document status: / Draft: / X
Final:
Reviewed (technical)
Edited:
Published:
Add an X after no more than one of the above states. The states follow our content publishing process.
Next review due: / Thames release
1.1. Overview
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.
1.2. Notation
In the following API descriptions and schemas a few namespace prefixes are used consistently:
· The namespace prefix dalm is used to indicate project specific entries in schemas and in the sample documents (e.g., dalm can refer to the namespace of a vendor of artifact type, attribute or named query or it can also refer to the namespace of project specific attributes.)
· The namespace prefix api refers to the namespace of the Project Tracker API operations, i.e. the namespace of the document root nodes.
1.3. 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.
1.4. 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 (See the samples/wsdl directory)
· 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.
A sample project that demonstrates the use of the API is available from the member downloads section on api.open.collab.net. The sample application 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.
1.5. Web Services
The following is the list of Web Services (and their end-points):
Web Service / Minimum security URL / Extended security URLDispatcher / 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.)
1.6. 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.
WSDL
DispatcherService.wsdl
JavaDoc
Dispatcher.html
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 spec/getArtifactList.xsd.
Sample
spec/getArtifactListSample.xml
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).
Sample
Sample schema: spec/artifactList.xsd.
Sample xml file: spec/artifactListSample.xml
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:
o Text (short, long) are represented as xs:strings
o Date is represented as xs:long. All dates are expressed as long values since January 1, 1970 UTC.
o Single select attributes are represented as xs:strings with an enumeration constraint
o 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.
Schema
Figure 5 getArtifactByID
The schema is at spec/getArtifactByID.xsd.
Sample
spec/getArtifactByIDSample.xml
Description
This document contains the following:
· A list of id tags, each containing the id of an artifact. (id means something like SC1, not the primary key in the database.)
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.
Schema
Figure 6 getNextPage
The schema is located at spec/getNextPage.xsd.
Sample
spec/getNextPageSample.xml
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.
Sample
Sample schema: spec/updateArtifactList.xsd.
Sample document: spec/updateArtifactListSample.xml
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:
· Only attributes specified in the artifact are actually changed
· The modification information for each changed attribute for the artifact as a whole is the current system time.
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.
Sample
Sample schema: spec/createArtifactList.xsd.
Sample document: spec/createArtifactListSample.xml
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 spec/loadMD.xsd.
Sample
spec/loadMDSample.xml
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