Deploying an event handler
Deploy your event handler to the IBM Connections server runtime.
Before starting
- Understand what events your handler needs to consume and what type of handler it is.
Pre-event handlers and post-event handlers that you intend to be invoked synchronously must always be run in the context of the application that generates the events that the handler is subscribed to consume. Therefore, these handlers must be deployed in a way that allows them to be executed by that application or applications.
Asynchronously-invoked post-event handlers are always run in the context of the News application. Therefore, these handlers much be deployed in a way that allows them to be executed by the News application.
- If your handler is a pre-event handler, or a post-event handler you will register synchronously, then document what IBM Connections applications you want to consume events from.
- Decide on the file system location in which to store your event handler code. This location should be available to all nodes in the deployment. A suggested approach is to create a new subdirectory within the shared content store location that was defined when the product was installed.
About this task
Perform the configuration of WAS using the Integrated Solutions Console of the dmgr.You will need the JAR file for the event handler implementation, plus any associated dependencies.
Procedure
- Place your event handler JAR file, and the files for any dependencies, in the file system location that you decided on earlier. For example /mnt/shared/LotusConnections/eventHandlers. So, if your handler JAR file is called myHandler.jar, the location is /mnt/shared/LotusConnections/eventHandlers/myHandler.jar.
- Log in to the WAS admin console, expand Environment, and then select Shared libraries.
- Select the Cell level scope from the Scope drop-down box, and then click New.
- Provide the following details for the shared library:
Table 1.
Field name Description Example Name The name of this shared library. Choose a name that describes the event handler. MyHandler Description Optional. Provide a fuller description on the event handler
Classpath Provide the physical location of the event handler JAR file, and any JAR files it depends on. /mnt/shared/LotusConnections/eventHandlers/myHandler.jar Native Library Path Optional. Only specify values here if your handler code relies on native libraries.
- Make sure that the Use an isolated class loader for this shared library check box is not selected.
- Click Apply, then click OK, and save your changes.
- Add the shared library you just created to each IBM Connections application you identified that this handler needs to be deployed to. If your handler is a pre-event handler, or a post-event handler which will be invoked synchronously, then perform the following steps for each IBM Connections application that it needs to run in. If your handler is a post-event handler which needs to be invoked asychronously, then perform the following steps only for the News application.
- Expand Applications -> Application Types, and then click WebSphere enterprise applications.
- Select the checkbox next to the application with which you want to associated the library.
- Under References, click Shared library references.
- Select the checkbox next to the application name, and then click Reference shared libraries.
- From the list of available handlers, select the handler name that you created and follow the instructions on the page to move the handler to the Selected list.
- Click OK, and then click OK again.
- Save your changes.
- Repeat these steps for any other applications that need to run this event handler.
- Edit the events-config.xml file, which is not checked out as part of the wsadmin check out command used to access the other core configuration files. You must retrieve the file from the file system on the system hosting the deployment manager. a. Go to the following directory on the system hosting the deployment manager:
<WASRoot>/<DmgrName>/config/cell/<cellName>/LotusConnections-config
For example:
/opt/IBM/WebSphere/AppServer/profiles/Dmgr01/config/cells/exampleCell01/LotusConnections-config
b. Make a backup copy of the events-config.xml file in case you need to revert back to it.
c. Open the events-config.xml file in a text editor.
d. Do one of the following:
- If you are deploying a pre-event handler, add a new
element in the element, following the example shown in the file. - If you are deploying a post-event handler, whether it is synchronous or asynchronous, add a new
in the element, following the example shown in the file. e. For each type of handler, add the following attributes:
nameThe name of the event handler. This is an arbitrary name.
enabled
Set to true to ensure this handler is enabled. This attributes can be set to false to disable the handler.
class
The Java class that provides the handler implementation.
If you are defining a post-event handler, in the
element also specify the following attribute:
invokeIdentify if the handler should be invoked synchronously or asynchronously using one of the following values:
ASYNC
SYNCf. Add a
element to your handler definition. Within this element, create one or more elements. Each subscription element tells the runtime about the events this handler will consume. For each element, define the following attributes:
sourceSpecify the source of the event. Valid values include:
* (Indicates all applications)
ACTIVITIES
BLOGS
BOOKMARKS
COMMUNITIES
FILES
FORUMS
HOMEPAGE
MOBILE
NEWS
PROFILES
SEARCH
WIKIStype
Specify the type of event to consume. Valid values include:
* (Indicates all types)
ACKCOM
APPROVE
AUDIT
COMMAND
CREATE
DELETE
DISMISS
FLAG
INACTIVE_UPDATE
MEMBERSHIP
MODERATE
NOTIFY
QUARANTINE
PEND
PRECREATE
READ
REJECT
RESTORE
RETURN
UPDATEeventName
Specify the event name to subscribe to. This can be any event name, or * for all event names. You cannot provide a partial event name nor use wild cards to prompt the application to search for the event name. For a list of the events available in IBM Connections, see the Events Reference wiki article.
Attention: A value for each of these attributes is required.
Examples:
- To subscribe to all events generated, specify the following:
<subscription source="*" type="*" eventName="*"/>
- To subscribe to all create events from all components, specify the following:
<subscription source="*" type="CREATE" eventName="*"/>
- To subscribe to all create events from the Profiles application, specify the following:
<subscription source="PROFILES" type="CREATE" eventName="*"/>
- To subscribe to only one specific event from the Profiles application, specify the following:
<subscription source="PROFILES" type="*" eventName="profiles.status.updated"/>
A single event handler can define multiple subscriptions, for example:
<subscriptions>
<subscription source="PROFILES" type="*" eventName="profiles.status.updated"/>
<subscription source="PROFILES" type="*" eventName="profiles.status.deleted"/>
</subscriptions>g. If your event handler defines properties, add a
element and define one element for each property. The name attribute value must match the name of the property. For example:
<properties>
<property name="logFile" value="/tmp/event.log"/>
</properties>
h. Save and close the events-config.xml file.
i. Synchronize the change you made to the configuration file on the deployment manager to the other nodes by completing the following steps:i. Log into the WAS admin console of the deployment manager using administrator credentials.
ii. Expand System Administration, and then click Nodes.
iii. Select the check box next to each node in your deployment, and then click Full Resynchronize.j. Stop and restart IBM Connections.