Initial Configuration
This page walks you through the first-time setup of Erik's ToolBox after installation. By following these steps, you will have a fully configured ToolBox environment ready for interactive coding, data management, and more.
Configuration Checklist
Complete the following steps in order to get your ToolBox environment up and running:
| Step | Task | Required | Description |
|---|---|---|---|
| 1 | Register the license | Yes (production) | Activate your license for full functionality |
| 2 | Open the ToolBox Setup page | Yes | Access the central configuration page |
| 3 | Configure general settings | Recommended | Set a nickname for your environment |
| 4 | Set up users and access levels | Yes | Define who can use the ToolBox and at what level |
| 5 | Download symbols | Recommended | Enable IntelliSense and code completion |
| 6 | Configure optional integrations | Optional | Set up the AI agents, Program Storage (Azure or GitHub), Remote ToolBox, or GitHub data |
Step 1: Register the License
If you are running in a production environment or on-premises, the first task is to register your license. In a SaaS sandbox, you can skip this step because all features are available without registration.
- Open the ToolBox Setup page by searching for "ToolBox Setup" in the search bar.
- Choose the License action in the action bar.
- On the Register ToolBox page, enter your registration key in the Registration Key field.
- Press Enter to validate the key. The system contacts the hougaard.com license server to verify your key.
- Upon success, you see the message: "Thank you for registering Erik's ToolBox, all functionality is now enabled."
For detailed information about the registration process, see Registration.
Step 2: Open the ToolBox Setup Page
The ToolBox Setup page is the central hub for all configuration. To open it:
- Search for ToolBox Setup using the search bar (Alt+Q).
- Alternatively, open the Erik's ToolBox main page and choose the Setup action from the action bar.
The first time you open the Erik's ToolBox main page, if no setup record exists, the ToolBox Setup page opens automatically as a modal dialog prompting you to complete the configuration.
You must have the SUPER permission set in Business Central to open the ToolBox Setup page. If you do not have SUPER, you will see the error: "ToolBox Setup can only be used by SUPER users."
Step 3: Configure General Settings
The General group on the ToolBox Setup page contains basic environment information and settings.
General Group Fields
| Field | Description | Editable |
|---|---|---|
| Tenant ID | Your Azure AD tenant identifier. Displayed automatically. | No (read-only) |
| Environment | The name of the current Business Central environment. Displayed automatically. | No (read-only) |
| Nickname | A friendly name you assign to this environment. Useful when you work with multiple environments. | Yes |
Setting the Nickname
The Nickname field lets you give your environment a recognizable name, such as "Production", "Testing", or "Customer ABC Sandbox". This name appears in various places throughout the ToolBox to help you quickly identify which environment you are working in.
- On the ToolBox Setup page, locate the Nickname field in the General group.
- Enter a descriptive name for this environment.
- The value is saved automatically when you leave the field.
Step 4: Set Up Users and Access Levels
After configuring general settings, you should set up ToolBox users and assign appropriate access levels.
- On the ToolBox Setup page, choose the Users action in the action bar.
- The ToolBox Users page opens. If this is the first time, you are automatically added as the first user with GodMode access.
- Choose the Add User action to add additional users.
- Select a Business Central user from the lookup and confirm.
- Set the appropriate Access Level for each user:
| Access Level | Use Case |
|---|---|
| ReadOnly | Users who should only view data and run read-only scripts |
| WriteNormalTables | Users who need to run scripts that modify standard table data |
| GodMode | Administrators who need full access, including protected tables and user management |
For detailed information about permissions, see Permissions.
Step 5: Download Symbols
Symbols provide the ToolBox with metadata about all installed extensions and their objects (tables, pages, codeunits, reports, etc.). Downloading symbols enables IntelliSense-style code completion and allows the ToolBox to validate table and field references in your scripts.
- Open the Interactive Code page from the Erik's ToolBox main menu.
- Look for the Symbols or Refresh Symbols action in the action bar.
- Choose the action to start downloading symbols from all installed extensions.
- The download process reads the symbol files from each installed extension and stores the metadata in the ToolBox symbol cache.
- Wait for the process to complete. The time required depends on the number of installed extensions.
After symbols are downloaded, you will have access to:
- Table names and field definitions for code completion.
- Page metadata including controls and actions.
- Report metadata including data items.
- Codeunit metadata including procedure signatures.
- Enum definitions and their values.
For detailed information about configuring symbol sources, see Symbols Setup.
Step 6: Configure Optional Integrations
The ToolBox Setup page includes several optional integration groups. Configure these based on your needs.
AI Agents
The AI Providers action on the ToolBox Setup page opens the provider list of the AL AI Services app. The row with the ToolBox Agent toggle on powers both the ToolBox Agent on the Interactive Code page and the SQL Agent on the SQL Workbench.
| Field | Description |
|---|---|
| Provider | One of the twelve supported providers (Azure Open AI, ChatGPT Open AI, Anthropic (Claude), LM Studio, Google Gemini, xAI Grok, Mistral, DeepSeek, Moonshot Kimi, Alibaba Qwen, Zhipu GLM, MiniMax) |
| Endpoint | The provider's chat endpoint URL |
| Access Key | The API key (masked; the drill-down opens the provider's key console) |
| Model | The model name, or blank for the ToolBox default for that provider |
| ToolBox Agent | Turn on for the row the ToolBox agents should use |
To configure the agents:
- Enable Allow HttpClient Requests for the AL AI Services extension in Extension Management.
- On the ToolBox Setup page, choose AI Providers.
- Add a row, select the Provider, and enter the Endpoint and Access Key.
- Optionally enter a Model.
- Turn on ToolBox Agent for the row.
- Reopen the Interactive Code page; the ToolBox Agent FactBox appears next to the editor.
Endpoints and per-provider notes are in AI Agents Setup.
Program Storage
The Program Storage group enables synchronization of your shared ToolBox programs to an external backend, so scripts can be shared across environments and backed up. You pick one backend — Azure Blob Storage or GitHub — or leave it set to None.
| Field | Description |
|---|---|
| Program Storage | Where shared programs are stored: None, Azure Blob Storage, or GitHub |
| Azure Storage Account / Azure Access Key | (Azure backend) The storage account name and its shared access key |
| GitHub Account Name / Personal Token / Repository / Branch | (GitHub backend) The account, token, repository, and optional branch used to store programs |
To configure Program Storage:
- On the ToolBox Setup page, set a distinct Nickname for the environment.
- Set Program Storage to Azure Blob Storage or GitHub.
- Fill in the fields shown for the chosen backend.
Shared programs are then pushed when you save and pulled when the ToolBox opens. See Program Storage for full details.
Remote ToolBox
The Remote ToolBox group enables communication between ToolBox instances across different Business Central environments. This is used by the Remote Packages feature to copy data between environments and tenants.
| Field | Description |
|---|---|
| Tenant ID | The Azure AD tenant ID of the remote environment. Leave blank for the current tenant. |
| Application ID | The Application (Client) ID from your Azure AD app registration |
| Secret Value | The client secret from the app registration (displayed as masked text) |
To configure Remote ToolBox:
- On the ToolBox Setup page, locate the Remote ToolBox group.
- Enter the Tenant ID of the target environment (leave blank if same tenant).
- Enter the Application ID from your Azure AD app registration.
- Enter the Secret Value for the app registration.
- For detailed setup instructions, click the Remote ToolBox Documentation link on the setup page, which opens https://www.hougaard.com/remote-toolbox/.
GitHub Integration
The GitHub Integration group enables the Data in GitHub feature, which lets you version-control Business Central table data using GitHub repositories.
| Field | Description |
|---|---|
| GitHub Account Name | Your GitHub username or organization name |
| GitHub Personal Token | A GitHub personal access token with repository access (displayed as masked text) |
| JSON Format | Choose between Verbose (human-readable) and Compact formatting for the JSON files stored in GitHub |
| Empty Tables Before Pull | When enabled, tables are cleared before pulling data from GitHub |
To configure GitHub Integration:
- On the ToolBox Setup page, locate the GitHub Integration group.
- Enter your GitHub Account Name.
- Enter a GitHub Personal Token with the appropriate repository permissions.
- Choose the JSON Format (Verbose is recommended for readability; Compact saves storage space).
- Optionally enable Empty Tables Before Pull if you want a clean slate before importing data from GitHub.
The ToolBox Setup Page Layout Summary
The following table provides a complete overview of all field groups on the ToolBox Setup page:
| Group | Fields | Purpose |
|---|---|---|
| General | Tenant ID, Environment, Nickname | Environment identification and labeling |
| Program Storage | Program Storage (None/Azure/GitHub) and the chosen backend's fields | Cloud or version-control storage for program synchronization |
| Remote ToolBox | Tenant ID, Application ID, Secret Value | Cross-environment data transfer via Remote Packages |
| AI Providers (action) | Provider, Endpoint, Access Key, Model, ToolBox Agent | The ToolBox Agent and the SQL Agent |
| GitHub Integration | GitHub Account Name, GitHub Personal Token, JSON Format, Empty Tables Before Pull | Version control for Business Central data |
Quick Start: Write Your First "Hello World" Script
Once you have completed the basic setup (steps 1 through 4), you can write your first ToolBox script to verify everything is working:
- Open the Erik's ToolBox main page.
- Choose Interactive Code to open the code editor.
- In the editor, type the following script:
begin
message('Hello, World!');
end;- Press F9 or choose the Run action in the action bar to execute the script.
- You should see a Business Central message dialog displaying "Hello, World!".
If the script runs successfully, your ToolBox is correctly installed and configured.
Next Steps After Hello World
After confirming the basic setup works, try these progressively more advanced scripts:
Read data from a table:
var
Customer: Record Customer;
begin
if Customer.FindFirst() then
message('First customer: %1', Customer.Name);
end;Use a loop to iterate records:
var
Item: Record Item;
Count: Integer;
begin
if Item.FindSet() then
repeat
Count += 1;
until Item.Next() = 0;
message('Total items: %1', Count);
end;Write output to the console:
var
Customer: Record Customer;
begin
if Customer.FindSet() then
repeat
printline(Customer."No." + ' - ' + Customer.Name);
until Customer.Next() = 0;
end;For detailed information about the code editor and execution environment, see Interactive Code Overview.
Post-Configuration Verification
After completing the initial configuration, verify each component:
| Component | How to Verify |
|---|---|
| License | Open ToolBox Setup > License; confirm expiration date is shown |
| General settings | Confirm Nickname appears correctly |
| Users | Open ToolBox Setup > Users; confirm all required users are listed with correct access levels |
| Symbols | Open Interactive Code and verify that table names auto-complete when typing |
| AI agents (if configured) | Open Interactive Code and confirm the ToolBox Agent FactBox shows its intro; open the SQL Workbench and confirm the SQL Agent FactBox |
| Program Storage (if configured) | Open Interactive Code and verify that shared programs sync from Azure or GitHub |
| GitHub (if configured) | Open Data in GitHub and verify repository connection |
Tips and Best Practices
- Complete the license registration first in production environments to avoid confusion about restricted functionality.
- Use descriptive Nicknames that clearly identify each environment, especially if you manage multiple environments.
- Start with ReadOnly access for new users and upgrade as needed. It is safer to grant additional permissions later than to revoke them.
- Download symbols after each major extension update to keep IntelliSense data current.
- Store API keys and secrets securely. The ToolBox masks these fields on the Setup page, but you should also follow your organization's key management policies.
- If you configure multiple optional integrations, test each one individually before using them together.