Skip to navigation
Workflows

Workflow Versioning

A workflow has one editable draft and any number of immutable deployed versions. Edits always land on the draft; deploying snapshots the draft into a new numbered version ("1", "2", …) that will never change. Production integrations pin a deployed version so that editing the draft, or deploying a newer version, cannot alter what is already running.

How a run picks a version

When you create a workflow run, workflow.version decides which definition executes:

workflow.versionRuns
omittedThe most recent deployed version. If nothing has been deployed yet, the draft.
"draft"The current draft, including unsaved-to-version edits. Use for development only.
"3"Exactly deployed version 3. Pin this in production.

Processors have their own, separate version strings ("draft", "latest", "1.0"). Each extract, classify, or split step in a workflow definition references its processor with an explicit version. A deployed workflow version freezes that reference, but if the reference is "latest" it still resolves to the newest published processor version at run time. To make a deployed workflow fully reproducible, reference specific processor versions ("1.0") in its steps. See Publishing Processors.

Via the API

1

Deploy a new version

Deploying with no body snapshots the current draft. Pass steps to deploy a definition directly without touching the draft (the pattern for config-as-code, where the repository is the source of truth). All configurable steps must include config; unconfigured steps are rejected with a 400. See Configuring Workflows via API for step definitions.

from extend_ai import Extend
client = Extend()
version = client.workflow_versions.create(
    "workflow_BMdfq_yWM3sT-ZzvCnA3f",
    name="Add vendor-name validation",
)
print(version.version)  # "4"
2

Pin a run to that version

Store the returned version string in your configuration and pass it on every run. Omitting version is fine for development, but in production it means a future deploy silently changes behaviour.

run = client.workflow_runs.create(
    workflow={"id": "workflow_BMdfq_yWM3sT-ZzvCnA3f", "version": "4"},
    file={"url": "https://example.com/invoice.pdf"},
)
3

List and inspect versions

list returns version summaries newest-first; retrieve returns the full step definitions of one version, which is useful for diffing what actually changed between two deploys.

versions = client.workflow_versions.list("workflow_BMdfq_yWM3sT-ZzvCnA3f")
for v in versions.data:
    print(v.version, v.name, v.created_at)
detail = client.workflow_versions.retrieve("workflow_BMdfq_yWM3sT-ZzvCnA3f", versions.data[0].id)
print([step.type for step in detail.steps])

Rolling back

Deployed versions are never deleted or modified, so a rollback is just pointing your runs at the earlier version string. There is no server-side “current version” pointer to move: the only thing that decides which version runs is the workflow.version you send (or omit).

Via Extend Studio

To view the workflow versions, click on the “Version history” button in the lower left corner of the workflow editor.

Workflow editor with the "Version history" button highlighted in the lower-left corner

The versions are displayed in a side panel on the left side of the screen. The “Draft” version above the separator is the version where any updates to the workflow will be saved. The versions below the separator are the deployed versions of the workflow.

Version history side panel showing the Draft above a separator and deployed versions below it

You can view a previously deployed version of the workflow by clicking on the version. This loads the workflow in the editor for viewing; you cannot make changes to a deployed workflow version. Once a workflow has been deployed you can count on it not changing, and can confidently use it in production environments.

Workflow editor showing deployed version 1 in read-only mode

To deploy a new version of the workflow, click on the “Deploy” button in the upper right corner of the workflow editor. This deploys the current draft and creates a new version in the version history.

Deploy dialog for publishing the current draft as a new workflow version

When running a workflow from the Studio runner, you can choose which version to run. By default the “Draft” version is run, but you can choose a different version from the dropdown.

Workflow runner with the version dropdown for choosing which version to run

After running a workflow, the history tab shows which version each run used.

Workflow run history tab listing runs with the workflow version used for each

You can also deploy workflow versions from GitHub by linking a workflow to a repository file. See GitHub App Integration.

Reference