Simple Object Designer Documentation
Index

First Run

When you open Simple Object Designer for the first time, you need to complete the initial setup before creating customizations. This page walks you through the setup wizard and symbol download process.

Opening the Setup Wizard

When you first open SOD, you may be prompted to run the setup wizard. If not:

  1. Open Simple Object Designer from the search menu
  2. Click Setup in the action bar
  3. Click Setup Wizard if available, or configure settings manually

Setup Wizard Steps

The setup wizard guides you through three steps: an intro screen, a basic-configuration screen, and a symbol-download screen.

Step 1: Introduction

The first screen welcomes you to Simple Object Designer and explains what the wizard will configure. Click Next to continue.

Step 2: Basic Configuration

In this step, you configure the identity of the extension that SOD will generate:

  1. Click the link to open the Simple Field Setup page
  2. Configure the following essential settings:
Setting Description Recommendation
Extension Name The name of your customization extension Use your company name + "Customizations"
Publisher Your company or organization name Match your AppSource publisher if applicable
Start Object Number The starting ID for generated objects Use 50000 or higher for custom objects
  1. Click Close to return to the wizard
  2. Click Next to continue

Step 3: Download Symbols

Symbols contain metadata about all tables, pages, reports, and other objects in your Business Central environment. SOD needs this information to:

  • Show you which tables exist and what fields they contain
  • Show you which pages exist and where you can place fields
  • Show you which reports exist and their data items
  • Validate your customizations against the actual system structure

If SOD prompts you to download symbols, it is safe to click Yes. The download only reads information about what already exists in the system. It does not change, break or alter any existing customization or third-party extension.

To download symbols:

  1. Click the Refresh Symbols action
  2. SOD displays an OAuth2 device code and the verification URL (https://microsoft.com/devicelogin)
  3. Open that URL in a browser, paste the device code, and sign in
  4. Grant the requested permissions
  5. Wait for the download to complete (this may take several minutes)

The progress indicator shows the download status. Once complete the wizard closes automatically — there is no separate "Completion" screen.

Manual Setup (Without Wizard)

If you prefer to configure settings manually:

Configure Basic Settings

  1. Open SOD main menu
  2. Click Setup
  3. Fill in the required fields:
    • Extension Name
    • Publisher
    • Start Object Number
  4. Close the setup page

Download Symbols Manually

  1. Open SOD main menu
  2. Click Setup
  3. Click Refresh Symbols in the action bar
  4. Complete the OAuth2 device-code authentication (open https://microsoft.com/devicelogin, paste the code, sign in)
  5. Wait for the download to complete

Understanding the Download Process

When you click Refresh Symbols, SOD:

  1. Starts an OAuth2 device-code authorization (you complete the sign-in in a browser of your choice)
  2. Requests permission to access the Development Endpoint API
  3. Downloads symbol packages for all installed extensions
  4. Parses the symbols to extract metadata
  5. Stores the metadata in internal cache tables

This process may take several minutes depending on:

  • The number of installed extensions
  • The size of each extension
  • Your internet connection speed

Verifying Symbol Download

To verify symbols downloaded successfully:

  1. Go to Inspect and Customize Objects > Tables
  2. You should see a list of all tables in the system
  3. If the list is empty, symbols did not download correctly

Common First-Run Issues

OAuth2 Authentication Fails

If the OAuth2 login window fails or returns an error:

  • Verify you have SUPER permissions
  • Check that your user has the necessary Azure AD permissions
  • Try clearing browser cookies and cache
  • Ensure pop-up blockers are not blocking the login window

Symbol Download Hangs

If the symbol download seems stuck:

  • The download can take 5-10 minutes for environments with many extensions
  • Check your internet connection
  • Try refreshing the page and starting again

"Missing Permissions" Error

If you see a permissions error:

  • Sandbox environments require Extension Management permissions
  • Production environments require Snapshot Debugging permission
  • Contact your administrator if you don't have sufficient permissions

Check the company scope of the permission. Moving from a working sandbox to a newly deployed production environment, symbol download can still fail with a Snapshot Debugging error after the permission set has been assigned — because the assignment line names a specific company. It must apply to all companies (a blank Company value). See Required Permissions.

"Record already exists" During the Refresh Prompt

If the symbol refresh offered when SOD opens fails with a "record already exists" error:

  1. Answer No to that prompt
  2. Open the SOD Setup page
  3. Run Refresh Symbols there
  4. Answer Yes when asked to clear the cache

The on-open refresh does not clear the cache; only the Setup page action offers that, and it is what resolves the conflict.

Symbols Not Showing Objects

If tables/pages/reports don't appear after download:

  • Verify the download completed successfully (check for success message)
  • Try downloading symbols again — from the Setup page, clearing the cache
  • Check the Extension Cache table to see what extensions were processed

Next Steps

After completing first-run setup:

  1. Explore the Main Menu to understand navigation
  2. Review the Recommended Workflow
  3. Start Creating Fields or explore Features