[8.14] [DOCS] Add Elasticsearch query rule action variables and data types (#183691) (#184791)

# Backport This will backport the following commits from `main` to `8.14`: - [[DOCS] Add Elasticsearch query rule action variables and data types (#183691)](https://github.com/elastic/kibana/pull/183691)  ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sqren/backport)  Co-authored-by: Lisa Cawley <lcawley@elastic.co>
2025-04-24 17:59:23 -04:00 · 2024-06-04 22:20:57 -04:00 · 2024-06-04 22:20:57 -04:00 · 6184f84168
commit 6184f84168
parent 234f97a8cd
1 changed files with 52 additions and 28 deletions
--- a/docs/user/alerting/rule-types/es-query.asciidoc
+++ b/docs/user/alerting/rule-types/es-query.asciidoc
@ -143,44 +143,44 @@ You can further refine the conditions under which actions run by specifying that
 [float]
 === Add action variables

-You can pass rule values to an action to provide contextual details.
-To view the list of variables available for each action, click the "add rule variable" button.
+When you create a rule in {kib}, it provides an example message that is appropriate for each action.
+For example, the following message is provided for server log connector actions that run for each alert:
+
+[source,mustache]
+--------------------------------------------------
+Elasticsearch query rule '{{rule.name}}' is active:
+
+- Value: {{context.value}}
+- Conditions Met: {{context.conditions}} over {{rule.params.timeWindowSize}}{{rule.params.timeWindowUnit}}
+- Timestamp: {{context.date}}
+- Link: {{context.link}}
+--------------------------------------------------
+
+Rules use rule action variables and Mustache templates to pass contextual details into the alert notifications.
+There is a set of <<defining-rules-actions-variables,variables common to all rules>> and a set that is specific to this rule.
+To view the list of variables in {kib}, click the "add rule variable" button.
 For example:

 [role="screenshot"]
 image::images/es-query-rule-action-variables.png[Passing rule values to an action]
 // NOTE: This is an autogenerated screenshot. Do not edit it directly.

-The following variables are specific to the {es} query rule.
-You can also specify <<defining-rules-actions-variables,variables common to all rules>>.
+The following variables are specific to the {es} query rule:

-`context.title`:: A preconstructed title for the rule. Example: 
-`rule term match alert query matched`.
+`context.conditions`::
+(string) A description of the condition. For example: `Query matched documents`.

-`context.message`:: A preconstructed message for the rule. Example: +
-`rule 'my es-query' is active:` +
-`- Value: 2` +
-`- Conditions Met: Number of matching documents is greater than 1 over 5m` +
-`- Timestamp: 2022-02-03T20:29:27.732Z`
+`context.date`::
+(string) The date, in ISO format, that the rule met the condition. For example: `2024-04-30T00:55:42.765Z`.

-`context.group`:: The name of the action group associated with the condition. 
-Example: `query matched`.
-
-`context.date`:: The date, in ISO format, that the rule met the condition. 
-Example: `2022-02-03T20:29:27.732Z`.
-
-`context.value`:: The value of the rule that met the condition.
-
-`context.conditions`:: A description of the condition. Example: 
-`count greater than 4`.
-
-`context.hits`:: The most recent documents that matched the query. Using the 
-https://mustache.github.io/[Mustache] template array syntax, you can iterate 
+`context.hits`::
+(array of objects) The most recent documents that matched the query.
+Using the https://mustache.github.io/[Mustache] template array syntax, you can iterate 
 over these hits to get values from the {es} documents into your actions.
 For example, the message in an email connector action might contain:
 +
 --
-[source,sh]
+[source,mustache]
 --------------------------------------------------
 Elasticsearch query rule '{{rule.name}}' is active:

@ -195,7 +195,7 @@ If the {es} query search API's {ref}/search-fields.html#search-fields-param[`fie
 which can be used to access any runtime fields defined by the {ref}/runtime-search-request.html[`runtime_mappings`] parameter. 
 For example:

-[source,sh]
+[source,mustache]
 --------------------------------------------------
 {{#context.hits}}
 timestamp: {{_source.@timestamp}}
@ -209,7 +209,7 @@ As the {ref}/search-fields.html#search-fields-response[`fields`] response always
 the https://mustache.github.io/[Mustache] template array syntax is used to iterate over these values in your actions.
 For example:

-[source,sh]
+[source,mustache]
 --------------------------------------------------
 {{#context.hits}}
 Labels:
@ -221,6 +221,30 @@ Labels:
 // NOTCONSOLE
 --

+`context.link`::
+(string) The URL for the rule that generated the alert.
+For example: `/app/management/insightsAndAlerting/triggersActions/rule/47754354-d894-49d3-87ec-05745a74e2b7`.
+
+`context.message`::
+(string) A preconstructed message for the rule.
+For example: +
+`Document count is 100 in the last 1h. Alert when greater than 50.`
+
+`context.sourceFields`::
+(object) If the rule was configured to copy source fields into alerts, for each source field there is an array of strings that contains its values.
+For example: `{'host.id': ['1'], 'host.name': ['host-1']}`.
+
+`context.title`::
+(string) A preconstructed title for the rule. Example: 
+`rule 'my-query-rule' matched query`.
+
+`context.value`::
+(number) The value that met the rule threshold condition.
+
+`rule.params`::
+(object) The rule parameters, such as `searchType`, `timeWindowSize`, and `timeWindowUnit`.
+For the definitive list of parameters for this rule, refer to the API documentation.
+
 [float]
 === Handling multiple matches of the same document

@ -252,4 +276,4 @@ window of 1 hour and checks if there are more than 99 matches for the query. The
 | `Run 4 (0:03)`
 | Rule finds 190 matches in the last hour. 71 of them are duplicates that were already alerted on previously, so you actually have 119 matches: `119 > 99`
 | Rule is active and user is alerted.
-|===
+|===