elastic / elastic/docs-content
Workflows 9.5 docs: apply nested-inputs YAML structure uniformly across all workflows docs
- Dominant language
- No language data
- Stars
- 47
- Forks
- 261
- Avg merge
- 3d 12h
- Merged PRs (30d)
- 116
Description
Sub-issue of [docs-content-internal#1151](https://github.com/elastic/docs-content-internal/issues/1151) (Workflows docs maturity META).
## Context
In 9.5, the workflow YAML schema moves `inputs:` from the top of the workflow to inside the `manual` trigger:
- **9.4 stack and serverless (today):** `inputs:` lives at the workflow root, alongside `triggers:`, `consts:`, etc.
- **9.5+ stack:** `inputs:` is nested inside `triggers: - type: manual`. Existing workflows authored with the top-level form continue to run, but new workflows can't be enabled with the top-level form.
PR [#6669](https://github.com/elastic/docs-content/pull/6669) established the documentation pattern: an `applies-switch` showing both YAML forms. See the [anatomy.md complete-shape example](https://github.com/elastic/docs-content/blob/main/explore-analyze/workflows/authoring-techniques/anatomy.md#workflows-anatomy-shape) and the [`inputs` field section](https://github.com/elastic/docs-content/blob/main/explore-analyze/workflows/authoring-techniques/anatomy.md#workflows-anatomy-inputs) for the template.
## Scope
Sweep every other Workflows page that shows root-level `inputs:` and apply the same applies-switch pattern, or otherwise reflect the new structure as appropriate to the page's purpose.
Known pages to audit and update:
- [`reference/cheat-sheet.md`](https://github.com/elastic/docs-content/blob/main/explore-analyze/workflows/reference/cheat-sheet.md) — workflow anatomy snippet at the top of the page.
- [`authoring-techniques/migrate-from-9-3.md`](https://github.com/elastic/docs-content/blob/main/explore-analyze/workflows/authoring-techniques/migrate-from-9-3.md) — currently has no mention of this schema change. Add a section.
- [`authoring-techniques/pass-data-handle-errors.md`](https://github.com/elastic/docs-content/blob/main/explore-analyze/workflows/authoring-techniques/pass-data-handle-errors.md) — any `inputs:` references in the data-flow examples.
- Use-case how-tos under `use-cases/` that include workflow YAML with `inputs:`.
- The build-your-first-workflow tutorial under `get-started/`.
Audit step before drafting: grep the docset for `^inputs:` and `triggers:` patterns at the start of YAML blocks to find every site.
## Tasks
- [ ] Audit: inventory every Workflows page with root-level `inputs:` in a YAML example.
- [ ] For each, apply the applies-switch pattern (or, on lighter pages, swap to the new form with a one-line version note).
- [ ] Update `migrate-from-9-3.md` (or its 9.4-to-9.5 successor) with a dedicated section on the inputs schema change.
- [ ] When sub-issue #N (serverless label update) ships, re-sweep these same pages to add `serverless: ga` to the new-form applies-item labels.
## Resources
- Engineering tracking issue for the legacy retirement: [elastic/security-team#16526](https://github.com/elastic/security-team/issues/16526).
- Schema: [`kbn-workflows/spec/schema/triggers/manual_trigger_schema.ts`](https://github.com/elastic/kibana/blob/main/src/platform/packages/shared/kbn-workflows/spec/schema/triggers/manual_trigger_schema.ts).
- Applies-switch syntax: [docs-builder reference](https://elastic.github.io/docs-builder/syntax/applies-switch).
## Point of contact
**Main contact:** @benironside
**Stakeholders:** @tinnytintin10
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.