[DOCS] Alerts-as-data for anomaly detection rules (#100864)

docs/reference/ml/anomaly-detection/ml-configuring-alerts.asciidoc

@@ -1,6 +1,9 @@
-[role="xpack"]
 [[ml-configuring-alerts]]
 = Generating alerts for {anomaly-jobs}
+:frontmatter-description: Create {anomaly-detect} alert and {anomaly-jobs} health rules.
+:frontmatter-tags-products: [ml, alerting]
+:frontmatter-tags-content-type: [how-to]
+:frontmatter-tags-user-goals: [configure]
 
 beta::[]
 
@@ -26,10 +29,6 @@ TIP: If you have created rules for specific {anomaly-jobs} and you want to
 monitor whether these jobs work as expected, {anomaly-jobs} health rules are 
 ideal for this purpose.
 
-
-[[creating-ml-rules]]
-== Creating a rule
-
 In *{stack-manage-app} > {rules-ui}*, you can create both types of {ml} rules:
 
 [role="screenshot"]
@@ -41,13 +40,13 @@ them from the {anomaly-job} wizard after you start the job or from the
 {anomaly-job} list.
 
 [[creating-anomaly-alert-rules]]
-=== {anomaly-detect-cap} alert
+== {anomaly-detect-cap} alert rules
 
 When you create an {anomaly-detect} alert rule, you must select the job that
 the rule applies to.
 
 You must also select a type of {ml} result. In particular, you can create rules
-based  on bucket, record, or influencer results.
+based on bucket, record, or influencer results.
 
 [role="screenshot"]
 image::images/ml-anomaly-alert-severity.png["Selecting result type, severity, and test interval", 500]
@@ -84,10 +83,71 @@ TIP: You must also provide a _check interval_ that defines how often to
 evaluate the rule conditions. It is recommended to select an interval that is
 close to the bucket span of the job.
 
-As the last step in the rule creation process, <<defining-actions,define its actions>>.
+As the last step in the rule creation process, define its actions.
+
+[discrete]
+[[anomaly-alert-actions]]
+=== {anomaly-detect-cap} alert rule actions
+
+You can optionally send notifications when the rule conditions are met and when
+they are no longer met. In particular, this rule type supports:
+
+* alert summaries
+* actions that run when the anomaly score matches the conditions
+* recovery actions that run when the conditions are no longer met
+
+Each action uses a connector, which stores connection information for a {kib}
+service or supported third-party integration, depending on where you want to
+send the notifications. For example, you can use a Slack connector to send a
+message to a channel. Or you can use an index connector that writes an JSON
+object to a specific index. For details about creating connectors, refer to
+{kibana-ref}/action-types.html[Connectors].
+
+After you select a connector, you must set the action frequency. You can choose
+to create a summary of alerts on each check interval or on a custom interval.
+For example, send slack notifications that summarize the new, ongoing, and
+recovered alerts:
+
+[role="screenshot"]
+image::images/ml-anomaly-alert-action-summary.png["Adding an alert summary action to the rule",500]
+// NOTE: This is an autogenerated screenshot. Do not edit it directly.
+
+TIP: If you choose a custom action interval, it cannot be shorter than the
+rule's check interval.
+
+Alternatively, you can set the action frequency such that actions run for each
+alert. Choose how often the action runs (at each check interval, only when the
+alert status changes, or at a custom action interval). You must also choose an
+action group, which indicates whether the action runs when the anomaly score is
+matched or when the alert is recovered. For example:
+
+[role="screenshot"]
+image::images/ml-anomaly-alert-action-score-matched.png["Adding an action for each alert in the rule",500]
+// NOTE: This is an autogenerated screenshot. Do not edit it directly.
+
+You can further refine the conditions under which actions run by specifying that
+actions only run they match a KQL query or when an alert occurs within a
+specific time frame.
+
+There is a set of variables that you can use to customize the notification
+messages for each action. Click the icon above the message text box to get the
+list of variables or refer to <<action-variables>>.
+
+[role="screenshot"]
+image::images/ml-anomaly-alert-messages.png["Customizing your message",500]
+// NOTE: This is an autogenerated screenshot. Do not edit it directly.
+
+After you save the configurations, the rule appears in the
+*{stack-manage-app} > {rules-ui}* list; you can check its status and see the
+overview of its configuration information.
+
+When an alert occurs, it is always the same name as the job ID of the associated 
+{anomaly-job} that triggered it. If necessary, you can snooze rules to prevent
+them from generating actions. For more details, refer to
+{kibana-ref}/create-and-manage-rules.html#controlling-rules[Snooze and disable rules].
 
 [[creating-anomaly-jobs-health-rules]]
-=== {anomaly-jobs-cap} health
+== {anomaly-jobs-cap} health rules
 
 When you create an {anomaly-jobs} health rule, you must select the job or group
 that the rule applies to. If you assign more jobs to the group, they are
@@ -131,56 +191,45 @@ evaluate the rule conditions. It is recommended to select an interval that is
 close to the bucket span of the job.
 
 As the last step in the rule creation process, define its actions.
-  
 
-[[defining-actions]]
+[discrete]
-== Defining actions
+[[anomaly-jobs-health-actions]]
+=== {anomaly-jobs-cap} health rule actions
 
-//tag::define-actions[]
+You can optionally send notifications when the rule conditions are met and when
-You can add one or more actions to your rule to generate notifications when its
+they are no longer met. In particular, this rule type supports:
-conditions are met and when they are no longer met.
 
-Each action uses a connector, which stores connection information for a {kib}
+* actions that run when an issue is detected
-service or supported third-party integration, depending on where you want to
+* recovery actions that run when the rule conditions are no longer met
-send the notifications. For example, you can use a Slack connector to send a
-message to a channel. Or you can use an index connector that writes an JSON
-object to a specific index. For details about creating connectors, refer to
-{kibana-ref}/action-types.html[Connectors].
 
-You must set the action frequency, which involves choosing how often to run
+For each action, you must choose a connector, which provides connection
-the action (for example, at each check interval, only when the alert status
+information for a {kib} service or third-party integration. You must set the
-changes, or at a custom action interval). Each rule type also has a list of
+action frequency, which involves choosing how often to run the action (for
-valid action groups and you must choose one of these groups (for example, the
+example, at each check interval, only when the alert status changes, or at a
-action runs when the issue is detected or when it is recovered).
+custom action interval). You must also choose one of the action groups (for
-
+example, the action runs when the issue is detected or when it is recovered).
-TIP: If you choose a custom action interval, it cannot be shorter than the
-rule's check interval.
-
-//end::define-actions[]
-
-It's also possible to customize the notification messages for each action. There
-is a set of variables that you can include in the message depending on the rule
-type; refer to <<action-variables>>.
 
 [role="screenshot"]
-image::images/ml-anomaly-alert-messages.png["Customizing your message",500]
+image::images/ml-health-check-action.png["Adding an action for each alert in the rule",500]
 // NOTE: This is an autogenerated screenshot. Do not edit it directly.
 
+You can pass rule values to an action to provide contextual details in the
+notification messages. For the list of variables that you can include in the
+message, click the icon above the message text box or refer to
+<<action-variables>>.
+
 After you save the configurations, the rule appears in the
 *{stack-manage-app} > {rules-ui}* list; you can check its status and see the
 overview of its configuration information.
 
-When an alert occurs, it is always the same name as the job ID of the associated 
-{anomaly-job} that triggered it. If necessary, you can snooze rules to prevent
-them from generating actions. For more details, refer to
-{kibana-ref}/create-and-manage-rules.html#controlling-rules[Snooze and disable rules].
-
 [[action-variables]]
 == Action variables
 
 The following variables are specific to the {ml} rule types. An asterisk (`*`)
 marks the variables that you can use in actions related to recovered alerts.
 
+You can also specify {kibana-ref}/rule-action-variables.html[variables common to all rules].
+
 [[anomaly-alert-action-variables]]
 === {anomaly-detect-cap} alert action variables
 

docs/reference/transform/transform-alerts.asciidoc

@@ -57,7 +57,24 @@ As the last step in the rule creation process, define its actions.
 [[defining-actions]]
 == Defining actions
 
-include::{es-repo-dir}/ml/anomaly-detection/ml-configuring-alerts.asciidoc[tag=define-actions]
+You can add one or more actions to your rule to generate notifications when its
+conditions are met and when they are no longer met.
+
+Each action uses a connector, which stores connection information for a {kib}
+service or supported third-party integration, depending on where you want to
+send the notifications. For example, you can use a Slack connector to send a
+message to a channel. Or you can use an index connector that writes an JSON
+object to a specific index. For details about creating connectors, refer to
+{kibana-ref}/action-types.html[Connectors].
+
+You must set the action frequency, which involves choosing how often to run
+the action (for example, at each check interval, only when the alert status
+changes, or at a custom action interval). Each rule type also has a list of
+valid action groups and you must choose one of these groups (for example, the
+action runs when the issue is detected or when it is recovered).
+
+TIP: If you choose a custom action interval, it cannot be shorter than the
+rule's check interval.
 
 It's also possible to customize the notification messages for each action. A
 list of variables is available to include in the message, like {transform} ID,