Context Tags

Not counted towards your tag license limit.

Context tags are used as parents in parent-child tag structures. They provide a generic and customizable template that you can use to define any natural grouping in your application (region, station, city, sub-assembly, etc.). The parameter list for a context tag is left for you to configure. You may add whatever properties you wish. For example, you might add properties named Latitude and Longitude to be able to draw the Context tag on a Site Map, or you might create I/O address fields that can be used by child tags that you add to the Context tag. If you have one type of Context tag that is to be used for sites, you can add another to be used as a connector between those sites.

Notes for Property Value:

When entering property values, decimal numbers of up to 15 significant digits will be converted to a numeric value. Numbers with more than 15 significant digits will be converted to an equivalent text string.
A decimal number expressed in exponential notation, (e.g. 1.1E-3) will be converted to an equivalent text string.
Binary, Octal, and Hexadecimal values are converted to their 32 bit signed integer equivalent. Any such number that exceeds the maximum signed 32 bit value limits (-2,147,483,648, 2,147,483,647) is undefined behavior and will be incorrectly converted to a numeric value.

Your context tags can be turned into new tag-types by assigning them a type-name, then using the Create New Type command from the tag's right-click menu in the Tag Browser. All the child tags will be included as part of the new type definition. This feature is especially useful if the child tags are configured using parameter expressions so that their properties are based on values defined in the parent tag.

Context tags can be given site parameters, allowing them to be located on a site map. Related configuration parameters allow you to choose the icon that will represent the site and the page that will open when an operator clicks on that site. You can also configure how and whether the site will be shown in the Sites List page.

Other tag types also count as "sites", including Polling Drivers and Station tags.

There are three situations where it is helpful to set Exclude from Site List on your Context tags:

- When requesting a Go To Page on any Context tag (or other container type) from the Tag Browser or Alarm Page, the Sites page will be included in the list of possible pages and might be the default.
- The above is also true for child tags of the Context tag.
- Context tags (and new types created from them) are always included in the list of a Sites List Display Options. This may not be appropriate if the Context represents equipment rather than a site.

To prevent these actions, do the following:
  1. Select the Add Site Properties button in the Settings tab of the Context tag.
          (See: Change the Parameter List if you have already turned the Context into a new type.)
  2. Delete all site properties except for SiteListDisplay.
  3. In the Display tab, select the option Exclude from the site list
       (If any child tags should be included in a site list then select Display as a Folder instead.)

If you have created one or more sites, you can choose to configure another context tag as a connector. Connectors are drawn as a line (you configure the line style) between two sites that have latitude and longitude values. Connectors can have any properties you care to assign and any child tags you want, thus you can use them to represent pipes or transmission lines configured with all the characteristics you require.

Connectors are straight lines between two points. You can create a corner by adding a third site to your map, located between the first and second site, and configuring that intermediate site so that it is not displayed on the map. Add one connector between the first site and the intermediate site, then add a second connector between the intermediate site and the destination site.

Configuration Notes:

Site-related properties or Connector-related properties are most easily added by clicking the Add Site Parameters button in the Settings tab. After adding the properties you will find it easier to configure site or connector properties using the tools in the Site Display tab.

A Context tag can be a site or it can be a connector, but it cannot be both. If you click Add Site Properties, all connector-specific properties will be removed. If you click Add Connector Properties, all site-specific properties will be removed.
If adding a Type name, ensure that it will be unique to your application, and will not conflict with any existing type such as "Pump" etc. It is best to add a prefix or suffix that is unique to your organization or application. Type names are limited to a maximum of 31 characters.
When adding properties, ensure that names do not conflict with existing parameters such as "Name" or "Area". It is best to add a prefix or suffix to each property name that is unique to your organization or application.

Context (Site) Tags and Alarm Notification

Context tags (or custom types derived from a Context tag) may define custom alarm message templates, for use by all alarms occurring within the structure. This is done by adding the desired template name(s) to the Context's list of properties. If doing so, it is typical to use an expression when defining the template so that the message will be unique for each instance of the type.

For example, Concat(\Name, "%N%M") would show the name of the Context tag plus the description of the alarm (which may be a child, grandchild, etc. of the context).

Because tag names and other properties may contain characters that would conflict with template characters, such as percent signs (%), you should always process information from the Context tag using the \PrepStringForTemplate() function. Updating the previous example, Concat(\PrepStringForTemplate(\Name), "%N%M") is the safer way to reference \Name in case any given name contains a %.

Note that you might also need to use a \GetPhrase or \GetParmPhrase call in your expression. See: Multilingual Expressions

Related information:

Design Your Own Tags - Use your context tag as the basis for a new tag type.

Automated Tag Configuration - Use expressions in child tags so that they configure themselves based on the parent's configuration.

Create Widgets - Create new multi-part widgets for your multi-tag types.

Site Map - Mapping in general. Sub-topics relate to linking at tag, such as your context tag, to a map.

Sites & Maps

Alarm Message Templates - Control the content of alarm messages.

Best Practices for Tags

Context properties ID tab

The Context Tag's ID tab contains an extra field named, "Type". If, after creating the context tag, you right-click on it in the tag browser and select "Create Type" you will create a new tag type, named after the contents of the Type field.

The name you provide for the type must be a single word and must not duplicate the name of any existing type of tag. An error dialog box will warn you if invalid characters are used, or if the name supplied cannot be used as the name of a new tag type.

The ID tab of every tag includes the same common elements: Name, Area, Description, and Help ID.

Name:

Uniquely identifies each tag in the application. If the tag is a child of another, the parent names will be displayed in a separate area before the name field.

You may right-click on the tag's name to add or remove a conditional start expression.

Area

The area field is used to group similar tags together. By defining an area, you make it possible to:

Filter for particular tag groups when searching in the tag browser
Link dial-out alarm rosters to Alarm tags having a particular area
Limit the number of tags loaded upon startup.
Filter the alarm display to show only certain areas.
Filter tag selection by area when building reports

When working with Parent-Child tag structures, the area property of all child tags will automatically match the configured area of a parent. Naturally, you can change any tag's area as required. In the case of a child tag, the field background will turn yellow to indicate that you have applied an override. (Orange in the case of user-defined types. Refer to Configuration Field Colors)

To use the area field effectively, you might consider setting the same Area for each I/O driver and its related I/O tags to group all the tags representing the equipment processes installed at each I/O device. You might also consider naming the Area property for the physical location of the tag (i.e. a station or name of a landmark near the location of the I/O device). For serial port or Roster tags, you might configure the Area property according to the purpose of each tag, such as System or Communications.

You may define as many areas as you wish and you may leave the area blank for some tags (note that for Modem tags that are to be used with the Alarm Notification System, it is actually required that the area field be left blank).

To define a new area, type the name in the field. It will immediately be added. To use an existing area, use the drop-down list feature. Re-typing an existing area name is not recommended since a typo or misspelling will result in a second area being created.

There is no tool to remove an area name from VTScada since such a tool is unnecessary. An area definition will exist as long as any tag uses it and will stop existing when no tag uses it (following the next re-start).

Description

Tag names tend to be brief. The description field provides a way to give each tag a human-friendly note describing its purpose. While not mandatory, the description is highly recommended.

Tag descriptions are displayed in the tag browser, in the list of tags to be selected for a report and also on-screen when the operator holds the pointer over the tag’s widget. For installations that use the Alarm Notification System, the description will be spoken when identifying the tag that caused the alarm.

The description field will store up to 65,500 characters, but this will exceed the practical limits of what can be displayed on-screen.

This note is relevant only to those with a multilingual user interface:
When editing any textual parameter (description, area, engineering units...) always work in the phrase editor. Any changes made directly to the textual parameter will result in a new phrase being created rather than the existing phrase being changed.
In a unilingual application this makes no difference, but in a multilingual application it is regarded as poor practice.

Help Search Key

Used only by those who have created their own CHM-format context sensitive help files to accompany their application. Refer to Custom Help Files

Context tag properties, Settings tab

Context tags may be given a list of named properties. Each copy of the tag may then be given its own unique values for those properties. There is no limit on the number of named properties that you may create.

Property names may not duplicate VTScada reserved words. To be safe, adopt a naming convention that adds a distinct identifier to every name (for example "MA_Name" for My Application...)

By defining properties in a context tag, you provide a method for children of that tag to adapt their configuration values to the parent instance via Parameter Expressions. For example, I/O addresses may be calculated from a BaseAddress value stored in the Context tag instance.

To create a new property click Add, which opens the Add Property dialog:

Property names must be unique, not just in the list of properties, but in the tag itself. VTScada properties such as Name, Area and Description may not be used. Attempting to do so will cause the "Name in Use" dialog to open.

Property names must include letters ("Property2" is valid, but "2" is not). The property name may not include a space or any of the following characters: ! , @ % ^ & * ( ) - ` ~ : ; " ' < > ? / { } [ ] | \ .

You can change any property name, value or comment by clicking on the field in the settings list. Editing is done in-place.

If you turn the context tag and its children into a new type using the Create New Type command in the tag browser, you can still edit the list of properties for the type definition as a whole. See: Modify a Custom Type.

Add Site Properties.

Connectors are not sites, and sites cannot be used as connectors.
Connectors do not have Latitude and Longitude properties. Sites do not have other start and end sites.
To create connectors, you must have both tags configured as sites and tags configured as connectors.

Click this button to add the five properties that relate to site maps, Latitude, Longitude, CustomDetailsPage, CustomMapIconParm and SiteListDisplay. After adding the properties it is easier to assign values for the properties using the Site Display tab. Connector-specific properties will be removed when you add site properties.

Values for all five can be set using the Site Display tab.
Latitude and Longitude are required if this context tag is to be added to a site map as a pin.
SiteListDisplay is necessary if you wish to control whether the tag behaves as a "site" or a "folder" in the Site List page, or should not be shown at all. In the Site List, a "site" will open to a Site Details page when clicked. A "folder" will open within the sites list to show sub-sites (if any) and immediate I/O child tags.
CustomDetailsPage is required only if you have or will create a custom page to display the child tags of this context tag. Otherwise, you may delete this property and use the standard Site Details page.
CustomMapIconParm is required only if you intend to create a custom pin to mark this Context tag on a Site Map. Otherwise, you may delete this property and use a standard pin.

Add Connector Properties

Click this button to add the five properties that relate to site maps, Latitude, Longitude, CustomDetailsPage, CustomMapIconParm and SiteListDisplay. After adding the properties it is easier to assign values for the properties using the Site Display tab. Connector-specific properties will be removed when you add site properties.

CustomDetailsPage is required only if you have or will create a custom page to display the child tags of this context tag. Otherwise, you may delete this property and use the standard Site Details page.

StartSite and EndSite are required for all connectors. These will be configured with the two tags that hold site properties to mark the latitude and longitude of the start and end of the connector line.

ConnectorColor defines the color of the line. By default the property is gray, defined using an Alpha value of FF and RGB values of E6E6E6. <FFE6E6E6> You may use any of the numeric values from the VTScada color palette instead.

ConnectorStyle defines the line type. The drop-down list of the available styles is easier to use than assigning numeric values, which match those provided in the list of VTScada line styles. Note that the line or pipe width cannot be configured as it will scale as the zoom-level changes.

ShowConnectorArrows defines which of the three possible arrows should be shown in the display. This is stored as a bit-wise value where bit 0 matches the arrow at the 1/4 position on the line, bit 1 matches the arrow at the half-way position and bit 2 matches the arrow at the 3/4 position. Arrows will always point from the start site towards the end site.

CustomMapIconParm is required only if you intend to create a custom widget to mark this Context tag on a Site Map. Otherwise, you may delete this property and use the standard Site Draw widget.

SiteListDisplay is necessary if you wish to control whether the tag behaves as a "site" or a "folder" in the Site List page, or should not be shown at all. In the Site List, a "site" will open to a Site Details page when clicked. A "folder" will open within the sites list to show sub-sites (if any) and immediate I/O child tags.

Filter Child Types in the Sites Page

As an example, your custom type might be a city. Within that city (and as child tags of this type) there might be lift stations and other custom types that qualify as sites for the purpose of this list.

When the city tag is viewed in the sites page, you will be able to expand the list to view all subordinate sites. But, you might want to restrict that list to only the lift stations.

You can filter the list of child sites by adding the parameter CustomSiteListFilterType to the parent type, and setting the value of that property to the type name that should be shown in the list. You could also specify the name of a group of types, such as "Station" to filter for tags such as the MultiSmart and MPE.

The filter affects only the immediate children of the tag where it is defined.

Context properties Site Display tab

Before using this page, you must add either site properties or connector properties in the Settings tab.

(Site Configuration)

(Connector configuration)

There are two ways to prevent a site's location pin from being shown on a map: Leave the Latitude and Longitude values empty, or deselect the Show option for the map icon. If the site has latitude and longitude values, but the icon is not displayed, then the indicator beacon will pulse while the cursor is held over the site's coordinates on the map, even though the pin is not displayed.

Latitude and Longitude (Site configuration only)

Holds location coordinates for this tag, thereby allowing it to be represented on a Site Map page if the map icon is shown.

Start Site and End Site (Connector configuration only)

Holds links to the two site tags, between which the connector will be drawn.

Custom Details Page

If a custom details page has been created for this context tag, then that page should be selected here. If there is no custom details page, then operators will see the standard Site Details page upon clicking the pin for this tag in a Site Map.

Map Icon

You might choose to define a location for this site, but not display it on a map. This is sometimes done to add corners for connector lines or pipes.

If a custom map icon widget has been defined, you can select it here. That icon will then be used instead of the standard icon when this tag is represented on a Site Map page. If there is no custom map icon, then the standard widget will be used. A custom map icon is any tag-widget that can be linked to this tag type.

Site List Display

Assuming that this tag has site properties, it will be included in the list of a Sites page. What will happen when an operator clicks on this tag in that list depends on the Site List display choice, and on whether any of this tag's children are I/O tags. Note that the following applies only to the list section of the Sites page, not to the map.

Display as Site: A click will open the Site Details page as a pop-up.
Display as Folder: A click will leave focus on the Sites page, but the list will now show the child tags of this site.
Exclude from Site List: This tag should not be shown in the list section of the Sites page.
Only Display Child Tags: This tag is used to group other sites. Those sites should be displayed, but this one should not be displayed. Operators will not need to navigate through this site to reach the child sites.
Automatic: If this tag contains child sites, folder display will be used. Otherwise, site display will be used.

Connector Style and Color (Connector configuration only)

Choose whether to display the connector as a pipe or as a line using any of the built-in VTScada line styles. The default color will be gray. Use the color option to select any other color.

Map Zoom Level (Site configuration only)

If Automatic is chosen (the default) then when a map is opened, showing only this site, it will zoom to level 15, which shows only the immediate surroundings. You may select any value between 18 (the closest possible level) and 2 (showing the entire globe).

Default zoom level.

Directional Arrows (Connector configuration only)

Up to three arrows can be drawn on the connector, pointing from the first site to the second. These can be added at the 1/4, 1/2 and 3/4 positions of the visible segment of the connector.