Simple Object Designer Documentation
Index

Recommended Workflow

This page outlines best practices for using Simple Object Designer effectively, from initial setup through production deployment.

The Sandbox-First Approach

Always develop and test customizations in a sandbox environment before deploying to production. This approach:

  • Protects production data from experimental changes
  • Allows you to test without affecting users
  • Provides a safe space to learn SOD features
  • Enables validation before going live

1. Set Up in Sandbox

  1. Install SOD in a sandbox environment first
  2. Complete the setup wizard
  3. Download symbols
  4. Configure extension identity settings

2. Design Your Customizations

Before creating anything in SOD, plan your customizations:

  • Identify which tables need new fields
  • Determine where fields should appear on pages
  • Plan any mandatory field rules
  • Consider whether you need new feature tables

3. Create in Small Batches

Instead of creating all customizations at once:

  1. Create a few related fields
  2. Place them on relevant pages
  3. Publish and test
  4. Repeat with the next batch

This incremental approach helps you:

  • Identify issues early
  • Understand how changes affect the system
  • Recover more easily from mistakes

4. Test Thoroughly

After each publish:

  1. Open the affected pages
  2. Verify fields appear in the correct positions
  3. Test field behavior (editing, validation)
  4. Check that existing functionality still works
  5. Test any mandatory field rules
  6. Verify report changes in report layouts

5. Document Your Changes

Keep track of what you've customized:

  • Which fields you added and why
  • Which pages show your custom fields
  • Any mandatory rules you created
  • Any calculated field expressions

This documentation helps with:

  • Training users
  • Troubleshooting issues
  • Planning future changes
  • Handoff to developers if needed

6. Deploy to Production

When satisfied with testing:

Option B is the recommended path. Keep SOD in one place and move a compiled app outward.

Option A: Direct Publish

  1. Install SOD in production
  2. Import your configuration (if available)
  3. Re-download symbols for production
  4. Verify customizations
  5. Publish

Note that direct publishing in production requires the Snapshot Debugging permission for symbol download, on top of everything else.

Option B: App File Install (recommended)

  1. Download the .app file from the sandbox — with a registered SOD, publishing downloads it automatically (you may need to click Keep)
  2. Go to Extension Management in production
  3. Manage > Upload Extension, select the file and deploy
  4. No need for SOD in production with this method

Option B avoids the production permission problem entirely. Symbol download works in a sandbox with SUPER or D365 EXTENSION MGT; uploading a finished .app needs no Snapshot Debugging permission in production at all. It also separates development from production cleanly.

If SOD was installed in production only to enable publishing, it can be uninstalled and the downloaded .app installed instead. After the install, your custom fields, tables and API-exposed data are all available in production — API URLs are derived by swapping the environment segment, see Consuming APIs.

Working with Multiple Environments

If you have multiple environments (dev, test, production):

Keep SOD in one environment only

Do not run SOD in both sandbox and production. Designate one sandbox as the dev sandbox, do all development and testing there, and deploy elsewhere by uploading the .app to Extension Management.

The consequence, stated plainly: because production holds only the compiled .app and not SOD, your custom fields, queries and features are not visible or editable in SOD from production. Every subsequent change is made in the dev sandbox and re-deployed as an updated .app.

This is a feature, not a limitation — a single source of truth avoids the divergence that causes fields to appear in one environment and stay empty in another.

Environment-Specific Considerations

Environment Purpose SOD Usage
Development Building customizations Full SOD install, active development
Test/UAT User acceptance testing Install .app only
Production Live business operations Install .app file only (recommended)

Promoting Changes Between Environments

  1. Build in development with full SOD access
  2. Download the .app file when ready
  3. Install the .app in test environment
  4. Test with business users
  5. Install the same .app in production

This ensures production gets exactly what was tested.

Changes always originate in the dev environment. An environment where the customization exists only as an installed .app cannot be used to modify it — the schema cannot be amended and fields cannot be added there. To change something after testing: go back to the dev sandbox, make the change, publish a new version, and re-deploy the updated .app. You never need to recreate the table as a new project in the target environment.

To deploy a subsequent version, simply upload the newer .app — the version auto-increments on publish, and Business Central recognizes the higher version with the same extension ID as an update. There is no need to uninstall the previous version first.

Moving work from a demo (unlicensed) tenant to a licensed one

Import App / Export App are disabled in demo mode, so the usual transfer route is unavailable from an unlicensed trial.

  • Use GitHub integration: push the generated source from the trial, then pull it into the licensed tenant, or install the resulting .app in production.
  • Or license first: once a license is purchased and applied to the sandbox, Import/Export become available and can be used normally.

Remember that the generated extension is a standard Business Central extension, independent of the SOD license — anything already published keeps running regardless of SOD's licence state.

Version Management

Track Your Versions

SOD automatically increments the version number when you publish. Keep track of:

  • What version is in each environment
  • What changes each version contains
  • When each version was deployed

Coordinating Updates

When making updates to an existing customization:

  1. Make changes in sandbox
  2. Publish (version increments automatically)
  3. Test the new version
  4. Download the updated .app file
  5. Install in other environments

Handling Problems

When Things Go Wrong in Sandbox

If a customization causes issues in sandbox:

  1. Use SOD to remove or modify the problematic customization
  2. Publish again
  3. Test to verify the fix

When Things Go Wrong in Production

If production has issues after installing a customization:

  1. Go to Extension Management
  2. Uninstall the customization extension
  3. Business Central reverts to the previous state
  4. Fix the issue in sandbox
  5. Re-deploy the corrected version

Recovery Options

Situation Recovery Approach
Field causes page errors Remove field placement, republish
Mandatory rule too strict Modify or delete the rule, republish
Need to remove a field Change Publish Update Mode to Force, remove field, republish
Complete rollback needed Uninstall the customization extension entirely

Preserving Your Configuration

Before an environment containing SOD is replaced or rebuilt, use Export App on the Setup page to save your configuration. After installing SOD in the replacement environment, use Import App to restore it — from the exported file, or from a previously published .app.

This matters most in the common sequence where a sandbox is refreshed from a copy of production: the deployed extension survives, but the SOD design data in the sandbox does not. Keeping every published .app file gives you a restore point for each version.

If neither an exported JSON nor an .app exists, SOD data cannot be recovered. See Environments, Companies and Backup.

Performance Considerations

Keep Symbol Data Current

Re-download symbols when:

  • Business Central is updated to a new version
  • New extensions are installed
  • Symbols appear outdated or incomplete

Always answer Yes to the cache-clearing prompt when troubleshooting, and run the refresh from the Setup page rather than the prompt that appears when SOD opens.

Publish Efficiently

Minimize publishing overhead by:

  • Batching related changes together
  • Testing thoroughly before publishing
  • Avoiding unnecessary publishes

Collaboration Guidelines

Multiple Users with SOD

If multiple people use SOD in the same environment:

  • Coordinate changes to avoid conflicts
  • Don't work on the same tables/pages simultaneously
  • Communicate before publishing
  • Consider using separate sandbox environments for parallel work

Handing Off to Developers

If customizations grow complex enough to need developer involvement:

  1. Use GitHub integration to export source code
  2. Provide documentation of business requirements
  3. The generated AL code serves as a starting point
  4. Developers can continue development in VS Code