Selecting a human task with custom properties using WebSphere Process Server

WebSphere Process Server V6.1 provides a technology called the Human Task Manager (HTM) that manages the life cycle of people interactions with business processes. An instance of a human interaction is called a task. Associated with a task is meta data called properties. Solution designers and developers can define some of these properties, known as custom properties. This article illustrates the use of custom properties for human tasks to locate specific task instances.

Neil Kolban (kolban@us.ibm.com), IT Specialist, IBM 

Neil Kolban is a member of IBM's TechWorks organization. His goal is to make WebSphere Integration Developer and WebSphere Process Server as easy to understand as they are to use.



26 March 2008

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
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
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
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 orderID values
The set of human tasks, each with their own orderID values

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

%htm:input.\orderDetails/orderID%

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
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
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
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
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
Making the new custom property column first in the table

Finally, you can give the new personalized view a name and save it as shown in Figure 11. This allows you to select and execute the view as shown in Figure 12.

Figure 11. Saving the new personalized view
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
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
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
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 1234.

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 orderID value.


Conclusion

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.

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Business process management on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Business process management, WebSphere
ArticleID=297054
ArticleTitle=Selecting a human task with custom properties using WebSphere Process Server
publish-date=03262008