APIs, SDKs, and Services > Process Server WSHT API Overview > Interacting with the WSHT API
  

Interacting with the WSHT API

The following topics discuss how you interacting with the Web Services Human Task (WSHT) API:

Accessing Lists of Tasks Using the 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 its sample request.
Enter the username and password (for example, loanrep1/loanrep1) for this request using the Request Properties window shown in the bottom left of SOAP-UI application:
Send the 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>
This request fetches all unclaimed (status = READY) tasks that the current user can access. The response should 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>
You will need the resultset value for other task operations as it has the task ID, which is within 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>
Refer to the WSHT API WSDL, schemas, and documentation for information on other operations.

getMyTasks Request Parameters

The Accessing Lists of Tasks Using the SOAP UI showed how to get a list of tasks using the getMyTasks operation. The basic request message is:

<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:
Element
Possible Values
Notes
<htdt:taskType/>
  • - TASKS
  • - NOTIFICATIONS
  • - ALL
Indicates whether to return tasks, notifications, or both
<htdt:genericHumanRole/>
  • - POTENTIAL_OWNERS
  • - OWNER
  • - ADMINISTRATORS
  • - NOTIFICATION_RECIPIENTS
  • - INITIATOR
  • - STAKEHOLDERS
Optional element. If this element is not provided, the server uses POTENTIAL_OWNER (and implicitly the OWNER)
<htdt:workQueue/>
group/role name
Optional element. Name of group/role. The user must be a member of the group.
<htdt:status/>
  • - READY (unclaimed - ready to be claimed)
  • - RESERVED (claimed)
  • - IN_PROGRESS (started)
  • - SUSPENDED
  • - EXITED
  • - FAILED
  • - ERROR
  • - COMPLETED
  • - OBSOLETE
This is a repeating element. Include more than one to simulate "OR" across two or more values. For example, including the following two elements filters the result set to tasks that are claimed (RESERVED) or started (IN_PROGRESS) by current user:
<htdt:status>IN_PROGRESS</htdt:status> <htdt:status>RESERVED</htdt:status>
<htdt:whereClause/>
Where clause string.
Optional element. Filter by using a simple where clause. For example,
  • - By taskId: "Task.ID = urn:b4p:8765309" // should only return 1 task.
  • - By owner: "Task.Owner = jenny" // All tasks owned by jenny (reserved, in_progress, completed, failed)
  • - By priority: "Task.Priority = 3"
  • - By search by: "Task.PrimarySearchBy = customerid-8765309"
<htdt:createdOnClause/>
Optional Element. Filter by the date task was created. For example, Task.CreatedOn = 2009-10-05T11:14:00Z The date should be a schema dateTime (xsd:dateTime) formatted value.
<htdt:maxTasks/>
Maximum number of tasks to be returned. Integer value (> 0).
Optional Element.

Sample getMyTasks Requests

The following sections describe some of the sample request elements for getMyTasks operation:
List all unclaimed tasks (that can be claimed/started by a potential owner)

<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>
List tasks that have been claimed by current principal (owner)

<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>
List all my (owned by principal) tasks that are in progress (started)

<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>
List all closed tasks owned by current principal

<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>
List all open tasks (ready, reserved, in progress and suspended) that are accessible by the task initiator (<htdt:genericHumanRole/> is 'INITIATOR')

<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>
List tasks that are claimed (reserved) where the principal is a business administrator of the task

<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>
List all notifications

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

Configuring a getMyTasks Filter with a whereClause

For an overview of this topic, see Configuring Task Role Filters elsewhere in this help.
In the Task Role Filters section of the .avcconfig file, you can add a filter to apply to the tasks in one of the Show drop-down entries. For example, you can create a filter for Unclaimed Tasks to show only Priority zero (highest priority).
To filter the task list for the Show filter:
Modify the default configuration in the <avccom:filter/> section of the <avccom:taskFilterDef/> section.
The following code snippet shows the default configuration:

<avccom:filter>
<tsst:getTasks
xmlns:tsst="http://schemas.active-endpoints.com/b4p/wshumantask/
2007/10/aeb4p-task-state-wsdl.xsd">
<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:whereClause>Task.Name = 'ApproveLoan'</htdt:whereClause>
<htdt:maxTasks>20</htdt:maxTasks>
</htdt:getMyTasks>
<tsst:taskIndexOffset>0</tsst:taskIndexOffset>
</tsst:getTasks>
</avccom:filter>
Filtering a task list by parameter via WS-HT whereClause
You can use the following operators in the whereClause:
For a complete list of task column names, task types, generic human roles and other WS-HT specifications, you can work with the SDK. To get started, see What is the Process Server WS-HumanTask API? elsewhere in this help.
The following examples show various whereClause syntax. Note that the Booleans and and or are case-sensitive.
Example 1
The following example shows a sample whereClause using a standard WS-HT task property name. For a list of standard WS-HT names, see WS-HT Task Property List elsewhere in this help.
<htdt:whereClause>Task.Name = 'ApproveLoan'</htdt:whereClause>
Example 2
This example combines filter properties.
Task.Priority &lt; 3 and Task.Owner = 'loanrep1'
Example 3
This example also combines filter properties.
Task.PaProcessId = 10 and(Task.Escalated = true or Task.Priority = 0)
Example 4
The following example shows using presentation parameters (that is, custom task properties).
Task.Name = 'LoanApproval' and loanAmount &gt; 10000 and zipCode = '06484'
For details, see Creating Custom Task Properties elsewhere in this help.

Using a getTasks orderBy Element

You can sort the results returned by getTasks by setting the orderBy element. The fields name you can use are:
The following example sorts the results with the most recent first (that is, in descending order), followed by the priority:
orderBy orderBy = new OrderBy();
orderBy.getFieldId().add("-Created");
orderBy.getFieldId().add("Priority");
Notice the minus sign ("-") being used to set the order to descending.
In XML, this same example is written as follows:
<ns:orderBy>
<ns:fieldId>-Created</ns:fieldId>
<ns:fieldIPdriority</ns:fieldId>
</ns:orderBy>