Alert summaries and conditional actions

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[Shows 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, which determines 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[Shows available connector types]
+
+. After you select a connector, set its action frequency to define when notifications are sent:
+
+** *Summary of alerts*: Select this option if you want to reduce the number of notifications you receive without affecting their timeliness. Alert notifications that summarize alerts will be sent at your preferred 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 ({jira} example).
+
 +
+[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, placeholder 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,17 @@ 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 placeholders to <<rule-notifications, rule action>> fields. Different variables are available based on the rule's action frequency. 
+
+If the rule’s action frequency is a summary of alerts, it passes {kibana-ref}/rule-action-variables.html#alert-summary-action-variables[alert summary variables] and `{{context}}` variables, for example `{{context.alerts}}`.
+
+If the rule’s action frequency is not a summary of alerts, it passes any of the following variables:
 
 * `{{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
 * `{{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 +549,14 @@ execution
 * `{{context.rule.query}}`: Rule query (query rules only)
 * `{{context.rule.references}}`: Rule references
 * `{{context.rule.risk_score}}`: Default rule risk score
++
+NOTE: The `{{context.rule.risk_score}}` placeholder contain 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: The `{{context.rule.severity}}` placeholder contain 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,10 +572,6 @@ 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.
-
 [float]
 [[placeholder-examples]]
 ===== Alert placeholder examples

docs/detections/rules-ui-manage.asciidoc

@@ -135,9 +135,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,notification actions>> on all selected rules. 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.
+
 +
-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, 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`). Rules without actions will be snoozed indefinitely. 
+
 
 ** *Update rule schedules*: Update the <<rule-schedule,schedules>> and look-back times on all selected rules.
 ** *Apply Timeline template*: Apply a specified <<timeline-templates-ui, Timeline template>> to the selected rules. You can also choose *None* to remove Timeline templates from the selected rules.

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, 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`). Rules without actions will be snoozed indefinitely. 
+
+