System Integration

NOTE: The functionality displayed in this topic might not be the same as what you see for your organization. Your Energy Hub feature plan subscription determines which functions and features are available for your organization. For feature plan details, see Feature plans.

System Integration enables Energy Hub to exchange data with other applications through an application programming interface (API). To access System Integration, you need an active subscription to one of the Energy Hub API feature plans, or you need the API Add On for one of the regular feature plans. For information on subscriptions, see Energy Hub subscriptions.

Overview

Use System Integration to share Energy Hub data with other applications. System Integration provides an API that is based on the Open Authorization (OAuth) 2.0 protocol, an open, industry-standard framework for token-based authorization on the internet.

NOTE: Data access for other applications is limited to data for the organization the Energy Code Compliance module has been activated for.

Configuring System Integration

To configure System Integration, you need to create an access client for each application that you want to integrate with Energy Hub. The client application then uses access client credentials to connect to Energy Hub. An access client has a client ID, a client secret, a role, and access permissions.

Property Description
Client ID The client ID is an auto-generated value that Energy Hub uses to identify the client application requesting access.
Client secret The client secret is an auto-generated 'password' that the client application uses to authenticate with Energy Hub.
Role The role determines which actions the client application can take in Energy Hub. This is similar to the user roles in Energy Hub.
Access permissions Access permissions determine which data the client application can access in Energy Hub. This is similar to the user access permissions in Energy Hub. For example, the "All My Organization" access permissions allow access to all data in the organization, but not data in other organizations.

System Integration prerequisites

Before configuring System Integration, verify that:

  • You have a subscription to an API feature plan or an API add on.
  • The Integrations tab is visible in Energy Hub Setup. The tab is only displayed with an API feature plan or an API add on

To create an access client:

  1. In Energy Hub, go to Setup > Integrations.
  2. On the API tab, select Create new access client. The access client configuration panel displays.
  3. In the access client configuration panel, define the new access client details.

    NOTE: Copy the client secret and keep it secure. The application using the access client to connect to Energy Hub needs the client secret to authenticate with Energy Hub. You cannot view the client secret again in Energy Hub after this configuration panel closes.

  4. Select Create.
  1. In Energy Hub, go to Setup > Integrations.
  2. On the API tab, in the access client list, find the access client that you want to edit.
  3. From the options menu (three dots) for the access client, select Edit client. The access client configuration panel displays.
  4. In the access client configuration panel, update the information that you want to change.
  5. Select Save.
  1. In Energy Hub, go to Setup > Integrations.
  2. On the API tab, in the access client list, find the access client that you want to delete.
  3. From the options menu (three dots) for the access client, select Delete client to delete the access client.

    NOTE: Deleting an access client will disconnect any connections for this client.

  1. In Energy Hub, go to Setup > Integrations.
  2. On the API tab, in the access client list, find the access client that you want to generate the new secret for.
  3. From the options menu (three dots) for the access client, select New secret. The generate new client secret dialog displays.
  4. In the generate new client secret dialog, select Generate to generate a new client secret.

    NOTE: Generating a new client secret will immediately suspend any client connections for this access client. To connect again, the client application needs to re-authenticate using the new client secret. The new client secret will be displayed after you select Generate, for you to copy it.

Using System Integration

The Energy Hub API uses GraphQL as a query language. Use any REST client application to connect to the API.

For information about the integrations API, the Energy Hub data model, and GraphQL query details, see Energy Hub API Reference (requires an Energy Hub login).

System Integration prerequisites

Before you can integrate a client application with Energy Hub, you need to configure System Integration.