elastic / elastic/docs-content

All workflow step types can now use the step-level `if` skip condition

Open
#8,007 2 comments 0 reactions 1 assignee Claimed by @nastasha-solomon View on GitHub
Team:SKI
Dominant language
No language data
Stars
47
Forks
261
Avg merge
3d 12h
Merged PRs (30d)
116

Description

## Summary

Workflow step types can now use the step-level `if` condition to skip a step, in cases where they couldn't before.

**Before:** Ten step types — `wait`, `waitForInput`, `waitForApproval`, `data.set`, `elasticsearch.*`, `kibana.*`, `parallel`, `merge`, `workflow.execute`, and `workflow.executeAsync` — rejected `if` with a validation error, even though the workflow engine already evaluated `if` for every step type at execution time.

**Now:** Every step type accepts `if`, with two exceptions:
- The `if` step itself still doesn't accept a step-level `if` — it already branches on its own `condition` property, and a conflicting step-level `if` is now explicitly rejected (previously it was silently ignored).
- A plain step nested inside a `parallel` branch still can't use `if`. However, `if` is now accepted directly on the `parallel` step, letting you gate the entire parallel block on one condition.

**Also new:** `if` (and the `if` step's `condition`) are now capped at 2000 characters, to keep condition parsing (KQL) within the Elastic Stack's limit.

**Why this needs docs:** The schema diff (spec/schema.ts, spec/schema.test.ts) adds `if` acceptance to exactly the ten step types the PR body names, and the internal parallel_step.md doc explicitly confirms `if` is now valid on the parallel step itself — which makes the public Parallel step doc page's current blanket statement that the parallel step doesn't accept `if` factually wrong going forward.

## Resources

- PR [#279210](https://github.com/elastic/kibana/pull/279210) — [One Workflow] Allow `if` on all step types
- Product issue: https://github.com/elastic/kibana/issues/279171

Screenshots from PR

![screenshot](https://pub-6b50802d113345dea50c783e8280b53e.r2.dev/artifacts/20260717/t941q5cz-before-editor.png)
![screenshot](https://pub-6b50802d113345dea50c783e8280b53e.r2.dev/artifacts/20260717/flztp9m8-after-editor.png)
![screenshot](https://pub-6b50802d113345dea50c783e8280b53e.r2.dev/artifacts/20260717/1mpcy8kf-after-execution-detail.png)

## Availability

| Channel | Details |
|---------|---------|
| **Stack** | v9.4.0, v9.5.2, v9.6.0 |
| **Serverless** | Aug 17–Aug 21 |
| **Feature flag** | None — active by default |

---
*Created with [Docs Quest Scanner](https://github.com/florent-leborgne/docs-quest-scanner) by @nastasha-solomon*

## Suggested edits

[Parallel](https://www.elastic.co/docs/explore-analyze/workflows/steps/parallel) > Handle branch failures
- **What the docs say:** "The parallel step doesn't accept on-failure or if as top-level parameters."
- **What to add:** Update this sentence: the parallel step now accepts `if` as a top-level parameter, which gates the whole block (all branches run only if the condition is true); only `on-failure` remains unsupported as a top-level parameter on `parallel`. Applies from 9.4.0 and in serverless.

[Parallel](https://www.elastic.co/docs/explore-analyze/workflows/steps/parallel) > Branch body limitations
- **What the docs say:** The limitations table lists nested flow control (if, switch, foreach, while), human-in-the-loop waits, step-level on-failure, and step-level timeout as rejected inside a branch body, with no row distinguishing a plain step's own `if` property from a nested `if` step type.
- **What to add:** Add a row noting that a step-level `if` property on an ordinary step is also rejected inside a branch body (separate from nesting a full `if` step type), since `if` is now valid on regular steps everywhere else. Point authors to set the condition on the parallel step itself or evaluate it in a step before the fan-out instead. Applies from 9.4.0 and in serverless.

[waitForInput](https://www.elastic.co/docs/explore-analyze/workflows/steps/wait-for-input) > Parameters
- **What the docs say:** The Parameters table lists `name`, `type`, `timeout`, `message`, `schema`, and `channels` as the step's fields. There's no `if` entry.
- **What to add:** Add an `if` row (top level, optional) noting that a step-level `if` condition can now gate whether the `waitForInput` step runs at all, the same as any other step type. Applies from 9.4.0 and in serverless.

[waitForApproval](https://www.elastic.co/docs/explore-analyze/workflows/steps/wait-for-approval) > Parameters
- **What the docs say:** The Parameters table lists `name`, `type`, `timeout`, `message`, `approveLabel`, `rejectLabel`, and `channels`. There's no `if` entry.
- **What to add:** Add an `if` row (top level, optional) — the step now accepts a step-level `if` condition like any other step type. Applies from 9.4.0 and in serverless.

[Wait](https://www.elastic.co/docs/explore-analyze/workflows/steps/wait) > Parameters (before "Duration format")
- **What the docs say:** The parameter list shows only `name`, `type`, and `with.duration`. There's no `if` entry.
- **What to add:** Add an `if` row noting the step now accepts a step-level `if` condition to skip the wait entirely, like any other step type. Applies from 9.4.0 and in serverless.

**Also reviewed, no changes needed:**
- **Action steps** (Elasticsearch action steps, Kibana action steps, Data action steps, Composition steps): these reference pages only document each action's `with`-block parameters, not the common top-level fields every step shares (`name`, `type`, `if`, `on-failure`, `timeout`) — so they never claimed `if` was unsupported, and don't need a correction. The `merge` step type named in the PR doesn't currently have a public reference page in the step catalog, so there's nothing to update for it either.
- **AI steps** (`ai.prompt`, `ai.classify`, `ai.summarize`, `ai.agent`): the AI steps page already correctly lists `if` as a supported top-level field ("alongside `name`, `type`, `if`, `foreach`"). These step types weren't in the PR's list of ten and were unaffected by this change.
- **Flow control steps overview**: the per-step summaries don't make an `if`-support claim beyond what's already covered in the Parallel edits above.

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.