Download Process
This page explains how Simple Object Designer downloads symbols and what happens during the process.
Starting the Download
You can initiate symbol download from:
- Setup Wizard - During first-run setup
- Setup Page - Click the Refresh Symbols action
- Prompt - When SOD detects outdated symbols
Is it safe to download symbols?
Yes. Downloading or refreshing symbols is a read-only operation, and answering Yes to the prompt cannot break anything in your environment.
Symbol download only reads information about what already exists — tables, pages, reports and other object metadata. It does not modify, alter or damage any extension or customization, including apps built by third-party developers.
Refresh Symbols and the cache-clearing prompt
When you run Refresh Symbols from the Setup page, SOD asks whether to clear the cache first:
- Yes — the existing symbol cache is discarded and everything is downloaded fresh. This is the answer that fixes problems.
- No — the existing cache is reused and updated incrementally, which will not resolve missing-object or stale-metadata issues.
The refresh that runs automatically when SOD opens does not offer this prompt. To get the clear-cache option, decline the on-open prompt and run Refresh Symbols from the Setup page instead.
Clearing the cache this way is the standard remedy for:
- "The record in table Field MetaData Hgd already exists" errors during refresh
- "Field MetaData Hgd does not exist" errors during publishing
- Fields or objects that are missing from SOD's lists
- Stale references to fields an extension update removed or renamed
- Recovering when the generated extension disappeared after a BC update took a dependency app with it
Step-by-Step Process
Step 1: OAuth2 Device-Code Authentication
When you click Refresh Symbols, SOD uses the OAuth2 device-code flow:
- SOD displays a short device code and the verification URL (
https://microsoft.com/devicelogin) - Open that URL in any browser
- Type or paste the device code shown by SOD
- Sign in with your Business Central / Microsoft 365 credentials
- Grant permission to access the development API
- SOD polls in the background and continues automatically once authorization completes
There is no automatic browser launch — copy the code into a browser of your choice. The authorization is reused while the access token is valid.
What you're authorizing:
- Read access to extension symbol packages
- Access to the development endpoint API
Conditional Access can block this flow. Because SOD uses the OAuth2 device-code flow, a Microsoft Entra Conditional Access policy that blocks device-code sign-in causes authentication to fail with a "You don't have access to this" screen even after valid credentials are entered. Device Code login must be allowed for the Simple Object Designer application in Azure Portal > Enterprise Applications. See Symbol Troubleshooting.
Step 2: Extension Discovery
After authentication, SOD:
- Connects to the Business Central development endpoint
- Queries for all installed extensions
- Retrieves extension identities (name, publisher, version)
- Compares against the existing cache
What's discovered:
- System and base applications
- Microsoft first-party apps
- AppSource extensions
- Per-tenant extensions (PTEs)
Step 3: Symbol Package Download
For each extension, SOD:
- Requests the symbol package from BC
- Downloads the package content
- Stores it temporarily for processing
Download size:
- Varies based on extension size
- Large environments may download 50-100+ packages
- Total download can be several megabytes
Step 4: Symbol Parsing
SOD parses each package to extract:
| Data Type | Information Extracted |
|---|---|
| Tables | ID, name, fields, keys, properties |
| Pages | ID, name, source table, page type, controls |
| Reports | ID, name, data items, columns |
| Codeunits | ID, name, methods, parameters |
| Enums | ID, name, values |
| Queries | ID, name, elements |
Step 5: Cache Update
Parsed data is stored in SOD's cache tables:
- Old cache entries are updated or removed
- New entries are added
- Extension versions are tracked
- Timestamps are updated
Progress Indication
During download, SOD shows:
- Current operation (authenticating, downloading, parsing)
- Progress percentage or extension being processed
- Any errors encountered
Download Duration
Typical download times:
| Environment Size | Approximate Time |
|---|---|
| Minimal (few extensions) | 1-2 minutes |
| Standard (10-20 extensions) | 3-5 minutes |
| Large (30+ extensions) | 5-10 minutes |
Factors affecting duration:
- Number of installed extensions
- Size of each extension
- Internet connection speed
- Business Central API responsiveness
What Gets Cached
After download, SOD has cached:
Extension Information
- Extension name, publisher, version
- Download timestamp
- Dependency relationships
Table Metadata
- All table IDs and names
- Field definitions (ID, name, type, length)
- Key definitions
- Table relations
Page Metadata
- All page IDs and names
- Page types (Card, List, etc.)
- Source tables
- Controls (fields, groups, parts)
- Action groups and actions
Report Metadata
- All report IDs and names
- Data items and their tables
- Columns and their fields
- Report properties
Codeunit Metadata
- All codeunit IDs and names
- Public methods
- Method parameters and return types
Incremental vs Full Download
Full Download
Occurs when:
- First-time setup
- Explicit "Refresh Symbols" action
- After clearing the cache
Downloads all symbols from all extensions.
To force a genuinely complete re-download — which is what you need when specific objects or fields are missing — answer Yes to the cache-clearing prompt. Answering No reuses the existing cache and typically leaves the problem in place.
Cache Validation
SOD can detect when symbols may be outdated by:
- Comparing cached extension versions to installed versions
- Checking for new or removed extensions
- Monitoring Business Central version changes
After Download Completes
Once download finishes:
- Verify by checking Tables list (Inspect > Tables)
- You should see all system and custom tables
- SOD is ready for customization work
Download Errors
Common download issues:
| Error | Cause | Solution |
|---|---|---|
| Authentication failed | Invalid credentials | Re-authenticate with correct account |
| "You don't have access to this" (53003) | Conditional Access blocks device code | Allow the SOD app in Enterprise Applications |
| Permission denied | Missing permissions | See Required Permissions |
| Connection timeout | Network issues, or a Microsoft outage | Check internet and retry; see below |
| "Could not contact dynamics.com (Request timed out.)" | Often a Microsoft development-endpoint outage | Retry; use a sandbox meanwhile |
| "No published package matches the provided arguments" | Microsoft backend bug | Update SOD to 12.0.0.555 or later |
| Partial download | Interrupted | Retry the download — it resumes where it left off |
.alpackages directory could not be found (source download) |
Server-side compiler path issue | Contact Hougaard support |
Timeouts are not always local. Could not contact dynamics.com, error (Request timed out.) can indicate a Microsoft development-endpoint service outage — a GatewayTimeout from the snapshotdebugger endpoint — rather than a problem with your network. Retry first; if it persists, see Symbol Troubleshooting. The workaround during an outage is to work in a sandbox environment, which downloads symbols from a different source.
Source download failures. If downloading source code fails with a message that a temporary directory ending in &#.;alpackages could not be found, that is a server-side compilation path issue — the Microsoft compiler could not set up its working directory. This cannot be fixed from your side; contact Hougaard support.
See Symbol Troubleshooting for detailed error resolution.
Manual Cache Management
Clear Cache
Clearing the cache is a normal, self-service operation — not an advanced support-guided one. Run Refresh Symbols from the Setup page and answer Yes when asked whether to clear the cache. That performs a full clear and re-download.
Use it whenever symbols look corrupted, incomplete, or out of date, and as a first response to publish errors that mention missing metadata.
Verify Cache
To check cache status:
- Go to Inspect > Tables
- Verify expected tables appear
- Check a few table field lists