A hands-on walkthrough of running your first Versus workflow from the console — pick a built-in playbook, start a run against a device group, watch it execute section by section, clear an approval gate, and recover a failed step.
A workflow is how Versus makes a change: a repeatable, auditable sequence of steps — pre-checks, approvals, device operations, verification — that runs the same way every time and records everything it did. This guide walks you through running one end to end from the console: picking a workflow, starting a run, watching it execute, approving a gate, and recovering if a step fails.
You don't need to build anything first. Versus ships with built-in workflows for common jobs (an HA-pair OS upgrade, a certificate renewal, a firewall change), so your first run can be a real, useful one.
Under the hood, a workflow is a graph — nodes connected by edges, stored as JSON — that the engine walks one node at a time from a single start node to an end node. Each node is one of a few kinds:
| Kind | What it does |
|---|---|
start | The trigger. Declares the inputs a run needs (device group, firmware image, options) — this is what the Run form is built from. |
action | Runs one registered step — a device operation, a script, an integration call. |
decision | Branches: the step returns a result that selects which outgoing edge to follow. |
approval | Pauses the run for a human to approve or reject before it continues. |
section | A labeled grouping of steps (for example Pre-Upgrade Checks, Upgrade Standby, Failover). Purely organizational — but sections are what let you run a change in controlled stages. |
end | Terminates the run successfully. |
Each workflow belongs to a category — F5 BIG-IP, NetScaler, Certificate Management, DNS, Firewall, Router/Switch, ServiceNow, ADC Migration, vSphere, rSeries Consolidation, or General — which is just how the library is organized. Built-in workflows are marked read-only; you run them as-is, and duplicate one when you want an editable copy (see Customizing and building your own).
Running a workflow that touches devices needs three things in place:
A workflow with no device operations (a pure script or an HTTP integration) doesn't need a device group at all.
Open Workflows. Each card shows the workflow's name, category, and how many times it has run. A live Runs panel keeps recent and in-flight runs one click away, so short dry-runs don't scroll out of sight.
Pick a built-in that matches something you actually want to do. For this walkthrough, any workflow with a clear pre-check → approve → apply → verify shape works well — an OS upgrade is the canonical example.
Click Run on the card. Versus reads the workflow's start node and builds a form from it — so you only ever see the inputs this workflow needs. Typically that's:
Submitting the form creates a run and starts it immediately in the background. Behind the console this is a single call:
POST /api/workflows/{id}/run/
Content-Type: application/json
{
"device_group": 7,
"name": "Nightly upgrade", // optional; auto-named if omitted
"context": { } // the options collected from the form
}
The run comes back in status pending and moves to running as the engine picks it up. You're taken straight to the run detail page.
Change gating. If the workflow is configured to run under a Versus Desk change window, starting it creates a Change ticket instead of executing right away — the run stays
pendinguntil that change is approved and scheduled, then begins on its own.
The run detail page is the heart of the operator experience. It shows the run broken down the way the graph is built — section → step → device — updating live as the engine advances:
pending, running, success, failed, skipped, or waiting_approval.pending, running, waiting_approval, paused, completed, failed, or cancelled.Because steps declare a target role (active, standby, both, or group), the engine resolves which physical device each step runs on from live HA state — so a step marked standby still hits the right box even after a failover step earlier in the run has flipped the roles.
If a step runs a long time with no fresh output, a background watchdog annotates its log — probing whether the target is still reachable — so you can tell a slow-but-working step from a genuinely stuck one, rather than guessing.
Most real changes include an approval node between the safe pre-checks and the part that actually changes something. When the engine reaches it, the run pauses at waiting_approval and the step shows the approver instructions the workflow author wrote (for example: "Pre-upgrade checks passed on both nodes. Approve to begin the upgrade, standby first.").
Approve to continue, or reject to stop the run cleanly — nothing past the gate runs on a rejection. Over the API the same action is:
POST /api/workflow-runs/{run_id}/resume_approval/
{ "approved": true, "comment": "Change CR-1234 approved" }
A run can pass through several gates — an upgrade often has one before touching the standby and another before triggering failover.
If a step fails, the engine stops the run at failed and leaves the failed step in place with its full log, an extracted error snippet, and — when an AI provider is configured — concise resolution guidance (a summary, recommended actions, and whether it's safe to retry). You have three recovery actions on that step:
| Action | When to use it |
|---|---|
| Retry | You fixed whatever caused the failure. The step re-runs in place; if it succeeds, the workflow continues from the next node. |
| Mark complete | You verified from the log that the operation actually finished, even though Versus didn't detect completion. The step is marked done and the run continues. |
| Stop | A step appears hung. Versus forcibly closes the connection it's stuck on and marks it failed so you can retry once the device is healthy. |
If a step targeted two devices and only one failed, the run stays failed until you clear the failed sibling too — so you never skip past a half-applied change. The same actions are available over the API (retry_step, mark_complete, stop_step), each taking the step_run_id you read from the run.
Sections aren't just labels — they're stopping points. When you want to gate a change stage by stage, tell the run to stop after a section and it pauses at that boundary as paused. Resume when you're ready:
POST /api/workflow-runs/{run_id}/resume/
{ "stop_after_section": 1 } // run through section 1, then pause again
Omit stop_after_section on resume to run everything remaining. This lets you run the pre-checks, validate them yourself, then release the Apply section, then Verify — each with its own confirmation. The Workflow API guide covers staged, API-driven runs in full.
You can also pause a running run (it stops after the current step) and cancel one outright.
A run that made changes can be reversed. Steps that support it declare themselves reversible and capture a "before" snapshot as they run; from a completed or failed run you can request a back-out plan, which Versus assembles from the reverse of what actually ran:
POST /api/workflow-runs/{run_id}/request_backout/
{ } // omit step_run_ids to back out the whole run
Two guardrails apply: a workflow marked production requires dual approval before its back-out executes, and back-outs can only be requested within the workflow's configured back-out window (24 hours after completion by default). Review the generated plan before approving it — each reversible step shows a plain-language description of what undoing it will do.
Once a workflow does what you want, you rarely run it by hand forever:
The API and the console act on the same run, so an operator can watch, intervene, or take over a run that a pipeline started.
Built-in workflows are read-only, but they're a starting point:
versus object for querying inventory and running device operations, so your custom logic runs inside the same durable, audited engine.Everything you did in this guide — running, approving, retrying, backing out — works identically on the workflows you build.