[Alerting V2][Serverless & 9.5][M2] Adds docs for action policies, workflows, and notifications#6525
Draft
nastasha-solomon wants to merge 24 commits into
Draft
[Alerting V2][Serverless & 9.5][M2] Adds docs for action policies, workflows, and notifications#6525nastasha-solomon wants to merge 24 commits into
nastasha-solomon wants to merge 24 commits into
Conversation
3 tasks
Contributor
Elastic Docs AI PR menuCheck the box to run an AI review for this pull request.
Powered by GitHub Agentic Workflows and docs-actions. For more information, reach out to the docs team. |
Contributor
Contributor
Elastic Docs Style Checker (Vale)Summary: 3 warnings, 10 suggestions found
|
| File | Line | Rule | Message |
|---|---|---|---|
| explore-analyze/alerting/kibana-alerting-experimental/workflows-alerting.md | 13 | Elastic.EndPuntuaction | Don't end headings with punctuation. |
| explore-analyze/alerting/watcher/actions.md | 150 | Elastic.QuotesPunctuation | Place punctuation inside closing quotation marks. |
| explore-analyze/workflows/triggers/event-driven-triggers.md | 361 | Elastic.Spelling | 'unsnoozed' is a possible misspelling. |
💡 Suggestions (10): Optional style improvements. Apply when helpful.
| File | Line | Rule | Message |
|---|---|---|---|
| explore-analyze/alerting/kibana-alerting-experimental/action-policies/about-action-policies.md | 71 | Elastic.WordChoice | Consider using 'can, might' instead of 'may', unless the term is in the UI. |
| explore-analyze/alerting/kibana-alerting-experimental/action-policies/about-action-policies.md | 80 | Elastic.WordChoice | Consider using 'deactivate, deselect, hide, turn off' instead of 'disable', unless the term is in the UI. |
| explore-analyze/alerting/kibana-alerting-experimental/action-policies/action-policy-reference.md | 98 | Elastic.WordChoice | Consider using 'deactivate, deselect, hide, turn off' instead of 'disable', unless the term is in the UI. |
| explore-analyze/alerting/kibana-alerting-experimental/action-policies/create-configure-action-policy.md | 79 | Elastic.WordChoice | Consider using 'deactivate, deselect, hide, turn off' instead of 'disable', unless the term is in the UI. |
| explore-analyze/alerting/kibana-alerting-experimental/action-policies/manage-action-policies.md | 8 | Elastic.WordChoice | Consider using 'deactivate, deselect, hide, turn off' instead of 'disable', unless the term is in the UI. |
| explore-analyze/alerting/kibana-alerting-experimental/action-policies/manage-action-policies.md | 13 | Elastic.WordChoice | Consider using 'deactivate, deselect, hide, turn off' instead of 'disable', unless the term is in the UI. |
| explore-analyze/alerting/kibana-alerting-experimental/action-policies/manage-action-policies.md | 34 | Elastic.WordChoice | Consider using 'deactivate, deselect, hide, turn off' instead of 'disable', unless the term is in the UI. |
| explore-analyze/alerting/kibana-alerting-experimental/action-policies/manage-action-policies.md | 36 | Elastic.WordChoice | Consider using 'deactivate, deselect, hide, turn off' instead of 'disable', unless the term is in the UI. |
| explore-analyze/alerting/kibana-alerting-experimental/notifications-actions.md | 35 | Elastic.WordChoice | Consider using 'deactivate, deselect, hide, turn off' instead of 'disable', unless the term is in the UI. |
| explore-analyze/alerting/watcher/actions.md | 150 | Elastic.FirstPerson | Use caution when using first-person pronouns such as 'me.' |
The Vale linter checks documentation changes against the Elastic Docs style guide. To use Vale locally or report issues, refer to Elastic style guide for Vale.
Adds six pages under kibana-alerting-experimental/: - workflows-alerting.md: workflow overview and runtime execution order - notifications.md: action policy overview with dispatcher behavior - notifications/create-configure-action-policy.md: creation guide - notifications/action-policy-reference.md: full field reference - notifications/manage-action-policies.md: management operations - notifications/notification-gating.md: acknowledge/snooze/deactivate gating Incorporates additions from PR #6395 including the new notification-gating page. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
nastasha-solomon
force-pushed
the
alerting/experimental-workflows
branch
from
2b99342 to
9bdc843
Compare
2 tasks
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
nastasha-solomon
changed the title
…6639) <!-- Thank you for contributing to the Elastic Docs! 🎉 Use this template to help us efficiently review your contribution. --> ## Summary <!-- Describe what your PR changes or improves. If your PR fixes an issue, link it here. If your PR does not fix an issue, describe the reason you are making the change. --> Updates the action policy docs for the experimental alerting features with content from eight doc issues. Following the tech preview principle of accuracy over comprehensiveness, changes focus on stable concepts and system behavior rather than UI details that are subject to change. ### Per-rule action policies ([#6613](#6613)) The most significant conceptual change in this batch. The previous docs described all action policies as global within a space. PR #268006 introduced a `global` / `single_rule` type discriminator, making the existing description factually incorrect. **`notifications.md`** — Updated "What is an action policy" to define both policy types, their scoping rules, and when to use each. Updated "How policies apply to rules" to distinguish global and per-rule scoping. Updated "Why policies are separate from rules" to reflect that per-rule policies exist for rule-specific routing. **`create-configure-action-policy.md`** — Added a **Policy type** field section explaining the global/per-rule distinction, the immutability constraint, and when to choose each type. Updated the opening paragraph and the match conditions scope description to reflect both types. ### Policy tags ([#6616](#6616)) PR #261008 added a `tags` field to notification policies across the full stack. **`create-configure-action-policy.md`** — Added a **Tags** field section explaining that policy tags are organizational labels distinct from rule tags and do not affect routing behavior. ### Quick filter KQL fields ([#6608](#6608)) PR #261601 added Rule, Status, and Tags quick filter pickers to the match conditions form. The pickers generate `rule.id`, `episode_status`, and `rule.tags` KQL respectively. **`action-policy-reference.md`** — Added `rule.tags` to the match conditions field reference table. This field was missing but is now surfaced by the quick filters and used in examples across the docs. **`create-configure-action-policy.md`** — Updated the match conditions example from `data.severity` to `rule.tags: "payment-service"` to reflect the fields that quick filters generate. ### Maintenance window suppression ([#6416](#6619)) PR #267771 added backend suppression logic for maintenance windows in the dispatcher. **`action-policy-reference.md`** and **`notifications.md`** — Updated the `suppressed` dispatch outcome description to include maintenance windows as a cause alongside acknowledge, snooze, and deactivate. ### View policy details ([#6419](#6619)) PR #264497 added a details flyout to the Action policies list page. **`manage-action-policies.md`** — Added a "View policy details" section describing that a policy's full configuration and all per-policy actions are accessible from the list page. UI mechanics (flyout vs. dedicated page) are omitted as the IA is not yet stable. ### Policy execution history ([#6501](#6501)) PR #266775 added a Policy Execution History UI and API. **`manage-action-policies.md`** — Added an "Execution history" section describing how to query dispatch outcomes per policy using the `.alert-actions` data stream. The section points to the existing dispatch outcomes reference rather than documenting the UI, which is subject to change. ### Out of scope for this PR - **[#6498](#6498 (optional `matcher` query parameter on the data fields suggestions endpoint): API reference detail with no conceptual home yet. - **[#6617](#6617 (grouping modes and frequency strategies redesign): The existing reference and create-configure pages already cover this content accurately. No new stable concepts to add at the tech preview stage. ## Generative AI disclosure <!-- To help us ensure compliance with the Elastic open source and documentation guidelines, please answer the following: --> 1. Did you use a generative AI (GenAI) tool to assist in creating this contribution? - [x] Yes - Cursor + Claude - [ ] No <!-- 2. If you answered "Yes" to the previous question, please specify the tool(s) and model(s) used (e.g., Google Gemini, OpenAI ChatGPT-4, etc.). Tool(s) and model(s) used: -->
kdelemme
reviewed
May 27, 2026
…tions.md Co-authored-by: Kevin Delemme <kdelemme@gmail.com>
…s from June 3, 2026 (#6846) <!-- Thank you for contributing to the Elastic Docs! 🎉 Use this template to help us efficiently review your contribution. --> ## Summary Updates the action policy, reference, and workflow docs for the experimental alerting features with content from five M2 doc issues. Following the tech preview principle of accuracy over comprehensiveness, content additions focus on confirmed stable behavior. UI details subject to change and API schema changes with no existing reference docs are deferred. ### `episode.severity` as a first-class match condition field (#6834, #6689) Issues #6834 and #6689 tracked the same underlying feature from two angles. #6689 documented the rule-side contract: severity is populated when a rule's ES|QL query includes a `severity` column with a recognized value (`info`, `low`, `medium`, `high`, `critical`); unrecognized values are silently ignored; the field is absent on recovery events. #6834 documented the dispatcher side: `episode.severity` is now available in the matcher context, making `data.severity` — previously the only way to match on severity — the legacy approach. **`action-policy-reference.md`** — Added `episode.severity` to the match conditions field reference table with its full behavioral contract: populated from the rule's ES|QL `severity` column, case-insensitive, unrecognized values silently ignored, not set during recovery. Updated the introductory KQL example from `data.severity: "critical"` to `episode.severity: "critical"`. Updated the `data.*` row to clarify it covers rule-specific payload fields not available as standard episode fields, removing the misleading `data.severity: "critical"` example. Narrowed the content-needed comments to three remaining open questions: whether `episode.severity_max` is also available, whether a mid-episode severity change triggers re-evaluation, and a placeholder for a future cross-link to rule authoring docs once they exist. **`create-configure-action-policy.md`** — Updated the match conditions example to lead with `episode.severity: "critical"` for PagerDuty routing, with `rule.tags` as a secondary scoping example. Narrowed the content-needed comment to the backward-compatibility question of whether `data.severity` on legacy rules should be documented as an alternative or removed from guidance. **`notifications-actions.md`** — Updated the "Why policies are separate from rules" example from `data.severity: "critical"` to `episode.severity: "critical"`. This was the one remaining reference to `data.severity` as a severity matcher outside the reference table. The full ES|QL severity authoring contract (column name, case-insensitivity, silent-ignore behavior) belongs in rule authoring docs. Those docs don't exist yet (#6689 notes this). A comment in the `episode.severity` table row flags this as a future cross-link target. ### Matcher context `rule.*` fields reduced to id, name, and tags (#6836) PR #271768 simplified `MatcherContextRule` to expose only `id`, `name`, and `tags`. The fields `rule.description`, `rule.enabled`, `rule.createdAt`, and `rule.updatedAt` were removed from the matcher context. The same PR added `rule.name`, `rule.tags`, and `rule.description` as payload variables in single-step workflow templates. **`action-policy-reference.md`** — Removed `rule.description` and `rule.enabled` rows from the match conditions field reference table. Both were previously listed as available matcher fields; both were removed in this PR. `rule.id`, `rule.name`, and `rule.tags` remain. The workflow payload variable additions (`{{rule.name}}`, `{{rule.tags}}`, `{{rule.description}}`) are not documented here — no workflow payload template docs exist yet. When those docs are written, they should document these three variables with example template snippets such as `Alert from rule: {{rule.name}}`. ### Notification policy form: Workflows enablement prerequisite and UI labels (#6843) PR #260796 introduced a warning callout in the notification policy form when `workflows:ui:enabled` is disabled on Stack, directing users to Advanced Settings to enable it. In 9.4, workflows was enabled by default, so there's no need to doc this as a pre-req. **`workflows-alerting.md`** — Added a note inside the existing important callout explaining that on Stack, workflows must be enabled before they can be used as destinations in action policies. Includes the path (**Stack Management > Advanced Settings**) and the setting key (`workflows:ui:enabled`). UI label changes from this PR ("Policy scope" section header, "Create a workflow" link in the destination field) are omitted — these are unstable IA details that will be documented once the UI stabilizes post-preview. ### Creator and updater display names in the policy list (#6845) PR #268426 standardized Alerting v2 on user profile UIDs for `createdBy` and `updatedBy` fields, resolving them to display names on read via the Kibana user profiles API. The policy list page and details flyout now show the full display name of the creator or last updater. **`manage-action-policies.md`** — Added a sentence noting that the policy list shows the display name of the user who created the policy and the user who last updated it. The API schema breaking change (`createdByUsername`/`updatedByUsername` fields removed in 9.5.0) is not documented here — no public API reference exists yet for the Alerting v2 action policy API, so there is nothing to update. When that reference is written, it should document `createdBy`/`updatedBy` as user profile UIDs and note the removal as a breaking change for pre-release integrations. ## Generative AI disclosure 1. Did you use a generative AI (GenAI) tool to assist in creating this contribution? - [x] Yes - Cursor + Claude - [ ] No
nastasha-solomon
changed the title
nastasha-solomon
changed the title
…s from June 22, 2026 (#7079) <!-- Thank you for contributing to the Elastic Docs! 🎉 Use this template to help us efficiently review your contribution. --> ## Summary <!-- Describe what your PR changes or improves. If your PR fixes an issue, link it here. If your PR does not fix an issue, describe the reason you are making the change. --> Updates action policy, workflow, and notification docs for the experimental alerting system with content from five M2 doc issues. Following the tech preview principle of accuracy over comprehensiveness, additions focus on stable concepts — architectural constraints, when to choose features, and how the system works. UI step-by-step procedures, unstable IA details, and unconfirmed API identifiers are deferred to post-preview docs. ### Action policies target only Alert mode rules (#6877) PR #272302 fixes a bug where rule quick filters in the action policy form surfaced all rule kinds instead of alert-kind rules only. **`notifications-actions.md`** — Integrated the Alert mode constraint into the opening paragraph so readers immediately understand the scope of action policies. The specific UI detail about quick filters is omitted; no existing docs described the incorrect behavior. **`action-policies/create-configure-action-policy.md`** — Added the Alert mode constraint as the opening sentence of the Policy type section so it reads as a foundational rule before the global/per-rule choice, not as an afterthought. ### Action policy scope uses matcher expressions only (#7012) PR #272196 removes `type` and `ruleId` fields from action policy scope and replaces them with a matcher-based pattern. **`action-policies/create-configure-action-policy.md`** — Added a sentence to the Match conditions section clarifying that the matcher expression is the sole mechanism for scoping a policy. There are no separate rule type or rule ID selector fields. The existing docs already reflected the KQL-based approach; this change makes the constraint explicit for users who may have encountered older API references. ### Execution history search and outcome filter (#7011) PR #272914 adds a search bar and outcome filter to the Execution history Policies tab. **`action-policies/manage-action-policies.md`** — Added a conceptual sentence noting that execution history supports search by policy name, rule name, or saved-object ID, and filtering by outcome. Explains that the new-events count reflects active filters. UI control details are omitted. Also updated the section heading from "Enable and snooze" to "Enable, disable, and snooze" so the section is findable by scanning. ### Alert episode lifecycle triggers (#6873, #7006) PR #268915 registers an `episodeAssigned` workflow trigger. PR #272504 adds triggers for eight alert episode lifecycle events including activation, deactivation, snooze, acknowledge, assign, unassign, and tag. **`workflows-alerting.md`** — Restructured the page to document both integration pathways: action policy-driven workflows and event-driven lifecycle triggers. Added a new Alert episode lifecycle triggers section with a table of all eight trigger IDs, the common event payload fields (`episodeId`, `ruleId`, `spaceId`), an example condition, and guidance on when to use triggers vs action policies. Marked the section as Stack only from 9.5.0. A TODO comment flags a discrepancy between trigger ID prefixes (`alertingV2.*` in issue #6873 vs `alerting.*` in issue #7006) for engineering confirmation before publishing. ### Description field cleanup (all pages) Replaced `{{alerting-v2-system}}` with the literal string "experimental alerting system" in the `description` frontmatter field across all six pages in the set. The variable is not valid in that field. ### Scope statement improvements (all pages) Added or sharpened "This page covers..." statements on `notifications-actions.md`, `workflows-alerting.md`, and `action-policies/reduce-notification-noise.md` to explicitly tell readers what they will understand or be able to do after reading. --- ### Issues confirmed as already covered or out of scope No issues from this batch were already covered or out of scope. The trigger ID prefix discrepancy between issues #6873 and #7006 is flagged with a TODO comment in `workflows-alerting.md` and is not blocking publication of the stable concepts documented here. ## Generative AI disclosure <!-- To help us ensure compliance with the Elastic open source and documentation guidelines, please answer the following: --> 1. Did you use a generative AI (GenAI) tool to assist in creating this contribution? - [x] Yes - Cursor + Claude - [ ] No <!-- 2. If you answered "Yes" to the previous question, please specify the tool(s) and model(s) used (e.g., Google Gemini, OpenAI ChatGPT-4, etc.). Tool(s) and model(s) used: --> --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
…ge, common scenarios, and nav restructure (#7105) <!-- Thank you for contributing to the Elastic Docs! 🎉 Use this template to help us efficiently review your contribution. --> ## Summary <!-- Describe what your PR changes or improves. If your PR fixes an issue, link it here. If your PR does not fix an issue, describe the reason you are making the change. --> This PR restructures the experimental alerting (alerting v2) notification and action policies documentation. The main goals are to separate conceptual content from how-to content, improve navigation, and add new pages that address common user questions about severity-based routing and notification behavior. ### Structural changes - **Splits `notifications-actions.md`** into a brief section landing page and a new dedicated conceptual page (`about-action-policies.md`), so that the landing page orients users and the conceptual content has its own focused home. - **Moves `workflows-alerting.md`** from a top-level sibling of `notifications-actions.md` to a child, grouping all notification-related content under one section in the sidebar. - **Adds `common-action-policy-scenarios.md`** — a new page with annotated, table-backed examples for three common scenarios: routing by severity, managing notifications across severity changes, and re-notifying for persistently active episodes. ### Content changes - **`notifications-actions.md`** — Rewritten as a brief landing page explaining the two-layer model (workflows + action policies) with a get-started flow and an in-section index. - **`about-action-policies.md`** (new) — Consolidates conceptual content: the three gates (suppression, match conditions, frequency), policy types (global vs per-rule), how the dispatcher evaluates policies, and a tip callout explaining how severity changes interact with policy matching. - **`workflows-alerting.md`** — Restructured with a new "How the alerting system connects to workflows" section containing the two pathways as subsections, with intro sentences added to each. - **`create-configure-action-policy.md`** — Adds a note in the Frequency section explaining the `on_status_change` + severity change interaction and when to use a time-based throttle instead. - **`action-policy-reference.md`**, **`reduce-notification-noise.md`**, **`create-configure-action-policy.md`** — Cross-links updated to reflect the new page structure. - `episode.severity` replaced with `severity` throughout the action policies pages. ### Navigation (`toc.yml`) ``` Notifications and actions ← section landing page ├── Connect workflows ├── About action policies ← new ├── Common scenarios ← new ├── Create an action policy ├── Action policy reference ├── Manage action policies └── Reduce notification noise ``` ## Generative AI disclosure <!-- To help us ensure compliance with the Elastic open source and documentation guidelines, please answer the following: --> 1. Did you use a generative AI (GenAI) tool to assist in creating this contribution? - [x] Yes - Cursor + Claude - [ ] No <!-- 2. If you answered "Yes" to the previous question, please specify the tool(s) and model(s) used (e.g., Google Gemini, OpenAI ChatGPT-4, etc.). Tool(s) and model(s) used: -->
Member
Author
|
Reverting back to draft state to add docs for using AB to create action policies. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Contributes to https://github.com/elastic/docs-content-internal/issues/919 by adding docs that explain how to set up actions and notifications for rules in alerting v2.
Note about docs strategy
The goal for experimental docs is accuracy over comprehensiveness. To achieve this, the docs will primarily focus on stable concepts, such as why users should choose alerting v2, when they should choose certain features, and how the system generally works (example below). Lower-level details about the "how" and UI details for unstable features/IA will be omitted for now. That content will be drafted and published after the experimental release goes public.
Review requests
This PR needs a technical and editorial review. Instructions for each are below.
🔧 Technical reviewer
Please focus your review on accuracy of facts, names, and structure only. For example, please verify that field names, values, and descriptions in reference material is accurate and matches the the current implementation. When reviewing conceptual material, please check that definitions are technically accurate and reflect the current engineering design.
✏️ Editorial reviewer
This PR adds pages covering workflows, action policies, notification routing, and notification gating in alerting v2. These pages build on the overview introduced in #6521. As you're reviewing the content, please focus on writing quality, clarity, and how the content serves a reader who's seeing this system for the first time.
Previews
🤖 Generated with Claude Code