Technical Document

Tagging Guide

July 14, 2016

Tagging Guide
Tridium, Inc.
3951 Westerre Parkway, Suite 350
Richmond, Virginia 23233
U.S.A.

Confidentiality
The information contained in this document is confidential information of Tridium, Inc., a Delaware corpora-
tion (“Tridium”). Such information and the software described herein, is furnished under a license agreement
and may be used only in accordance with that agreement.
The information contained in this document is provided solely for use by Tridium employees, licensees, and
system owners; and, except as permitted under the below copyright notice, is not to be released to, or re-
produced for, anyone else.
While every effort has been made to assure the accuracy of this document, Tridium is not responsible for
damages of any kind, including without limitation consequential damages, arising from the application of the
information contained herein. Information and specifications published here are current as of the date of this
publication and are subject to change without notice. The latest product specifications can be found by con-
tacting our corporate headquarters, Richmond, Virginia.

Trademark notice
BACnet and ASHRAE are registered trademarks of American Society of Heating, Refrigerating and Air-Con-
ditioning Engineers. Microsoft, Excel, Internet Explorer, Windows, Windows Vista, Windows Server, and SQL
Server are registered trademarks of Microsoft Corporation. Oracle and Java are registered trademarks of
Oracle and/or its affiliates. Mozilla and Firefox are trademarks of the Mozilla Foundation. Echelon, LON, Lon-
Mark, LonTalk, and LonWorks are registered trademarks of Echelon Corporation. Tridium, JACE, Niagara
Framework, NiagaraAX Framework, and Sedona Framework are registered trademarks, and Workbench,
WorkPlaceAX, and AXSupervisor, are trademarks of Tridium Inc. All other product names and services men-
tioned in this publication that is known to be trademarks, registered trademarks, or service marks are the
property of their respective owners.

Copyright and patent notice

This document may be copied by parties who are authorized to distribute Tridium products in connection
with distribution of those products, subject to the contracts that authorize such distribution. It may not oth-
erwise, in whole or in part, be copied, photocopied, reproduced, translated, or reduced to any electronic
medium or machine-readable form without prior written consent from Tridium, Inc.
Copyright © 2016 Tridium, Inc. All rights reserved.
The product(s) described herein may be covered by one or more U.S. or foreign patents of Tridium.
Contents
About this guide .................................................................................................5
Document change log ................................................................................5
Related documents ....................................................................................5

Chapter 1 Tagging Overview............................................................................7

License requirements .................................................................................7
Tagging process.........................................................................................7

Chapter 2 Common Tagging Tasks ...................................................................9

Creating a tagged device ...........................................................................9
Adding Ad Hoc tags .................................................................................10
Removing a tag ........................................................................................11
Add tags to objects in the Discovered pane...............................................11
Add tags in the Database pane .................................................................12
Adding a tag group to a component .........................................................13
Adding a tag to an existing tag group .......................................................14
Adding tags using Batch Editor.................................................................15
Editing tags in a template .........................................................................16
View Implied Tags using Edit Tags dialog ..................................................17
Viewing implied tags using Spy view .........................................................18
Selecting or Exiting Tag Mode (Manager views).........................................19
Exporting and importing tag dictionaries ..................................................20
Creating and exporting a new tag dictionary ...................................20
Editing a tag dictionary exported to CSV.........................................21
Importing a tag dictionary in CSV format.........................................24
Chapter 3 Tagging reference ..........................................................................27
About tags...............................................................................................27
Online tagging vs. offline tagging .............................................................28
About the Edit Tags dialog .......................................................................28
Components in the tagdictionary module..................................................30
About the Tag dictionary Service ....................................................31
Tag Group Monitor ........................................................................32
Tag Dictionary................................................................................33
Tag Definitions...............................................................................35
Tag Group Definitions ....................................................................36
RelationDefinitions .........................................................................37
Tag Rules .......................................................................................38
Data Policies ..................................................................................41
Plugins in the tagdictionary module ..........................................................42
Tag Dictionary Manager view..........................................................42
Glossary ............................................................................................................45

Index.................................................................................................................47

July 14, 2016 3

Contents Tagging Guide

4 July 14, 2016

About this guide
This guide explains to the Systems Integrator how to use the Niagara Tagging feature.

Document change log

Updates (changes and additions) to this document are listed below.
• Updated: July 14, 2016
Added information on Niagara 4.2 changes, which include the following:
– Incorporated minor changes throughout to support rebranding.
– In the Tag Rules topic, added new information on TagRules in the tagdictionary palette.
• Updated: November 29, 2015
Added information on changes supporting the Tag Dictionary Service functionality for Niagara 4.1. The
following topics have been modified as described.
– Creating a tagged device: edited content in steps 4 and 5. Results info explains that tags in added tag
groups are replaced with an implied relation.
– Editing tags in a template: added note to step 5.
– About the Edit Tags dialog: deleted duplicate content in 2nd paragraph and added note at end that
describes changed handling of tags in tag groups.
– Tag Definitions: added note that about data policy in tag definitions.
– Tag Group Definitions: added content that describes changed handling of tags in tag groups, data
policies, and other instances.
The following topics have been added to this guide:
– Adding a Tag Group to a component
– Adding a tag to an existing Tag Group
– Data Policies
– Tag Group Monitor
• Initial release document: August 31, 2015

Related documents
Following documents provide information related to using tags.
• Hierarchies Guide
• Relations Guide
• Templates Guide

July 14, 2016 5

 Tagging Guide

6 July 14, 2016

Chapter 1 Tagging Overview
Topics covered in this chapter
♦ License requirements
♦ Tagging process

Adding tags to your data model can streamline the process of setting up a system, especially large or “enter-
prise” systems. Instead of manually mapping data into the application point by point, trend by trend, sys-
tems integrators can use tags to facilitate the process. Tag information can also facilitate and improve
search results and hierarchical navigation design.
If you add tags to station objects using standard Tag Dictionaries then other applications can discover sta-
tion content without having to understand the naming convention used by the installer or system integrator.
Typical station tagging might include things such as: networks, devices, points, control blocks, and more.
You can also map all of these example objects to domain-specific semantic entities such as, buildings, sys-
tems, equipment to further indicate how they relate to each other.

Li c ens e req uirem e nts

The t a g s license is required to use the TagDictionaryService and tag dictionaries on a station. The
[Link] attribute limits the number of tag dictionaries available for the system. Any diction-
aries added above the limit for the license will be in fault. When a dictionary is in fault, the tags in that dic-
tionary are not available in the E d i t T a g s dialog. By default, you are limited to the first two tag dictionaries.
However, the [Link] attribute is configurable on the license in the same manner as are device
limits.
For more licensing information, see licensing topics in the Niagara 4 Platform Guide.

T ag gi ng p ro c es s
Before adding tags, make sure that you have a plan and that you have the dictionaries that you need to com-
plete the process.
The basic process for tagging involves the following
1. Identify your purpose. Possible uses could be one or more of the following examples:
• Enterprise structure navigation. In this case you may want to focus on using tags that include
geographical.
• Systems maintenance views. In this case you may need to use tags that include device or equipment
information.
• End user navigation. In this case you may use functionally related tags.
2. Make sure you have the dictionaries you need.
In many cases, the Niagara dictionary may be sufficient. The Niagara Tag Dictionary is in the TagDictio-
naryService folder by default in a new station. You can add the Haystack dictionary from the h a y s t a c k pa-
lette, if needed. You can also create Ad Hoc tags or create your own custom dictionary if you need to.
N O T E : For new stations, it may be true that you need only the Niagara and Haystack Smart Tag Diction-
aries. However, you can reduce or eliminate your tagging efforts by looking for Smart Tag Dictionaries
developed by the Niagara community. These are likely to be the best option for stations created in
NiagaraAX and migrated to Niagara 4.
3. Add tags to your components.

July 14, 2016 7

Chapter 1 Tagging Overview Tagging Guide

You can add tags one at a time or you can use Tag Groups to add multiple tags with each Add action. You
can add tags during or after a discovery process and you can also use the Batch Editor to add tags.

8 July 14, 2016

Chapter 2 Common Tagging Tasks
Topics covered in this chapter
♦ Creating a tagged device
♦ Adding Ad Hoc tags
♦ Removing a tag
♦ Add tags to objects in the Discovered pane
♦ Add tags in the Database pane
♦ Adding a tag group to a component
♦ Adding a tag to an existing tag group
♦ Adding tags using Batch Editor
♦ Editing tags in a template
♦ View Implied Tags using Edit Tags dialog
♦ Viewing implied tags using Spy view
♦ Selecting or Exiting Tag Mode (Manager views)
♦ Exporting and importing tag dictionaries

The following sections include descriptions of some common ways to use tagging.

C reati ng a t agg e d d evi c e

You can add Direct Tags to a device (or other station objects) to provide additional semantic information.
You may add more than one type of tag to a device, in order to support multiple hierarchical navigation
schemes. You can also use Tag Groups to add a predefined collection of tags to the device in a single add
action.
P re re q u i s i t e s :
• One or more installed tag dictionaries. If necessary, add required tag dictionaries to the
TagDictionaryService.
N O T E : If tagging offline, it is possible that no dictionaries are available. In that situation the system
searches for tag dictionaries in alternate locations.
This task describes how to use the E d i t T a g s dialog box to add individual tags or tag groups from an in-
stalled tag dictionary.
Step 1 Right-click on the device that you want to tag and select E d i t T a g s from the popup menu.
Step 2 In the E d i t T a g s dialog box, select a dictionary from the option list in the top left corner
.
T I P : In the Search field, you can use a shortcut to designate the dictionary. Type hs: for Haystack,
n: for Niagara, and similarly for other dictionaries.
The top half of the dialog box shows a list of tags available from the selected dictionary.
Step 3 Use the filter fields as needed to limit the number of tags displayed. For example:

• Type in the S e a r c h field to filter by tag name. Tags are filtered immediately as
you type.

• Select an option from the option list to filter based on validity options (Show
All, Valid Only, or Best Only).
Step 4 Add any number of tags to suit your needs (such as, n:device, hs:geoState, my:bldgRef, etc.) using
either of the following methods:

July 14, 2016 9

Chapter 2 Common Tagging Tasks Tagging Guide

• To add an individual tag from a tag dictionary, select one or more tags in the T a g D i c t i o n a r y
(upper) pane and click A d d T a g to assign the selected tag(s) to the device
• To add a predefined collection of tags from a tag dictionary,in the T a g D i c t i o n a r y (upper) pane
in the dialog, scroll down to T a g G r o u p s and select a tag group, and click A d d T a g to assign
the selected collection of tags at once.
The assigned individual tags and added tag groups are listed on the D i r e c t T a g s tab in the lower
half of the dialog.
Step 5 Edit any tag value fields, as appropriate, and click the S a v e button to save the added tag
assignments.
Starting in Niagara 4.1, when using the E d i t T a g s dialog any added TagGroups display differently
than in the prior release. When adding a TagGroup to any component the added tag group dis-
plays on the D i re c t T a g s tab as an Ord to the TagGroup itself. After saving the added tag assign-
ments, when you reopen the E d i t T a g s dialog you will see the set of individual tags in that
TagGroup display on the I m p l i e d T a g s tab. The reason for this is that the Tag Group Monitor de-
tects the presence of individual tags that are included in a tag dictionary’s TagGroupDefinition and
it replaces those tags with an n:tagGroup relation from the component to the corresponding tag
dictionary's TagGroupInfo tags.
Step 6 O p t i o n a l : For tags that have Ord type values (such as “hs:siteRef”), refer to the following steps as
an example of how to add a link to your tag.
a. Click the option list arrow located to the right of the tag value field.
b. Select the appropriate link type from the options menu.
c. Browse to the desired link and select it.
d. Select the Handle option and click O K .
The device is now tagged.

Adding Ad Hoc tags

You can add Ad Hoc Tags to any station object to provide additional semantic information without using an
installed tag dictionary. Ad Hoc tags are tags that you create directly from the E d i t T a g s dialog box. These
tags are not found in any tag dictionary.
Ad Hoc tags are useful for development or testing purposes, allowing you to test without adding or modify-
ing tag dictionaries and without using the tags that are already in use by active production applications.
However, when applying tags that will be used by applications, best practice is to use tags from standar-
dized tag dictionaries that are applied system-wide.
Step 1 Right-click on the component that you want to tag and select E d i t T a g s from the popup menu.
Step 2 In the E d i t T a g s dialog box, and without making any selections click the A d d T a g button.
The A d d T a g dialog box appears.
Step 3 In the TagId field, enter a new tag name using the following syntax: namespace:tagname.
For example, my:datalogs. For best practices, use a consistent naming convention. Also, it is im-
portant to use a namespace that does not conflict with that of other installed tag dictionaries.
Step 4 In the Type field use the option list to select the tag type from the options available.
N O T E : In your ad hoc tag, do not use a namespace that is identical to an existing tag dictionary.
For example DO NOT use hs:, n:, or other namespace characters that would conflict with existing
tag dictionaries.
For example, for an Ad Hoc tag with the TagId my:datalogs you could select a type called baja:
String to determine that the tag value be a String type of data.
Step 5 Click the O K button to assign the tag to your selected component.

10 July 14, 2016

Tagging Guide Chapter 2 Common Tagging Tasks

The new tag is added and appears in the D i r e c t T a g s table in lower half of the dialog box.
Step 6 Edit any tag value fields (such as String, Ord, etc.), as appropriate, and click the S a v e button to
save the tag assignments.
The component is now tagged.

Removing a tag
You can remove direct tags from individual station objects using the R e m o v e dialog box.
N O T E : This task does not apply to implied tags.
Step 1 Right-click on the object that you want to edit and choose E d i t T a g s from the menu.
Step 2 Click the R e m o v e T a g button from the E d i t T a g s dialog box.
The Remove dialog box displays, showing a list of all the Direct tags that are assigned to the se-
lected component.

Step 3 Select the individual tags that you want to remove or choose Remove All and then click the O K
button.
The selected tags are removed from the table listing under the Direct Tags tab in the lower half of
the dialog.
N O T E : Check that the appropriate tags are now listed in the E d i t T a g s lower pane, under the Di-
rect Tags tab. Your deletions are not complete until you click the S a v e button. Click the C a n c e l
button if you want revoke the delete action.
Step 4 Click the S a v e button to complete the task.
The tag is removed from the selected object.

A dd tag s t o ob j ec ts in th e D i sc o ve red p ane

Tagging is integrated into the S t a t i o n M a n a g e r and P o i n t M a n a g e r views to make it easier to tag editable
stations or points in the D i s c o v e r e d pane, before adding them to the D a t a b a s e pane.
P re re q u i s i t e s : Device or Point Manager view is active with Tag Mode selected. Points or devices are discov-
ered and listed in the D i s c o v e r e d pane.
Tagging during discovery is optional but it is a convenient way to add metadata as you add points or devi-
ces. This task describes how to add tags only, it does not describe all point or device fields that need to be
reviewed or edited during an add process.
Step 1 From the P o i n t o r S t a t i o n M a n a g e r view, in the T a g D i c t i o n a r y pane, select the desired tag
dictionary.
Step 2 Select one or more discovered objects in the D i s c o v e r e d pane.
Step 3 In the T a g D i c t i o n a r y Pane, select one or more tags to add and click the A d d button.

July 14, 2016 11

Chapter 2 Common Tagging Tasks Tagging Guide

Step 4 In the A d d dialog box, check that the appropriate tags are added (table in top pane) and add val-
ues to any tags that have editable fields.
Step 5 Click the O K button and verify that your tags appear with the desired objects in the D a t a b a s e
pane.
Devices or points are added to the station with tags.

Add tags in the Database pane

Tagging is integrated into the S t a t i o n M a n a g e r and P o i n t M a n a g e r views to make it easier to tag editable
stations or points that are in the D a t a b a s e pane.
Prerequis i tes :
• D e v i c e M a n a g e r or P o i n t M a n a g e r view is active with T a g M o d e selected.
• Points or devices are listed in the D a t a b a s e pane.
Tagging objects that are in the Database pane of a manager view is a convenient way to add metadata to
your points or devices. This task only describes how to add tags, it does not describe point or device fields
that may be edited from the manager view.
Step 1 From the P o i n t o r S t a t i o n M a n a g e r view, in the T a g D i c t i o n a r y pane, select the desired tag
dictionary.
Step 2 Select one or more objects in the D a t a b a s e pane.
Step 3 In the T a g D i c t i o n a r y Pane, select one or more tags to add and click the T a g I t button.
Depending on the type of tag you are adding, one of the following happens:
• If one or more tags have a value field, an T a g s E d i t dialog box opens and displays all fields.
• If no tags have value fields, a T a g s A d d e d dialog box displays a confirmation message indicat-
ing how many tags are added.
Step 4 Depending on the type of tags you have added, do one of the following:

12 July 14, 2016

Tagging Guide Chapter 2 Common Tagging Tasks

Option Description
Edit tag values and click OK in the Tags Edit dia-
log box.

If this dialog box displays, then you have tag values

to edit. Edit the value fields and click O K .
Click OK in the Tags Added dialog box.

If this dialog box displays, no tag values are avail-

able. Click theOOK button.

A d d i n g a t a g g ro u p t o a c o m p o n e n t
Adding a Tag Group lets you add a predefined collection of tags to a component in a single action. Typically
tags are in a tag group because it is common for each of the tags to be assigned to the same component.
The D e v i c e M a n a g e r and P o i n t M a n a g e r views of a driver, and the E d i t T a g s dialog are the primary meth-
ods for adding a tag group to a component. This procedure describes how to use the E d i t T a g s dialog to
add a tag group.
P re re q u i s i t e s :
• One or more installed tag dictionaries. If necessary, add required tag dictionaries to the
TagDictionaryService.
N O T E : If tagging offline, it is possible that no dictionaries are available. In that situation the system
searches for tag dictionaries in alternate locations.
Step 1 Right-click on the component that you want to tag and select E d i t T a g s from the popup menu.
Step 2 In the E d i t T a g s dialog box, select a dictionary from the option list in the top left corner
.
The top half of the dialog box shows a list of individual tags available from the selected dictionary.
Step 3 Scroll down to see the list tag groups in the dictionary.
T I P : Use the Search and the Filter fields as needed to limit the number of tags displayed.
Step 4 Select the desired tag group and click A d d T a g to assign the selected collection of tags.
The assigned tag group displays as an Ord on the D i re c t T a g s tab (lower half).
Step 5 Click the S a v e button to save the added tag assignments.

July 14, 2016 13

Chapter 2 Common Tagging Tasks Tagging Guide

N O T E : Starting in Niagara 4.1, when using the E d i t T a g s dialog any added TagGroups display dif-
ferently than in the prior release. When adding a TagGroup to any component the added tag group
displays on the D i r e c t T a g s tab as an Ord to the TagGroup itself. After saving the added tag as-
signments, when you reopen the E d i t T a g s dialog you will see the set of individual tags in that
TagGroup display on the I m p l i e d T a g s tab. The reason for this is that the Tag Group Monitor de-
tects the presence of individual tags that are included in a tag dictionary’s TagGroupDefinition and
it replaces those tags with an n:tagGroup relation from the component to the corresponding tag
dictionary's TagGroupInfo tags.
Once you save the added tag assignments, the set of tags in the tag group are implied tags on the
component.

Ad d ing a t ag t o an exi st in g tag gro up

Starting in Niagara 4.1, you can add a tag from a different tag dictionary to an existing tag group. Optionally,
you can add a tag from thetagdictionary palette. Shown in the following image, the hs:hvac tag (cop-
ied from the Haystack tagdictionary) is added to MyTagGroup in the Building tagdictionary.

Prerequis i tes :
• At least two tag dictionaries installed, one of which contains a TagGroup
Step 1 In the Nav tree, expand the tag dictionary to the TagGroup that you wish to edit.
Step 2 Expand the second tag dictionary to select a Marker tag to you wish to add to the TagGroup in the
first tag dictionary.
Step 3 Drag (or right-click and Copy) the selected tag, and drop it (or right-click and Paste it) on the Tag-
List folder of the Tag Group Definition that you are editing.
N O T E : An alternative is to add a Marker tag from the tagdictionary palette.
Step 4 In the N a m e dialog, enter the tag's desired name as a fully qualified tag name including the name-
space with the colon separator. For example: hs:hvac.
N O T E : There is no verification that the tag name entered is actually defined in a tag dictionary. If it
is not defined in a tag dictionary, the added tag is an "ad hoc" tag. While you can certainly use ad
hoc tags, the recommended tagging best practice is to use tags that are contained in a standar-
dized tag dictionary that is applied system-wide.
Changes to the tag group are saved automatically.
This namespace overrides the application of the parent dictionary's defined namespace. The added tag au-
tomatically becomes an n:tagGroup relation (an implied tag) from the component to the corresponding
tagdictionary's TagGroupInfo.

14 July 14, 2016

Tagging Guide Chapter 2 Common Tagging Tasks

Adding tags using Batch Editor

You can add Direct Tags to large numbers of objects using the Program Service, B a t c h E d i t o r view. Use the
B a t c h E d i t o r to locate objects that need tagging and use the A d d T a g s button in the B a t c h E d i t o r view to
add tags.
P re re q u i s i t e s :
• One or more installed tag dictionaries. If necessary, add required tag dictionaries to the
TagDictionaryService.
N O T E : If tagging offline, it is possible that no dictionaries are available. In that situation the system
searches for tag dictionaries in alternate locations.
This task describes how to use the E d i t T a g s dialog box to add individual tags or tag groups from a diction-
ary that is installed in the station Services folder.
N O T E : If you are using tags to support multiple hierarchical navigation schemes, you may add more than
one type of tag to a component. You can use Tag Groups for adding multiple tags in a single add action.
Step 1 In the Station Nav tree, expand the S t a t i o n → C o n f i g → S e r v i c e s nodes and double click on the Pro-
gram Services node.
Step 2 In the B a t c h E d i t o r view, click the F i n d O b j e c t s button and use the B q l Q u e r y B u i l d e r to pro-
duce a list of objects that you want to tag.
For example, under the Config node you can search for all Component types that have AHU in their
name (using parameters similar to the example in the image below).

The search should produce a list of matching components similar to the example in the following
image.

Step 3 Select and remove the unwanted components in the table and then click the A d d T a g button.

July 14, 2016 15

Chapter 2 Common Tagging Tasks Tagging Guide

Step 4 Select one or more tags from the T a g D i c t i o n a r y (top) pane (or you may choose to use the A d d
T a g button from this dialog box to apply custom tags) and then click the A d d T a g button to assign
the selected tags to all components.
N O T E : Select a Tag Group, if appropriate, to add several tags at once.
The selected tags are added and appear in the D i r e c t T a g s table in lower half of the dialog box. Fi-
nally, the B a t c h E d i t o r R e s u l t s dialog opens with all tag actions listed.

The components are tagged.

Editing tags in a template

You can edit an existing template to add additional direct tags to the objects in it, or to remove or modify
the existing tags. These changes are made on the template C o n f i g u r a t i o n tab
Prerequis i tes :
• An existing template
• One or more installed tag dictionaries
This task describes using the T e m p l a t e sidebar to access an existing template and invoke the E d i t T a g s dia-
log from the template C o n f i g u r a t i o n tab.
Step 1 To locate a template, open the T e m p l a t e side bar by clicking W i n d o w → S i d e B a r s → T e m p l a t e

Step 2 In the T e m p l a t e side bar, click the pull down menu and select either: t e m p l a t e s folder or m o d u l e s
folder.
N O T E : To see templates stored in a template module, select the m o d u l e s folder and expand the
desired module.
Step 3 Double-click on the desired template.
The T e m p l a t e view appears displaying the template configuration tabs with the T e m p l a t e I n f o
tab selected.
N O T E : A template stored in a module cannot be edited. When you open it, you will see “Read-
Only” in the top left corner of the T e m p l a t e view. In order to make changes you must first click
S a v e A s and save it as a new template in the t e m p l a t e s folder.
Step 4 Click the C o n f i g u r a t i o n tab in the T e m p l a t e view, right-click the object you want to change in the
left pane, and select E d i t T a g s .
The E d i t T a g s dialog displays.

16 July 14, 2016

Tagging Guide Chapter 2 Common Tagging Tasks

Step 5 Proceed to add tags, remove tags, or modify values of existing tags and click S a v e to close the E d -
i t T a g s dialog.
N O T E : Starting in 4.1, when using the E d i t T a g s dialog within the T e m p l a t e E d i t o r view,
TagGroup tags are assigned to a component as individual direct tags in the template. Upon tem-
plate deployment, the Tag Group Monitor in the Tag Dictionary Service is notified and the individu-
al tags (of the tag group) are removed from the component and replaced with an n:tagGroup
relation. The relation, of course, implies the same set of tags.
Step 6 When finished, click S a v e to save your changes to the template.
• Or, click S a v e A s to create a new variation of the template with a different filename (leaving the
original template unchanged).
N O T E : For more details on using the Template view Configuration tab, refer to the Template Guide sections
“Creating a template” and “Template reference”.

Vie w I m p l ied Tag s u si ng E d it T ag s d ial o g

Viewing Implied tags can be useful when designing a custom tag dictionary, to confirm that certain objects
are getting the desired tags, or when designing a NEQL query for a hierarchy definition or search. Implied
Tags do not appear in an object Property Sheet or other typical views. One way that to view these tags is on
the Implied Tags tab in the E d i t D i a l o g box.
P re re q u i s i t e s :
• One or more installed tag dictionaries. If necessary, add required tag dictionaries to the
TagDictionaryService.
N O T E : If tagging offline, it is possible that no dictionaries are available. In that situation the system
searches for tag dictionaries in alternate locations.
Implied tags are automatically assigned to objects by S m a r t T a g R u l e s in the installed Tag Dictionaries.
Step 1 Right-click the object whose tags you want to examine and choose E d i t T a g s from the popup
menu.
Step 2 Select the I m p l i e d T a g s tab in the lower pane of the dialog to view the I m p l i e d T a g s .
For example, in the following image, you can see five tags that are implied based on the dictionary
rules for a Component object:

The first four tags are implied from Niagara Tag Dictionary rules:
• n:name
• n:displayName
• n:type
• n:ordInSession

July 14, 2016 17

Chapter 2 Common Tagging Tasks Tagging Guide

The final tag is implied based on Haystack tag dictionary rules:

• hs:id

Vi e w i n g i m p l i e d t a g s u s i n g S p y v i e w
Implied tags and implied relations are automatically assigned to objects by rules in the installed Smart Tag
Dictionaries. The implied tags and implied relations do not appear in the Property Sheet view or other more
commonly used views. Spy View shows all of the direct and implied tags and relations on an object as well as
other detailed data. Although intended to be used for diagnostic purposes, you can use Spy View to identify
implied tags and/or relations already assigned to a component. This can be useful when developing hierar-
chies. Once identified, you can then create queries for those tags/relations in your hierarchy definition.
Prerequis i tes :
• Connection to your station
• One or more installed tag dictionaries. If necessary, add required tag dictionaries to the
TagDictionaryService.
N O T E : If tagging offline, it is possible that no dictionaries are available. In that situation the system
searches for tag dictionaries in alternate locations.
This procedure describes the how to open the Spy View on a station component to see its implied tags:
N O T E : Invoking the E d i t T a g s dialog is another method for viewing the direct and implied tags assigned to
a component.
Step 1 In the Workbench Nav tree, right-click on the component of interest and click V i e w s → S p y R e m o t e
from the popup menu.
Spy information displays in the We b B ro w s e r V i e w.
Step 2 Scroll down the until you see the T a g s I m p l i e d heading.
The implied tags assigned to the selected component are listed. Scroll up or down to view all of
the tags and relations assigned to the component.
The Spy view pictured here lists the different types of tags and relations assigned to the AHU_2 component.

18 July 14, 2016

Tagging Guide Chapter 2 Common Tagging Tasks

Selecting or Exiting Tag Mode (Manager views)

Station Manager and Point Manager views have a T a g M o d e available for adding tags to devices or points
as they are added.
P re re q u i s i t e s :
• T a g M o d e is only available in the S t a t i o n M a n a g e r or P o i n t M a n a g e r views.
Tagging is integrated into the driver manager views to help you add tags when devices or points are discov-
ered and added. You can select and exit T a g M o d e using either the M a n a g e r menu or the T a g icon in
the T o o l b a r.
Step 1 While in the Station Manager or Point Manager view, click M a n a g e r → T a g M o d e from the Work-
bench main menu to select or exit Tag Mode.
When selected, Tag Mode appears as a single pane across the top or as a second pane in the upper pane de-
pending on whether or not you also have Learn Mode selected. The following image shows Tag Mode and
Learn Mode selected simultaneously.

July 14, 2016 19

Chapter 2 Common Tagging Tasks Tagging Guide

Exporting and importing tag dictionaries

The T a g D i c t i o n a r y M a n a g e r view provides a method to import and export tag dictionaries (or smart tag
dictionaries) in a standard CSV file format, compatible with Excel (or other CSV-compatible spreadsheet soft-
ware). This facilitates creating custom tag dictionaries which you then import to your station. Working in the
exported CSV file, you can easily edit the correctly structured tag dictionary, populating it with your custom
tag definitions, tag rules, etc. When finished, simply save the revised CSV file and import it using the T a g
D i c t i o n a r y M a n a g e r view.
It may suit your purposes to create a custom tag dictionary (or dictionaries) for a specific customer, for an
OEM, or for a specific application. You may use a custom tag dictionary as you would other tag dictionaries,
to apply tags to objects, create hierarchy definitions, as well as search the station for tagged objects.
N O T E : By default, the license for the Tag Dictionary Service limits the number of tag dictionaries available
for the system to the first two. Any dictionaries added above the limit for the license will be in fault and unus-
able. However, the [Link] attribute on the license is configurable in the same manner as are
device limits.

Creati ng and exp orti ng a new tag d ic tio nary

Create a new custom tag dictionary and export it to CSV file format. Using this method of creating a new
tag dictionary results in a correctly structured, “empty” tag dictionary, which you can then export for
editing.
Prerequis i tes :
• tag license
• TagDictionaryService installed
• Open station connection (online or offline)
Step 1 In the Nav tree, double-click the TagDictionaryService to open the T a g D i c t i o n a r y M a n a g e r view
(or use the right-click menu to open this view).
Step 2 Click N e w and in the N e w dialog, select one of the following options and click O K .
• Tag Dictionary (“simple” tag dictionary with no implied tags)
• Smart Tag Dictionary (supports implied tags)
Step 3 In the 2nd N e w dialog, in the Name field enter the dictionary name and click O K .
Your new custom tag dictionary is listed in the database table in the and also is visible under the
TagDictionaryService node in the Nav tree.

20 July 14, 2016

Tagging Guide Chapter 2 Common Tagging Tasks

Step 4 In the T a g D i c t i o n a r y M a n a g e r view, select your new custom tag dictionary and click E x p o r t .
Step 5 In the F i l e C h o o s e r dialog, select a location to save the file, enter the desired file name (as shown),
and click S a v e .

The exported structured tag dictionary is “empty” at this point, you can edit the file, as well as use it as a
template which you use to develop additional tag dictionaries.
N O T E : You can also export the Niagara or Haystack dictionaries to use as examples.

Editing a tag dictionary exported to CSV

You can open an exported tag dictionary (CSV format) in Microsoft Excel or other CSV-compatible spread-
sheet software, or even a text editor. The file is structured correctly, ready for you to enter a namespace and
add tag definitions and other types of definitions, as needed.
P re re q u i s i t e s :
• Tag dictionary exported to CSV format
• CSV-compatibile spreadsheet software
Step 1 Open the exported CSV file (which should resemble the one shown here).

July 14, 2016 21

Chapter 2 Common Tagging Tasks Tagging Guide

Step 2 In cell B 1 , enter a Namespace for this tag dictionary (typically only a few characters, for example:
MyTags).
N O T E : Avoid using a namespace that conflicts with that of other installed tag dictionaries, such as
“n” (NiagaraTagDictionary) or “hs” (HaystackTagDictionary).
Step 3 Starting under the Tag Definition section, in R o w 1 8 , enter the first of your tagDefinition en-
tries (one per row), be sure to note the following information:

Row Description
Row 4 Tag Definition section: define the tags for your dictionary in this area.
# Rows that begin with # are comment lines which show examples or explanatory comments
which may be helpful to retain in the file.

22 July 14, 2016

Tagging Guide Chapter 2 Common Tagging Tasks

Row Description
Row 5
Row 5 is an example of the pattern to use to define a tagDefinition entry. Yo u m u s t d e -
fine tag name and tag type.
Row 6–17
Row 6–17 show valid tag types that can be used.
Validation Rules columns: Validation rules are optional. These columns are used to define
NEQL query predicates that will be used to suggest where the tag can be applied. For a
particular tag definition entry, if more than one of these columns have values they will be
wrapped in a tagdictionary:And function.
• hasTag: this tag may be applied if the target component also matches this NEQL tag
query.
• hasAncestor: This tag may be applied if the target component has an ancestor that
matches this neql tag query.
• isType: This tag may be applied to the target component is one of these types. Value
must be entered in the "module:ClassName" form.
If more that one type is entered separated by a space, It will be treated as an "or"
function. Example: driver:Device driver:PointFolder: The tag is valid on a BDevice or
a BPointFolder.
• hasRelation: This tag may be applied if the target component has has this relation and
has the tags that are listed in the hasRelationFilter (3.c.v) column.
hasRelationFilter: This is a tag filter used with hasRelation ([Link]) validation check.
Units: Units are optional. This can be used to define a measurement unit to be used for a
tag that has a value. The value entered is used to as the unitName argument in the BUnit.
getUnit(String unitName). Example: "square foot" for a tag whose value is an area

Step 4 Under the TagGroupDefinitions section (optional), add a row for each TagGroup, defining a Group-
Name that will be used to represent this collection of tags.
a. Add one or more tag rows under the TagGroup one row for each tag in the group.
N O T E : Tags included in a TagGroup must also be defined in the TagDefinitions section.
Step 5 Under the RelationDefinitions section (optional), add a row for each relation defining a Relation-
Name and enter Relation in the Type column.
Step 6 Under the RuleDefinitions section (SmartTagDictionaries only) define the rules for implied tags and
relations.
a. Add a row for each TagRule, entering a RuleName and one or more validation rule column val-
ues. See information on Validation Rules listed under Step 3.
b. Under the tag rule row, add a row for each implied tag for this rule entering a name, type and a
smart type. The smart type should be in the module:class format.
c. If there are any implied tag groups for this rule add a row for each with the GroupName entered
in the groupName column.
d. If there are any implied relations for this tag rule, add a row for each with the RelationName in
the name column and enter Relation in the type column.
Your edited tag dictionary is complete and ready to import. An example of an edited tag dictionary in CSV
file format, shown here.

July 14, 2016 23

Chapter 2 Common Tagging Tasks Tagging Guide

Namespace = my

Tag Definitions — notice tagDefinitions, area and temp are configured with Validity Rules

Tag Group Definitions — notice oaTemp tagGroup is configured with a Validity Rule and the group
contains three tagDefinitions. (outside, air, and temp).

Relation Definitions — defines one Relation, buildingRef

Importing a tag dictionary in CSV format

Prerequis i tes :
• Tag dictionary in CSV format in your Workbench user home
Step 1 Open the T a g D i c t i o n a r y M a n a g e r view of the TagDictionaryService.
Step 2 Select the tag dictionary to update and click I m p o r t .

Step 3 In the C o n f i r m dialog (alerting you that the Import action will overwrite the selected tag diction-
ary) click Ye s to continue.

24 July 14, 2016

Tagging Guide Chapter 2 Common Tagging Tasks

Step 4 In the F i l e C h o o s e r dialog, locate and select the CSV file to import, and click O p e n .

NOTE:
By default, the function prompts for a CSV file. This behavior can be modified programmatically.
Step 5 Click O K in the R e s u l t s dialog (notifying you that the CSV file imported successfully), as shown.

N O T E : In the event that an error is detected in the CSV file, an E r r o r dialog displays indicating the
error and its location by row or line number.
Step 6 In the Nav tree, expand the TagDictionaryService node and double-click (or right-click) on the im-
ported/updated tag dictionary to open a P ro p e r t y S h e e t view. Then review its properties and veri-
fy your changes.

July 14, 2016 25

Chapter 2 Common Tagging Tasks Tagging Guide

26 July 14, 2016

Chapter 3 Tag g ing ref erenc e
Topics covered in this chapter
♦ About tags
♦ Online tagging vs. offline tagging
♦ About the Edit Tags dialog
♦ Components in the tagdictionary module
♦ Plugins in the tagdictionary module

Tagging is a form of semantic modeling that assigns information (one or more tags) to objects. The tag infor-
mation can help integrators and users significantly when searching for objects, designing system structures
or navigating hierarchies.
Tagging can identify a device and indicate where it is physically located. By identifying and locating devices,
tags provide a context for the device that can be used in many different ways. When you use tags, you can
reduce or eliminate the requirement to manually map objects directly to a desired application.

About tags
Tags assign additional information to objects in order to make the objects more accessible and flexible for
search and system design. Tags also facilitate the design and use of hierarchical organization in a station user
interface, whether you are working with an Enterprise Supervisor station or a single controller station.
N O T E : The tags available for use are defined in the tag dictionaries installed on your station.

Ta g st r u ct ure
A tag contains different parts that, together, make the tag useful as additional information on objects in a
station. The following diagram shows the four basic parts of a tag.

F ig ure 1 Parts of a Tag

The following table provides definitions of the different parts of a tag:

Item Tag Element Description

1 Tag Id The Tag Id is comprised of a dictionary and name, generally displayed
as two pieces of text separated by a colon (:), as shown in the following
example: dictionaryNamespace:name.

2 Tag Dictionary The dictionary string is used to link or assign a tag to a particular
"namespace" (tag dictionary). This is typically a very short string of only
a few characters.
N O T E : If the dictionary is not defined (empty string), the Id is displayed
with just the name.

July 14, 2016 27

Chapter 3 Tagging reference Tagging Guide

Item Tag Element Description

3 Tag Name The name string provides the semantic information and is often paired
with the Tag Value.
4 Tag Value A string value assigned to the tag for more information, for example:
building name, device name, location, or other.

Ty p e s o f t a g s
The following table describes types of tags that may be used on the system:

Tag type Description

D i re c t t a g s Direct tags are tags that you add intentionally to a component using an in-
stalled tag dictionary or an Ad Hoc tag. In its simplest form, a Tag on a compo-
nent is a component “property”, with a non-component value and a metaData
flag set. The property name is a string form of the Tag Id. In the E d i t T a g s dia-
log box, Direct Tags are listed under the Direct Tags tab.
Implied tags Implied tags are tags that are not directly stored in the component, but are
"implied" by tag rules that are defined in installed Smart Tag Dictionaries.
These tags are typically the remapping of existing component properties to
the semantic naming convention defined in a Tag Dictionary. In the E d i t T a g s
dialog box. Implied Tags are listed under the I m p l i e d T a g s tab.

Ad Hoc tags An Ad Hoc tag, also a direct tag, is one that you create in the A d d T a g dialog
box just before adding it to a component. Ad Hoc tags are not included in any
Tag Dictionary.

Onli ne tag g i ng v s. offl in e t ag g ing

There are three separate scenarios in which you apply tags:
• O n l i n e t a g g i n g — where the installed tag dictionaries in T a g D i c t i o n a r y S e r v i c e take effect.
• O f f l i n e t a g g i n g i n a s t a t i o n w i t h t a g d i c t i o n a r i e s — where the installed tag dictionaries in the T a g D i c -
t i o n a r y S e r v i c e take effect. You will also see implied tags in the E d i t dialog.
• O f f l i n e t a g g i n g i n a s t a t i o n w h e n n o d i c t i o n a r i e s a r e f o u n d — in this case the system searches for tag
dictionaries in the following locations:
– all palettes of installed tag dictionary modules
– in the user-home/tagDictionary folder (where custom tag dictionaries are stored)
– and also searches for Implied tags

About the Edit Tags dialog

The E d i t T a g s dialog (as well as the station and point manager views) are the primary methods for adding a
Tag or a Tag Group to a component. The dialog lets you add individual tags or tag groups to the object, as
well as remove them from the object. The lower half of the dialog provides tabs to view the Direct and Im-
plied tags assigned to the object.
Invoke the E d i t T a g s dialog by right-clicking an object and selecting E d i t T a g s .

28 July 14, 2016

Tagging Guide Chapter 3 Tagging reference

F ig ure 2 Edit Tags dialog

In the E d i t T a g s dialog box, select a dictionary from the option list in the top left corner .
T I P : You can use this shortcut to select a dictionary. In the S e a r c h field type hs: for Haystack, n: for Niag-
ara, or enter the namespace for another dictionary.
The top half of the dialog box shows a list of tags available from the selected dictionary. Once a tag is as-
signed to the active object, the tag icon appears dimmed.
To facilitate making selections, the dialog includes filters which help by narrowing the list of tags from which
you can choose. This is most useful when selecting from a dictionary containing a huge number of tags, such
as the Haystack Tag Dictionary.

Type in the S e a rc h field to filter by tag name. Tags are filtered immediately as you type.
• If the list has only a single item, then it is selected by default.
• If a tag name is a subset of another tag, adding a space selects the shorter tag by name.
For example, if you have both “chiller” and “chillerPlant” tags, typing "chiller" shows both tags. Adding
a space after “chiller” filters out “chillerPlant” and shows the “chiller” tag only.
• Entering a colon ":" filters for the tag dictionary that has the prefixed namespace.
For example, if you enter "hs:temp" you select the “hs” (Haystack) dictionary and the "temp" tag.

You can also select an option from the option list to filter based on validity options.
• Show All: no filtering applied when this option is selected.
• Valid Only: shows just the tags that are valid based on rules defined in the tag dictionary.
• Best Only: filters tags in appropriate manager views based on the identity of the component; for exam-
ple, whether it is a point or device.
Methods for adding tags include the following:
• Add an individual tag from a dictionary
• Add a Tag Group (predefined collection of tags) from a dictionary
• Add a unique Ad Hoc tag which you create
After clicking A d d T a g s , the selected tags are added and appear in the D i re c t T a g s table in lower half of
the dialog box.
After editing any tag value fields as needed, click the S a v e button to save the tag assignments.

July 14, 2016 29

Chapter 3 Tagging reference Tagging Guide

For tags that have Ord type values (such as “hs:siteRef”), refer to the following image and steps as an exam-
ple of how to add a link to your tag.

1. Click the option list arrow located to the right of the tag value field.
2. Select the appropriate link type from the options menu.
3. Browse to the desired link and select it.
4. Select the Handle option.
5. Click the O K button.
N O T E : Starting in Niagara 4.1, when using the E d i t T a g s dialog any added TagGroups display differently
than in the prior release. When adding a TagGroup to any component the added tag group displays on the
D i re c t T a g s tab as an Ord to the TagGroup itself. After saving the added tag assignments, when you reopen
the E d i t T a g s dialog you will see the set of individual tags in that TagGroup display on the I m p l i e d T a g s
tab. The reason for this is that the Tag Group Monitor detects the presence of individual tags that are in-
cluded in a tag dictionary’s TagGroupDefinition and it replaces those tags with an n:tagGroup relation from
the component to the corresponding tag dictionary's TagGroupInfo tags.

Components in the tagdictionary module

“Component” includes services, folders and other model building blocks associated with a module. They
may be dragged and dropped onto a Property or Wire sheet from a palette.
Components, shown here, in the tagdictionary palette are described in the following sections.

Fi gu re 3 The tagdictionary palette

30 July 14, 2016

Tagging Guide Chapter 3 Tagging reference

About the Tag dictionary Service

The Tag Dictionary Service, located in a station’s Services directory, is the container for all tag dictionaries in-
stalled in the station.

Tag Dictionary Service

The T a g D i c t i o n a r y M a n a g e r is the main view for the Tag Dictionary Service. The service has a property for
defining a default namespace so that queries that do not specify a namespace are resolved on this default
namespace. For example, if you execute a NEQL query for "point" (instead of "n:point"), and the default
namespace ID is set to "n", your query returns all objects tagged with "n:point".
Note the following information about the Tag Dictionary Service:
• The t a g s license is required in order to use the TagDictionaryService and tag dictionaries on a station.
• A station can support only one tag dictionary service.
• Neither the tag dictionary service nor any tag dictionaries are strictly required for tagging or for perform-
ing NEQL queries. However, without tags or tag dictionaries, a station is not be able to take advantage
of most of the functions available from tagging objects. Tags and tag dictionaries are fairly lightweight
and therefore are included by default in all stations created by the new station wizard.
• Installed tag dictionaries belong under the T a g D i c t i o n a r y S e r v i c e . They are not legal anywhere else in
the station.

F ig ure 4 TagDictionaryService is located in the Services directory

Property Values Description

Enabled [general] true or false Activates and deactivates use of the function.
Status text Read-only field. Indicates the condition of the component at
[component] last polling.
• {ok} indicates that the component is polling successfully.
• {down} indicates that polling is unsuccessful, perhaps be-
cause of an incorrect property.
• {disabled} indicates that the Enable property is set to
false.
• fault indicates another problem.

Fault Cause text Read-only field. Indicates why the network, component, or ex-
tension is in fault.
Default Name- Text string This TagDictionaryService property provides a field that is
space Id used to indicate a default tag namespace (tag dictionary) that
is used if there is not a namespace provided as part of a query.
For example, if the default namespace is set to “hs”, then a
search query that includes only “ahu” would return all objects
that are tagged with “hs:ahu”.

July 14, 2016 31

Chapter 3 Tagging reference Tagging Guide

Fi gu re 5 Default Namespace Id property in TagDictionaryService property sheet view

Tag Grou p Mon itor

Starting in Niagara 4.1, the TagDictionaryService has a frozen TagGroupMonitor slot named Moni-
tor. The primary responsibility of this component is to monitor the addition or removal of component tags
and the maintenance of n:tagGroup relations.

Conver ti ng ex is ti ng ta gs t o T agGroup Rel at ions

On station startup, the Tag Group Monitor in Tag Dictionary Service scans the station components looking
for a complete set of tags from each defined TagGroup in the TagDictionaryService. If a complete set is de-
tected, the Monitor replaces the set of tags on the component with an n:tagGroup relation from the com-
ponent to the TagGroupDefinition. This set of tags then becomes implied tags on the component.
Using the Edit Tag dialog within the Template Editor
When using the E d i t T a g s dialog within the T e m p l a t e E d i t o r view, TagGroup tags are assigned to a compo-
nent as individual direct tags in the template. Upon template deployment, the Tag Group Monitor in the Tag
Dictionary Service is notified and the individual tags (of the tag group) are removed from the component
and replaced with an n:tagGroup relation. The relation, of course, implies the same set of tags.

32 July 14, 2016

Tagging Guide Chapter 3 Tagging reference

Prope rt i es

Name Value Description

Status text Read-only field. Indicates the condition of the component at
[component] last polling.
• {ok} indicates that the component is licensed and polling
successfully.
• {down} indicates that polling is unsuccessful, perhaps be-
cause of an incorrect property.
• {disabled} indicates that the Enable property is set to
false.
• {fault} indicates another problem.

Enabled [general] true or false Activates and deactivates use of the function.
Frequency +00000h 00m 00s Specifies how frequently the monitor will do a complete scan
of the station looking for applied tag group tags.

Execute Count 0000s Seconds until next scan.

Down
Execute Status idle
Last Scan Time Date and time stamp

Scan Count Number of scans.

Avg Execute Time 0000ms The average time in milliseconds that it has taken to execute
the scan.
Last Execute Time 0000ms The time in milliseconds of the last scan execute.
Tag Group Count 90 The total number of tag groups found in the installed tag
dictionaries.
Entity Count 5706 Total number of entities (components) included in the scan.
N O T E : The services folder is not included in the scan.
Tag Group Rela- 1202 Total number of n:tagGroup relations found.
tion Count
Data Policy Count 3 Total number of data policies found in the installed tag
dictionaries.

Tag Dictionary
The tagdictionary module provides two tag dictionary components, TagDictionary and SmartTagDiction-
ary, which you can use to create custom tag dictionaries. These components are available in the tagdic-
tionary palette.
N O T E : The t a g s license is required in order to use the TagDictionaryService and tag dictionaries on a
station.

About tag dictionaries

A Tag Dictionary is the container for a collection of tag definitions, tag group definitions, and relation defini-
tions. The tags in a tag dictionary may be associated with devices, components, and points. Typically, these
associations are established when the device is discovered, registered, and fully subscribed but tags can be
added to an object at any time. Tags also provide a vocabulary for searching.

July 14, 2016 33

Chapter 3 Tagging reference Tagging Guide

The T a g D i c t i o n a r y M a n a g e r view of the Tag Dictionary Service displays the dictionaries installed on the
station. You can create and add custom tag dictionaries to the station’s Tag Dictionary Service via this view
or by dragging from the tagdictionary palette. For example, you may create one or more custom diction-
aries for a specific customer, for an OEM, or for a specific application.

Ty p e s o f t a g d i c t i o n a r i e s
Characteristics of the two types of tag dictionaries are:
• Simple tag dictionary
The TagDictionary component, can be dragged to the Tag Dictionary Service to create a new simple
tag dictionary. It contains a collection of tag definitions and may also contain relation definitions, as well
as tag group definitions. A simple tag dictionary does not apply implied tags or implied relations.
• Smart tag dictionary
The SmartTagDictionary component, also can be dragged to the Tag Dictionary Service to create a
new smart tag dictionary. In addition to tag definitions, tag group definitions, and relation definitions
present in a simple tag dictionary, a smart tag dictionary contains a list of Tag Rules which determine the
implied tags and implied relations for each and every object, applying the tags and relations to objects
automatically. Technically, these smart tags (the Implied Tags and Implied Relations) are never added to
the station, and the station size is not increased as a consequence.
One example of a smart tag dictionary is the Niagara tag dictionary, whose namespace is the n character
followed by a colon (:). It is included by default in all stations created using the N e w S t a t i o n W i z a rd .
Another example is the Haystack tag dictionary, indicated by hs followed by a colon. This dictionary is
available from the haystack palette which is included in the Niagara installation. The Haystack diction-
ary is a result of the work of the Open Source Initiative (OSI) hosted on the website [Link]
[Link].

Tag dictionary composition

A tag dictionary is composed of the following:
• A unique namespace, normally 1- or 2-characters, for example ”n” for Niagara, “hs” for Haystack
• Tag Definitions (contains individual Tag components added to the dictionary). This is the collection of
standardized tags with an [Link], that has semantic meaning for the given domain or namespace. The
dictionary also defines tag default values and any validation rules for applying tags.
• TagGroup Definitions (optional - contains individual TagGroups components added to the dictionary).
This is a collection of standardized groupings of tags (tag groups) that have semantic meaning for the giv-
en domain or namespace. The dictionary also defines any validation rules for applying these tag groups.
• Relation Definitions (optional - contains individual Relation components added to the dictionary). This is a
collection of standardized Relation Id's with semantic meaning for the given domain or namespace.
• TagRules (optional - contains individual smart tag definitions and conditions)

34 July 14, 2016

Tagging Guide Chapter 3 Tagging reference

Ta gDi ct i on ar y prope r t ie s

Type Value Description

Status text Read-only field. Indicates the condition of the component at
[component] last polling.
• {ok} indicates that the component is polling successfully.
• {down} indicates that polling is unsuccessful, perhaps be-
cause of an incorrect property.
• {disabled} indicates that the Enable property is set to
false.
• fault indicates another problem.

Fault Cause text Read-only field. Indicates why the network, component, or ex-
tension is in fault.
Namespace text string Descriptive text that reflects the name of the tag dictionary.
This is typically a very short string of only a few characters. For
example, “n” for NiagaraTagDictionary, “hs” for
HaystackTagDictionary.
Enabled [general] true or false Activates and deactivates use of the function.
Frozen true or false
Tag Definitions Tag Info List Container for a collection of standardized tags that have se-
mantic meaning for that namespace (tag dictionary). Each tag
in this TagInfoList can be used to add metadata to compo-
nents, providing additional semantic information. Tags may
contain a Validity slot with conditions such as, Always, IsType,
etc.
Tag Group Tag Group Info List Container for a collection of TagGroups for a tag dictionary. A
Definitions tag group provides a structure that lets you add multiple tags
to a component, with a single action. Typically tags are in a
group because it is common for each of the tags to be as-
signed to a single component.

Relation RelationsInfoList Container folder that contains a collection of standardized Re-

Definitions lation Id's with semantic meaning for that namespace.

validTagRules Tag Rule List

validTagGrou- Tag Rule List
pRules

Tag Definitions
The Tag Definitions folder in a TagDictionary property sheet contains the collection of standardized tags
that have semantic meaning for that namespace (tag dictionary). Each tag in this TagInfoList can be used to
add specific metadata to objects in a station, assigning additional semantic information which provides a ba-
sis for searching. Tags may contain a Validity slot with conditions such as, Always, IsType, etc.
The following implementations of Simple Tag Info are available in the Tags folder of the tagdictionary
palettė. When creating a custom tag dictionary, drag and drop tags from the palette to the Tag Definitions
folder in the tag dictionary’s property sheet to create the tag definitions for that dictionary.
Tag components available in the palette are described below.

July 14, 2016 35

Chapter 3 Tagging reference Tagging Guide

Tag Type Value Description

Marker Marker (default) Tag name only. The Marker tag does not require a value. The
fact that a component has the tag applied is sufficient to con-
vey semantic information (the tag name, i.e. “device” or
“input”).

String String value Tag name and string value

Integer 0 (default) Tag name and numeric value
Long 0 (default) Tag name and numeric value
Float 0.00 (default) Tag name and numeric value
Double 0.00 (default) Tag name and numeric value
Ord null (default) Tag name and Ord value

N O T E : Starting in Niagara 4.1, tag dictionaries support adding a single DataPolicy to a TagInfo or a Tag-
GroupInfo component. Also, the TagInfo and TagGroupInfo components have an A d d D a t a P o l i c y action.
For details, see “Data Policies”.

Tag Grou p De fin iti ons

Although not required, a tag dictionary may contain tag groups. The Tag Group Definitions folder in a Tag-
Dictionary property sheet contains the collection of TagGroups for that dictionary. A tag group provides a
structure that lets you add multiple tags to a component, with a single action. Typically tags are in a group
because it is common for each of the tags to be assigned to a single component.
For example, in the Haystack Tag Dictionary, there is a tag group for “discharge air temp sensor” that con-
tains the following set of individual tags:
• discharge
• air
• temp
• sensor
When you add that tag group to a component all four tags are added to that component with one add
action.
The D e v i c e M a n a g e r and P o i n t M a n a g e r views of a driver, and the E d i t T a g s dialog are the primary meth-
ods for adding a Tag Group to a component.

36 July 14, 2016

Tagging Guide Chapter 3 Tagging reference

N O T E : When creating or editing a Tag Group, a tagging best practice is to include only those tags that have
a corresponding Tag Definition in the parent tag dictionary. One way to guarantee it is to populate the Tag
Group’s Tag List with tags copied only from the Tag Definitions list in the tag dictionary. Note that in
Niagara 4.0, any tag that exists in a Tag Group Definition is required to have a corresponding Tag Definition
in the same tag dictionary. While in Niagara 4.1 this is no longer required but it is still a recommended best
practice.

T a g G ro u p f u n c t i o n a l i t y c h a n g e s f o r N i a g a r a 4 . 1
Starting in Niagara 4.1, when using the E d i t T a g s dialog to add a Tag Group, the Tag Group displays in the
D i r e c t T a g s tab as an Ord to the Tag Group itself, and once the change is saved the individual tags of the
Tag Group display in the I m p l i e d T a g s tab. This is a change from how Tag Group tags were handled in
Niagara 4.0, where using the E d i t T a g s dialog to add a Tag Group resulted in the individual tags displaying
in the D i r e c t T a g s tab.
A Tag Group can contain tags from other tag dictionaries. You can add a tag to a Tag Group that overrides
the namespace of the parent tag dictionary. This allows you to define a Tag Group that contains tags from
multiple tag dictionaries. Note, that there is no verification that the tag name entered is actually defined in a
tag dictionary. If the Tag Definition does not exist, the added tag is an "ad hoc" tag. It is possible to use ad
hoc tags although, a tagging best practice is to include only those tags that have a corresponding Tag Defi-
nition in the parent tag dictionary.
You can add a single “Data Policy” to a Tag Group Definitions folder (or to a Tag Definitions folder). A data
policy provides additional metadata that can be associated with a tagged component. For more details see
“Data Policies”.
Conv ert ing ex i st in g t ags to Ta gGrou p Rel a ti ons
On station startup, the Tag Group Monitor in Tag Dictionary Service scans the station components looking
for a complete set of tags from each defined TagGroup in the TagDictionaryService. If a complete set is de-
tected, the Monitor replaces the set of tags on the component with an n:tagGroup relation from the com-
ponent to the TagGroupDefinition. This set of tags then becomes implied tags on the component.
Using the Edit Tag dialog within the Template Editor
When using the E d i t T a g s dialog within the T e m p l a t e E d i t o r view, TagGroup tags are assigned to a compo-
nent as individual direct tags in the template. Upon template deployment, the Tag Group Monitor in the Tag
Dictionary Service is notified and the individual tags (of the tag group) are removed from the component
and replaced with an n:tagGroup relation. The relation, of course, implies the same set of tags.

RelationDefinitions
Tag dictionaries often contain a collection of Relation Definitions (shown in the following image) which are
standardized Relation Id's with semantic meaning for that namespace. These relation definitions come into
play when adding a relation to a component, in the R e l a t i o n dialog, your choices are limited to the relations
that are defined in any of the tag dictionaries installed on your system.

F ig ure 6 Relation Definitions in custom TagDictionary (left) provide choices seen in the Relation dialog (right)

July 14, 2016 37

Chapter 3 Tagging reference Tagging Guide

N O T E : Starting in Niagara 4.1, there is a new implied relation. For devices containing child points that have
a Null Proxy extension, the childNullProxyPoint relationis implied on each of those points.

Tag Rules
The Tag Rules used in a SmartTagDictionary are the primary mechanism for implying tags and relations. It is
the tag rules defined in the installed tag dictionaries that determine which implied tags and implied relations
are assigned to each object.
A Tag Rule defines certain criteria that determines if one or more tags and/or relations are implied on an en-
tity. In addition to the Condition property, Tag Rules contain three definition lists: Tag List, Tag Group List,
and Relation List.
When a “taggable” object (entity) is evaluated, the process determines if the object meets the criteria speci-
fied in the Condition property of each tag rule. If the criteria is met, then it will return a tag (or relation, or
tag group) with the value set (if other than a Marker tag). If the criteria is not met, then the implied tag does
not apply and a null value is returned. Eventually, the results from the tag rules in all of the smart tag diction-
aries in the station are merged to form the complete set of implied tags and implied relations for an object.
The Validity slot of a definition (TagInfo, RelationInfo, or TagGroupInfo) is not evaluated in a tag rule or in a
tag group definition. It is only evaluated in the Tag Definitions of a tag dictionary.
Any definition (tag, tag group, or relation) that exists in a Tag Rule or Tag Group Definition is required to
have a corresponding definition in the main lists of the tag dictionary (Tag Definitions, Tag Group Defini-
tions, Relations Definitions).

New in Niagara 4.2

In earlier releases, the tagdictionary palette contains only one default TagRule, TagForType which has
the IsType condition, however the Condition slot is frozen, uneditable, limiting its usage. In Niagara 4.2,
the tagdictionary palette contains additional Rule components allowing you to add custom TagRules
(with different Conditions) to smart tag dictionaries. These new TagRule components in the palette cover all
possible conditions (except Never) which means that tags can be implied using more complex logic.

Fi gu re 7 Example hvac tag rule (Haystack Tag Dictionary)

The tag rule shown here is the BooleanFilterRule. The rule’s Condition slot has a F i l t e r field contain-
ing the NEQL predicate which queries for the following tags: hs:ahu or hs:vav or hs:chiller or hs:
chillerPlant or hs:coolingTower or hs:heatExchanger or hs:boiler or hs:boilerPlant. Al-
so, the rule’s Tag List is configured with the hvac marker tag. This tag rule queries objects in the station,
filtering for those that have one or more of the tags specified in the condition Filter field. If the query returns
true for any object (as having one of more of the queried tags), then the rule applies the hvac implied tag
to the object as well.
Each of the TagRule components is configured for a certain condition. If these conditions are met (present in
station objects) then the specified tag(s) and/or relation(s) become implied for those objects.

AlwaysRule
If the AlwaysRule is present in an installed tagdictionary, then the condition is true for all station objects and
so the specified tag(s) may be applied to each and every object.

38 July 14, 2016

Tagging Guide Chapter 3 Tagging reference

Name Value Description

Condition true (default) There is no criteria to be met. The condition is always “true”
so a filter is not necessary.
Tag List tag(s) Tag Info List contains the list of tag(s) to be applied.

Tag Group List tag group(s) Tag Group Info List contains the list of tag groups to be
applied.

Relation List relation Id(s) Relation Info List contains the relation Ids to be applied.

AndRule
The specified tag definitions may be applied if the target object has all of the conditions listed under the
Condition property.

Name Value Description

Condition Criteria to be met by target objects.
Condition sub- tagdictionary: Add slots under Condition property or drag any of the Condi-
properties conditionName tion components (Always, And, BooleanFilter, HasAncestor,
null (default) HasRelation, IsType, Never, Or) from the palette.
Tag List tag(s) Tag Info List contains the list of tag(s) to be applied.

Tag Group List tag group(s) Tag Group Info List contains the list of tag groups to be
applied.

Relation List relation Id(s) Relation Info List contains the relation Ids to be applied.

BooleanFilterRule
The specified tags may be applied if the target object has a tag listed in the Filter property.

Name Value Description

Condition Criteria to be met by target objects.
Filter baja:string Target object must meet the filter criteria (NEQL query).
false (default)
Tag List tag(s) Tag Info List contains the list of tag(s) to be applied.

Tag Group List tag group(s) Tag Group Info List contains the list of tag groups to be
applied.

Relation List relation Id(s) Relation Info List contains the relation Ids to be applied.

HasAncestorRule
The specified tag definition(s) may be applied if the target object, or one of its ancestors, has the tags listed
in the Filter property.

July 14, 2016 39

Chapter 3 Tagging reference Tagging Guide

Name Value Description

Condition Criteria to be met by target objects.
Filter baja:string Target object or one of its ancestors must meet the filter crite-
false (default) ria (NEQL query).
Tag List tag(s) Tag Info List contains the list of tag(s) to be applied.

Tag Group List tag group(s) Tag Group Info List contains the list of tag groups to be
applied.

Relation List relation Id(s) Relation Info List contains the relation Ids to be applied.

HasRelationRule
The specified tag definition(s) may be applied if the target object, or an object along the relation specified in
the Relation Id field, has the tags listed in the Filter property and has the relation specified in the Rela-
tion Id field.
Name Value Description
Condition Criteria to be met by target objects.
Filter baja:string Target object must meet the filter criteria (NEQL query).
false (default)
Relation Id baja:string Relation along which objects will be searched for one that
meets the Filter criteria.
Tag List tag(s) Tag Info List contains the list of tag(s) to be applied.

Tag Group List tag group(s) Tag Group Info List contains the list of tag groups to be
applied.

Relation List relation Id(s) Relation Info List contains the relation Ids to be applied.

I s Ty p e R u l e
The specified tag definition(s) may be applied if the target object is one of the specified object type.

Name Value Description

Condition Criteria to be met by target objects.
Is Type Condition baja:TypeSpec Target object must be or extend this specified type.
sub-property
Tag List tag(s) Tag Info List contains the list of tag(s) to be applied.

Tag Group List tag group(s) Tag Group Info List contains the list of tag groups to be
applied.

Relation List relation Id(s) Relation Info List contains the relation Ids to be applied.

OrRule
The specified tag definition(s) may be applied if the target object has any of the conditions listed under the
Condition property.

40 July 14, 2016

Tagging Guide Chapter 3 Tagging reference

F ig ure 8 Example OrRule tag rule

Name Value Description

Condition Criteria to be met by target objects.
Condition sub- tagdictionary: Add slots under Condition property or drag any of the Condi-
properties conditionName tion components (Always, And, BooleanFilter, HasAncestor,
null (default) HasRelation, IsType, Never, Or) from the palette.
Tag List tag(s) Tag Info List contains the list of tag(s) to be applied.

Tag Group List tag group(s) Tag Group Info List contains the list of tag groups to be
applied.

Relation List relation Id(s) Relation Info List contains the relation Ids to be applied.

Data Policies
Starting in Niagara 4.1, tag dictionaries may include data policies. A data policy provides additional metada-
ta associated with a tag or tag group. The tagdictionary palette contains the following DataPolicy
components:
• DataPolicy
• BooleanDataPolicy
• EnumDataPolicy
• NumericDataPolicy
• StringDataPolicy
N O T E : Typical tagging operations do not require data policies. The data policy functionality is provided pri-
marily for use by the Niagara 4.1 Analytics engine. For that reason, tag dictionaries may include added data
policies.
An A d d D a t a P o l i c y action has been added to TagInfo and TagGroupInfo components. Invoking this action
prompts you to select a DataPolicy type to add to the selected TagInfo or TagGroupInfo component in a tag
dictionary.
You can also add a data policy to TagInfo or TagGroupInfo components by dragging a DataPolicy compo-
nent from the tagdictionary palette and dropping it on the desired TagInfo or TagGroupInfo
component.
N O T E : You may not add a data policy if the TagInfo component is a Marker tag, or if the TagInfo or Tag-
GroupInfo component already has a DataPolicy child. Only a single data policy can be added to TagInfo or
TagGroupInfo components.

July 14, 2016 41

Chapter 3 Tagging reference Tagging Guide

Properties for Data Policy

Name Value Description

Min Interval drop-down with The minimum allowed interval when requesting a trend.
time intervals
Max Interval drop-down with The maximum allowed interval when requesting a trend.
time intervals
Preferred Time three fields: drop- The default time range of the data when a request does not in-
Range down list for time clude a time range.
period, drop-down
list for day of the
month, drop-down
list for time
selector
Preferred Rollup drop-down list of The default rollup of the data when a request does not specify
arithmetic the rollup function.
functions
Preferred drop-down list of The default aggregation when a request does not specify the
Aggregation arithmetic aggregation function.
functions
Units drop-down list of Defines the uni of measure for the data reported from the
units of measure point.
Precision 32 bit (default), 64 Allows you to select 3 2 b i t or 6 4 b i t options for the history da-
bit ta logging. The 64 bit option allows for higher level of preci-
sion but consumes more memory.
Totalized
Trend Required true (default) or When true, all points must have a trend.
false
Units drop-down list of Defines the uni of measure for the data reported from the
units of measure point.

Plugins in the tagdictionary module

Plugins provide views of components and can be accessed in many ways. For example, double-click a com-
ponent in the Nav tree to see its default view. In addition, you can right-click on a component and select
from its V i e w s menu.
For summary documentation on any view, select H e l p → O n V i e w (F
F1 ) from the menu or press F 1 while the
view is open.
View(s) in the tagdictionary module are described in the following sections.

Tag Dictionary Manager view

T a g D i c t i o n a r y M a n a g e r, the default view for the Tag Dictionary Service, lists all tag dictionaries installed
on the station. The view provides functionality for creating, editing, importing and exporting tag
dictionaries.

42 July 14, 2016

Tagging Guide Chapter 3 Tagging reference

The N e w button at the bottom of the view allows you to create either a new tag dictionary or a new smart
tag dictionary which you can then export to a CSV file for editing. You can edit an exported tag dictionary
The E d i t button at the bottom of the view allows you to change the tag dictionary properties Name, Name-
space, and Enabled status.
The T a g D i c t i o n a r y M a n a g e r view allows you to I m p o r t and E x p o r t tag dictionaries in a standard CSV file
format. You can edit an exported tag dictionary in a CSV-compatible spreadsheet program (either online or
offline) to add or remove tag definitions, tag groups definitions, relation definitions, as well as validity rules.
Afterwards, you may import the edited CSV file, thereby updating the existing tag dictionary.

July 14, 2016 43

Chapter 3 Tagging reference Tagging Guide

44 July 14, 2016

Glossary
data policy A data policy provides additional metadata that can be associated with a
tagged component. For more details on tags and tagging, see the Tagging
Guide.
Haystack An extensible Semantic Web Browser developed by the Haystack research
group at the MIT Computer Science and Artificial Intelligence Laboratory
([Link] The project explores how the Semantic Web data
model (a Resource Description Framework — RDF) can be applied by users to
better organize, navigate, and retrieve information, both personal and shared
([Link]/2005/04/swls/BioDash/Demo/What is [Link]).
Haystack tag dictionary A smart tag dictionary (namespace) containing a collection of tags developed
by Project Haystack, which can be used for semantic modeling of building con-
trol entities, i.e. site tags, building tags, equipment tags, point tags, geo-loca-
tion tags, etc.
The Haystack dictionary is indicated by the hs character, followed by a colon
character (:).
The Haystack dictionary is a result of the work of the Open Source Initiative
(OSI) hosted on the website [Link]
namespace A container for a set of names in a naming system. A tag dictionary is a
namespace.

Niagara tag dictionary A tag dictionary (namespace) containing a collection of tags developed for
Niagara systems, that are used for semantic modeling of specific building con-
trol entities, i.e. networks, devices, equipment, points, sites, buildings, geo-lo-
cation, histories, etc.
The Niagara dictionary is a type of Smart Tag dictionary, therefore it applies
Implied Tags and Implied Relations to components and links. This allows
queries to find these components based on type, linkage, hierarchy or combi-
nations of these. The Niagara tag dictionary is included by default in all stations
created using the New Station tool.
The Niagara dictionary is indicated by the n character, followed by a colon char-
acter (:).
semantic information Metadata used to indicate the purpose of a device, that is, what the device is,
what each of its data points means, and how devices are related to each other.
tag A piece of semantic information (metadata) associated with a device or point
(entity) for the purpose of filtering or grouping entities. Tags identify the pur-
pose of the component or point and its relationship to other entities. For exam-
ple, you may wish to view only data collected from meters located in
maintenance buildings as opposed to those located in office buildings or
schools. For this grouping to work, the metering device in each maintenance
building includes a tag that associates the meter with all the other maintenance
buildings in your system.
JACEs are associated with Supervisors based on tags; searching is done based
on tags.
Tags are contained in tag dictionaries. Each tag dictionary is referenced by a
unique namespace.
Tagging Guide

tag dictionary Tag dictionaries contain a set of tag definitions, and may contain tag group
definitions, relation definitions, as well as tag rules for smart tags.
taggable spaces The implementation of tags for all common data types: components, files, his-
tories and alarms.
Index
A S
Ad Hoc tags .......................................................27 simple tag dictionary ..........................................33
adding ............................................................10 smart tag
adding tag rules .........................................................33
tag groups .................................................. 9, 13 smart tag dictionary...................................... 33, 38
tags ..................................................................9 Spy View ............................................................18
AlwaysRule.........................................................38
AndRule .............................................................39
T
tag
B adding in Database pane .................................12
BooleanFilterRule ...............................................39 adding in Discovered pane ..............................11
adding using Batch Editor................................15
tag component...................................................35
D Tag Definitions ...................................................35
tag dictionaries...................................................20
Data Policy creating custom ..............................................20
component .....................................................41 editing exported .............................................21
properties .......................................................41 exporting........................................................20
Direct Tags.........................................................27 importing........................................................24
tag dictionary
custom............................................................33
E properties .......................................................33
Edit Tags dialog..................................................28 types of ..........................................................33
Editing tags in template ......................................16 Tag Dictionary Manager view ..............................43
Tag Dictionary Service ........................................31
tag group
adding ............................................................13
H Tag Group
HasAncestorRule ................................................39 adding ..............................................................9
HasRelationRule .................................................40 adding tag to ..................................................14
Tag Group Definitions.........................................36
Tag Group Monitor.............................................32
I Tag mode
exiting ............................................................19
implied relations and tags in Manager views ...................................... 11–12
viewing with Spy View .....................................18 selecting .........................................................19
Implied Tags.......................................................27 tag rules.............................................................38
viewing ...........................................................17 Tagging
IsTypeRule..........................................................40 license requirements .........................................7
overview ...........................................................7
process .............................................................7
O TagRule
Offline tagging ...................................................28 AlwaysRule .....................................................38
Online tagging ...................................................28 AndRule..........................................................39
OrRule ...............................................................40 BooleanFilterRule ............................................39
HasAncestorRule.............................................39
HasRelationRule ..............................................40
IsTypeRule ......................................................40
R OrRule ............................................................40
Relation Definitions.............................................37 tags
Removing a tag ..................................................11 types of ..........................................................27

July 14, 2016 47

Index Tagging Guide

V
viewing
implied relations..............................................18
implied tags ....................................................18

48 July 14, 2016