It is quite easy to access TargetProcess SOAP API via Ruby.

Install soap4r

First thing you need to install soap4r. SOAP4R is a Ruby library for accessing Web Services via SOAP.

gem install soap4r --include-dependencies

Generate Classes From WSDL

For example, you want to use ProjectService API. You have to generate some classes using wsdl2ruby.

[path_to_wdsl2ruby]wsdl2ruby.rb --wsdl [targetprocess_url]/Services/ProjectService.asmx?WSDL --type client

Real command may look like:

/Library/Ruby/Gems/1.8/gems/soap4r-1.5.8/bin/wsdl2ruby.rb --wsdl http://localhost/targetprocess2/Services/ProjectService.asmx?WSDL --type client

This command will generate 4 classes. You may rename them if you want, in this example we use them as is.

default.rb
defaultDriver.rb
defaultMappingRegistry.rb
ProjectServiceClient.rb

Authentication

TargetProcess uses WSE, so it is required to provide correct authentication. First, create the following class in wsse_authentication.rb file in lib folder. Specify correct login and password. You may use System User credentials (login into TargetProcess and navigate to Admin section to set them).

require 'soap/header/simplehandler'

class WsseAuthHeader < SOAP::Header::SimpleHandler
  NAMESPACE = 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd'
  USERNAME  = 'admin'
  PASSWORD  = 'admin_password'

  def initialize()
    super(XSD::QName.new(NAMESPACE, 'Security'))
  end

  def on_simple_outbound
    {"UsernameToken" => {"Username" => USERNAME, "Password" => PASSWORD}}
  end
end

Usage

Let's assume you have DashboardController in your application and want to show specific project name. Here is the code that will extract project name via web services.

require "defaultDriver.rb"
require 'wsse_authentication.rb'

class DashboardController < ApplicationController
  def index
    driver = ProjectServiceSoap.new     

    #Add authentication
    driver.headerhandler << WsseAuthHeader.new()

    # Print project name
    project = driver.getByID(:id => 2)
    @project_name = project.getByIDResult.name
  end
end

We've almost finished web services API implementation for TP 2.3 release. It looks quite powerful and provides huge integration capabilities. With web services API you may do almost anything: add, edit and delete new entities, retrieve entities and even execute custom queries based on HQL (Hibernate Query Language). Of course you need to know HQL syntax (close to SQL in fact) and understand TargetProcess domain model to create complex queries. So we share entities description, class diagrams and NHibernate mapping files. You may check Web Services Developers Guide (PDF - 0.4M) for details.

Here are some examples that shows web services abilities.

Add new bug into TargetProcess.

BugServiceWse bugService = new BugServiceWse();
TpPolicy.ApplyAutheticationTicket(bugService, "admin", "admin");

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

Add comment to existing user story.

UserStoryServiceWse service = new UserStoryServiceWse();
TpServicePolicy.ApplyAutheticationTicket(service, "admin", "admin");
int storyId = 98;

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

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

Exampe with complex HQL query. Select all user stories assigned to user

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