Triggers and Actions

Triggers and Actions

While they are two separate things, triggers and actions work together. There is no point in only having one without the other. A trigger and action are like a sentence such as:

For example, you may light to send an email if an interface for a particular host goes down, the sentence would read:

Triggers are part of the system for JFFNMS to send out notifications when certain specific things happen. The most common example of a trigger is JFFNMS sending an email when either an event or alarm occurs.

To setup a trigger, there are a few steps involved, this chapter will explain what those steps are and how to get triggers working. In brief, they steps are:

1. Create the trigger, that is a container to hold the rules
2. Define the trigger by adding trigger rules
3. Optionally, create a new action or decide which existing action you will use
4. Add the trigger to a user

Creating Triggers

You can see the current list of triggers with the Administration menu item Internal Configuration => Triggers & Filters => Triggers Configuration. This will bring up a table of triggers.

Each trigger has a small description and a Type field which determines if the trigger works off an event or an alarm. Generally it is better to work off an alarm because they have a more definite state but it is really dependent on what the trigger is for.

Trigger Rules

In each row of the trigger table is a View Rules link. Clicking on this link brings up the rules that are used to evaluate the trigger. Table * explains what each column in the trigger rules table does.

You will be unable to edit all the fields in one go as some are dependent on others. You cannot edit the Value column until the Field column is selected. You cannot edit the Action Parameters until the action is selected.

Currently the only action is Send Email. Actions are defined in the Actions table but also need to be created in the code.

The Boolean at the end can be used so that the trigger will fire only if all rules match or if one of them does. The AND and OR can be used in combination with care. For example to fire the trigger if condition A and either B or C are true you would set the rules up like:

However to fire the trigger if A happens or if B and C happen, then the table would be reconstructed like this

Actions

Actions need to be defined in this table as well as created in the code. The action Description is referenced by the Trigger Rules and gives a name of what the action is trying to do. The command is used by the code to load the engine/actions/commandname.inc.php file and call the action_commandname() function.

Actions are define in the table found in the Administration menu Internal Configuration => Triggers & Filters => Actions Definition. The table described in Table * appears.

The Parameters can have tokens in them, so JFFNMS can fill in some specific details about the alarm or event that trigged the action. The tokens are written as "<object-parameter>. For example, to print the hostname of an interface, you would put "<interface-host_name>". The objects are interface, action and event. The parameters are found Common Parameters section.

To see how the various Parameter fields work together, consider the email action. It requires input from the user for each trigger that uses that action. The input is the subject and a comment. The User Parameters field is "subject:Subject,comment:Comment" meaning there will be two fields with the labels Subject and Comment and the email action will receive the value of those fields in the array value parameters[`subject'] and parameters['comment'].

Putting it all together

OK, so now we have talked about Triggers and Actions, it is time to use an example to get a trigger working. The important points to consider are the start and end of the whole process, in other words what do you want to trigger off and what action.

In this example, assume you want to send an email any time a host called Claymore has an interface changing state. The following shows what is required.

1. Bring up the Triggers table by selecting Administration menu item Internal Configuration => Triggers & Filters => Triggers Configuration.
2. Click Add at the top of the Triggers table, a new Trigger row opens in edit mode.
3. Enter "Claymore Interfaces" as the trigger Description
4. Make sure "Match Alarms" is selected for the Type
5. Click the Save button.
6. The Triggers table show be redisplayed with the new Trigger you have just created, now it is time to enter in the rules.
7. Click "View Rules" on the line showing the Trigger, a Triggers Rules table appears below the Triggers table.
8. Click Add from the Triggers Rules table, a new Trigger Rule row opens in edit mode.
9. Change the Field column (the second one) to Host and then click Save. You have to edit the row twice to get the list of Hosts. Leave everything else the same.
10. Click edit for the Trigger row, the row now changes to edit mode.
11. Choose the Host called Claymore from the list in the Value column.
12. Check that Action column is "No Action" and the last column is "AND". If so click the Save button.
13. Click the Add from the Triggers Rules table, yet another new Trigger Rule opens in edit mode.
14. Change the Position column to 20.
15. Change the Field column to Type, this means we will be matching on Alarm type.
16. Change Action to "Send Email", the parameters are not shown at the moment.
17. Change "if Match" column to "Stop this Trigger".
18. Click on the Save button, the Value and Parameters columns change because the Field and Action were changed respectively.
19. Click on the Edit button for the row just created (Position 20).
20. Select "Interface Protocol" from the Value column.
21. Put in some values in the Parameters column, perhaps giving some information about this host.
22. Click Save

You now have a new Trigger which will send email if an interface on the host Claymore changes state. Your screen should look something like Figure *.

Next you have to tell JFFNMS who will be getting these emails and what their email address is. First of all, make sure that the user has an email address set. This is done in the User Profiles Table by entering in the user's email address in the eMail option.

Next you need to apply the trigger to the user, this is explained in the User Triggers section, more specifically the part about adding a new trigger for a user. Your newly created trigger should be in the list of available triggers when you click on the Add button.

Deactivating Triggers

There are times when you will need to undertake maintenance on some of your networking equipment. At those times you probably do not want to send alarms for an interface dropping because you have unplugged it, for example. This is especially so if the work is at night and the support engineer is asleep!

Deactivating Triggers is done by removing the active flag for that trigger, applied to a specific user. There is currently no simple way of disabling a Trigger for all users, or even all Triggers for a specific user.

The User Trigger table is accessed via the Administration menu item User and Customers => Triggers Users. The far-right column is labelled Active. If there is a tick-box in that column for that particular User/Trigger row, then that User will get the notification if that Trigger fires.

Deactivating a Trigger for an User is a reasonably simple excercise:

1. Bring up the User Trigger table by selecting Administration menu item User and Customers => Triggers Users.
2. Find the relevant row for the User and Trigger Pair.
3. Click on the Edit button, the row re-appears in edit mode.
4. Un-check the Active column so the tick disappears.
5. Click the Save button, the row reappears in view mode.

To re-activate the Trigger, follow the above process only ensure that the Active column has a tick in it.

Trigger Logs

If you have logging/debugging enabled, then the trigger log will display JFFNMS evaluating the trigger for each alarm or event. For each alarm raised, each trigger is evaluated. Triggers that match the alarm then cause actions to happen. A sample log is shown below.

19:10:22 ==================================================
19:10:22 alarm 16:      T 3 - P 10 - R 3        If 'interface_host(2) = 3' (0)
Stop
19:10:22 alarm 16: --------------------------------------------------------------------------------
19:10:22 alarm 16:      T 4 - P 10 - R 5        If 'any' (1)    Then email (1)

Each line shows, from left to right: localtime, alarm id, Trigger id, Position of rule in trigger group, id of trigger rule, then the evaluation.

Alarm 16 has been raised (this is just the alarms internal ID). There are two triggers defined, one with Trigger ID 3 and one with 4.

Trigger 3 has its first rule at position 10, which is rule number 3. This rule tries to match the host. It wants to match to host with id 2, but the alarm is for host 3, therefore it is not a match (the "(0)"). In addition the rule says to stop evaulating for this trigger.

Trigger 4 is rather simple, if there is something in the alarm, it is a match. Naturally this is only a test alarm. As there is a match, the action is Then performed, which was the email action. The email action returned 1, which means it was successfull.

Tools

The tools are links that can be found on the expanded view of the events table. Clicking on the flashing light or tick icon will expand the relevant event.

A tool consists of a description, an URL, an optional image for an icon and a filter. The URL can have the usual macros, e.g. <interface_id>. The filter is the same set as the express filters used on the events viewer itself.

Triggers and Actions