TARGETPROCESS WEB SERVICES GUIDE

(1)

1

TARGETPROCESS

WEB SERVICES GUIDE

v.2.10

Web Services API / Developers Guide

This document describes Web Services in TargetProcess and provides some usage examples.

(2)

2

TARGETPROCESS DOMAIN MODEL ... 3

PROJECT ... 3

ASSIGNABLE ENTITIES (USER STORY,BUG,TASK) ... 4

TIME ... 4

RELEASE AND ITERATION ... 5

TEST CASES ... 7

WEB SERVICES ... 8

STANDARD COMPLIANCE ... 8

ENTITIES ... 8

Bug Entity ... 8

Bug Web Service Methods ... 10

Examples ... 12

QUERIES (HQL) ... 12

USING TARGETPROCESS WEB SERVICES IN .NET 2.0 ... 14

AUTHENTICATION ... 14

INSTALLING WEB SERVICES ENHANCEMENTS 3.0 ... 14

CREATING PROJECT ... 15

GENERATING WEB SERVICE PROXY USING WSE3.0 ADD-IN (VS2005 ONLY) ... 18

GENERATING WEB SERVICE PROXY USING COMMAND LINE ... 18

USING WEB SERVICES API ... 19

EXAMPLES ... 20

Using HQL to retrieve all assigned user stories ... 20

Add comment to user story ... 20

CONFIGURING INTEGRATED AUTHENTICATION ... 21

Configuring User Active Directory Name in Target Process ... 21

Configuring Security Settings for IIS ... 22

Sample calling web service ... 22

TpServicePolicy class ... 22

USING TARGETPROCESS WEB SERVICES IN JAVA ... 24

CONFIGURING JAVA PROJECT ... 24

Setting Up Project Dependencies ... 24

Enabling Code Generation ... 25

Customizing Code Generation ... 26

USING THE GENERATED API ... 27

Configuring Authentication ... 27

USING TARGETPROCESS WEB SERVICES IN PHP ... 30

RETRIEVING ENTITIES ... 30

CREATING/UPDATING ENTITIES ... 30

APPENDIX A. ENTITY TYPE CONSTANTS ... 32

(3)

3

TargetProcess Domain Model

Domain model understanding is very important for successful Web Services API usage and integration needs.

Project

Project is one of the core entities in TargetProcess. It should have defined Practice and collection of ProjectMembers.

(4)

4

Assignable Entities (User Story, Bug, Task)

Assignable entities are UserStory, Task, Bug and TestPlanRun. They inherited from Assignable class and can be assigned to team member.

Time

(5)

5

Release and Iteration

Project contains collection of Releases and release contains collection of Iterations. Relations are Project → Releases → Iterations.

(6)

6

(7)

7

(8)

8

Web Services

Standard Compliance

TargetProcess web services claim to conform to the WSI Basic Profile version 1.1.

TargetProcess web services use WS-Security specification for authenticating the client using a

UsernameToken security token.

Entities

There are more than 20 available web services in TargetProcess. They provide common operations like:

Create Update Delete GetByID

Pre-defined Retrieve (RetrieveAll, RetrieveAllFor[Entity])

Retrieve using NHibernate HQL queries

Bug Web Service is one of the most complex services, so below is a full description of Bug Service.

Bug Entity

Represents bug or defect (error, flaw, mistake, failure, or fault in a computer program). XML format of Bug Data Transfer Object:

<entity> <BugID>int</BugID> <Name>string</Name> <TagsString>string</TagsString> <Description>string</Description> <StartDate>dateTime</StartDate> <EndDate>dateTime</EndDate> <CreateDate>dateTime</CreateDate> <ModifyDate>dateTime</ModifyDate> <LastCommentDate>dateTime</LastCommentDate> <NumericPriority>float</NumericPriority> <CustomField1>string</CustomField1> <CustomField2>string</CustomField2> <CustomField3>string</CustomField3> <CustomField4>string</CustomField4> <CustomField5>string</CustomField5> <CustomField6>string</CustomField6> <CustomField7>string</CustomField7> <CustomField8>string</CustomField8> <CustomField9>string</CustomField9> <CustomField10>string</CustomField10> <CustomField11>string</CustomField11> <CustomField12>string</CustomField12> <CustomField13>string</CustomField13> <CustomField14>string</CustomField14> <CustomField15>string</CustomField15> <Effort>decimal</Effort> <EffortCompleted>decimal</EffortCompleted> <EffortToDo>decimal</EffortToDo> <TimeSpent>decimal</TimeSpent> <TimeRemain>decimal</TimeRemain> <LastCommentUserID>int</LastCommentUserID> <OwnerID>int</OwnerID> <LastEditorID>int</LastEditorID> <EntityStateID>int</EntityStateID>

(9)

9 © 2004-2008 TargetProcess www.targetprocess.com <PriorityID>int</PriorityID> <ProjectID>int</ProjectID> <IterationID>int</IterationID> <ParentID>int</ParentID> <ReleaseID>int</ReleaseID> <SeverityID>int</SeverityID> <BuildID>int</BuildID> <UserStoryID>int</UserStoryID> <EntityTypeName>string</EntityTypeName> <EntityStateName>string</EntityStateName> <PriorityName>string</PriorityName> <ProjectName>string</ProjectName> <IterationName>string</IterationName> <ParentName>string</ParentName> <ReleaseName>string</ReleaseName> <SeverityName>string</SeverityName> <BuildName>string</BuildName> <UserStoryName>string</UserStoryName> </entity>

Property Name Type Description

BugID int Bug identity

Name string Entity name or title

TagsString string Comma separated string of tags. Used only for TestCase for now

Description string Entity description

StartDate dateTime For example, start date of the iteration. Relevant for Iteration, Project,

Release.

EndDate dateTime For example, end date of the iteration. Relevant for Iteration, Project,

Release.

CreateDate dateTime Date when entity has been created

ModifyDate dateTime Date when entity has been modified

NumericPriority float Calculated priority of entity. Valid for UserStory and Bug for now

CustomField1 string Reserved property for custom field

Effort decimal Total effort of assignable. Can be set if only one ActorEffort for

assignable exists

EffortCompleted decimal Effort spent on assignment. Read-only calculated field

EffortToDo decimal Effort required to complete assignment. Read-only calculated field

TimeSpent decimal Total time spent on assignment. Read-only calculated field

(10)

10

calculated field

OwnerID int Person who added the entity

LastEditorID int Person who edited entity last time

EntityStateID int State of assignable. For example, User Story may be in Open or Done

state

PriorityID int Priority of assignable. For example, User Story may have Must Have or

Nice To Have priority

ProjectID int Assignable should belong to Project

IterationID int Assignable may be assigned to Iteration or may be in Backlog (Iteration is

not defined in this case)

ParentID int Used for Task only (Task parent is a User Story)

ReleaseID int Assignable may be assigned to Release or may be in project Backlog

(Release is not defined in this case)

SeverityID int Severity (measure of injuriousness) of the bug. For example, Blocking,

Critical, Small

BuildID int Build in which bug has been found. Optional.

UserStoryID int Bug may be associated with user story. Optional

EntityTypeName string Gets or sets the Entity Type Name. Type of the entity

EntityStateName string Gets or sets the Entity State Name. State of assignable. For example,

User Story may be in Open or Done state

PriorityName string Gets or sets the Priority Name. Priority of assignable. For example, User

Story may have Must Have or Nice To Have priority

ProjectName string Gets or sets the Project Name. Assignable should belong to Project

IterationName string Gets or sets the Iteration Name. Assignable may be assigned to Iteration

or may be in Backlog (Iteration is not defined in this case)

ParentName string Gets or sets the Parent Name. Used for Task only (Task parent is a User

Story)

ReleaseName string Gets or sets the Release Name. Assignable may be assigned to Release or

may be in project Backlog (Release is not defined in this case)

SeverityName string Gets or sets the Severity Name. Severity (measure of injuriousness) of

the bug. For example, Blocking, Critical, Small

BuildName string Gets or sets the Build Name. Build in which bug has been found. Optional

UserStoryName string Gets or sets the User Story Name. Bug may be associated with user story.

Optional.

Bug Web Service Methods

Name Description

AddAttachmentToBug Adds the attachment to the specified Bug. Note: The filename is

the name of existing file which should be uploaded to upload directory using FileService or manually.

AddBugWithAttachment Adds the bug with attachment.

(11)

11

AddRequestGeneralToBug Adds Request General to the specified Bug

AddRevisionAssignableToBug Adds Revision Assignable to the specified Bug

AddTeamToBug Adds Team to the specified Bug

AssignUser Assigns the user by id to the specified Bug.

AssignUserAsActor Assigns the user by id as actor to the specified Bug.

AssignUserByEmailOrLogin Assigns the user by email or login to the specified Bug.

AssignUserByEmailOrLoginAsActor Assigns the user by email or login as actor to the specified Bug.

ChangeEffort Changes the effort of specified Bug entity.

ChangeState Changes state of Bug entity to the specified state.

Create Creates the specified entity.

Delete Deletes the entity with the specified id.

GetByID Gets the entity by ID.

GetIDs Retrieves the IDs of entities by specified HQL.

GetPriorities Loads available priorities for Bug.

GetSeverities Gets the severities.

RemoveAttachmentFromBug Removes Attachment from specified Bug.

RemoveCommentFromBug Removes Comment from specified Bug.

RemoveRequestGeneralFromBug Removes Request General from specified Bug.

RemoveRevisionAssignableFromBug Removes Revision Assignable from specified Bug.

RemoveTeamFromBug Removes Team from specified Bug.

Retrieve Retrieves the list if entities by specified HQL.

RetrieveActorEffortsForBug Loads the child collection of Actor Effort entities for specified

Bug.

RetrieveAll Retrieves all.

RetrieveAllForBuild Loads Bug entities by specified Build.

RetrieveAllForEntityState Loads Bug entities by specified Entity State.

RetrieveAllForIteration Loads Bug entities by specified Iteration.

RetrieveAllForLastCommentUser Loads Bug entities by specified General User.

RetrieveAllForOwner Loads Bug entities by specified General User.

RetrieveAllForPriority Loads Bug entities by specified Priority.

RetrieveAllForProject Loads Bug entities by specified Project.

RetrieveAllForRelease Loads Bug entities by specified Release.

RetrieveAllForSeverity Loads Bug entities by specified Severity.

RetrieveAllForUserStory Loads Bug entities by specified User Story.

RetrieveAttachedRequestsForBug Loads the child collection of Request General entities for

specified Bug.

RetrieveAttachmentsForBug Loads the child collection of Attachment entities for specified

Bug.

RetrieveCommentsForBug Loads the child collection of Comment entities for specified Bug.

RetrieveCount Retrieves the count.

RetrieveOpenForMe Loads open Bug entities for the currently logged in user.

RetrieveOpenForUser Loads open Bug entities for specified user

(12)

12

RetrieveRevisionAssignablesForBug Loads the child collection of Revision Assignable entities for

specified Bug.

RetrieveTeamsForBug Loads the child collection of Team entities for specified Bug.

Update Updates the specified entity.

Examples

Retrieve bug by id

BugServiceWse bugService = ... BugDTO bug = bugService.GetByID(97);

Console.WriteLine(bug.Name);

Add new bug into TargetProcess BugServiceWse bugService = ...

BugDTO bug = new BugDTO(); bug.Name = "New bug";

bug.CreateDate = DateTime.Today; bug.Description = "Bug Description"; bug.ProjectID = 1;

int bugId = bugService.Create(bug);

Console.WriteLine(bugId);

Delete bug from TargetProcess BugServiceWse bugService = ... bugService.Delete(bugId);

Update bug

BugServiceWse bugService = ...

BugDTO bug = bugService.GetByID(bugId); bug.Name = "Updated bug";

bugService.Update(bug);

Queries (HQL)

It is possible to retrieve entities from TargetProcess using HQL syntax. HQL is Hibernate Query Language which is resembles SQL. HQL is a very flexible language and you may create complex queries to retrieve data from TargetProcess.

Each TargetProcess web service has Retrieve method that accepts HQL query and array of parameters. For example, the following query returns user with login “admin”:

UserServiceWse userService = ...

UserDTO user = userService.Retrieve("from User as user where user.Login = ?", newobject[] { "admin" })[0];

(13)

13

UserStoryServiceWse service = ...

UserStoryDTO[] list = service.Retrieve(

"from UserStory as story where story.Project.DeleteDate is null " +

"and ? in (select team.User.Login from story.Teams as team " +

(14)

14

Using TargetProcess Web Services in

.NET 2.0

IMPORTANT: TargetProcess Web Services use Web Services Enhancement 3.0, so it is required to have them installed.

Authentication

TargetProcess web services based on WSE 3.0 (Microsoft Web Service Enhancements). It limits interoperability and support of WS-Security 1.0 or 1.1 required to use TargetProcess web services. Also note that UsernameOverTransport security assertion is used.

Check

Generating Web Service Proxy using command line

You should have WSE 3.0 installed. Please find the steps of generating below

1. Open command line window and navigate to “WseWsdl3.exe” (usually it is in [C:\Program Files\Microsoft WSE\v3.0\Tools\WseWsdl3.exe])

2. Execute the following command

WseWsdl3 /type:webClient http://[your tp path]/Services/UserService.asmx?wsdl

Using Web Services API section to see how to authenticate in .NET 2.0.

Installing Web Services Enhancements 3.0

Download WSE 3 from http://www.microsoft.com/downloads/details.aspx?familyid=018a09fd-3a74-43c5-8ec1-8d789091255d&displaylang=en

(15)

15

Creating Project

We will create sample console application that will retrieve all users from TargetProcess. Open Visual Studio, click New Project and select Console Application.

(16)

16

Next step is to add reference to WSE 3.0. Right click on project References and find

(17)

17

(18)

18

Generating Web Service Proxy using WSE 3.0 add-in (VS

2005 only)

Right click on References and select Add Web Reference option. Type path to web service

http://[your_tp_path]/Services/UserService.asmx and click Add Reference button. Visual Studio will generate proxy classes and from that moment you may access UserService.

Generating Web Service Proxy using command line

You should have WSE 3.0 installed. Please find the steps of generating below

3. Open command line window and navigate to “WseWsdl3.exe” (usually it is in [C:\Program Files\Microsoft WSE\v3.0\Tools\WseWsdl3.exe])

4. Execute the following command

(19)

19

Using Web Services API

The most complex part with TP services is authentication. It is recommended to create TpPolicy class and use it for authentication. Just copy the complete class code below.

using Microsoft.Web.Services3; using Microsoft.Web.Services3.Design; using Microsoft.Web.Services3.Security; using Microsoft.Web.Services3.Security.Tokens; namespace TpIntegration {

public class TpPolicy : Policy

{

public TpPolicy() {

Assertions.Add(newUsernameOverTransportAssertion()); }

public static UsernameToken GetUsernameToken(string username, string password, PasswordOption

passwordOption) {

UsernameToken token = new UsernameToken(username, password, passwordOption); ISecurityTokenManager securityTokenManager =

SecurityTokenManager.GetSecurityTokenManagerByTokenType(WSTrust.TokenTypes.UsernameToken); securityTokenManager.CacheSecurityToken(token);

return token; }

public static void ApplyAutheticationTicket(WebServicesClientProtocol protocol, string userName, string

password) {

UsernameToken token = GetUsernameToken(userName, password, PasswordOption.SendPlainText); protocol.SetClientCredential(token);

protocol.SetPolicy(new TpPolicy()); }

} }

Now we are ready to investigate power of TargetProcess web services API. using System;

using TpIntegration.UserService;

namespace TpIntegration {

internalclass Program

{

private static void Main(string[] args) {

// Create web service and path authentication.

// "admin" / "admin" is login/password of user

// that has access to TargetProcess

UserServiceWse userService = new UserServiceWse();

TpPolicy.ApplyAutheticationTicket(userService, "admin", "admin"); // Retrieve all users in TargetProcess

UserDTO[] users = userService.RetrieveAll(); // Make something interesting with users list.

// For example, just show users

foreach (UserDTO user in users) {

Console.WriteLine(user.FirstName + " " + user.LastName); }

} } }

As you see, the code is simple: Instantiate web service

Path authentication using TpPolicy helper class

Get all users from TargetProcess as an array of UserDTO (data-transfer object which represents User

(20)

20

Examples

Using HQL to retrieve all assigned user stories

string userName = "admin";

string userPassword = "admin";

UserStoryServiceWse userStoryService = newUserStoryServiceWse();

TpServicePolicy.ApplyAutheticationTicket(userStoryService, userName, userPassword);

string hqlAssignedUserStoryQuery =

@"from UserStory as us where us.UserStoryID in

(select team.Assignable.AssignableID from Team as team where team.User.UserID = ?

and team.Actor = us.EntityState.Actor

and team.Assignable.AssignableID = us.UserStoryID)";

UserStoryDTO[] stories = userStoryService.Retrieve(hqlAssignedUserStoryQuery, newobject[] {users[0].UserID});

Add comment to user story

UserStoryServiceWse service = new UserStoryServiceWse();

TpServicePolicy.ApplyAutheticationTicket(service, "admin", "admin");

CommentDTO comment = newCommentDTO(); comment.Description = "New Comment";

(21)

21

Configuring Integrated Authentication

(22)

22

Configuring Security Settings for IIS

Sample calling web service

AuthenticationServiceWse wse = new AuthenticationServiceWse();

wse.Credentials = new NetworkCredential("UserName", "Password", "Domain"); TpServicePolicy.ApplyAutheticationTicket(wse, "Domain\\UserName", "Password"); Console.WriteLine(wse.Authenticate());

TpServicePolicy class

public class TpServicePolicy : Policy {

public TpServicePolicy() : base() {

Assertions.Add(new UsernameOverTransportAssertion()); Assertions.Add(new RequireActionHeaderAssertion()); }

public static UsernameToken GetUsernameToken(string username, string password, PasswordOption passwordOption) {

UsernameToken token = new UsernameToken(username, password, passwordOption); ISecurityTokenManager securityTokenManager = SecurityTokenManager.

(23)

public static void ApplyAutheticationTicket(WebServicesClientProtocol protocol, string userName, string password)

{

UsernameToken token = GetUsernameToken(userName, password, PasswordOption.SendPlainText);

protocol.SetClientCredential(token); protocol.SetPolicy(new TpServicePolicy()); }

(24)

24

Using TargetProcess Web Services in

Java

One of the design goals of the web services specification was interoperability, so it was designed to be neutral to a platform, language or framework. Java is not an exception, and there are several options for working with web services in Java projects. You can choose from many frameworks, tools and vendors, and we will not force you to any particular solution, but for this quick start guide we adopted XFire web services framework (http://xfire.codehaus.org/) because in our opinion it is simple, intuitive and developer friendly. Regardless of framework of your choice the procedure should be the same:

• Configure code generation so that web services stubs and data transfer objects are generated for you from WSDL files by the machine and you don’t need to code it by hand.

• Configure security settings in web services client following WS-Security standard so that TargetProcess can authenticate client requests.

• Make proper use of the generated API to call TargetProcess remotely and implement use cases of your interest.

In this mini guide we will describe these steps in details using our preferred tools and frameworks. Let’s begin with prerequisites:

JDK 5 (http://java.sun.com/javase/downloads/index.jsp) XFire 1.2 (http://xfire.codehaus.org/)

Maven 2 (http://maven.apache.org/)

TargetProcess 2 (http://www.targetprocess.com/) web services

There is no reason to use older JDK releases, unless you support a legacy project, so we recommend using JDK 5 or earlier. It got quite stable and mature with lots of useful enhancements in language we will make use of. As we stated earlier, we prefer XFire framework for its simplicity and efficiency. However you probably should take a look at CeltiXFire (http://incubator.apache.org/cxf/) framework which is successor of XFire.

Maven is an excellent tool for build management with lot of functionality available in plugins, we will make use of. You will also need TargetProcess WSDL files, which you can download to your local file system, or you can refer them online if your tools support it. XFire supports both options. You can browse WSDL files at http://[your_tp_path]/Services/. To download a particular WSDL file, point your browser to http:// [your_tp_path]/Services/[service_name].asmx?WSDL, for instance bugs web service on local host can be found at http://localhost/tp/Services/BugService.asmx?WSDL.

Configuring Java Project

Setting Up Project Dependencies

You will need to add XFire libraries to your project. Let’s do it by example, add the following fragment in your POM file:

(25)

25 © 2004-2008 TargetProcess www.targetprocess.com <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"> ... <dependencies> <dependency>

<groupId>org.codehaus.xfire</groupId> <artifactId>xfire-java5</artifactId> <version>${xfire.version}</version> </dependency>

<groupId>org.codehaus.xfire</groupId> <artifactId>xfire-annotations</artifactId> <version>${xfire.version}</version> </dependency>

<groupId>org.codehaus.xfire</groupId> <artifactId>xfire-jaxb2</artifactId> <version>${xfire.version}</version> </dependency>

<groupId>org.codehaus.xfire</groupId> <artifactId>xfire-ws-security</artifactId> <version>${xfire.version}</version> </dependency>

...

As you see, we included xfire-java5, xfire-annotiations, xfire-jaxb2 and xfire-ws-security dependencies to the project. These dependencies also include additional, transitive dependencies, such as xfire-core,

jaxb-api, jaxb-impl, jaxb-xjc, wsdl4j, wss4j and others. We specified XFire version in property

xfire.version, whose definition you will find later.

Enabling Code Generation

Now we need to configure code generation from WSDL files. XFire provides Ant task WsGenTask for these purposes, which we need to configure by means of AntRun Maven plugin. In the following example

AntRun plugin executes WsGenTask task twice to generate code from WSDL files ProjectService.wsdl and

ReleaseService.wsdl: <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"> ... <build> ... <plugins> ... <plugin>

<groupId>org.apache.maven.plugins</groupId> <artifactId>maven-antrun-plugin</artifactId> <executions>

<phase>generate-sources</phase> <configuration> <tasks> <delete dir="${xfire.src.dir}"/> <taskdef name="wsgen" classname="org.codehaus.xfire.gen.WsGenTask" classpathref="maven.compile.classpath"/> <wsgen outputDirectory="${xfire.src.dir}" wsdl="${basedir}/src/main/wsdl/ProjectService.wsdl" package="com.targetprocess.integration.project" externalBindings="${basedir}/src/main/jaxb/bindings-project.xml" generateServerStubs="false" overwrite="true"/>

(26)

26 © 2004-2008 TargetProcess www.targetprocess.com <wsgen outputDirectory="${xfire.src.dir}" wsdl="${basedir}/src/main/wsdl/ReleaseService.wsdl" package="com.targetprocess.integration.release" externalBindings="${basedir}/src/main/jaxb/bindings-release.xml" generateServerStubs="false" overwrite="true"/> ... add more WSDL files here ... </tasks>

<sourceRoot>${xfire.src.dir}</sourceRoot> </configuration>

<goals>

</execution> </executions> <dependencies> <dependency>

<groupId>org.codehaus.xfire</groupId> <artifactId>xfire-generator</artifactId> <version>${xfire.version}</version> </dependency>

</dependencies> </plugin>

You may add more WSDL files to the generation, but be aware that it is better to generate classes into different packages, otherwise conflicts can happen. You must configure these properties if the

WsGenTask task for successful generation:

Name Description

outputDirectory Specifies directory where the generated sources will be placed.

wsdl Specifies where WSDL file is located. This can be local file system path or URL of

an online WSDL resource.

package Specifies package name for the generated classes. Please use different packages

for different WSDL files, otherwise conflicts can happen.

externalBindings Specifies path to JAXB XSD-to-Java compiler configuration file. In this file you can

customize code generation options, such us provide specific package name, common super type, etc. There must be one compiler configuration file for every WSDL file.

To eliminate configuration duplicates, we extracted common settings to the global properties of POM file:

<xfire.version>1.2.6</xfire.version>

<xfire.src.dir>${basedir}/target/generated-sources/xfire</xfire.src.dir> </properties>

There may be newer XFire version when you read this documentation.

You may add more properties, such as TargetProcess URL to find online WSDL files, etc.

Customizing Code Generation

In this example we use JAXB 2 bindings to serialize Java classes as XML messages. JAXB provides compiler, which given an XML schema (XSD) file will generate a set of Java classes representing types of this XML schema. This is what WsGenTask task described above does: given a WSDL file it extracts XML schema portion from it and conveys it to the JAXB compiler, then JAXB compiler generates Java classes used as data-transfer objects.

(27)

27

By default JAXB compiler chooses package name specified in the WSDL file, which is com.targetprocess in case of TargetProcess web services. However this causes conflicts when sources from multiple WSDL files are generated in the same package. To avoid conflicts compiler needs to be customized using an external bindings configuration file. Path to this file should be specified in the externalBindings property of the

WsGenTask task. Here is an example content of a bindings customization file:

<jxb:bindings version="1.0"

xmlns:xs="http://www.w3.org/2001/XMLSchema"

xmlns:jxb="http://java.sun.com/xml/ns/jaxb">

<jxb:bindings schemaLocation="../wsdl/ProjectService.wsdl#types?schema1" node="/xs:schema"> <jxb:schemaBindings> <jxb:package name="com.targetprocess.integration.project"/> ... </jxb:schemaBindings> ... </jxb:bindings> </jxb:bindings>

In this example we customized package name for the generated classes. You can customize other options.

For more information on customizing JAXB bindings see Sun Java Web Services tutorial

http://java.sun.com/webservices/docs/2.0/tutorial/doc/JAXBUsing4.html.

Using the Generated API

XFire makes using web services straightforward, however some initial preparation is required. TargetProcess follows WS-Security specification for authenticating user requests, so clients have to provide proper credentials in order for TargetProcess to validate incoming messages and authenticate clients.

Configuring Authentication

XFire integrates with WSS4J (http://ws.apache.org/wss4j/) which is a Java library implementing the WS-Security standard. It can be used to provide user credentials, sign and verify, encrypt and decrypt SOAP messages. For information on how to enable WS-Security support in XFire see

http://xfire.codehaus.org/WS-Security. Here we provide a brief excerpt from this page with only relevant information.

To enable WS-Security support you must add two handlers to the client’s outgoing handler chain:

org.codehaus.xfire.util.dom.DOMOutHandler — Converts from StAX to DOM format for WS-Security.

org.codehaus.xfire.security.wss4j.WSS4JOutHandler — Performs the WS-Security related functions. Here is code fragment which demonstrates programmatic XFire client configuration example:

// Classes from this example are imported from the following packages.

import org.codehaus.xfire.client.Client; import org.codehaus.xfire.util.dom.DOMOutHandler; import org.codehaus.xfire.security.wss4j.WSS4JOutHandler; import org.apache.ws.security.handler.WSHandlerConstants; import org.apache.ws.security.WSConstants; ...

// URL of the TargetProcess bugs web service.

(28)

28

// Instantiate web service stub.

BugServiceClient bugServiceClient = new BugServiceClient();

BugServiceSoap bugService = bugServiceClient.getBugServiceSoap(url); // Begin configuring web service client.

Client client = Client.getInstance(bugService);

// Add first outgoing handler which converts from StAX to DOM format for WS-Security. client.addOutHandler(newDOMOutHandler());

// Configure second outgoing handler which performs WS-Security related activities.

Properties properties = new Properties();

// We will transmit user name and password to the web service,

properties.setProperty(WSHandlerConstants.ACTION, WSHandlerConstants.USERNAME_TOKEN); // Here we specify actual user name.

properties.setProperty(WSHandlerConstants.USER, "admin"); // We will transmit password as is, without hashing it.

properties.setProperty(WSHandlerConstants.PASSWORD_TYPE, WSConstants.PW_TEXT);

// Specify name of the handler class which will be invoken when remote web service is called. // This handler will update outgoing SOAP message with WS-Security header,

// specifying user name and password.

properties.setProperty(WSHandlerConstants.PW_CALLBACK_CLASS, PasswordHandler.class.getName()); // Add second outgoing handler which performs WS-Security related activities.

client.addOutHandler(newWSS4JOutHandler(properties)); ...

// Call web service!

BugDTO bug = bugService.getByID(1);

Here is an example of PasswordHandler class used in the code fragment above: package com.targetprocess.integration; import org.apache.ws.security.WSPasswordCallback; import javax.security.auth.callback.Callback; import javax.security.auth.callback.CallbackHandler; import javax.security.auth.callback.UnsupportedCallbackException; import java.io.IOException; import java.util.HashMap; import java.util.Map;

public class PasswordHandler implements CallbackHandler { /**

* Simple database which maps user names to passwords. * It is a good idea to externalize this data.

*/

private final Map<String, String> passwords = new HashMap<String, String>(); public PasswordHandler() {

this.passwords.put("admin", "admin"); // Add user name/password pair. }

public void handle(Callback[] callbacks) throws IOException, UnsupportedCallbackException { WSPasswordCallback callback = (WSPasswordCallback) callbacks[0];

callback.setPassword(this.passwords.get(callback.getIdentifer())); }

}

You can troubleshoot authentication issues by monitoring HTTP traffic between your client and

TargetProcess web services. Every SOAP message must contain WS-Security headers, as in the following example: <soap:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Header> <wsse:Security soap:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"> <wsse:UsernameToken wsu:Id="UsernameToken-6722010" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"> <wsse:Username xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"> user name

(29)

29 © 2004-2008 TargetProcess www.targetprocess.com </wsse:Username> <wsse:Password xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText"> password </wsse:Password> </wsse:UsernameToken> </wsse:Security> </soap:Header> <soap:Body> <ns1:Create xmlns:ns1="http://targetprocess.com"> <ns1:entity>

<ns1:ID xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/> <ns1:ProjectID xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/> <ns1:Name>...</ns1:Name>

... payload goes here ... </ns1:entity>

</ns1:Create> </soap:Body> </soap:Envelope>

(30)

30

Using TargetProcess Web Services in

PHP

NuSOAP - Web Services Toolkit for PHP is used to be able to connect to TP Web Services. Several changes were made in NuSOAP sources, so use for your development version which comes with the examples (NuSOAP library and required TargetProcess PHP library are in [lib] directory).

Retrieving entities

<?php

require_once('lib/nusoap.php'); require_once('tp.php'); //Initialize security header

$securityHeader = new SecurityHeader; //Initialize Soap Client

$client = new soapclient('http://localhost/TargetProcess/Services/ProjectService.asmx?wsdl','wsdl'); $client->soap_defencoding = "UTF-8";

$err = $client->getError(); if ($err)

echo '<h2>Constructor error</h2><pre>' . $err . '</pre>'; //Append Tp Policy (must be applied before every soap call)

$securityHeader->AppendTpPolicy($client, 'RetrieveAll', 'admin', 'admin'); $result = $client->call('RetrieveAll');

//Output results or error if ($client->fault) {

echo '<h2>Fault (Expect - The request contains an invalid SOAP body)</h2><pre>'; print_r($result); echo '</pre>'; } else { $err = $client->getError(); if ($err) {

echo '<h2>Error</h2><pre>' . $err . '</pre>'; } else { echo '<h2>Result</h2><pre>'; print_r($result); echo '</pre>'; } }

//Show Debug Information

echo '<h2>Request</h2><pre>' . htmlspecialchars($client->request, ENT_QUOTES) . '</pre>'; echo '<h2>Response</h2><pre>' . htmlspecialchars($client->response, ENT_QUOTES) . '</pre>'; ?>

Creating/Updating Entities

<?php

require_once('lib/nusoap.php'); require_once('lib/tp.php'); //Initialize security header

(31)

31

//Initialize Soap Client

$client = new soapclient('http://localhost/TargetProcess/Services/ProjectService.asmx?wsdl','wsdl'); $client->soap_defencoding = "UTF-8";

$err = $client->getError(); if ($err)

echo '<h2>Constructor error</h2><pre>' . $err . '</pre>'; //Append Tp Policy (must be applied before every soap call) $securityHeader->AppendTpPolicy($client, 'Create', 'admin', 'admin'); $projectName = 'My Prj : '.$securityHeader->getGuid();

//Fill out project DTO. Create the project with unique name. $params = array(

//Please note the parameters names should be the same as declared in wsdl 'entity' => array

(

"Name"=>$projectName ));

$result = $client->call('Create', $params); //Output results or error

if ($client->fault) {

echo '<h2>Fault (Expect - The request contains an invalid SOAP body)</h2><pre>'; print_r($result); echo '</pre>'; } else { $err = $client->getError(); if ($err)

echo '<h2>Error</h2><pre>' . $err . '</pre>'; else

echo '<h2>Result</h2><pre>'; print_r($result); echo '</pre>'; }

//Show Debug Information

echo '<h2>Request</h2><pre>' . htmlspecialchars($client->request, ENT_QUOTES) . '</pre>'; echo '<h2>Response</h2><pre>' . htmlspecialchars($client->response, ENT_QUOTES) . '</pre>'; ?>

(32)

32

Appendix A. Entity Type Constants

Entity type constants are defined in code as follows: public readonly static int PROJECT_TYPE_ID = 1;

public readonly static int RELEASE_TYPE_ID = 2;

public readonly static int ITERATION_TYPE_ID = 3;

public readonly static int USERSTORY_TYPE_ID = 4;

public readonly static int TASK_TYPE_ID = 5;

public readonly static int USER_TYPE_ID = 6;

public readonly static int TIME_TYPE_ID = 7;

public readonly static int BUG_TYPE_ID = 8;

public readonly static int FEATURE_TYPE_ID = 9;

public readonly static int PROGRAM_TYPE_ID = 10;

public readonly static int BUILD_TYPE_ID = 11;

public readonly static int TESTCASE_TYPE_ID = 12;

public readonly static int TESTPLAN_TYPE_ID = 13;

public readonly static int TESTPLANRUN_TYPE_ID = 14;

(33)

33

References

Complete reference for HQL syntax:

http://www.hibernate.org/hib_docs/nhibernate/1.2/reference/en/html/queryhql.html

TargetProcess NHibernate mapping files: