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 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,14 @@ 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 the following placeholders to <<rule-notifications, rule action>> fields. Different variables are provided based on the rule's action frequency. 
+
+If the rule’s action frequency is a summary of alerts, it passes variables that summarize alerts. Refer to {kibana-ref}/rule-action-variables.html#alert-summary-action-variables[Action frequency: Summary of alerts] for additional alert summary variables. 
+
+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.
 
-* `{{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
@@ -558,11 +563,15 @@ used as an identifier across systems
 * `{{rule.spaceId}}`: Space ID of the rule
 * `{{rule.tags}}`: Tags of the rule
 * `{{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.
+If the rule’s action frequency is not a summary of alerts (per each alert), it passes 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.
+* `{{state.signals_count}}`: Number of alerts detected
 
 [float]
 [[placeholder-examples]]

docs/detections/rules-ui-manage.asciidoc

@@ -139,6 +139,9 @@ Similarly, rules will be skipped if they can't be modified by a bulk edit. For e
 +
 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: In 8.8, action frequencies can be set for individual actions, and you can specify if notifications are sent when an alert is generated or at a custom alert summary interval. When you upgrade to 8.8, action-level frequency settings are applied to rules that have actions and were created in 8.7 or earlier. The frequency setting will default to the action frequency that was chosen for the rule before the upgrade. 
+
 ** *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.
 . On the flyout that opens, update the settings.

docs/upgrade/upgrade-security.asciidoc

@@ -135,3 +135,8 @@ 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 
+
+In 8.8, <<rule-notifications,rule action frequencies>> can be set for individual actions, and you can specify if notifications are sent when an alert is generated or at a custom alert summary interval. When you upgrade to 8.8, action-level frequency settings are applied to rules that have actions and were created in 8.7 or earlier. The frequency setting will default to the action frequency that was selected for the rule before you upgraded.