Linked Tags (version 24)
Linked Tags are 2 or more tags that may exist in different (or the same) DataSets which the user wishes to link together to create one single data stream of history. The user may wish to link tags together if migrating historical data into a separate DataSet while current data is being logged to another or if a tag name/path changes in the source and needs to link the new name with the old one. Without linking the tags together, the historian has no knowledge that the two are related and sees them as distinct tags.
Prior to Linked Tags, if a user wanted to merge historical data in with current data, all of the tags would have to reside in the same DataSet which can be tedious to achieve. Similarly, if a user wanted to sync a new tag name with its old name, the old name would have to be renamed to match the new one in all historical files provided they resided in the same DataSet (How to Rename Tags in a DataSet). If they did not reside in the same DataSet, they could not be synced.
When linking tags together, it is expected that there is a progression from one tag to the next in regards to the tags' historical data and that there may be overlap between them.
When there is overlap, the user will have the option of deciding which tag has precedence.
Linked Tags do NOT allow the user to fill a gap within another tag's history.
Although it is possible to add multiple historian views to a single Views service (see How to Add a Remote Historian View), tags can only be linked within a single historian view. Similarly, Linked Tags only work with the raw historian tag name that is derived from the historian view, not a virtual view.
Configuration
- Open the Views tile in the Canary Admin and select the historian view.
- Click the yellow down-arrow in the VIEW menu and select IMPORT LINKED TAGS.
- There are 2 options for importing linked tags.
- ExplicitTagPaths - tags are explicitly listed in a CSV file with 2 or more columns depending on how many tags are being linked together in a single group. When tags' data overlap, tags in the left column take precedence over tags in the right column. Tag names should be prepended with the DataSet name (i.e. DataSetName.Branch1.Branch2.TagName). If a tag cannot be found, it will be ignored. If two linked tag groups contain the same tag path, they will be merged together.
Example - Regex - a CSV file that contains exactly 3 columns. The first column contains the Primary Expression. This will be evaluated against all of the tags in the view. When a match is found, the next two columns are used to find a matching secondary tag path. The second column contains the Dataset Match Expression. This is used to determine in which DataSets to look for a matching secondary tag. If a DataSet matches this regular expression, it will then be searched for the secondary tag. The third column contains the Secondary Tag Expression. When a primary match is found, a secondary tag path is constructed using this expression. Regex capture placeholders ("$1", "$2", etc.) in the secondary expression will be replaced using the capture groups from the primary expression. If the secondary tag is found in the DataSet(s), then the primary tag and secondary tag are linked, with the secondary tag given priority over the primary tag.
Example
The Primary Expression is looking for any tags that are found in "DatasetA##". If it finds a tag that matches this expression, it looks for a secondary path in "DatasetB##".
$1 from column C matches the capture group (.+$) from the Primary Expression in column A. Essentially, it is looking for the exact same tagpath in B as it appears in A. If the secondary path is found, the two tags are linked together with the secondary path taking precedence over the primary path.
Regex rules can "chain" tags together. If a regex rule links a primary and secondary tag together, the secondary tag can be linked to a third tag through another regex rule. Then all three of the tags will be linked together with the third tag having the highest priority. There is no limit to the number of tags that can be chained. Adding to the example above, a second row is introduce to link a tag from DataSetA## to DataSetB## to DataSetC##.
Example
- ExplicitTagPaths - tags are explicitly listed in a CSV file with 2 or more columns depending on how many tags are being linked together in a single group. When tags' data overlap, tags in the left column take precedence over tags in the right column. Tag names should be prepended with the DataSet name (i.e. DataSetName.Branch1.Branch2.TagName). If a tag cannot be found, it will be ignored. If two linked tag groups contain the same tag path, they will be merged together.
- Check the box Replace existing if wishing to overwrite the previously configured Linked Tags. If unchecked, the linked tags will be added to the existing database.
After the tag linking rules are processed, an info message will be logged stating the number of tags that were linked.
The database containing these tags is located in C:\ProgramData\Canary\Historian Web Service\LinkedTags\LinkedTags.sqlite. This database is evaluated each time a DataSet is modified by the addition or removal of tags. When rules from a CSV file are imported, a backup of the SQLite database is created along with a copy of the CSV file. Additionally, if the EAL (Enhanced Audit Log) is enabled, a message is logged with the settings used for the import and the path to a copy of the CSV file that was saved for auditing purposes.
A Linked Tags Last Build Time property will appear in the View menu when the historian view is highlighted displaying the last time it was built.
Similarly, a linked tag will have a Linked Tag property containing all of the tags that are a part of its group. Tags are ordered chronologically based upon their historical data.
Data Retrieval
When data is requested for any linked tag in a group, the data is retrieved from whichever tag's data range covers the requested timestamp. The "data range" for a tag is defined as the time range between the earliest and latest TVQs for the tag.
When the range of data overlaps between linked tags, the tag with higher priority is given precedence when returning data and only the data from that tag is returned.
If data is requested for a time range that spans the data ranges of multiple linked tags, TVQs will be seamlessly returned from all of the relevant tags.
Storing Annotations
When adding an annotation to a linked tag, the annotation will be stored with the tag whose data range covers the annotation timestamp in the appropriate hdb2 file.
Error Conditions
- When searching for secondary tags for a regex rule, if multiple secondary tags are found for a single primary tag then the first secondary tag will be linked and an error message will be logged for the remaining secondary tags.
- If a regex primary expression matches on a tag that exists in an explicitly linked tag group, an error will be logged and the regex rule will skip the tag.
- If a regex primary expression matches on a tag that was already matched by another primary expression, an error will be logged and the regex rule will skip the tag.
- If a primary tag matches on a secondary tag that is already linked to a primary tag, an error will be logged.
- If a primary tag matches on itself as a secondary tag, an error will be logged.
- If regex rules create a circular "chain" of mappings, where the tail of the chain is linked to the head of the chain, an error is logged and none of the tags in the chain will be linked.