Version and deploy a workflow
- Synopsis
- Full Details
In briefCommitting a change to a workflow creates a new, numbered version; running it in an environment is a separate step, deployment. Each environment's deployment either follows Latest or is pinned to one version, so you can test a change in one environment while another keeps running the version you trust.
- Your edits are a draft kept in this browser until you commit a version with the filled save action, Commit changes to a version. The version selector shows where you stand.
- Renaming a workflow does not create a version.
- To roll an environment back, edit its deployment and pin it to the earlier version. There is no separate rollback action.
- A deployment can be limited to a window with an Effective Date and an Expiration Date.
- Replace schedules a new deployment to take over on a future date; the current one keeps building until then.
- The commit action stays greyed out while any job in the workflow cannot run, including one you did not touch. Hover it to see the first problem.
- A workflow with a Workflow Container job cannot be deployed where its sub-workflow is not deployed, or for dates the sub-workflow's deployment does not cover. Deploy the sub-workflow first.
- A commit that changes which sub-workflows a workflow embeds is refused while the workflow is deployed as Latest somewhere those sub-workflows are not deployed.
Editing a workflow saves a new version; running it in an environment is a separate step called deployment. Keeping these separate lets you test a change before it reaches production.
If editing a workflow immediately changes what runs in production, there's no safe way to test a change first, and no clean way back when one goes wrong.
Versions
Committing a change creates a new, numbered version, kept in the workflow's history with its notes. You can view an earlier version from the Version selector; the editor has no action that commits it again as the current version. To have an environment run an earlier version, pin its deployment to it (see below). The older versions are never lost. A fix saved on Check SAP Job Numbers is a new version too, whose notes start SAP job number re-sync: — see Checking every stored SAP job number.
Draft, save, version — which is which
The editor keeps these apart deliberately, because only one of them puts your work on the server:
- A draft is local. Your edits auto-save in this browser as a temporary draft. Nobody else sees them, and they are not on the server. The Workflow Settings panel's footer says so.
- Committing a version is the save that counts. Use the filled save action in the toolbar — it's the only filled icon in that row, and its tooltip reads Commit changes to a version.
- The version selector tells you where you stand:
v1 (draft)means nothing has been committed yet,v1means committed and clean, andv1 (auto saved draft)means committed with local edits that are not on the server.
The very first version commits with no dialog — there's no history to describe yet. Every one after that offers Notes, capped at 300 characters. They are optional, so Save works with the field empty, but a short note is what makes the version history worth reading later.
Renaming is not a version. Once the workflow has been saved, its Workflow Name is read-only; select Rename beside it in the Workflow Settings panel. The new name is saved straight away and the version number does not change; any edits you have not committed are kept for your next version. See Renaming a workflow does not create a version.
If the workflow is marked Sub-Workflow, the dialog leads with "Changes apply to every workflow that uses this sub-workflow" and names the parents that embed it — the first three, then a count of the rest. Those parents change behaviour on their next build, so read the list before you commit.
It does not block Save: if the parents can't be looked up, you get the sentence without the names rather than no warning at all. The one save it does block is the one that turns Sub-Workflow off while a container job still embeds the workflow — the dialog says Sub-workflow cannot be turned off, names the parents, and Save stays disabled until you remove or retarget those container jobs or turn the switch back on. Only container embeddings count; a cross-workflow dependency on this workflow isn't one. See Saving a version warns you which parents it affects.
That means the browser couldn't store the draft — storage is full or unavailable. Your edits are still on screen but nothing is persisted anywhere. Commit a version now.
If a commit is refused because of a sub-workflow
A deployment set to Latest re-points at whatever you commit next, so a commit that changes which sub-workflows a workflow embeds can break the environments running it. That commit is now refused rather than allowed through, and the Save to a New Version dialog tells you before you save: This version cannot be saved while deployed as "latest"., with one line per environment naming the job and the sub-workflow at fault, and Save disabled.
The way out is either to deploy the sub-workflow to those environments or to pin this workflow's deployment there, then save again. Two things worth knowing:
- A save that leaves the container references alone is never checked, so a workflow whose sub-workflow was never deployed stays editable for every other edit you need to make to repair it.
- A check that can't be reached doesn't block you. The dialog says the save will be verified on submit and leaves Save live; the server has the last word either way.
The dialog now stays open until the commit settles, so a refusal arrives in place with your notes still in it.
See Committing a version is checked too.
If the commit action is greyed out
The commit action (Commit changes to a version) is blocked while the workflow contains a job that couldn't run. Hover the button: the tooltip names the first problem and how many others there are, and the job responsible has a yellow warning border on the canvas — hover that too for its own reason.
The usual causes are a job with no job type (for example one whose job type was cleared or changed to one that is not available), a missing required parameter or custom field, a duplicate job name, a job type that isn't available in this workspace, a job that needs an agent assignment and has none, or an OS 2200 Job with a value its agent could not be sent, such as Job 'PAYROLL': Qualifier is required.
Fix the flagged jobs and the button re-enables. Two things that surprise people:
- It can flag a job you didn't touch. The check covers the whole workflow, so a job stored before a rule applied — or before a plugin update made one more parameter required — has to be completed now. That's deliberate: the alternative is a version that fails when it runs.
If the tooltip says Checking workflow…, the check is still loading its data — wait a moment. If it says it couldn't load the job types, retry.
Deploy to an environment
Select Manage Deployment in the workflow editor toolbar to open the Deploy modal, which has one card per environment. Use Set-up Deployment on an environment's card to create a deployment (Edit and Delete on the card change or remove one), choose its Version, and select Deploy. The Version list decides how the environment tracks versions:
- Latest: the environment always runs the newest version.
- Version N: the deployment is pinned, and the environment runs that version until you change it.
You can also set an Effective Date and Expiration Date so a deployment is active only within a window. The same workflow can be deployed to several environments at once: for example, pinned to a tested version in production while running latest in a test environment.
- A change isn't appearing in an environment? The deployment is probably pinned to an older version, the new version hasn't been deployed, or the effective date is in the future.
- To roll an environment back, edit its deployment and pin it to the earlier version. There is no separate rollback action in the interface.
- Deliberate production-vs-test drift is normal: pin production, run latest in test.
If the workflow embeds another through a Workflow Container job, you cannot deploy it to an environment where that sub-workflow is not deployed — nor for dates the sub-workflow's own deployment doesn't cover. The Deploy modal shows the state per environment in a Sub-Workflows section and holds Set-up Deployment back with the reason on the card, so deploy the sub-workflow first.
The rule runs the other way too: once a parent is deployed, the sub-workflow's deployment can't be removed or narrowed underneath it, and the sub-workflow can't be deleted — nor renamed while a deployed parent refers to it by name only. A Used By section on the sub-workflow's card names the parents holding it in place. See A sub-workflow must be deployed wherever its parent is.
The deploy form checks the dates you type, as you type them. The New Deploy and Edit Deploy form carries the same Sub-Workflows section and re-checks it against the environment, strategy, pinned version and window you have entered, so you find out that a date doesn't fit before you submit it. Deploy stays inactive until it does, and tells you why on the button. More on the form's check.
A rename carries through to the jobs bound to that frequency, so their schedule survives the
deployment. Swapping two frequencies' names, or chaining renames (A to B and B to C), works:
each name moves once. The dialog blocks a rename it cannot apply cleanly — two renames of the same
name, two renames landing on the same name, or a name a job already has — so resolve the conflict
and deploy again. A name that a saved Advanced rule moves away first is not counted as taken. See
What the dialog blocks.
Change a deployment from a set day
To move an environment to a new version or new transform rules from a future day, without a gap, schedule a replacement rather than editing the live deployment:
- On the environment's card, select Replace. It shows when the deployment is live today and no replacement is already waiting.
- In Replace Deploy, which starts from the current deployment's version and transform rules, change what should be different. A Was: hint under each changed field shows the current value.
- Set the Effective Date, which must be after today and, when the current deployment has an expiration date, no later than it. Set an Expiration Date if the replacement should end.
- Select Schedule.
The card now shows the replacement under Upcoming Replacement, and the current deployment's Expiration Date becomes the replacement's Effective Date, so the current deployment keeps building until that day and the replacement from it. Use Edit or Delete in that section to change or cancel it; deleting it gives the current deployment its old Expiration Date back. The current deployment cannot be deleted while a replacement waits.
If you edit a live deployment and move its Effective Date into the future, Edit Deploy warns that nothing will build until then and offers Replace. See Replacing a deployment on a date.
Related topics
- Workflow versions and deployments — full configuration reference and troubleshooting
- Add jobs to a workflow (Builder)
- Manage environments (Administrator)