---
title: Create an action policy
description: Create action policies to route alerts to workflows. Scope policies with routing tags or a KQL expression, set batching and frequency, and link rules to policies with matching routing tags.
url: https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/8924/explore-analyze/alerting/esql/action-policies/create-configure-action-policy
products:
- Elastic Documentation
- Kibana
applies_to:
- Elastic Cloud Serverless: Generally available
- Elastic Stack: Experimental in 9.5
---
# Create an action policy
In Kibana Universal Alerting, an action policy connects alerts to the [workflows](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/8924/explore-analyze/workflows) that respond to them. To create one, you set which alerts the policy applies to, how those alerts batch into notifications, how often a workflow can run, and which workflows to invoke.
To start, go to **Alerting** → **Action Policies** in the Observability navigation menu, or find **Action Policies** using the [global search field](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/8924/explore-analyze/find-and-organize/find-apps-and-objects).
To use workflows, your role must have the appropriate privileges and your subscription must include workflows. Refer to the subscription page for [Elastic Cloud](https://www.elastic.co/subscriptions/cloud) and [Elastic Stack/self-managed](https://www.elastic.co/subscriptions) for a breakdown of available features by tier.
## Specify the action policy scope
The policy's scope decides which alerts it applies to, and [frequency](#reduce-noise-grouping) decides how often the policy invokes a workflow for an alert in scope. Leave the scope empty and the policy applies to every alert in the space that [passes the eligibility check](/elastic/docs-content/pull/8924/explore-analyze/alerting/esql/action-policies/about-action-policies#action-policy-gates). Rule events that aren't part of an alert (`type: signal`) stay in `.rule-events`, so the action policy scope doesn't include them.
To narrow the scope of an action policy, use a [KQL expression](#filter-with-kql-expression).
Elastic Cloud Serverless: Generally available Elastic Stack: Planned You can also use [routing tags](#routing-tags), on their own or with an expression. If you use both, the alert's rule has to have at least one of the routing tags and the alert has to match the expression.
### Apply the policy to alerts from specific rules
- Elastic Cloud Serverless: Generally available
- Elastic Stack: Planned
To apply an action policy to a rule's alerts, give the policy and the rule the same routing tag. The policy applies to alerts from every rule that has at least one of its routing tags. If you add the tag to another rule later, the policy also applies to that rule's alerts, and you don't need to edit the policy.
In **Routing tags**, select or enter the tags for the policy. The list recommends the routing tags that your rules already use, most-used first. You can also add a tag that no rule has yet. A policy can have up to 50 routing tags, each up to 128 characters. Matching is exact and case-sensitive, so `checkout` doesn't match `Checkout`.
Routing tags are separate from the rule's **Tags** field. Rule tags label and filter rules, and they don't affect which action policies apply. To add routing tags to a rule, refer to [Add routing tags to a rule](#add-routing-tags).
| To apply the policy to | How to configure it |
|----------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------|
| All alerts that pass the eligibility check, regardless of rule or severity | Leave **Routing tags** and **Match conditions** empty |
| Alerts at a specific severity level | Enter `severity: "critical"` in **Match conditions** |
| Alerts from a group of rules | Add the same routing tag, for example `checkout`, to the policy and to each rule |
| Alerts from one specific rule | Add a routing tag that no other rule uses, for example `notify-checkout-latency`, to the policy and to the rule |
To narrow the scope further, add a [match conditions expression](#filter-with-kql-expression).
### Filter with a KQL expression
Add a **Match conditions** [KQL](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/8924/explore-analyze/query-filter/languages/kql) expression to narrow the policy to the alerts whose fields match it. For example, `severity: "critical"` applies the policy to critical alerts only. For the fields you can use, refer to [Match conditions fields](/elastic/docs-content/pull/8924/explore-analyze/alerting/esql/action-policies/action-policy-reference#action-policy-matcher-fields).
Elastic Cloud Serverless: Generally available Elastic Stack: Planned On a new action policy, expand **Advanced matching** to show **Match conditions**. The expression can use only the [match conditions fields](/elastic/docs-content/pull/8924/explore-analyze/alerting/esql/action-policies/action-policy-reference#action-policy-matcher-fields), so it can't select alerts by the rule's ID, name, or tags. To apply the policy to specific rules, use [routing tags](#routing-tags).
## Add tags to categorize the action policy
- Elastic Cloud Serverless: Unavailable
- Elastic Stack: Planned for removal
- Elastic Stack: Experimental in 9.5
Tags are optional labels you assign to an action policy to categorize it or filter it in the **Action Policies** list. Action policy tags describe the action policy itself, not the alerts it applies to. You can add, edit, or remove tags at any time without affecting routing behavior.
## Set batching and frequency
**Notify per** controls how alerts batch before a workflow is invoked. **Frequency** controls how often the action policy can invoke a workflow for each batch.
| Notify per | What it does | Available Frequency options |
|------------|-----------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------|
| Alert | One workflow invocation for each alert. | - On status change - On status change + repeat at interval - At most once every… - Every evaluation |
| Group | Bundle alerts that share a field value. Specify a **Group by** field such as `data.service.name` or `data.host.name`. | - At most once every… - Every evaluation |
| Digest | One workflow invocation for all matching alerts combined. | - At most once every… (default) - Every evaluation |
**Frequency** limits how often the action policy can invoke a workflow for a given alert or notification group, depending on the **Notify per** setting. The interval resets from the last time a workflow was invoked, so successive notifications stay at least `interval` apart. Set a duration such as `1h` or `30m`.
### Re-notify when severity escalates
`On status change` re-notifies only when the alert's status changes, not when its severity changes. Once the action policy has invoked a workflow and the status stays the same, the throttle blocks re-notification, even if severity later escalates from `low` to `critical`.
To get a notification for the escalation, do either of the following:
- Create separate action policies scoped to specific severity levels. For examples, refer to [Manage severity escalation notifications](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/8924/explore-analyze/alerting/esql/action-policies/severity-escalation).
- Set a time-based frequency such as `At most once every 1h`, so the action policy invokes a workflow again after the interval regardless of severity or status changes. For examples, refer to [Re-notify for persistently active alerts](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/8924/explore-analyze/alerting/esql/action-policies/re-notification).
## Select workflows to invoke
An action policy needs at least one destination. In **Destination**, attach the [workflows](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/8924/explore-analyze/workflows) that run when the action policy notifies. You can attach workflows you built earlier, create an email or Slack workflow without leaving the action policy, or do both. You can add or remove destinations later by editing the action policy.
### Attach an existing workflow
In **Workflows**, search for a workflow by name and select it. Select as many as you need. Use an existing workflow for anything beyond a single message, such as opening a ticket, calling a webhook, or running several steps in order.
If the workflow doesn't exist yet, select **Create a workflow** to build it in the **Workflows** app in a new tab, then return to the action policy and select it.
### Create an email or Slack workflow
- Elastic Cloud Serverless: Generally available
- Elastic Stack: Planned
If all the action policy needs to do is send an email or post a Slack message, build that workflow in the action policy itself:
1. Select **Create Email workflow** or **Create Slack workflow**.
2. Select a **Connector**, or select **+ Create new connector** to add one. For Slack, also select the **Channel**.
3. In **Parameters**, write the message in YAML. An email takes `to`, `subject`, and `message`. A Slack message takes `text`.
To put alert details in the message, reference the dispatcher payload with `{{inputs.payload.}}`, for example `{{inputs.payload.policyId}}`, `{{inputs.payload.groupKey}}`, or `{{inputs.payload.alerts}}`.
Kibana creates a single-step workflow for each one when you save the action policy and attaches it as a destination. These are ordinary workflows, so you can open them in **Workflows** afterwards to edit them or attach them to another action policy. If the action policy fails to save, Kibana deletes the workflows it created for it.
### Create a notification from the rule form
- Elastic Cloud Serverless: Unavailable
- Elastic Stack: Planned for removal
- Elastic Stack: Experimental in 9.5
If you don't have a workflow ready, set up an email or Slack notification while you create a rule. When you save, Kibana creates the workflow and an action policy that matches that rule's alerts by `rule.id`.
## Link a rule to action policies
To send a rule's alerts through an action policy that uses routing tags, add one of the policy's tags to the rule. To confirm which policies apply to a rule, check the rule's applied policies.
### Add routing tags to a rule
- Elastic Cloud Serverless: Generally available
- Elastic Stack: Planned
To link a rule to an action policy, add one of the policy's routing tags to the rule. Only rules that open alerts can have routing tags. A rule that only writes rule events (`type: signal`) can't, because action policies don't evaluate those events.
1. Create or edit the rule, then go to the **Actions** step.
2. Under **Action policies**, add tags in **Routing tags**. As you enter a tag, each suggestion shows how many action policies use it. A rule can have up to 20 routing tags, each up to 128 characters.
3. Check **Applied policies**. The policy appears with a tag icon (`tag`), and its tooltip lists the shared tag under **Matching routing tags**.
4. Save the rule. The link takes effect when you save.
To set routing tags in a YAML rule definition, use [`metadata.routing_tags`](/elastic/docs-content/pull/8924/explore-analyze/alerting/esql/rules/yaml-rule-schema-reference#metadata-fields).
### Check which policies apply to a rule
When you create or edit a rule that opens alerts, the **Actions** step lists the policies that apply to those alerts under **Action policies**. Select a policy's name to open it for editing in a new tab.
The list also indicates why each policy applies.
To add a policy without leaving the rule, select **Create action policy** in **Applied policies**, then give the new policy one of the rule's routing tags. Each entry in **Applied policies** shows the connector types its workflows use, along with a badge or icon:
- A **Catch-all** badge means the policy has no routing tags and no expression, so it applies to alerts from every rule.
- A tag icon (`tag`) means the rule and the policy share routing tags. The tooltip lists them under **Matching routing tags**.
- An **Expression** badge means the policy also has a KQL expression. Kibana evaluates that expression against alert data when the policy runs, so the list can't confirm it in advance. A policy scoped by an expression alone doesn't appear in the list at all, but it can still apply once the rule opens an alert.
The list covers policies whose **Match conditions** expression matches the rule's ID, name, or tags. Policies that match every rule appear under **Global policies**, and policies that match this rule in particular appear under **Matching global policies**.
## Related pages
- [Manage action policies](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/8924/explore-analyze/alerting/esql/action-policies/manage-action-policies): Enable, disable, snooze, and rotate API keys after setup.
- [Action policy reference](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/8924/explore-analyze/alerting/esql/action-policies/action-policy-reference): Look up match condition fields, grouping modes, and frequency options.
- [About action policies](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/8924/explore-analyze/alerting/esql/action-policies/about-action-policies): Understand the eligibility, scope, and frequency gates that determine when workflows are invoked.