Roster Tags
Not counted towards your tag license limit.
Contacts cannot be added to Roster tags before you enable at least one notification method. A voice contact method, or an email server or an SMS appliance must be correctly configured before you attempt to configure a roster.
Further to this, no contact method can be selected unless VTScada is able to determine that it is available for use.
It is not necessary for users to have the Tag Modification privilege to update modem contacts. Anyone with the Manual Data or Parameter View security privilege may add, change or remove roster entries.
Roster tags are designed to work with the Alarm Notification system. Using a Roster tag, you may configure contact information for up to
If the communication method you want to select is not enabled:
Communication methods are enabled only when VTScada is able to use those methods. For example, if you have not configured an email server then you cannot send an email or SMS text ready email.
Roster tags do not work alone. You will also need a way for notifications to be sent (Modem tag, SMS Appliance tag, email server, Twilio account, or pager system) and configuration of the Alarm Notification System properties .
Area Property and Roster Tags
The Area field, selected during configuration, is especially important for Roster tags. The Area field is used by VTScada to tie the Roster to alarms with the same area. If more than one Roster shares the an area, only one can be active at a time. The active Roster Tag in an area is always the one most recently activated - all other Roster tags with the same area property are automatically deactivated when one is activated. (See: Roster Selection Hierarchy)
In general, Roster tags should use the area, Default, unless you intend to send different sets of alarms to different operators.
If a Roster is a child of a custom AlarmDatabase, it will notify for alarms only from that database rather than all. Alarms with a matching Area property but under other AlarmDatabases will not be sent out by this Roster.
You may switch to the legacy behavior where all AlarmDatabases are searched, but this will be slower if you have a large number of AlarmDatabase tags. See: LimitRosterToParentDB
Default Call-Out Off Roster
One Roster Tag, the Default Call-Out Off Roster, is configured in every VTScada system. No names should be added to this roster. Its purpose is to provide a means of telling VTScada to not notify anyone. Because only one roster in an area can be active at a time, if the roster that is active has no names attached, no one will be notified.
Whether existing alarms are sent to a roster as it becomes active depends on the configuration of the rosters.
Alarms are not transferred: Given two rosters, the first having no contacts (since operators are assumed to be on-site) and the second having a list of contacts for when operators are not on-site. As the second roster becomes active, existing alarms are not sent to it.
Alarms are transferred: Given two rosters, each of which has a list of contacts. As the second roster becomes active, existing alarms that were being called out to the now-inactive roster will switch to the currently active roster.
If your system includes more than one modem, and those modems are attached to servers located in regions with different area codes, then you must use the 1 for each phone number and you must configure the server's location within the Windows™ Phone and Modem Settings dialog.
"9" - Internal vs external phone lines
In the event that you must configure a Roster tag to include the prefix "9" from some workstations, but not others, you should use the Modem Settings dialog in the Windows Control Panel.
On a computer that requires the 9:
- Open the Control Panel.
- Open the Phone and Modem Options dialog.
- Select the Dialing Rules tab.
- Click, Edit.
- Ensure that the area code is set.
- In the appropriate boxes, enter the number "9".
- Click Apply and close.
- In the Roster configuration, ensure that you use the canonical form of the phone number.
Roster Control Using Properties
Roster properties ID tab
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 orange to indicate that you have applied an override.
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.
The Contacts tab for a Roster tag is used to create the list of people who will be notified, and to define how to reach each of them. The available methods include voice (a phone call) email, pager, text message, or text as a compact email via your cellular provider.
Contacts cannot be added for communication methods that do not exist on your system. A voice system or an email server or an SMS appliance must be correctly configured before you attempt to configure a roster.
Note that the choice of communication method controls the label and purpose of the next few fields, as shown. (Voice and SMS Text will have identical fields, as will Email and Compact Email.)
Contact List (Contact Order | Username | Mode | Enabled)
The list displays the operators who will be contacted in this roster, how they will be contacted and whether that entry is enabled. Up to 30 names may be added. The list is not interactive . You cannot change the contact mode or enabled status by clicking on in the list. Instructions are provided later in this topic.
Blank lines are permitted, but not recommended because they will make the list more difficult to work with.
Usernames are encrypted before being stored. Because the encryption is tied to the application's GUID, these will not be available in a cloned copy of the application.
The list may be reorganized using the Move Selected buttons. 
Communication Method
The Communication Method radio buttons enable you to select the method of contact for this operator record. Options include phone/voice, pager, or email.
Continue Roster Sequence
This option does not apply to voice contacts.
VTScada will assume that a message sent by pager, email or SMS-text will be delivered (the equivalent of a phone call being picked up), and will therefore not continue to the next name in the list.
Use the Continue Roster Sequence check box to command the system to continue to contact operators in the order they appear on the roster even though the email or other message was sent.
The roster will continue contacting entries flagged as "continue roster sequence" until the alarm is acknowledged. The time between each attempted contact is controlled by the application property, RosterDelay. If the roster fails to send a notification to a contact, no delay is used before attempting the next (if any).
After calling a Voice contact, the roster will automatically notify the next contact if the last was not successfully contacted and the alarm has not yet been acknowledged. After the alarm is acknowledged (by either the person on the phone or by an operator at the workstation) the roster sequence will terminate until the next alarm goes active.
Do Not Contact
The Do Not Contact check box enables you to temporarily disable an operator's record in the roster. In the event that an alarm is triggered and goes unacknowledged, this operator will be skipped by the roster/dial-out system until the operator's contact information has been enabled.
Contact Description
Used to identify each contact in the list. This is an optional field. If left blank, the Phone Number or email address of the contact will be shown.
Contact User Name
Used if alarm acknowledgment by email or SMS text is configured and if the Communication Method is set to email or SMS text for this contact. If left blank, a notification will be sent, but that message will not include an acknowledgment code.
If set, the field must match an existing security account name.
Phone Number / Email addresses
Voice lines: Enter the contact’s phone number, using only the digits. If your phone systems requires a 9 to access an outside line, you will need to configure your modem options using the Windows™ control panel.
If your system includes more than one modem, and those modems are attached to servers located in regions with different area codes, then you must use the Canonical Address Format for each phone number and you must configure the server's location within the Windows™ Phone and Modem Settings dialog.
Pagers: The Phone Number field requires the paging company’s T.A.P. Modem Number (TAP = Telocator Alphanumeric Protocol). This number enables access to the alphanumeric paging network, enabling VTScada to send a message to the pager phone/PIN. The correct number for the Phone Number field can be obtained from your paging company’s technical support team.
Email addresses: If the selected contact mode is email, this field will be used for email addresses rather than phone numbers. You may enter several addresses, using a semi-colon between each.
You may add a list of email aliases, from which acknowledgments will be accepted. This is useful when an operator has forwarded one or more email accounts to another that is used more often. Use a colon character to separate the list of email addresses to which the alarm will be sent from the list of email addresses that are acceptable aliases for those accounts. There is no need to add an alias address if the operator will reply from one of the addresses to which the notification is sent.
Example 1 - A simple configuration.
JoeOperator@CountyUtility.com
Example 2 - Configured with multiple addresses for one operator. A notification is sent to both addresses. Joe can acknowledge from either.
JoeOperator@CountyUtility.com;JoeOperator@GigaMail.com
Example 3 - Joe has forwarded his CountyUtility account to his GigaMail account. Notification is sent to his CountyUtility account, but Joe reads and acknowledges the alarm using his GigaMail account.
JoeOperator@CountyUtility.com:JoeOperator@GigaMail.com
While there is no limit on the number of email addresses you may have, the combined total number of characters may not exceed 255.
For those using Realm Filtering: Each contact user name in the roster that belongs to a realm must include the full realm qualifier. For example: WestRealm:Robert
Pager PIN
This field is used only with the pager communication method. A PIN is a required part of the pager contact information.
Time Zone
If one or more of the contacts are located in a time zone other than that of the alarm server, they may find it inconvenient or confusing to translate the time stated in the alarm notification to their local time. If the contact's time zone is provided, using this drop-down list, then they will receive a message that has been adjusted to their location for them.
The list uses the names built into the Microsoft Windows' Multilingual User Interface Pack.
To add contact to the list:
- Click on a blank row in the list.
To keep the list tidy, you should select the first blank row from the top. The row will be displayed with blue highlighting. - Select the communication method.
Voice, Pager or Email - Enter the name of the operator in the Name field.
As soon as you press enter or exit from the field, the name you typed will be added to the list. - Enter the phone number or email address (as per the communication method) for the contact.
Email addresses may be in the basic form, Name@Company.Com" or you may use either of the following longer forms. Multiple addresses may be entered, separated by semi-colons or commas. Do not add spaces within the angle brackets.
"Full Name" <Name@company.com>
Full Name <Name@company.com> - [Only if the contact mode is "Pager"] Enter the PIN number for the pager.
To update a contact in the list:
- Click on the contact entry that you want to modify in the list.
- Change any of the fields that need to be updated.
Changes to the row take effect immediately on pressing <enter> in each field, or upon leaving the field.
To delete a contact from the list
- Select the contact entry that you want to delete from the list.
- Click the X (delete) button at the lower, right corner of the list.
If an operator’s contact mode has been set to email and a badly formatted email address has been entered, then the following warning dialog will be displayed:
Click on the Close button and correct the email address before proceeding. The Roster tag will not permit you to save a badly formatted email address.
Roster properties
Activation Trigger:
For any given area (including "Default") one roster, and only one roster, is always active. Activating a roster automatically deactivates all other rosters that share the same area.
You can draw a roster as a Make Active button to allow user control but many sites prefer to automate the process of switching rosters by using a Trigger Tag. Note that if using a Trigger tag, in addition to setting the On time, you should also set an Off time 30 seconds later. This will not deactivate the Roster, but will allow the next On time trigger to occur.
When this tag is represented on screen by widgets that can use a Style Settings tag, you can save development time by choosing the Style Settings tag that holds the correct display configuration for this tag instance.
The default configuration will use System Style, the default style tag that is automatically part of every new VTScada application.
Roster Tag Widgets
The following widgets are available to display information about your application’s Roster tags:
