How-To: Connect to Canary System

What Does This Article Cover?

This article provides an overview of connecting Intelligence Hub with Canary System, focusing on both retrieving and sending data between the two systems. The primary method for accomplishing data exchange is using the Canary API endpoints.

This article covers the following:

What is Canary System?
Canary Read/Write APIs
- Security and Token
Design Considerations
Configure REST API connection for Canary Read Endpoint
Configure REST API connection for Canary Write Endpoint
Other related material

What is Canary System

Canary System is a data historian platform offered by Canary Labs. The primary component of the Canary System is the Canary Historian which provides an industrial time series database. The Canary System also includes data collection and data client tools to easily integrate data exchanges with the historian server. Please see this Canary Knowledge Base article for additional information.

Canary Read/Write APIs

The Canary System offers two web APIs for data exchanges:

A Read API is available for reading data from the Canary Historian; all requests are routed through the Canary View subsystem service.
A Write API is available for writing data to the Canary Historian; all requests are routed through the Canary Store and Forward subsystem service.

Security and Token

Security considerations must be taken when setting up and connection via the web APIs offered in the Canary System. It is recommended to use API Token security and not to use Anonymous options. Within the Canary Identity tile of the Canary Administrator, ensure that “Enable Anonymous” is not enabled under the External Provider Options, as show here:

The following steps show the required configurations needed within the Canary Administrator client to create a dedicated Canary application user is created, assigned a non-expiring API token, and configured the user with read and write access at the root level of the tag structure.

Step 1: Create dedicated application user, using the Identity Tile:

Step 2: From the API Tokens sub-menu, add a new token with the following configurations:

User Name: [HB_KB_API_User]
Token State: Allow
Expiration Date: Never

Step 3: From the Tag Security sub-menu, ensure the “Views” root is highlighted and select to add a new permission, entering the following configurations:

Entity Type: User
Entity Name: [HB_KB_API_User]
Permissions: ReadWrite

For enhanced security, granular access can be accomplished by creating and using multiple API Tokens and assigned for least needed privilege. Furthermore, for Read API uses, configuring the permission on a virtual view would provide the most security. However, for Write API, the only method to provide appropriate access for the Store and Forward service is to configure the permission on datasets listed within the historian.

Configuring an Intelligence Hub REST Client Connection for Canary Read

The Intelligence Hub REST Client Connection is used to read data from the Canary Read API Endpoints. The REST Client Connection needs configured with the Canary system Read API URL (default port: 55293) the following security settings:

Authentication Type: Bearer Token
Token: [generatered API Token] or [System.Variable.Canary_Bearer_Token]
- Note: It’s recommended to store the Canary Token(s) in System Variables instead of direct entry in connections.

Once a REST Client Connection is setup, connection Inputs will be used to configure data reads from Canary API Endpoints. Please see the linked article below for HOW TO Exchange(read) Data.

Configuring an Intelligence Hub REST Client Connection for Canary Write

The Intelligence Hub REST Client Connection is used to write data to the Canary Write API Endpoints. The REST Client Connection needs configured with the Canary system Read API URL (default port: 55293) the following security settings:

Authentication Type: Bearer Token
Token: [generatered API Token] or [System.Variable.Canary_Bearer_Token]
- Note: It’s recommended to store the Canary Token(s) in System Variables instead of direct entry in connections.

Once a REST Client Connection is setup, connection Outputs will be used to configure POST calls to Canary API Endpoints for session token acquisition and data writing. Please see the linked article below for HOW TO Exchange(write) Data.