Skip to end of metadata
Go to start of metadata


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.


On this page ...



Notification

The Notification tab allows you to select which Notification profile you would like to use of the ones that 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 each notification. So if your delay 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

SettingDescription
From AddressEmail address used for the From field.
SubjectSubject 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 MessageThe message sent when consolidation is turned on, and more than one alarm is being sent. See the Notification Block#Consolidation 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 CountThe number of retry attempts per email per alarm.  Default is 0.
Retry DelayIntroduces a delay between each email for each alarm. Default is 5.

Voice Settings

SettingDescription
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.  Default is 1.


Delay Between Retries

Introduces a delay between calling each contact, for each alarm. The pipeline dropout conditions are checked regularly between calls and while waiting, so this would provide time for the alarm to drop out before calling the next person. The delay is only enforced after following a "successful" call (a call that was answered). Unanswered or errored calls will move on to the next contact right away.

Caution: Long delays can block other alarms in the call queue.
The delay is applied to all contacts for a particular alarm. The system must have time between each call to hang up properly before dialing again. 
Note: For most phone systems, a delay of at least 1 second is advised.


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

SettingDescription
MessageThe message to use for single events.
Consolidated MessageThe message sent when consolidation is turned on, and more than one alarm is being sent. See the Notification Block#Consolidation section for more details.
Delay Between NotificationAs with voice, a delay between each message sent, to give the recipient time to acknowledge and prevent further notification.
Acknowledge MessageWhen 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 ModeIf 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). 

SettingDescription
From Number

Number from which the alarm notification is sent.

Message

Message to send. Default is " At {eventTime|hh:mm:ss}, alarm "{name}" at "{displayPath}" transitioned to {eventState}." Click the bindingicon to access other alarm properties that can be used to the message.

Consolidated Message

This feature is new in Ignition version 8.1.2
Click here to check out the other new features
The message sent when consolidation is turned on, and more than one alarm is being sent. See the Notification Block#Consolidation 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 NameProperty Display NameDescription
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|hh:mm:ss}
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 setup 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 setup and use, but also the least flexible. Any On Call Roster defined on the Gateway can be used directly. 

IULocgo


Dynamic Rosters

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.


if({Group}= "A","Group A","Group B")

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.

Alarm Properties
# 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"]

Building a Roster

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.

NameDescriptionData Type
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.

String
firstnameA first name for this particular user.String
lastnameA last name for this particular user.String
emailA list of possible email address for the user.List of Strings
phoneA list of possible phone numbers for the user for voice notification purposes.List of Strings
smsA list of possible SMS numbers for the user for SMS notification purposes.List of Strings
extraPropsExtra properties that can be added to a user. This is useful when dealing with any third party functionality.Dictionary of Lists


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.

Manual User List
# 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.

One Big Builder
# 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.

Breaking up the Builder
# 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.

Looping through Users
# 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:

Complete Builder Example
# 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


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. 

Note: 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 <br> 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:




  • No labels