Simple Object Designer Documentation
Index

Setup Page

The Setup page is the central location for configuring Simple Object Designer. This page explains each setting and how it affects your customization extension.

Accessing the Setup Page

  1. Open Simple Object Designer
  2. Click Setup in the action bar
  3. The Simple Field Setup page opens

General Configuration Group

App Mode

Controls whether SOD generates one or two extension apps.

Value Description
Single Generates one extension containing all customizations (default)
Dual Generates two extensions to avoid circular dependencies

Use Single mode for most scenarios. Switch to Dual only if you encounter circular dependency errors during publishing. See Dual-App Overview for details.

Extension Name

The name of your customization extension as it appears in Extension Management. Maximum 30 characters.

Recommendations:

  • Use a descriptive name like "Contoso Customizations"
  • Include your company name for identification

This name appears in:

  • Extension Management
  • About This Extension
  • App file name

Extension Name 2

Only visible when App Mode is set to Dual. This is the name for the second extension.

Recommendations:

  • Use a name like "Contoso Customizations - Part 2"
  • Make it clear it's related to the first extension

Publisher

Your company or organization name as the extension publisher.

Recommendations:

  • Use your official company name
  • Match your AppSource publisher name if applicable
  • Keep it consistent across all your extensions

Version

The version number of your extension in four-part format: Major.Minor.Build.Revision

SOD automatically increments the Revision number each time you publish. You can manually change the Major, Minor, or Build numbers when appropriate.

Version example: 1.0.0.1

Start Object Number

The starting ID number for objects created by SOD. All tables, pages, fields, and other objects receive IDs starting from this number.

Requirements:

  • Must be 50,000 or higher (Microsoft reserves lower numbers)
  • Must not overlap with other extensions in your environment
  • SOD scans for a 1000-ID-wide free block and assigns IDs sequentially from there as you create new objects

Recommendations:

  • Use a unique range for each SOD installation
  • Document your object ID allocations to avoid conflicts

Object Prefix

A prefix added to all object names created by SOD. This helps identify SOD-generated objects.

Example: If prefix is "CONT" and you create a field named "Discount Percent", the internal name becomes "CONT Discount Percent".

Recommendations:

  • Maximum 3 characters (field length limit)
  • Use your company abbreviation
  • The suffix "Hgd" is always added for AppSource compliance

Advanced Settings

Last Table No. / Last Page No.

These hidden fields track the last used object numbers. SOD uses them to assign IDs to new objects sequentially.

You generally don't need to modify these unless recovering from issues.

Alternative API URL

Use this if your Business Central environment uses a non-standard API host.

When to use:

  • Connecting to national cloud instances
  • Custom hosting scenarios
  • When standard API URLs don't work

Important: This field expects only the host name (no scheme, no path). The validator rejects any value containing :, /, or http://.

  • ✅ test.bc.dynamics.com
  • ❌ https://api.businesscentral.dynamics.com/v2.0/...

Leave blank for standard Business Central cloud environments.

Only Allow API Creation

When enabled, SOD restricts functionality to API creation only. Other features like field creation and page customization are hidden.

Use cases:

  • Organizations that only need API exposure
  • Environments with strict change control
  • Scenarios where full SOD functionality is not appropriate

Publish Update Mode

Controls how Business Central handles schema changes during publishing.

Value Description
Add app to manifest Registers the app without schema sync
Synchronize Standard mode, preserves data (default)
Force Sync Allows destructive schema changes

Important: Force Sync can result in data loss. Use it only when:

  • Removing fields that contain data
  • Making changes that require table recreation
  • You have backed up your data

Always use Synchronize for normal operations.

GitHub Integration Mode

Enables pushing generated AL source code to a GitHub repository.

Value Description
None No GitHub integration (default)
Source Repository/AL-Go! Push generated AL source to GitHub on publish (supports plain source repos and AL-Go for GitHub)

When enabled, additional GitHub configuration fields appear. See GitHub Configuration for setup details.

Include Symbols in Source Code

When enabled, SOD includes symbol references in the generated AL source code. This creates more complete source files that can be compiled independently.

When to enable:

  • Using GitHub integration
  • Planning to continue development in VS Code
  • Need standalone compilable source

Setup Actions

The Setup page includes several actions in the action bar:

Refresh Symbols

Initiates the symbol download process. Opens OAuth2 device-code authentication and downloads metadata for all installed extensions.

It prompts you to clear the cache — answer Yes. Clearing the cache performs a full clear and re-download rather than an incremental update, and it is the fix for most symbol-related problems: missing fields in selection lists, "record already exists" errors, "Field MetaData … does not exist" at publish time, and stale references to fields an extension update removed.

Run it from here, not from the on-open prompt. Opening SOD may offer to refresh symbols; that automatic refresh does not clear the cache. Decline it and use this action instead when you are troubleshooting.

About the refresh on opening SOD: it can take a considerable amount of time — 20 minutes is not unusual on a large environment. It only happens during development; it does not occur when the app runs in a live environment. Answering No simply skips it, and you can answer Yes later if something turns out to be missing.

Init new App

Resets SOD configuration for creating a new, separate customization extension. Use when you want to start fresh without affecting existing customizations.

Export first. After Init new App, the features, fields, tables and other customizations from the previous configuration are no longer visible or manageable in SOD, because SOD now points at a new, separate configuration.

The published extension keeps working. The already-published tables, fields and features continue to function normally in Business Central as an ordinary extension. What you lose is the ability to modify them through SOD — not the extension itself.

Safe workflow:

  1. Export App to save the current configuration to a file
  2. If you use GitHub integration, push the current state first
  3. Init new App and work on the new one
  4. To manage the original features again later, Import App with that file — or with the previously published .app, since SOD embeds the source definition inside the .app when publishing

Export App

Exports your SOD configuration to a file — a .json file — for backup or transfer to another environment.

Export and retain your SOD source. Keeping the exported .json, and the published .app files, is what makes your work recoverable if the original author leaves, an environment is rebuilt, or a sandbox is refreshed from production. Without one of those files, SOD data cannot be recovered.

Note that Export App and Import App require a licensed environment. If they are greyed out, the environment is not licensed.

Import App

Restores a SOD configuration. It accepts two kinds of input:

  1. A file previously created with Export App (.json)
  2. An .app file previously published from SOD

Use Export App and Import App together to preserve your creations before reinstalling SOD in a new or replacement environment, so you continue where you left off instead of starting over. See Environments, Companies and Backup.

Download Source

Downloads a ZIP archive containing the generated AL source code. Useful when you want to inspect or graduate the source to a normal AL development workflow.

It is also the artifact support asks for when diagnosing publish and package validation failures — email the ZIP to support@hougaard.com, renamed to .txt if mail filtering blocks it.

Enable Include Symbols in Source Code when you also need to verify which symbol packages were downloaded: the resulting .alpackages folder can be inspected to confirm the base application package is present.

Choosing the compiler

SOD can compile with either the Legacy compiler or the Microsoft compiler, and the choice is made in a compiler selection field on this Setup page. The two produce different errors, so confirm which one is active before reporting a compilation problem.

  • Switching to the Legacy Compiler is a standard troubleshooting step when publishing fails with "Unexpected Compiler Output" on the Microsoft compiler.
  • Reports can only be compiled by the Microsoft compiler — this is why report generation from Document and Data Table features is not yet available.
  • If no compiler selection is visible in your SOD settings, the Legacy compiler is in use.

Alternative API Dependencies

This field is hidden by default — surface it with personalization. It is used to work around a Microsoft symbol-resolution bug that produces "A package with publisher 'Microsoft', name 'Application' … could not be found". See Publishing Failures.

The Setup Wizard is not an action on this page — it launches automatically the first time you open the SOD main menu without a saved setup.

Saving Changes

Changes to the Setup page are saved automatically as you modify each field. There is no explicit Save button required.