Configuring the IBM Maximo Integration Framework to route outbound event messages to App Connect

For each IBM® Maximo® event type that you want to add as a trigger to an App Connect flow, you must configure the Maximo Integration Framework for outbound communication.

1. Create an endpoint that defines a target location for outbound messages about new, updated, or deleted Maximo records.

   Set this location to the event-specific webhook callback URL that is shown in App Connect and then specify a handler (or transport protocol) for routing the messages.

   Note: Create an endpoint for each event type (per Maximo object and account) that you use in a flow.

   To create an endpoint for a webhook callback URL, complete the following steps.

   1. From the Maximo navigation pane, click Integration > End Points (or use the search bar to search for end point).
   2. In the End Points application, click New End Point.
      
   3. Complete the End Point tab as follows.
      1. In the End Point fields, specify a name and a meaningful description for the endpoint. For the name, use a naming convention that identifies the destination system (App Connect), the Maximo object (for example, asset, company, or contract), and the event type (for example, new, updated, or deleted).
      2. In the Handler field, select a value of HTTP.
      3. In the Properties for End Point table, add values for the following properties by clicking View Details.
         • For the URL, copy and paste the webhook callback URL that App Connect provides for this specific event, and then select the Allow Override checkbox. To obtain this URL, add the event to a flow.
           • Example webhook callback URL in the App Connect flow editor
         • For HEADERS, specify a value of Content-Type:application/json and select the Allow Override checkbox.
         • For HTTPMETHOD, specify a value of POST and select the Allow Override checkbox.

      

   4. Click Save End Point
2. Create a publish channel to process outbound messages that an event initiates (such as a new, updated, or deleted record for an object) in Maximo.

   Specify the object structure to provide the message content and enable a listener for the event.

   Note: Create an associated publish channel for each endpoint that you create.

   To create a publish channel and enable an event listener, complete the following steps.

   1. From the Maximo navigation pane, click Integration > Publish Channels (or use the search bar to search for publish channel).
   2. In the Publish Channels application, click New Publish Channel

      

   3. Complete the Publish Channel tab.
      1. In the Publish Channel fields, specify a name and a meaningful description for the publish channel. (For the name, use a naming convention that identifies the related destination system, Maximo object, and event type.)
      2. In the Object Structure field, search for and select the object structure that you want to check for events. The value that you select must match the mxapi value that is provided in the event-specific webhook callback URL in App Connect.
         • Example of locating and selecting the object structure
         Note: In App Connect, the same mxapi object structure value is used in the webhook callback URLs for the three event types that can be triggered for an object. For example, for the asset object, mxapiasset is used for the New asset, Updated asset, and Deleted asset events. However, you must configure separate publish channels for these three events because they each require a separate endpoint. (In a later step, you map publish channels to endpoints, where a publish channel can be mapped to only one endpoint.)
      3. Select the Publish JSON checkbox.
      4. In the navigation pane, click the Enable Event Listener action and then click OK. The Enable Listener checkbox is automatically selected.

         

   4. If necessary, click Save Publish Channel.

      (The publish channel details might be saved automatically after you enable the event listener in the previous step.)

3. Create an automation script to customize the processing of outbound messages.

   When you create, update, or delete a record for an object, the outbound message for that event is sent to all the publish channels that are configured with that object structure. For example, if you configured a publish channel for a new asset, a second channel for an updated asset, and a third channel for a deleted asset, outbound messages about new, updated, and deleted assets are sent to each of the three publish channels. To ensure that the relevant subset of messages are added to a publish channel, you must use automation scripts to filter the messages by event type.

   Note: Create an automation script for each publish channel that you create. Include event-specific Python code (which is provided in the following task) to define which messages are processed in that channel.

   Complete the following steps for each publish channel that you created in Creating a publish channel:

   1. From the Maximo navigation pane, click System Configuration > Platform Configuration > Automation Scripts (or use the search bar to search for automation).
   2. In the Automation Scripts application, select the Create > Script for Integration action.

      

   3. Complete the Create Script for Integration window as follows.
      1. Select Publish Channel as the type of integration component that the automation script runs on.
      2. In the Publish Channel field, click Detail Menu (>) to search for and select the publish channel that you created earlier for a new, updated, or deleted event.
      3. Select Event Filter.
      4. In the Script Details section, add a description for the automation script.
      5. Ensure that the Active checkbox is selected.
      6. In the Script Language field, select python.
      7. Enter the script directly into the source code field by using the supplied sample code.
         • If the selected publish channel is associated with a new event, copy and paste the following code.

           
           if onadd == True:
                   evalresult = False
           else:
                   evalresult = True
           

         • If the selected publish channel is associated with an updated event, copy and paste the following code.

           
           if onadd == True:
                   evalresult = True
           elif ondelete == True:
                   evalresult = True
           else:
                   evalresult = False
           

         • If the selected publish channel is associated with a deleted event, copy and paste the following code.

           
           if ondelete == True:
                   evalresult = False
           else:
                   evalresult = True
           

         For example:

      8. Click Create.

      This automation script runs whenever outbound messages are sent to the publish channel and the messages are filtered based on the specified code.

      If you don't have an external system yet, go to Creating an external system for the App Connect integration. Otherwise, go to Associating the external system with a publish channel.

4. Create an external system that forwards processed messages from your publish channels to a JMS destination queue.
   Note: A single external system is needed for the App Connect integration, so you need to complete this step once only.

   To create the external system, complete the following steps.

   1. From the Maximo navigation pane, click Integration > External Systems (or use the search bar to search for external system).
   2. In the External Systems application, click New External System

      

   3. Complete the System tab as follows.
      1. In the System fields, specify a name and a meaningful description for the external system.
      2. Select the Enabled checkbox.
      3. In the End Point field, select a value of MXXMLFILE.
      4. In the Outbound Sequential Queue field, select a value of jms/maximo/int/queues/sqout.
      5. In the Inbound Sequential Queue field, select a value of jms/maximo/int/queues/sqin.
      6. In the Inbound Continuous Queue field, select a value of jms/maximo/int/queues/cqin.

      
   4. Click Save External System
5. Associate the external system with each publish channel that you create to process event-specific messages and identify the endpoint to which these messages are delivered.
   Before you begin, complete the following steps.

   • Ensure that you created an external system for App Connect.
   • Make a note of the names of the endpoint and the publish channel that you created earlier.

   Note: For each endpoint and associated publish channel that you create, you must configure a mapping in the external system.

   Complete the following steps to map the endpoint to the publish channel.

   1. If not already open, go to Integration > External Systems to open the External Systems application. Then search for and open the external system record for App Connect.
   2. Click the Publish channels tab and then click New Row to create a mapping.
      
   3. In the Publish Channel field, click Detail Menu (>) to select the publish channel that you want to map.
   4. In the End Point field, search for and select the associated endpoint.
   5. Select the Enabled checkbox.
      
   6. Click Save External System

   To activate the SEQQOUT instance of the JMSQSEQCONSUMER crontask, go to Activating polling and message processing on the outbound queue.

6. Activate polling and message processing on the outbound queue.

   Inbound and outbound messages are placed in two JMS sequential queues for asynchronous processing. The predefined crontask, JMSQSEQCONSUMER, can be used to poll these queues at frequent intervals, and then process any messages that are found. To ensure that outbound messages about new, updated, or deleted records are processed for delivery to App Connect, activate the SEQQOUT instance of the crontask, which polls the outbound queue (sqout).

   Note: This task needs doing only once.

   To activate the SEQQOUT instance of the JMSQSEQCONSUMER crontask, complete the following steps.

   1. From the Maximo navigation pane, click System Configuration > Platform Configuration > Cron Task Setup
   2. In the Cron Task Setup application, search for and open the JMSQSEQCONSUMER crontask.

      

   3. Ensure that Active is selected for the SEQQOUT instance, which is used to process outbound messages.
      
   4. Click Save Cron Task Definition
7. Configure App Connect certificates.
   For the Maximo endpoint to accept the requests that App Connectmakes in webhooks, configure App Connect certificates on Maximo.

   Important: If you don't do this step, the Maximo endpoint rejects the requests that are made by App Connect on webhooks.

   Complete the following steps to configure App Connect certificates on Maximo.

   1. Log in to the WebSphere Application Server administrative console by using your URL. The URL is of the form https://hostname:port/ibm/console.
   2. Go to Security > SSL certificate and key management > Key stores and certificates > CellDefaultTrustStore > Signer certificates.
   3. Click Retrieve from port.
      
   4. To retrieve a signer certificate from a specific port, complete the following steps.
      1. Enter the hostname (for example webhook-connector-provider-name.mybluemix.net) and port (for example, 443).
      2. Select an SSL configuration for outbound connection from the list.
      3. Enter an alias to identify the signer certificate.
   5. Click Retrieve signer information, and information about the signer certificate is displayed, then click Apply. If you want the certificate to be stored in the keystore, click Save.
      

      If the certificate is not getting reflected, restart the WebSphere Application Server administrative console.