Added documentation for printing associated queries, and sample documents in notification message.

_observing-your-data/alerting/triggers.md

@@ -125,15 +125,76 @@ Variable | Data type | Description
 #### Other variables
 
 Variable | Data type | Description
-:--- | :--- : :---
-`ctx.results` | Array | An array with one element (`ctx.results[0]`). Contains the query results. This variable is empty if the trigger was unable to retrieve results. See `ctx.error`.
+:--- | :--- | : ---
+`ctx.results` | Array | An array with one element (`ctx.results.0`). Contains the query results. This variable is empty if the trigger was unable to retrieve results. See `ctx.error`.
 `ctx.last_update_time` | Milliseconds | Unix epoch time of when the monitor was last updated.
 `ctx.periodStart` | String | Unix timestamp for the beginning of the period during which the alert was triggered. For example, if a monitor runs every 10 minutes, a period might begin at 10:40 and end at 10:50.
 `ctx.periodEnd` | String | The end of the period during which the alert triggered.
 `ctx.error` | String | The error message displayed if the trigger was unable to retrieve results or could not be evaluated, typically due to a compile error or null pointer exception. Null otherwise.
 `ctx.alert` | Object | The current, active alert (if it exists). Includes `ctx.alert.id`, `ctx.alert.version`, and `ctx.alert.isAcknowledged`. Null if no alert is active. Only available with query-level monitors.
-`ctx.dedupedAlerts` | Object | Alerts that have been triggered. OpenSearch keeps the existing alert to prevent the plugin from creating endless numbers of the same alert. Only available with bucket-level monitors.
-`ctx.newAlerts` | Object | Newly created alerts. Only available with bucket-level monitors.
-`ctx.completedAlerts` | Object | Alerts that are no longer ongoing. Only available with bucket-level monitors.
-`bucket_keys` | String | Comma-separated list of the monitor's bucket key values. Available only for `ctx.dedupedAlerts`, `ctx.newAlerts`, and `ctx.completedAlerts`. Accessed through `ctx.dedupedAlerts[0].bucket_keys`.
-`parent_bucket_path` | String | The parent bucket path of the bucket that triggered the alert. Accessed through `ctx.dedupedAlerts[0].parent_bucket_path`.
+`ctx.alerts` | Array | Newly created alerts. Includes `ctx.alerts.0.finding_ids` that triggered the alert, and `ctx.alerts.0.related_doc_ids` associated with the findings. Only available with document-level monitors.
+`ctx.dedupedAlerts` | Array | Alerts that have been triggered. OpenSearch keeps the existing alert to prevent the plugin from creating endless numbers of the same alert. Only available with bucket-level monitors.
+`ctx.newAlerts` | Array | Newly created alerts. Only available with bucket-level monitors.
+`ctx.completedAlerts` | Array | Alerts that are no longer ongoing. Only available with bucket-level monitors.
+`bucket_keys` | String | Comma-separated list of the monitor's bucket key values. Available only for `ctx.dedupedAlerts`, `ctx.newAlerts`, and `ctx.completedAlerts`. Accessed through `ctx.dedupedAlerts.0.bucket_keys`.
+`parent_bucket_path` | String | The parent bucket path of the bucket that triggered the alert. Accessed through `ctx.dedupedAlerts.0.parent_bucket_path`.
+`associated_queries` | Array | An array of document-level monitor queries that triggered the creation of the finding associated with the alert. Only available with document-level monitors. Accessed through `ctx.alerts.0.associated_queries`.
+`sample_documents` | Array | An array of sample documents that matched the monitor query. Only available with bucket-level, and document-level monitors. Accessed through `ctx.newAlerts.0.sample_documents`, and `ctx.alerts.0.sample_documents`, respectively.
+
+#### `associated_queries`, and `sample_documents` variables
+
+Per bucket, and per document monitors support printing sample documents in notification messages; and per document monitors support printing the list of queries that triggered the creation of the finding associated with the alert. Each new alert that's generated during a monitor execution will be added to a list (i.e., `newAlerts` for per bucket monitors, and `alerts` for per document monitors) within the `ctx` variable. Each alert has its own list of `sample_documents`, and each per document monitor alert has its own list of `associated_queries`. The message template can be formatted to iterate through the list of alerts, and the list of `associated_queries`, and `sample_documents` for each alert.
+
+To learn more about security in the Alerting plugin, see [Alerting security](https://opensearch.org/docs/latest/observing-your-data/alerting/security/).
+
+#### Sample documents variables
+
+Variable | Data type | Description
+:--- | :--- | : ---
+`_index` | String | The index containing the 
+`_id` | String | The document ID for the document in its index.
+`_score` | Float | A positive 32-bit floating point number illustrating the relevance of the returned document.
+`_source` | Object | The JSON payload of the sample document.
+
+##### Mustache template example
+
+```groovy
+Alerts:
+{{#ctx.alerts}}
+    RULES
+    {{#associated_queries}}
+        Name: {{name}}
+        Id: {{id}}
+        Tags: {{tags}}
+    ------------------------
+    {{/associated_queries}}
+{{/ctx.alerts}}
+```
+
+#### Associated queries variables
+
+Variable | Data type | Description
+:--- | :--- | : ---
+`id` | String | The ID for the document-level query.
+`name` | String | The name configured for the document-level query.
+`tags` | Array | An array of tags (each of type String) configured for the document-level query.
+
+##### Mustache template example
+
+**Note**: The `_source` object in this example is based on the `opensearch_dashboards_sample_data_ecommerce` index that's available on OpenSearch Dashboards.
+
+```groovy
+Alerts
+{{#ctx.alerts}}
+    Sample documents:
+    {{#sample_documents}}
+        Index: {{_index}}
+        Document ID: {{_id}}
+
+        Order date: {{_source.order_date}}
+        Order ID: {{_source.order_id}}
+        Clothing category: {{_source.category}}
+        -----------------
+    {{/sample_documents}}
+{{/ctx.alerts}}
+```