Skip to main content

Macro and substitution syntax reference

APEX AIOps Incident Management includes a proprietary macro language for use with Workflow Engine.

Substitution syntax

Incident Management lets you create references to payload fields (keys) and use them in webhook endpoint payloads, URLs, workflow actions, and webhook endpoint request headers. There are many uses for substitution, such as pulling information from a payload to create an incident description or adding information to a custom tag. See Substitution in webhook endpoint requests to see how substitution is used in webhook endpoint requests.

Basic substitution

Substitutes the value of <property_name> for the field reference. The reference syntax is returned if property_name is undefined.

Syntax:

${<property_name>}

where <property_name> is the name of a field.

Example 1. Basic substitution

If the statement says:

"services": ${tags.key1}

and the tags.key1 field referenced contains these values:

{
 ...
 "tags.key1": [ "mongodb","saas","radius","storage"]
 ...
}

Then the following substitution occurs:

{
 ...  
   "services": [ 
       "mongodb", 
       "saas", 
       "radius",
       "storage 
   ]
 ...
}

For additional examples of basic substitution, refer to Field and tag substitution for JSON payloads.



Quiet mode

To replace an undefined reference with an empty sting instead of returning the reference, use the ! character to indicate quiet mode. Use quiet mode when you want to return an empty string instead of the reference string when it is undefined.

Syntax:

$!{<property_name>}

where <property_name> is the name of a field.

Undefined values in webhooks

Webhooks created prior to the introduction of separate alert and incident webhook endpoints use this syntax for substitution:

$tags.<sometag>

If you would like to edit your deprecated webhook, you can use either the old or the current substitution syntax. The behavior is different when the reference is undefined, however, as shown in the following table:

Syntax

Value returned value when the reference is undefined

Old version:

$tags.<sometag>

empty string

Current version:

${tags.<sometag>}

‌

${tags.<sometag>}

When the value for $tags.<sometag> is undefined, an empty string is returned. When the value for ${tags.<sometag>} is undefined, the value ${tags.<sometag>} is returned.

If your webhook relies on returning an empty string when a reference is undefined, it is recommended that you either continue using this old syntax, or use quiet mode with the current syntax:

$!{tags.<sometag>}

Important

While deprecated webhooks support both old and current syntax, you must consistently use only one syntax version in the webhook. Using the current syntax anywhere in the webhook body causes it to expect the current syntax throughout, so mixing the old and current versions will cause your webhook to fail.

Note that this support for the old substitution syntax only applies to webhooks.

Macro syntax

Incident Management macros are functions that receive one or more parameters (a field name and a number, in some cases), process the data according to the function definition, and then return one or more values. Macros are useful when populating descriptions or passing information (such as a list of elements or a count of values) to other payload fields.

You can use macros to create descriptions in incidents in correlation definitions, modifying payloads with workflow actions that accept macros, or when referencing data with webhook endpoint payloads.

Use the following format when using macros:

${<macro_name>(<field_name>,N)}

where <macro_name> is the name of the macro, N is the number of results to return, and <field_name> is the name of a field in an alert.

Note

Only certain macros support the N parameter.

Macro reference

Incident Management supports the following macros:

cited

Returns the number of times the most frequently occurring values appear for a given field.

Syntax:

${cited(<field_name>,N)}

where <field_name> is the name of the alert field to evaluate and N is the number of values to show.

Example 2. cited

If your macro states:

${cited(service,2)}

and the values for the service fields are as follows:

mongodb

saas

saas

mongodb

mongodb

radius

saas

storage

Then the output for the macro is: 

saas(3), mongodb(3)


count

Returns the number of different values for a field.

Syntax:

${count(<field_name>)}

where <field_name> is the name of the alert field to evaluate.

Example 3. count

If your macro states:

${count(source)}

And the values for the source fields are as follows:

10.0.0.1

10.0.0.1

10.0.0.10

10.0.0.1

10.0.0.15

10.0.0.1

10.0.0.75

10.0.0.6

Then the output for the macro is:

8


max

Returns the maximum value for a numeric value field.

Syntax:

${max(<field_name>)}

where <field_name> is the name of the alert field to evaluate.

Example 4. max

If your macro states:

${max(severity_numeric)}

And the values for the severity_numeric fields are as follows:

1

3

2

1

Then the output for the macro is:

3


Note

The max macro is unsupported for correlation definition descriptions.

min

Returns the minimum value for a numeric field.

Syntax:

${min(<field_name>)}

where <field_name> is the name of the alert field to evaluate.

Example 5. min

If your macro states:

${min(severity_numeric)}

And the values for the severity_numeric fields are as follows:

4

1

1

5

Then the output for the macro is:

1


Note

The min macro is unsupported for correlation definition descriptions.

tolist

Returns a list of all the values for the selected field, including duplicates. Note that this macro cannot be applied to fields containing lists (arrays).

Syntax:

${tolist(<field_name>)}

where <field_name> is the name of the alert field to evaluate.

Example 6. tolist

If your macro states:

${tolist(check)}

And the values for check are as follows:

Info1

Info3

Info2

Info1

Then the output for the macro is:

Info1, Info1, Info2, Info3


top

Returns the most-cited value for a field.

Syntax:

${top(<fieldname>)}

where <field_name> is the name of the alert field to evaluate.

Example 7. top

If your macro states:

${top(tags.myfield)}

And the values for tags.myfield are as follows:

mongodb

saas

saas

mongodb

storage

radius

saas

storage

Then the output for the macro is:

saas


unique

Returns a comma-separated list of the first N unique elements for a field, excluding duplicates.

Syntax:

${unique(<field_name>,N)}

where <field_name> is the name of the alert field to evaluate and N is the number of elements to return.

Example 8. unique

If your macro states:

${unique(class,2)}

And the values for class are as follows:

mongodb

saas

saas

mongodb

storage

radius

saas

storage

Then the output for the macro is:

mongodb, radius


unique_count

Returns the number of unique values for a field.

Syntax:

${unique_count(<field_name>)}

where <field_name> is the name of the alert field to evaluate.

Example 9. unique_count

If your macro states:

${unique_count(source)}

And the values for source are as follows:

192.168.1.1

192.168.1.5

192.168.1.1

192.168.1.50

192.168.1.100

192.168.1.1

192.168.1.250

192.168.1.1

Then the output for the macro is:

5


In this section: