Add three workflows authoring guidance pages: anatomy, settings, choose-the-right-step#6669
Conversation
…ht-step Three new reference pages under authoring-techniques, adapted from PM internal source material at elastic/workflows-internal-docs: - anatomy.md: every top-level workflow field, what it does, and the execution lifecycle states. Schema verified against kbn-workflows/spec/schema.ts (11 top-level fields confirmed). - settings.md: workflow-wide settings reference covering timeout, timezone, concurrency, max-step-size, and global on-failure. - choose-the-right-step.md: decision aid keyed by intent. No mermaid flowchart (the PM source had one; redundant with the intent tables). Companion updates: - toc.yml: three new entries under Authoring techniques. - workflows.md, authoring-techniques.md: bullet-list signposts to the new pages. - compose-workflows.md, pass-data-handle-errors.md, scheduled-triggers.md, cheat-sheet.md, reference/step-types.md: targeted cross-links into the new pages where existing prose was already gesturing at the same info. Style: per-page anchors on every section, no version references in prose (applies_to handles versioning), REFER TO not "see", em-dashes used sparingly, concrete legal values enumerated in tables, no mermaid. References docs-content-internal#1158. The issue stays open for the two remaining pages tracked there (debugging-and-testing and designing-for-reuse), which need fresh authoring or are blocked on composition GA. Co-authored-by: Cursor <cursoragent@cursor.com>
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. |
Elastic Docs Style Checker (Vale)Summary: 3 warnings, 16 suggestions found
|
| File | Line | Rule | Message |
|---|---|---|---|
| explore-analyze/workflows.md | 19 | Elastic.PluralAbbreviations | Don't use apostrophes when making abbreviations plural. Use 'HQ' instead of ''s'. |
| explore-analyze/workflows/authoring-techniques/anatomy.md | 324 | Elastic.Spelling | 'inis' is a possible misspelling. |
| explore-analyze/workflows/authoring-techniques/choose-the-right-step.md | 34 | Elastic.DirectionalLanguage | Don't use directional language. Use 'in the preceding section' instead of 'listed above'. |
💡 Suggestions (16): Optional style improvements. Apply when helpful.
| File | Line | Rule | Message |
|---|---|---|---|
| explore-analyze/workflows.md | 32 | Elastic.WordChoice | Consider using 'efficient, basic' instead of 'simple', unless the term is in the UI. |
| explore-analyze/workflows/authoring-techniques/anatomy.md | 18 | Elastic.Wordiness | Consider using 'all' instead of 'all of '. |
| explore-analyze/workflows/authoring-techniques/anatomy.md | 119 | Elastic.WordChoice | Consider using 'run, start' instead of 'execute', unless the term is in the UI. |
| explore-analyze/workflows/authoring-techniques/anatomy.md | 141 | Elastic.WordChoice | Consider using 'cancel, stop' instead of 'kill', unless the term is in the UI. |
| explore-analyze/workflows/authoring-techniques/anatomy.md | 143 | Elastic.WordChoice | Consider using 'deactivated, deselected, hidden, turned off, unavailable' instead of 'disabled', unless the term is in the UI. |
| explore-analyze/workflows/authoring-techniques/anatomy.md | 188 | Elastic.Semicolons | Use semicolons judiciously. |
| explore-analyze/workflows/authoring-techniques/anatomy.md | 230 | Elastic.Semicolons | Use semicolons judiciously. |
| explore-analyze/workflows/authoring-techniques/anatomy.md | 230 | Elastic.Semicolons | Use semicolons judiciously. |
| explore-analyze/workflows/authoring-techniques/choose-the-right-step.md | 18 | Elastic.Semicolons | Use semicolons judiciously. |
| explore-analyze/workflows/authoring-techniques/choose-the-right-step.md | 115 | Elastic.WordChoice | Consider using 'stop, exit' instead of 'terminate', unless the term is in the UI. |
| explore-analyze/workflows/authoring-techniques/pass-data-handle-errors.md | 137 | Elastic.Semicolons | Use semicolons judiciously. |
| explore-analyze/workflows/authoring-techniques/settings.md | 28 | Elastic.Wordiness | Consider using 'per' instead of 'as per'. |
| explore-analyze/workflows/authoring-techniques/settings.md | 54 | Elastic.WordChoice | Consider using 'can, might' instead of 'may', unless the term is in the UI. |
| explore-analyze/workflows/authoring-techniques/settings.md | 73 | Elastic.Semicolons | Use semicolons judiciously. |
| explore-analyze/workflows/authoring-techniques/settings.md | 110 | Elastic.Semicolons | Use semicolons judiciously. |
| explore-analyze/workflows/triggers/scheduled-triggers.md | 95 | Elastic.Semicolons | Use semicolons judiciously. |
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.
- Convert tags: [observability, slo] in the complete-shape example to block-style (multi-line) array so the array syntax matches triggers, inputs, outputs, and steps elsewhere in the same snippet. - Split the bundled 'Identity fields' section so name, description, tags, and version each get their own H2, matching the per-field treatment that enabled, triggers, inputs, consts, outputs, settings, and steps already had. - Reorder sections to match the field-reference table. - Add small concrete details to each new section (uniqueness + API-identifier note for name; UI placement for description; yaml example + convention notes for tags; quoting note for version). Co-authored-by: Cursor <cursoragent@cursor.com>
tinnytintin10
left a comment
tinnytintin10
left a comment
There was a problem hiding this comment.
@benironside added some comments in places where we need to make slight changes. re the inputs moving to under the manual trigger, how should we track this? people on 9.4 and earlier will still be able to define it at the root level of the yaml, but people on servreless and in the future in 9.5 will need to capture it under manual.
existing workflows are fine, even though the editor highlights this as an error. They'll continue to work. New workflows, though, in serverless and in 9.5 can't be enabled without moving the input def under the manual trigger
| triggers: # when it runs | ||
| - type: alert | ||
|
|
||
| inputs: # runtime parameters (optional) |
There was a problem hiding this comment.
@benironside one the changes we made was moving input definitions under the manual trigger as opposed to being at the root of the yaml like so:
name: New workflow
enabled: false
description: This is a new workflow
triggers:
- type: manual
inputs:
- name: message
type: string
default: "hello world"for now we can remove this inputs section from this example wf and just keep the alert trigger
There was a problem hiding this comment.
updated yaml
name: slo-breach-response
description: Investigate and mitigate SLO breaches.
enabled: true
tags:
- observability
- slo
version: "1"
triggers:
- type: alert
consts:
severity_threshold: 70
outputs:
- name: result
type: string
settings:
timeout: "5m"
concurrency:
strategy: drop
steps:
- name: investigate
type: elasticsearch.esql.query
with:
query: "FROM ..."
| | `tags` | `string[]` | No | Classification tags. Used for filtering in the list UI and for organizational conventions. | | ||
| | `version` | string | No | Schema version. Defaults to `"1"`. The engine uses this for forward compatibility; leave it unset unless instructed otherwise. | | ||
| | `triggers` | `Trigger[]` | Yes | One or more triggers that start the workflow. Refer to [Triggers](/explore-analyze/workflows/triggers.md). | | ||
| | `inputs` | object or `Input[]` | No | Runtime parameters the workflow accepts. Values provided at invocation time become `{{ inputs.<name> }}` inside the workflow. | |
There was a problem hiding this comment.
for input here we can mention that it's defined under manual trigger
|
|
||
| When you invoke a workflow — manually, on schedule, or through a trigger — the engine puts it through this lifecycle: | ||
|
|
||
| | State | Meaning | |
There was a problem hiding this comment.
we need to include timed out as an execution lifecycle
…le and types schema fixes Addresses Tinsae's CHANGES_REQUESTED review on PR #6669, plus three related schema-correctness fixes uncovered during the audit. Changes: - Complete-shape example: wrapped in applies-switch with two YAML forms. The 9.4 / serverless form keeps inputs at the workflow root; the 9.5+ form nests inputs inside the manual trigger. Trigger changed from alert to manual in both forms so the inputs nesting demo is schema-correct (alert triggers don't accept inputs). - Dedicated inputs section: same applies-switch treatment. Added one-paragraph orientation explaining that existing workflows on 9.5+ continue to run with the top-level form, but new workflows can't be enabled with it. - Field-reference table: inputs row gains a "On 9.5+, defined under the manual trigger" parenthetical with a cross-link to the dedicated inputs section. - Lifecycle table (schema-verified against kbn-workflows/types/v1.ts ExecutionStatus enum): added three missing states (timed_out, waiting_for_input, waiting_for_child), removed the conflated timeout case from cancelled, updated the waiting description so it covers only the wait step, and bumped the summary sentence from four to five terminal states. - Input types list: replaced object (not in the schema) with array (with optional minItems / maxItems), and noted that the legacy array-of-fields form is being migrated to a JSON Schema form. Follow-up issues will track the broader sweep of nested-inputs across other workflows docs, and the future serverless: ga label update once the change ships in serverless. Co-authored-by: Cursor <cursoragent@cursor.com>
|
@tinnytintin10 thanks for the review. Pushed
The field-reference table row for
Input types list. While I was in the section: swapped Follow-up issues (both opened under docs-content-internal#1151):
Re-requesting review when you have a moment. |
…n fallback example
Per Pius Fung's report in the workflows Slack channel
(C08U04SUN49, 2026-06-02), the fallback example referenced
{{steps.<step>.error}} directly. The error context value is an
object (with fields like message, status, etc.), so Liquid
stringifies it as [object Object] when used as a bare value
inside a string message.
Fixes three places in the Fallback section:
- The prose description of the example (line 137).
- The YAML example itself (line 150).
- The "access error information" sentence below the example
(line 153) — clarified to reinforce referencing fields like
.message and .status rather than the object as a whole.
The "Retry" section above already used the correct
.error.status pattern in its condition: KQL example, so the
fallback example was the lone outlier on the page.
Co-authored-by: Cursor <cursoragent@cursor.com>
The applies-switch on this page previously labeled the legacy (root-level inputs) form for both 9.4 stack and serverless, and the new (nested-under-manual) form for 9.5+ stack only. With the schema change now live in serverless, the labels are inverted relative to serverless: drop it from the legacy side and add it to the new side. Both applies-switches in this file are updated, plus the orientation paragraph above the second one (which previously said "on serverless today, inputs sits at the top level"). Closes #6812 in conjunction with the equivalent updates on the #6811 sweep PR. Co-authored-by: Cursor <cursoragent@cursor.com>
Workflows shipped as preview in 9.3 and went GA in 9.4, so the top-level `inputs:` form is the only form on both 9.3 (preview) and 9.4 (GA). Update both applies-switches in this file so the legacy applies-item is labeled `stack: preview 9.3, ga 9.4` instead of just `stack: ga 9.4`. The new-form applies-item (`stack: ga 9.5+, serverless: ga`) is unchanged. Also reword the orientation paragraph above the second applies-switch to match: "On stack 9.4 and earlier, inputs sits at the top level of the workflow. From stack 9.5+ and on serverless, new workflows place inputs inside the manual trigger; existing top-level workflows continue to run." Co-authored-by: Cursor <cursoragent@cursor.com>
The schema change moving inputs: from the workflow root to under
the manual trigger is now live in serverless. Updates the applies-
switch labels, dependent prose, and the migration guide section
to reflect this on all the pages this PR added or modified.
Changes:
Applies-switch labels (5 Tier 1 pages — templating.md, manual-
triggers.md, context-variables.md, composition.md, compose-
workflows.md):
- Legacy form: { stack: ga 9.4, serverless: ga } -> stack: ga 9.4
- New form: stack: ga 9.5+ -> { stack: ga 9.5+, serverless: ga }
Orientation prose on the same 5 pages: "On 9.4 and earlier (and
on serverless today), inputs sits at the top level. On 9.5+,
inputs sits inside the manual trigger." -> "On 9.4, inputs sits
at the top level. On 9.5+ and serverless, inputs sits inside
the manual trigger."
Tier 2 prose-only updates (4 pages — workflows.md, cheat-sheet.md,
enrich-alert-with-threat-intel.md, run-rules-on-demand.md): same
shape ("9.4 and serverless today" -> "9.4 only", "9.5+ structure"
-> "9.5+ and serverless structure").
Migration guide (migrate-from-9-3.md):
- Section title: "Looking ahead to 9.5: inputs schema change" ->
"inputs schema change in 9.5 and serverless".
- applies_to: stack: ga 9.5+ -> stack: ga 9.5+, serverless: ga.
- Removed the "The change is not yet live in serverless." line.
- YAML comment headers updated to mention serverless.
Closes #6812. The corresponding update on anatomy.md ships on the
#6669 fix-up commit (still on the workflows-authoring-guidance
branch, not yet pushed).
Co-authored-by: Cursor <cursoragent@cursor.com>
alaudazzi
left a comment
alaudazzi
left a comment
There was a problem hiding this comment.
I left a few suggestions for your consideration, otherwise LGTM.
There was a problem hiding this comment.
This seems more like a "why" you should use workflow. Maybe you can combine it with the previous section?
| - id: elastic-stack | ||
| --- | ||
|
|
||
| # Workflows [workflows-overview] |
There was a problem hiding this comment.
To make the start of this page a bit more linear, I would:
1/ remove the heading "What are workflow"
2/ move this paragraph to the top of the page, immediately after the title
3/ do not start with an admonition, maybe turn it into regular text, following the introductory paragraph.
|
|
||
| :::: | ||
|
|
||
| ## Field reference [workflows-anatomy-fields] |
There was a problem hiding this comment.
Adding links on the field names to their relevant sections that follow the table would help the navigation
|
|
||
| A workflow definition has eleven top-level fields. Most of them are optional. This page is the reference for all of them. | ||
|
|
||
| ## The complete shape [workflows-anatomy-shape] |
There was a problem hiding this comment.
I'm wondering if we can make this title a bit more explicit for workflow (for SEO purposes):
The complete workflow shape?
Workflow definition?
|
|
||
| Every step also accepts a standard set of common fields for control flow and error handling. Refer to the [Steps overview](/explore-analyze/workflows/steps.md) for those. | ||
|
|
||
| ## The execution lifecycle [workflows-anatomy-lifecycle] |
There was a problem hiding this comment.
Same here -- can we make this title a bit more explicit for workflow (for SEO purposes):
The execution lifecycle of a workflow?
Workflow -- the execution lifecycle?
|
|
||
| For an alphabetical catalog of every step type, refer to the [Step type index](/explore-analyze/workflows/reference/step-types.md). | ||
|
|
||
| ## I want to… [workflows-choose-intent] |
There was a problem hiding this comment.
I like the way this long page is organised :)
You might want to complete each subsection with the full version of the tile "I want to query or modify ES data", "I want to work with data", etc.
This would be for those who scan the page, without the assumption that they read from the top to the bottom of the page, which is rarely the case :-)
| | `strategy` | string | `cancel-in-progress` (cancel the currently running execution when a new one arrives) or `drop` (the new execution is skipped). | | ||
| | `max` | number | Maximum concurrent executions per group. | | ||
|
|
||
| ### Example: per-host serialization [workflows-settings-concurrency-per-host] |
There was a problem hiding this comment.
Adding these examples is great! Could they be made more prominent and put under a section called "Use cases"?
| | `drop` | The ongoing execution is doing valid work you don't want to interrupt. The new trigger would have done the same thing anyway. | | ||
| | `cancel-in-progress` | The new trigger carries fresher information than the ongoing one. You'd rather have the new one complete than the old one. | | ||
|
|
||
| ## Full example [workflows-settings-full-example] |
There was a problem hiding this comment.
This section is a bit confusing. Full example of what? Maybe being more explicit with the title would help.
…6669 Arianna approved with seven inline suggestions for consideration. All seven applied as a single fix-up commit. Branch unchanged otherwise. workflows.md: - Restructured the intro: dropped the "What are workflows" H2, lifted the definition paragraph to immediately follow the H1, and converted the Keep HQ admonition into regular prose beneath it. Loses the workflows-what anchor (no cross-links to it; verified by grep). - Combined the "Who should use workflows" H2 into the end of the "Why use workflows" section as a closing sentence. Loses the workflows-who anchor (no cross-links to it; verified). anatomy.md: - Renamed "The complete shape" -> "The complete workflow shape" for SEO clarity. Anchor unchanged. - Renamed "The execution lifecycle" -> "The execution lifecycle of a workflow" for the same reason. Anchor unchanged. - Linked every field name in the field-reference table to its per-field section anchor. The redundant inline link in the inputs row's description was dropped now that the field name itself carries the cross-link. choose-the-right-step.md: - Dropped the "..." prefix from all ten H3 subsection titles under "I want to..." (line 22). Each H3 now reads as a scannable standalone task. The H2 stays as semantic context for the section, per Arianna's intent. settings.md: - Dropped the "Example:" prefix on the two concurrency-section H3s, reframing them as named use-case patterns: "Serialize per host" and "Cancel in-progress runs for scheduled health checks". Anchors unchanged. - Renamed "Full example" -> "Complete settings example" so the section title is explicit about what example it covers. Anchor unchanged. Co-authored-by: Cursor <cursoragent@cursor.com>
3 participants
Closes #6670.
Summary
Three new authoring-guidance pages under
explore-analyze/workflows/authoring-techniques/, adapted from PM internal source material:anatomy.md(preview) — every top-level workflow field, what it does, and the execution lifecycle states. Field table schema-verified againstkbn-workflows/spec/schema.ts(11 fields confirmed).settings.md(preview)— workflow-wide settings reference coveringtimeout,timezone,concurrency,max-step-size, and globalon-failure.choose-the-right-step.md(preview) — decision aid organized by intent ("I want to query Elasticsearch" → step).Incidental updates: TOC entries plus targeted cross-links from
workflows.md,authoring-techniques.md,compose-workflows.md,pass-data-handle-errors.md,scheduled-triggers.md,cheat-sheet.md, andstep-types.mdinto the new pages where existing prose was already gesturing at the same information.applies-switchlabel conventionThe two
applies-switchblocks inanatomy.md(covering the placement ofinputs) use this convention:inputs:):stack: preview 9.3, ga 9.4manual):{ stack: ga 9.5+, serverless: ga }Workflows shipped as preview in 9.3 and went GA in 9.4, so the legacy form covers both. The new form is required for new workflows on stack 9.5+ and on serverless (per Tinsae's review confirming the schema change is live in serverless).
Generative AI disclosure
Tool(s) and model(s) used: Claude Opus 4.7 via Cursor.
Follow-up issues
Sub-issues under docs-content-internal#1151 (Workflows docs maturity META):
serverless: gato the new (nested) form. Resolved together with this PR and Workflows: sweep nested-inputs YAML structure across remaining docs #6814: the schema change is live in serverless, so the new-form applies-item is labeled{ stack: ga 9.5+, serverless: ga }from the start.