APIs, SDKs, and Services > ActiveVOS WSHT API > Background and Setup
  

Background and Setup

Before using the Web Services Human Task API, you should be familiar with the following concepts:

Authentication and Use of the Process Server Identity Service For Authorization

There are 4 basic components involved when interacting with tasks on the Process 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. This security constraint is defined in the active-bpel.warweb.xml file. 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 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 Process Server 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 Process Central's 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 Process Server:
  1. 1. Process Sever Identity Service is enabled and configured. For example, LDAP/Active Directory.
    2. If you are using the evaluation version, you can use the default settings, which is to use an 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 (for example, loanrep1) also have the abTaskClient role in order access the secured service endpoint.
  2. 2. The Web service endpoint to access the task operations is secured (for example, using HTTP Basic authentication). This can be done by un-commenting the appropriate section in the Process Server's web.xml file (located in active-bpel.war). Here's an example of what the active-bpel.war web.xml file looks like:

    3. <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 (for example, tomcat-users.xml in Tomcat file based provider) must use the same data (that is, 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 Process Server. The samples uses a bare-bones version of the Loan Approval process that is shipped with the Process Developer. The BPEL process that implements this simplified Loan Approval process is located in /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/> (using the 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:  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. 1. Choose File > New WSDL Project.
    1. a. Enter a name for the project; for example: HumanTaskDemo.
    2. b. For the initial WSDL, enter http://localhost:8080/active-bpel/services/humantaskProcessDemoService. Make sure that Create Request check box is checked.
    3. c. Press OK.
  2. 2. Save the SOAP-UI project.
  3. 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. 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. 1. Open the HTML document located in the /docs/InvokeLoanApproval-REST-form.html using a web browser.
  2. 2. Fill out the Loan Application web form and press the Apply for Loan button.
  3. 3. Repeat to send more create messages.
You can verify that tasks were created by logging into the Inbox using the credentials for loanrep1.