ActiveVOS WS-HumanTask API

ActiveVOS server implements the operations described by the OASIS WS-HumanTask (WSHT) API task client specifications to manage human tasks as well as interact with specific tasks. In addition to WSHT API, the ActiveVOS server also provides an extension API to the OASIS WSHT API with enhanced functionality. This document introduces the reader to the Active Endpoint implementation of the WSHT and ActiveVOS Extension APIs, and includes a few examples describing the use of the API via SOAP and indirectly via Java code using JAX-WS (ActiveVOS WSHT4J API).

Readers should read the WS-HumanTask Architecture PDF document found in the docs/ directory to get an appreciation of WSHT. This document will help understand concepts necessary to the use of the API.

1. Package Contents
2. HumanTask Related Web Service Endpoints
3. Background and Setup
   1. Authentication And Use Of Identity Service For Authorization
   2. Development Setup
   3. Creating Human Tasks For Use With Samples
   4. Using SOAP-UI To Create Human Task Processes
   5. Using Web Form To Create Human Task Processes
4. Interacting With WSHT API
   1. Accessing List Of Tasks Using SOAP UI
   2. Parameters Used In GetMyTasks Request
   3. Sample GetMyTasks Requests
   4. Getting Task Input And Output Data
5. ActiveVOS Extensions To WSHT API
6. Using JAX-WS Based ActiveVOS WSHT4J API
   1. Building WSHT4J
   2. WSHT4J Samples
   3. Listing Tasks Using WSHT4J API
   4. Claiming A Task Using WSHT4J API
   5. Additional Examples Using WSHT4J
7. Getting Task Lists As A RSS or ATOM Feed
8. Recommended External Tools

Package Contents

The WSHT API using JAX-WS (WSHT4J) and samples code project contains the following artifacts:

HumanTask Related Web Service Endpoints

The follow table shows the Human Task related web service endpoints. Note that these endpoints require that the client application provide login credentials of the principal.

Background and Setup

Authentication and Use of the ActiveVOS Identity Service For Authorization

There are 4 basic components involved when interacting with tasks on the ActiveVOS server via service located at API endpoint http://.../active-bpel/services/AeB4PTaskClient-taskOperations.

 [Client: accesses /services/AeB4PTaskClient-taskOperations with username and password] -->
  ----> [Web Application Container: checks if user has access to resources] -->
  ----> [ActiveVOS engine: execution of tasks and API] -->
  ----> [Identity Service: checks if user has access to tasks]

A Task Client is any application that wants to access the API via a web service call. The Inbox application is one such implementation. All clients access the WSHT API at the service endpoint located at http://.../active-bpel/services/AeB4PTaskClient-taskOperations.

The API service endpoint (/services/AeB4PTaskClient-taskOperations) is normally secured using standard Java servlet security. By default, this service is secured to provide access to a user with the role of abTaskClient per security constraint defined in the active-bpel.war web.xml. Anyone wishing to access this endpoint must provide authentication credentials and have the abTaskClient role.

It is the responsibility of the web application container (such as Tomcat) to make sure that the client accessing the service endpoint has proper credentials. As mentioned previously, any principal with role of abTaskClient (as defined in the web.xml) should have access to the resources (service). If the credentials are not provided or incorrect, the web container normally responds with the HTTP 401 (unauthorized).

Once access to service endpoint is granted (by the web container), the request along with the principal's username is passed into the ActiveVOS engine's task client API implementation. At this point, the engine consults a ACL and the Identity Service to see which tasks the principal has access to. The principal must have a role associated with the tasks (generic human role such as a potential owner, business administrator) in order to view or manipulate tasks.

Note: The user credentials (such as via HTTP BASIC authentication and session cookies thereafter) are required for every web service request. Otherwise you will get an empty response (same as an anonymous user would obtain). In most cases, this is the reason for getting empty responses (as evidenced by a lack of task in the ActiveVOS Inbox task list). Another reason could be that the task has been escalated and assigned to another user/admin and therefore not accessible to this user.

In summary, the web container is responsible for authentication and authorizing access only to the service endpoint. The Identity Service is then used to determine what tasks (if any) the user is authorized to view and or modify.

Development Setup

In order to interact with the WSHT API using web services make sure that the following are configured on your ActiveVOS Server:

1. ActiveVOS Identity Service is enabled and configured. For example, LDAP/Active Directory.

   If you are using the evaluation version of ActiveVOS, you can use the default settings - which is to use a xml file (similar tomcat-users.xml) that contains list of roles/groups and users:

   Username	Password	Roles
   loanrep1	loanrep1	loanreps, abTaskClient
   loanrep2	loanrep2	loanreps, abTaskClient
   loanrep3	loanrep3	loanreps, abTaskClient
   loanmgr1	loanmgr1	loanmgrs, abTaskClient
   loanmgr2	loanmgr2	loanmgrs, abTaskClient
   loancsr1	loancsr1	loancsrs, abTaskClient

   Note: the task users (e.g. loanrep1) also have the 'abTaskClient' role in order access the secured service endpoint.

2. The web service endpoint to access the task operations is secured (e.g. using HTTP Basic authentication). This can be done by un-commenting the appropriate section in the ActiveVOS server's web.xml file (located in active-bpel.war). If you are using ActiveVOS 6.1 or later, this endpoint is secured by default. The endpoint is not secured in earlier versions - however, you can secure it by removing the comments '<!-- TASKCLIENT ...' in the active-bpel.war web.xml : E.g the content in the active-bpel.war web.xml looks like:

   
   <security-constraint>
    <web-resource-collection>
     <web-resource-name>WS-HT BPEL for People Client</web-resource-name>
     <description>Endpoint that contains all of the operations for an WS-HT BPEL for People client application.
       These applications will provide an interface for people to interact with tasks that were created
       by people activities within a BPEL process.</description>
     <url-pattern>/services/AeB4PTaskClient-taskOperations</url-pattern>
     <url-pattern>/services/AeB4PTaskClient-aeTaskOperations</url-pattern>
     <url-pattern>/taskxsl/*</url-pattern>
     </web-resource-collection>
      <!-- TASKCLIENT Uncomment to restrict access to the task client services
         <auth-constraint>
            <role-name>abTaskClient</role-name>
         </auth-constraint>
         TASKCLIENT
       -->
   </security-constraint>
   

   Note: The web container's authentication provider (e.g. tomcat-users.xml in Tomcat file based provider) must use the same data (i.e. list of usernames and roles) as does the Identity Service.

Creating Human Tasks for Use with Samples

In order to use the samples described in this document, you will need to create some tasks on the ActiveVOS server. The samples uses a bare-bones version of the Loan Approval process that is shipped with the ActiveVOS Designer. The BPEL process that implements this simplified Loan Approval process is located in the /orchestration/HumanTaskDemo/bpel/humantaskdemo.bpel.

This process must be deployed to the server by using the BPR file located at /orchestration/HumanTaskDemo/deploy/humantaskdemo.bpr.

This process simply takes a <loan:loanProcessRequest/> (per loanRequest.xsd schema) element as the create message and passes it onto a human task. The SOAP message looks like:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:loan="http://schemas.active-endpoints.com/sample/LoanRequest/2008/02/loanRequest.xsd">
   <soapenv:Header/>
   <soapenv:Body>
      <loan:loanProcessRequest>
         <loan:loanType>Automobile</loan:loanType>
         <loan:firstName>John</loan:firstName>
         <loan:lastName>Smith</loan:lastName>
         <loan:dayPhone>2039299400</loan:dayPhone>
         <loan:nightPhone>2035551212</loan:nightPhone>
         <loan:socialSecurityNumber>123-45-6789</loan:socialSecurityNumber>
         <loan:amountRequested>15000</loan:amountRequested>
         <loan:loanDescription>Application to finance the purchase of a Toyota Prius</loan:loanDescription>
         <loan:otherInfo>Down payment is US$7500</loan:otherInfo>
         <loan:responseEmail>john.smith@example.com</loan:responseEmail>
      </loan:loanProcessRequest>
   </soapenv:Body>
</soapenv:Envelope>

Before running any of the examples, you should create one or more tasks by sending the create messages to the humantaskdemo's service endpoint located at http://localhost:8080/active-bpel/services/humantaskProcessDemoService. You can send these messages using two methods - via SOAP-UI or a REST based web form.

Using SOAP-UI to Create Human Task Processes

Download and install SOAP-UI. SOAP-UI can be downloaded from http://www.soapui.org/. After installing SOAP-UI:

1. Choose File -> New WSDL Project.
   Enter name for project. E.g.: HumanTaskDemo.
   For the initial WSDL, enter http://localhost:8080/active-bpel/services/humantaskProcessDemoService.
   Make sure that "Create Request" check box is checked.
   Press OK.

   

2. Save the SOAP-UI project.

3. Select project from the Project Explore; expand the port type associated with the humantaskProcessDemoServiceBinding. Then double click on the Request to see the sample create message.

   

4. Populate the request and send the message to the server.
   

Using Web Form to Create Human Task Processes

You can use the user friendly HTML form to send create messages to the humantaskdemo process using a second REST based process.

1. Open the HTML document located in the /docs/InvokeLoanApproval-REST-form.html using a web browser.
2. Fill out the Loan Application web form and press the Apply for Loan button.
3. Repeat to send more create messages.

You can verify that tasks were created by logging into the Inbox using the credentials for loanrep1.

Interacting With WSHT API

Accessing List of Tasks Using SOAP UI

To quickly see the WSHT API in action, you can use SOAP-UI or similar tool (such as the Eclipse's Web Services Explorer tool).

To use SOAP-UI, create a new WSDL Project in SOAP-UI using the endpoint address of the WSHT API service for the initial WSDL: http://localhost:8080/active-bpel/services/AeB4PTaskClient-taskOperations . Save the project after SOAP-UI has created the sample requests.

From SOAP-UI's Project Explorer, locate the project for the WSHT API and expand the getMyTasks operation and double click on the Request to reveal the sample request.

Enter the username and password (e.g. loanrep1/loanrep1) for this request via the Request Properties window shown in the bottom left of SOAP-UI application:

Send following SOAP request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.example.org/WS-HT/api/xsd">
   <soapenv:Header/>
   <soapenv:Body>
     <htdt:getMyTasks xmlns:htdt="http://www.example.org/WS-HT/api/xsd">
       <htdt:taskType>TASKS</htdt:taskType>
       <htdt:genericHumanRole>POTENTIAL_OWNERS</htdt:genericHumanRole>
       <htdt:status>READY</htdt:status>
       <htdt:maxTasks>5</htdt:maxTasks>
     </htdt:getMyTasks>
   </soapenv:Body>
</soapenv:Envelope>

The above request is to fetch all unclaimed (status = READY) tasks that are accessible to current user. The response should be contain one or more <htdt:taskAbstract> elements representing each task.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
     xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soapenv:Body>
      <htdt:getMyTasksResponse
             xmlns:htdt="http://www.example.org/WS-HT/api/xsd"
             xmlns:htda="http://www.example.org/WS-HT/api">
         <htdt:taskAbstract>
            <htda:id>urn:b4p:5</htda:id>
            <htda:taskType>TASK</htda:taskType>
            <htda:name>ApproveLoan</htda:name>
            <htda:status>READY</htda:status>
            <htda:priority>2</htda:priority>
            <htda:taskInitiator>anonymous</htda:taskInitiator>
            <htda:potentialOwners>
               <htd:users xmlns:htd="http://www.example.org/WS-HT">
                  <htd:user>loanrep1</htd:user>
                  <htd:user>loanrep2</htd:user>
               </htd:users>
            </htda:potentialOwners>
            <htda:businessAdministrators>
               <htd:groups xmlns:htd="http://www.example.org/WS-HT">
                  <htd:group>loanmgr1</htd:group>
               </htd:groups>
            </htda:businessAdministrators>
            <htda:createdOn>2009-04-23T19:12:21.615Z</htda:createdOn>
            <htda:createdBy>anonymous</htda:createdBy>
            <htda:activationTime>2009-04-23T19:12:21.615Z</htda:activationTime>
            <htda:isSkipable>true</htda:isSkipable>
            <htda:hasPotentialOwner>true</htda:hasPotentialOwners>
            <htda:startByExists>false</htda:startByExists>
            <htda:completeByExists>false</htda:completeByExists>
            <htda:presentationName>Loan Approval Demo</htda:presentationName>
            <htda:presentationSubject>Loan request for US$ 15000 from John Smith [taskid: urn:b4p:5]</htda:presentationSubject>
            <htda:renderingMethodExists>false</htda:renderingMethodExists>
            <htda:hasOutput>false</htda:hasOutput>
            <htda:hasFault>false</htda:hasFault>
            <htda:hasAttachments>false</htda:hasAttachments>
            <htda:hasComments>false</htda:hasComments>
            <htda:escalated>false</htda:escalated>
            <htda:primarySearchBy>123-45-6789</htda:primarySearchBy>
         </htdt:taskAbstract>
      </htdt:getMyTasksResponse>
   </soapenv:Body>
</soapenv:Envelope>

One element value from the resultset you will need for other task operations is the task id, represented by the <htda:id>task identifier</htda:id> element. For example, to claim this task, the SOAP message is:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.example.org/WS-HT/api/xsd">
   <soapenv:Header/>
   <soapenv:Body>
      <htdt:claim xmlns:htdt="http://www.example.org/WS-HT/api/xsd">
         <htdt:identifier>urn:b4p:62</htdt:identifier>
      </htdt:claim>
   </soapenv:Body>
</soapenv:Envelope>

Please refer to the WSHT API WSDL, schemas and documentation for further reference on various operations.

Parameters Used In GetMyTasks Request

The previous example showed how to get a list of tasks using the getMyTasks operation. The basic request message takes the format:

<htdt:getMyTasks xmlns:htdt="http://www.example.org/WS-HT/api/xsd">
   <htdt:taskType/>
   <htdt:genericHumanRole/>
   <htdt:workQueue/>
   <htdt:status/>
   <htdt:whereClause/>
   <htdt:createdOnClause/>
   <htdt:maxTasks/>
</htdt:getMyTasks>

The key elements in this request are:

Sample GetMyTasks Requests

The following table lists some of the sample request elements for getMyTasks operation:

<htdt:getMyTasks xmlns:htdt="http://www.example.org/WS-HT/api/xsd">
    <htdt:taskType>TASKS</htdt:taskType>
    <htdt:genericHumanRole>POTENTIAL_OWNERS</htdt:genericHumanRole>
    <htdt:status>READY</htdt:status>
    <htdt:maxTasks>20</htdt:maxTasks>
</htdt:getMyTasks>

<htdt:getMyTasks xmlns:htdt="http://www.example.org/WS-HT/api/xsd">
    <htdt:taskType>TASKS</htdt:taskType>
    <htdt:genericHumanRole>OWNER</htdt:genericHumanRole>
    <htdt:status>RESERVED</htdt:status>
    <htdt:maxTasks>20</htdt:maxTasks>
</htdt:getMyTasks>

<htdt:getMyTasks xmlns:htdt="http://www.example.org/WS-HT/api/xsd">
    <htdt:taskType>TASKS</htdt:taskType>
    <htdt:genericHumanRole>OWNER</htdt:genericHumanRole>
    <htdt:status>IN_PROGRESS</htdt:status>
    <htdt:maxTasks>20</htdt:maxTasks>
</htdt:getMyTasks>

<htdt:getMyTasks xmlns:htdt="http://www.example.org/WS-HT/api/xsd">
    <htdt:taskType>TASKS</htdt:taskType>
    <htdt:genericHumanRole>OWNER</htdt:genericHumanRole>
    <htdt:status>EXITED</htdt:status>
    <htdt:status>FAILED</htdt:status>
    <htdt:status>ERROR</htdt:status>
    <htdt:status>COMPLETED</htdt:status>
    <htdt:status>OBSOLETE</htdt:status>
    <htdt:maxTasks>20</htdt:maxTasks>
</htdt:getMyTasks>

<htdt:getMyTasks xmlns:htdt="http://www.example.org/WS-HT/api/xsd">
    <htdt:taskType>TASKS</htdt:taskType>
    <htdt:genericHumanRole>INITIATOR</htdt:genericHumanRole>
    <htdt:status>READY</htdt:status>
    <htdt:status>RESERVED</htdt:status>
    <htdt:status>IN_PROGRESS</htdt:status>
    <htdt:status>SUSPENDED</htdt:status>
    <htdt:maxTasks>20</htdt:maxTasks>
</htdt:getMyTasks>

<htdt:getMyTasks xmlns:htdt="http://www.example.org/WS-HT/api/xsd">
    <htdt:taskType>TASKS</htdt:taskType>
    <htdt:genericHumanRole>ADMINISTRATORS</htdt:genericHumanRole>
    <htdt:status>RESERVED</htdt:status>
    <htdt:maxTasks>20</htdt:maxTasks>
</htdt:getMyTasks>

<htdt:getMyTasks xmlns:htdt="http://www.example.org/WS-HT/api/xsd">
    <htdt:taskType>NOTIFICATIONS</htdt:taskType>
    <htdt:genericHumanRole>NOTIFICATION_RECIPIENTS</htdt:genericHumanRole>
    <htdt:maxTasks>20</htdt:maxTasks>
</htdt:getMyTasks>

Getting Task Input and Output Data

Most of task specific operations such as claim, start, stop etc. are simple and they require only the task id element. You may refer to the WSHT documentation and ws-humantask-api.wsdl for further details.

The getInput, getOutput, and setOutput operations require the task id as well as the input (output) part name. For example, the humantaskdemo.wsdl approveLoanWshtPT port type approveLoan operation is described as follows:

<portType name="approveLoanWshtPT">
   <operation name="approveLoan">
   <input message="tns:WshtLoanInput" />
   <output message="tns:WshtLoanOutput" />
   </operation>
</portType>

Note: The above shows the port type for the Human Task used by the People Activity (which is not the same as the port type used by the humantaskdemo bpel process).

The input message is defined as:

<message name="WshtLoanInput">
   <part name="request" element="loan:loanProcessRequest" />
</message>

Note the message part name is 'request'. The message part name is included in the WSHT API getInput message:

<htdt:getInput xmlns:htdt="http://www.example.org/WS-HT/api/xsd">
   <htdt:identifier>urn:b4p:5</htdt:identifier>
   <htdt:part>request</htdt:part>
</htdt:getInput>

Similarly, the output message part is named 'response':

<message name="WshtLoanOutput">
   <part name="response" element="loan:loanApprovalResponse" />
</message>

The getOuput is:

<htdt:getOutput xmlns:htdt="http://www.example.org/WS-HT/api/xsd">
   <htdt:identifier>urn:b4p:5</htdt:identifier>
   <htdt:part>response</htdt:part>
</htdt:getOutInput>

The setOutput has an additional element <htdt:taskData> which contains the output message part element. For example:

<htdt:setOutput xmlns:htdt="http://www.example.org/WS-HT/api/xsd">
   <htdt:identifier>urn:b4p:5</htdt:identifier>
   <htdt:part>response</htdt:part>
   <htdt:taskData>
     <!-- loanApprovalResponse element (output) -->
     <loan:loanApprovalResponse xmlns:loan="http://schemas.active-endpoints.com/sample/LoanRequest/2008/02/loanRequest.xsd">
       <loan:responseToLoanRequest>approved</loan:responseToLoanRequest>
       <loan:responseDescription>Your loan has been approved.</loan:responseDescription>
     </loan:loanApprovalResponse>
   </htdt:taskData>
</htdt:setOutInput>

ActiveVOS Extensions to WSHT API

Task data has the following information:

1. Identifier (task id).
2. Name (name of task).
3. Type (TASK or NOTIFICATION).
4. Presentation information such as presentation name, subject, description etc.
5. Context data such as potential owners, business admins, actual owner, creation dates, and other meta data.
6. Operational data such as the input (e.g. loan approval name, email, loan amount), output, comments, attachments etc.

The current version of the WSHT API (at endpoint /services/AeB4PTaskClient-taskOperations) allows you to access all of these data by making multiple web service calls. For example, if you have an application that needs to populate the user interface with the task presentation name, input data, output data and comments, you will have to make discrete web service calls to operations:

• getTaskInfo()
• getTaskDescription()
• getInput()
• getOutput()
• getComments()

Alternate method to retrieve all of the task data using a single web service call is the ActiveVOS specific operation 'getInstance' available from the aeTaskOperations port type at endpoint http://host:port/active-bpel/services/AeB4PTaskClient-aeTaskOperations.

This operation returns a single element <trt:taskInstance> described in the aeb4p-task-rt.xsd schema. The element contains all of the task data, including input data, output data, comments, attachments, presentation information etc. (The aeTaskOperations port type is described in the aeb4p-task-state.wsdl). The <trt:taskInstance> element also contains some additional useful meta data such as the list of operations the current principal can invoke given the task's current status and the principal's role.

See the xml files at /docs/ae-getTaskInstance-request.xml and /docs/ae-getTaskInstance-response.xml for a detailed request and response example.

The complete list of extension operations provided by the /services/AeB4PTaskClient-aeTaskOperations is shown in the table below:

Using JAX-WS Based ActiveVOS WSHT4J API

The ActiveVOS wsht4j API is a WSHT API client based on JAX-WS (version 2.1.5). To use the client api, include the avos-wsht4j.jar along with the dependent libraries (for JAX-WS) in your classpath. The JAX-WS dependent jars are:

Building WSHT4J

You can build the api using the provided ant build script. The built avos-wsht4j.jar is copied to the dist/ directory. JDK 1.5 or later is required to build this project.

WSHT4J Samples

Samples using the wsht4j API can be found under the /src-examples/ source tree.

Listing Tasks Using WSHT4J API

The following sample snippet shows how to list unclaimed tasks using the wsht4j api. Please see the com.activevos.examples.wsht.GetMyTasksDemo1 (and GetMyTasksDemo2) class for the complete examples.

import com.activevos.api.humantask.AeB4PTaskClientTaskOperations;
import com.activevos.api.humantask.TaskOperations;
import com.activevos.api.humantask.wsht.htda.TGenericHumanRoleType;
import com.activevos.api.humantask.wsht.htda.TStatus;
import com.activevos.api.humantask.wsht.htda.TTask;
import java.util.ArrayList;
import java.util.List;
import javax.xml.ws.BindingProvider;

// Define endpoint, username and password
String serviceUrl = "http://localhost:8080/active-bpel/services/AeB4PTaskClient-taskOperations";
String username = "loanrep1";
String password = "loanrep1";

// Create service and get service port.
AeB4PTaskClientTaskOperations wshtService = new AeB4PTaskClientTaskOperations();
TaskOperations wshtServicePort = wshtService.getAeB4PTaskClientTaskOperationsPort();

// Set request properties such as binding endpoint and BASIC credentials.
((BindingProvider)wshtServicePort).getRequestContext().put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, serviceUrl);
((BindingProvider)wshtServicePort).getRequestContext().put(BindingProvider.USERNAME_PROPERTY, username);
((BindingProvider)wshtServicePort).getRequestContext().put(BindingProvider.PASSWORD_PROPERTY, password);

// Task type. In this case we are looking for the tasks (and not notifications).
// In general, the taskType is 'TASKS' for all cases unless you want notifications
// in the response. For notifications, use the value 'NOTIFICATIONS'. If you want tasks and
// notifications, use 'ALL'.
String taskType = "TASKS";

// Set role to be potential owners. That is, tasks that are available
// to potential owners.
TGenericHumanRoleType role = TGenericHumanRoleType.POTENTIAL_OWNERS;

// workQueue - not used.
String workQueue = null;

// Task status - this is one of the main filters we use to narrow down the resultset.
// Unclaimed tasks have a status of 'READY'.
// Some other common status enumerations are claimed (RESERVED),
// started (IN_PROGRESS), failed (FAILED), and completed (COMPLETED).
List<TStatus> statuses = new ArrayList<TStatus>();
statuses.add(TStatus.READY); // READY = 'unclaimed'.

// whereClause - not used.
String where = null;

// createdOn - not used.
String createdOnClause = null;

// maximum number of tasks to be returned in the resultset.
int maxtasks = 5;

// Call getMyTasks
List<TTask> tasks = wshtServicePort.getMyTasks(taskType, role, workQueue, statuses, where,
      createdOnClause, maxtasks);

// Note: TTask is of complex type tTask defined in ws-humantask-api-wsdl.xsd schema.
int count = tasks.size();
System.out.println("Number of tasks: " + count);
if ( count == 0 )
{
   // No tasks. Normally, this happens if:
   // - The username (defined in PRINCIPAL_USERNAME) does not have access to any tasks
   // - There are no unclaimed tasks (i.e. tasks with status = READY).
   return;
}
//
// Get 1st task in the list and print some information.
//
TTask task = tasks.get(0);
// The taskId is unique and normally takes for form "urn:b4p:NNN" where NNN is some number
// (usually representing the process id that implements the task on the ActiveVOS server).
// The taskId is required for all task related operations.
String taskId = task.getId();
System.out.println("TaskID: " + taskId);
// print some additional information:
System.out.println("Name: " + task.getName());// task QName
System.out.println("PresentationName: " + task.getPresentationName());
System.out.println("PresentationSubject: " + task.getPresentationSubject());
System.out.println("Status: " + task.getStatus().toString()); // expected value is READY (unclaimed).

Claiming A Task Using WSHT4J API

The following sample snippet shows how to claim task using the wsht4j api. Please see the com.activevos.examples.wsht.BasicOperations class for the complete example illustrating how to claim, start, set the output and complete at task .

// Service port
TaskOperations wshtServicePort = null;
//
// Code to create wshtServicePort similar to previous example
//

// Id of task we want to claim
String taskId = "urn:b4p:5";
try
{
   // claim
   wshtServicePort.claim(taskId);
}
catch(IllegalArgumentFault illegalArgumentFault)
{
   //Fault due to invalid task id.
   System.out.println("IllegalArgumentFault: " + illegalArgumentFault.getFaultInfo());
}
catch(IllegalStateFault illegalStateFault)
{
   // Illegal state. E.g. tried to claim a task that was not in a
   // a READY state (unclaimed).

   IllegalState illegalState = illegalStateFault.getFaultInfo();
   // Sample:
   // illegalState.getStatus()  : 'RESERVED'  (already claimed)
   // illegalState.getMessage() : 'Task must be in the READY state in order to be claimed.'
   System.out.println("IllegalStateFault: "
            + "\n taskStatus=" + illegalState.getStatus()
            + "\n " + illegalState.getMessage());
}

Additional Examples Using WSHT4J

Getting Task Lists As A RSS or ATOM Feed

The list of tasks can also be accessed as a RSS or ATOM feed via the REST based service located at http://host:port/active-bpel/services/REST/AeB4PTaskFeed. This endpoint also requires the principal username and password.

The AeB4PTaskFeed service implements the WSHT getMyTasks operation. The request parameters should passed as part of the HTTP GET request query string:

Task Feed Examples

Recommended External Tools

If you are writing your own client code (Java, .NET etc.), you could use an excellent debugging tool called Charles (free download http://www.charlesproxy.com/). Charles is a web/reverse proxy that lets you monitor xml traffic between the client (your code) and the server (ActiveVOS WSHT).