Workflow versions and deployments
- Synopsis
- Full Details
In briefEvery committed change to a workflow is a new, numbered version kept in its history. A deployment decides which version runs in which environment, either the latest or a pinned one, for an optional date window, and can rewrite references with transform rules as the workflow is served there.
WhereDesign › Workflows › open a workflow. The filled save action in the editor toolbar commits a version (Commit changes to a version), and the version selector shows which version you are looking at and whether it is committed. Manage Deployment in the same toolbar opens the Deploy modal, with one card per environment: Set-up Deployment on a card creates a deployment, Edit and Delete change or remove it, and Replace schedules a replacement from a future date. A deployment's transform rules are edited in its New Deploy or Edit Deploy form. Deployment history and rollback are available through the API only.
WhenUse this page when:
- a change you made is not showing up in an environment;
- you want one environment on a tested version while another follows the latest;
- you want an environment to change version or rules from a set day, with no gap;
- you need the same design to run against a different environment's agents, properties or frequencies;
- a commit, deployment or deletion is refused because of a sub-workflow.
To start a separate workflow from an existing one, use Copy a workflow; to move configuration between environments, use Automation export and import.
How
- Commit your changes in the workflow editor. From the second version on, the Save to a New Version dialog offers an optional Notes field for the version history.
- Select Manage Deployment, and use Set-up Deployment on the environment's card.
- In Version, choose Latest, or a version to pin the deployment to, and set the Effective Date and Expiration Date if the deployment should have a window.
- Add transform rules for anything that differs in that environment, and select Deploy.
The full steps are on Version and deploy a workflow.
- Drafts stay in your browser until you commit. A Latest deployment serves the newest committed version; a Pinned one keeps serving its version.
- A draft that a newer version has overtaken is flagged by a banner above the canvas, and its commit is refused. Discard changes loads the latest version and deletes your edits, so copy them from Code View first.
- The Deploy modal shows only the environments in which you may view this workflow's deployments.
- A rollback restores a deployment's settings, not its transform rules.
- A replacement scheduled with Replace takes over on its Effective Date; until then the current deployment keeps building, and its Expiration Date follows the replacement's start.
- Some fields can never be changed by a transform rule; a rule that targets one, or renames a field on the way to one, is refused when you save it.
- An agent rename sends the job to the target agent, even when a different relay serves it.
- A sub-workflow must be deployed wherever, and for whenever, its parent is.
- Rename in the Workflow Settings panel renames a saved workflow without creating a version.
- Committing changes what every Latest environment builds next, so check them before you commit.
- Delete is disabled on a sub-workflow's deployment while a deployed parent still uses it.
- Moving a live deployment's Effective Date into the future stops it building until then. Use Replace to keep it running until the change.
- Environment-level rules apply to every deployment in that environment and are not counted on a deployment's card.
- In an Advanced rule's filter, quote a value with
(or)at either end in double quotes, not single: a single-quoted one is refused when you save, unless it ends in)and closes the filter. - A rule path that is valid but finds nothing in the deployed configuration still saves, and does nothing.
- An Advanced rule's filter may only read values, and its Source Pattern must be one that runs
quickly: a filter that does more, or a pattern such as
(a+)+, is refused when you save.
See How workflows work.
Task walkthrough: Version and deploy a workflow. This page is the full configuration and troubleshooting reference.
A workflow is versioned as it's edited, and deployed to an environment to run there. These are separate ideas: a version is a saved snapshot of the design; a deployment decides which version runs in which environment.
- Versions
- Validation Errors
- Deployments
- Sub-Workflow Rule
- Deploy and Commit Checks
- Transform Rules
- Advanced and Protected Rules
Versions
Versions
Each saved change creates a new version (an incrementing number) with an optional change description, linked to the version it came from. This gives a full history that can be reviewed and rolled back to.
Versioning tracks one workflow through its own lifecycle. To start a separate workflow from an existing one, see Copy a workflow; to move configuration between environments, see Automation export and import.
| Field | Notes |
|---|---|
| Version | Incrementing version number. |
| Message | The change description: a note describing the change, entered as Notes in the Save to a New Version dialog. The note is optional; the dialog caps it at 300 characters and trims it before it is stored, and a version saved with no note carries none — see Draft, save, and version. Through the API it is optional and at most 500 characters. It is taken when a workflow is updated; the first version of a workflow is always recorded as Initial version. |
| Previous version | The version this one was based on (none for the first). Recorded with the version and not shown in the version selector. |
| Timestamp / User | When and by whom the version was saved. |
The bold names are the version selector's columns.
A version can also come from Check SAP Job Numbers. A fix saved there is a new version, by the person who saved it, in which only the chosen SAP R/3 Jobs' SAP Job Number values change; its message starts SAP job number re-sync: and names each job with its old and new number. Like any new version, it reaches a Latest deployment and not a Pinned one. See Checking every stored SAP job number.
Draft, save, and version in the workflow editor
Three different things were all called "saving". They now read differently:
| What it is | Where you see it |
|---|---|
| A temporary draft — your edits, auto-saved in this browser. It is not on the server and no one else can see it. | The Workflow Settings panel's footer says the workflow is auto-saving temporary drafts, and a notice appears the first time a draft is written in a session. |
| A committed version — the change persisted on the server, in the history. | The filled save action in the editor toolbar, whose tooltip reads Commit changes to a version (Create workflow on one that has never been committed). It is the only filled icon action in its group, so it stands out from the ghost icons beside it. |
| Which version you are looking at | The version selector, which now states the save state in words. |
The version selector reads:
| Label | Meaning |
|---|---|
v1 (draft) | Never committed. The selector is not openable — there is nothing to choose yet. |
v1 | Committed, with no local edits since. |
v1 (auto saved draft) | Committed, with local edits auto-saved in this browser and not yet committed. |
The suffix is presentational; it never changes the version number. It appears only where a browser draft actually exists — a historical view or Forecast view, where auto-saving is off, shows the bare number.
Committing behaves differently for the first version and every one after it:
- The first version commits with no dialog. There is no history to describe yet.
- Every later version opens a Save to a New Version dialog with an optional Notes field, capped at 300 characters and trimmed before it is stored. Leave it empty and Save still works. Earlier builds kept Save off until Notes had text. The API's own limit is still 500 characters.
The Workflow Settings panel used to carry Draft and Cancel buttons, and edits made in that panel did not reach the workflow until you pressed Draft. The panel now writes straight through: what you type is in the workflow immediately, and the auto-save persists it in the browser. Committing a version is what puts it on the server.
If the browser cannot store the draft — storage full or unavailable — the footer says so as an error rather than claiming the work is saved. Commit a version to keep it.
Renaming a workflow does not create a version
A workflow's name is not part of its versions. Once a workflow has been saved, its Workflow Name in the Workflow Settings panel is read-only; select Rename beside it. The Rename Workflow dialog says Renaming changes the name only. It does not create a new version. Enter the new name and select Rename: the new name is saved at once, everywhere the workflow is listed, and the version number stays as it was. Edits you have not committed stay as they were, and the next version you commit keeps the new name.
The new name follows the workflow naming rules (see Object naming), and Rename stays off while the name is unchanged, empty or not allowed. A rename the platform refuses leaves the dialog open with the reason — for example, another workflow already has the name, the new name would make a job depend on itself, or a deployed parent workflow still embeds this one by its name only (see A sub-workflow must be deployed wherever its parent is). Rename is unavailable for a workflow that has never been saved, whose name you type in the panel, or when you are viewing an older version or may not edit the workflow.
Earlier builds had no Rename: the name was an ordinary field, and changing it took effect only when you committed a new version.
A rename made elsewhere is not undone. If the workflow is renamed in another session while your
Rename Workflow dialog is open, the dialog takes the new name, unless you have already typed in
it, in which case your text is kept. The workflow switcher's Recent list follows the new name
too. A save through the API that carries the version it was built on and a name other than the current one is refused, rather
than putting the old name back, when the workflow was renamed after that version. The message begins
Workflow was renamed to '<current name>' after the version this request read. Send no name to
keep it, and goes on to point at the rename request. Leave the name out of the save to keep the
current one, or rename the workflow instead.
The Code View dialog reads and writes the same live configuration. It now states the
find-and-replace shortcut (Ctrl+F / Cmd+F) under its title, and its own footer repeats the
auto-save note.
When a commit is refused because someone else committed first
A commit carries the version it was built on. If someone else committed in the meantime, yours is refused — and the message says exactly that: Someone committed a newer version of this workflow while you were editing, so this commit was refused. Your edits are still in this browser. Discard changes loads the latest version and deletes your edits — copy anything you need from Code View first, then re-apply it and commit again.
What you cannot do is commit onto a version the server has already moved past. Discard changes in the editor toolbar loads the latest version and deletes your edits, so copy what you need from the Code View dialog first. Then discard, make the edits again on the latest version, and commit.
A browser draft remembers the version it was started from, so this holds across sessions too. When the editor holds a draft that a newer version has overtaken — restored when you open the workflow, or overtaken while you edit — a warning banner stays above the canvas: Your browser draft was started from version 2, but version 3 has since been committed, so committing this draft will fail. Discard draft loads the latest version and deletes your edits — copy anything you need from Code View first.
The banner's Discard draft and load latest button does the same as Discard changes. You can close the banner; it comes back if yet another version is committed. Committing that draft is refused with the message above rather than replacing the newer version. Reloading the page does not help, because a reload restores the same draft.
While a commit is in progress, the banner's button is unavailable, the same as Discard changes in the toolbar, so a commit that then fails still has your edits to fall back on. The banner shows in the forecast view too, because your edits are still there; only viewing an older version hides it. Earlier builds left the button live during a commit, so selecting it then deleted the draft under the commit, and a commit that failed lost your edits; they also hid the banner in the forecast view.
A draft started from a newer version than the page loaded — one edited in another tab after a commit there — gets its own banner: Your browser draft was started from version 4, but this page loaded version 3. Reload the page to load the latest version before you commit.
Switching versions with unsaved changes deletes the draft. Choosing another version in the Version selector while you have unsaved changes asks first — Switching versions will discard these changes — and Discard Changes then removes the browser draft too, so it does not come back on the next reload.
Earlier builds said your changes were safe in the same message that told you to discard them, showed the overtaken-draft warning for a few seconds only, and kept the browser draft after a confirmed version switch, so a reload brought back the edits you had chosen to discard.
A browser draft did not record the version it was edited from. When you reopened the workflow, the editor laid the draft over the latest version and committed it as though it were based on that one, so the commit went through and silently undid the other person's changes. The message also advised reloading, which restored the same draft. A draft saved before this release still carries no starting version, and is treated as edited from the latest one.
Two other refusals are reported in their own words rather than as this one:
| Refusal | Meaning |
|---|---|
| A workflow with this name already exists. Please choose a different name. | A genuine name collision. Discarding changes cannot help. |
| A duplicate job id | The server names the offending job, which is the only way to find it in a workflow with dozens. |
Any refused commit that was not self-evidently a version clash was reported as A workflow with this name already exists — including a lost race. Renaming cannot clear a stale version, so the advice led nowhere.
You can view an earlier version from the Version selector, but the workflow editor offers no action that commits it again as the current version. To have an environment run an earlier version, pin that environment's deployment to it — see Deployments.
Validation Errors
A version won't commit while the workflow has validation errors
The commit action (its tooltip reads Commit changes to a version) is blocked while anything in the workflow would produce a job that cannot dispatch. The button is disabled and its tooltip names the first problem, with a count of the rest — "Job 'EXTRACT' has no job type (and 2 more problems)". The one exception is a missing workflow name: when that is the only problem, the button stays selectable, and selecting it opens the Workflow Settings panel and flags the field.
The same check draws a yellow warning border and tooltip on the offending job on the canvas, so what blocks the commit is always visible on the node that causes it. Before this, the canvas badge and the commit gate were separate computations and could disagree.
Blocked on any of:
| Rule | Detail |
|---|---|
| The workflow has no name | Applies when updating, not only when creating. |
| A changed workflow name is over 40 characters, or contains a character a workflow name may not | Checked only when the name differs from the stored one. |
| A job has no name, a name over 255 characters, or a name that duplicates another job's | Names are compared ignoring case. |
| A schedule instance has two properties with the same name | Names are compared ignoring case and trailing spaces. Checked only when that instance's property names differ from the stored ones. |
| A job's agent assignment is internally inconsistent | |
| A job has no job type | A job added on the canvas starts as a Null Job, so this arrives through an import, an edit in Code View, or an undo or redo that rebuilt the job. |
| A job is missing a required task parameter | Top-level parameters of the job type's schema. |
| A job's exit criteria rows are not valid | |
| An OS 2200 job has a parameter value its fixed-width record cannot hold | An over-length value, a character the field does not allow, or a misplaced row, as the job editor would report it. |
| A job is missing a required custom field | |
| A job's job type is not available in this workspace, or its definition could not be loaded | The job type is not in the plugin catalog at all — for example a name brought in by an import or a Code View edit that no plugin provides. Names are matched exactly, including case. Turning a plugin or a job type off does not cause this: a job of that type still saves (see What turning off changes). |
| A job needs an agent assignment and has none | |
| A completion event or a job event could not be saved as it stands | The event is checked as stored, by the same rules the server applies on save. A blank event is reported as having no event to fire. |
| A job event is scoped to a frequency the job does not have | Such an event would never fire. |
| A job depends on a job that is not in this workflow | A dependency that names this workflow must name one of its jobs. |
| A dependency names this workflow but is linked to another workflow | Pick the workflow again in the dependency. |
| The workflow's job list cannot be read | Use Discard changes to drop the local draft. |
Two things follow from this that are worth knowing:
- It blocks on pre-existing problems, not only on your current edit. A job stored before a rule applied — or before a plugin update marked one more parameter required — has to be opened and fixed before the workflow can be versioned again. The alternative is a version that cannot dispatch.
- The gate validates the config, not the editor. Routes such as an import, an undo/redo resync and the Code View dialog put jobs into a workflow without opening the job editor, so the editor's own checks can't be the only defence.
While the job-type and custom-field data the check needs is still loading, the button reports Checking workflow… and stays blocked, so a slow lookup can't race an invalid save through. If that data fails to load outright, the tooltip says so and asks you to retry rather than letting the commit proceed unchecked.
Deployments
Deployments
A deployment links a workflow to an environment with a version strategy and an optional date window.
| Field | Notes |
|---|---|
| Target Environment | The environment the workflow is deployed to. |
| Version | Latest (always run the newest version) first, then every committed version, newest first, as Version N. Choosing a version pins the deployment to it; Latest follows each new commit. A pinned version the list no longer holds still shows as Version N. |
| Pinned version | The version a Pinned deployment runs, chosen in Version. Earlier builds offered it from a Versioning Strategy button, with the value shown in a caption under it. Through the API it must be a whole number from 1 to 2147483647; anything else, such as 1.5, is refused with a 400 saying so. A rollback's version number follows the same rule. |
| Effective Date / Expiration Date | Optional window during which the deployment is active. Leave Effective Date empty for immediately effective, and Expiration Date empty for no expiration. Clearing either field on an existing deployment now removes the boundary — earlier builds silently kept the stored date. |
Active (isActive) | Whether the deployment is currently active. Set only through the API — see the Deploy and Commit Checks tab. |
A workflow can be deployed to multiple environments — for example, Pinned to a tested version in production while running Latest in a test environment.
- A change isn't showing up in an environment. Likely the deployment is Pinned to an older version, the new version hasn't been deployed, or the deployment's effective date is in the future — including an upcoming replacement that has not yet taken over (see Replacing a deployment on a date). Check the environment's deployment, not just the workflow.
- To roll an environment back, edit its deployment and pin it to the earlier version. The older version still exists in the workflow's history. There is no separate rollback action in the interface — see Deployment history.
- Production vs test drift is expected when production is Pinned and test runs Latest.
- A date window you thought you removed may still be there. On earlier builds, clearing the Effective or Expiration Date field and saving left the stored date in place, so a deployment could keep an expiry nobody could see in the form. Clearing works now — but if a deployment behaves as though it has a window, open the dialog, clear the field, and save again to be certain.
Deployment history
Each change to a deployment's settings is recorded in a deployment history, and a deployment can be rolled back to an earlier entry. Both are available through the API only — no screen shows the history or offers the rollback. Three things limit what that history tells you:
- A rollback restores the deployment's settings, not its transform rules. The strategy, pinned version, dates and active flag return to the earlier entry; the transform rules stay as they are now.
- An edit's entry records the settings from before the edit, not after it. When the most recent change was an edit, rolling back to the newest entry undoes it.
- For a Latest deployment, the workflow version recorded is always 1, whatever version the environment was actually running. Only a Pinned entry records a meaningful version.
Replacing a deployment on a date
To change what an environment runs from a set day, without a gap and without editing the live deployment early, schedule a replacement. The current deployment keeps building until the replacement's Effective Date, and the replacement builds from that date on. This is for workflow deployments only; a service request's card has no Replace.
Replace is on a workflow's environment card when its deployment is live today and no replacement is already waiting. It opens Replace Deploy, filled in from the current deployment — its version and transform rules — with Effective Date and Expiration Date empty:
- Effective Date is required and must be after today. When the current deployment has an Expiration Date, the replacement must start on or before it.
- Expiration Date is optional, and must be after the Effective Date.
- Under each field you change, a Was: hint shows the current deployment's value, for the version, the dates, the transform rule count and any agent renames.
- Schedule creates the replacement with its own copy of the current deployment's transform rules, and sets the current deployment's Expiration Date to the replacement's Effective Date. As Effective Date is inclusive and Expiration Date exclusive, the two never overlap and leave no gap. The sub-workflow rule below is checked against the two together.
The dialog explains a date it will not accept — Choose an Effective Date after today., or
Choose an Effective Date on or before <date>, when the current deployment expires.
While a replacement waits, the card shows it in an Upcoming Replacement section — its version, Effective Date, Expiration Date and transform rule count — with its own Edit and Delete:
| On the card | What happens |
|---|---|
| The current deployment's Expiration Date | Reads Set by the upcoming replacement. In Edit Deploy the field is read-only and says Follows the upcoming replacement. Move the replacement's Effective Date instead. |
| Edit on the upcoming replacement | Opens Edit Upcoming Replacement. Its Effective Date must still be after today, and moving it moves the current deployment's Expiration Date with it. |
| Delete on the upcoming replacement | Asks first, in Remove Upcoming Replacement. The replacement and its transform rules are removed, and the current deployment gets its old Expiration Date back. |
| Delete on the current deployment | Disabled, with Delete the upcoming replacement first. |
| Replace | Hidden, as only one replacement can wait at a time. |
On the Effective Date the replacement takes over. The card shows it as the environment's deployment, and Replace is offered again. The deployment it replaced is retired: it still answers for the dates before the takeover, but it no longer appears on the card and can no longer be changed. It does not come back when the replacement later expires. Days already built stay as they were built.
Editing a live deployment's Effective Date into the future warns you. Edit Deploy then says
Nothing will build for this workflow in <environment> until <date>. When the deployment can be
replaced, it adds To keep the current deployment building until then, use Replace., with a
Replace button that switches the dialog to Replace Deploy.
Sub-Workflow Rule
A sub-workflow must be deployed wherever its parent is
A Workflow Container job embeds another workflow, so deploying the parent to an environment only means something if the embedded child is deployed there too — and deployed for as long as the parent is. The platform holds that invariant at the moment a deployment is written, in both directions.
What is checked, and when
| The write | What it asks |
|---|---|
| Set-up Deployment on a parent | Every container job's sub-workflow is deployed to this environment, with a window that covers the one you are creating. |
| Edit on a live parent deployment | The same question, against the window as you are changing it. |
| Edit that narrows a child's window | Every deployed parent using the child here stays covered. |
| Delete, or deactivating, a child's deployment | No live parent deployment in that environment still uses it. |
| Rollback to an earlier deployment history entry (API only) | The snapshot being restored is checked as though you had edited the deployment into that shape. |
| Renaming the child workflow | No deployed parent references it by name only — an embedding that stores the child's id survives a rename. |
| Deleting the child workflow | No deployed parent references it at all. This reaches a Pinned parent serving an older version, which a cross-reference check of current designs alone would miss. |
| Turning off Sub-Workflow on the child workflow | No container job in another workflow embeds it, and no deployed parent embeds it where the child is deployed as Latest. See Workflow Container job. |
| Edit or Rollback that changes which version a live child deployment serves | When the version it serves now has Sub-Workflow on and the new one has it off, no deployed parent in that environment embeds it. Refused with "This sub-workflow is used by deployed workflows in this environment and cannot be changed to a regular workflow. Used by: …" |
| Committing a new version of a parent | Every container job's sub-workflow is deployed to each environment holding a live Latest deployment of this parent — see Committing a version is checked too. |
A rejected write changes nothing — the check runs before the deployment's version snapshot is taken, so a refused edit leaves no half-written row behind. Every violation found across the rules is reported in one refusal rather than one per attempt.
How a window has to cover
Effective Date is inclusive and Expiration Date is exclusive, and both compare as UTC calendar dates. A child covers a parent when:
- the child's effective date is on or before the parent's — and a parent with no effective date (immediately effective) is covered only by a child that also has none;
- the child's expiration date is on or after the parent's — and a parent with no expiration is covered only by a child that also has none.
A parent whose window has fully elapsed no longer constrains its children, so an expired deployment never blocks tidying up the child it used to use.
What the refusal tells you
Each message names the sub-workflow and what is wrong with it — that it is not deployed here, that it is not deployed for a given date or earlier, that it is not deployed for a date or later, or that the reference cannot be resolved at all:
"Child" is not deployed to this environment. Open the sub-workflow to set up deployment."Child" is not deployed for October 1, 2026 or earlier in this environment.The child's effective date starts after the parent's."Child" is deployed with an expiration date, but this deployment has none.An open-ended parent needs an open-ended child.Job "X" references a sub-workflow that no longer exists ("Child").Or, when the job stored an id that does not resolve, that you should re-select the sub-workflow.Job "X" references "Child" by id only. Re-select the sub-workflow so its name is stored.The build resolves a container by name, so an id with no name beside it is unbuildable.Job "X" has no sub-workflow selected.Job "X" references this workflow as its own sub-workflow.
On the child's side the refusal states the boundary you would have to meet, and lists who is holding you to it — "Expiration Date must be on or after December 31, 2026 (or blank) — deployed workflows use this sub-workflow until then. Used by: Nightly Close and Payroll Run." The date quoted is the strictest across all dependents, so meeting it satisfies every one of them at once.
A dependent in a workspace you have no access to is reported as "1 workflow in a workspace you cannot view" — it still blocks the write, and the required date still accounts for it, but nothing about it is disclosed. The first three names are listed, with the rest as a count.
Deploy and Commit Checks
The deploy modal shows the answer before you act
Select Manage Deployment in the workflow editor toolbar to open the Deploy modal. Each environment card is checked in its own right, so the state is visible per environment rather than only in a refusal.
The modal lists only the environments your role reaches. A card appears for each environment in which you may view this workflow's deployments, and the deployment list behind it holds only those environments' deployments. When the list of environments cannot be read, the modal shows an error instead of cards. A service request's modal works the same way. Earlier builds showed a user whose role covers one environment the deployments in every environment, and showed four placeholder environments that did not exist when the list could not be read.
- A workflow with container jobs gets a Sub-Workflows section on each card, one row per container job, reading the child's name and the version it serves — Version 4 (Pinned) or Version 6 (Latest). A row that fails shows the warning in place of its strategy hint, and failing rows sort to the top. Where two jobs embed the same child, the rows say which job each one is. A workflow with no container jobs gets no section, and its Set-up Deployment does not wait on the check, on a card that is not deployed yet or is deployed as Latest. On a Pinned card the section is hidden once the platform confirms the pinned version has none.
- Set-up Deployment is disabled on a card whose sub-workflow is missing, with the reason on the card rather than in an error after the fact. It is also held disabled while the check is still running, so it never offers an action it is about to refuse.
- A sub-workflow's deployed cards get a Used By section naming the parents that depend on that deployment, each with the version it serves and the job that embeds it, and Delete is disabled while any of them does. When nothing depends on it the section reads "Not used by any deployed workflow" — which is how you know removing the deployment is safe, rather than having to try it.
- Edit and Delete stay available on a deployed parent whose child row is failing — the state already exists, and fixing it is exactly what those actions are for.
- Each row's name is a link that opens that workflow in a new tab, when you can view that workflow.
- A workflow that is both a parent and a sub-workflow gets both sections.
Deploying again after the transform rules fail. When a new deployment is created but its transform rules cannot be saved, the dialog stays open with the error. Selecting Deploy again updates the deployment just created rather than creating a second one, and the Sub-Workflows check follows: it checks that update, not a new deployment. Earlier builds kept checking a new deployment, which could disable Deploy for the retry with no way to clear it in the dialog.
If the check itself cannot be run the section says "Could not check sub-workflow deployments." and nothing is disabled — the card falls back to letting you try, and the write is still refused if it must be. An environment you have no view grant on is left out of the check entirely, and its card renders as though nothing was asked.
The Used By section and the Delete gate follow what the platform reports, not the workflow's Sub-Workflow flag: a workflow whose flag was never turned on is still protected while parents embed it.
The deployment's active flag (isActive) is reachable only through the API. It is checked by the same rule as a delete — a child's
deployment cannot be deactivated while a live parent uses it — but there is no control for it on the
card.
Service requests share this modal and have no sub-workflow rules, so neither section appears on one.
The deploy form checks the window as you type it
The environment card answers the question for the deployment as it stands. The New Deploy and Edit Deploy form answers it for the deployment you are about to write — so a window that would not cover a child is caught before you submit it, not after.
- The form carries its own Sub-Workflows section, below the transform rules, with the same rows as the card: one per container job, the child's name and the version it serves, and the warning in place of the strategy hint on a row that fails.
- It re-checks as you change the environment, the strategy, the pinned version and the two dates — the dates after a brief pause, so a typed date is checked once you stop rather than per keystroke. The check describes exactly the write the button would make.
- Deploy (or Save) is held inactive while the check is running or still settling, and while it reports a failure. A workflow with no container jobs has no Sub-Workflows section, and Deploy does not wait on the check; when the workflow is itself a sub-workflow, a failure for a parent that uses it still holds Deploy back. Because the section sits at the bottom of a long form, the inactive button carries the reason: Checking sub-workflow deployments…, or A sub-workflow is not deployed or does not cover this window — see Sub-Workflows.
- If the check itself cannot be run, the button stays active. The rule is enforced when the deployment is written either way, and refusing to let you try on the strength of a failed check would be worse than letting the write answer for itself.
- A refusal that arrives on submit anyway — someone else changed a child's deployment in the meantime — is rendered as those same rows rather than as a bare error message, so you can see which sub-workflow and which side of the window was wrong. Changing anything on the form hands control back to the live check.
- Reopening the form shows the rows it last held straight away, but Deploy waits for the check to confirm them before becoming active again.
The child side appears above the form. When the workflow you are deploying is itself a sub-workflow and the window you have typed would strand a deployed parent, the warning at the top of the form names each parent holding you to it, and each name opens that workflow in a new tab. A workflow that is both a parent and a sub-workflow can show both at once.
A reminder sits under the rows, because it is the question the section prompts: transform rules for a sub-workflow are set on that sub-workflow's own deployment. To change them, open the sub-workflow and redeploy it.
Committing a version is checked too
A deployment set to Latest re-points at whatever version is committed next, so committing is a write that can change what an environment runs — and until this build nothing checked it. Adding a container job for an undeployed sub-workflow committed cleanly and broke that environment at its next build, with no signal to the person who did it.
A commit is now refused when it would leave a live Latest deployment holding an undeployable sub-workflow reference. The refusal carries the same per-environment failure lines the deployment writes use, and no version is committed — nothing is half-written.
What it covers, and what it deliberately does not:
| Scope | What the check does |
|---|---|
| Deployments considered | Only this workflow's active Latest deployments, and only those whose window has not fully elapsed. A Pinned deployment keeps serving its pinned version and cannot be changed by a commit, so it is not consulted. |
| Saves considered | Only a save that changes the container reference set — which sub-workflows the workflow embeds. A save that leaves those references alone is not checked at all. |
| Undeployed sub-workflow you inherited | Stays editable. A workflow whose existing sub-workflow was never deployed has to remain savable for every edit that leaves its references alone, or the check would trap exactly the people repairing it. |
| Deployments that already violate the rule | Left as they are. Nothing is retro-corrected; the check applies from the next write onwards. |
The Save dialog says so before you commit
The Save to a New Version dialog asks the same question while it is open, so the answer arrives before you commit rather than after:
-
Blocked shows a warning above every other notice in the dialog — This version cannot be saved while deployed as "latest". — with one line per failure grouped by environment, and Save is disabled. The advice under it is to deploy the sub-workflow to those environments, or pin this workflow's deployment there, then save again.
-
While the check is running the dialog reads Checking sub-workflow deployments… and Save is disabled with it. The answer is moments away and committing through it would race it.
-
A check that could not be reached does not block you. The dialog reads Could not check sub-workflow deployments; the save will be verified on submit. and Save stays live — the server re-checks on submit and is the authority, so an unreachable pre-check is not evidence of a problem.
-
A save the server would refuse for its references or events — a sub-workflow, dependency or other object it names that does not exist, is deleted, or is in a workspace you cannot view, or an event the save would reject as invalid — shows This version cannot be saved. with the save's own message, and Save is disabled. Earlier builds' check looked only at sub-workflow deployments, so it could say a save would go through and the save then be refused.
The check only runs on a workflow that has a live Latest deployment and at least one container job. A save on an undeployed or pinned-only workflow cannot change what anything runs, and one with no container job has no sub-workflow to check, so the dialog says nothing.
The dialog now stays open until the commit settles. A sub-workflow's deployment can be retired in the moment between the pre-check and your Save, so the refusal has to have somewhere to land: it renders in the dialog, in place, with the notes you typed still in it. A refusal reported that way raises no snackbar — it would say the same thing twice, and worse. Success, and every other kind of failure, closes the dialog exactly as before.
Renaming a sub-workflow that a deployed parent still embeds by name is refused by the same write, but it is not a commit problem, so it is reported on its own rather than inside the dialog's notice.
Transform Rules
Transform rules
A deployment can rewrite references as the workflow is served to its environment, so one design
can run against a different environment's inventory without a second version of the workflow. The
deploy dialog offers three kinds of rename, each authored as a from → to pair:
| Kind | What it rewrites |
|---|---|
| Agent | The agent named in a job's agent slots (primary, secondary, tertiary, quaternary). |
| Property | The name of a property defined on a job or on one of the workflow's schedule instances. It does not change token text in a job's parameters, and it does not change which global property a token reads. |
| Frequency | The frequency a job or an event is bound to. |
An agent is renamed only to an agent of its own type. An Agent row's target list offers only agents of the same type as its source — a Windows agent can be renamed to another Windows agent, never to a UNIX one — because a job sent to an agent of another type fails at dispatch on every run. A rule saved earlier that renames across types still shows its target, with the row flagged and Save refused until it is fixed. When the source agent's type cannot be found, the list is not filtered and the row carries a warning to check that the target is of the same type.
Agent pools are deliberately not offered in the agent picker. A pool is a different kind of entity from an agent, so renaming across the two would leave a reference that resolves to nothing in the target environment.
A changed agent is where the job runs
When a rule changes the agent a job is assigned to — a job set to a specific agent — the job is dispatched to the rule's target agent:
- A legacy job is sent to the target machine. The machine name the relay sends the job to follows the renamed agent, so the target LSAM machine runs it, and the job's kill and output requests go there too.
- The job is routed to whatever reaches the target agent — its own pool, or the relay that serves it — so an agent rename can move a legacy job to a machine behind a different relay.
Earlier builds showed the target agent on the job but still sent the job to the original agent.
Two cases are left as they are: a SMAFT File Transfer job, whose machines come from its own source and destination fields, and a job whose machine name an Advanced rule rewrites itself.
The rule count on each environment card
Each deployed environment's card in the Deploy modal shows a Transform Rules field: None configured, or N configured. It counts the same rows the deployment's edit dialog lists, so the two agree: a rename counts once, however many stored rules it is made of, and an Advanced rule counts once. Environment-level rules belong to the environment rather than the deployment, and are not counted. The count refreshes after you save rules in the dialog. It reads Loading… while it is being fetched, and — if it cannot be read. The same field is on a self service button's deployment cards, where each stored rule is one row. Both the count and the edit dialog include every rule on the deployment, however many there are.
Earlier builds always showed None configured on this field, whatever rules the deployment had, and a self service button's cards and edit dialog stopped at the first 100 rules.
Scoping a transform to one job
Every row starts with a Job selector, which defaults to All jobs. Leave it there and the rename applies across the whole workflow, as it always has. Choose a job and the rename applies to that job only — so a single job can be retargeted without touching the rest of the schedule.
What a job-scoped row reaches is narrower than the all-jobs equivalent, and deliberately so:
| Kind | All jobs | Scoped to one job |
|---|---|---|
| Agent | Every job's agent slots | That job's agent slots |
| Property | Job properties and schedule-level properties | That job's own properties only |
| Frequency | The schedule's frequency definitions, every job's frequency binding, event frequencies, and dependency predecessor frequencies | That job's own frequency binding and its event frequencies |
The exclusions matter. A workflow's frequency definitions and its schedule-level properties are shared by every job, so rewriting them because one job changed would leave every other job pointing at a name that no longer exists. Use an All jobs row when you mean to rename the shared definition; use a scoped row when you mean to move one job onto a different one.
A name can be the source of one rename per scope. AGENT1 → AGENT_PROD on Job A and
AGENT1 → AGENT_TEST on Job B are both valid and independent, because they touch different jobs. Two
rows that overlap and share a source are not: the dialog stops offering a name that a row covering
the same jobs has already claimed, because the second rename would silently do nothing. An All
jobs row overlaps every scope.
You also can't rename a name to itself — the target list drops whatever the row's source is.
Swapping and chaining names works. The renames you add in the dialog apply to the names as they
were before any of them ran, so each name moves exactly once, whatever order the rules are stored in.
AGENT_A → AGENT_B with AGENT_B → AGENT_A exchanges the two; AGENT_A → AGENT_B with
AGENT_B → AGENT_C moves each name one step. The same holds for Property and Frequency
rows, and a frequency another row renames away is not counted as taken, so a frequency swap is not
reported as a collision. Advanced rules and environment-level rules
still apply one after another, each to the result of the one before.
Earlier builds refused a swap or a chain, because the rules applied one after another.
A rename is checked against the names as they will be once the save has run. Save works out the result the deployment will actually serve — every rule in the order it applies — and refuses only a rename that would collide there:
- Advanced rules apply one at a time, in the order of their rows, and the dialog never reorders
them. A chain listed with the move off a name first —
Monthly → Monthly-old, thenWeekly → Monthly— saves in one go. Listed the other way round, the move ontoMonthlyis refused with Renaming "Weekly" to "Monthly" collides with a name already in use: delete that row, add it again below the other, and save. An Advanced swap is still refused, because one of the two always lands on a name the other has not left yet. - The typed rows apply together, after the Advanced rules that were already saved. So a typed
rename onto a name an existing Advanced rule moves away —
Weekly → Dailyin the Frequency section, with a saved Advanced ruleDaily → Daily-old— saves, and the deployment serves both. A new Advanced row added in the same save applies after the typed rows, so it cannot free a name for them.
Earlier builds checked each rename against the stored workflow as it was before any rule, so a rename onto a name another rule was moving away was refused even though it would have worked.
What the dialog blocks, and what it only warns about
Blocking — Save is refused until you resolve the row:
| Condition | Why |
|---|---|
| Two transforms of the same kind, covering the same jobs, rename the same name — Agent: "A" → "B" and Agent: "A" → "C" both rename "A". Remove one of them. — or rename onto the same new name — … both rename onto "B". Choose a different new name for one of them. | One of the two would silently not happen. The message names both rows. |
| A frequency rename collides with a frequency key a job already has | The job would end up with two bindings under one name. |
| The scoped job's name can't be expressed as a rule path | See below. |
| Scoping to that job makes the rule path longer than the platform allows | Shorten the job name, or scope the row to all jobs. |
| An agent rename's target is of a different type from its source — "…" (Windows) and "…" (Unix) are different agent types. An agent can only be renamed to another agent of the same type. | The job would be sent to an agent that cannot run it, and fail at dispatch. Choose a target of the same type. |
A job name can't be used as a scope if it contains a line break, the sequence )] or )', or an
@ followed by a space, ., ), [, or one of the words root, parent, property, path, or
parentProperty. Ordinary names with an @ in them — svc@corp backup, a@b.com run — are fine.
When a name can't be scoped, either rename the job or set the row back to All jobs.
Advisory — the row is flagged but Save still works:
-
"The type of agent "…" could not be determined, so the target list is not filtered by type. Make sure the target is an agent of the same type." The source agent is not among the agents the dialog loaded.
-
"Job … is not in the workflow version this deployment serves, so this transform will not apply." The scoped job was renamed or deleted, or the deployment runs Latest and the workflow has moved on. This is a warning rather than a block because a rule legitimately outliving a version is normal, and refusing Save would trap you in the dialog with unsaved work.
Because a scoped rule binds to the job's name, renaming a job breaks any transform scoped to it. The warning above is how you find out.
Renaming a frequency on deploy
A frequency rename follows through to the per-job settings that reference it, so jobs keep the
schedule they had instead of losing the binding. The dialog refuses a rename it cannot apply cleanly:
two renames of the same frequency, two renames onto the same new name, or a rename onto a frequency
a job already has, which names the jobs: Job <job> already uses "<new>". Renaming "<old>" onto
it would collide. A frequency another row renames away is not counted as taken, so a swap or a
chain saves (see above). Resolve the conflict and deploy again.
Advanced and Protected Rules
Advanced rules — anything the typed sections can't express
The three typed sections above cover renames. Anything else — deleting a field, appending or prepending to one, a pattern replacement, a hand-written path into a task parameter — is an Advanced rule, and the Advanced Rules section is a full editor for them. Each row has:
| Field | Notes |
|---|---|
| Name | Required, up to 255 characters. Rule names are unique per tenant, not per deployment, so two rows can't share one — and you can't reuse the name of a rule the same save is removing. |
| Target Path | Required. A JSONPath expression starting with $ or ., up to 500 characters. |
| Transform Type | REPLACE, REPLACE_PATTERN, APPEND, PREPEND, DELETE, or RENAME_KEY. |
| Source Pattern | A regular expression, up to 500 characters. Required for REPLACE_PATTERN and RENAME_KEY; read-only for the others, with a note saying why. A pattern that could take too long to run is refused when you save — see A source pattern must run quickly. |
| Target Value | The value to write, or the new key for RENAME_KEY. Read-only for DELETE. |
Use New Advanced Rule to add a row, and the row's remove control to drop one.
A new row starts blank and is not flagged until you have worked on it. Its Name is empty, and each field shows its error only after you have edited it and moved on, or once you select Deploy (or Save). An incomplete row does not disable the button: selecting it shows every error, with An advanced rule has an invalid field. Fix it, or remove the rule., and saves nothing. A name two rows share is still flagged as soon as it happens. Earlier builds gave a new row a generated name and showed its errors from the moment it was added.
Changing the type clears the operands that type forbids, so a Target Value left over from a
REPLACE can't ride along on a DELETE and be rejected when you save.
A rule the section can't recognise as one of the typed kinds still lands here, which means a rule authored through the API is now editable — you can fix a typo in one or remove it without going back to the API. Two things follow from that:
- A saved rule keeps the settings this dialog doesn't edit. Saving compares each row against the server's copy and updates only what changed, so a rule's priority — which decides the order rules run in within a scope — and its active flag survive an edit made here.
- The dialog's checks are authoring guidance, and they're stricter than the API. They aren't
applied to a row that came from the server and hasn't been edited, because a rule the API accepted
shouldn't be flagged as broken.
REPLACE_PATTERNis exempt from needing aTarget Valueoutright: replacing a match with nothing is how you strip a prefix, which is the commonest reason to reach for an Advanced rule at all.
A quoted value the rule path cannot match
The Target Path field's help reads Checked for syntax, and for filters that can never match. A valid path that finds nothing in the deployed configuration is still saved. The platform makes the same checks when a rule is created, and when a save changes a rule's path, whether the rule comes from this dialog or the API. A filter that is not a valid expression is refused with This rule path's filter is not a valid expression: ….
A Target Path whose filter quotes a value — $.jobs[?(@.name=="Report @ 5pm")].agent — is
refused when you save if the value is one the platform cannot match. Earlier builds saved such a rule
and showed it as active, but it selected nothing when the workflow was deployed, so the job kept the
source environment's value. The same checks as a job-scoped typed row
apply, plus one for single quotes. The row's Target Path reports:
| A quoted value in a filter that… | Message |
|---|---|
| Contains a line break | A quoted value in this filter contains a line break, which a rule path cannot express. Remove the line break. |
Contains )] or )' | A quoted value in this filter contains ")]" or ")'", which ends the filter early. Match on a value without it. |
Contains @ followed by a space, ., ), [, or one of root, parent, property, path | A quoted value in this filter contains "@" followed by a space, ".", ")", "[", or one of "root"/"parent"/"property"/"path", so the filter would match nothing. Match on a value without it. |
Is in single quotes and starts with ( — '(daily)' — or ends with ) anywhere but at the very end of the filter | A single-quoted value in this filter starts with "(", or ends with ")" in a way that breaks the filter. Use double quotes instead. |
Contains a type check such as @string() or @number() | A quoted value in this filter contains a type check such as "@string()" or "@number()", so the filter would match nothing. Match on a value without it. |
| Has no closing quote | A quoted value in this filter has no closing quote. Add the closing quote. |
A regex in a filter (/…/) is checked the same way for a line break, )] or )', @, and a
type check, with the message starting A regex in this filter and ending Change the regex so it
does not contain it. A regex with no closing / reports A regex in this filter has no closing
"/". Add the closing "/". A filter written as [?@…], without ( after [?, or with a space
after [ or ?, is read as a property name and matches nothing, so it is refused too: This
filter is written without "(" after "[?", or with a space after "[" or "?", so it is read as a
property name and matches nothing. Write it as "[?(…)]".
A single-quoted value ending in ) is accepted when its closing quote ends the filter, as in
$.jobs[?(@.name=='f(x)')].agent, and earlier text in the filter does not open a nested filter
([(, [?(, '( or '?(). Followed by anything else — another clause, a space, an inner ) —
it ends the filter early and is refused. Earlier builds refused every single-quoted value ending in
), including ones that worked. The same value in double quotes is always accepted. An ordinary @ in a
value, as in "a@b.com", is fine.
A filter may only read the workflow. It can compare values, combine comparisons with &&, ||
and !, and call these text methods on a value: match, test, startsWith, endsWith,
includes, indexOf, toLowerCase, toUpperCase, trim, substring, slice, split, charAt
and search — so $.jobs[?(@.name.match(/Null/))].name works as before. A filter that calls
anything else, assigns a value, or uses a regex with the g or y flag is refused when you save,
with This rule path's filter must only read the workflow, but …, followed by what it does and the
methods it may call. A rule saved earlier with such a filter no longer applies.
A source pattern must run quickly
A rule's Source Pattern runs over every key or value its path selects, each time the deployment
is served. A pattern that could take too long on some values — one whose repeats can match the same
text more than one way, such as (a+)+ or (\d|\w)+ — is refused when you save, and the message
names those two shapes to avoid. A pattern that cannot be checked in time, which is common for one
with a lookaround or a back-reference, is refused too, with advice to simplify it or save fewer new
patterns at once. Ordinary renames such as ^(\w+)_(\w+)$ or (.*)DEV(.*) are accepted, and so is
any pattern with no *, +, ? or {.
Two cases are not re-checked, so a deployment that already holds an older pattern can still be saved:
- An edit that leaves a rule's Source Pattern as it was.
- A pattern another rule of the same deployment, service request deployment or environment already uses.
A saved rule whose path can never match is named, not refused. A row that keeps the path it was saved with shows a warning under it, This saved path can never match anything. followed by the reason, and Deploy (or Save) still goes through, so you can rename or retype the rule. Change the path and the checks above apply. The same checks and the same warning apply to a service request rule's Target Path.
A rule whose stored value can't be read still degrades to a plain entry rather than breaking the dialog. Earlier builds failed to load the whole Design module when a deployment carried transformation rules.
When you save, rules are written before any are deleted, so a save that fails partway leaves every existing rule in place rather than removing one and failing to add its replacement.
A new rename is not refused for clashing with the rename it replaces in the same save. Re-saving a
deployment that already renames Daily to Weekdays — to add a second rename, or to edit that
row — goes through, and so does removing an Advanced RENAME_KEY row while adding one onto the
same key. If an Advanced save fails partway, the error says which removed rules were not deleted
and still apply; Save again to finish.
A rule scoped to a deployment is authorized against that workflow's own workspace. A rule scoped to an environment is different: it rewrites what is served to every workflow deployment and every service-request deployment in that environment, whichever workspace they belong to. So writing one requires Workflow Deployments Edit and Service Request Deployments Edit through grants that cover every workspace, in that environment.
A role scoped to particular workspaces is refused — otherwise the rule would reach deployments its author could not edit directly. See Where a grant has to be wider than one workspace.
Fields no rule may change
A transformation rule takes an arbitrary path, so a few fields are protected: a rule that would add, remove, or rename one is refused.
| Protected field | Why |
|---|---|
| Sub-Workflow flag | The Schedule Workflow dialog reads a workflow's stored setting while the build reads the transformed one, so a rule that changed it would make the two disagree about whether the workflow can be run directly. |
| A job's id | It is the job definition's persistent identity. A transformation applies per environment, so a rule reaching a job's id would give one definition a different identity in each environment while the stored definition kept another — and anything bound to that identity, such as a notification group member naming the job, would fire in some environments and silently not in others. |
A dependency's predecessor job id (predecessorJob.schedule.job.id) | The same argument one layer out: a rule here would aim a dependency at a different job identity in each environment. The name beside it stays transformable, which is the legitimate per-environment retarget — so leaving the id open would let the two disagree. The workflow id one level up (predecessorJob.schedule.id) also stays transformable: retargeting which workflow a dependency names per environment is supported. |
A job's Connection parameter (taskDefinition.parameters.batchUserId) | It only displays the attached credential; dispatch reads the job's connection reference. A rule here would look active and change nothing, and the job would authenticate as the source environment's account on the target environment's machine, reporting success. |
| What a workflow's events do — the completion-event list and everything in it, a job's event list, and each job event's event itself | Events are checked against the permissions of the person who saves the workflow. A rule that changed one would fire an event nobody was checked for. A job event's frequency stays transformable, which is what a per-environment frequency rename rewrites. |
A container job's sub-workflow reference (taskDefinition.parameters.workflow, and the id and name beneath it) | The sub-workflow deployment check runs against the reference as stored, and a transform rule is applied after it — so a rule that retargeted the reference would re-open exactly the failure the check exists to prevent, while the dialog still showed the target that passed. |
Retargeting a machine name or a path per environment is what these rules are for. Retargeting an identity, or a reference to one, never is.
connectionRefs is deliberately not protected: pointing a job at a different
connection per environment is a named, supported use of these rules. Target
$.jobs[*].connectionRefs[0].id. The Connection parameter beside it is re-synced to match the
reference when the deployment is served, so the served configuration stays internally consistent.
A rule on a protected field is refused when you save it, not silently at deploy time. That check covers every rule type — replace, delete, append, and rename alike — and it catches every spelling that reaches the field, including an array wildcard or a recursive descent. For an environment-scoped rule only the path's own spelling can be checked, because such a rule applies to every deployment in the environment and there is no single configuration to resolve it against.
A rename may not move a protected field either. A RENAME_KEY rule is refused, at every scope,
if it could rename a field on the way to a protected one, or rename another field onto one of those
names: jobs, events and subWorkflow at the top of the workflow; a job's id, taskDefinition,
events and dependencies; parameters under taskDefinition, and batchUserId and workflow
under it; and the fields from a dependency down to its predecessor job id, and from a job event down
to its event. Where the path could reach one of those names, name the one field to rename exactly,
as ^name$, and give a plain new name; the message says which names the path reaches. Frequency
renames, and a rename of an ordinary field such as ^workingDirectory$, are not affected.
Each rule is checked again as the deployment is served. After a rule applies, the protected fields are compared with the stored workflow. A rule that changed one anyway — replacing a whole job or job event with a value, for example — is left out, and the deployment is served with every other rule. Removing a whole job, a job event or a dependency still applies. Once five rules have been left out this way, every other rule is left out too, environment-level rules included, except the renames from the dialog's typed sections.
A refusal that happens at deploy time is not shown anywhere in the interface. That can happen to an environment-scoped rule whose path reaches a protected field by a spelling the save could not check, to a rule left out by the check above, or to a broad wildcard rule that sweeps across a protected field along with others: the protected field is skipped and the rest of the rule applies. The rule still looks active in the deploy dialog, but the protected field keeps its stored value. The same is true of a rule whose path matches nothing in the version being served: apart from the dialog's warning for a job-scoped rule whose job is gone, nothing tells you it had no effect. If a per-environment change is not taking effect, check the rule's path against the fields above and against the version the deployment serves.
Environment-level rules
Rules defined at the environment level apply to every deployment into that environment and are applied before a deployment's own rules. They're shown read-only in the deploy dialog, and job scoping doesn't apply to them — a job name only means something against one workflow.
Contact support when
- The active deployment points at a version that demonstrably differs from what's running in the environment.
Include the workflow, the environment, the deployment's version strategy/pinned version, and the effective/expiration dates.