In certain cases it can be very useful for IMS to integrate with third party applications. These are usually applications that provide specialised and in-depth functionality that relates to IMS services.
An IMS integration with a “downstream” application (i.e. that receives data from IMS) is typically implemented using the third party application's API (application programming interface) which may take various forms. If an integration doesn't currently exist between IMS and your third-party application, this can be requested through the usual IMS support channels.
ServiceNow Integration
ServiceNow is a platform for managing IT Services, Operations & Assets. It offers the ability to capture events, relate them to a tracked asset and raise incidents from those events.
IMS already includes an integrated alert and incident tracking system (through its Triggers and Tickets modules), however, if a company is already using ServiceNow to track incidents and events in their operations then they may prefer to integrate IMS with ServiceNow so that they have one centralised system for this purpose.
To achieve this, IMS can be configured to push events to ServiceNow whenever user-specified conditions or thresholds are met. These events in ServiceNow can then be further customised, directed to appropriate teams or turned into incidents for action.
Compatibility
IMS has been successfully tested against the “Utah” version of ServiceNow (Q1-2023) and may also work with earlier or later versions. It is also possible to configure the integration to use a ServiceNow “mid-server”.
Note that IMS integration with ServiceNow requires that you have the Event Management capability installed in your ServiceNow instance so this should be arranged with your ServiceNow account manager before attempting this configuration.
Configuration
Some configuration is required for the integration to work:
- ServiceNow must be configured to accept events from IMS.
- IMS must be configured to communicate with ServiceNow.
Expand the options below to learn more:
Configure ServiceNow to accept events from IMS
For ServiceNow to accept events from IMS, it needs two things configured:
- An OAuth credential created
- A user created with the evt_mgmt_integration role
Following is an example of how this may be done. Please note that this may vary depending on your version of ServiceNow. Please consult ServiceNow specialists within your company for assistance if required.
Configure OAuth in ServiceNow
In your ServiceNow instance, navigate to System OAuth → Application Registry and then click New.
Click on ‘Create an OAuth API endpoint for external clients’:
And then fill in the Name and Client Secret fields and click Submit. Record the Client ID & Client Secret for later usage.
The OAuth configuration in ServiceNow is now complete.
Add a User in ServiceNow
In your ServiceNow instance, navigate to Organization → Users and then click New.
Fill out the record with any required identifying information, ensuring that ‘Active’ and ‘Web service access only’ are ticked, and then click Submit. Record the User ID for later usage.
Find the user you have just created in the list view, open it again, click the ‘Set Password’ button and set a password. Make sure to click Update when you are done. Record the Password for later usage.
Find the user you created in the list view, open it again and click the ‘Edit’ button in the Roles table at the bottom.
Find and add the evt_mgmt_integration role to the user and click Save.
Ensure you click ‘Update’ on the main user screen when done.
The user setup in ServiceNow is now complete.
Configure IMS to communicate with ServiceNow
Now that ServiceNow is configured appropriately, IMS needs to be configured with some of the values that you selected in the previous steps.
Open your instance of IMS, navigate to the Admin → ServiceNow section and configure the required values, as shown with the example data below.
| Config Item | Description | Example |
|---|---|---|
| Token Service | The token service URL of your ServiceNow instance | https://YOUR_SERVICENOW_INSTANCE/oauth_token.do |
| Username | The username for the user configured earlier | IMS_user |
| Password | The password for the user configured earlier | password |
| Client ID | The OAuth Client ID configured earlier | 265861c6573031101e3cb11b2ca1df21 |
| Client Secret | The OAuth Client Secret configured earlier | eja9008h2098hf4n32vv; |
| Event API URL | The event URL of your ServiceNow instance | https://YOUR_SERVICENOW_INSTANCE/api/global/em/jsonv2 |
| Source | Your name for IMS | IMS |
| Source Instance | Your name for this particular instance of IMS. If you have an instance of IMS per site, you might want to indicate which site this is for. | IMS Perth |
When you are done, you can click ‘Save Changes’ to persist your configuration.
The ‘Test Changes’ button can also be used to verify your configuration. This will post a test event into ServiceNow to prove end-to-end functionality, including IMS connectivity to ServiceNow through your network. If it does not work, an error message will be displayed which will indicate what areas need your attention.
Any test event posted into ServiceNow can be found by opening your instance of ServiceNow, navigating to Event Management → All Events and looking for the most recent event which matches the Source you configured earlier.
If you can find the event on the ServiceNow events list then this proves that ServiceNow and IMS are configured correctly and you are ready to create some triggers for real event integration.
Note that you can disable the integration if you wish using the ‘Enable’ toggle at the top.
The Data Flow between IMS and ServiceNow
The integration between the applications allows IMS to push an event into ServiceNow when a particular condition occurs or threshold is met. This is done by configuring a trigger in IMS for your use case.
For a full guide on configuring triggers, see our guide on condition monitoring.
An example trigger setup is covered below; the use-case will be “report an event to ServiceNow when Connectivity for an asset is less than 80%”.
Open IMS, navigate to the Triggers tab, and click ‘New Aggregation Trigger’. Fill out the trigger name, description, and choose an appropriate priority as below.
On the Query tab, select ‘IP Device’ as the grouping, the statistic of interest as ‘connectivity’, the measure as ‘is less than’, and the threshold as ‘80%’. See below for an example.
On the Actions tab, select ‘ServiceNow’ and click ‘Add Action’.
The following optional values can be configured for the ServiceNow Event if desired.
- Configuration Item Override: This value will be used to set the ‘Node’ value on the ServiceNow Event. It will be used by ServiceNow for Configuration Item binding. If not provided the ‘Node’ value will default to the Name from the selected Trigger grouping (e.g. if IP Device grouping has been selected, it will be the name of the IP Device that tripped the trigger).
- Event Description Override: The description to use for the ServiceNow Event. If not provided the description will default to the description of the Trigger as set on the Details tab.
When done, click ‘Create and Close’. The trigger will now show in the appropriate column of the Triggers list:
If any IP Device in your system has < 80% connectivity, the trigger will now fire and switch into the Alerting state.
If you open your ServiceNow instance and navigate to Event Management → All Events you should see the newly created event in the list.
If you click on the time of the event, you can see the details of the Event. The Event details will be populated using the details from the Trigger. The Additional Information section will contain some extra information from the IMS item that tripped the trigger. The contents of the additional information will be determined by the selected Trigger grouping (i.e. if IP Device grouping has been used the additional information will contain extra details for the device). This data is provided in JSON format, allowing values to be used with Event Rules you may wish to create in ServiceNow.
This demonstrates that an event can be created in ServiceNow when a particular threshold or condition is met in IMS, and allows for further custom handling of each event using ServiceNow Event Rules, as required.