Integrating EcoStruxure IT Expert and ServiceNow

[JLehr]

Integrating EcoStruxure IT Expert and ServiceNow allows you to streamline IT operations, enhance efficiency, and effectively manage incidents within a single organization.

This guide provides an example EcoStruxure IT application to integrate with ServiceNow.

The example application polls data from IT Expert and creates incident tickets in ServiceNow based on incoming alarms.

https://github.com/EcoStruxure-IT/ite-public-api-example-servicenow

Before proceeding with the integration, make sure the prerequisites are met.

Refer to the appropriate guide for assistance.

Table of Contents

• Prerequisites
• Set up the example application
  • Fork the EcoStruxure IT example application in GitHub
  • Import the example application into ServiceNow
  • Fetch information from IT Expert
• How the application works
  • How job polling works
  • How the new ServiceNow incident record is created
• Appendix
  • How to create an API key in IT Expert
  • How to get your IT Expert organizationId

Prerequisites

• EcoStruxure IT Expert API key  Learn more...
• Organization ID for the organization to be integrated in IT Expert  Learn more...
• A GitHub account  Learn more...
• A running ServiceNow instance configured with the GitHub account  Learn more...

Set up the example application

Fork the EcoStruxure IT example application in GitHub

ServiceNow leverages GitHub to allow application repositories to import other applications and use them within the Developer Site.

A fork is a copy of a repository. Forking a repository allows you to freely make changes to the code without affecting the original project.

The Readme is added to the example application.

Make sure ServiceNow is configured with your GitHub account. You can then fork the repository.

See how to fork the repository:

• https://developer.servicenow.com/dev.do#!/learn/learning-plans/xanadu/servicenow_application_develop...
• https://developer.servicenow.com/dev.do#!/guides/xanadu/developer-program/github-guide/using-service...

Import the example application into ServiceNow

Once the repository has been forked and imported into your ServiceNow instance, you need to include the the API key for IT Expert and your organizationId.

The imported example application is intentionally disabled by default. To start using the application, create a new record:

1. Navigate to the EIT_POLLING_STATE table and insert a new row.
2. Enter the following information into the form:

• Config organization ID: The ID of your organization in IT Expert
• Config host: http://api.ecostruxureit.com
• Config API token: The API key generated in IT Expert
• Job name: polling.1
• The job name can be changed but will require changes in the JavaScript code. Make sure that your API key and organization ID are valid.

5. Click Submit to save the new record.

Fetch information from IT Expert

To start fetching information from IT Expert:

Go to Scheduled Script Execution and enable the script EIT_POLL_ALARMS_WITH_INVENTORY.

This will start an automatic process of polling information from IT Expert.

Once the script is running correctly, proceed to initiate the business rule that will create the incident tickets in ServiceNow.

To verify that incidents are being created by alarms fetched from EcoStruxure IT, copy an Ind sys ID in the EIT_POLLING_STATE table and paste it into the ServiceNow Sys ID search.

How the application works

The sample application runs on ServiceNow. It polls alarm and inventory data from EcoStruxure IT using its API. For each new alarm, it creates a new ServiceNow incident.

The new incident includes information from the alarm and details from the inventory data that the alarm references, such as device labels and location labels.

The application is built using the following ServiceNow components:

Component	Description
Custom tables	The application stores all fetched data in tables and performs data manipulation exclusively using these tables. One reason for this approach is to avoid handling data in memory due to limitations in the ServiceNow JavaScript Runtime. See Create a table
Classic business rules	The business rule is triggered each time a new alarm is created. The rule logic includes retrieving additional information from the inventory custom table and creating the incident record. See Business rules
Scheduled script executions	Performs the periodic fetching of data from EcoStruxure IT See Scheduled script executions and events objectives
Outbound REST web services	Representation of EcoStruxure IT API endpoints See Outbound REST API web service

How job polling works

ServiceNow executes the polling job periodically.

At the beginning of each cycle, the polling job reads its state and configurations from the eit_polling_state table.

First, it checks whether it's time to fetch the entire state snapshot of the inventory data. If not, it checks if it's the right time to fetch recent changes in the inventory data.

This step is performed before fetching the alarm data to ensure that any new events have corresponding inventory data available.

The next step is to determine if it's time to load the entire alarm state snapshot or just the alarm delta changes.

At the end of the job, the time of the current cycle is saved in the eit_polling_state table for future self during the next execution cycle.

The result of the polling job is that the latest inventory and alarm data fetched from EIT is stored in the eit_inventory and eit_alarm tables, respectively.

How the new ServiceNow incident record is created

The polling job ensures that the latest inventory and alarm data is fetched from EIT and saved into the appropriate tables.

When a new alarm is saved into the alarm table, ServiceNow initiates a business rule.

This business rule takes the new alarm as input. It looks up device labels using the device ID from the alarm and retrieves location labels based on the same ID.

The rule then constructs a text string from the alarm ID, alarm message and label, location labels, and device labels. This text is used as the incident description when creating a new record in the incident table.

At the end of the business rule, the system saves the incident system ID and alarm ID into a special table called eit_alarm_to_incidents for maintenance purposes.

Appendix

How to create an API key in IT Expert

See Getting access to the IT Expert API as an end user

1. Log in to IT Expert.
2. Go to Administration > More > API.
3. Generate a key.

IMPORTANT: For security purposes, you are required to copy the key when it is created. Save the key in a safe place. Your key cannot be retrieved. If it is lost, you will have to delete it and create a new one.

How to get your IT Expert organizationId

1. Go to https://api.ecostruxureit.com/rest/
2. To authorize yourself, click Authorize and enter your API key. The key is case sensitive - be sure to type it correctly.

3. Open the first tab in the Organization section.
4. Click Try it out and then execute.
5. Copy and save the organizationId listed in the response body in a safe place.

If the execution returns an unauthorized error, you have entered the wrong API key.