IBM Maximo Asset Management is an enterprise asset management solution that enterprises can use to track and manage assets throughout their life cycles, manage procurement, contracts, services, people, and work orders, and optimize work processes.

You can use IBM App Connect to pass key data between IBM Maximo and other apps – automatically, in real time. You can do so using configuration and data mapping without a need for coding, and can achieve a return on your investment in minutes/hours, not days/months.

This guide shows you how.

If you can’t find what you want, or have comments about the “how to” information, please either add comments to the bottom of this page or .

What should I consider first?

Before you use App Connect Designer with Maximo, take note of the following considerations:

  • App Connect supports IBM Maximo V7.6 deployments that run on premises. For more information about Maximo, see the Maximo Asset Management documentation in IBM Knowledge Center.
  • If the Maximo instance is in a private network (for example, behind a firewall in your on-premises data center), you’ll need to set up a gateway that App Connect will use to securely access the Maximo instance. You can use the IBM Secure Gateway Client to set up the required network connection for accessing protected data.

    If you’ve previously used the Secure Gateway Client to set up a network connection for an App Connect application that is on the same private network as the Maximo instance, you can use this network connection with Maximo. If you don’t have such a network connection in place, configure one as described in Configuring a private network for IBM App Connect. Also ensure that the host and port of the Maximo instance are defined in the Secure Gateway Client’s access control list.

  • To create an integration flow that passes key data between Maximo and other apps, you must connect App Connect to each app in the flow. To connect App Connect to your Maximo account, you’ll need the following connection details.
    • Maximo URL: Specify the URL of the Maximo on-premises instance in the format https://hostname:port or http://hostname:port.
    • User name: Specify the user name for authenticating to the Maximo instance.
    • Password: Specify the password for the specified user name.
    • WebSphere Application Server user name: If the Maximo instance is installed on WebSphere Application Server, provide the user name of the WebSphere Application Server account so that you can use WebSphere authentication. For more information, see Installing on WebSphere Application Server in the Maximo Asset Management documentation in IBM Knowledge Center.
    • WebSphere Application Server password: If the Maximo instance is installed on WebSphere Application Server, provide the password of the WebSphere Application Server account.
    • Network name: Specify the name of the network (configured using the IBM Secure Gateway Client) for connecting to a Maximo instance in a private network.

      Important: Ensure that the Secure Gateway Client has been started. If you need to, you can start the Secure Gateway Client as described in Configuring a private network for IBM App Connect: Finally, start and configure the Secure Gateway Client.

    • Example of completed fields for connecting from App Connect

      If Maximo is installed on WebSphere Application Server, you must also provide credentials for the WebSphere Application Server account.

      Example of IBM Maximo connection details

    You can connect to the IBM Maximo app either from the Applications tab on the App Connect Catalog page, or when you add the app to a flow.

    Tip:

    • Immediately after you connect, rename your account with a meaningful name that helps you identify which Maximo instance the account relates to. You can rename an account only from the Applications tab on the Catalog page, and before it’s used in a flow.
    • If you’d like to interact with multiple Maximo instances in your flows, you’ll need to add an account for each instance that you want to access.

      For information about renaming accounts and setting up multiple accounts, see Managing accounts in App Connect.

  • App Connect can listen for events from your Maximo instance and then use those events to trigger event-driven flows. To use a Maximo event as a trigger, you must configure the integration framework in your Maximo instance before you start the flow in App Connect. For information about using a Maximo event as a trigger and the configuration required, see Using a Maximo event to trigger an event-driven flow and Configuring the Maximo integration framework to route outbound event messages to App Connect.
  • App Connect supports actions that enable you to create, retrieve, update, or delete records for objects in your Maximo instance. A set of standard objects are displayed by default in the Applications tab or flow editor, and you can click Show More to discover and work with additional Maximo objects.

    Show More link for discovering Maximo objects

Using a Maximo event to trigger an event-driven flow

App Connect supports new, updated, and deleted event types for a defined set of Maximo objects.

Maximo events

To use any of these event types as the trigger for an event-driven flow, you must work with your Maximo system administrator to configure the Maximo integration framework. As part of this configuration, you’ll need to provide the callback URL that is supplied for the event in the App Connect flow editor.

Callback URLs are unique to an App Connect instance, and Maximo account, object, and event type (as illustrated in the following figure), so you must configure a separate Maximo integration for each event type that you add to a flow. For example, if you are connected to Maximo using Account 1, and you want to trigger flows whenever a record is created, updated, or deleted for an asset object, you must configure three separate integrations for the New asset, Updated asset, and Deleted asset event types. You’ll also need to configure similar integrations for the event types for other Maximo objects under Account 1. After you’ve configured the integration for a specific event type (for example, New asset), you can use it in multiple flows in your App Connect instance.

Callback URL construction in App Connect

The high-level steps for using a Maximo event to trigger a flow are as follows:

  1. From your App Connect instance, create an event-driven flow.
  2. Add a Maximo event as a trigger for the flow (for a selected Maximo account and object).
  3. For the selected event type, configure the Maximo integration framework to route outbound event messages to App Connect. This configuration will deliver a POST HTTP request to the callback URL when the status of the object changes in your Maximo instance (for example, when a record is created).

    For more information, see Configuring the Maximo integration framework to route outbound event messages to App Connect.

  4. Add actions and any required toolbox nodes to the flow and then start it.

Configuring the Maximo integration framework to route outbound event messages to App Connect

Maximo provides an integration framework for integrating its application data with applications in external systems like App Connect. You can use integration components such as endpoints, handlers, object structures, publish channels, and external systems to process and send asynchronous event messages to App Connect when Maximo records are created, updated, or deleted for specific objects.

For each 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 by completing these tasks:

  1. Step 1: Create an endpoint:
    This endpoint will define how to route outbound messages from Maximo to the callback URL of the event type in App Connect.
  2. Step 2: Create a publish channel for outbound messages:
    This publish channel will listen for events that occur on a specific object and process the message content that the associated object structure provides.
  3. Step 3: Create an automation script to customize the processing of outbound messages:
    This automation script will apply custom logic during message processing to ensure that only the relevant messages are processed in the publish channel.
  4. Step 4: Create an external system for the App Connect integration (one-time task):
    This external system will forward processed messages from the publish channel to an outbound JMS queue.
  5. Step 5: Associate the external system with a publish channel:
    This configuration maps a publish channel to an endpoint to indicate where the messages from the channel should be sent.
  6. Step 6: Activate polling and message processing on the outbound queue (one-time task):
    This configuration ensures the outbound queue is polled at scheduled intervals for messages that need to be delivered to the App Connect callback URL that was defined for the endpoint.

Note: If you don’t have the required privileges, you must work with your Maximo system administrator to complete these tasks.

Step 1: Creating an endpoint

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 callback URL that’s shown in App Connect and then specify a handler (or transport protocol) for routing the messages.

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

To create an endpoint for a callback URL:

  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.

    Selecting New End Point in Maximo

  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, consider using a naming convention that identifies the destination system (that is, 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 (>):
      • URL: Copy and paste the callback URL that App Connect provides for this specific event, and then select the Allow Override check box.

        Tip: To obtain this URL, add the event to a flow.

        • Example

          Sample callback URL for a Maximo event

      • HEADERS: Specify a value of Content-Type:application/json and then select the Allow Override check box.
      • HTTPMETHOD: Specify a value of POST and then select the Allow Override check box.

    Sample values for a new endpoint

  4. Click Save End Point.

What to do next: Go to Step 2: Creating a publish channel for outbound messages.

Step 2: Creating a publish channel for outbound messages

Create a publish channel that will be used to process outbound messages that are initiated by an event (such as a new, updated, or deleted record for an object) in Maximo. You’ll need to specify the object structure that will provide the message content and enable a listener for the event.

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

To create a publish channel and enable an event listener:

  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.

    Selecting New Publish Channel in Maximo

  3. Complete the Publish Channel tab as follows:
    1. In the Publish Channel fields, specify a name and a meaningful description for the publish channel. (For the name, consider using 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’s provided in the event-specific callback URL in App Connect.
      • Example: Locating and selecting the object structure

        Locating and selecting the object structure

      Note: In App Connect, the same mxapi object structure value is used in the 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’ll need to map publish channels to endpoints, and it’s worth noting that a publish channel can be mapped to only one endpoint.)

    3. Select the Publish JSON check box.
    4. In the navigation pane, click the Enable Event Listener action and then click OK. The Enable Listener check box is automatically selected.

    Sample values for a new publish channel

  4. If necessary, click Save Publish Channel. (The publish channel details might be automatically saved after you enable the event listener in the previous step.)

What to do next: Go to Step 3: Creating an automation script to customize the processing of outbound messages.

Step 3: Creating 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’ve 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: You must create an automation script for each publish channel that you create and include event-specific Python code (provided in the following task) to define which messages should be processed in that channel.

Complete the following steps for each publish channel that you created in Step 2: 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.

    Selecting the 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 will run 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.

      Channel definitions for the automation script

    4. In the Script Details section, add a description for the automation script.
    5. Ensure that the Active check box is selected.
    6. In the Script Language field, select python.

      Script Details selections

    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:

      Sample Python script

    8. Click Create.

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

What to do next: If you haven’t yet created an external system, go to Step 4: Creating an external system for the App Connect integration. Otherwise, go to Step 5: Associating the external system with a publish channel.

Step 4: Creating an external system for the App Connect integration

Create an external system that forwards processed messages from your publish channels to a JMS destination queue.

Note: A single external system is required for the App Connect integration, so this is a one-time task.

To create the external system:

  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.

    Selecting New External System in Maximo

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

    Sample values for a new external system

  4. Click Save External System.

What to do next: Go to Step 5: Associating the external system with a publish channel.

Step 5: Associating the external system with a publish channel

You must associate the external system with each publish channel that you create to process event-specific messages, and identify the endpoint to which these messages should be delivered.

Before you begin:

  • Ensure that you’ve 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.

    Adding a new row for a publish channel/endpoint 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 check box.

    Defining a publish channel/endpoint mapping

  6. Click Save External System.

What to do next: If you haven’t yet activated the SEQQOUT instance of the JMSQSEQCONSUMER cron task, go to Step 6: Activating polling and message processing on the outbound queue.

Step 6: Activating polling and message processing on the outbound queue

Inbound and outbound messages are placed in two JMS sequential queues for asynchronous processing. The predefined cron task, 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, you must activate the SEQQOUT instance of the cron task, which polls the outbound queue (sqout).

Note: This is a one-time task.

To activate the SEQQOUT instance of the JMSQSEQCONSUMER cron task:

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

    Selecting the JMSQSEQCONSUMER cron task

  3. Ensure that Active is selected for the SEQQOUT instance, which is used to process outbound messages.

    Activating the SEQQOUT instance

  4. Click Save Cron Task Definition.

The configuration of outbound events for the chosen event type, object, and account in your App Connect flow is now complete. Any event-driven flow that uses this event type will be triggered when a corresponding Maximo event occurs.

Error handling in the Maximo integration framework

Messages in the outbound sequential queue are processed on a first-in-first-out basis and will remain in the queue until they are successfully delivered to App Connect or are deleted from the queue. If a message is flagged with a processing error, subsequent messages in the queue are not processed until the error is resolved or deleted.

If you are not seeing the expected results for your App Connect flow and no errors are logged for the flow in App Connect, a possible cause might be that the flow isn’t being triggered because Maximo messages are not being delivered to the endpoint URL. Use the Message Reprocessing application to check whether any message is flagged with an error and then resolve or delete the error message. For more information about managing errors in the integration framework, see Error management in the Maximo documentation in IBM Knowledge Center.

Join The Discussion

Your email address will not be published. Required fields are marked *