Environments, Companies and Backup

How SOD customizations relate to companies and environments, how to move a tested app from sandbox to production, and how to back up and restore your SOD work.

One Company, All Companies

Two facts that resolve most confusion:

Always work with Simple Object Designer from one and the same company. Pick one company and do all SOD work there.
A deployed extension is active in ALL companies in that environment. Customizations apply environment-wide; there is nothing to do per company.

Building the same feature separately in a second company is unnecessary, and it can leave that company in an inconsistent or blank state that blocks further deployments.

If the SOD page cannot be found in a particular company, suspect permissions rather than a per-company setup step — see Common Issues.

Licensing Across Environments

An SOD license covers all environments within a single Business Central tenant, sandbox and production alike. A new production environment in the same tenant needs no additional license.

Note that Export App / Import App require a licensed environment. If those actions are greyed out or unavailable, the environment is not licensed. When moving customizations between environments, apply the license key to both the source and destination environment.

The Recommended Workflow: Dev Sandbox → Production

Keep SOD in one place and move a compiled app outward:

Designate one sandbox as your dev sandbox.
Do all development there.
Test until you are satisfied.
Publish. SOD gives you an .app file.
In production, go to Extension Management > Manage > Upload Extension and deploy that file.

SOD does not need to be installed in the target environment for this method.

Do not rebuild a customization by hand in production. Recreating fields, placements and transfers manually produces different results between environments — the classic symptom is a field that appears on the page but stays empty, in production only. Deploy the same tested app instead.

The trade-off: if production has only the compiled .app and not SOD itself, you will not see your custom fields, queries and objects in SOD in production. That is expected. Make every further change in the dev sandbox and re-deploy the updated .app; never recreate them in production.

Deploying to Multiple Environments

Customizations built with SOD are published as an ordinary Business Central extension, and extensions are installed per environment.

The extension does not automatically carry over to a new or additional production environment.
Business Central has no multi-environment deployment process. Publishing once does not update several environments at the same time.
Every change must be deployed to each environment separately.

Two ways to do that:

Option 1 — Install the .app file (recommended)

After a successful publish in the source environment, download the .app file from SOD
In the target environment, open Extension Management
Manage > Upload Extension
Select the .app file and deploy

All environments then run the exact same tested version.

Option 2 — Install SOD in the target environment and publish there

Install SOD in the target production environment
Re-download symbols
Publish from that environment

Limitation: in production, symbol download requires the Snapshot Debugging permission in addition to SUPER. See Required Permissions.

Keeping Version Numbers in Sync

Version numbers stay aligned naturally when you always build in the sandbox and then deploy to production. A discrepancy appears when someone deploys straight to production without building in the sandbox first.

To bring a sandbox back in sync: the sandbox version only needs to be equal to or higher than production. Set the version in the SOD Setup page to a valid X.X.X.X value at or above production, publish successfully to the sandbox, then deploy to production.

"Error parsing version string" on deployment

Error text:

Deploy Operation rejected. Error: Error parsing version string:. Path 'value[6].applicationDependencyVersion', line 1, position 5972.

Despite mentioning the version string, this often points at the version number of one of the app's dependencies, not your own app version.

First step: on the SOD Setup page run Refresh Symbols and answer Yes to clearing the cache, then publish again.

Known root cause: this error has been confirmed by Microsoft as an issue on their side, with a hotfix in progress. If your version number in SOD Setup is a valid major.minor.build.revision and Refresh Symbols does not help, nothing further inside SOD will resolve it — wait for the Microsoft fix.

Backing Up and Restoring Your SOD Work

Installing SOD in a new or empty environment does not bring your existing SOD creations with it. Back them up explicitly.

Export App

On the SOD Setup page, use Export App to save your SOD configuration to a JSON file. Keep this file.

Import App

In the new environment, install SOD and use Import App on the Setup page to upload the file. Import App also accepts an .app file previously published from SOD.

Keep every .app file

As long as a downloaded .app file is preserved, it can be re-imported to restore that exact version of the SOD app — the SOD app definition is captured inside the file, so importing it restores the editable design, not just the compiled extension.

Recommended practice: download and retain the .app file for every version you publish. Each retained file is a restore point.

The limitation is absolute: recovery is only possible if a file was exported and kept. If neither an exported JSON nor an .app file exists, the SOD data cannot be recovered.

The scenario this protects against

A very common sequence: you modify the SOD app in a sandbox, deploy the extension to production, then the sandbox is deleted and refreshed from a copy of production. The deployed extension survives — but the SOD design data in the sandbox is gone. With the .app file (or an exported JSON) you simply Import App and carry on.

The same applies whenever a test environment is rebuilt from production: export first, then import into the new environment.

Switching Between Multiple SOD Projects

If you develop several separate SOD apps in one environment:

Before switching away, Export App to save the current configuration to JSON (or use the .app file from a publish)
Init New App to start a fresh project
To return to a previous project, Import App with that project's exported JSON or .app file

Importing a SOD Configuration Between Environments

Importing a SOD configuration (as opposed to installing the compiled .app) can fail with an error of this form:

The supplied field number 'NN' cannot be found in the 'API Pages' table.

If you hit this, send the error's Copy Details to support@hougaard.com so it can be investigated.

The reliable way to avoid needing this import at all is the dev-sandbox workflow above: keep SOD in one place and move only the compiled .app outward.

Merging Two SOD Installations

SOD has no feature to merge two separate SOD-generated extensions into one. This is not a supported operation, and doing it by hand is complicated and error-prone.

Two different kinds of SOD data must be handled:

Fields added to existing tables
New tables added (features)

Why data does not carry over automatically: the two SOD extensions use different object ID ranges, so "the same" field has a different internal field ID in each extension. Data therefore does not transfer between them. See Object Numbering.

If you must do it, the manual data migration is:

Export the existing data from Business Central into a Configuration Package Excel sheet
Perform all the SOD changes in the surviving SOD instance, so the fields and tables exist in that extension
Export a new Configuration Package to Excel from the surviving structure
Manually copy the data from the old sheet into the new sheet
Import the new Configuration Package back into Business Central

Test the whole sequence in a sandbox first and take a backup before starting.