Configuring notification priority based on event severity

This article explains how to configure an incoming token (or predicate) so that it maps to the Priority Threshold settings in xMatters.

When configuring Devices in xMatters, you can specify a Priority Threshold that determines what kind of Alerts can be delivered to that Device: High priority Alerts, Medium and High priority Alerts, or Alerts of all priority levels (for more information about configuring Devices, refer to the xMatters user guide).

This article explains how to configure an incoming token (or predicate) so that it maps to the Priority Threshold settings in xMatters. The steps below provide an example of the process, illustrating how to add priority to messages sent using the default Quick Message panel and the messaging Event Domain.

Adding priority to messages

To add priority to messages, you must edit the Script Package for the messaging Event Domain, and add a list predicate so Users can specify their message's severity. The severity specified by the User will then map to the different priority levels in xMatters.

To edit the Business Script Package:

    1. Open your Developer IDE, and check out your Company scripts.
    2. Expand the messaging (BUSINESS) Script Package, and double-click the initial script to open it in the Scripting pane.
    3. In the initial script, locate the following section, which configures the default settings for the messages:
# Setup defaults for use within this script.  
@alert::setHandlerScript("response")  
@alert::setPresentationScript("messaging")  
@alert::setTimeOverride(FALSE)  
@alert::setEmergencyDeviceUsage(FALSE)  

    1. Add the following code within the section illustrated above to set the default priority ("LOW"), and to specify which severity levels map to the three priority levels:
@alert::setEventPriority("LOW")  
if (EXISTS ($event.severity))  
 if ($event.severity == "Critical")  
 @alert::setEventPriority("HIGH")  
 else-if ($event.severity == "Major")  
 @alert::setEventPriority("MEDIUM")  
 endif  
endif
  1. To commit your changes, save your workspace (File > Save), validate your changes (Workspace > Validate), and check in the script package (Database > Check In).

To add a predicate to the Event Domain:

  1. Log in to xMatters as a Company Administrator, and then click the Developer tab.
  2. In the Event Domains list, click messaging.
  3. On the Event Domain Details page, above the Predicates table, click the Add New link.
  4. On the Event Domain Predicates page, type the following information into the form:
    • Predicate Name: Severity
    • Type: List
  5. In the New List Value field, type Critical, and then click Add List Value.
  6. Repeat step 5 to add two more values, "Major" and "Minor".
  7. Click Save.
  8. Click the Messaging tab, and note the new Severity drop-down list in the Message area.

Users can now specify a Severity level for their Quick Messages. xMatters will treat all "Critical" messages as HIGH priority events, and all "Major" messages as MEDIUM priority events. "Minor" messages, and messages without a specified Severity, will be treated as LOW priority.

Adding priority to alerts

To add priority to Alerts, the relevant Event Domain's initial script must be changed to set the Alert priority and a severity token must be added to the injected events. In the messaging Event Domain example above, the severity token is added to the Quick Message panel and specified by the User sending the message. Most management system integrations, however, inject events programmatically via the integration agent, and require the following steps to add priority to the resulting Alerts:

  1. Include the management system's severity level in the data map tokens it submits to the integration.
  2. Edit the integration's configuration to store the management system's severity level as the value of the severity token in the event that the integration injects in xMatters.
  3. Edit the integration's initial script to map the management system's severity levels to corresponding Alert priorities.

The specifics of each step vary between Integrations; as an example, the following steps use the default integration included with Java Client and configured using the\etc\integrations\default.xml file.

Step 1 - Configure the management system to include the severity level

The requirements for this will depend on your integration; consult the integration guide included in the archive for more information.

Step 2 - Map the severity level to an event token

After modifying the management system include the severity level, add the parameter to the default integration's data map:

<mapped-input method="add" subclass="action">  
 <parameter index="1" type="string">person_or_group_id</parameter>  
 <parameter index="2" type="string">situation</parameter>  
 <parameter index="3" type="string">device</parameter>  
<--! +++++++ parameter below added for severity +++++++ -->  
 <parameter index="4" type="string">severity</parameter>  
 <parameter index="5" type="string">incident_id</parameter>  
 <parameter index="6" type="string">contact_type</parameter>  
 </mapped-input>  

For more information about data mapping in the integration agent, refer to the xMatters integration agent guide.

Step 3 - Map the severity level to an Alert priority

For the severity levels to be mapped to corresponding Alert priorities, you must change the default Script Package in a similar fashion to the messaging Event Domain example above. Add the following code to the default (BUSINESS) > PROCESS > initial script:

@alert::setEventPriority("LOW")  
if (EXISTS ($event.severity))  
 if ($event.severity == "Critical")  
 @alert::setEventPriority("HIGH")  
 else-if ($event.severity == "Urgent")  
 @alert::setEventPriority("MEDIUM")  
 else-if ($event.severity == "Important")  
 @alert::setEventPriority("MEDIUM")  
 else-if ($event.severity == "Information")  
 @alert::setEventPriority("LOW")  
 endif  
endif  

Note how mapping management system severity levels to Alert priorities differs from the message Event Domain example. Each management system may define its own severity levels, so its corresponding initial script must be customized to handle the expected values. Additionally, a management system may have to map several severity levels to a single Alert priority. In this example, the Urgent and Important severity levels are both mapped to the MEDIUM Alert priority.

xMatters Reference

JDN-2075 Originally created by Don Clark

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.
Powered by Zendesk