Dynamic configuration of the Human Task Manager in WebSphere Process Server

Using custom solutions and standard features in WebSphere Process Server and WebSphere Integration Developer to control Human Task Manager behavior

The ability to change task metadata is a requirement in business processes involving human tasks. Canceling a running task re-evaluating metadata due to changes in the business environment are also tasks some customers might require. The Human Task Manager is a component of IBM WebSphere Process Server V6.0.2 that is used to solve various problems that require dynamic configuration of human tasks. This article describes the range of programmatic and dynamic capabilities of the Human Task Manager. It describes advanced scenarios based on an actual client site.

Vivek Gadiyar (gadiyar@us.ibm.com), Architect, IBM

Vivek Gadiyar is an Architect with IBM Business Partner Technical Enablement. He works with ISVs and System Integrators to enable them on the WebSphere platform. Vivek is an IBM Certified IT Specialist and his current focus in on WebSphere SAP Integration. Previously, Vivek worked on several development teams for WebSphere Portal, WebSphere Application Server, Encina++ (OTS). and Encina.



Vikram Desai (vdesai@us.ibm.com), Solutions Architect, IBM

Vikram Desai photoVikram Desai is a Solutions Architect with IBM SWG Business Partner Technical Strategy and Enablement for WebSphere. He has worked with several IBM Business Partners to enable them on WebSphere Platform. Previously he has worked as part of development teams for WebSphere Portal, NextWeb, Federated NAS, WebSphere Application Server and Encina++/Encina. He holds a Masters degree in Computer Science and Engineering from The Pennsylvania State University.



Charles P. Brown (cpbrown@us.ibm.com), Executive IT Specialist, IBM

Charlie Brown is an Executive IT Specialist for WebSphere products. He spent over 20 years with IBM working in robotics, software development, beta support programs (for IBM in the United Kingdom), and for the last six years supporting IBM partners. Charlie's focus is the practical application of product and technology: helping partners and clients develop skills, and then assisting them in being successful in their initial implementations. Charlie is also the author of the IBM Redbook: Experience J2EE. Charlie holds a Bachelors of Science in Mechanical Engineering (M.I.T., 1984) and a Masters of Science in Computer Science (Johns Hopkins, 1989).



22 August 2007

Introduction

The ability to change task metadata, such as expiration and due date at runtime and the ability to cancel a running task and re-evaluate the metadata due to changes in the business environment are requirements for business processes that involve human tasks.

This article examines the out-of-the-box features available in IBM® WebSphere® WebSphere Process Server V6.0.2 (hereafter known as Process Server) and WebSphere Integration Developer V6.0.2 (hereafter known as Integration Developer) that allow dynamic configuration of human tasks at runtime in the Human Task Manager (HTM). It presents a pattern to achieve dynamic configuration changes of running but not-yet-complete human tasks.

The following use cases involving human task are addressed:

  1. Abort a task at runtime.
  2. Transfer a started task to another owner.
  3. Assign the expiration time at runtime.
  4. Dynamic assignment to users and groups.
  5. Change Expiry after task has begun.
  6. Dynamic re-assignment of running task to different users and groups.

Human Task Manager

Human interaction is often an integral piece of business process execution. Human interaction is necessary when a business process reaches execution points where the process cannot continue without manual intervention. Some examples of these activities include manual approval and data entry steps. A real-life example could be a business process that calculates an auto insurance quote. Normally such a process will read in the user details and automatically generate a quote, but in certain circumstances, such as driver risk above average, it cannot automatically compute the cost and has to redirect the request to a human. HTM component within WebSphere Process Server enables the definition of components, which allows humans to interact with a business process. The interaction itself can be initiated by a person or by a service. For more information, see the WebSphere Process Server Information Center in the Resources section.

Human tasks are defined using WebSphere Integration Developer. The HTM exposes various setting for configuration of human tasks. In addition to WebSphere Integration Developer, programmatic access to human tasks is available within the HTM component in WebSphere Process Server. In this article, we will look at some of the dynamic configuration and programmatic capabilities available for human tasks.

Using standard features and custom solutions for specialized HTM behavior

HTM provides a flexible suite of capabilities that allow you to customize your business process flows so that you can incorporate human intervention tasks with a wide range of specialized behavior. You can choose from standard APIs and out-of-the-box features, configure dynamic runtime actions, or prepare home-grown solutions from a mix of these options. Here is a summary of the options that are available:

Using HTM programmatic capabilities

WebSphere Process Server and the HTM support implementation of a custom application client to control business processes and human tasks by programming to the HTM and Business Process Choreographer APIs. You can use the Task API to control running human tasks such as Display Tasks, Abort, Query by Task ID, Claim, Complete, Cancel, Suspend, and Resume. These APIs are used to build custom Web applications that control human tasks, see Resources. The Display tasks section and the Abort section show examples of using this API for Display Tasks and Abort.

Building a custom User Interface with WebSphere Integration Developer

The programming capabilities enable your customer to build custom user interfaces to interact with human tasks. An orthogonal but related capability is the wizard-based User Interface generation using WebSphere Integration Developer (Integration Developer). This feature is available in Integration Developer V6.0.2. The wizard takes the programmer through the steps of creating a J2EE Web application based on Java Server Faces that can be deployed to Process Server or a standalone WebSphere Application Server instance.

A snapshot of the context menu and the view of the generated application are shown below in Figure 1 and Figure 2.

Figure 1. Snapshot of the context menu
Snapshot of the context menu
Figure 2. View of the generated application
View of the generated application

Using HTM dynamic capabilities

When a task instance or process requires retrieval of variables during runtime, you can use replacement expressions that can be evaluated on the fly. For example, your customer may need to dynamically assign a task to a user or group whose identity must be determined based on a set of criteria dependent on data that becomes available at runtime. You may also need to assign an expiration time that must be retrieved from an outside source at runtime. These specialized cases and example solutions are described in the section, Using dynamic capabilities in HTM.

Using a mix of standard and custom configurations

Some projects may require a mix of standard features and custom coding to achieve the desired behavior. The section, Using HTM for advanced scenarios, describes two solutions designed for a Systems Integrator (SI). The solutions use both the standard HTM API and customized code snippets to allow the customer to reschedule a task after it had begun, and to reassign a running task to a different user or group.

Programmatic capabilities

WebSphere Process Server and the HTM support implementation of custom application clients to control business processes and human tasks by programming to the HTM and Business Process Choreographer APIs. For more information, see the Task API.

These APIs are used to build custom a Web application that controls human tasks. Example usage is shown below.

Display tasks

A sample query that was used to retrieve participating tasks that the current authenticated user has access to from the HTM database is shown below. The QueryResultSet works similarly to ResultSet in JDBC API.

Listing 1. Retrieving all tasks using Task API
InitialContext initialContext = new InitialContext();

// Lookup HumanTaskManager bean home
LocalHumanTaskManagerHome lhtmHome = 
(LocalHumanTaskManagerHome) 
initialContext.lookup 
("java:comp/env/ejb/LocalHumanTaskManagerHome");
LocalHumanTaskManager htm =
 lhtmHome.create ();
QueryResultSet resultSet = htm.query(
"DISTINCT TASK.ACTIVATED,
TASK.COMPLETED,TASK.DUE,
TASK.EXPIRES, TASK.FIRST_ACTIVATED,
TASK.KIND,TASK.LAST_MODIFIED, 
TASK.LAST_STATE_CHANGE, 
TASK.NAME,TASK.NAME_SPACE, 
TASK.ORIGINATOR,  TASK.OWNER, 
TASK.PRIORITY, TASK.STARTER, TASK.STARTED, 
TASK.STATE,TASK.TYPE, TASK.IS_ESCALATED, 
TASK.IS_INLINE,TASK.SUSPENDED,
TASK.SUPPORT_AUTOCLAIM, 
TASK.SUPPORT_CLAIM_SUSP,TASK.
SUPPORT_DELEGATION,TASK.TKIID", "TASK.KIND= 
TASK.KIND.KIND_PARTICIPATING", null, null, null, null);

Abort

The HumanTaskManager API supports a terminate function that takes the task instance ID as an argument. The terminate task can be called only on standalone human tasks, inline human tasks cannot be terminated with this API, for inline human task the enclosing process can be terminated by using the Business Process Choreographer API. A code snapshot is shown below.

Listing 2. Aborting a task using Task API
InitialContext initialContext = new InitialContext();
// Lookup HumanTaskManager bean home
LocalHumanTaskManagerHome lhtmHome = 
(LocalHumanTaskManagerHome) initialContext.lookup
("java:comp/env/ejb/LocalHumanTaskManagerHome");
LocalHumanTaskManager htm = 
lhtmHome.create ();
htm.terminate (taskId);

Important points to keep in mind

As we have seen above, it is possible to use to the Task API to control running human tasks. It is also possible to:

  • Query by Task ID
  • Claim
  • Complete
  • Cancel
  • Suspend
  • Resume

For more information, refer to the Task API reference.

Using dynamic capabilities in HTM

Replacement expressions for runtime evaluation

Replacement expressions are used in template description of human tasks, activities, and processes so that they can be evaluated at runtime using the process variables or input and output messages. The values of staff variables such as originator, starter, owner, or the task variables such as instance ID are not known at development time. Replacement expressions are used in the templates and provide a way to determine the real values of these variables for a given process or task instance at runtime. There are predefined expressions for some type of variables. It is also possible to retrieve values from user defined process variables. The list of variables and the corresponding replacement expression is available at: WebSphere Process Server Information Center.

Dynamic assignment to users and groups

In this section, we describe how replacement expressions are used for dynamic assignment of tasks to users and groups at runtime.

The human task can be statically assigned to a user or a group in the human task editor. In the static case, the verb user by userID or group by groupID is assigned a static user name or group name. This assumes that the user name or group name of the potential owner(s) is known at design or implementation time. In most cases, the user name is not known at design/implementation time. Therefore, it is necessary to assign the human task to a staff member dynamically at process execution, based on some criteria computed at runtime. In the dynamic case, we will use variables that will resolve to users or groups at runtime. We will continue to assign the potential owner using the Staff Group (Verb) Users by user ID

Replacement expressions are used instead static values to assign the user name. The actual value for the replacement expression is computed based on the input message.

A sample process with an inline human task is shown below in Figure 3:

Figure 3. Sample BPEL to demonstrate Dynamic Staff Assignment
Sample BPEL to demonstrate Dynamic Staff Assignment

In this process, the human task is assigned to a user based on the skill requirement passed in as an input to the business process. The Java snippet ComputeUserIDSnippet assigns a value to the userID. The code in the Java snippet initializes userID to the correct value for potential owner based on the value of the input attribute skillsRequired. The default value for userID is "user1". However, if skillsRequired is software, then userID is assigned to "user2".

Listing 3. Code-snippet that initializes variable representing potential owner
//default userID = user1
System.out.println(" skill required is : " + input1.getString(""skillRequired"));
if(input1.getString("skillRequired").equals("software"))  {
	System.out.println("Setting userID to user2");
	userID = "user2";
Figure 4. Replacement expressions that queries process variables "userID"
Figure 4. Replacement expressions that queries process variables "userID"

In the figure above, the staff group is set to "Users by user ID". The replacement expression states that the real value for the name UserID is obtained from the variable userID. This is expressed as: %wf:variable.userID%

Important: Notice that the variable used is a process variable, which is available only to an inline human task.

If dynamic staff assignment is required for standalone human task, then the replacement expression used is described in the next section. In addition, in the section on dynamic staff reassignment, we show how a replacement expression is used with a standalone human task to set and change potential owner of the task.

Assign the expiration time at runtime

You can set a duration value for your human task to either specify how long the task will hold, before it is due, set to expire, or is deleted. The different duration settings are shown below in the table, (taken from the Information Center):

Table 1. Duration settings
OptionDescription
Duration until dueUse this field to set the period that will elapse between the time this task is assigned and the time that it is expected to be completed. This field id provided for client programs only, reaching the due date will not cause actions within the HTM.
Duration until deletedUse this field to set the period that will elapse between the time this task reaches an end state and the time that it will be removed from the system. End states include finished, failed, terminated, expired and forwarded
Duration until expirationUse this field to set the period that will elapse between the time this task is assigned and the time it is expected to be completed. This setting is very similar to 'Duration until due' , the difference is, at expiration time, the HTM takes actions: changes the task's state.

As with staff assignments, it is possible to determine the expiration time at runtime from variables defined for the process or from the inputs to the HTM. A sample is shown below.

The interface to the human task is as shown below. The expiration value is passed as an input to the business process. The business object HTMetaData has a field expires.

Figure 5. Interface Definition
Interface Definition

The figure below shows how duration to expire is set for standalone human task. For an inline human task, the expiration value is set differently from that for standalone human task. This article explains the differences following the explanation for standalone human tasks.

Figure 6. Use of replacement expressions to set Duration to Expire
Use of replacement expressions to set Duration to Expire

You will notice the value of the replacement expression is: htm:input.testSetDurationParameters\input1/expires

How did we arrive at this value? The variable is constructed from the input to the standalone human task. The input for the human task is determined from the interface and operation implemented by the human task. To determine the value of the input, you will open the interface WSDL file in a text editor it is as shown below.

Figure 7. WSDL Definition showing message details
WSDL Definition showing message details

The input to the operation (testSetDuration) implemented by the human task is the highlighted WSDL message; the name of the part within the input message is the name of the input variable.

The replacement expression is of the form:

htm.input.<variableName>\<xpath expression to get to the desired field>

The name of the variable as determined from the wsdl file shown in Figure 10 is:

testSetDurationParameters

Now to determine the xpath, we are looking at the value contained in expires within the type HTMetaData within testSetDurationParameters. The input variable testSetDurationParameters is an element form testSetDuration (defined in the wsdl:types section ), which has an element of name input1. The root of the xpath expression is input1. The element input1 is of type HTMetaData.

The HTMMetaData is defined in a XSD as shown below:

Listing 4. XML Schemas for HTMetaData
<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd=
"http://www.w3.org/2001/XMLSchema" targetNamespace=
"http://SetHTDurationsModule">
  <xsd:complexType name=
  "HTMetaData">
    <xsd:sequence>
      <xsd:element minOccurs="0" name="expires" type="xsd:string"/>
    </xsd:sequence>
  </xsd:complexType>
</xsd:schema>

The name of the element whose value we are interested in is expires. Thus the xpath to get to this is input1/expires. These values help us form the replacement expression:

htm.input.testSetDurationParameters\input1/expires

If you were using an inline human task as shown below in Figure 8, the interface to set duration until expiration is grayed out in the human task editor.

Figure 8. Inline human task duration until expiration property setting is disabled
Inline human task duration until expiration property setting is disabled

You can set the expiration when using an inline human task by setting the expiration for the human task activity in the process editor.

Figure 9. Setting expiration for human task in process editor
Setting expiration for human task in process editor

Using HTM for advanced scenarios

This section discusses a few unique scenarios that we encountered while working with a large System Integrator (SI). In addition to the dynamic capabilities presented in previous sections, the SI wanted solutions for manipulating tasks that had started and assigned. For example, the SI wanted to restart an assigned task with a new expiration or revoke a started task from one group and assign it to another.

The solution involved wrapping the task in a subprocess and implementing a custom BPEL around the task invocation to support the redo. The task invocation sits in a while loop. An authorized person pseudo-completes the task, which returns a special return code. The return code is used to determine whether control should loop back to the beginning of the while statement and re-execute or fall out in case the task is truly complete. The second element of the solution is it is necessary to provide a way for the authorized personnel to supply the new values for human task properties.

The human task is wrapped in a subprocess for better encapsulation. The main process tends to contain the high-level overview of the business process. The business process is muddied if every human task invocation is decorated with the additional control logic that has nothing to with the main business process. Also, a subprocess offers better reuse when possible.

The following sections present details of the solution that we developed for this SI.

Transfer a started task to another owner

HTM API offers a method to transfer a started task from one user to another using the task identifier as a String or an object of type TKIID.

Listing 5. TransferWorkItem Task API
public void transferWorkItem
   (String tkiid, int assignmentReason, String fromUser, String toUser );....
public void transferWorkItem
   (TKIID tkiid, int assignmentReason, String fromUser, String toUser)....

The caller must be an owner, starter, originator, or administrator of the task instance. There are more details of when this API can be used in the Business Process Choreographer API Javadoc.

This capability can be demonstrated using the Business Process Choreographer Explorer using the transfer button for a task.

Reschedule after task has begun

Since Process Server and Integration Developer do not support changing the properties of a task once those properties have been evaluated and started, it is necessary to investigate alternate means to achieve this requirement. Basically, the API does not support a setDurationForExpiration() method. This section outlines one solution to change the expiration after the task has started.

Figure 10. BPEL wrapper to implement Reschedule
BPEL wrapper to implement Reschedule
Figure 11. ReviewRequest and ReviewResponse Business Objects
ReviewRequest and ReviewResponse Business Object

Figure 10 shows how reschedule functionality can be implemented using BPEL. For this pattern to work, the duration to due has to be set dynamically as explained previously in section, Assign the expiration time at runtime. The replacement expression for a standalone human task invoked by the process with the input ReviewRequest business object is shown below in Figure 12.

Figure 12. Replacement expression for dynamic duration setting
Replacement expression for dynamic duration setting

The algorithm is described below:

  1. A listed Administrator, claims the task and pseudo-completes the task and sets a special status string in TaskMetaData (see Figure 11), such as, REDO.
  2. If the status string is REDO, set the WhileLoopCond flag to true and start the task again with the new expiration value. This is shown in the Java snippet BPEL activity SetValuesIfNecessary (see Figure 13).
  3. The Java snippet also reinitializes ReviewRequest with new values for expiration, as shown in Figure 13 below.
Figure 13. Code Snippet from Java snippet
Code Snippet from Java snippet

By following this pattern, a new human task is created with modified values for metadata. The task is not automatically claimed but it is presented for the user and groups to claim to apply the modified metadata.

Dynamic reassignment of running task to different users and groups

Dynamic reassignment to a different user or group may be required once a process invokes a human task and the task has been assigned to a staff member. The transfer API allows transfer of a work item from one user or group to another. Here we present an alternative approach to do the same using the pattern presented earlier. An authorized user pseudo-completes the task and changes the metadata before the task is reexecuted. The metadata relevant to this section is the new owner name for the task. The figures below show how the potential owner is changed from user1 to user2.

Figure 14. Replacement expression using metadata to set owner
Replacement expression using metadata to set owner

Figure 15 shows a snapshot of the Test Tool wherein an Administrator has assigned a task to user1.

Figure 15. Administrator assigns review task to user1
Administrator assigns review task to user1

The Administrator decides to assign the task to user2. In this exercise, the Administrator used the Business Process Choreographer Explorer to claim the task and set the new values in taskMetaData. Figure 16 shows the response as seen in the Test Tool in Integration Developer.

Figure 16. Administrator decides to reassign task to user2. Notice the new expiration.
Administrator decides to reassign task to user2.
Figure 17. Review Task is assigned to user2
Review Task is assigned to user2

Figure 18 indicates that user2 claimed the task and completed it. The completion is indicated in user2 comments stating, "Done". In this exercise, user2 used Business Process Choreographer Explorer to claim and complete the task.

Figure 18. User2 completes the review task
User2 completes the review task

Conclusion

In this article, you learned about the range of programmatic and dynamic capabilities of HTM. You also learned about the out-of-the-box capabilities, and hopefully, gained knowledge from the advanced scenarios that the authors encountered at a client site.

Acknowledgments

We would like to thank the following IBMer's for helping us prepare and improve this article: Catherine Rivi, Jeff Kaminski, Tendai Chinoda, Gerhard Pfau, Andreas Arning, and Thomas Bernhardt. We appreciate the time and effort they devoted to improve the quality of this article.


Download

DescriptionNameSize
code snippet zipHTMCodeSnippet.zip2KB

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 WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere, Business process management
ArticleID=249713
ArticleTitle=Dynamic configuration of the Human Task Manager in WebSphere Process Server
publish-date=08222007