TARGETPROCESS WEB SERVICES GUIDE

TARGETPROCESS WEB SERVICES GUIDE v.2.10 Web Services API / Developers Guide This document describes Web Services in TargetProcess and provides some usage examples. 1

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 2

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. 3

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. 4

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

6 TargetProcess v.2.10 Web Services Guide

Test Cases 7

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> 8

<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 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 field 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 9

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 AddAttachmentToBug AddBugWithAttachment AddCommentToBug Description 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. Adds the bug with attachment. Adds Comment to the specified Bug 10

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 RetrievePage Retrieves the page (the range) of entities. 11

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 =?", new object[] "admin" )[0]; The following query returns all assigned user stories: 12

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" ); 13

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. 14

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. 15

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

17 TargetProcess v.2.10 Web Services Guide

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 18

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 19

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); 20

Configuring Integrated Authentication Configuring User Active Directory Name in Target Process 21

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. 22

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()); 23

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:///) 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: 24

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

<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 outputdirectory wsdl package externalbindings Description Specifies directory where the generated sources will be placed. Specifies where WSDL file is located. This can be local file system path or URL of an online WSDL resource. Specifies package name for the generated classes. Please use different packages for different WSDL files, otherwise conflicts can happen. 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. 26

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"; 27

// 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 28

</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> 29

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; 30

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

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; 32

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:///download/tp_mappings.zip 33