[Alerting V2] [DOCS] [M2] Configure action policy scope using matcher patterns in Alerting v2

[nastasha-solomon]

Summary

Alerting v2 action policies previously scoped by rule type and rule ID fields. This PR removes those fields and replaces them with a matcher-based pattern, allowing more flexible alert scoping. Users creating action policies now define scope via a matcher expression (e.g., event.ruleId: "my-rule-id") rather than selecting a fixed type or rule. Documentation should cover the new matcher syntax and migration from the old type/ruleId approach.

Why this needs docs: Removal of public-facing schema fields and introduction of a new scoping mechanism (matcher) is a user-visible breaking change in configuration that requires doc coverage.

Resources

• PR #272196 — feat(action_policies): remove type/ruleId and scope via matcher

Availability

Channel	Details
Stack	v9.5.0
Serverless	Jun 22–Jun 26
Feature status	technical-preview
Feature flag	None — active by default

---

Created with Docs Quest Scanner by @nastasha-solomon

Suggested edits

Alerting (Kibana) > Action policies

• What the docs say: No Alerting v2 action policy docs exist yet; existing alerting docs cover Kibana Rules only.
• What to add: Create a new section or how-to page explaining action policies in Alerting v2, describing the matcher field syntax and providing examples of scoping policies to specific rules or rule patterns. Note that type and ruleId fields are removed; all scoping is now done through the matcher expression. Stack only, from 9.5.0 (technical preview).

[github-actions]

Elastic Docs AI Menu

Check one box to run an AI workflow for this issue.

• Triage (docs-triage). Status: not started.
• Scope the docs work (docs-issue-scope). Status: not started.

Powered by GitHub Agentic Workflows and docs-actions. For more information, reach out to the docs team.

[nastasha-solomon]

Addressed in #7079.

[nastasha-solomon]

Issue description doesn't quite convey the change, and the "addressed" fix left it half-done

Re-checked this against the implementation, kibana#272196, and against the docs in docs-content#6525 (still open). Two things worth flagging:

1. The issue description conflates two different concepts

The current text says policies "previously scoped by rule type and rule ID fields." That's not quite it. The field that was removed was the action policy's own type field (values global / single_rule), plus a ruleId field used only when type: single_rule. It has nothing to do with the rule's type.

More precisely, what changed:

• Before: a policy had an immutable type (global or single_rule) chosen at creation. single_rule policies also carried a ruleId pointing at the one rule they applied to, and deleting that rule auto-deleted the policy.
• After: type and ruleId are gone entirely (confirmed in the current schema — action_policy_saved_object_attributes/v1.ts, no type/ruleId, only matcher). Every policy is now space-wide, and scope is expressed purely through the KQL matcher — e.g. rule.id: "my-rule-id" to scope to one rule, rule.tags: "checkout" for several, or an empty matcher for everything.

So the accurate framing for docs is: there's no longer a distinct "global" policy type vs. "per-rule" policy type — they're merged into one model, and whether a policy behaves like the old global or per-rule kind falls out of whatever the matcher happens to express. Internally the match-evaluation categories also collapsed from three (direct, global, global-filtered) to two (global, global-filtered) — direct (a policy hard-linked to a rule ID) no longer exists as a category.

Two more user-facing behaviors bundled into #272196 that the issue doesn't currently call out:

• Deleting a rule no longer auto-deletes action policies that were scoped to it (previously true for single_rule policies). Policies now outlive the rules they matched and need to be cleaned up separately.
• Agent Builder's rule-management tooling scopes a policy to a rule via a set_matcher action instead of the old set_type action.

2. The "Addressed in #7079" comment above is only partially true

#7079 (merged into the alerting/experimental-workflows branch, which #6525 is built on) added one sentence to create-configure-action-policy.md's match-conditions section: "There are no separate rule type or rule ID selector fields." But it left the immediately preceding "Policy type" section completely untouched:

An action policy can be global or per-rule... Global: applies to any alert episode in the space... Per-rule: scoped to a single rule... The policy type is set at creation and cannot be changed.

That section describes exactly the removed type/ruleId mechanism as if it's still live, and now directly contradicts the sentence #7079 just added two paragraphs later. The page is self-contradicting as it stands.

The same outdated global/per-rule model also appears in about-action-policies.md (sections "How policy types differ" and "How policies apply to rules" — e.g. "Per-rule policies are bound to a specific rule at creation... The rule association is set at creation and cannot be changed"), which #7079 didn't touch at all.

Suggest: reopen/keep this issue open (or file a follow-up) and, before #6525 merges, rewrite:

• create-configure-action-policy.md — remove the "Select a policy type" global/per-rule section; describe policy creation as destinations + matcher + grouping + frequency, with the matcher as the only scoping mechanism.
• about-action-policies.md — rewrite "How policy types differ" and "How policies apply to rules" to explain matcher-based scoping instead of an immutable type chosen at creation.
• Downstream example tables (route-by-severity.md, severity-escalation.md, re-notification.md) use a "Policy type: Global" row that's technically still accurate post-fix, but should be reframed once "policy type" stops being a distinct selectable concept, so the doc set stays internally consistent.
• action-policy-reference.md and manage-action-policies.md were checked and don't reference the old type/ruleId model — no changes needed there.

[nastasha-solomon]

New details added via b5705db (#6525).