4.3.15.10. Trigger Action System

IRM includes a Trigger Action System, which is a general-purpose mechanism for automatically recognizing a condition of interest (the trigger) and taking an action as a result. One of the areas that this system is most useful for is integrating IRM with third-party software. The Trigger Action system is meant to generate alerts to IRM Users, or notify external systems about some change in the IRM system. In some ways it resembles the Analytics system, with the key differences that Analytics is controlled via states and produces visual outputs, whereas Trigger Action is controlled by events and produces alerts such as emails and notifications.

Note: This topic introduces various features and concepts related to the Trigger Action System, while the following sub-topic explains how these can be used through a step-by-step use case scenario.

A Trigger Action object is defined for a single Category of objects and is specified by the following properties

Name
Owner (IRM User who created it)
Condition(s), evaluated based on a
targeted field value
Operation, which specifies the type of the field value update
optional Value(s), only for certain Operations
Action(s) which should be performed if the Conditions have been met
A batch handling strategy which defines actions in cases where the same Trigger Action is activated for many objects

Additional options that can be defined for a Trigger Action object:

Is Public? property sets the Trigger Action either visible only to the owner or shared with other IRM users
Fallback Trigger Action -an existing Trigger Action defined for the same target Category, which triggers in case an attempt to execute an action fails

The following are additional explanation of these and additional Trigger Action features.

Trigger varieties

A Value Trigger waits for a set of conditions to be satisfied for a single object type. When the last trigger condition(s), which weren't previously met, become met, the specified action (or multiple actions) is taken. That is, what causes a trigger to activate is not that the condition is met, but that the condition becomes met after it previously wasn't met. After a trigger is activated, it will not continuously re-activate even if the conditions remain satisfied. That is why we describe a trigger as "event-driven" rather than "state-driven".

For example, the user can define an Equipment trigger with the following conditions:

is Rack == true

Fraction Occupied Total > 0.9

Location Alternate Name == “DC1”.

This means that if a Rack in the DC1 Location had its Fraction Occupied Total increase from 0.85 to 0.95, the trigger condition would be met and the corresponding action(s) would be taken.

An Explicit Trigger is triggered explicitly by one of the following means:

failure of an Action for some other Trigger Action after retries are exhausted -- this is a fallback Trigger Action
by software external to IRM calling an IRM REST API

Trigger Conditions

Trigger Conditions can be set against any of the following field types:

Field type	Applicable Condition Operations ("If field value")
Numeric fields (int, float, Length, RU, Weight, Data Rate, Heat, Watts, Amps, Volts, VA, Utilization, Currency)	Becomes greater than Becomes less than Becomes equal to Becomes not equal to Changes (any change)
String	Becomes equal to Becomes not equal to Changes (any change)
Enumerated value	Becomes equal to Becomes not equal to Changes (any change) Changes from A to B

If a Trigger has multiple Conditions, only one has to transition to being met for the Action to be taken, as long as the other Conditions currently meet their target Values. On the other hand, the "Any Change" Condition Operation is considered to have its target value met only if the field its specified upon is having its value changed.

In the previously mentioned example, "is Rack" and "Location Alternate Name" fields would not normally change their value, but a Trigger with the "Any Change" Condition would activate exactly once whenever Fraction Occupied Total changed from less than or equal to 0.9 to greater than 0.9.

Trigger Action Time state

Every time the object (of the targeted Category) is updated, the Conditions for that object need to be evaluated:

first, whether the Conditions are already met immediately previous to this update (in which case the Action should not be taken), and
second, whether the Conditions are met after the update.

This is done by maintaining a trigger-related state for each (Managed) object, the Trigger Action Time, which is used as a flag to indicate that the Trigger Action was activated when the object was last updated.

Trigger Action Time includes:

a reference to a Trigger Action object
the Time of the Last Trigger
Trigger count

For example, an Equipment Trigger Action is defined for Equipment object of the target Category with the Trigger Action Times list initially empty. Next, the following sequence happens:

An Equipment object is updated such that it now meets the trigger conditions. Because the Trigger Action Times list for this object doesn't contain any Trigger Action, the Actions specified for that Trigger Action are all taken and the Trigger Action is added to Equipment's Trigger Action Times list.
The Equipment is updated again. Since the Trigger Action is already in the Equipment's Trigger Action Times list, no actions are taken and Equipment’s Conditions are only evaluated once, against the new state of Equipment. If the Conditions are still met, nothing happens, but if they are no longer met, the Trigger Action is removed from the Equipment's Trigger Action Times list. If the Trigger Action is no longer on Equipment's Trigger Action Times state due to the previous step and if the Equipment is updated again, the original state is back and the Trigger Action can be triggered by Equipment if the Conditions are met after the update.

To prevent a Trigger Action from triggering over and over again by the same object due to the oscillation of a value in some of its field(s), the information about when the Trigger Action was last triggered by the targeted object is maintained as Time of the Last Triggered property, as part of the Trigger Action Time state. Then, if Trigger Action is re-triggered by the targeted object before the minimum re-trigger time has passed (defined for the Trigger Action object), no actions are taken and instead the appropriate number of triggers (from the Trigger Action Time state) is incremented. In other words, the Trigger Action system has hysteresis that prevents it from triggering repeatedly if a condition quickly transitions across its threshold value.

Trigger Actions

The following types of Actions are supported:

Sending an email - by specifying the email address, subject of the email and email body with the field references
Sending an IRM Notification (an in-app instant message) - by specifying the IRM Users to notify
Sending an HTTP request - by specifying the type (POST / PUT / PATCH), URL, body and header of the HTTP request, which is useful for integrations with other software

Fallback Trigger Action

If an attempt to execute an Action fails, IRM will retry the operation twice more, after a delay of one minute. If the operation fails all three times, and the Fallback Trigger Action is specified, this fallback Trigger Action is triggered. In order for this to work, the fallback Trigger Action must be in the same Super Category as the failing Trigger Action and must have the same context as the failed Trigger Action.

Batch processing

Because it is possible that an IRM batch update operation causes the same Trigger Action to be activated by many objects (possibly thousands or many thousands), the following batch handling strategies are supported:

Process All - each batch item triggers its own actions if the Conditions are met. Note: This can be dangerous if a large batch size is encountered, so it is not the default. Please use cautiously, as this can lead to poor system performance.
First Only - allows only the first object in a batch that activates a Trigger Action to run Actions. The rest of the batched objects are ignored for purposes of that Trigger Action. This option is the safest, as a batch update can only cause each Trigger Action to be activated at most once.
Consolidate - each object in the batch generates a separate Action value that gets added to a list, with a individual Action taken only once for the entire list. This option is less dangerous than Process All, but still problematic if thousands or more objects activate the Trigger Action, because of the length of the list.

Note that if either the Process All or Consolidate strategy is used and a very large update happens, the IRM server may not process all such Actions due to hard limits built into the server. This is done in order to prevent the server from becoming unresponsive in the case of such a very large operation.

Action Logs