elastic / elastic/docs-content

Workflows 9.5 docs: apply nested-inputs YAML structure uniformly across all workflows docs

Open
#6,811 1 comment 0 reactions 1 assignee Claimed by @benironside View on GitHub
Team:Experience
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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.