From 17cdf73bec1b750e5a46cdb62868b80c14a2d062 Mon Sep 17 00:00:00 2001 From: Patrick Mueller Date: Sun, 14 May 2023 14:39:25 -0400 Subject: [PATCH] [ResponseOps][docs] add docs for new mustache lambdas and asJSON for array (#155417) resolves: https://github.com/elastic/kibana/issues/155408 ## Summary adds doc for function added in [adds mustache lambdas and array.asJSON](https://github.com/elastic/kibana/pull/150572) (cherry picked from commit 120fa44afd6b87764d114475caa97d862c55f343) --- docs/user/alerting/action-variables.asciidoc | 221 +++++++++++++++++- .../email-mustache-template-rendered.png | Bin 0 -> 125297 bytes 2 files changed, 212 insertions(+), 9 deletions(-) create mode 100644 docs/user/alerting/images/email-mustache-template-rendered.png diff --git a/docs/user/alerting/action-variables.asciidoc b/docs/user/alerting/action-variables.asciidoc index 4eda20454ef93..7bffa7dcaaa1a 100644 --- a/docs/user/alerting/action-variables.asciidoc +++ b/docs/user/alerting/action-variables.asciidoc @@ -1,8 +1,12 @@ [[rule-action-variables]] == Rule action variables -Alerting rules can use the https://mustache.github.io/[Mustache] template syntax -(`{{variable name}}`) to pass values when its actions run. +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: @@ -20,7 +24,7 @@ Mustache also supports "triple braces" of the form `{{{variable name}}}`, which [float] [[general-rule-action-variables]] -=== General +==== General All rule types pass the following variables: @@ -34,7 +38,7 @@ All rule types pass the following variables: [float] [role="child_attributes"] [[alert-summary-action-variables]] -=== Action frequency: Summary of alerts +==== Action frequency: Summary of alerts If the rule's action frequency is a summary of alerts, it passes the following variables: @@ -91,7 +95,7 @@ include::action-variables.asciidoc[tag=alerts-data] [float] [[alert-action-variables]] -=== Action frequency: For each alert +==== Action frequency: For each alert If the rule's action frequency is not a summary of alerts, it passes the following variables: @@ -100,15 +104,15 @@ If the rule's action frequency is not a summary of alerts, it passes the followi `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:[] +`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 +===== 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}}`. +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 alert-specific variables, use `{{.}}`. +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`: @@ -125,3 +129,202 @@ 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] +---- +{{#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] +---- +{{#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] +---- +{{#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] +---- +{{#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: `;