Skip to main content

Configuration packages and environment compare

A configuration package is a JSON file holding configuration: source systems with their instances, endpoints and datasets, variables, export systems, actions, jobs and schedules. It is how configuration moves from one environment to another, from one install to another, and how a template from the gallery is installed. Environment compare does the same promotion between two environments of one install without a file.

Building a package and comparing environments need Enterprise. Loading a package is available on every plan, because a package is how a customer receives a ready-made setup.

What a package carries​

A package carries the configuration as it stands, including passwords and keys typed straight into a field. Three things stay behind:

  • Variable values. A variable travels as a declaration with no value, so a secret kept in a variable never leaves the install. This is the way to keep secrets out of a package: put them in variables.
  • OAuth sign-ins. The receiving install presses Connect… again.
  • A Key Vault variable's vault reference, which names the exporting install's vault; the receiving install maps the variable to a secret in its own vault.

Also left out: the diagram layout, load positions and watermarks, rename locks, run history, API keys, settings and Data access roles.

Objects are matched by name, never by id: a source system by its name, an instance by source system and name, a dataset by source system and name, an endpoint by its method, path and body, a variable, action, job or schedule by its name. A renamed object therefore reads as one new object and one removed one.

Build a package​

Open Setup → Environments, the pencil of the environment to copy from, and the section Build a configuration package. Give it a Package name, Version, Author and Description, tick the objects in the picker (ticking a node ticks its whole branch; Nested and Flat list views, a name and type filter), and press Download package.

Include what they depend on (on by default) adds what the chosen objects point at: the export system an action writes to, the variables its templates name. Without these the package loads and then fails on its first run. Variables the selection needs are shown in bold. After the download, a warning lists any gaps: objects the export points at that no longer exist here.

Load a package​

Source Systems → Import configuration package opens a file picker, then a dialog for the chosen file. The package loads into the environment you are in.

  • External references — things the package points at but does not contain, each with a dropdown to say where it lands here. Exact name matches are prefilled; a required one left unbound blocks the load.
  • The item list with New or Already exists per item. New items are ticked (they will be created); existing ones are unticked (kept as they are), and ticking one means overwrite. On a row with children, a dropdown can redirect the branch: Merge into <existing> loads a "Business Central" pack under your "BC Prod".
  • Warnings name what arrives without a value: variables to fill in, Key Vault variables to map to your own vault, fields that need a value after loading, and dependencies that are not ticked.
  • Load package runs item by item and reports created, overwritten, kept as they were, failed, with a line per failure. Plan limits apply to what the load creates (source systems, instances, actions).

Overwrite replaces the target object with the package's: fields the package carries are written, and fields the package lacks are cleared to their defaults, except ids, timestamps, sign-in tokens, locks, load positions, and an existing variable's value and vault reference. There is no undo.

Compare and sync environments​

The panel Compare environments sits under the table on Setup → Environments once the install has two or more environments. Pick From (source) (read only, never written to) and To (target), tick What to compare (source systems, export systems, actions, jobs, schedules, variables; everything under a ticked item is compared, plus what it depends on), and press Compare. Nothing is written until you press Sync.

The result has four tabs:

  • New and removed — objects missing from the target, to be created, and objects only in the target, to be deleted (a soft delete; loaded data is untouched). Each section has a select-all.
  • Changed — objects in both with differing lines, each shown as path from → to, with a select-all.
  • Danger zone — the rows you should read before ticking, one by one: connection details (base URLs, servers, databases, credentials, which are usually different between environments on purpose, and syncing one repoints the target at the source's), an enabled switch that travels, and ids typed in where a variable would have let each environment keep its own. Hover a mark for the reason. There is no select-all here.
  • Unchanged.

Sync N change(s) creates and overwrites first, then deletes, and compares again. A delete is refused while something outside the deletion set still uses the object. Overwrite follows the same rule as a package load; global variables are never written by a sync; the environments' variable values stay their own.