Thursday, December 12, 2013

How To Filter Alarms on Static Associated Data

First of all, I want to say sorry for neglecting the blog since January. Starting this week, I want to post a new blog entry once a week. So stay tuned for new and exciting tips and tricks for Ignition.

For this post, I want to show how you can filter alarms on the alarm status component, alarm journal component, and in alarm notification pipelines through the use of static associated data.

Ignition 7.6 introduced a host of new alarming features; one such feature is the ability to add "Associated Data" to an alarm configuration. Associated data are custom alarm properties that can be added to any alarm. The values can either be static or dynamic. Dynamic properties will often be bound to other tags that represent associated contextual data that may be related to the alarm. Either way, a snapshot of the values of these properties will be taken when the alarm becomes active. These values will be attached to the alarm event as it moves through the rest of the alarming system, meaning that the values will be available from the alarm status system, the alarm journal system, and in the alarm notification system.

Let's assume you already have a couple of alarms configured. It's easy to go back to the alarms and add associated data. Edit one of your alarm tags and go to the alarm configuration area. Select one of the alarms. Of course you will see all of the alarm properties that you have previously configured. Those properties come with every single alarm. We can add our own properties called "Associated Data."

To add associated data simple click on the green plus icon right above the alarm properties (in the top right).

That will add a new property at the bottom of the list. By default the property will be called "New Data."

To rename the property simple double click on the name and type in a new one. Let's call the property "Group." At this point, we can either type in a static value for the property or make it dynamic by linking it to another tag or an expression. Dynamic associated data is important to snapshot other tag values along with the alarm. That way you can go back in time and see what the temperature of the room was or what happened upstream or downstream when the alarm occurred. If we simply just type in a static value than it will never change, allowing us to use it in filtering.

Go ahead and set the value of the property for the first tag to "Group A" and press OK to save. Do the same thing for other alarm we have configured and set the property to "Group B."

If your tag has more than one alarm configuration make sure you add the associated data to each one. Every alarm configuration can have a different set of values.

At this moment we have 2 alarm tags with one tag set to "Group A" and other tag set to "Group B." Let's look at how we can filter for a particular group on the alarm status component. 

Drag the alarm status component onto a window. You will notice it shows every single alarm that is active right now. So both of our alarms are showing up.

To add the filter, right click on the component and select "Scripting." On the left hand side you will see the component's "Extension Functions." Extension functions allow you to hook into the component providing a way to override/implement parts of the functionality of the component. There is an extension function on the alarm status component called "filterAlarm" which allows you to filter the alarms any way you want through the use of scripting. Go ahead and select the filterAlarm extension function.

Set the "Enabled" checkbox to true and the script will become active. The filterAlarm function will get called for every single alarm that would normally show up in the component. You will return True if you want the alarm to show up and False if you don't. The alarms that would "normally" show up are based on the filters you can put on the alarm status component, such as minimum priority or alarm state (active and unacked, active and acked, clear and unacked, clear and acked). Typically you would allow the component to bring back everything and you would filter them out in the filterAlarm extension function.

The filterAlarm extension function automatically gives you a variable called alarmEvent, which has a function called get to retrieve any property of the alarm such as the name, source, priority, or our associated data. So, if we only want to show alarms for "Group A" we can put in the following script:

group = alarmEvent.get("Group")
if group == "Group A":
return True
return False

Now we only see one alarm.

Typically you won't hardcode the group name in the script. Usually it comes from a property on the window like a drop down list or value passed into the window. If you want to grab a value from the screen you can use the self variable just like the event.source variable in event handlers. The example below gets a value passed into the window on the root container:

group = alarmEvent.get("Group")
groupName = self.parent.groupName
if group == groupName:
return True
return False

Notice the second line that goes to the parent (root container) and grabs the groupName property. We than use that variable in the if statement.

If you want to filter on the alarm journal component, it is exactly the same as the alarm status component. The alarm journal component also has the filterAlarm extension function. 

Lastly, I want to show how you could use the associated data in an alarm notification pipeline. That way you can do something different for each group like notifying a different list of people.

Go ahead and add a new alarm pipeline in the designer. First drag in the "Switch" block into the pipeline. The switch block is very similar to the expression block, except that the result of the expression does not need to be a boolean. Instead, it can be a number or string, and it will be looked up against the defined list of expected results. If a match is found, the alarm will follow that path, otherwise the "catch all" output will be used. You can simply set the expression to:


Below the expression, add two values to the list: one for "Group A" and one for "Group B."

Now you have two paths on the block that can do different logic if the alarm is in "Group A" or "Group B." Here is a pipeline that will send out an email to two different lists based on the group (the pipeline will do nothing if the alarm doesn't have a group):

I hope this gives you a good idea of how to use associated data on alarms. They are extremely powerful and they add a lot of flexibility to the alarming system.


  1. Hay, May thanks for this blog, because I want to know about How To Filter Alarms on Static Associated Data, and got it here..... :) I ma was so happy to read your blog and will always follow to blog. For more information:

  2. Hi, you explained the topic very well. The contents has provided meaningful information thanks for sharing info
    Boligalarm uten binding

  3. I just found this blog and have high hopes for it to continue. Keep up the great work, its hard to find good ones. I have added to my favorites. Thank You.
    wake up light