elastic / elastic/docs-content
[Alerting V2] Rule artifacts (runbooks and dashboards) now use structured per-type fields, with better handling of deleted dashboards
- Dominant language
- No language data
- Stars
- 47
- Forks
- 261
- Avg merge
- 3d 12h
- Merged PRs (30d)
- 116
Description
## Summary
Rule artifacts (runbooks and linked dashboards) now use structured, per-type fields instead of a single string value:
| Before | After |
|---|---|
| `artifacts[].value: string` | `artifacts[].data: object` |
**Validation is now per artifact type:** a runbook needs non-blank `content` (up to 50,000 characters); a dashboard needs a `dashboardId`; any other field defaults to a 1,024-character cap.
**Also new:** a rule whose linked dashboard was deleted now shows a "Dashboard deleted" indicator and survives saving, instead of being silently dropped.
This is a breaking change to the YAML `artifacts[].value` field specifically — existing saved rules are migrated automatically on read, but any docs or examples using `value` are now wrong.
**Why this needs docs:** The YAML schema reference documents the exact field this PR removed, and neither existing rule-authoring page mentions dashboards as an artifact type at all.
## Resources
- PR [#281751](https://github.com/elastic/kibana/pull/281751) — [Alerting V2] Change artifacts schema
- Product issue: https://github.com/elastic/rna-program/issues/764
- Related: [#284481](https://github.com/elastic/kibana/pull/284481) — companion PR adding the inline "Attach related dashboards" UI (tracked separately)
## Availability
| Channel | Details |
|---------|---------|
| **Stack** | v9.6.0 |
| **Serverless** | Aug 12–Aug 19 |
| **Feature status** | Technical preview |
| **Feature flag** | Requires the Alerting v2 preview to be enabled |
---
*Created with [Docs Quest Scanner](https://github.com/florent-leborgne/docs-quest-scanner) by @nastasha-solomon*
## Suggested edits
### 1. [YAML rule schema reference](https://www.elastic.co/docs/explore-analyze/alerting/experimental-alerting-system/rules/yaml-rule-schema-reference) > Artifact fields — breaking change
- **What's wrong:** Documents `artifacts[].value` (string, markdown content) as the field for artifact content. That field no longer exists.
- **What to add:** Replace `artifacts[].value` with `artifacts[].data` (object), and document the per-type shape:
- `runbook`: `{ content: string }` — required, non-blank, max 50,000 characters
- `dashboard`: `{ dashboardId: string }` — required
- any other/unregistered type: unvalidated `data`, other fields default to a 1,024-character cap
Update the `type` field's example to list both `runbook` and `dashboard`. Applies from 9.6.0 (technical preview) and in serverless.
### 2. [Tags and runbooks in the experimental alerting system](https://www.elastic.co/docs/explore-analyze/alerting/experimental-alerting-system/rules/configure-rule-tags)
- **What's wrong:** This is the dedicated page for rule artifacts, but it only covers tags and runbooks — dashboards aren't mentioned as an artifact type anywhere, despite having their own UI on the rule details page.
- **What to add:** Add a "Dashboards" subsection alongside Tags and Runbooks (or retitle the page, at the writer's discretion) covering: how to link a dashboard for investigation context, and that a rule whose linked dashboard was deleted shows a "Dashboard deleted" indicator rather than losing the link silently. Applies from 9.6.0 (technical preview) and in serverless.
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.