> For the complete documentation index, see [llms.txt](https://gsfcorp.gitbook.io/macula/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gsfcorp.gitbook.io/macula/administration-guide-v1.33.0/alarm-escalation-rules.md).
# Alarm Escalation Rules
Alarm escalation rules allow Macula to update alarms automatically if they remain in a specified state for a configured period of time. Use this feature when an alarm requires operator attention and must be escalated if it is not processed in time.
Alarms in Macula are based on bookmarks. For this reason, alarm escalation rules use alarm/bookmark properties, such as resource, severity, workflow state, and inactivity duration, to determine when an alarm must be escalated.
To access alarm escalation rules in Macula Console, open Events & Actions and select Alarm escalation rules from the menu on the left.
#### Add Alarm Escalation Rules
To create an alarm escalation rule:
1. Open *Events & Actions > Alarm escalation rules*.
2. Click + *New* and select *New alarm escalation rule*.
3. Enter the rule title.
4. Make sure *Enable* is selected if the rule should start processing alarms.
5. Select a resource. The resource can be a channel or a channel group.
6. Set the effective date and time. The rule processes existing alarms starting from this date and time.
7. Configure the trigger conditions.
8. Configure one or more escalation actions.
9. Click *OK* to save the rule.
The new rule appears in the Alarm escalation rules list. The list displays the rule title, ID, resource, severity filter, state filter, and effective date.
#### Rule Settings
The following settings are available for an alarm escalation rule:
* *Title*: user-defined rule name.
* *Enable*: enables or disables the rule.
* *Resource*: channel or channel group whose alarms can be processed by the rule.
* *Effective* *from*: date and time when the rule starts processing existing alarms.
#### Trigger Conditions
Trigger conditions define which alarms can be escalated and how long the alarms must remain in the matching condition before the escalation is applied.
The following trigger conditions are available:
* *Trigger severity*: limits the rule to alarms with the selected severity. Available values are Info, Low, Normal, High, Critical, and Unknown.
* *Trigger state*: limits the rule to alarms with the selected workflow state.
* *Inactivity duration*: defines how long the alarm must remain in the trigger state before the rule escalates it.
If a trigger condition is not selected, that condition is not used for matching alarms.
#### Escalation Actions
Escalation actions define how Macula updates the alarm after all trigger conditions match for the configured inactivity duration.
The following escalation actions are available:
* *Target severity*: changes the alarm severity after escalation.
* *Target* *state*: changes the alarm workflow state after escalation.
* *Escalation* *message*: adds an automatic message to the alarm log.
For example, a rule can monitor alarms on the Perimeter channel with Normal severity. If an alarm remains in the selected trigger state for the configured inactivity duration, Macula can change the alarm severity, update its workflow state, and add an escalation message such as "Please review this alarm!"
#### Alarm Escalation Events
Each alarm escalation can generate an event. Use this event in the Events & Actions rules to run any supported action when an alarm is escalated.
To create an alarm escalation event:
1. Open *Events & Actions > Events*.
2. Click + *New* and select *New event.*
3. In the list of available event types, select *Alarm escalation*.
4. Enter the event title
5. In *Source*, select the alarm escalation rule that must trigger the event.
6. Click *OK* to save the event.
If the required alarm escalation rule does not exist yet, click + *New alarm escalation rule* in the source selection dialog and create the rule first.
#### Use Alarm Escalation Events in Rules
After creating the alarm escalation event, connect it to one or more actions in the Events & Actions configurator.
To configure the rule:
1. Open Events & Actions > Rules.
2. Click Open configurator.
3. In the Events pane, select the alarm escalation event.
4. In the *Actions* pane, select the action that must run when the alarm is escalated.
5. Use the arrow buttons to add the event and the action to the rule.
6. Click *OK* to save the rule.
The saved rule appears in the Rules list. The rule uses the alarm escalation rule as the source, the alarm escalation event as the event, and the selected action as the target action.
#### Use Escalation Details in Actions
Actions that support text fields can include event and action data. For example, the *Create bookmark* action provides *Insert field* buttons for the bookmark title and description.
The available fields include event ID, event title, event source ID, event source title, event date and time, event timestamp, action ID, action title, action target, action parameter, \`{ADDITION\_INFORMATION}\`, and \`{VALUE}\`.
Use \`{ADDITION\_INFORMATION}\` when the action text must include alarm details passed by the alarm escalation event. The escalation event can pass alarm/bookmark data such as alarm title, severity, status, and channel title through the additional information value.
For the *Create bookmark* action, you can also configure:
* *Target*: server where the action is available.
* *Bookmark title*: title of the bookmark created by the action.
* *Description*: bookmark description.
* *Severity*: bookmark severity.
* *Request user description*: asks the selected user or user group to enter a description. The request timeout value must be in the range from 5 to 9999999 seconds.
* *Create alarm*: makes the created bookmark appear in the alarm pane of Macula Monitor instances.
* *Time offset*: shifts the bookmark timestamp up to one minute earlier or later than the event time.
