How to set up a Canary data source?
INTRODUCTION
Canary Labs provides industrial data management solutions, specializing in software for collecting, storing, analyzing, and visualizing historical and real-time data from various industrial processes and systems. Their flagship product, Canary Historian, is known for its efficient time-series data handling and robust analytics capabilities.
To integrate with and ingest data from Canary historian, a datasource of provider type Canary can be added and configured in ConfigHub.
CREATING CANARY PROVIDER
To add a Canary data source, in ConfigHub go to Data in the left side menu, then Data sources, choose + Add data source. Fill out 'Data source details' on the first step of the datasource creation wizard: type the name of the data source, select “Canary” from the Provider dropdown. Selecting the capabilities for the data source with the given checkboxes will open additional properties to enter, grouped in following sections:
Connection details - lists properties related to the configuration of the connection that will be established with datasource.
Time series details - lists properties relevant for context data
Asset details - lists properties relevant for asset data
Following properties need to be populated to establish the connection to the Canary historian:
“Host" - mandatory host URL of Canary historian
“Port" - mandatory port of Canary historian
"Username" - mandatory username used to establish a connection to Canary historian
"Password" - mandatory password used to establish a connection to Canary historian
“Views" - optional field that allows you to specify views the data will be ingested from:
If a view or multiple views are defined, only tags and assets within these views are ingested.
If no view is defined, the datasource will ingest all data regardless of the views.
You can connect to the Canary server using two options: via TM-Connect (TrendMiner Connect Agent) or without TM-Connect. For further information, please refer to Establishing a connection to Canary for more details.
Important
For SaaS environments only. When connecting to the Canary historian via the TM-Connect tunnel, you can choose a pre-configured proxy from the "Proxy" dropdown menu. Upon selection, the host field will be automatically populated with the proxy name and the port field will be automatically populated with value 80. The fields will become read-only.
 |
TIME SERIES CAPABILITY
Following properties need to be populated to configure time series capability:
“Configure Data quality” - optional field that allows you to specify the quality of data to ingest. By default, only time series values with GOOD quality are ingested. However, you can choose to include time series values with BAD and/or UNCERTAIN quality as well.
“Prefix” - optional text can be entered here that will be used to prefix the tag names in TrendMiner, if a value is entered. Warning: this cannot be changed. The datasource can however be deleted and you can start the configuration over again.
“Tag filter” - optional regular expression can be entered here. Only tags with names that match this regex will be retained when creating tags.
For plot and index calls, we retrieve 4 key data points per interval using the following Canary functions:
Start: Retrieves the starting point of the interval.
End: Retrieves the endpoint of the interval.
MaximumActualTime2: Retrieves the maximum value and its corresponding time within the interval.
MinimumActualTime2: Retrieves the minimum value and its corresponding time within the interval.
These way we ensure that we capture the critical data trends for each interval, providing a clear representation of the range and changes within the period while providing the optimized performance.
Data type mapping: Tag type mappings between Canary and TrendMiner are documented here: How does TrendMiner determine tag type?
Please note:
Tags with a data type of 'Disabled' will be excluded from the sync.
If the data type is null or missing, the tag is skipped, and the following message is logged:
“Skipping [tagName] tag because TagProperties Data Type is null for tag“
Important
Please make sure the property “Data Type” exists in on the response of Canary API call POST /getTagProperties. If the property is not present, please follow the procedure for importing the data type property through the Canary admin. You can find the documentation on how to import custom tag properties here: https://helpcenter.canarylabs.com/t/p8hvlzv/how-to-import-custom-tag-properties-version-23
ASSET CAPABILITY
There are no asset specific properties to configure for Canary provider.
Asset tree in TrendMiner is built based on Canary virtual view that contains asset types. The node names represent assets of type ASSET, while the underlying tags are classified as assets of type ATTRIBUTE and can be added to the trend chart.
Example of asset structure in Canary Historian:
Example of corresponding asset tree in TrendMiner:
OUT OF SCOPE:
The system tags - diagnostic tags, e.g. DemoHistorian.{Diagnostics}.Sys.Memory Physical, - aren't synced into TrendMiner.
The aggregate tags aren't synced into TrendMiner.