[[rule-action-variables]] == Rule action variables :frontmatter-description: A summary of common variables for use in {kib} alerting rule actions. :frontmatter-tags-products: [alerting] :frontmatter-tags-content-type: [reference] :frontmatter-tags-user-goals: [configure] Alerting rules can use the https://mustache.github.io/mustache.5.html[Mustache] template syntax (`{{variable name}}`) to pass values when the actions run. [float] [[common-rule-action-variables]] === Common variables The available variables differ by rule type, however there are some common variables: * <> * <> * <> Some cases exist where the variable values will be "escaped" when used in a context where escaping is needed. For example: - For the <>, the `message` action configuration property escapes any characters that would be interpreted as Markdown. - For the <>, the `message` action configuration property escapes any characters that would be interpreted as Slack Markdown. - For the <>, the `body` action configuration property escapes any characters that are invalid in JSON string values. Mustache also supports "triple braces" of the form `{{{variable name}}}`, which indicates no escaping should be done at all. Use this form with caution, since it could end up rendering the variable content such that the resulting parameter is invalid or formatted incorrectly. [float] [[general-rule-action-variables]] ==== General All rule types pass the following variables: `date`:: The date the rule scheduled the action, in ISO format. `kibanaBaseUrl`:: The configured <>. If not configured, this will be empty. `rule.id`:: The rule identifier. `rule.name`:: The rule name. `rule.params`:: The rule parameters, which vary by rule type. `rule.spaceId`:: The space identifier for the rule. `rule.tags`:: The list of tags applied to the rule. [float] [role="child_attributes"] [[alert-summary-action-variables]] ==== Action frequency: Summary of alerts If the rule's action frequency is a summary of alerts, it passes the following variables: `alerts.all.count`:: The count of all alerts. `alerts.all.data`:: An array of objects for all alerts. The following object properties are examples; it is not a comprehensive list. + .Properties of the alerts.all.data objects [%collapsible%open] ===== //# tag::alerts-data[] `kibana.alert.end`:: Datetime stamp of alert end. preview:[] `kibana.alert.flapping`:: A flag on the alert that indicates whether the alert status is changing repeatedly. preview:[] `kibana.alert.instance.id`:: ID of the source that generates the alert. preview:[] `kibana.alert.reason`:: The reason of the alert (generated with the rule conditions). preview:[] `kibana.alert.start`:: Datetime stamp of alert start. preview:[] `kibana.alert.status`:: Alert status (for example, active or OK). preview:[] //# end::alerts-data[] ===== `alerts.new.count`:: The count of new alerts. `alerts.new.data`:: An array of objects for new alerts. The following object properties are examples; it is not a comprehensive list. + .Properties of the alerts.new.data objects [%collapsible] ===== include::action-variables.asciidoc[tag=alerts-data] ===== `alerts.ongoing.count`:: The count of ongoing alerts. `alerts.ongoing.data`:: An array of objects for ongoing alerts. The following object properties are examples; it is not a comprehensive list. + .Properties of the alerts.ongoing.data objects [%collapsible] ===== include::action-variables.asciidoc[tag=alerts-data] ===== `alerts.recovered.count`:: The count of recovered alerts. `alerts.recovered.data`:: An array of objects for recovered alerts. The following object properties are examples; it is not a comprehensive list. + .Properties of the alerts.recovered.data objects [%collapsible] ===== include::action-variables.asciidoc[tag=alerts-data] ===== [float] [[alert-action-variables]] ==== Action frequency: For each alert If the rule's action frequency is not a summary of alerts, it passes the following variables: `alert.actionGroup`:: The ID of the action group of the alert that scheduled the action. `alert.actionGroupName`:: The name of the action group of the alert that scheduled the action. `alert.actionSubgroup`:: The action subgroup of the alert that scheduled the action. `alert.flapping`:: A flag on the alert that indicates whether the alert status is changing repeatedly. `alert.id`:: The ID of the alert that scheduled the action. `alert.uuid`:: A universally unique identifier for the alert. While the alert is active, the UUID value remains unchanged each time the rule runs. preview:[] [float] [[defining-rules-actions-variable-context]] ===== Context If the rule's action frequency is not a summary of alerts, the rule defines additional variables as properties of the variable `context`. For example, if a rule type defines a variable `value`, it can be used in an action parameter as `{{context.value}}`. For diagnostic or exploratory purposes, action variables whose values are objects, such as `context`, can be referenced directly as variables. The resulting value will be a JSON representation of the object. For example, if an action parameter includes `{{context}}`, it will expand to the JSON representation of all the variables and values provided by the rule type. To see all alert-specific variables, use `{{.}}`. For situations where your rule response returns arrays of data, you can loop through the `context`: [source,sh] -------------------------------------------------- {{#context}}{{.}}{{/context}} -------------------------------------------------- For example, looping through search result hits: [source,sh] -------------------------------------------------- triggering data was: {{#context.hits}} - {{_source.message}} {{/context.hits}} -------------------------------------------------- [discrete] [[enhance-mustache-variables]] === Enhancing Mustache variables preview::[] You can enhance the values contained in Mustache variables when the Mustache template is rendered by rendering objects as JSON or by using Mustache lambdas. [discrete] ==== Rendering objects as JSON Some connectors (such as the <>) expect JSON values to be passed as parameters when the connector is invoked. The following capabilities are available: - Array values referenced in braces have a predefined rendering by Mustache as string versions of the array elements, joined with a comma (`,`). To render array values as JSON, access the `asJSON` property of the array, instead of the array directly. For example, given a Mustache variable `context.values` that has the value `[1, 4, 9]` the Mustache template `{{context.values}}` will render as `1,4,9`, and the Mustache template `{{context.values.asJSON}}` will render as `[1,4,9]`. - The <> Mustache lambda makes it easier to create JSON in your templates by using https://hjson.github.io/[Hjson], a syntax extension to JSON, rather than strict JSON. [discrete] ==== Using Mustache lambdas Mustache lambdas provide additional rendering capabilities for Mustache templates. A Mustache lambda is formatted like a Mustache section. For example: [source,sh] ---- {{#EvalMath}} round(context.value, 1) {{/EvalMath}} ---- In that example, the lambda `EvalMath` is passed the text `round(context.value, 1)` and renders a rounded value of the `context.value` variable. This pattern is used by all the provided Mustache lambdas described in the subsequent sections. [discrete] ===== EvalMath The EvalMath lambda will evaluate the text passed to it as <>. For example, when the Mustache variable `context.value` is `3.1234`, the following template will render as `3.1`: [source,sh] ---- {{#EvalMath}} round(context.value, 1) {{/EvalMath}} ---- This lambda can access Mustache variables without having to wrap them in `{{}}`. However, if the value is in a string form (for example, an Elasticsearch numeric field whose source was indexed as a string), or could be escaped, escaping the value with triple quotes should allow this to work. For example, if the Mustache variable `context.value` is `"3.1234"`, the following template will render as `3.1`: [source,sh] ---- {{#EvalMath}} round( {{{context.value}}} , 1) {{/EvalMath}} ---- [discrete] [[parse-hjson-lambda]] ===== ParseHjson The ParseHjson lambda provides ease-of-use capabilities when constructing JSON objects. https://hjson.github.io/[Hjson] is a syntax extension to JSON. It has the following features: - Missing and extra trailing commas are allowed in arrays and objects. - Comments are supported. - Property names can be specified without quotes. - Property values can be specified without quotes (one per line and no commas). - Multi-line strings have dedent support to remove the leading whitespace. - Legal JSON documents are supported. To use it, surround your Hjson content with `{{#ParseHjson}}...{{/ParseHjson}}`. For example: [source,sh] ---- {{#ParseHjson}} { # add the rule id and name to the JSON document ruleId: "{{rule.id}}" ruleName: "{{rule.name}}" } {{/ParseHjson}} ---- When rendered, this template will generate: [source,json] ---- { "ruleId": "", "ruleName": "" } ---- [discrete] ===== FormatDate The FormatDate lambda provides date formatting capabilities. Dates can be formatted in an arbitrary time zone and with an arbitrary format string. To use it, surround the date and formatting parameters with `{{#FormatDate}}...{{/FormatDate}}`. The format of the text passed to the lambda is: `;