Configure Payload Mapping Rules

You configure payload mapping rules in an automation integration UI. The payload map configuration follows a similar pattern to LAM mapping. A configuration consists of name:rule pairs. The rule is macro enabled to allow you to convert or modify the alert or Situation values.

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

For example, a mapping rule called "location" which contains the following:

{ "city" : "$(custom_info.location.city)", "country" : "$(custom_info.location.country)" }

Produces a simple target payload:

{
  location: '{ "city" : "London", "country" : "UK" }'
}

Configure a map name

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

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.

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.

Macros

The Payloads integration supports the following Macros:

Macro	Function
<empty macro>	No action. For example, `$(alert_id)`.
`TO_INT()`	Ensures the end value is an integer. For example, `$TO_INT(alertid)`.
`TO_STRING()`	Ensures the end value is a string. For example, `$TO_STRING(severity)` is a value of "5" and not 5 for a Critical severity.
`TO_DATE()`	Converts an epoch time value to an ISO string. See the Mozilla documentation for details.
`TO_JSON()`	Converts the final values within a rule to a JSON object. For example: `$TO_JSON({ "alertid" : $TO_INT(alert_id) , "severity" : $EXPAND(severity) })`
`TO_BOOLEAN()`	Converts true/false indicators to boolean true or false.
`EXPAND()`	Converts an enumerated value into the corresponding human readable string. For example, a severity value of “5” to “Critical”.
`CONTEXT_URL`	Creates a context link to the in-scope Situation’s Situation Room.
`ALERT_URL()`	Creates a context link to the in-scope alert in an alert list.

See Macros Reference for more information.

Substitutions

Substitutions allow you to substitute event attributes into the rule text of the payload.

To substitute alert and Situations attributes into the payload, use the format "$(<attribute>)". The integration interprets any other format as a string.

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"

To include a macro in the substitution, use the format "$<macro>(<attribute>)".

The following table provides valid and invalid examples.

Rule	Validity
`$(alert_id)`	Valid: Uses the correct form `"$(<attribute>)"`.
`$alert_id`	Invalid: Does not enclose the attribute within braces.
`$TO_INT(alert_id)`	Valid: Uses the correct form `"$<macro>(<attribute>)"`.
`TO_INT(alert_id)`	Invalid: Does not include the prefix "$".

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, and the default value does not apply to the entire rule.

For example, you have the following rules to substitute "$(custom_info.myValue)":

In the first rule, the only value in Rule is the substitution:
- Name: MyValue
- Rule: $(custom_info.myValue)
  - Use Default: Enabled
- Default: Unknown
In the second rule, Rule contains a compound rule which consists of text, the substitution from the first rule, and $(sig_id):
- Name: MyCompoundValue
- Rule: This is myValue $(custom_info.myValue)$(sig_id)
  - Use Default: Enabled
- Default: Unknown

If custom_info.myValue does not exist, the default value 'Unknown' replaces each individual occurrence, as opposed to overriding the entire rule.

For example, if sig_id is 32, the two rules produce the following payload:

{
    MyValue: 'Unknown',
    MyCompoundValue: 'This is myValue Unknown 32'
}

The rule applies the default value before macro evaluation. For example, given the following rule:

Name: defaultTime
Rule: $TO_DATE(custom_info.epoch)
- Use Default: Enabled
Default: current

If there is no value for "custom_info.epoch", the rule applies "current", and only then applies the $TO_DATE() macro. You can see this in the debug level logging:

 +|ceventMacroMap: Using default value current for custom_info.epoch as no value was found|+
 +|ceventMacroMap: Running TO_DATE on 1582035063|+
 +|ceventMacroMap: Macro TO_DATE returned 2020-02-18T14:11:03.000Z for value 1582035063 for attribute custom_info.epoch|+
 +|Adding:defaultTime, 2020-02-18T14:11:03.000Z|+``

In this section: