[00:00] In this video, we are going to take a look at how we can make a roster dynamic and an alarm notification pipeline. Let's go ahead and take a look at how they work. I have a notification block here, and if I go over to the contacts tab in the Pipeline Block Editor, you'll see, we have an option to select a roster type. Currently there are three roster types, Direct, Expression, and Calculated. The Direct roster type is by far the simplest. I simply need to select a roster from this dropdown list of On-Call rosters that I've previously set up in the gateway. Once I've made a selection, the notification block will always notify the users in that selected On-Call roster. While this roster type is very easy to use, the trade-off is that it's not very flexible, forcing you to select a single roster to use for this notification block. Next up is the Expression roster type.

[01:03] The Expression roster type allows you to use ignitions built in expression language to select a particular On-Call roster that you're going to use. Because you have the ability to create an expression here, it does offer some amount of flexibility. For example, in my expression here, I'm looking at the priority of the alarm. If it's equal to four, then I want to use the administrators On-Call roster. Otherwise it'll just use the user's On-Call roster. In addition, I also have the ability to use tag values or even any of the built-in expression functions of the expression language. While this roster type is a little bit more complex, it does offer the flexibility you may need to make a dynamic selection for what roster you're going to use for this notification block. However, it still forces you to choose a roster that was created previously. So, if you don't have users that you want notified, grouped into a particular roster, you won't be able to notify them.

[02:03] This forces you to really plan ahead and select what users are going to be notified in certain instances and create a roster for each of them. These limitations led to the third type of roster, the Calculated roster. The Calculated roster allows you to use scripting to create a custom roster at runtime. With it you're essentially building a temporary roster that will be used this one time, during the notification. If a new notification comes in, the script will run again and rebuild a new roster using potentially new parameters. This is perfect if the users that you're notifying change with each new alarm instance, allowing you to truly customize who you're going to be notifying when the alarm event happens. I'm gonna expand the block editor so we can take a closer look at how the script works. Now, the basics of this script is that it needs to return a list of dictionaries. This can be done in one of two ways, either manually by building out a dictionary for each user, putting them into a list and then returning them or using the built in builder object.

[03:09] Let's first take a look at the example down here that puts together a list of dictionaries manually. As you can see, it first creates two different user dictionaries, it then places those dictionaries into a list, and then it returns that list of dictionaries. It's important to note that the key value pairs that you build your user dictionaries with, must match the key value pairs that are listed here in the description. You can put together as many different users as you like, and you'll also notice that each user does not have to have the same type of information. As the user, Bob has a phone number while the user, Joe has an email address. Now, let's take a look at how you could use our builder object instead. I've put together an example that uses the same information from the manual example. You'll notice that this time we're calling methods of the builder object to insert in information for each user.

[04:04] Then once we have all the users appropriate information, we call the add method on that builder object. This adds all previously added information as a single user into the builder. I can add as many different users as I would like, again, even using different types of information, such as a phone number or an email address. It's important to know that the methods of the builder object that I'm calling must match the keys listed above, while the parameter values that get passed in must match the data type associated with the corresponding key. So, for example, the phone number is expecting a list of strings. So, when I call the phone method, I have to pass it a list of strings for the phone number, even if there is only one phone number there. Once I've added all the appropriate users, I then call.build on the builder object. This will return the same list of dictionaries that I'd previously built using the manual method. I then simply need to return that list of dictionaries to finish my script.

[05:07] You may have noticed that there's a couple of different ways that we can use the builder object, such as in my example, where I've broken it up into multiple lines, or like within the description, where it's all on one line. Both of these will yield the same results and I recommend you check out the user manual for more information on how to use both the builder method and the manual method. Now, It's important to note that the examples I've shown here are fairly simple, with just a couple of static users that I'm returning. However, it's not recommended that you use the calculated roster like this, as it would just be easier to build a roster for them in the gateway, and then select that roster as a direct roster. Ideally, we would use scripting here to grab various bits of information such as from the database or even tags. And then you use that information to build a very customized roster from various user sources. This helps to ensure you are notifying exactly who you need to.

[06:03] The last thing I wanna point out is that both the manual method and the builder method achieve a similar result, which is to create a list of dictionaries. This means that you can use whichever one feels more comfortable for you so that you can build the best script possible. So, with these three roster types, you can put together a notification pipeline that sends out alarm notifications to exactly who they're intended for.