Haystack smart tag dictionary

This module provides the Niagara Haystack smart tag dictionary.

The Haystack dictionary is indicated by the hs or h4 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). ProjectHaystack.org created and maintains the Haystack tags and equipment point tag groups. As part of that, the organization frequently adds and removes tag definitions. Periodically, a new or updated Niagara release provides the updated haystack module. However, an alternative is available for customers who do not want the updated module or who cannot upgrade software for their whole station.

Note: In Niagara, 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.
Figure 1. Haystack palette contains 2 versions of the dictionary


In Niagara, 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 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 2. Tags Import File field in dictionary that includes smart relations


In latest version of Niagara a 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 3. 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”.