Creating a custom event handler for event notification

The event handler publishes the event message to the external system. Use this procedure to create a custom event handler.

Create the custom handler:

1. In InfoSphere MDM Workbench, open your project configuration .imm file.
2. From the MDM Configuration perspective, select Handlers and click Add.
   1. Type a unique name for your Handler Name.
   2. Use the default Sequence Number provided.
   3. Select All for Callback Type and Interaction Code.
   4. Enter any Arguments for the handler. Arguments are generally in the format of key=value. Separate multiple arguments with a carat (^) character.
3. Select the handler that you just created and click Generate to start the Create a Master Data Management Handler Class wizard.
   1. Specify or browse to a Handler bundle project name.
   2. Select Add bundle to composite and specify the Composite project .cba file, then click Next to load the Handler Information window.
   3. Enter the appropriate information for the handler:
      • Select the Type of interaction from the dropdown menu.
      • Enter or browse to the Name of the handler.
      • Enter or browse to the Java class for the handler.
      • Enter the Java package name for the handler.
   4. Click Finish.
      There are now two projects in the Navigator view: ConfigurationProjectName.cba and ConfigurationProjectName.handlers.

Implement the com.initiatesystems.hub.event.handler.IEventHandler interface:

4. In the Navigator view, go to ConfigurationProjectName.handlers/ejbModule/handlers/event/and open the CustomerEventHandlerName.java file and configure the parameters.
5. Change the package name in the import property from: com.initiatesystems.hub.event.handler.IEventHandler to com.initiatesystems.hub.event.handler.yourhandler_name.
   For example, the default JMS handler uses the package name of com.initiatesystems.hub.event.handler.jms.
6. The following is is the IEventHandler interface that you must implement for your custom handler:

   {
   		public static final int EVENT_PUBLISH_SUCCESS = 0;
   		public static final int EVENT_PUBLISH_ERROR_RECOVERABLE = 1;
   		public static final int EVENT_PUBLISH_ERROR_UNRECOVERABLE = 2;
    
   		public void init()
   		{
   		}
   		public void addDestination(String destName, String destArgs)
   		{
   		}
   		public int publish(String destName, String msg)
   		{
   		}
   		public void shutdown()
   		{
   		}
   }

7. void init(): This method is called when the event handler is loaded by the OSGi framework. If your destination or queue requires any initialization work, add the code between the braces { }.
8. void addDestination: This method is called by the event manager to notify the event handler of the destinations that are being assigned to this Handler. This method can be called multiple times (because multiple destinations can be configured and be assigned to the same event handler).
   In addition, every time a new destination is added or updated in InfoSphere MDM Workbench, this method is called so that the event handler can update the destination in its internal cache. The method has two arguments:

   • destName: Unique destination name per handler
   • destArgs: The arguments that are configured in step 2.d

   Your custom event handler must keep information about these destinations in an internal cache. When the event manager calls the publish method, it sends the destination name and the XML message. The custom event handler must apply any arguments (the arguments are added in step 2.d.).
9. int publish: This method is called by the event manager. The arguments are as follows:
   • destName: Destination to which this message must be published
   • msg: Actual XML message as a string

   Note: When you first open the *.java file, the publish method shows as: public boolean publish (String destName, String msg). For event handlers, make sure that you replace that line with: public int publish(String destName, String msg)
10. Provide the integer for the return type. Values are:
    • IEventHandler.EVENT_PUBLISH_SUCCESS = 0: if the message is received successfully by the destination
    • IEventHandler.EVENT_PUBLISH_ERROR_RECOVERABLE = 1: if the message is not received successfully and you want to attempt to resend the message according to the event manager recoverable error logic
    • IEventHandler.EVENT_PUBLISH_ERROR_UNRECOVERABLE = 2: if the message is not received successfully and the message must be handled according to the event manager unrecoverable error logic
11. shutdown(): This method is called when the event manager shuts down. You can add any cleanup work that you want the handler to do here. If you have open connections to something (such as a JMS queue), then you might want to close the open connections.

Configure your blueprint.xml:

12. In the Navigator view, go to ConfigurationProjectName.handlers/BundleContent/OSGI-INF/blueprint and open the event-handlers.xml file.
13. Set the interface property as:

    <service interface="com.initiatesystems.hub.event.handler.IEventHandler">

14. Set the handler name value to the same name as you entered in step 2.a.
    For example:

    <entry key="handlerName" value="XYZCustomHandlerName"/>

15. Save and close the file.
16. Deploy the CBA to the operational server.