Macros Reference

This is a reference guide for the macros you can use with automation integrations. Macros enable you to change the content of an event attribute so that the end value is either a conversion, or contains additional information. You configure macros as mapping rules in an automation integration's UI. See Configure Payload Mapping Rules for more information on mapping rules.

In the Rule field, use the format $<macro>(attribute). For example, $TO_INT(alert_id).

TO_INT

Converts a strings value to an integer. You can use this macro to convert alert or Situation IDs, severities, or timestamps.

Example

  • Name: AlertID

  • Rule: $TO_INT(alert_id)

Converts an alert_id of "99" to 99:

{
    AlertID : 99
}

TO_STRING

Converts an array, object, number, or boolean, to a string.

Example

  • Name: Severity

  • Rule: $TO_STRING(severity)

Converts a severity value of 5 to "5":

{
    Severity: "5"
}

Note

If you are already using the TO_JSON macro or another compound value macro, do not use TO_STRING. Quote the value you need. For example, $TO_JSON( { "alert_id" : "$(alert_id)" }), as opposed to $TO_JSON( { "alert_id" : $TO_STRING(alert_id) })

TO_DATE

Converts an epoch time, or any number, to an ISO format date.

Example

  • Name: Date

  • Rule: $TO_DATE(first_event_time)

Converts a first_event_time of 1582020352 to a human readable string:

{
    Date : 2020-02-18T10:05:52.000Z
}

TO_JSON

Converts the final values within a rule to a JSON object. This is the only macro which can contain other macros, and enables you to create a final object from other compound or constructed objects.

Example 1

Your receiving system expects an object that contains the following details:

  • A top level object of alert_id, severity, and description.

  • A location object which contains the city and country associated with the alert (taken from enrichment data held in custom info).

Set the following for the top level object:

  • Name: alert_id

    Rule: $TO_INT(alert_id)

  • Name: severity

    Rule: $TO_INT(severity)

  • Name: description

    Rule: $(description)

You do not need to perform any additional conversion on the top level object. However, you must configure the location object as a valid JSON object and not a string.

Set the following. Note that you must enclose compound or constructed objects in braces "{}" or square brackets "[]":

  • Name: location

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

These rules take the final values the macro substitutes, and uses the standard JSON.parse() JavaScript function to convert the values to a JSON object.

This produces the following JSON object inside the payload object:

{
    alert_id: 92,
    severity: 5,
    description: 'switch down',
    location: { 
        city: 'London', 
        country: 'UK' 
    }
}

Example 2

You typically use TO_JSON to create compound or constructed objects, and you do not need to convert values that are already objects. For example, $custom_info and $TO_JSON(custom_info) produce the same result. However, you can also use this macro to create key:value pairs and lists.

For example, you want to produce the same top level object as Example 1, but this time you want to create a list (array) from the location data. Set the following:

  • Name: location

  • Rule: $TO_JSON([ "$(custom_info.location.country)" , "$(custom_info.location.city)" ])

This produces the following payload:

{
    alert_id: 97,
    severity: 5,
    description: 'switch down',
    location: [ 'UK', 'London' ]
}

Example 3

TO_JSON allows you to nest macros within it. This allows you, for example, to add timestamps to your object. Set the following:

  • Name: timings

  • Rule: $TO_JSON( { "first" : "$TO_DATE(first_event_time)", "last" : "$TO_DATE(last_event_time)" })1

With the same top level object as Example 1, this produces the following payload:

{
    alert_id: 99,
    severity: 5,
    description: 'switch down',
    location: { country: 'UK', city: 'London' },
    timings: {
      first: '2020-02-18T11:10:00.000Z',
      last: '2020-02-18T11:11:30.000Z'
    }
}

TO_BOOLEAN

Converts true/false indicators to a native boolean.

Maps from the following strings: "true", "false", "yes", "no", "0", "1".

Maps from the following integers: 0, 1.

Example

  • Name: isBranch

  • Rule: $TO_BOOLEAN(custom_info.isBranch)

Converts the string isBranch with a value of "1" to true:

{
    isBranch: true
}

Expand

Converts an enumerated value into the corresponding human readable string. Only works on specific alert and Situation fields. Any other field returns the original value.

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 table below details the supported fields.

Field Name

Input Type

Expanded Value

severity (alerts)

internal_priority (Situations)

Integer

Converts the numeric severity to the human readable value. For example "5" to "Critical".

state (alerts)

status (Situations)

Integer

Converts the numeric state to the human readable value. For example "9" to "Closed".

services

service_list

impacted_services

List of service IDs.

For example, [1, 2, 3].

Converts the list of impacted service IDs to a list of the service names. For example: [ “network”, “customerSat”, “ABCD” ].

processes

process_lists

impacted_processes

List of process IDs.

For example, [1, 2, 3].

Converts the list of impacted processes to a list of the process names. For example: [ “process1” , “process2” , “process3 ].

teams

List of team IDs.

For example, [1, 2, 3].

Converts the list of team IDs into a list of team names. For example: [ “Cloud”, “Server” , “Network” ]

owner (alerts)

Integer (user ID of the owner)

Converts the user ID of the owner to their username.

moderator_id (Situations)

Integer (user ID of the owner)

Converts the user ID of the moderator to their username.

prc (Situations)

N/A

The top Probable Root Cause alert for the Situation returned from the getTopPrcDetails API call. If you use this in an alert map the value returns null.

Example

The following Situation payload map contains default input types:

{ 
    "id" : $TO_INT(sig_id),
    "severity" : $(internal_priority),
    "description" : "$(description)",
    "services" : $(services),
    "teams" : $(teams),
    "moderator" : $(moderator_id)
}

This produces the following payload:

{
    id: 23,
    severity: 5,
    description: 'Alerts with a similar description ',
    services: null,
    teams: [ 1 ],
    moderator: 2
}

To convert numerical values to human readable values, use the EXPAND macro:

{ 
    "id" : $TO_INT(sig_id),
    "severity" : $EXPAND(internal_priority),
    "description" : "$(description)",
    "services" : $EXPAND(services),
    "teams" : $EXPAND(teams),
    "moderator" : $EXPAND(moderator_id)
}

The relevant substitutions convert to the corresponding human readable values, so that the payload becomes:

{
    id: 23,
    severity: 'Critical',
    description: 'Alerts with a similar description ',
    services: [ 'email', 'network' ],
    teams: [ 'Cloud DevOps' ],
    moderator: 'admin'
}

CONTEXT_URL

The following macros create context-launchable URLs for alerts and Situations, which open an alert list or Situation Room for the in-scope alert or Situation:

  • ALERT_URL

  • SIG_URL, SITN_URL, SITUATION_URL

Unlike other macros, these macros do not take object values as parameters. Instead, they take either:

  • A webhost name. For example, myServer, https://myserver.

  • A directive to read a configuration file to find a webhost. This is only valid if the local servlets.conf file contains the correct webhost. If you have a distributed installation of Moogsoft AIOps, you must configure the webhost in servlets.conf on the Core server.

Example 1

The following configuration provides a hardcoded webhost:

  • Name: MyHost

  • Rule: $SITUATION_URL(https://myHost)

In this form, the rule uses the host name to construct the URL.

For a Situation with an ID of 30, this produces the following payload:

{
    MyHost: "https://myHost/#/situations?filtereditor=advanced&filter-query='id'=30",
}

Example 2

The following configuration uses the format $MACRO(config[filename][<attribute>]) to read the webhost from servlets.conf:

  • Name: MyConfig

  • Rule: $SITUATION_URL(config[sevlets.conf][webhost])

If the rule finds the attribute, it passes the attribute's value to the macro. You can use this format to read other values. For example, with $(config[moog_farmd.conf][config.threads]).

For a Situation with an ID of 30, this produces the following payload:

{
    MyConfig: "https://moogga/#/situations?filtereditor=advanced&filter-query='id'=30"
}