Alert summaries and conditional actions (#3245)

Co-authored-by: Ievgen Sorokopud <e40pud@gmail.com>
Co-authored-by: Joe Peeples <joe.peeples@elastic.co>
Co-authored-by: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com>
(cherry picked from commit 2331998)

docs/detections/rules-ui-create.asciidoc

@@ -459,7 +459,7 @@ run exactly at its scheduled time.
 . Click *Continue*. The *Rule actions* pane is displayed.
 +
 [role="screenshot"]
-image::images/rule-actions.png[]
+image::images/available-action-types.png[Available connector types]
 
 . Do either of the following:
 
@@ -476,37 +476,40 @@ are generated.
 NOTE: To use {kib} Actions for alert notifications, you need the
 https://www.elastic.co/subscriptions[appropriate license] and your role needs *All* privileges for the *Action and Connectors* feature. For more information, see <<case-permissions>>.
 
-. Set when to send notifications:
-
-* *On each rule execution*: Sends a notification every time new alerts are
-generated.
-* *Hourly*: Sends a notification every hour.
-* *Daily*: Sends a notification every day.
-* *Weekly*: Sends a notification every week.
-+
-NOTE: Notifications are sent only when new alerts are generated.
-+
-The available connector types are displayed.
-[role="screenshot"]
-image::images/available-action-types.png[Shows available connector types]
-
-. Select the required connector type, which determines how notifications are sent. For example, if you select the {jira} connector, notifications are sent to your {jira} system.
+. Select a connector type to determine how notifications are sent. For example, if you select the {jira} connector, notifications are sent to your {jira} system.
 +
 NOTE: Each action type requires a connector. Connectors store the
 information required to send the notification from the external system. You can
 configure connectors while creating the rule or on the {kib} Rules and Connectors
 page (*Stack Management* -> *Rules and Connectors* -> *Connectors*). For more
 information, see {kibana-ref}/action-types.html[Action and connector types].
 +
-The selected connector type fields are displayed ({jira} example).
 [role="screenshot"]
-image::images/selected-action-type.png[]
+image::images/available-action-types.png[Available connector types]
+
+. After you select a connector, set its action frequency to define when notifications are sent:
+
+** *Summary of alerts*: Select this option to get a report that summarizes generated alerts, which you can review at your convenience. Alert summaries will be sent at the specified time intervals. 
 +
-. Fill in the fields for the selected connector types. For all connector types, click
-the icon above the `Message` field to add
-<<rule-action-variables, placeholders>> for rule and alert details to the
-notifications.
+NOTE: When setting a custom notification frequency, do not choose a time that is shorter than the rule's execution schedule. 
+
+** *For each alert*: Select this option to ensure notifications are sent every time new alerts are generated.  
+
+. (Optional) Specify additional conditions that need to be met for notifications to send. Click the toggle to enable a setting, then add the required details:
+
+** *If alert matches query*: Enter a KQL query that defines field-value pairs or query conditions that must be met for notifications to send. The query only searches alert documents in the indices specified for the rule.
+** *If alert is generated during timeframe*: Set timeframe details. Notifications are only sent if alerts are generated within the timeframe you define.
+
+. Complete the required connector type fields. Here is an example with {jira}:
+
 +
+[role="screenshot"]
+image::images/selected-action-type.png[]
+
+
+. Use the default notification message or customize it. You can add more context to the message by clicking the icon above the message text box and selecting from a list of available <<rule-action-variables, alert notification variables>>.
+
+
 . Create the rule with or without activation.
 +
 NOTE: When you activate a rule, it is queued, and its schedule is determined by
@@ -517,12 +520,12 @@ minutes at 14:03 but it does not run until 14:04, it will run again at 14:09.
 [[rule-action-variables]]
 ==== Alert notification placeholders
 
-You can use http://mustache.github.io/[mustache syntax] to add the following placeholders to <<rule-notifications, rule action>> fields:
+You can use http://mustache.github.io/[mustache syntax] to add variables to notification messages. The action frequency you choose determines the variables you can select from.   
+
+The following variables can be passed for all rules: 
+
+NOTE: Refer to {kibana-ref}/rule-action-variables.html#alert-summary-action-variables[Action frequency: Summary of alerts] to learn about additional variables that can be passed if the rule's action frequency is **Summary of alerts**. 
 
-* `{{alert.actionGroup}}`: Action group of the alert that scheduled actions for the rule
-* `{{alert.actionGroupName}}`: Human readable name of the action group of the alert that scheduled actions for the rule
-* `{{alert.actionSubgroup}}`: Action subgroup of the alert that scheduled actions for the rule
-* `{{alert.id}}`: ID of the alert that scheduled actions for the rule
 * `{{context.alerts}}`: Array of detected alerts
 * `{{{context.results_link}}}`: URL to the alerts in {kib}
 * `{{context.rule.anomaly_threshold}}`: Anomaly threshold score above which
@@ -541,10 +544,14 @@ execution
 * `{{context.rule.query}}`: Rule query (query rules only)
 * `{{context.rule.references}}`: Rule references
 * `{{context.rule.risk_score}}`: Default rule risk score
++
+NOTE: This placeholder contains the rule's default values even when the *Risk score override* option is used.
 * `{{context.rule.rule_id}}`: Generated or user-defined rule ID that can be
 used as an identifier across systems
 * `{{context.rule.saved_id}}`: Saved search ID
 * `{{context.rule.severity}}`: Default rule severity
++
+NOTE: This placeholder contains the rule's default values even when the *Severity override* option is used.
 * `{{context.rule.threat}}`: Rule threat framework
 * `{{context.rule.threshold}}`: Rule threshold values (threshold rules only)
 * `{{context.rule.timeline_id}}`: Associated Timeline ID
@@ -560,9 +567,13 @@ used as an identifier across systems
 * `{{rule.type}}`: Type of rule
 * `{{state.signals_count}}`: Number of alerts detected
 
-NOTE: The `{{context.rule.severity}}` and `{{context.rule.risk_score}}`
-placeholders contain the rule's default values even when the *Severity override*
-and *Risk score override* options are used.
+The following variables can only be passed if the rule’s action frequency is for each alert: 
+
+* `{{alert.actionGroup}}`: Action group of the alert that scheduled actions for the rule
+* `{{alert.actionGroupName}}`: Human-readable name of the action group of the alert that scheduled actions for the rule
+* `{{alert.actionSubgroup}}`: Action subgroup of the alert that scheduled actions for the rule
+* `{{alert.id}}`: ID of the alert that scheduled actions for the rule
+* `{{alert.flapping}}`: A flag on the alert that indicates whether the alert status is changing repeatedly
 
 [float]
 [[placeholder-examples]]

docs/detections/rules-ui-manage.asciidoc

@@ -136,9 +136,11 @@ Similarly, rules will be skipped if they can't be modified by a bulk edit. For e
 * Bulk edit multiple rules: Select the rules you want to edit, then select an action from the *Bulk actions* menu:
 ** *Index patterns*: Add or delete the index patterns used by all selected rules.
 ** *Tags*: Add or delete tags on all selected rules.
-** *Add rule actions*: Add <<rule-notifications,notification actions>> on all selected rules.
+** *Add rule actions*: Add <<rule-notifications,rule actions>> on all selected rules. If you add multiple actions, you can specify an action frequency for each of them. To overwrite the frequency of existing actions select the option to **Overwrite all selected rules actions**.
+
 +
-NOTE: The action frequency you select applies to all actions (both new and existing) on all selected rules. If you don't want to change the frequency of existing actions, update the rules separately.
+IMPORTANT: After upgrading to 8.8 or later, frequency settings for rule actions created in 8.7 or earlier are moved from the rule level to the action level. The action schedules remain the same and will continue to run on their previously specified frequency (`On each rule execution`, `Hourly`, `Daily`, or `Weekly`). 
+
 +
 NOTE: Rule actions won't run during a {kibana-ref}/maintenance-windows.html[maintenance window]. They'll resume running after the maintenance window ends.
 

docs/upgrade/upgrade-security.asciidoc

@@ -135,3 +135,10 @@ Changes to the indicator match rule's <<rule-ui-advanced-params, default threat
 * If an existing indicator match rule was configured to use threat indicator indices generated from {filebeat} version 7.x, updating the default threat indicator path to `threat.indicator` after you upgrade to {stack} version 8.x and {agent} or {filebeat} version 8.x configures the rule to use threat indicator indices generated by those later versions.
 * You must create separate rules to query threat intelligence indices created by {filebeat} version 7.x and version 8.x because each version requires a different default threat indicator path value. Review the recommendations for <<query-alert-indices, querying alert indices>>.
 
+[float]
+[[rule-action-upgrade]]
+=== Updates to rule actions 
+
+After you upgrade to 8.8 or later, frequency settings for <<rule-notifications,rule actions>> created in 8.7 or earlier are automatically moved from the rule level to the action level. The action schedules remain the same and will continue to run on their previously specified frequency (`On each rule execution`, `Hourly`, `Daily`, or `Weekly`). 
+
+