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.

Back to top

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.

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.

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.

Back to top

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.

Back to top

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.

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.

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.

Back to top

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.

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.

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.

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.

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.

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.

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

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.

Back to top

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

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

About the author

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• An overview of human tasks and queries
• The human task and custom properties technology
• Using the custom property
• Creating the custom property on the task
• Querying for the task
• Conclusion
• Resources
• About the author
• Comments

Next steps from IBM

• Try: WebSphere Integration Developer (in the SOA Sandbox: Connect)
• Demo: Process automation, adoption pattern
• Webcast: Develop innovative applications efficiently using the right application foundation in today's economy
• Briefing: WebSphere flexible business processes
• Buy: WebSphere Integration Developer (in the SOA Sandbox: Connect)

My developerWorks community

Dig deeper into WebSphere on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers