An API event occurs when an API method manipulates a human
task. Use the API event handler plug-in service provider interface
(SPI) to create plug-ins to handle the task events sent by the API
or the internal events that have equivalent API events.
About this task
Complete the following steps to create an API event handler.
Procedure
- Write a class that implements the APIEventHandlerPlugin5
interface or extends the APIEventHandler implementation class. This class can invoke the methods of other classes.
- If you use the APIEventHandlerPlugin5 interface, you must implement
all of the methods of the APIEventHandlerPlugin5 interface and the
APIEventHandlerPlugin interface.
- If you extend the APIEventHandler implementation class, overwrite
the methods that you need.
This class runs in the context of a Java™ Platform, Enterprise Edition (Java EE) Enterprise application. Ensure that
this class and its helper classes follow the EJB specification.
Note: If you want to call the HumanTaskManagerService
interface from this class, do not call a method that updates the task
that produced the event. This action might result in inconsistent
task data in the database.
- Assemble the plug-in class and its helper
classes into a JAR file.
You can make the JAR file available
in one of the following ways:
- As a utility JAR file in the application EAR file.
- As a shared library that is installed with the application EAR
file.
- As a shared library that is installed with the TaskContainer application.
In this case, the plug-in is available for all tasks.
- Create a service provider configuration file for the plug-in
in the META-INF/services/ directory of your JAR
file.
The configuration file provides the mechanism
for identifying and loading the plug-in. This file conforms to the Java EE service provider interface
specification.
- Create a file with the name com.ibm.task.spi.plug-in_nameAPIEventHandlerPlugin,
where plug-in_name is the name of the plug-in.
For
example, if your plug-in is called Customer and it
implements the com.ibm.task.spi.APIEventHandlerPlugin5 interface,
the name of the configuration file is com.ibm.task.spi.CustomerAPIEventHandlerPlugin.
- In the first line of the file that is neither a comment
line (a line that starts with a number sign (#)) nor a blank line,
specify the fully qualified name of the plug-in class that you created
in step 1.
For example, if your plug-in class is called MyAPIEventHandler and
it is in the com.customer.plugins package, then the
first line of the configuration file must contain the following entry: com.customer.plugins.MyAPIEventHandler.
Results
You have an installable JAR file that contains a plug-in that
handles API events and a service provider configuration file that
can be used to load the plug-in.
Notes: You only have one eventHandlerName
property available to register both API event handlers and notification
event handlers. If you want to use both an API event handler and a
notification event handler, the plug-in implementations must have
the same name, for example,
Customer as the event
handler name for the SPI implementation.
You can implement both
plug-ins using a single class, or two separate classes. In both cases,
you need to create two files in the META-INF/services/ directory
of your JAR file, for example, com.ibm.task.spi.CustomerNotificationEventHandlerPlugin and com.ibm.task.spi.CustomerAPIEventHandlerPlugin.
Package
the plug-in implementation and the helper classes in a single JAR
file.
To make a change to an implementation effective, replace
the JAR file in the shared library and restart the server. If the
plug-in is part of the application EAR file, it is sufficient to reinstall
the updated application.
What to do next
You now need to install and register the plug-in so that
it is available to the human task container at run time. You can register
API event handlers with a task instance, a task template, or an application
component.
