Notification Block
As the name suggests, the Notification block is responsible for sending notifications. Each notification block can target multiple notification profiles, which represents different methods of notification, but it will only notify the user on the first profile that the user has contact information for. So having a notification block with both email and SMS listed will first attempt to contact a person with the profile type listed first. If that fails because the user does not have contact information for that profile type, it will try the second profile. Each type of notification profile will have its own relevant properties for configuration, although some features are common to all profile types. The various profiles will also behave differently, according to their capabilities, in regards to how notifications are ordered. For example, the Email profile is capable of sending a message to many recipients at once, while the SMS and Voice notification profiles must step through each contact sequentially.
There are two required settings for notification blocks: the Notification Profile and the On-Call Roster. The profile will dictate the method through which notifications occur, and the on-call roster will dictate who receives the notifications. The on-call roster provides an ordered list of contacts, which will first be pared down according to each user's schedule. The resulting contacts will be notified in order, based on how the profile operates. The settings displayed will depend on the type of profile selected.
Notification
The Notification tab allows you to select which Notification Profile you would like to use from what you have currently configured in your Gateway. The settings that can be configured differ, depending on the type of Notification profile selected. However, all of the notification types share a setting, outside of the property area called Delay Between Messages. This property allows you to set a delay that will happen in between notifications to each user in a roster. So if your delay time is set to 30 seconds on an email notification, it will email the first person in the roster and then wait for 30 seconds before emailing the next person. It is set to zero seconds by default.
Email Settings
| Setting | Description |
|---|---|
| From Address | Email address used for the From field. |
| Subject | Subject of the email. |
| Message | The body of the email. Like the subject, may refer to properties of the alarm. Message supports HTML formatting. Simply add the <html> tag at the beginning of the Message property. An end tag (</html>) is not required. <html>This is my message. <br>That was a line break. |
| Consolidated Message | The message sent when consolidation is turned on, and more than one alarm is being sent. See the Notification Block section for more details. |
| Recipient Type | Determines if the email is sent to the user via "To", "CC", or "BCC". |
| Send Ack Link | Allows the notification block to override the acknowledgment link that's included with two way email notification, potentially hiding it. If Two-way notification is enabled on the email notification profile, and this property is false, then emails sent by the block will not include an acknowledgement link. |
| Test Mode | If enabled, logs to the console each time an email would be sent, instead of sending the actual email. |
| Retry Count | The number of retry attempts per email per alarm. Default is 0. This setting applies when there is an exception that occurs when attempting to send a message, such as network connectivity issues. |
| Retry Delay | Introduces a delay between each email for each alarm. Default is 5. This setting applies when there is an exception that occurs when attempting to send a message, such as network connectivity issues. |
Voice Settings
| Setting | Description |
|---|---|
| Require PIN | If true, the user will need to enter their PIN in order to hear the alarm notification messages. The user's PIN is defined in the user management section of the Gateway. If false, then anyone will be allowed to hear the messages after answering the phone. |
| Allow Acknowledgment | If false, users will only be allowed to listen to alarms, not to acknowledge them. |
| Retries Per Contact | The number of retry attempts per contact per alarm. |
| Delay Between Retries | Introduces a delay between each retried contact notification in a Roster for each alarm when the Retries Per Contact setting is greater than 0. This delay setting is independent from the Delay Between Messages setting. Example Notification Delay Process: If there are two Users in a roster and Retries Per Contact is set to 2, the notification process would function as follows:
|
| Test Mode | If enabled, messages will be logged to the console indicating when and to whom calls would have been made, without actually making a call. |
SMS Settings
| Setting | Description |
|---|---|
| Message | The message to use for single events. |
| Consolidated Message | The message sent when consolidation is turned on, and more than one alarm is being sent. See the Notification Block section for more details. |
| Delay Between Notification | As with voice, a delay between each message sent, to give the recipient time to acknowledge and prevent further notification. |
| Acknowledge Message | When two-way SMS notification is enabled, this property allows for the configuration of the acknowledgment instructions the users receive in the notification. The '%s' will be replaced by the user's acknowledge code. |
| Test Mode | If enabled, logs messages that would have been sent to the Gateway console, and does not actually send them. |
Twilio Settings
SMS notifications can also be sent with the Twilio Alarm Notification module. To use Twilio, you must first set up Twilio SMS Notification. This does not require a cellular modem, but the Gateway must have Internet access, and a Twilio account with SMS capabilities must be created ( www.twilio.com ).
| Setting | Description |
|---|---|
| From Number | Number from which the alarm notification is sent. |
| Message | Message to send. Default is " At {eventTime |
| Consolidated Message | New in 8.1.2 The message sent when consolidation is turned on, and more than one alarm is being sent. See the Notification Block section for more details. In release 8.1.2 this setting was renamed from "Throttled Message" to "Consolidated Message." |
Message Properties
The email, SMS notification, and Twilio notification types have a few different message settings. There are properties that contain alarm values that can be used in these message settings. To use the property, place { } around it. The table below contains all of the properties available to them.
| Property Name | Property Display Name | Description |
|---|---|---|
| Count | {AlarmEvents.Count} | The number of alarm events that are in the pipeline. Typically used with alarm consolidation. |
| Maximum Priority | {AlarmEvents.MaxPriority} | The maximum priority of the alarms in the pipeline. Typically used with alarm consolidation. |
| Minimum Priority | {AlarmEvents.MinPriority} | The minimum priority of the alarms in the pipeline. Typically used with alarm consolidation. |
| Display Path | {displayPath} | The display path of the alarm. |
| Display Path or Source | {displayPathOrSource} | The display path of the alarm, or the sourcepath if no display path was defined. |
| Name | {name} | The name of the alarm. |
| Priority | {priority} | The priority of the alarm. |
| Source Path | {source} | The source path of the alarm. |
| Ack Time | {ackTime} | The time when the alarm was acknowledged. |
| Ack'ed By | {ackUser} | The username of the person that acknowledged the alarm. |
| Ack'ed By (Name) | {ackUserName} | The name of the person that acknowledged the alarm. |
| Acked? | {isAcked} | A True or False on if the alarm is acknowledged. |
| Active Time | {activeTime} | The time the alarm went active. |
| Active? | {isActive} | A True or False on if the alarm is active. |
| Clear Time | {clearTime} | The time the alarm went to a cleared state. |
| Clear? | {isClear} | A True or False on if the alarm is cleared. |
| Current State | {state} | The current state of the alarm. (Active, Unacknowledged/Active, Acknowledged/Cleared, Unacknowledged/Cleared, Acknowledged) |
| Event State | {eventState} | The state of the alarm event. (Active, Acknowledged, Cleared) |
| Event Time | {eventTime} | The time that the alarm event occurred. Can format the time to a specific format like {eventTime |
| Event Value | {eventValue} | The value of the tag for the alarm event. |
| Is Shelved? | {isShelved} | Is the alarm shelved. |
Contacts
From the Contacts tab, you can specify who you want to send the alarm notification to by specifying what roster type you want to use. There are three different ways to set up a roster.
Direct - Set a specific roster to use. Expression - Set up an expression that will determine which roster to use. Calculated - Use scripting to build a roster within the pipeline. Each has different advantages, so it's important to understand the difference so you can select the method that best fits your needs.
Direct
The Direct roster type is the simplest to set up and use, but also the least flexible. Any On Call Roster defined on the Gateway can be used directly.
Expression
The Expression roster type makes it possible to dynamically choose a single, predefined roster from within the pipeline. The expression can make use of Tag values, alarm properties and associated data. The alarm properties are accessible from the Alarm Properties 
icon located on the right side of the panel. Associated data can be manually entered using the "{" and "}" characters. A list of rosters is available from the On-Call Rosters 
icon.
The above expression checks for associated data named "Group" on the alarm. If the value is equal to "A", the Group A roster is used, otherwise the Group B roster will be notified.
When should I use quotation marks on the Roster name?
It is recommended to always place quotation marks around roster names. However, it is not always required for notifications to be sent out successfully.
If the expression consists of only the name of the roster, then quotes can be omitted. For example, specifying that a Notification block should always use the Roster named Operators could look like the following with quotes:
//This expression will evaluate successfully.
"Operators"
Which would return the string Operators, a valid Roster.
However, quotation marks could be removed in this scenario. This normally causes a syntax error, because strings in expressions must be encased in quotation marks. However, in this case the Notification block will assume you simply typed out the name of the roster, so the following example will also successfully use the Operators roster:
//This will fail to evaluate as an expression, so the block will instead look for a roster named "Operators",
//and the users will still be notified.
Operators
However, if the expression is any more complicated than the above example, such as using an expression function, then quotation marks must be used. The following example would check the priority of the alarm. If the alarm's priority was "critical", then the High Priority Roster would be notified. For all other priorities, the Low Priority Roster would be used.
//This expression will evaluate successfully.
if({priority} > 3, "High Priority Roster", "Low Priority Roster")
However, if the quotes were removed from the roster names, the expression would fail with a syntax error:
//This expression will fail, so all the text is assumed to the name of a Roster
if({priority} > 3, High Priority Roster, Low Priority Roster)
When this expression fails, the Notification block will assume that the text is actually the name of a roster, and will attempt to use a roster named "if({priority} > 3, High Priority Roster, Low Priority Roster)". For this reason, it is a good idea to always place quotes around Roster names, as well as check your expressions for syntax errors.
Calculated
The Calculated roster type allows you to use scripting to create a roster at that time using scripting. This becomes extremely useful for situations when you are not sure who should be contacted at the time. Instead of creating an on-call roster for each possible combination of users, you can determine who needs to be notified in the script based on the circumstances of the alarm, and then build the roster to fit that scenario. While this is extremely powerful and offers the most flexibility, it is the most difficult to configure, so you should only use it when absolutely necessary.
Accessing Alarm Properties
You can access any of the alarm properties through the event object in a calculated roster. Properties are stored as a dictionary and can be accessed in the same way.
# properties can be accessed directly using the dictionary format
# event["propertyname"]
# get the alarm name
alarmName = event["name"]
# get an associated data property named "Machine Area"
associatedArea = event["Machine Area"]
Calculated Rosters
The Calculated roster type requires a return value which is a list of dictionaries, where each dictionary is a set of contact information. The contacts that you use are specific to that instance, meaning neither the user nor contact information have to exist on the Gateway. This can either be done manually, by putting together dictionaries with the appropriate contact info and then placing them into a list, or you can use the builder to put together the list for you. Both end up with the same results, so we advise that you use the one that you find easier. The builder has a set of methods which align with the key:value pairs the dictionary is expecting.
| Name | Description |
|---|---|
| username | A username for this particular user. Note: This can be anything that you want, the user does not have to exist in the Gateway. It will be used for acknowledgement and auditing purposes, so it is important you create meaningful usernames. |
| firstname | A first name for this particular user. |
| lastname | A last name for this particular user. |
| A list of possible email address for the user. | |
| phone | A list of possible phone numbers for the user for voice notification purposes. |
| sms | A list of possible SMS numbers for the user for SMS notification purposes. |
| extraProps | Extra properties that can be added to a user. This is useful when dealing with any third party functionality. New in 8.1.8 The extraProps key can be used to set arbitrary user properties as of 8.1.8. This is useful when trying to set a user property not mentioned above. For example, if you needed to set the language for a user on a calculated roster to Spanish so that the Voice Notification module uses a Spanish voice, the user would be configured as follows: extraProps key can be used to set the following user properties. Technically it can be used to set any user property. See the User object. The value for each key must be a list. extraProps can be used to set user properties that are registered by modules. For example, the SMS module registers a user pin setting, which can be set with the user.pin key: |
User Data Created Manually
When putting together a dictionary manually, you can use some or all of the properties listed in the table above. You can create as many dictionaries of users as you want, adding in as much or as little contact info. Once you have your dictionaries created, you then need to place them in a list. You then need to use that list as the return value, which the pipeline will use to determine who to contact.
# create your user dictionaries
user1 = {"username":"mary", "email":["mary@company.com"]}
user2 = {"username":"john", "firstname":"John", "lastname":"Smith", "email":["john@company.com"], "phone":["1234567890"], "sms":["8905671234"]}
# create a list of the user data
userList = [user1, user2]
# return the user data
return userList
You can use this in conjunction with a database query to dynamically create a list of user information. See below for an example using the Builder.
User Data Created with the Builder
If you opt instead to use the builder, the builder object has a few extra methods that it can use besides what were listed above.
- add() - Adds all previous info as a single dictionary.
- build() - Returns the completed list of dictionaries. The builder object is used by calling consecutive methods on it. Using the same info as the example above, you can add all of the contact info to the builder on a single line.
# Here, we are putting together contact information in our builder using one big string of code.
# Notice that even though it is one long string of code, we are adding both users.
# The first add() at the end of Mary's information acts as a divider between the details, adding hers first.
# The second add() at the end of the code will then add all of John's information.
builder.username("mary").email(['mary@company.com']).add().username('john').firstname('John').lastname('Smith').email(['john@comapny.com']).phone(['1234567890']).sms(['8905671234']).add()
While the above will work just fine, it may be a bit confusing to put together. However, you don't have to add all of the users at once like that. You can instead break it up, making sure to call add at the end of each user's information.
# Here, I still add all of the same contact information to my builder, but this time, I do it in two stages.
# The difference here is that I have to call builder again in the second line when adding John's information.
builder.username("mary").email(['mary@company.com']).add()
builder.username('john').firstname('John').lastname('Smith').email(['john@comapny.com']).phone(['1234567890']).sms(['8905671234']).add()
This can be really useful as it can allow you to add users one at a time, making use of flow control methods like a for loop. You can then use external information, such as database records or Ignition's built in user and security functions to determine who to add.
# This would grab a table from the database that contains a username, email address, and SMS number.
# We must specify the database connection name because this is in the gateway scope.
data = system.db.runQuery("SELECT username, emailaddress, smsnumber FROM user_info_table", "DB")
# loop through the returned query data
for row in data:
# add users to the builder row by row
# note the extra [] in the email and sms functions
builder.username(row["username"]).email([row["emailaddress"]]).sms([row["smsnumber"]]).add()
Once you have all of the appropriate contact information added to the builder, you then call build() on the builder object. This will give us a new built object. We then return our userList as before. Using our example from above:
# get the alarm name property
alarmName = event["name"]
# don't send notification for some alarms
if alarmName in ["Diagnostic Alarm", "Joe's Test Alarm"]:
# return an empty list so no one will be emailed
return []
else:
# get user information from the database
data = system.db.runQuery("SELECT username, emailaddress, smsnumber FROM user_info_table", "DB")
# loop through the returned query data
for row in data:
# add each user to the builder
builder.username(row["username"]).email([row["emailaddress"]]).sms([row["smsnumber"]]).add()
# use the builder object's build() function to create the finished list of data
userList = builder.build()
return userList
if({Group}= "A","Group A","Group B")
Ignore User Schedules
Consolidation
Notification consolidation allows you to limit the number of notifications sent by specifying a delay during which incoming events will be collected. When the delay expires, all events that have arrived during the period of time will be sent together to the notification profile. The manner in which the profile implements consolidation will vary, but in general the result will be a shorter message, or fewer messages, than would have occurred otherwise.
Consolidation is defined with two parameters:
Delay - How long to wait after the first eligible alarm arrives. This setting forces a pause before sending a notification. The delay is used to protect against situations where an event might generate many alarms together. In other words, if an alarm comes into the Notification Block, it will be delayed for this amount of time in case there are other alarms arriving soon.
Frequency - The max frequency with which the profile can send alarms. This setting forces a pause after sending a notification. The frequency is used to ensure that contacts aren't notified too often, for example if an alarm is rapidly going in and out of the active state.
Consolidated Message Property
Some notification settings include a Consolidated Message, which dictates the formatting for the message when consolidation is enabled. This property features a text area that allows you to determine the content of the consolidated message.
While the editor looks like an Expression Editor, it's not, so the normal expression functions and rules do not apply here. Although there is a Property Reference button to the right of the editor that can create references to alarm event properties. Since this isn't an expression, you don't need to wrap string literals in quotation marks.
Since consolidated messages will potentially contain multiple alarms, they utilize some unique syntax: the double curly bracket {{ }} notation. The content within this notation will be repeated for each alarm included in the consolidated notification.
{alarmEvents.Count} alarm events have occurred:
{{Every thing in here will be repeated for each alarm included in the consolidated notification}}
HTML Formatting in Email Notifications
Messages within consolidated messages can use HTML formatting by simply leading with an <html> tag at the start of the message. Doing this by itself does cause the resulting formatting to omit the built-in line breaks, so you will need to add line break tags to signify a new line.
For example, we could add some HTML tags to the initial example on a consolidated message to write the alarm name and display path in bold <b> using the following:
<html>
{alarmEvents.Count} alarm events have occurred: <br>
{{Alarm <b>{name}</b> at <b>{displayPath}</b> transitioned to {eventState} at {eventTime|hh:mm:ss} <br>}}
Which would result in the following body:
