What Does This Article Cover?
This article provides examples of configurations for simple data exchanging between Intelligence Hub and Canary System using the Canary API endpoints.
This article covers the following:
- Overview of Connections Input and Output
- Read API Inputs
- Get Tag Data – Use of the getTagData endpoint for getting the latest tag value or a time window of stored raw data.
- Live Data Subscription – Using a Live Data Token to subscribe to receive tag updates.
- Get Asset Information – Obtaining asset information of an asset defined within a Canary View
- Write API Input/Output
- Get Session Token
- Store Tag Data
- Other related material
Overview of Connections Input and Output
This article is segmented into two segments, one for each API service. The connection linked to the Read API service will utilize Input configurations to call Get method endpoints, while the connection linked to the Write API service will utilize both Input and Output configurations for Get and Post method endpoints.
Read API Inputs
Connection Inputs will be used to read data into Intelligence Hub from the Canary System Read API service. The following sections provide examples of simple data interfaces.
Get Tag Data
Latest Value
In this example, the getTagData method of the Read API will be used to get the latest value of a historian data tag. Only a single tag name is provided within the URL and all other optional parameters are excluded, thus returning only the latest value of the tag. The value of interest for this example is the “CanaryWater.Hays.Station1.Pump01.Flow” tag from the “Roadshow – Water District” view.
Configure an input with the following settings:
- Name: GetTagData_LastValues_HaysPump01Flow
- Endpoint URL:
/getTagData?tags=Roadshow - Water District.CanaryWater.Hays.Station01.Pump01.Flow
- HTTP Method: Get
- Content Type: JSON
Save the newly created input and select the “Test Input” to yield the following results:
Raw Values
In this example, the getTagData method of the Read API will be used to get raw historian values of a data tag. Only a single tag name is provided within the URL, along with a start and end time for the desired raw data timeframe. For this example, the end of the timeframe will be the time of input execution and the start time of the timeframe will be 1 hour prior to the input execution (using relative time units). The value of interest for this example is the “CanaryWater.Hays.Station1.Pump01.Flow” tag from the “Roadshow – Water District” view.
Configure an input with the following settings:
Note: A parameter has been used to allow for timeframe flexibility by future Intelligence Hub objects.
- Name: GetTagData_RawValues_HaysPump01Flow
- Parameters:
Parameter Default Value startTime "now-1h" - Endpoint URL:
/getTagData?tags=Roadshow - Water District.CanaryWater.Hays.Station01.Pump01.Flow&startTime={{this.startTime}}&endTime=now - HTTP Method: Get
- Content Type: JSON
Save the newly created input and select the “Test Input” to yield the following results:
Get Live Data Subscription
The following examples will show the configurations for how Intelligence Hub inputs can be utilized to subscribe to a Live Data session. Three inputs will be created to obtain a Live Data Token, request a return of the subscribed data, and finally revoke the obtained Live Data Token.
These examples will also use the “CanaryWater.Hays.Station1.Pump01.Flow” tag from the “Roadshow – Water District” view.
Get Live Data Token
To initiate a subscription session, the getLiveDataToken method of the Read API needs to be called to create the subscription and endpoint response will provide the Token created for the new subscription. In this example, only a single tag name is provided for the subscription. The “CanaryWater.Hays.Station1.Pump01.Flow” tag from the “Roadshow – Water District” view will again be used.
Configure an input with the following settings:
- Name: GetLiveDataToken
- Endpoint URL:
/getLiveDataToken?tags=Roadshow - Water District.CanaryWater.Hays.Station01.Pump01.Flow
- HTTP Method: Get
- Content Type: JSON
Save the newly created input and select the “Test Input” to yield the following results:
Note: The returned token will be used in Get Live Data section below.
Get Live Data
While a subscription session is open, the getLiveData method of the Read API is called to return the newly stored data for the tags in scope of the subscription. The Live Data session Token needs to be provided within the URL. The returned values will be all new values logged to the Canary Historian since the last call of the session.
Configure an input with the following settings:
- Name: GetLiveDataToken_Values
- Parameters:
| Parameter | Default Value |
| apiDataToken | "[token value returned from above test]" |
- Endpoint URL:
/getLiveData?liveDataToken={{this.apiDataToken}} - HTTP Method: Get
- Content Type: JSON
Save the newly created input and select the “Test Input” to yield the following results:
Revoke Live Data Token
To close the subscription session, the revokeLiveDataToken method of the Read API needs to be called to close the active subscription. The Live Data session Token needs to be provided within the URL.
Configure an input with the following settings:
- Name: GetLiveData_RevokeToken
- Parameters:
Parameter Default Value apiDataToken "[token value returned from above test]" - Endpoint URL:
/revokeLiveDataToken?liveDataToken={{this.apiDataToken}} - HTTP Method: Get
- Content Type: JSON
Save the newly created input and select the “Test Input” to yield the following results:
Get Asset Information
The following example configurations will show how Intelligence Hub inputs can be configured to read a View’s Asset information. The inputs created will return the tags of a specified Asset Type and the instances of that specified Asset.
These examples utilize the implementation of the Canary Roadshow configuration. The “Roadshow – Water District” view will be the view in scope and the “Pump” Asset Type will be the specified asset of interest.
Asset Type Tags
In this example, the getAssetTypeTags method of the Read API will be used to get a list of tags within the Pump asset type from the Roadshow – Water District view. The following image shows the Asset Tags as seen in Canary Administrator Asset Definition for the Pump asset type.
Configure an input with the following settings:
- Name: GetAssetTypeTags_WaterDistrict_Pump
- Endpoint URL:
/getAssetTypeTags?view=Roadshow - Water District&assetType=Pump
- HTTP Method: Get
- Content Type: JSON
Save the newly created input and select the “Test Input” to yield the following results:
Asset Instances
In this example, the getAssetInstances method of the Read API will be used to get an array of Pump asset instances from the Roadshow – Water District view. The following image shows the Asset Instances as seen in Canary Administrator Asset Definition for the Pump asset type.
Configure an input with the following settings:
- Name: GetAssetInstances_WaterDistrict_Pump
- Endpoint URL:
/getAssetInstances?view=Roadshow - Water District&assetType=Pump
- HTTP Method: Get
- Content Type: JSON
Save the newly created input and select the “Test Input” to yield the following results:
Write API Inputs and Outputs
Connection Outputs will be used to write data from Intelligence Hub into the Canary Historian. However, a Connection Input will be needed to request a session Token for use in Write API endpoints.
Store Data Value to Tag
The examples in the following sections demonstrate simple configurations that allow for writing a single value at a time to one specified tag within a Canary dataset.
Get Session Token
To initiate a storage session, the getSessionToken method of the Write API needs to be called to create the working session. The endpoint response will provide a Token for use in calling storage methods.
At minimum, the getSessionToken expects a payload that provides the list of Historians to connect and a client ID for the session. Additionally, session settings values can be provided that including the ability to set a desired timeout for the client session and set whether a dataset shall be created if the dataset does not exist. Additional options can be found in the Canary Write API documentation.
For this example, we will request the following setting for the session:
- Historian: “localhost”
- Client ID: IHTest
- Settings:
- Client Timeout: 300,000 ms (5 Minutes)
- autoCreateDatasets: true
In order to obtain the response that contains the generated Token, a Connection Input will need to be configured. Configure an input with the following settings:
- Name: GetSessionToken
- Endpoint URL: /getSessionToken
- HTTP Method: Post
- Content Type: JSON
- Request Body:
{
"historians":["localhost"],
"clientId":"IHTest",
"settings":{
"clientTimeout":300000,
"autoCreateDatasets": true
}
}
Save the newly created input and select the “Test Input” to yield the following results:
Store Single Data Value
Once a storage session has been initiated, data can be written to tag storage. In this example, a single value is written to a new tag in a new dataset. The storeData method of the Write API will be used and the request body payload will contain the dataset name, tag name, and value to be stored.
Note: Once a write has been made on a tag, that tag will be write-locked until the session is closed or expires.
Configure and save an output with the following settings:
- Name: StoreData_SingleValue
- Endpoint URL: /storeData
- HTTP Method: Post
- Content Type: JSON
After the new output has been saved, enter the following expression into the “Expression to write” box and click “Write Output”:
({
"sessionToken": "20250624194519071_8f3ee81da729",
"tvqs": {
"IHTest.tag1" : [
[
"2025-06-07T11:01:01.0000000-05:00",
9
]
]
}
});
The results should yield the following:
Revoke Session Token
To close a storage session, the revokeSessionToken method of the Write API needs to be called. The endpoint requires the Session Token to be passed in the request body.
Configure and save an output with the following settings:
- Name: RevokeSessionToken
- Endpoint URL: /revokeSessionToken
- HTTP Method: Post
- Content Type: JSON
After the new output has been saved, enter the following expression into the “Expression to write” box and click “Write Output”:
({
"sessionToken": "20250624212919972_c261033266ba",
});
The results should yield the following:
Other related material