[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,7 +40,7 @@ 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.
@@ -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
@@ -132,55 +192,44 @@ close to the bucket span of the job.
 
 As the last step in the rule creation process, define its actions.
 
+[discrete]
+[[anomaly-jobs-health-actions]]
+=== {anomaly-jobs-cap} health rule actions
 
-[[defining-actions]]
-== Defining 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:
 
-//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.
+* actions that run when an issue is detected
+* recovery actions that run when the rule 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].
-
-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.
-
-//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>>.
+For each action, you must choose a connector, which provides connection
+information for a {kib} service or third-party integration. 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). You must also choose one of the action groups (for
+example, the action runs when the issue is detected or when it is recovered).
 
 [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,