Validating and Planning a Workflow

Why validate and plan

Before a workflow runs — and certainly before you activate it — you want two guarantees: that its graph is structurally sound, and that it will execute in the order you intend. The Validate & Plan tab gives you both. Validation checks the workflow definition for errors and warnings; planning computes the topological execution plan — the ordered stages the engine will walk. Both are pure, side‑effect‑free computations, so you can run them as often as you like.

What validation checks

Validation inspects the whole workflow — its trigger and every step — and returns:

• valid — a simple pass/fail for the graph as a whole;
• errors — structural problems that must be fixed before the workflow can run or publish (for example a step that depends on a step key that does not exist, or a dependency cycle);
• warnings — non‑blocking advisories worth reviewing (for example a step that nothing depends on, or a configuration that looks incomplete).

A workflow that fails validation cannot be published — Publish validates first and refuses to activate an invalid graph, returning the validation details so you know exactly what to fix.

What the plan shows

The execution plan is the schedule the engine derives from your steps' dependencies. It sorts the graph topologically into stages: stage 1 contains the steps that run directly off the trigger, stage 2 contains steps whose dependencies were all satisfied in stage 1, and so on. Steps within the same stage have no dependency on one another and are considered together. The plan is the single best way to confirm, at a glance, that your branches and parallel steps line up the way you designed them.

How to validate and plan

1. Open the Validate & Plan tab and select the workflow.
2. Read the validation result. If valid is false, work through the listed errors — each points at the offending step or dependency.
3. Review any warnings. They will not stop a run, but they often reveal a step you forgot to wire up.
4. Review the execution plan. Confirm the stages match your intent — that gated steps sit after their filter, and that steps you want to run together share a stage.
5. Fix, then re‑validate. Repeat until the graph is clean and the plan is correct.

The engine requirement, and graceful degradation

Live validation and planning are computed by the StretchAutomate engine. When your administrator has the engine enabled, the tab shows fresh, engine‑computed results and stores the latest validation snapshot on the workflow. When the engine is not enabled, the read‑only Validate & Plan view degrades gracefully rather than erroring: it shows the last persisted validation snapshot (if one exists) or a clear note that live validation requires the engine, and the plan view reports that the engine must be enabled to compute stages. In other words, you always get an answer — either live results or the last known state — and never a hard failure just for looking. See The StretchAutomate Engine for how it is enabled.

Realistic example

An operator builds an order‑processing workflow and opens Validate & Plan. Validation returns valid: false with one error: the step send_receipt depends on charge_card, but the actual step key is capture_payment. They correct the dependency and re‑validate — now valid: true with one warning that a notes transform has nothing depending on it. That is intentional (it feeds an optional branch), so they leave it. The plan shows three stages: the payment capture in stage 1, the receipt and a CRM tag together in stage 2, and a delayed follow‑up in stage 3 — exactly as designed. They publish with confidence.

Tips

• Validate after every structural change — adding a step, editing dependencies, or renaming a step key can silently break a reference.
• Read the plan as a design review: if two steps you expected to be sequential appear in the same stage, one is missing a depends_on.
• Treat warnings as a checklist, not noise — an orphaned step is usually a forgotten wiring.
• Publish rather than flipping status manually so validation runs as a gate automatically.

Troubleshooting

Validation says the graph is invalid but I can't see why. Read the errors array closely — each entry names the step and the problem (missing dependency, cycle, or bad reference). Fix the exact key it cites.

Validate & Plan shows "engine disabled" or a persisted note. The engine is off, so you are seeing the last saved snapshot instead of a live result. Ask your administrator to enable the StretchAutomate engine for live validation and planning.

Publish is rejected with validation details. Publishing enforces validation. Open the returned details, resolve every error, and publish again.