This Is The Title Of The Article

1. The Framework Web Service API

Product: Products this applies to (e.g. CollabNet Enterprise Edition 4.5+) Component: CEE HELM API Last review: Sept 21 - 2007 Author: Marcello Sales 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 Framework Web Service API works, code name helm, see api-overview.doc. 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 helm is used to indicate common entries in schemas that are shared on all other schemas;  The namespace prefix domain, project and membership refers to the namespace of the Helm API operations, i.e. the namespace of the document root nodes, specifically for each of the specialized services.

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 5.0 release of CollabNet Enterprise Edition supports previous Web Service Clients that use Java Axis 1.3, and adds the support to a new set of clients for the Helm framework. It uses the same typical pattern to develop the Web Service Client as follows:

 Complete Java Client helm-ws-sample.zip based on the Apache AXIS API (includes the consolidated WSDL interfaces)  If you want to write your own clients, download the detailed interfaces that are defined in the following WSDL and XML Schemas helm-ws-spec.zip. This file includes the following artifacts: o Domain.wsdl o Project.wsdl o Membership.wsdl o exception.wsdl-import

Supporting XML Schemas are also used

o xsd/helm-common-types.xsd o xsd/helm-domain-types.xsd o xsd/helm-membership-types.xsd o xsd/helm-project-types.xsd  Run GenerateAllStubs to generate the stub classes  Update the client test methods to your needs  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 = new (engineConfiguration);

// Now use the service to get a stub which implements the SDI.

URL portAddress = ...; port = service.get(portAddress);

// Make the actual call object = new (...); port.(object); } } where

 is an interface generated by WSDL2Java that extends the javax.xml.rpc.Service,  is the implementation of and  is the actual interface that exposes the API operations (such as in the above example).  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.

The sample project that demonstrates the use of the API is available in the file helm-ws- sample.zip, which includes an Eclipse Project. 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 URL Domain AXIS/ws-sec-min/helm/Domain AXIS/ws-sec-ext/helm/Domain Project AXIS/ws-sec-min/helm/Project AXIS/ws-sec-ext/helm/Project Membership AXIS/ws-sec-min/helm/Membership AXIS/ws-sec-ext/helm/Membership

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 Domain Web Service

The Domain web service is responsible for general administrative operations defined on the helm framework. This is the initial version of this API that focuses on a few administration operations such as the list of projects from a user, user information based on username, full name or email, among others.

JavaDoc

This documentation brings details on the requirements for the calls each of the operations for the Domain Service, as well as specification of each of the internal types used.

 Domain Interface Operations  Complete list of classes

WSDL High-level

Overview of the public methods for the remote API concerning the domain Web Service API. This is intended for SOAP/XML developers who want to develop their own clients following the WSDL specification. Domain.wsdl

1.7. The Project Web Service

The Project web service is responsible for general operations inside a given project. Once connected to this interface you will be able to manage or get information about the project.

JavaDoc

This documentation brings details on the requirements for the calls each of the operations for the Project Service, as well as specification of each of the internal types used.

 Project Interface Operations  Complete list of classes

WSDL High-level

Overview of the public methods for the remote API concerning the project Web Service API. This is intended for SOAP/XML developers who want to develop their own clients following the WSDL specification. Project.wsdl 1.8. The Membership Web Service

The Membership web service is responsible for operations for a given member of the project in the context. The focus of this API is primarily to provide means to automate membership activities such as add, remove, grant and revoke permissions on a project.

JavaDoc

This documentation brings details on the requirements for the calls each of the operations for the Membership Service, as well as specification of each of the internal types used.

 Membership Interface Operations  Complete list of classes

WSDL High-level

Overview of the public methods for the remote API concerning the project Web Service API. This is intended for SOAP/XML developers who want to develop their own clients following the WSDL specification. Membership.wsdl