Automation export and import
- Synopsis
- Full Details
In briefAutomation export and import move a bundle of workflows, calendars, frequencies, properties, thresholds, resources and tags from one environment or tenant into another. Export returns exactly the objects you list; import applies a bundle as a single all-or-nothing transaction, matching existing objects by name.
WhereThere is no screen: both are API operations, run by an administrator with a client. Both need permissions that reach every workspace — see Permissions.
When
- You are carrying a configuration built in a test environment into production.
- You are lifting a working pattern from one institution's tenant into another.
To promote a single workflow through its own lifecycle, use Versions and deployments instead — usually the right choice.
How
- Export the objects you want, listing every calendar, frequency, property, threshold and resource the workflows use — export does not follow references.
- Import the bundle in the default mode, which refuses the whole import if any object already exists, or in overwrite mode to update existing objects in place.
- Move new objects out of the General workspace to where they belong.
- Re-enter every encrypted property value by hand.
- Workflow names are matched without regard to case; every other kind of object is matched exactly.
- Import points references to calendars, frequencies, thresholds, resources and tags at the objects in the target environment. A reference to an object deleted there is refused, not moved to a namesake.
- Import also points jobs' cross-workflow dependencies, scripts, runners, agent pools, agents and connections at the target's objects by name; one that matches nothing keeps its identifier, with a warning.
- Every imported job gets a fresh identity.
- Imported jobs' custom fields are checked as a save checks them; a job with no value gets the field's default, a value that does not fit refuses the whole import, and a value for a field that was deleted or has never existed here is removed and listed in the response.
- Encrypted property values are never exported; those properties arrive empty.
- Overwrite mode restores and overwrites a deleted object whose name is in the bundle.
- A timed-out import (408) may still complete. Check before retrying.
- An import is not checked for sub-workflows that are undeployed where the workflow runs Latest.
This page is the reference for moving configuration between environments. For promoting a single workflow through its own lifecycle, see Versions and deployments — that is a different mechanism and usually the right one.
Automation export and import move a bundle of objects out of one environment or tenant and into another. It is how a configuration built in a test environment is carried into production, or how a pattern that works for one institution is lifted into another tenant.
Export produces a bundle. Import consumes one. The bundle that comes out of export is directly usable as the input to import, which is what makes the round trip possible.
There is no screen for export or import. Both are API operations, so this is an administrator task performed with a client rather than something a builder does in the interface. Everything on this page describes behavior the API provides; the concepts are what matter if someone else runs it for you.
- Bundle Contents
- Export
- Import
- Permissions
- Troubleshooting
Bundle Contents
What a bundle can contain
Seven kinds of object:
| Kind of object | Details |
|---|---|
| Workflows | The current version of each. See Versions and deployments. |
| Calendars | Calendars |
| Frequencies | Frequencies |
| Properties | Properties |
| Thresholds | Thresholds and resources |
| Resources | Thresholds and resources |
| Tags | Tags |
A bundle can hold any mixture of these, including just one kind. It does not have to contain workflows.
Export
Export takes a list of the objects you want and returns them in bundle form.
Only what you ask for is exported. This is the single most important thing to know about export: it does not follow references. Exporting a workflow does not pull in the calendars, frequencies, properties, thresholds or resources that workflow depends on. If you want them in the bundle, list them too.
That is a deliberate choice — it keeps a bundle to exactly what you selected — but it means an incomplete bundle is easy to produce and only shows itself on import, when the target environment turns out not to have something the workflow refers to. Build the list from what the workflow actually uses.
What export strips or omits:
| What is stripped or omitted | What happens to it |
|---|---|
| Identifiers, audit timestamps and links | Removed from each exported object. The bundle describes objects by name, which is what lets it land in a different environment where the internal identifiers differ. A workflow's or frequency's references to other objects keep the name and the source environment's identifier; import repoints them — see What import fixes up for you. A reference to a threshold, resource, tag or calendar carries that object's current name, even if it was renamed after the workflow or frequency was last saved. |
| Encrypted property values | Excluded. The property is exported and arrives with an empty value. See the caution below. |
| Deleted objects | Cannot be exported. Asking for one reports that it is gone rather than silently omitting it. |
Names for scripts, runners and connections travel with the bundle. A job holds its script, runner and connection by identifier only, and an identifier means nothing in another environment. So export adds a referenceNames table to the bundle, naming each script and runner the exported jobs use — those you can view — and each connection a job's settings name. Import uses those names to find the same objects in the target. Send the whole export, referenceNames included, as the import; nothing has to be taken out of it first.
A property whose value is encrypted is exported without its value. This is intentional — it is what stops a secret being carried out of an environment in a file — but it means every encrypted property must be given its value again by hand in the target environment after the import. An import that appears to have succeeded can still leave a workflow unable to run for exactly this reason, so treat re-entering those values as part of the import, not as follow-up.
Import
Import takes a bundle and applies it to the current environment.
It is all or nothing
The whole bundle is applied as a single transaction. If any object in it fails for any reason, nothing is written — there is no partial import to unpick. A failed import leaves the environment exactly as it was.
A large import can outlast the service's request time limit (45 seconds by default). The request then returns 408 Request timeout, but the import keeps running and can still complete. Before you retry, check whether the objects are already there. A retry in the default mode is refused as a conflict if the first attempt finished; a retry in overwrite mode applies the bundle a second time.
Conflicts, and the overwrite decision
Import matches objects in the bundle against what already exists by name. What happens next is the one decision you have to make:
| Mode | Behavior |
|---|---|
| Default (fail on conflict) | If any object in the bundle already exists, the whole import is refused as a conflict and nothing is written. Use this when the bundle is meant to be new: it will not quietly modify anything you already have. A deleted object with the same name is not a conflict; a new object is created beside it. |
| Overwrite | Existing objects are updated in place and new ones created. A deleted object with a matching name is restored and overwritten, so an object you deleted on purpose comes back. Use this mode when you are deliberately pushing a newer configuration over an older one, and check the bundle for names you have retired. |
The result tells you which happened: everything created, or at least one thing updated. It can also carry warnings about a workflow that will fail when it runs, such as a script or runner it names that cannot be found here; a warning never refuses the import.
Where imported objects land
New workflows, properties, thresholds and resources are created in the General workspace. An object that is updated or restored keeps the workspace it already had. Move new objects to their proper workspace after the import. See Workspaces.
An import does not run the commit check for sub-workflows
Importing over an existing workflow gives it a new version, and a deployment set to Latest runs that version from its next build. A commit in the workflow editor is refused if it would leave a Latest deployment embedding a sub-workflow that is not deployed in that environment. An import is not checked this way. Before importing a workflow with Workflow Container jobs, make sure each sub-workflow is deployed wherever the workflow runs Latest. See Committing a version is checked too.
What import does check is the opposite case: a bundle that would leave a workflow's Sub-Workflow setting off while a container job still embeds that workflow is refused, with the workflows that use it named once each, and any environments where they are deployed named by their names.
Names are matched exactly for every kind of object except workflows, which are matched without
regard to case — so a bundle naming Nightly-Core-Export will match an existing
nightly-core-export and update it rather than creating a second workflow.
An import is a clone, not a restore
Every job in an imported bundle is given a fresh identity, always — even when the bundle came out of export minutes earlier. Object identity is what other things point at, and a reused identity would make one notification member fire for two different jobs.
This has a consequence worth understanding before using overwrite mode:
Importing over a workflow that already exists replaces the identity of every job in it. The workflow's history keeps the old identities and the new version carries new ones, and the two cannot be reconciled afterwards. A notification member that names one of those jobs specifically is bound to the old identity, so it no longer matches the job; select the job again in that member. Prefer the default mode unless you specifically intend to overwrite.
What import fixes up for you
- References to calendars, frequencies, thresholds, resources and tags are pointed at the objects in this environment. That covers a workflow's holiday calendar, its frequencies, its jobs' tags, threshold and resource dependencies, the frequency on an event or on a dependency, and the calendars a frequency pattern names. Each reference goes to the bundle's own copy of the object when the bundle carries one; otherwise to an object here with the same identifier, taking that object's current name if it has been renamed; otherwise to the object here with that name. So an imported calendar lists the frequencies that use it and cannot be deleted from under them, an imported workflow deploys with its frequencies, and its threshold and resource dependencies find what they name. One exception: an identifier that names an object deleted here is not moved to a different object that has since taken its name — the import is refused instead (see Troubleshooting). A frequency's exclusion calendar is the one reference left as it is rather than refused. The same rule applies when a workflow is saved; see Renaming or replacing an object a workflow uses.
- Names are validated against the rules for each kind of object, and an object being updated under its existing name is not re-checked. See Object naming.
- Dependencies on jobs in other workflows are pointed at the workflow and job in this environment: the bundle's own copy of the workflow when it carries one, otherwise the workflow here with that name. A dependency whose workflow is in neither, or is in a workspace you cannot view, refuses the import with Schedule 'X' not found. Either provide it in the import request or ensure it exists in the system., and one whose job is not in that workflow with Job 'A' not found in workflow 'X'. See Dependencies.
- The workflow a container job runs is pointed at the workflow in this environment: the bundle's own copy when it carries a workflow of that name (trimmed, any case); otherwise a workflow here with the same identifier, whose current name is taken; otherwise a workflow here with exactly that name. When none of these is a workflow you can view, the job keeps the name, loses the source identifier, and the import goes ahead with a warning — Job 'X': workflow 'Y' was not matched by id or exact name to a workflow you can view here, so its id was not kept. The job keeps the name; check that it selects the right workflow. An identifier that names a workflow deleted here is kept, with a warning that says so. Earlier imports kept the source environment's identifier on every container job.
- Scripts, runners, agent pools, agents and connections a job uses are pointed at the objects of the same name here: a script or runner by its name in referenceNames, an agent pool by its name and kind, an agent by its name within the pool that matched (or by a name no other agent here has), and a connection by its name and connection type. They are looked up with your own permissions. One that matches nothing here keeps the bundle's identifier, and the import goes ahead with a warning that names the job — for example Job 'Load': script 'Nightly-Load' (id '…') matches no script here. The job keeps the id; choose another script. An agent name that more than one agent here shares is reported as ambiguous instead. If the agents and connections cannot be read at all, each kind is kept as the bundle has it, with one warning that says why. A bundle from an earlier export has no referenceNames, so its scripts and runners keep their identifiers.
- An exclusion calendar that matches nothing here keeps the bundle's identifier and is reported in a warning — Calendar 'X' (id '…') matches no calendar here. The reference keeps the id; choose another calendar., or … is deleted here. … — rather than refusing the import.
- Property values marked encrypted in the bundle are encrypted at rest on arrival, exactly as if they had been created directly in the target environment.
- Custom fields on imported jobs are checked against your organization's custom field definitions exactly as a workflow save checks them: a job with no value for a field is given its default, a value for a field that was deleted here or that has never existed here is removed, and a missing required value or a value that does not fit its field refuses the import. The import is all or nothing — when any workflow is refused, nothing is written — and each message names the workflow and the job. A value the import removes is reported: the response carries a removedCustomFields list naming the workflow, the job and the field (with its name when the field was deleted), and is absent when nothing was removed. Values are matched to a definition by its identity, not its name, so a bundle from another tenant whose jobs carry custom-field values arrives without them, and the list shows each one. If the field definitions change while the import reads them, it is refused with Custom field definitions changed while they were being read. Try again. See How a default reaches a job.
Permissions
Both operations reach across the whole tenant, so a role limited to particular workspaces cannot run them. See Where a grant has to be wider than one workspace.
| Operation | Your role needs |
|---|---|
| Export | Permission to view workflows (Workflows View), and View on every workspace for each object type the export asks for. |
| Import | Permission to create workflows (Workflows Create), and Create and Edit on every workspace for each object type the bundle carries. You also need the permission every event in the bundle's workflows needs — all of them, not only new ones, because an import replaces each workflow's configuration. See What an event is refused for. |
Troubleshooting
| Symptom | Likely cause | Resolution |
|---|---|---|
| Import refused, reporting that one or more objects already exist | The default fail-on-conflict mode, and something in the bundle matches an existing name | Decide deliberately: remove those objects from the bundle, rename them, or re-run in overwrite mode. |
| Import refused: Calendar 'X' not found. Either provide it in the import request or ensure it exists in the system. | A frequency in the bundle names a calendar that is neither in the bundle nor in this environment. For an Annual Plan that calendar is the whole schedule, so it is always required; an exclusion calendar is required when the bundle names it without an identifier | Add the calendar to the bundle, or create it here first. |
| Import refused: Threshold 'X' is deleted. Restore it or use a different threshold. (or the same for a calendar, frequency, resource or tag) | The bundle refers to that object by an identifier that names an object deleted in this environment — typically a bundle exported here before the object was deleted — and the bundle does not carry the object itself. The reference is not moved to a live object of the same name | Restore the deleted object, include the object in the bundle, or point the reference at the object you mean before exporting again. |
| Objects imported by an earlier build do not show as referenced, or an imported workflow deployed without its frequencies | Earlier imports kept the source environment's identifiers on references | Import the bundle again in overwrite mode, which repoints them. |
| The import response carries warnings that a job's script, runner, agent pool, agent or connection matches no … here | Nothing of that name exists in this environment, or you cannot view it. The job keeps the source environment's identifier, which names nothing here | Create the object here, or choose another one on the job, and save the workflow. |
| Import succeeded but a workflow will not run | The bundle omitted something the workflow refers to, or an encrypted property arrived empty | Check that every calendar, frequency, property, threshold and resource the workflow uses exists in this environment, and re-enter encrypted property values. |
| An exported bundle is smaller than expected | Export does not follow references — only the objects named in the request are included | List the referenced objects explicitly and export again. |
| A property imported with no value | Its value is encrypted, and encrypted values are never exported | Set the value in this environment. It cannot be recovered from the bundle. |
| Export reports an object is gone | It has been deleted in the source environment | Deleted objects cannot be exported. |
| Import refused for permission | Your role is limited to particular workspaces, or lacks Create or Edit for one of the object types in the bundle | See Permissions. |
| Imported objects are in the General workspace | New objects are always created there | Move them to the workspace they belong in. |
| An object you had deleted is back | Overwrite mode restores a deleted object whose name is in the bundle | Delete it again, and remove it from the bundle before the next import. |
| Import returned 408, but the objects exist | The request timed out while the import carried on and completed | Expected. Check what was written before retrying. |
| After an import, an environment on Latest fails to build a workflow with a container job | The import is not checked for undeployed sub-workflows | Deploy the sub-workflow to that environment, or pin the workflow's deployment there. |
| Imported jobs carry values they did not have in the bundle, or lost a value | A job with no value for a field is given the field's default, and a value for a field deleted here is removed — the response lists each one in removedCustomFields | Read that list, then set the values on the imported jobs, or set each field's Default Value before you import. See How a default reaches a job. |
| The import is refused with Custom field validation failed, naming a workflow and a job | A job in the bundle is missing a required value or holds a value that does not fit its field | Correct the value in the source and export again. Nothing was written. |
| A second workflow was expected but an existing one was updated | Workflow names match without regard to case | Choose a name that differs by more than capitalisation. |