Symbols Usage

Introduction

Once you have configured your symbol source (see Symbols Setup), you are ready to download, browse, and manage symbol data. This chapter covers the day-to-day operations you will perform with symbols in Erik's ToolBox.

If you are unfamiliar with what symbols are and what data they contain, start with the Symbols Overview.

Triggering a Symbol Download

To download symbols, open the Symbols Setup page and invoke the download action. The toolbox calls the DownloadSymbols() function on the Symbol Management codeunit, which connects to your Business Central environment and retrieves symbol packages for each configured extension.

You can also trigger a download from several other places in the toolbox where symbol data is referenced, such as the code editor toolbar or the Object Inspector. Any of these entry points ultimately calls the same underlying DownloadSymbols() function.

Full Download vs. Selective Download

By default, the download processes all extensions that are not marked as excluded in the Installed Extension table. If you only need to refresh symbols for a specific extension, you can select that extension in the Installed Extension list and use the per-extension download action.

A selective download is faster and useful when you know that only one or two extensions have changed since your last refresh.

The Download Process

When you initiate a symbol download, the toolbox follows a multi-step process. Understanding these steps can help you diagnose issues and set expectations for timing.

Step 1: Reading Installed Extensions

The system queries the Business Central environment to retrieve the current list of installed extensions. This list is stored in the Installed Extension table. If an extension has been added or removed since the last download, the cached list is updated accordingly.

Step 2: Downloading Symbol Files

For each extension in the list (excluding any you have marked as excluded), the toolbox downloads the symbol package file. This is the .app file that contains the compiled metadata for the extension. The download is performed over the API connection you configured during setup.

The symbol files are downloaded sequentially. For environments with many extensions, this step can take several minutes. The toolbox provides a progress indicator so you can monitor how many extensions have been processed.

Step 3: Processing Symbol Files

After each symbol file is downloaded, the ProcessSymbols() function parses it and extracts the metadata into the local symbol tables. This step calls several specialized extraction functions:

ExtractFromFields() reads table definitions and populates the Table Metadata and Field Metadata tables with table IDs, names, field IDs, field names, data types, and field lengths.
ExtractFromPageControls() reads page definitions and populates the Page Metadata and Page Control Metadata tables with page IDs, names, page types, source tables, and control definitions.
ExtractFromPageActions() reads page action definitions and populates the Page Action Metadata table with action types, names, and targets.
ExtractFromDataItems() reads report definitions and populates the Report Metadata and Report DataItem tables with report IDs, names, data item source tables, and data item relationships.

Method signatures for codeunits and other objects are extracted and stored in the Object Method Metadata table during the same processing pass.

Step 4: Storing Metadata

All extracted metadata is committed to the local symbol tables. Existing records for the same extension are replaced with the newly extracted data, ensuring that you always have an up-to-date snapshot of each extension's objects.

Monitoring Download Progress

During a symbol download, the toolbox displays a progress dialog that shows:

The total number of extensions to process.
The current extension being downloaded or processed.
The number of extensions completed so far.

If an error occurs during the download of a specific extension, the toolbox logs the error and continues with the remaining extensions. After the process completes, you can review the log to identify any extensions that failed and take corrective action.

Viewing Downloaded Symbols

After symbols have been downloaded and processed, you can browse the extracted metadata through several interfaces.

Table Metadata and Fields

Open the Table Metadata page to see a list of all table objects across your downloaded extensions. From here, you can drill down into any table to view its fields in the Field Metadata table. Each field record shows the field ID, name, data type (such as Code, Text, Integer, Decimal, Boolean, Option, Enum, and so on), and maximum length where applicable.

This view is useful when you need to reference a field name or verify a data type without switching to the AL source code.

Page Metadata, Controls, and Actions

Open the Page Metadata page to browse all downloaded page objects. Each page record shows the page ID, name, page type, and source table. You can drill down to view the page's controls in the Page Control Metadata table and its actions in the Page Action Metadata table.

Page controls show the control type and which table field they are bound to, if any. Page actions show the action type and run-object target, making it easy to trace navigation flows.

Report Metadata and Data Items

Open the Report Metadata page to see report objects. Drill down into a report to view its data items in the Report DataItem table. Data items show the source table for each data item and the indentation level, which represents the parent-child relationships between data items.

Codeunit and Method Signatures

Open the Object Method Metadata page to browse methods exposed by codeunits, tables, pages, and other objects. Each record shows the method name, the object it belongs to, parameter definitions, and the return type. This is particularly helpful when you need to call a method from another extension and want to verify the expected parameters.

Clearing Symbols for a Specific Extension

If you no longer need symbol data for a particular extension, or if you want to force a clean re-download, you can clear the symbols for that extension. Select the extension in the Installed Extension list and invoke the clear action. This calls the ClearSymbolsFor() function on the Symbol Management codeunit, which removes all metadata records associated with that extension from the local symbol tables.

Clearing symbols does not affect the extension itself or any other extensions. It only removes the locally cached metadata. You can re-download the symbols at any time.

Using Symbols in the Code Editor

The primary consumer of symbol data is the interactive code editor built into Erik's ToolBox. When you write AL code in the editor, the toolbox queries the local symbol tables to provide IntelliSense suggestions.

IntelliSense Triggers

IntelliSense activates in the following contexts:

Table and field references. When you type a table name or field reference in a record variable declaration, a SetRange, SetFilter, Get, or similar call, the editor suggests matching table and field names from the symbol data.
Page and report references. When you reference a page or report in a Page.Run, Report.Run, or similar call, the editor suggests matching page and report names.
Method calls. When you call a method on a codeunit or other object variable, the editor suggests available methods and shows parameter hints based on the symbol data.
Enum and option values. When you assign a value to an enum or option field, the editor suggests the valid values defined in the symbol data.

IntelliSense works across all downloaded extensions. If you reference a table from the base application and a field added by a third-party extension, both will appear in the suggestions as long as symbols for both extensions have been downloaded.

For more details on the code editor, see Interactive Code Editor.

Symbol Data in Object Inspector

The Object Inspector feature in Erik's ToolBox also uses symbol data to provide detailed information about Business Central objects. When you inspect an object, the Object Inspector pulls metadata from the symbol tables to show you the object's structure, fields, controls, actions, and methods without needing to open the source code.

This is especially useful for inspecting objects from extensions where you do not have access to the source code. The symbol data gives you a complete structural view of the object.

For more details, see Object Inspector Overview.

Performance Considerations

Download Time

The time required for a full symbol download depends on several factors:

Number of extensions. More extensions means more symbol packages to download and process.
Extension size. Large extensions with many tables, pages, and reports take longer to process than small ones.
Network speed. For SaaS deployments, download speed is influenced by your internet connection. For on-premises, it depends on your internal network.
Server load. If the Business Central server is under heavy load, API responses may be slower.

For a typical environment with 20 to 50 extensions, a full download usually completes within a few minutes. Environments with hundreds of extensions may take longer.

Storage

Symbol metadata is stored in standard Business Central tables. The storage footprint is modest for most environments. A full symbol set for the base application, system application, and a handful of extensions typically occupies a few megabytes of database space.

Runtime Impact

Querying symbol tables during code editing is fast because the data is stored locally in indexed Business Central tables. You should not notice any perceptible delay when IntelliSense suggestions appear.

The download process itself does consume server and network resources. It is best to run full downloads during off-peak hours in production environments.

Best Practices

Follow these guidelines to get the most out of the symbol system:

Refresh after every deployment. Whenever you install, update, or remove an extension, refresh symbols to keep IntelliSense accurate. Stale symbols can lead to missing or incorrect suggestions.
Clear unused extension data. If you have downloaded symbols for extensions you no longer work with, clear them to reduce clutter in the symbol tables and keep browsing views focused on relevant objects.
Use selective downloads when possible. If only one extension has changed, download symbols for just that extension rather than running a full download. This saves time and reduces server load.
Verify after major updates. After a Business Central major version update (for example, upgrading from version 23 to version 24), perform a full symbol refresh. Major updates can change object definitions, add new objects, and deprecate existing ones.
Review the extension list periodically. Check the Installed Extension table from time to time to ensure it reflects the current state of your environment. Remove or exclude extensions that are no longer relevant to your work.
Coordinate with your team. In multi-developer environments, establish a convention for when and how symbols are refreshed. This avoids situations where one developer has stale data while another has current data.

Troubleshooting

IntelliSense Not Showing Expected Objects

If the code editor is not suggesting objects you expect to find:

Verify that symbols have been downloaded for the extension that publishes the object. Check the Installed Extension table.
Confirm that the download completed successfully without errors for that extension.
Open the relevant metadata table (for example, Table Metadata for tables) and search for the object by name.
If the object is missing from the metadata table, re-download symbols for that extension.

Stale or Outdated Suggestions

If IntelliSense suggests objects or fields that no longer exist:

The symbol data is likely outdated. Refresh symbols for the affected extension.
If refreshing does not resolve the issue, clear symbols for the extension and re-download them.

Download Errors

If the download process reports errors:

Check your connection configuration on the Symbols Setup page.
Verify that the Business Central environment is accessible and that the API endpoints are responding.
Review the error log for specific error messages and address them according to the Symbols Setup troubleshooting section.