haystack-HsTagDictionary

This module provides the Niagara Haystack smart tag dictionary. The Haystack dictionary is indicated by the hs namespace followed by a colon character (:). The haystack module contains the types of components typically present in any smart tag dictionary (Tag Definitions, Tag Group Definitions, Relation Definitions, and Tag Rules), all of which are described in detail in other sections of this document.

ProjectHaystack.org, created and maintains the Haystack tags and equipment point tag groups. As part of that, the organization frequently adds/removes tag definitions. Periodically, a new or updated Niagara release provides the updated haystack module. However, an alternative is available for customers that do not want the updated module or that cannot upgrade software for their whole station.

NOTE: In Niagara 4.8 and later, when a Haystack tag dictionary is already installed in a station it is no longer imported automatically when the station starts after upgrading the haystack module. This change prevents any new implied equipRef and siteRef relations from appearing in the station and affecting hierarchies and NEQL results. The latest tag, tag group, and relation definitions can be imported by invoking the Import Dictionary action on the HsTagDictionary component. Note that in the released versions of Niagara 4.4U3 and Niagara 4.7U1, the dictionary continues to import itself automatically. Consult your support channel on the availability of a haystack-rt patch jar that removes this auto-import behavior.

Figure 25. haystack palette contains 2 versions of the dictionary

Also in Niagara 4.8 and later (and in the haystack-rt patch jar for released versions of Niagara 4.4U3, Niagara 4.7U1), the haystack palette provides two versions of the dictionary: one contains only standard items while the other contains the implied equipRef and siteRef smart relations. When adding a new Haystack tag dictionary to a station the latter dictionary is the recommended one to use in order to benefit from the smart relations functionality of the dictionary.

The version that includes smart relations has the Tags Import File property pre-configured with a file Ord (module://haystack/com/tridium/haystack/data/smartRefsImport.csv) pointing to a file included with the haystack module, as shown here.

Figure 26. Tags Import File field in dictionary that includes smart relations

In Niagara 4.4U2, Niagara 4.7 and later, a patch jar for the haystack-rt module is available which allows you to modify tag definitions in the haystack dictionary using an external .csv file. The patch jar provides two added properties in the dictionary for this purpose. Using the Tags Import File and Equip Import File properties you can point to an external file, or a file within a module, to import tag values overriding those originally in the dictionary.

The installed official Haystack dictionary version number is visible in the property sheet. Periodically, the software installation will provide an updated version of the dictionary. Otherwise, if making your own modifications to the dictionary, edit the version number prior to importing your changes. If the version is the same, the import will still accept changes from the TagsImportFile. “(import)” is appended to the version found in the TagsImportFile but that version could be identical to the base version (“3.0.2” for example). For more details on making modifications, see the section on “Modifying the Haystack tag dictionary”.

Figure 27. Haystack Tag Dictionary Property Sheet view

NOTE: To use these import files, you must always specify a Tags Import File that contains a specified version number even if there are no tags to be modified. If no modifications are made to equipment tagGroups, then the Equip Import File is optional.

Importing changes allows you to modify a tag’s type, validity rule, and implied tag rule. In doing this, the tag name is key. You must use the same tag name to override an original tag. You can specify a different value for anything except the original tag name.

You can also add new tag names to add tags to the haystack dictionary, and remove a tag name to remove the tag from the dictionary. To remove a tag, the TagsImportFile must have a row with the tag name and set the value in the Kind column to “Remove”. Simply omitting the tag from the TagsImportFile will not remove it from the dictionary. For more details, see the section on “Modifying the Haystack tag dictionary”.

Properties

Besides the standard smart tag dictionary properties, the haystack dictionary contains the following configuration properties.

Name	Value	Description
`Version`	`3.0.2` (default)	Version number for the installed haystack tag dictionary. When the number is appended with “`(import)`”, this indicates that dictionary modifications have been included from the TagsImportFile and/or EquipImportFile.
`Tags Import File`	`null` (default)	A file Ord for a CSV file that can be edited using MS Excel (or other spreadsheet program). The file is used to add a new tag or relation, modify an existing tag or relation, or remove an existing tag or relation to/from the haystack dictionary. The file contents are imported to the dictionary when you invoke the haystack dictionary’s Import Dictionary action.
`Equip Import File`	`null` (default)	A file Ord for a CSV file that can be edited using MS Excel (or other spreadsheet program). The file is used to add a new tagGroup, modify an existing tagGroup or remove an existing tagGroup to/from the haystack dictionary. The file contents are imported to the dictionary when you invoke the haystack dictionary’s Import Dictionary action.

Actions

Import Dictionary — imports tag, tag group, relation, and tag rule definitions from a standard definition tags.csv file and from the optional TagsImportFile and EquipImportFile files.
Make Import Files — creates example files (tagsMerge.csv and equipMerge.csv) that can be specified as the TagsImportFile and EquipImportFile respectively to modify the tags, tag groups, and relations in the installed Haystack tag dictionary.