Macros Reference

The following configuration provides a hardcoded webhost:

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",
}

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

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]) would return "10".

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

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

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'
}

EXPAND_AS_CSV has two operations: the EXPAND macro followed by a join on the result. It can be used when the receiver needs a string without the JSON artifacts.

Given the following rules in a Payload:

TeamsAsCSV : $EXPAND_AS_CSV(teams)

The resulting outbound payload value is:

{
     TeamsAsCSV: 'Cloud DevOps,test'
}

EXPAND_AS_STRING has two operations: the EXPAND macro followed by a result stringification. It can be used when the payload receiver needs a string rather than the original JSON object.

Given the following rules in a Payload:

TeamsAsString : $EXPAND_AS_STRING(teams)

The resulting outbound payload value is:

{
    TeamsAsString: '["Cloud DevOps","test"]'
}

Given a source list of:

myList: [ "d" , "g" , "h" , "a" , "z" ]

$FIRST(myList) returns “a”

Sorting is alphanumeric, so a list of mixed data types may produce unexpected results (such as where text and integer values exist in the same list).

Given a deeply nested source object:

{ 
  "key1" : "value 1",
  "key2" : {
    "key4" : "value 4",
    "key5" : {
      "key6" : "value 6"
    }
  },
  "key3" : [ 1, 2, 3, 4, 5 ],
  "key7" : 99
}

The flattened target object is:

{ 
  "key1" : "value 1"
  "key2.key4" : "value 4",
  "key2.key5.key6" : "value 6",
  "key3" : "[1, 2, 3, 4, 5 ]",
  "key7" : 99
}

Note that key3 had an array as a value and, after flattening, this array is now a stringified version of the array.

To include the alert ID and description of the top PRC alert in the Situation description alongside the number of unique hosts:

$UCOUNT(source) hosts affected, Alert $PRC(alert_id) : $PRC(description) is the probable cause.

Which translates to the following JSON:

This produces the following Situation data:

{
    "id" : 47, 
    "description" : "1 hosts affected, Alert : 126 : switch down is the probable cause."
}

You can extract values from the PRC alert and map them to the Situation's custom_info using the standard $MAP[ … ] syntax.

Adding attributes to the Situation custom_info:

$MAP[ $PRC(custom_info.supportGroup,prc.supportGroup) $PRC(alert_id,prc.alert_id) $PRC(description,prc.description) ]

The resulting Situation custom info would be as follows:

custom_info : {
    prc : 
    {  
        "alert_id"  : 129,
        "description" : "switch down",
        "supportGroup" : "Network Ops"
    }
}

The standard $$ syntax is not necessary for either macro since they only return values from single alerts.

The PRC macro can be used within a Payload integration map. The functionality and constraints (e.g. availability of PRC data) are the same as the Situation Labeler macros. However, the Payload macros must be nested.

Rules in a payload map are enclosed by $PRC(…). Other nested macros will be honored and substituted normally. This macro changes the in-scope object from the Situation to the top PRC or reference alert for that rule only (e.g. the switch is only applied to that rule not all rules). For example, an alert that has Situation Export use PRC alert details:

$PRC($EXPAND(severity))

Examples of misusing the PRC macro include:

$(sig_id) has PRC alert id $PRC(alert_id)

$PRC($(alert_id) is the PRC alert in $(sig_id))

In the second example, the sig_id attribute does not exist in the PRC alert, which produces a value of null.

Using the PRC macro alongside the standard macro set:

"rules": [
        {   
            "name": "id",
            "rule": "$(sig_id)",
        },
        {   
            "name": "severity",
            "rule": "$EXPAND(internal_priority)",
        },
        {   
            "name": "prc_details",
            "rule": "$PRC($(alert_id) $(custom_info.supportGroup) $EXPAND(severity) )",
        }
    ]

Results in the following data being exported:

{
  severity: 'Major',
  refDescr: 'switch down',
  id: 51,
  reference_alertId: 136,
  prc_details: '136 Network Ops Major '
}

Details of the reference alert id, class and type severity in the Situation description:

$UCOUNT(source) hosts affected, Alert $REF(alert_id) : a $REF(class) $REF(type) alert was the initiator of the Situation.

This produces the following Situation data:

}
    "id" : 49, 
    "description" : "1 hosts effected, Alert : 132 : a network availability alert was the initiator of the Situation."
}

You can extract values from the reference alert and map them to the Situations custom_info using the standard $MAP[...} syntax.

Adding to Situation custom_info:

$MAP[$REF(custom_info.supportGroup,ref.supportGroup) $REF(alert_id,ref.alert_id) $REF(description,ref.description)  $REF(class,ref.class) $REF(type,ref.type)]

Resulting Situation custom info:

custom_info : {
    ref : 
    {  
        "alert_id" : 136,
        "class" : "network",
        "description" : "switch down",
        "supportGroup" : "Network Ops",
        "type" : "availability"
    }
}

The REF macro can be used within a Payload integration map. The functionality and constraints (e.g. availability of REF data) are the same as the Situation Labeler macros. However, the Payload macros must be nested.

Rules in a payload map are enclosed by $REF(…). Other nested macros will be honored and substituted normally. This macro changes the in-scope object from the Situation to the top REF or reference alert for that rule only (e.g. the switch is only applied to that rule not all rules). For example, an alert that has Situation Export use REF alert details:

$REF($TO_INT(alert_id))

Examples of misusing the REF macro include:

$(sig_id) has REF alert id $REF(alert_id)

$REF($(alert_id) is the REF alert in $(sig_id))

In the second example, the sig_id attribute does not exist in the REF alert, which produces a value of null.

Using the REF macro alongside the standard macro set:

"rules": [
        {   
            "name": "id",
            "rule": "$(sig_id)",
        },
        {   
            "name": "severity",
            "rule": "$EXPAND(internal_priority)",
        },
        {   
            "name": "refDescr",
            "rule": "$REF($(description))",
        },
        {   
            "name": "reference_alertId",
            "rule": "$REF($TO_INT(alert_id))",
        }
    ]

Results in the following data being exported:

{
  severity: 'Major',
  refDescr: 'switch down',
  id: 51,
  reference_alertId: 136,
  prc_details: '136 Network Ops Major '
}

$Severity(5): Converts the value "5" to "Critical."

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

{
    isBranch: true
}

would produce the following payload:

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

In this case, "isBranch" is treated as a string.

Using the $TO_BOOLEAN() macro converts it to a boolean value:

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

Native boolean values do not require this macro. However, it is safe to use when the value type is uncertain.

Boolean values (true or false) are mapped from the strings "true", "false", "yes", and "no", as well as the string and numeric values 0 and 1.

Example 1:

Example 2:

Converts a first_event_time of 1582020352 to a human readable string:

{
    "Date": "2020-02-18T10:05:52.000Z",
    "FirstOccurred" : 1582020352
}

Converts an alert_id of "99" to 99:

{
    AlertID : 99
}

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

Set the following for the top level object:

{
  "alert_id" : $TO_INT(alert_id),
  "severity" : $TO_INT(severity),
  "description" : $(description),
  "location" : {
      "city" : $(custom_info.location.city),
      "country" : $(custom_info.location.country)
  }
}

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.

If the following rule is used:

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

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.

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:

This produces the following payload:

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

$TO_JSON( [ $(custom_info.location.country) , $(custom_info.location.city) ])

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

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'
    }
}

Any valid macro can be used within the $TO_JSON() macro, with the exception of $TO_JSON() itself.

The $TO_JSON() macro must be the enclosing macro. In other words, a rule must start with “$TO_JSON(“ and the last a “)”.

For example:

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

Valid:

This is an object  $TO_JSON({ "first" : "$TO_DATE(first_event_time)", "last" : "$TO_DATE(last_event_time)" })

results in the following:

This is an object  $TO_JSON({ "first" : "$TO_DATE(first_event_time)", "last" : "$TO_DATE(last_event_time)" })

In this case, the substitutions are performed, but the $TO_JSON() macro is not executed because it does not enclose the entire rule.

TO_LIST joins the value without any expansion.

Given the following rules in a Payload:

TeamsAsList : $TO_LIST(teams)

The resulting outbound payload value is:

{
    TeamsAsList : '[1,2]'
}

Converts a severity value of 5 to "5":

{
    Severity: "5"
}

For example, if the desired output is:

{
  "alert_id" : "1234"
}

Similarly, if the desired output is:

This is the severity "5"