Simple Object Designer Documentation
Index

Installing Downloaded Apps

You can download your customization as an .app file and install it in other environments. This page explains the process.

When to Use App Files

Use Cases

  • Production deployment - Install tested app in production
  • Multi-environment - Same app in multiple tenants
  • Archival - Keep version copies
  • Distribution - Share with other organizations
  • No SOD needed - Target doesn't need SOD installed

Benefits

  • Install without SOD in target
  • Exact same version everywhere
  • Audit trail of versions
  • Controlled deployment process

Downloading the App File

After Publishing

  1. Complete a successful publish
  2. Download option becomes available
  3. Save the .app file locally — you may need to click Keep on the browser download

The .app contains your entire SOD extension — every field, page, feature and API configured in that SOD instance. There is no way to download or export a single published API endpoint on its own.

An external vendor does not need the .app to consume an API. They call the published endpoint over HTTPS with OAuth 2.0 — see Consuming APIs. Handing over the .app is only necessary when the extension itself must be installed in another Business Central environment.

If customizations genuinely need to be split into separate extensions, Dual-App mode and Init New App are the mechanisms — see Advanced Settings.

An installed .app is not editable

Uploading an .app into another environment — for user testing or inspection — gives you the deployed result, not an editable SOD project. In that environment you cannot amend the table schema or add and change fields.

To make changes, go back to the original development sandbox where the feature was created in SOD, change it there, and publish a new version. You do not need to recreate the table as a new project in the target sandbox.

Moving an existing customization from production into a sandbox

If SOD and its customizations currently live in production and you want to move development into a sandbox:

  1. In production, use Export App to export the customization
  2. Install SOD in the sandbox
  3. In the sandbox, use Import App with the exported file
  4. Apply your license key in the sandbox — see Registration and Licensing

From then on, develop in the sandbox and publish there to produce the .app for production.

Import App — accepted file formats

Import App accepts exactly two kinds of file:

  1. A JSON file created by Export App, containing the SOD configuration — field definitions, page placements, feature definitions, API configurations, setup settings
  2. An .app file generated by the SOD Publish process, from which Import App extracts the embedded source definitions

What will not import:

  • A compiled .app that was not produced by SOD — one built in VS Code or published externally. Only SOD-generated .app files carry extractable source definitions. The error looks like: "A DotNet variable has not been instantiated. Attempting to call System.IO.Compression.ZipArchiveEntry.Open in CodeUnit Data Compression Impl."
  • A .zip of AL source files, which is not a supported format at all. The error looks like: "A call to System.IO.Compression.ZipArchive.GetEntry failed with this message: Number of entries expected in End Of Central Directory does not correspond to number of entries in Central Directory."

Both errors mean the file is not a recognized SOD export format — not that the file is corrupt.

Licensing: Import App and Export App are limited to the paid (registered) version of SOD. They are not available in demo mode or in an unregistered sandbox.

App logos are not supported

SOD cannot add a logo to an app or extension package, and there is no way to upload a PNG or other image as an extension logo. This is a current product limitation.

Because apps have no logo, the tile view of the Extension Management page shows no custom image. Switch that page to List view instead of the default tile view.

App File Location

The .app file can be:

  • Downloaded from deployment page
  • Found in SOD output location
  • Stored locally after download

File Naming

App files are named:

{Publisher}_{ExtensionName}_{Version}.app

Example:

Contoso_Customizations_1.0.0.5.app

Installing via Extension Management

Accessing Extension Management

  1. In target environment, search "Extension Management"
  2. Open the Extension Management page

Upload and Install

  1. Click Manage > Upload Extension
  2. Select your .app file
  3. Click Deploy
  4. Choose deployment options

Deployment Options

Option Description
Language Installation language
Accept Accept install terms
Sync Mode Synchronize or Force Sync

Installation Process

What Happens

  1. Upload - File uploaded to BC
  2. Validation - BC validates the package
  3. Schema sync - Database updated
  4. Installation - Extension activated

Timeline

Similar to direct publish:

  • 1-5 minutes typical
  • Depends on extension size
  • Check deployment status

Verifying Installation

After Installation

  1. Check Extension Management
  2. Verify your extension appears
  3. Status should be "Installed"

Testing

  1. Open affected pages
  2. Verify customizations work
  3. Test key functionality

Updating Installed Apps

Uploading New Version

To update an existing installation:

  1. Download the new .app file from the sandbox — the version auto-increments on publish
  2. Upload it via Extension Management > Manage > Upload Extension in production
  3. BC detects the higher version with the same extension ID as an update
  4. Runs upgrade process

You do not need to uninstall the previous version first. Business Central recognizes it as an update and runs the upgrade.

Monitor progress through the installation status in Extension Management — Business Central does not show SOD's publish progress screen for this path.

Version Compatibility

  • Must have same extension ID
  • Version must be higher
  • Schema changes may require Force Sync

Uninstalling Apps

Removing the Extension

  1. Open Extension Management
  2. Find your extension
  3. Click Uninstall
  4. Confirm removal

What Happens

  • Extension deactivated
  • May prompt about data
  • Custom fields may be removed

Data Considerations

When uninstalling:

  • Data in custom tables may be deleted
  • Custom fields on standard tables removed
  • Consider data export first

Multi-Environment Deployment

Deployment Pattern

  1. Develop in sandbox with SOD
  2. Test thoroughly
  3. Download .app file
  4. Install in UAT environment
  5. Test again
  6. Install in production

Consistency

Using .app files ensures:

  • Same code in all environments
  • Tested version deployed
  • No configuration drift

Troubleshooting Installation

Installation Fails

Error Solution
Dependency missing Install required dependencies
Version conflict Check existing version
Schema sync error Use Force Sync if appropriate
Permission denied Check installation permissions

Extension Not Working

After installation:

  1. Verify installation completed
  2. Check deployment status
  3. Refresh browser/client
  4. Review extension properties

Best Practices

Version Management

  • Track which version in which environment
  • Keep copies of .app files
  • Document version contents

Testing Before Production

Always:

  1. Test in non-production first
  2. Verify functionality
  3. Check for regressions
  4. Then deploy to production

Rollback Planning

Have a plan for issues:

  • Keep previous version .app
  • Know how to uninstall
  • Test rollback procedure