TARGETPROCESS WEB SERVICES GUIDE

insidiousbehaviorSecurity

Nov 3, 2013 (3 years and 8 months ago)

88 views


TargetProcess v.2.10 — Web Services Guide



1
© 2004-2008 TargetProcess
www.targetprocess.com



TARGETPROCESS
WEB SERVICES GUIDE












v.2.10
Web Services API / Developers Guide

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



TargetProcess v.2.10 — Web Services Guide



2
© 2004-2008 TargetProcess
www.targetprocess.com



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 WSE 3.0 ADD-IN (VS 2005 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
REFERENCES ......................................................................................................................................................... 33


TargetProcess v.2.10 — Web Services Guide



3
© 2004-2008 TargetProcess
www.targetprocess.com


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.


TargetProcess v.2.10 — Web Services Guide



4
© 2004-2008 TargetProcess
www.targetprocess.com


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
Time belongs to Assignable.

TargetProcess v.2.10 — Web Services Guide



5
© 2004-2008 TargetProcess
www.targetprocess.com



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

TargetProcess v.2.10 — Web Services Guide



6
© 2004-2008 TargetProcess
www.targetprocess.com




TargetProcess v.2.10 — Web Services Guide



7
© 2004-2008 TargetProcess
www.targetprocess.com


Test Cases


TargetProcess v.2.10 — Web Services Guide



8
© 2004-2008 TargetProcess
www.targetprocess.com


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>

TargetProcess v.2.10 — Web Services Guide



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

R
eserved property for custom field

CustomField2

string

Reserved property for custom field

CustomField3

string

Reserved property for custom field

CustomField4

string

Reserved property for custom field

CustomField5

string

Reserved property for custom fiel
d

CustomField6

string

Reserved property for custom field

CustomField7

string

Reserved property for custom field

CustomField8

string

Reserved property for custom field

CustomField9

string

Reserved property for custom field

CustomField10

string

Reserved

property for custom field

CustomField11

string

Reserved property for custom field

CustomField12

string

Reserved property for custom field

CustomField13

string

Reserved property for custom field

CustomField14

string

Reserved property for custom field

CustomField15

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

TimeRemain

decimal

Total time remaining to complete assignment for Actor. Read
-
only

TargetProcess v.2.10 — Web Services Guide



10
© 2004-2008 TargetProcess
www.targetprocess.com


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 whic
h bug has been found. Optional.

UserStoryID

int

Bug may be assoc
iated 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. Ass
ignable 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 u
ser 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.
Ad
dBugWithAttachment

Adds the bug with attachment.

AddCommentToBug

Adds Comment to the specified Bug


TargetProcess v.2.10 — Web Services Guide



11
© 2004-2008 TargetProcess
www.targetprocess.com


AddRequestGeneralToBug

Adds Request General to the specified Bug

AddRevisionAssignableToBug

Adds Revision Assignable to the specified Bug

AddTeamToBu
g

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.

Assig
nUserByEmailOrLoginAsActor

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.

RetrieveAllFo
rBuild

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

Loa
ds open Bug entities for the currently logged in user.

RetrieveOpenForUser

Loads open Bug entities for specified user

RetrievePage

Retrieves the page (the range) of entities.


TargetProcess v.2.10 — Web Services Guide



12
© 2004-2008 TargetProcess
www.targetprocess.com


RetrieveRevisionAssignablesForBug

Loads the child collection of Revision As
signable 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 = ?"
,
new

object
[] {
"admin"
})[0];
The following query returns all assigned user stories:

TargetProcess v.2.10 — Web Services Guide



13
© 2004-2008 TargetProcess
www.targetprocess.com


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 "
+
"where story.EntityState.Final = 0 and story.EntityState.Actor = team.Actor)"
,
new

object
[] {
"admin"
});

TargetProcess v.2.10 — Web Services Guide



14
© 2004-2008 TargetProcess
www.targetprocess.com


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

Run Microsoft WSE 3.0.msi. Select “Visual Studio Developer” option in setup wizard.

TargetProcess v.2.10 — Web Services Guide



15
© 2004-2008 TargetProcess
www.targetprocess.com



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.

TargetProcess v.2.10 — Web Services Guide



16
© 2004-2008 TargetProcess
www.targetprocess.com




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


TargetProcess v.2.10 — Web Services Guide



17
© 2004-2008 TargetProcess
www.targetprocess.com



TargetProcess v.2.10 — Web Services Guide



18
© 2004-2008 TargetProcess
www.targetprocess.com


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

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



TargetProcess v.2.10 — Web Services Guide



19
© 2004-2008 TargetProcess
www.targetprocess.com


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

UsernameOverTransportAssertion
());
}


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
{

internal

class

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
entity) Use users array as required

TargetProcess v.2.10 — Web Services Guide



20
© 2004-2008 TargetProcess
www.targetprocess.com


Examples
Using HQL to retrieve all assigned user stories
string
userName =
"admin"
;
string
userPassword =
"admin"
;

UserStoryServiceWse
userStoryService =
new

UserStoryServiceWse
();
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,
new

object
[] {users[0].UserID});
Add comment to user story
UserStoryServiceWse
service =
new

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

CommentDTO
comment =
new

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

int
commId = service.AddCommentToUserStory(EntityId, comment);

TargetProcess v.2.10 — Web Services Guide



21
© 2004-2008 TargetProcess
www.targetprocess.com


Configuring Integrated Authentication
Configuring User Active Directory Name in Target Process


TargetProcess v.2.10 — Web Services Guide



22
© 2004-2008 TargetProcess
www.targetprocess.com


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.

TargetProcess v.2.10 — Web Services Guide



23
© 2004-2008 TargetProcess
www.targetprocess.com


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 TpServicePolicy());
}
}



TargetProcess v.2.10 — Web Services Guide



24
© 2004-2008 TargetProcess
www.targetprocess.com


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:

TargetProcess v.2.10 — Web Services Guide



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
>

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

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

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

TargetProcess v.2.10 — Web Services Guide



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
>
<
goal
>run</
goal
>
</
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.
p
ack
a
ge

Specifies p
ackage 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:
<
properties
>
<
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.


TargetProcess v.2.10 — Web Services Guide



27
© 2004-2008 TargetProcess
www.targetprocess.com


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.

String
url =
"http://localhost/tp/Services/BugService.asmx"
;

TargetProcess v.2.10 — Web Services Guide



28
© 2004-2008 TargetProcess
www.targetprocess.com



// 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(
new

DOMOutHandler
());

// 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(
new

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


TargetProcess v.2.10 — Web Services Guide



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
>

TargetProcess v.2.10 — Web Services Guide



30
© 2004-2008 TargetProcess
www.targetprocess.com


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
$securityHeader = new SecurityHeader;

TargetProcess v.2.10 — Web Services Guide



31
© 2004-2008 TargetProcess
www.targetprocess.com



//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>';
?>



TargetProcess v.2.10 — Web Services Guide



32
© 2004-2008 TargetProcess
www.targetprocess.com


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;
public readonly static int
PERSONREQUEST_TYPE_ID = 15;

TargetProcess v.2.10 — Web Services Guide



33
© 2004-2008 TargetProcess
www.targetprocess.com


References
Complete reference for HQL syntax:
http://www.hibernate.org/hib_docs/nhibernate/1.2/reference/en/html/queryhql.html


TargetProcess NHibernate mapping files:
http://www.targetprocess.com/download/TP_Mappings.zip