Move integrations between environments

This screen exports the tenant's whole integration setup as one JSON file and applies such a file in another environment or tenant, for example from test to production. It is used by integration owners and release managers. Credentials never travel: after an import each connection and connector is flagged so its secret can be added in the target. For the command line routes for other kinds of definitions see Command line - move definitions between environments.

Move between environments

Where to find it

Studio Explorer > Workspace > Integrations > Move between environments. Page key integration-bundle. The Connector Catalog screen also has Export and Import buttons that use the same bundle for connectors and flows.

Key concepts

Term	Meaning
Bundle	A JSON file with "format": "spark-integration-bundle" and "version": 2. A version 1 bundle (connectors and flows only) is still accepted.
Preview	An import that reports what would change and writes nothing.
Change	Per item: new (does not exist in the target), changed (exists with different content), unchanged, rejected (invalid, with a reason).
Needs credentials	Connections and connectors that arrived without a stored secret.

What a bundle holds

Section	Content	What does not travel
connectors	Connector definitions of the integration domain: name, address, sign-in type and settings, request path, method, request template, response and status mapping, notes.	The secret value; only the secret's name (requiredSecrets) is recorded.
flows	Flow code, name, description and definition.	Run history, schedule, trigger event, signing secret, on or off state.
connections	Code, name, address, auth type, auth settings, connection type, and hasSecret.	The password or key.
queues	Code, name, attempts, retry seconds, retention days, enabled, and the bridge direction, connection and destination.	Messages.
syncs	Code, name and definition.	Run history, remembered agreed values, disagreements.
lookupTables	Code, name, description, entries.
pollTriggers	The trigger settings.	State: last look, last error, last item count, and the memory of items already seen.
fileWatches (added by the screen from a separate export)	Code, name, connection, directory, file pattern, interval, processing, processed and failed folders, retention days, acknowledgement ending.	State and the record of files taken.

Rules on import

• New items arrive switched off: flows are DISABLED, queues are not enabled, synchronizations are off, poll triggers and folder watches are not watching, connectors are inactive. Something that already exists keeps its current on or off state. Nothing already switched on is ever switched off by an import.
• A connection arrives without a secret. If its auth type is not NONE and it has no stored secret in the target it is listed as connection:CODE under needs credentials. A connector whose authConfig.secretRef names a tenant secret that does not exist in the target lists that secret name.
• A flow is validated by the flow engine first. A flow that fails is rejected with the validator's messages joined by semicolons.
• A connector with a name that is not lower-case letters, digits and dashes, or with an address that is not a public https address, is rejected.
• Queues, synchronizations, lookup tables and poll triggers are validated like a normal save; a failure is rejected with the reason.
• Importing the same bundle twice reports every item unchanged.
• Import order inside a bundle is connectors, flows, connections, queues, synchronizations, lookup tables, poll triggers. A queue bridge needs its connection to exist; export a bundle that contains both, or import the connection first.
• A bundle whose format is not spark-integration-bundle or whose version is not 1 or 2 is refused: "this is not an integration bundle (format spark-integration-bundle, version 1 or 2)". The screen checks the format itself first: "this file is not an integration bundle".

Screen

Panel	Controls	Effect
Export	Prepare export, Download	Prepare reads the bundle and the folder watches and shows the counts "N connectors, N flows, N connections, N queues, N syncs, N lookup tables, N poll triggers, N folder watches". Download saves integration-bundle-YYYY-MM-DD.json.
Import	Choose a bundle file, Preview, Apply	Preview shows "Preview only - nothing changed". Apply shows "Imported (new items are switched off)".
Result	Sections Connectors, Flows, Connections, Queues, Synchronizations, Lookup tables, Poll triggers, Folder watches	Each item has a chip (new, changed, unchanged, rejected) and any reason. A warning lists "These connections need a password added on the Connections screen: ..."

Procedure: promote test to production

1. In the test environment open the screen, select Prepare export, then Download.
2. Sign in to the production environment and open the same screen. Choose the file and select Preview. Read the rejected items and the credentials warning.
3. Select Apply. Everything new arrives switched off.
4. Add the secrets: open Connections and edit each flagged connection; for connectors run erp connector secret set NAME --from-file secret.txt.
5. Test each flow from the designer, then switch on in the order that matches your data: connections tested, flows, triggers.

Permissions

Resource integration.bundle: view exports and previews, manage imports. Folder watch bundle calls use integration.flow (view to export and preview, manage to apply). An import is audited as integration.bundle.imported.

API and CLI

Purpose	Request
Export	GET /api/v1/integration/bundle
Preview	POST /api/v1/integration/bundle/preview with {"bundle": {...}}
Import	POST /api/v1/integration/bundle/import with {"bundle": {...}}
Export folder watches	GET /api/v1/integration/bundle/file-watches
Import folder watches	POST /api/v1/integration/bundle/file-watches/import with {"fileWatches":[...],"commit":false}

The result of preview and import: committed, then one list per section of {key, change, reason?, switchedOn?, hasSecret?}, and needsCredentials.

{
  "format": "spark-integration-bundle",
  "version": 2,
  "exportedAt": "2026-10-05T09:00:00Z",
  "connectors": [],
  "flows": [
    {
      "flowCode": "order-to-partner",
      "name": "Order to partner",
      "description": "Posts new orders to the partner.",
      "definition": {
        "steps": [
          { "code": "send", "type": "REST", "method": "POST", "connectionCode": "partner-api", "url": "/events", "body": { "orderId": "${input.id}" } }
        ]
      }
    }
  ],
  "connections": [
    { "connectionCode": "partner-api", "name": "Partner API", "baseUrl": "https://api.partner.example", "authType": "BEARER", "authConfig": {}, "connectionType": "REST", "hasSecret": true }
  ],
  "queues": [],
  "syncs": [],
  "lookupTables": [],
  "pollTriggers": [],
  "requiredSecrets": []
}

Command	Purpose
erp integration export [--out <file>] [--tenant <id>]	Write the bundle (connectors, flows, connections, queues, syncs, lookup tables, poll triggers).
erp integration import <bundle.json> [--apply] [--tenant <id>]	Preview by default; --apply imports. Prints "credentials to add here: ..." for each secret to add.
erp connector secret set <name> [--from-file <path>]	Add a connector secret in the target.
erp connection save <code> ... --secret-from-file <path>	Add a connection secret in the target.

The CLI route covers the sections of the bundle endpoint. Folder watches travel through this screen or the folder-watch bundle endpoints above.

Plugins as the alternative

A plugin can carry flows, queues, synchronizations and connections as files under metadata/flow, queue, sync and connection. When the plugin is installed everything arrives switched off and keeps its state on upgrade; connections install first; a connection arrives with no password. See Integration and Connector Designer.

Limits and behaviour

• Preview and import run one pass, so the preview cannot say something the import then does differently.
• The export lists at most 500 connectors.
• Poll trigger and folder watch comparisons ignore state, so a trigger that is only running differently reads unchanged.

Errors and troubleshooting

Message	Cause	Fix
"this file is not an integration bundle"	Wrong file chosen.	Choose a downloaded bundle.
"this is not an integration bundle (format spark-integration-bundle, version 1 or 2)"	Wrong format or version through the API.
"a flow needs a code and a definition"	A flow entry is incomplete.
"a connection needs a code and an address"
"the connector name must be lower-case letters, digits and dashes"
"the connector address must be a public https address"
"a folder watch needs a code, a name, a connectionCode and a directory"
Flow rejected with validator messages	The flow definition is invalid in this environment, for example a step names an unknown step.	Fix the definition at the source and export again.
Needs credentials lists a connection	The target has no secret.	Edit the connection and enter it.

Related

Overview, Connections, Connector Catalog, Command line - move definitions between environments.