Deploying an event handler 

Deploy your event handler to the IBM Connections server runtime.

Before you begin

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.


  1. 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.

  2. Log in to the WAS admin console, expand Environment, and then select Shared libraries.

  3. Select the Cell level scope from the Scope drop-down box, and then click New.

  4. 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.

  5. Make sure that the Use an isolated class loader for this shared library check box is not selected.

  6. Click Apply, then click OK, and save your changes.

  7. 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.

    1. Expand Applications -> Application Types, and then click WebSphere enterprise applications.

    2. Select the checkbox next to the application with which you want to associated the library.

    3. Under References, click Shared library references.

    4. Select the checkbox next to the application name, and then click Reference shared libraries.

    5. 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.

    6. Click OK, and then click OK again.

    7. Save your changes.

    8. Repeat these steps for any other applications that need to run this event handler.

  8. 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:
    For example:
    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:

      The name of the event handler. This is an arbitrary name.


      Set to true to ensure this handler is enabled. This attributes can be set to false to disable the handler.


      The Java class that provides the handler implementation.

    If you are defining a post-event handler, in the element also specify the following attribute:

      Identify if the handler should be invoked synchronously or asynchronously using one of the following values:

    f.    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:

      Specify the source of the event. Valid values include:
      * (Indicates all applications)


      Specify the type of event to consume. Valid values include:
      * (Indicates all types)


      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.

      • 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:
        <subscription source="PROFILES" type="*" eventName="profiles.status.updated"/>
        <subscription source="PROFILES" type="*" eventName="profiles.status.deleted"/>

    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:
      <property name="logFile" value="/tmp/event.log"/>
    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.


November 7, 2011


Nov 7, 2011 4:47:56 PM Added an inline link to the Events Reference article. 4 Aug 11, 2011 12:50:37 PM Fixing broken code references - formatting issues. 3 Aug 11, 2011 12:48:38 PM 2 Aug 11, 2011 12:40:57 PM Updated Step 8 to reflect fact that the wsadmin checkout command does ... 1