Invoking a service from a task API event handler in WebSphere Process Server V7

WebSphere® Process Server supports different types of human tasks. Each task type has a lifecycle with well-defined states, which emit events to signal the occurrence of such states. This tutorial shows how to create a task API event handler and how to invoke a service from the handler.

Samir Nasser (snasser@us.ibm.com), Senior Managing Consultant, Certified IT Specialist, IBM

Photo of Samir NasserSamir Nasser is a Senior Managing Consultant and Certified IT Specialist with the IBM Software Services for WebSphere team in Durham, North Carolina. He is currently architecting and developing SOA solutions based on the WebSphere family of products.



28 September 2011

Also available in

About this tutorial

Many long-running processes with human tasks must execute one or more service for each human task. One way to do this is to model the service invocation activities in parallel with human task activities in a process model. However, this approach has two drawbacks:

  • The process model can easily become cluttered.
  • It only implements one business requirement scenario where service invocation occurs in parallel with a human task creation.

WebSphere Process Server provides the task API event handler mechanism that enables you to execute any kind of logic, including a service invocation at the various task states (not just when the task is created). This tutorial demonstrates this capability of WebSphere Process Server.

Objectives

You will learn to create a task API event handler and to invoke certain services from the handler.

Prerequisites

You need to be familiar with WebSphere Integration Developer V7.0.0.3.

System requirements

You need a machine with at least 2 GB of physical memory.

Duration

This tutorial takes about 1 hour to complete.

Download file

There is one project interchange file listed in the Download section of the tutorial: PI_Final.zip.


Introduction

WebSphere Process Server (hereafter called Process Server) supports a number of human task types, namely standalone, ad hoc, and inline. Each task type has a lifecycle that consists of states and transitions between states. Process Server manages these task states and enables you to provide the following plug-in types to customize the task-related logic:

  • Task API event handler: This is executed by the Process Server task container at specific points before or after the task API call
  • Task escalation notification event handler: This is executed by the Process Server task container when a task is escalated.
  • People resolution plug-in: This is executed by the Process Server task container to customize the returned result set of task-related users, such as task potential owners.

The purpose of this tutorial is to provide a step-by-step procedure to develop, configure, and test a simple task API event handler and invoke a service from the task API event handler.


Using the sample code

After you import the project interchange PI_Final.zip into WebSphere Integration Developer V7.0.0.3, you will have three projects in the Business Integration perspective:

  1. MyProcess: An SCA project
  2. Task Event Handler: A Java™ project
  3. MyService: An SCA project

The MyProcess project contains a simple long-running process that essentially contains an inline human task activity that is configured with a task API event handler. When the process navigation reaches the inline task activity, the task container checks the configured task API event handler and executes the handler methods in the right order with respect to the task API calls.

The Task Event Handler project contains the task API event handler TaskEventHandler that will be executed by the task container. This happens when the process navigation reaches the inline human task activity in the long-running process that is in the MyProcess project.

The MyService project contains a simple Java component exposed as an SCA service that is executed by the task event handler when the handler is executed.


Creating the task API event handler

Follow these steps to create the task API event handler:

  1. Create a Java project and add the Process Server runtime library to it. The tutorial creates the Java project Task Event Handler.
  2. Create an optional, but recommended, Java package in the src folder. If the package is not created, the default package is used (as is done in the tutorial).
  3. Create a Java class that extends the com.ibm.task.spi.APIEventHandler class. You have the option to create a handler that implements the APIEventHandlerPlugin5 interface. However, extending the APIEventHandler class is recommended because if there is any future change in the task API with future product releases, APIEventHandler of the new release will provide a default (do nothing) implementation of the various declared methods in the APIEventHandlerPlugin5 interface or potentially other interfaces.
  4. Override the appropriate methods of the APIEventHandler class. Which method is overridden depends on the business requirements. The tutorial overrides the preCreateTask and postCreateTask methods.

Listing 1 shows the preCreateTask method of the TaskEventHandler plug-in.

Listing 1. The preCreateTask method
public void preCreateTask(TaskModel newTaskModel, TaskTemplate template, 
 Serializable inputMessage, ReplyHandler replyHandler) throws ApplicationVetoException {
	ServiceManager serviceManager = new ServiceManager();
	Service myService = (Service) serviceManager.locateService("MyServiceIntPartner");
	myService.invoke("getIt", "preCreateTask method is executed.");
}

This is a simple implementation of the preCreateTask method. The task container of Process Server executes this method in the context of the Java EE application that represents the logic implemented in the MyProcess SCA project before the task is created. This implementation shows how to invoke a service that is located in the MyService SCA module, which is a different SCA module from MyProcess. To invoke the service in the MyService module, the preCreateTask method:

  1. Gets a reference to the singleton service ServiceManager as shown in the ServiceManager serviceManager… line.
  2. Looks up the service MyServiceIntPartner as shown in the Service myService… line. MyServiceIntPartner is the service reference that points to the Java component exposed as an SCA service in the MyService project.
  3. Invokes the method getIt of the MyServiceIntPartner service reference as shown in the myService.invoke… line.

The task API event handler TaskEventHandler is configured as a Java EE service provider. To configure it, follow these steps:

  1. Create the META-INF/services folder in the root of the Task Event Handler project.
  2. Create a text file called com.ibm.task.spi.plug-inNameAPIEventHandlerPlugin in the META-INF/services folder. Replace plug-inName with an arbitrary text that may appropriately be your event handler class name. For the tutorial, the event handler class name is TaskEventHandler.
  3. Type the fully qualified name of the plug-in name (package.name) in the first line of the text file. For the tutorial, the default package is used. So, the first line in the text file is TaskEventHandler.
  4. Save the text file com.ibm.task.spi.plug-inNameAPIEventHandlerPlugin.

Registering the task API event handler

Now that the task API event handler is created and configured as a Java EE service provider, how do you execute it before and after the Approver task (the inline task in the CreditProcess process in the MyProcess project) is created? The following steps show one way to register the task API event handler:

  1. Double-click the assembly diagram icon of the MyProcess project to open the assembly diagram.
  2. Double-click the process CreditProcess to open the long-running process.
  3. Double-click the Approver task in the CreditProcess process.
  4. Click the Details tab of the Properties view of the opened task.
  5. Enter the task API event handler name in the Event handler name field. The handler name is TaskEventHandler for this tutorial as shown in Figure 1.
Figure 1. Task API event handler
Task API event handler

In general, there are a number of ways to register a task API event handler. You can register the handler in any of the following ways:

  1. Use the setEventHandlerName() method on the TTask object for ad hoc tasks.
  2. Dynamically update the task API event handler name on a task object using the update() method of the task object.
  3. Specify the event handler name on the task model as was done in this tutorial. So, all tasks created from this task model will use the same event handler.

Installing the task API event handler

The task container executes the task API event handler before the Approver task is created when the process navigation reaches the task activity in the CreditProcess process in the MyProcess project. For that to occur, the Task Event Handler Java project needs to be available at runtime when the CreditProcess process is executed. The following steps show one way to make the Task Event Handler project available at runtime:

  1. Double-click the dependencies icon of the MyProcess project.
  2. Add the Task Event Handler project as a dependent project in the Java section of the dependencies editor as shown in Figure 2.
Figure 2. Task API event handler as a dependent
Task API event handler as a dependent

Note that the Task Event Handler project will be deployed with the MyProcess project as designated in the check box in Figure 2.


Testing the task API event handler

Follow these steps to test the task API event handler that was registered to run when the process flow navigation reaches the Approver task:

  1. Launch Business Process Choreographer Explorer and login when prompted.
  2. Click the Currently Valid template in the Process Templates category in the top left corner.
  3. Select the CreditProcess process and click Start Instance.
  4. Enter any text in the fields firstName, lastName, and amount and click Submit.
  5. Note that the Console view of WebSphere Integration Developer shows the messages shown in Listing 2.
Listing 2. Task API event handler log messages
SystemOut      o preCreateTask method is executed.
SystemOut      o postCreateTask method is executed.

The log messages are printed to SystemOut.log by the preCreateTask and postCreateTask methods of the TaskEventHandler class.


Conclusion

The task API event handler mechanism enables you to execute any kind of logic, including a service invocation at the various task states (not just when the task is created). This tutorial demonstrated that a piece of logic, including a service, can be executed by the human task container at various human task states. This is powerful because a task can have a number of states and business requirements may call for an execution of a service only when a task is at a specific state. For example, such requirements may state that a service is invoked only when a task is escalated.

Acknowledgments

The author would like to thank Martin Smolny from WebSphere BPM Development for his review of the tutorial.


Download

DescriptionNameSize
Project interchange filePI_Final.zip24KB

Resources

Learn

Discuss

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=762324
ArticleTitle=Invoking a service from a task API event handler in WebSphere Process Server V7
publish-date=09282011