EcoStruxure IT Expert API

The EcoStruxure IT Expert - API gives users a way to integrate EcoStruxure IT into their own environments. Its functionalities allow users to maintain a local data store or to build applications that react to changes in their critical infrastructure. Overview The APIs grant access to: Locations  All locations created in EcoStruxure IT. Devices  All discovered devices, including the most relevant device properties, relationships to other devices, and locations. Alarms  All alarms generated by devices or threshold configurations, including information about the alarm’s lifetime and severity, and a reference to the originating device. Sensors  All device sensors, including unit, label, and a reference to the parent device. Measurements  Measurements for device sensors. For everything except measurements, the APIs allow users to:  Retrieve a snapshot of their "State of the World", retrieving all existing devices, locations, and sensors as well as all active or recently cleared alarms. Poll for changes to get the changes that have occurred since the last snapshot or poll. For measurements, the APIs allow users to: Stream live measurements where a connection is kept alive and measurements are sent as they become available from the time at which the connection was established. Replay measurements that were missed because of a short period of being disconnected from the live measurement stream. The APIs are relevant both for customers who monitor their own environment and partners who monitor infrastructure environments on behalf of their customers. IT Expert API technical documentation You can download detailed API documentation and a technical breakdown of the various features and example programs that demonstrate the proper usage here: https://api.ecostruxureit.com/ For rate limits applicable to the APIs, please read the documentation. Note that rate limits may vary for the different API calls.

All customers who have an active IT Expert subscription, either paid or trial, can use the EcoStruxure IT Expert - API to monitor their own inventory and alarms.   Creating a key   To be able to call the APIs, you must first generate an API key. You can see a list of your currently valid API keys on the Administration > More > API tab.    Click Generate new API key.  Create a key to access your equipment data, or check This is a demo key for testing purposes to create a demo key to access a set of demo data for testing.    IMPORTANT: For security purposes, you are required to copy the key when it is created. Store it in a safe place. Your key cannot be retrieved. If it is lost, you will have to delete it and create a new one.  

Partners can use the EcoStruxure IT Expert - API to access the device data of their connected and valid customers. A customer is considered valid for access via the APIs when: the customer has an active IT Expert subscription, either paid and trial, and the customer has allowed their partner(s) to access their data via the API. Getting customer consent Partners must contact the customer and ask them to log in to their EcoStruxure IT, navigate to Administration > Subscriptions, and check Allow API access to device data in the Your partner section. customer-consent_360004769678.png Verifying customer consent The API provides a call that allows Partners to get a list of all the unique identifiers for customers who are currently covered by the key. When a customer revokes their consent, their identifier will no longer appear in the list. If a customer has revoked their consent, the API automatically denies any further access to their data. It is still the responsibility of the Partner to verify the customer's continued consent and take appropriate actions should access no longer be granted.  Creating a key To be able to call the APIs, Partners must first generate an API key. You can see a list of currently valid API keys on the Administration > API tab.   partner-api-key-list_360004769678.png partner-api-key-create_360004769678.png Partners can create three types of keys: Demo Accesses a set of data from a demo customer for testing purposes All Customers Grants access to data from all their valid customers. Newly added customers are dynamically included. Invalid customers do not appear in the list. Specific Customers Grants access to the data from a selected set of their valid customers. Invalid customers do not appear in the list. IMPORTANT: For security purposes, you are required to copy the key when it is created. Store it in a safe place. Your key cannot be retrieved. If it is lost, you will have to delete it and create a new one. partner-api-key-copy_360004769678.png

A valid IT Expert subscription is required to use the EcoStruxure IT Expert API. Partners can use the API for their customers if that customer has an IT Expert subscription. Customers and Partners using the API should make sure that the calls they make don't cause performance issues for the EcoStruxure IT platform or for other API users. Schneider Electric reserves the right to disconnect customers or Partners either temporarily or permanently if their API calls cause performance issues.

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_developer/SSS_Lab_ForkRepo_xanadu https://developer.servicenow.com/dev.do#!/guides/xanadu/developer-program/github-guide/using-servicenow-provided-application-repositories   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:   Navigate to the EIT_POLLING_STATE table and insert a new row. 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. 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   Log in to IT Expert. Go to Administration > More > API. 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   Go to https://api.ecostruxureit.com/rest/ To authorize yourself, click Authorize and enter your API key. The key is case sensitive - be sure to type it correctly. Open the first tab in the Organization section. Click Try it out and then execute. 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.