An overview of human tasks and queries
When a human task is created by IBM® WebSphere® Process Server V6.1, the task is intended to be worked upon by a person at some time in the future. WebSphere Process Server supports the existence of many concurrent tasks simultaneously in the system. There can be many tasks for many different people and there can also be many tasks for the same person. On occasion there may be the desire to work upon a specific instance of a task. The challenge then becomes that of locating the desired task from the potentially vast number of tasks in existence.
Let us use a simple scenario to illustrate the problem and examine an efficient and elegant solution. Consider a business process that is handling some customer request. A step in the process requires that the customer call our company and talk with a customer service representative. Perhaps there is a problem with their order or payment. We e-mail the customer and ask them to call us at their convenience. The sending of the e-mail and the creation of the associated human task is automated by the business process. When the customer calls, we need the customer service representative to pull-up the details of the human task that gives the details of the interaction as well as providing an outcome for the continuation of the process.
This scenario is illustrated in Figure 1. When a business process executes, it sends an e-mail message to the customer. The customer contacts our company and supplies his customer information. The customer service representative must now locate the calling customer's associated specific task from the set of tasks currently in existence associated with all the other business processes which are also running.
Figure 1. Interactions between process, people and sets of Human Tasks
The human task and custom properties technology
When we start to examine the technology of the solution in more depth, we are able to focus into the challenge area. The business process will invoke the creation of a Human Task. Each instance of a human task has input data associated with it. From a WebSphere Process Server perspective, a human task exposes a service interface and the input parameters to that service interface describe the data that is supplied to the instance of the human task to be created. The customer service representative is the user of the human tasks and will use a client interface to interact with the set of tasks available. We should be able to assume that the data passed to a human task, when it is created, will include the details of the customer that will eventually call-back. The challenge then is how to locate the specific human task instance associated with a particular calling customer.
If we focus in on the client interface that a customer service representative may use, we find that this is composed of a set of application programming interfaces (APIs) exposed by the Human Task Manager. These APIs allow us to retrieve human task instances based on a wide variety of meta data such as the type of task, the time the task was created, the current state of the task, and many other such attributes. Unfortunately, the query API does not allow us to select a task based on the data content submitted to that task when it was created.
Examining Figure 2 we see an example of the data that is associated with an instance of a human task. Of particular interest is the field called
orderID. This is a unique identifier for each order. When a customer calls in, we expect him to supply the
orderID information. This will be the key for locating the particular instance of the human task of interest.
Figure 2. The Business Object representing the Order
A human task has a service interface associated with it. Figure 3 shows the chosen interface for the example human task. It accepts a Business Object called Order as input and returns a String that represents the outcome of the communication with the customer.
Figure 3. The Interface description for the processOrder operation
From the customer service representative's perspective, the customer calls in and supplies the
orderID. The customer service representative now wants to work upon the human task associated with the customer's order. The designers and developers of the customer service representative client interface now need to implement an efficient mechanism to locate this Task.
Using the custom property
A custom property is a piece of meta data that you can associate with an instance of task. A custom property consists of a name and value pair. Both the names and values are simple character strings. You can set or retrieve a custom property through the human task API when working with an instance of a human task. You can use this data for a variety of purposes, since it is not limited to any one usage pattern. For our scenario, the key benefit here is that we can use a custom property as a query able parameter to locate a human task instance. If we were to create a custom property associated with a human task that contains the
orderID value from the Order Business Object then when a customer telephones, the human task associated with that order can be retrieved with a simple query. This is illustrated in Figure 4 which shows a set of human tasks known to the Human Task Manager with a custom property called
orderID exposed on each task.
Figure 4. The set of human tasks, each with their own
Creating the custom property on the task
You can define custom properties in the Human Task Editor when the template for the human task is created. With a human task selected in the Human Task Editor in WebSphere Integration Developer, the Properties view contains a tab called Environment. This tab shows all the custom properties associated with the Task template. Buttons are provided to:
- Add new custom properties
- Remove existing custom properties
- Edit the names and values of existing custom properties.
When you click Add, a simple dialog is displayed into which you can enter the name and value of the custom property. An example of this dialog is shown in Figure 5.
Figure 5. The settings of the custom property definition
For this scenario, the name of the custom property is chosen to represent the fact that it is an
orderID so the name
orderID for the name of the property is appropriate. The value of the custom property is much more interesting. Obviously a constant value does not make sense for our solution. We want the value of the custom property to be the value of the
orderID field in the incoming data. The Human Task Manager provides support for this through a technique called replacement variables. Replacement variables allow us to supply a description of where the data should be obtained that should be used for the value of the property. The syntax of each of the allowable replacement variable encodings is described at the: WebSphere Integration Developer Information Center.
One of the allowable encodings is to source a value for a property from the incoming data supplied when the human task is created. The encoding for this replacement variable is:
This should be interpreted as taking the field called
orderID from the
orderDetails operation specified by the input variable. The complete Custom Property definition in the Human Task Editor Environment panel looks as shown in Figure 6.
Figure 6. The configuration to set the
orderID parameter of the task
When an instance of this human task is created, a custom property called
orderID will be associated with the task and its value taken from the supplied parameter called
orderDetails and the associated field called
orderID inside that parameter. Using the IBM supplied Business Process Choreographer Explorer (BPC) tool, we can view an instance of such a human task and validate that the settings are correct. Figure 7 illustrates viewing the property within BPC Explorer.
Figure 7. Examining the property of an existing human task instance
Querying for the task
What remains now is to construct a query that the client environment can use to obtain the human task for a specific order. This will be achieved by asking the Human Task Manager to retrieve task instances which have a custom property called
orderID with a value of the order supplied by the customer.
Querying tasks through BPC Explorer
Normally this will be achieved by client side code that will execute a query against the Human Task Manager using the programming API, but before we get to that, let us look at using the supplied BPC Explorer tool that can also be used for this purpose and especially useful during development and testing.
When the BPC Explorer tool is launched, additional views can be added to the set of predefined views. These views can be customized to present different types and content of information. You can click the icon, shown as highlighted in Figure 8, to define the new view.
Figure 8. Creating a new personalized view
Once in the definition for the new view, you can select the tab called View Properties. Within this tabbed panel, there is an entry for selecting additional columns for display that should be taken from the values of custom properties contained within the human task. In the example shown in Figure 9, the custom property called
orderID has been added.
Figure 9. Adding a new column for the custom property
To demonstrate the new column, it is usually a good idea to position it as the first column in the view as shown in Figure 10.
Figure 10. Making the new custom property column first in the table
Figure 11. Saving the new personalized view
Notice that there is a now a new column shown called
orderID, which will show the custom property called
orderID associated with each of the Human Tasks.
Figure 12. Executing the new personalized view
To search for a specific order, you can edit the personalized view, and in the Property Filters tab, enter the property name and property value to be located. In the example shown in Figure 13, the property called
orderID with value
1234 is to be located.
Figure 13. Defining a filter of tasks by custom property
You can execute the search by clicking Search or you can save the personalized view by clicking Save. Saving a view with a property filter in place will re-execute the filter each time the view is shown which may or may not be what is desired. The execution of a search is shown in Figure 14
Figure 14. Executing a filtered search for Tasks with a specific property
Querying Tasks through API
A client can achieve a lookup of a Human Task using the Human Task API query() method with a "where" clause such as:
TASK_CPROP1.NAME='orderID' AND TASK_CPROP1.STRING_VALUE='1234'
This will find tasks that have an
orderID value of
A sample Jython script for running tests is shown in the following:
from javax.naming import InitialContext context = InitialContext() home = context.lookup("com/ibm/task/api/HumanTaskManagerHome") htm = home.create() orderID = raw_input('Enter orderID: ') select='DISTINCT TASK.TKIID' where="TASK.NAME='OrderHumanTask' " + \ "AND TASK_CPROP1.NAME='orderID' " + \ "AND TASK_CPROP1.STRING_VALUE='" + orderID + "'" resultSet = htm.query(select, where, None, None, None) if resultSet.size() == 0: print "No results" else: hasMore = resultSet.first() while hasMore: tkiid = resultSet.getOID(1) print "Task is: ", tkiid hasMore = resultSet.next()
Execute this with the following commands:
set WPSROOT=C:\Program Files\IBM\WID61\runtimes\bi_v61 wsadmin -lang jython -wsadmin_classpath "%WPSROOT%/ProcessChoreographer/client/task137650.jar" <script.py>
When executed, it will prompt for an
orderID and display the Human Task identifier for a Human Task instance that has the associated
This article illustrated a powerful technique to locate individual human tasks through the use of custom properties. There are other solutions for locating task instances, but none are known to neither be as efficient or elegant nor integrate as well with the WebSphere Process Server architecture. The article described the rationale of wanting to locate a unique task as well as the technique for tagging that task with a custom property. Finally, the article illustrated how the correct tasks could be retrieved through both the BPC Explorer supplied user interface and through the Human Task Manager API.
- developerWorks: Dynamic configuration of the Human Task Manager in WebSphere Process Server, 2007-08-22
Read this article for more information about WebSphere Process Server and the Human Task Manager.
- InfoCenter: Replacement variables and context variables
Learn more about replacement variables and context variables.
- IBM InfoCenter: Developing client applications for business processes and tasks
Learn more about developing client applications using tasks.
- WebSphere business integration zone
Get WebSphere Process Server technical articles and tutorials from the Business integration zone.
- IBM developerWorks WebSphere Process Server resource page
Provides technical resources for WebSphere Process Server and WebSphere Integration Developer.
- WebSphere Process Server software support site
Provides information about prerequisites for WebSphere Process Server.
- Discussion forums and newsgroups
Get involved in the WebSphere community by participating in discussion forums and newsgroups.