Introduction

In Part 1 of this series, we introduced an on demand business process scenario for an Order to Manufacturing Processing System (OTMPS). This article describes how to integrate human intervention in the process with staff activities. A staff activity is a step in the process that is manually performed through interaction with a person. This interaction is performed using a client user interface, such as a Web client running in a browser. Staff activities are assigned to people in the organization through work items. When a staff activity is invoked, work items are created for the potential owners. One of these persons will later claim the activity and become responsible for it by providing the relevant information and ensuring that the activity is completed.

Back to top

Staff activity resolution in WebSphere Business Integration Server Foundation Process Choreographer

As shown in Figure 1, the main components involved in staff resolution are the Web client, Process Choreographer engine, work item manager, staff support service, staff resolution plug-ins, and staff repositories.

The Web client is based on Java Server Pages (JSP). It provides users a set of worklists containing work items, on which they can perform queries, view further details, or perform certain actions. Each work item represents a process instance, an activity, or an event, on which the user is allowed to perform certain actions. The potential owner of the item can claim or complete the task. The Web client interacts with the process choreographer engine through the process API.

The Process Choreographer engine is responsible for controlling the state transitions for the process instances and for the activities in these process instances.

The work item manager is responsible for creating and deleting work items, executing work item queriesm, and invoking staff support services to enforce authorization.

The staff support service controls access to the staff resolution plug-ins, transforms the staff query verbs into plug-in specific queries, and delegates staff resolution requests to these specialized plug-ins.

The staff resolution plug-ins are specific to different repositories such as, Lightweight Directory Access Protocol (LDAP) directories or user registries. They retrieve staff information from the external staff repositories and execute the staff queries. For more information about the staff resolution architecture, please refer to the "Staff Resolution Architecture" article under Resources.

Back to top

Staff activity in the OTMPS Scenario

In Part 5 of this series, we illustrated how to add a fault handler to a process. In this section, we describe an example of using a staff activity in a fault handler.

In the OTMPS scenario, we added a fault handler for the Validate & Generate Topology activity to capture faults generated in that activity. When any exception happens in this activity, the process enters into the fault handler, which requires human intervention. A work item is generated for the potential user -- for example, the user "Joe," who is in an "Administrator" role. Later, when Joe logs into the process Web client, he will see the work item under his "My To Dos" list.

Through the user interface, Joe can see the input from the process and details on what went wrong in the process. He can then make decisions on the flow of the process -- to restart or terminate the process. For instance, if the error message tells Joe that the Configuration service is not reachable, Joe may make a phone call to the Configuration service staff to find the cause of the problem and when the service will be available. If the problem can be fixed and the service is available again, Joe can decide to restart the Order Processing process. But if the error is fatal and Joe cannot fix the problem, he can decide to terminate the process and notify the support team. After Joe enters his response, it is sent back to the process. The process will then execute a path according to his response, and the work item is completed.

Back to top

How to add a staff activity to a fault handler process

A staff activity is introduced at the place in the process at which human intervention is needed. A staff activity component provides one or more operations that have associated input and output messages and are implemented as an interaction with people through an appropriate user interface. In the following section, we describe a method for adding a staff activity to a fault handler process. The required steps are:

1. Create a staff activity interface
2. Add a staff activity into the process
3. Add staff roles, verbs, and parameters
4. Integrate user interface pages for staff activities
5. Select the staff resolution plug-in and parameters
6. Deploy the process with appropriate staff resolution plug-in

Step 1: Create a staff activity interface

First, you need to define an interface with the appropriate operations for the staff activity. These operations define the input and output messages of the staff activity.

To create a Web Service Definition Language (WSDL) interface file, you can either directly use the WSDL wizard or build it from a Java class using WebSphere Studio Application Developer Integrated Edition tooling. To create a WSDL interface file from a Java class, write the Java class with the appropriate signature method. The method doesn't need a concrete implementation. For example, consider the Java class in Listing 1.

				
package Process.ExceptionHandler;

public class StaffActivity {

	public boolean  staffAction(ExceptionInput input)
	{
		return true;
	}
}

You then generate a new WSDL file from this Java class, by selecting the WebSphere Studio Application Developer Integrated Edition Service build from feature. In the following Create Service screen, choose the Java template to build the new service. In the Select Methods screen, you simply check the methods that you want to expose as service operations.

In addition to the WSDL interface files StaffActivity.wsdl, the binding and service file StaffActivityJavaBinding.wsdl and StaffActivityJavaService.wsdl are automatically generated. But, since the binding and service files are not needed in our scenario, you can delete these two files.

Figure 2 shows the staff activity Port Type with the service operation and associated messages.

Step 2: Add the staff activity into the process

A process that includes a staff activity must be a macroflow. As shown in Figure 3, you insert the staff activity by selecting the Staff icon from the Business Process Execution Language (BPEL) editor palette to the ExceptionHandler process. In the Implementation screen of the Staff activity, click Browse and link to the interface you created in the last step. Select the Port Type and Operation by using the Port Type and Operation drop-down menus. Create new Request and Response variables for the staff activity by clicking the New buttons. Figure 3 shows the implementation property of the staff activity. It is linked to PortType "StaffActivity" and operation "staffAction". The variables StaffIn and staffOut are generated.

The input data used by the staff activity may be different from the process input data. We need a Java Snippet for the Staff activity to map input data to staffIn data.

You should add additional logic in your process -- for example, what to do after the staff activity returns. In the OTMPS scenario, there are two execution paths after the Staff activity returns, as shown in Figure 4. If the staff's answer to the exception is to terminate the process, a Java snippet will notify the support team and a BPEL "Terminate" activity will stop the process. If the staff's answer is to restart the process, a Java snippet will be executed to map the data, and the OrderProcessSystem process will be invoked again. You can implement these functions in Java snippets or by invoking other services.

Step 3: Add staff roles, verbs and parameters

The above staff activity operation (staffAction) is performed by people in the organization with different roles. A staff activity task is assigned to a role. You can use verbs to specify the staff members associated with the defined role. Figure 5 shows the Staff property sheet of the above staff activity with the potential roles and verbs.

The Process Editor defines roles, such as "Potential Owner," "Editor," "Reader," or "Administrators." The Process Editor also provides a set of predefined staff query verbs in a file VerbSet.xml. These verbs (for example, userID, users by User ID, everybody) are parameterized abstract query templates, which can be used to define concrete staff queries against a staff repository, such as LDAP. At deployment time, these verbs are transformed into queries specific to the repository. For example, the verbs defined in the WebSphere Business Integration ServerFoundation Process Choreographer are transformed into LDAP-specific queries. For more details on the verbs, queries, and query transformation, please refer to the "Staff Resolution Parameter Reference" under Resources.

People are assigned to the staff activity by means of staff queries. In the OTMPS scenario, we specify a staff query with the "Potential Owner" role and the "Users by user ID" verb to assign members to this role. The "Users by user ID" verb allows you to define a number of query parameters, such as user ID (for example, Joe). Even though it is not recommended to hardcode user names as parameters, this verb is useful in combination with context queries. As shown in Figure 5 we set the parameter "UserID" to %wf:process.starter%.

The verb "Users by user ID" is supported by LDAP and the user registry. We used the WebSphere User Registry as a staff repository for users (for example, Joe and Sam) and groups (for example, administrators, users, and staff). (See Resources for a link to more information about WebSphere User Registries.)

A potential owner (for example, an OTMPS administrator) at runtime can claim the staff activity to work with it, thus becoming the owner of the activity and ultimately completing it. When a work item is created for a staff activity, it is created for the person identified by the "Users by user ID" verb. Specifically, a work item will be generated for the user who started the current process instance. This user information will be retrieved from the user registry. For example, if "Joe" started the process, the details of his information (for example, name, associated roles, and credentials) are retrieved from the WebSphere user registry and a work item is created for "Joe".

When you deploy the process into a production environment, you may want to use another registry solution.

Step 4: Integrate user interface pages for staff activities

Anytime you want your process to communicate with an external user, use the client capabilities of the Process editor. For example, consider a staff member that has been assigned a work item by the staff activity task of the process. You can use the default Process Web Client and deliver this task to him.

The default Process Web client is only intended for testing and as a functional sample to serve as a starting point for customization. For a custom look and feel, write a customized Web client or a custom application.

In the Client property of the staff activity property sheet, as shown in Figure 6, you can define the JSP pages you want to use to interact with the staff. These JSPs are embedded inside the Process Web Client. Also, you can use WebSphere Portal as the client interface to manage the tasks. To integrate the process with the Portal, use Portal settings to specify a unique Client UI identifier for this task. This identifier will be used by the Portal server to look up the task page definition.

To write your own custom application to handle work items and process lifecycle events (for example, process start and process end), you can use the Process Choreographer APIs to interact with the process. Listing 2 contains an example that shows how to retrieve a personal work list using the process APIs for the user "Joe" who logged into the web client with an "Administrator" role.

				
import com.ibm.bpe.api.*; 
   ... 
   InitialContext initialContext = new InitialContext(...); 
 
   // lookup the EJB home interface 
   Object object = initialContext.lookup("com/ibm/bpe/api/BusinessProcessHome"); 
   BusinessProcessHome processHome = (BusinessProcessHome) 
       javax.rmi.PortableRemoteObject.narrow(object, BusinessProcessHome.class); 
 
   // get the remote interface 
   BusinessProcess process = processHome.create(); 

   // run a query to show all activity names that are ready to be started 
   // and that I can claim (where I have a potential owner work item) 
   QueryResultSet resultSet = process.query( 
      // select clause - what do we want to get? 
      "PROCESS_INSTANCE.NAME, ACTIVITY.TEMPLATE_NAME",  
      // where clause - what are the qualifying rows? 
      "WORK_ITEM.REASON=WORK_ITEM.REASON.REASON_POTENTIAL_OWNER AND " + 
     "ACTIVITY.STATE = ACTIVITY.STATE.STATE_READY", 
      // order clause - specify the sort order 
      "PROCESS_INSTANCE.NAME", 
      // threshold - return first 10 entries only 
      new Integer(10),  
      // no timezone specified 
      null 
   ); 

   // loop over results in the result set 
   while( resultSet.next() ) 
   { 
      // print out selected columns, keep in mind column indexes start with "1" 
      System.out.println( "Process instance name = " + resultSet.getString(1) ); 
      System.out.println( "Activity template name = " + resultSet.getString(2) 
); 
   } 

For more details on developing a custom web client, please refer to the article "Developing a custom Web client for Business Process Choreographer with WebSphere Studio Integration Edition," listed under Resources.

Step 5: Select the staff resolution plug-in and parameters

Because WebSphere Business Integration Server Foundation Process Choreographer delegates staff resolution to plug-ins, you can use various types of enterprise directories. The staff resolution plug-ins are responsible for dealing with the retrieval of staff information from an external subsystem (for example, an LDAP directory). The list of providers supported by Process Choreographer includes user registry, LDAP, and system registry.

In OTMPS, we used WebSphere User Registry for storing information about users and groups interacting with the system. We used the user registry staff plug-in provider to connect to the WebSphere User Registry with configurations. This provider uses the users and groups that are known to the WebSphere Application Server and requires WebSphere global security to be enabled. As shown in Figure 7, this staff plug-in configuration contains a reference to an XSL transformation file, which is used to transform the Process Choreographer staff query verbs into queries specific to the user registry provider. For our scenario, we are using the default transformation script provided by Process Choreographer. We could configure these staff plugin providers by selecting the Staff tab in the server configuration window.

Step 6: Deploy the process with staff resolution provider

During the BPEL Deploy code generation, select the correct JNDI name for the staff plug-in configuration to be used when the application is deployed. As shown in Figure 8, we select bpe/staff/userregistryconfiguration as the JNDI name. This is the JNDI name you defined for the staff plug-in configuration in Step 5. When the EAR is deployed, the staff support service uses this JNDI name to locate the staff plug-in configuration and invokes the corresponding native provider APIs.

Back to top

How staff activities are invoked

At runtime, when the Staff activity is reached, the Process Choreographer engine creates the work items that can be claimed by any staff member who is a potential owner of the work item. Users who are the potential owners of work items will log in to the default process Web Client and see a screen similar to the one shown in Figure 9.

Once the work item is claimed by the eligible owner, the request variable and its contents are displayed to that person. The person completes the work by entering the data for the response variable and passing the variable back to the process. Figure 10 shows the default user interface.

Back to top

Conclusion

This article described staff activities in WebSphere Business Integration Server Foundation and gave examples of their usage in the OTMPS scenario. It illustrated, step-by-step, how to add a staff activity in a workflow and how the work items are created by the process and retrieved by the process clients. In addition, we described the relationship between user roles, registries, and the staff resolution components.

Resources

• Read all parts of the On demand business process life cycle, and keep track as we add new installments.
  
  
• Read these articles and InfoCenters for additional information on Process Choreographer:
  • "Business process choreography in WebSphere: Combining the power of BPEL and J2EE"
  • "Websphere Application Server Information Center"
  • "Staff Resolution Architecture"
  • "Staff Resolution Parameter Reference"
  • "Work items and the query() API call"
  • "WebSphere Application Server Enterprise Process Choreographer Programming model for staff resolution"
  • "Developing a custom Web client for Business Process Choreographer with WebSphere Studio Integration Edition"
  • "WebSphere User registries"
  
  
  
• Get your hands on application development tools and middleware products from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere®. You can download evaluation versions of the products at no charge, or select the Linux® or Windows® version of developerWorks' Software Evaluation Kit.
  
  
• Browse for books on these and other technical topics.
  
  
• Get involved in the developerWorks community by participating in developerWorks blogs.
  
  
• The IBM developerWorks team hosts hundreds of technical briefings around the world which you can attend at no charge.
  
  
• Want more? The developerWorks SOA and Web services zone hosts hundreds of informative articles and introductory, intermediate, and advanced tutorials on how to develop Web services applications.
  
  

About the authors

Comments

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Staff activity resolution in WebSphere Business Integration Server Foundation Process Choreographer
• Staff activity in the OTMPS Scenario
• How to add a staff activity to a fault handler process
• How staff activities are invoked
• Conclusion
• Resources
• About the authors
• Comments

Local resources

• IBM Innovation Center - Austin, TX
• IBM Innovation Center - Chicago, IL
• IBM Innovation Center - Dallas, TX
• IBM Innovation Center - San Mateo, CA
• IBM Innovation Center - Waltham, MA
• Technical Briefings in North America

My developerWorks community

Dig deeper into SOA and Web services on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers