Payload Maps

Note

To configure payload maps, use the Payloads integration, available in Add-ons v1.3.

Payload maps define mapping between an alert or Situation and the keys in a JSON payload. You can configure payload maps for use with Workflow Engine actions. For example, to create a payload that can send alert or Situation data to an external system.

The payload map configuration follows a similar pattern to LAM mapping; a configuration consists of name:rule pairs, and some pairs include an optional data conversion. See Tokenize Source Event Data for more information on LAM mapping.Data Parsing

A payload map can also contain multiple rules. The resulting JSON payload consists of key:value pairs based on these rules.

For example, a map that contains the following:

[ 
    { "name" : "alert number" , "rule" : "$alert_id" , "conversion" : "stringToInt" },
    { "name" : "alert text" , "rule" : "$description" },
    { "name" : "severity" , "rule" : "$severity", "conversion" : "un-enumerate"  },
    { "name" : "categories" , "rule" : "$class : $type" }
]

Produces a simple target payload:

{
    "alert number" : <number>,
    "alert text"  : <text>,
    "severity : <text>
}

Before You Begin

Before you start to set up your integration, ensure you know the following about your payload map:

A Map Name for your payload map. For example, "My REST Mapping".
The keys for your resulting payload. Use these as the rule name.
The values for your resulting payload.
Any default value, if any, you want for a key.
Any difference in the data type of the alert or Situation and the destination payload See Payload Maps for more details on rules.

Configure the Payload Maps Integration

You can configure multiple payload maps from the Payload Maps integration. To configure the integration:

Navigate to the Integrations tab.
Click Payload Maps in the Reporting and Dashboards section.
Provide a unique integration name. You can use the default name or customize the name according to your needs.
Enter the details for each payload map you want to configure.

Configure a Map Name

Specify a name for the payload map. This becomes the key in the payload. In the example above this is alert number, alert text, and severity.

Configure Rules

Rules specify values you want to populate in the payload. A rule can contain any alert attribute including custom_info keys such as custom_info.enrichment.cmdb.location, as well as Situation and compound attributes.

Alert and Situation attributes require a $ prefix to substitute the attributes value into the payload. For example:

A rule of "$alert_id" substitutes the value of alert_id into the payload.
A rule of "alert_id" inputs the string "alert_id" into the payload.

You can use this to create complex compound values which contain both substituted values and text. For example, given the following configuration:

"The alert_id is $alert_id"

The final payload map contains:

"The alert_id is 99"

Add Current Time

To add the current epoch time to the payload, define a mapping rule with a rule which contains $moog_now as a substitution. The value is treated as a string, so if necessary use an appropriate conversion. See the conversion section for details.

Configure Default Values

In certain scenarios the rule is unable to determine a value, for example when the rule contains an alert or Situation field that does not exist. You can configure a default value to use when this occurs. Check Use default and enter a value in the Default field. This field's default value is an empty string. To configure an object as the default value, specify a JSON object (empty lists and arrays are valid), and ensure Conversion is set to string to object.

Configure Conversion

By default all values are created as strings, regardless of the source data type. For example $alert_id, by default, produces a value of "99". If the payload destination is expecting a different data type, you can use the Conversion field to select one of the following conversion methods:

none (string): Keeps the value as a string.
string to number (stringToInt) : Converts a string to an integer. Assumed to be base 10.
string to object (stringToObj) : If the value from the alert or situation (or default value) is a string, converts it to a JSON object.
object to string (objToString) : If the value from the alert or situation is a JSON object, converts it to a single string. Flattens objects.
epoch time to date (epochToDate) : If the value from the alert or situation is a timestamp (or any integer), converts it to a human readable date format. Format is ISO (e.g. 2019-11-25T09:59:30.000Z). Note that the time is based on the server running Moogfarmd and not the event source timezone.
un-enumerate : Reverse the internal enumeration. See the "Un-enumeration" section for more information.

Substitute a human readable string for an enumeration

Some alert and Situation fields require you to express them as numbers rather than a human readable string. One of the most common of these is severity. A severity of 5 indicates "Critical", 4 is "Major", and so on. When you construct a payload, it is useful to send data in this format instead of (or in addition to) the raw integer value.

The un-enumerate conversion allows you convert the following fields:

severity: Converts the numeric severity to the human readable value. For example "5" to "Critical".
internal_priority: Converts the human readable value to the numeric severity. For example "Critical" to "5".
state: Converts the numeric state to the human readable value. For example "9" to "Closed".
status: Converts the human readable value to the numeric state. For example "Closed" to "9".
service_list, services, or impacted services: Converts the list of impacted service IDs to a list of the service names.
process_list, processes, or impacted_processes: Converts the list of impacted processes to a list of the process names.
teams: Converts the list of team IDs into a list of team names.
alert and Situation times: For example first_event_time and created_time. Converts from epoch to the ISO time local to the server.
owner/moderator: Converts the username of the alert/Situation owner.

For example, given the following map:

[
    { "name" : "severity as number" , "rule" : "$alert_id" , "conversion" : "stringToInt" },
    { "name" : "severity" , "rule" : "$severity", "conversion" : "un-enumerate"  }
]

The final payload contains:

{
    "severity as number" : 5,
    "severity : "critical"
}

Un-enumeration also works within a compound field:

[
    { "name" : "severity" , "rule" : "The severity is: $severity", "conversion" : "un-enumerate"  }
]

The final payload now contains:

{
    "severity : "The severity is Critical"
}

After you complete the configuration, you can use payload maps in your workflows. For example, you can use the createPayload function to generate a payload from an alert or Situation. Use the map name from your configuration to when the the workflow action requires the map name.

In this section: