Using the event handler for FileNet Content Manager

You can deploy the event handler on a IBM® FileNet® Content Manager system, and configure it to provide notification events to your IBM BPM processes.

Overview

The event handler is for IBM FileNet Content Manager version 5.1 or higher.

Supported events

The following table lists all ECM events that are supported by IBM BPM, and the corresponding FileNet Content Manager events. Use the table to identify the FileNet Content Manager events that you need to subscribe to, and the names that are used in Process Designer to identify the same events in IBM BPM.

Table 1. Mapping between supported ECM events and FileNet Content Manager events
ECM events supported by IBM BPM (com.ibm.bpm.BPMEventType)	Object types that the event can apply to	Corresponding FileNet Content Manager events (com.filenet.api.events)
CheckedIn	Document	CheckinEvent
CheckedOut	Document	CheckoutEvent
CheckOutCancelled	Document	CancelCheckoutEvent
ClassChanged	Folder or Document	ChangeClassEvent
ClassifyCompleted	Document	ClassifyCompleteEvent
Created	Folder or Document	CreationEvent
Deleted	Folder or Document	DeletionEvent
Filed	Folder	FileEvent
Frozen	Document	FreezeEvent
Locked	Folder or Document	LockEvent
PublishCompleted	Document	PublishCompleteEvent
PublishRequested	Document	PublishRequestEvent
SecurityUpdated	Folder or Document	UpdateSecurityEvent
StateChanged	Document	ChangeStateEvent
Unfiled	Folder	UnfileEvent
Unlocked	Folder or Document	UnlockEvent
Updated	Folder or Document	UpdateEvent
VersionDemoted	Document	DemoteVersionEvent
VersionPromoted	Document	PromoteVersionEvent

Define a process to consume the ECM events

Before you configure the event handler to generate event notifications on your IBM BPM system, you might want to create a test process to consume the notifications. For a simple end-to-end verification test, consider subscribing to one event that is not triggered too often, for example, the Updated event for folders. For details about how to create an event subscription in Process Designer, refer to Creating and configuring event subscriptions.

Tip: In Process Designer, when you use the content integration control, the value that you specify for the Object Type must match the name of the document or folder class you select when creating the subscription on the FileNet Content Manager server.

Copy the event handler to your FileNet Content Manager server

The event handler is in the following location on your IBM BPM server:

install_root/BPM/EventHandlers/ECM/FileNet/filenet-bpm-event-handler-51.jar
install_root\BPM\EventHandlers\ECM\FileNet\filenet-bpm-event-handler-51.jar

Copy the event handler to a suitable location on your FileNet Content Manager server.

Creating the connection information document

The connection information necessary for the ECM event handler to connect to the IBM BPM system is stored as a document in the FileNet Content Manager repository. To create the connection information document, perform the following steps:

On your FileNet Content Manager server, create a properties file.
Tip: If you require multiple subscriptions that notify different IBM BPM servers of events, you need one properties file for each IBM BPM server. Although you can give the properties file any name, it makes sense to include the name of the server in the name of the properties file, for example, bpmserver1.properties.
- If you have a suitable J2C authentication alias defined on the application server where FileNet Content Manager is running, you can define the connection properties file to use the authentication alias. For example:
```
bpm.server.authalias=scope/my_authentication_alias
bpm.server.uri=http\://bpm_server_name\:9443
```
  Where scope is the scope of the authentication alias my_authentication_alias, and bpm_server_name is the host name or IP address of your IBM BPM server, for example, bpm1.example.com.
- If you do not use an authentication alias, your server connection properties file must specify a suitable IBM BPM user name and password. For example:
```
bpm.server.username=bpm_user
bpm.server.password=bpm_user_password
bpm.server.uri=http\://bpm_server_name\:9443
```
  Where bpm_user is a user ID that is authorized to access the IBM BPM, bpm_user_password is the password for the user ID, and bpm_server_name is the host name or IP address of your IBM BPM server, for example, bpm1.example.com.
- IBM BPM by default uses the context root /rest/bpm/wle for its REST API. If you use a custom context root prefix, add this line to your connection properties file:
```
bpm.server.contextRoot=/myCustomContextRoot/rest/bpm/wle
```
Store the properties file in the ECM system. You can store the properties file in several ways. For example, you can use the IBM Administration Console for Content Platform Engine to store the properties file by using the following actions:
1. Using a browser, log in to the Administration Console for Content Platform Engine at the URL http://filenet_server_host_name:port/acce.
2. Select the object store where you want to store the configuration file.
3. Expand the object store, then either add a folder or select a suitable existing folder where you want to store the properties file.
4. Select New Document from the Actions drop-down list of the folder.
5. Specify a Document title. You might want to choose a name that identifies the BPM system that this connection document is targeting. Then, click Next.
6. In the Content Elements section, click Add. In the Add Content Element dialog, click Browse and select the property file that you created. Click Add Content. Click Next.
7. On the following pages (Object Properties, Document Content and Version, Specify Settings for Retaining Objects, and Advanced Features) you can keep the default values. Click Next on each page.
8. On the Summary page, click Finish.
9. The document is created. Click Open to open it.
10. In the Properties tab, look for the ID property and note the value. Select and copy it to a clipboard or text file. You need it later when you create the event subscription.
11. In the Security tab, you might want to make sure that the document can be read and modified only by administrators to prevent all of your users from seeing these connection information.

Creating the event action

An event action in FileNet Content Manager represents the code that is invoked when an event happens. To create the event action for the BPM event handler, follow these steps in the Administration Console for Content Platform Engine:

In your object store, browse to the Event Actions that are located under Events, Actions, Processes.
Click New.
Enter a Display name, for example, BPM event action. Click Next.
On the Specify the Type of Event Action page, enter the Java class handler com.ibm.bpm.integration.filenet.BPMEventHandler. Enable the Configure code module check box. Click Next.
On the Specify the Code Module page, enter a Code Module title, for example, BPM event handler code module. Click Browse and select the filenet-bpm-event-handler-51.jar file. Click Next.
On the Summary page, click Finish.

This event action is not Business Process Management (BPM) system-specific. Therefore, you can use it for event subscriptions designated for different BPM systems.

Creating a subscription

A subscription in FileNet Content Manager defines which events on a certain object are to be handled by an event action.

For the integration with IBM BPM, you need to create the required subscriptions in FileNet Content Manager that match the events you need for your BPM solution:

If you define event subscriptions in BPM, you need to create corresponding subscriptions in FileNet Content Manager using the event mapping table from above.
If you use Document Start events in processes, you need to create a subscription for the Created event for the document class.
If you use activity preconditions based on documents that are added to a folder, you need to create a subscription for the Filed event for the folder class.

If you have multiple BPM systems that you want to send the event to, create subscriptions in FileNet Content Manager for each of them individually.

Subscriptions in FileNet Content Manager can be configured to include events that happen on subclasses as well. Therefore, when you use this setting, you need to take care to not create multiple subscriptions that handle the same event and send this event twice to the same BPM system. For example, you have this class structure in your FileNet Content Manager system:

Document
- ClaimForm
- Contract

In your BPM system, you have an event subscription defined for the Document Created event on the base Document class that includes subclasses. You also have another event subscription for the Document Created event on the Contract class that does not include subclasses. In this scenario, you only need one subscription in your FileNet Content Manager system: an event subscription on the Document class that includes subclasses and that subscribes to the Created event. This subscription will send all required events to the BPM system. If you created an extra subscription on the Contract class that subscribes to the Created event, then both subscriptions would be triggered if a Contract is created. Subsequently, two events would be sent to the BPM system.

To create a subscription, follow these steps in the Administration Console for Content Platform Engine:

In your object store, browse to the Subscriptions that are located under Events, Actions, Processes.
Click New.
Enter a Display name and optionally a Description. You should specify a display name and description that clearly identifies which BPM system is targeted, which events are handled for which Document and Folder classes, and if the include subclasses flag is enabled. This clarification allows you to keep track of which events are handled by which BPM systems. This clarification also helps you prevent subscriptions that cause the same event to be sent multiple times to one BPM system. Click Next.
On the Select Classes page, select Document or Folder as Class type. Select the Class that you want to handle events. Click Next.
On the Specify the Subscription Behavior page, keep all defaults and click Next.
On the Select the Triggers page, select the events you want to handle. Click Next.
On the Select an Event Action page, select the event action that you previously created. Click Next.
On the Specify Additional Options page, for the Initial state, disable the Enable this subscription check box. Enable the Include subclasses check box according to your needs. Do not enable the Run synchronously check box. Synchronous events are sent to the BPM system even before the transaction is completed. As a transactional context cannot be propagated using a REST API, this may result in operations getting triggered in the BPM system even if the content operation is subsequently rolled back. Click Next.
On the Summary page, click Finish.
The subscription is now created. Click Open to open it.
On the Properties tab, look for the User String property. Enter the document identifier from the connection information document as a value. Optionally, look for the Is Enabled property and change its value to True. Click Save.

Now notifications of all subscribed events are sent to the appropriate IBM BPM server.

Advanced configuration

Certain event handler behavior can be controlled by using Java Virtual Machine (JVM) system properties. To create or modify those properties, log in to the WebSphere Integrated Solutions Console of your FileNet Content Manager system. Browse to Servers > Server Types > WebSphere application servers. For each server belonging to the deployment target the FileNet Content Manager engine application is deployed to, go to Java and Process Management > Process definition > Java Virtual Machine > Custom Properties. Click New... to create new entries, or click an existing entry to apply changes to it. After you have made changes, save the configuration, synchronize the nodes, and restart the servers.

The following table contains the properties that can be set:

Table 2. Customizing Java Virtual Machine properties
Property name	Default value	Description
`com.ibm.bpm.integration.filenet.configurationExpiration`	600000	The time in milliseconds that the content of a connection information document is cached.
`com.ibm.bpm.integration.filenet.sendCreatedEventOnCheckOut`	true	When you check out a document, FileNet Content Manager fires a Creation event for the new document version. This behavior might not be desired if the expectation is that the event happens only for the first version of a document. Set this value to false to cause the BPM event action to ignore document creation events for non-initial versions.