Symbols Setup

Before You Begin

Before you can use IntelliSense, object browsing, or any other symbol-dependent feature, you must configure the toolbox to connect to your Business Central environment and download symbol data. This chapter walks you through the setup process for both SaaS and on-premises deployments.

If you are not familiar with what symbols are or why they are needed, review the Symbols Overview first.

The Symbols Setup Page

All symbol configuration is managed from the Symbols Setup table and its associated setup page. To open the setup page, use the search bar in Business Central and search for "Symbols Setup" or navigate to it from the Erik's ToolBox administration area.

The setup page contains the following sections:

General. The environment type (SaaS or On-Premises) and the active configuration profile.
Connection. Server URL, authentication method, and credentials or certificate references.
Extensions. Controls for selecting which installed extensions should have their symbols downloaded.
Processing. Options that govern how downloaded symbol files are parsed and stored.

You must complete the Connection section before you can download any symbols. The Extensions and Processing sections have sensible defaults that work for most environments.

SaaS Configuration

If you are running Business Central as a SaaS (online) deployment hosted by Microsoft, the symbol download process connects to the Business Central API using Azure AD (Entra ID) authentication via OAuth2.

Authentication

SaaS environments use OAuth2 for authentication. The toolbox handles the OAuth2 flow, but you must ensure the following prerequisites are met:

Azure AD App Registration. An app registration must exist in your Azure AD tenant with the appropriate Business Central API permissions. If your organization already has an app registration for Business Central integrations, you can reuse it.
API Permissions. The app registration must have delegated or application permissions to read extension and symbol data from the Business Central API.
Client ID and Secret (or Certificate). You need the client ID from the app registration. Depending on your authentication flow, you also need either a client secret or a certificate thumbprint.
Tenant ID. Your Azure AD tenant ID, which identifies your organization.

Enter these values on the Symbols Setup page in the Connection section. The toolbox stores credentials securely using the Business Central isolated storage mechanism.

Environment Selection

For SaaS deployments, you must specify which Business Central environment to connect to (for example, "Production" or "Sandbox"). The environment name is used to construct the API endpoint URL. If you are unsure of your environment name, you can find it in the Business Central Admin Center.

Network Requirements

The toolbox connects to the Business Central API over HTTPS. No additional server-side configuration is needed on the Business Central side. Your network must allow outbound HTTPS traffic to the api.businesscentral.dynamics.com endpoint (or your region-specific equivalent).

On-Premises Configuration

If you are running Business Central on-premises, the symbol download process connects directly to your Business Central server instance.

Server URL

Enter the base URL of your Business Central server in the Connection section of the Symbols Setup page. This is typically in the format:

https://your-server:port/bc-instance

Replace your-server, port, and bc-instance with your actual server hostname, the OData or API port, and the server instance name.

Authentication Method

On-premises deployments support the following authentication methods:

Windows Authentication. Uses the current Windows user credentials. No additional credential configuration is required, but the user must have appropriate permissions on the Business Central server.
NavUserPassword. Uses a Business Central username and password. Enter the credentials in the Connection section of the setup page.
Certificate-Based Authentication. Uses a client certificate for authentication. You must specify the certificate thumbprint and ensure the certificate is installed in the appropriate certificate store on the machine running Business Central.

Select the method that matches your server instance configuration. If you are unsure which method your server uses, check the Business Central Server Administration tool or consult your system administrator.

Certificate Setup

If you are using certificate-based authentication, follow these steps:

Obtain a client certificate issued by a certificate authority trusted by your Business Central server.
Install the certificate in the Local Machine or Current User certificate store.
Note the certificate thumbprint.
Enter the thumbprint in the Certificate Thumbprint field on the Symbols Setup page.
Ensure the Business Central service account has read access to the certificate private key.

Firewall and Network Considerations

For on-premises deployments, ensure the following:

The machine running the toolbox can reach the Business Central server on the configured port.
If a firewall is in place, the appropriate port is open for API or OData traffic.
If you are using HTTPS (recommended), a valid SSL certificate is installed on the Business Central server.

Selecting Extensions for Symbol Download

After configuring the connection, you can choose which installed extensions should have their symbols downloaded. By default, the toolbox downloads symbols for all installed extensions. However, you may want to limit this in large environments to reduce download time and storage.

The Installed Extension Table

The Installed Extension table stores a cached list of all extensions installed in the target environment. The toolbox populates this table automatically when you initiate a symbol download or when you explicitly refresh the extension list.

Each record includes:

App ID. The unique identifier of the extension.
Name. The display name of the extension.
Publisher. The extension publisher.
Version. The installed version number.
Scope. Whether the extension is global or per-tenant.

You can review and filter this list to decide which extensions you need symbols for. For most development scenarios, downloading symbols for the base application, system application, and any extensions you directly depend on is sufficient.

Excluding Extensions

If you want to exclude certain extensions from the symbol download, you can mark them as excluded on the Installed Extension page. Excluded extensions are skipped during the download process. This is useful if you have many extensions installed but only work with a subset of them.

Refresh Frequency Recommendations

How often you should refresh symbols depends on how frequently your environment changes:

Scenario	Recommended Frequency
Active development with frequent extension updates	After each deployment
Stable production environment	Weekly or after any extension update
Initial setup or migration	Once, then as needed
After installing a new extension	Immediately

There is no automatic refresh schedule built into the toolbox. You trigger refreshes manually or incorporate them into your deployment workflow. See Symbols Usage for instructions on triggering a refresh.

Troubleshooting Symbol Setup

If you encounter issues during setup or your first symbol download, check the following common causes.

Authentication Failures

SaaS. Verify your client ID, client secret or certificate, and tenant ID. Ensure the app registration has the correct API permissions and that admin consent has been granted if required.
On-Premises. Verify the username and password, or certificate thumbprint. Ensure the user has the necessary permissions in Business Central.

Connection Errors

SaaS. Confirm that your network allows outbound HTTPS traffic to the Business Central API endpoint. Check for proxy or firewall rules that may block the connection.
On-Premises. Verify the server URL, port, and instance name. Ensure the server is running and the API or OData endpoint is enabled.

Empty Extension List

If the Installed Extension table is empty after attempting a download:

Verify that the connection is configured correctly and that a test connection succeeds.
Ensure the authenticated user has permission to read installed extension information.
On-premises: confirm that the API endpoint for extension management is enabled on the server instance.

Partial Symbol Data

If some extensions download successfully but others fail:

Check whether the failing extensions are published with symbols included. Some extensions may not include symbol data in their published packages.
Verify that you have read permissions for all extensions, not just a subset.
Review the error log for specific error messages related to individual extension downloads.

Performance During Setup

The initial symbol download can take several minutes in environments with many extensions. This is expected behavior. Subsequent downloads are typically faster because the toolbox can detect which extensions have changed and skip unchanged ones.

If the download is unacceptably slow:

Consider excluding extensions you do not need.
Ensure your network connection to the Business Central environment is stable and has adequate bandwidth.
For on-premises deployments, check server resource utilization during the download.

Verifying Your Setup

After completing the setup, you can verify that everything is working by performing a test symbol download:

Open the Symbols Setup page and review your configuration.
Navigate to the symbol download action (see Symbols Usage).
Initiate a download for a single, small extension to confirm connectivity.
After the download completes, check the Table Metadata, Page Metadata, and other symbol tables to confirm that data has been populated.

If the test download succeeds and you can see metadata records, your setup is complete. You can proceed to download symbols for all desired extensions.