Community articleDeploying an event handler
Added by IBM contributorIBM | Edited by IBM contributordeveloperWorks Lotus Team on July 8, 2014
Rate this article 1 starsRate this article 2 starsRate this article 3 starsRate this article 4 starsRate this article 5 stars

Deploy your event handler to the IBM® Connections server runtime.



Deploy your event handler to the IBM® Connections server runtime.

Before you begin

  • 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 WebSphere® Application Server using the Integrated Solutions Console of the Deployment Manager.

You will need the JAR file for the event handler implementation, plus any associated dependencies.

Procedure

  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 WebSphere Application Server Integrated Solutions 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:
  5. 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.


  6. Make sure that the Use an isolated class loader for this shared library check box is not selected.
  7. Click Apply, then click OK, and save your changes.
  8. 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.
  9. Start the wsadmin client from the following directory of the system on which you installed the deployment manager:
    1. Open a command prompt, and then change to the following directory of the system on which you installed the deployment manager:

      app_server_rootexternal link \profiles\dm_profile_root\bin
    2. where app_server_root is the WebSphere Application Server installation directory and dm_profile_root is the Deployment Manager profile directory, typically dmgr01. For example, on Windows:

      cfC:\Program Files\IBM\WebSphere\AppServer\profiles\Dmgr01\bin{code}

      Attention: You must run the following command to start the wsadmin client from this specific directory because the Jython files for the product are stored here. If you try to start the client from a different directory, then the execfile() command that you subsequently call to initialize the administration environment for an IBM Connections component does not work correctly.
    3. Enter the following command to start the wsadmin client:
      • AIX or Linux:
      • ./wsadmin.sh -lang jython -user admin_user_id -password admin_password -port SOAP_CONNECTOR_ADDRESS Port

      • Microsoft Windows:
      • wsadmin -lang jython -user admin_user_id -password admin_password -port SOAP_CONNECTOR_ADDRESS Port

      where:
      • admin_user_id is the user name of a person in the Administrator role on the IBM WebSphere Application Server.
      • admin_password is the password of the WebSphere Application Server administrator.
      • SOAP_CONNECTOR_ADDRESS Port is the SOAP port for the WebSphere Application Server deployment manager server. The default value of the SOAP port is 8879. If you are using the default port value, you do not need to specify this parameter. If you are not using the default and you do not know the port number, you can look up its value in the WebSphere Application Server Integrated Solution Console. To look up the SOAP port number, perform the following steps:
        1. Open the WebSphere Application Server Integrated Solution Console for the deployment manager, and then select System Administration -> Deployment Manager.
        2. In the Additional properties section expand Ports, and then look for the SOAP_CONNECTOR_ADDRESS port entry to find the port number.
      For example:
      • AIX or Linux:
      • ./wsadmin.sh -lang jython -username primaryAdmin -password p@assword -port 8879

      • Microsoft Windows:
      • wsadmin -lang jython -username primaryAdmin -password p@assword -port 8879

    4. Use the following command to access the IBM Connections configuration files:
    5. execfile("connectionsConfig.py")

    6. Check out the events-config.xml file using the following command:
    7. LCConfigService.checkOutEventsConfig("<working_directory>","<cell_name>")


      where:
      • <working_directory> is the temporary working directory to which the configuration XML and XSD files are copied and are stored while you make changes to them. Use forward slashes to separate directories in the file path, even if you are using the Microsoft Windows operating system.
      • Note: AIX and Linux only: The directory must grant write permissions or the command will not run successfully.
      • <cell_name> is the name of the WebSphere Application Server cell hosting the IBM Connections application. This argument is case-sensitive, so type it with care. If you do not know the cell name, type the following command while in the wsadmin command processor:
      • print AdminControl.getCell()

    8. From the working directory to which you checked out the configuration files, open the events-config.xml file in a text editor.
    9. Do one of the following:
      • If you are deploying a pre-event handler, add a new <preHandler> element in the <preHandlers> 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 <postHandler> in the <postHandlers> element, following the example shown in the file.

    10. For each type of handler, add the following attributes:
    11. name
      The 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 <postHandler> element also specify the following attribute:

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

    12. Add a <subscriptions> element to your handler definition. Within this element, create one or more <subscription> elements. Each subscription element tells the runtime about the events this handler will consume. For each <subscription> element, define the following attributes:
    13. source
      Specify the source of the event. Valid values include:
      • * (Indicates all applications)
      • ACTIVITIES
      • BLOGS
      • BOOKMARKS
      • COMMUNITIES
      • FILES
      • FORUMS
      • HOMEPAGE
      • MOBILE
      • NEWS
      • PROFILES
      • SEARCH
      • WIKIS

      type
      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
      • UPDATE

      eventName
      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 Events Reference.

      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>

    14. If your event handler defines properties, add a <properties> element and define one <property> element for each property. The name attribute value must match the name of the property. For example:
    15. <properties>
      <property name="foo">bar</property>
      </properties>

    16. Save and close the events-config.xml file.
    17. Check in the configuration files using the following command:
    18. LCConfigService.checkInEventsConfig("<working_directory>","<cell_name>")


      where you specify the same values you specified in Step 8d for <working_directory> and <cell_name>.
    19. Stop and restart IBM Connections.