Remote Packages Setup

Before You Begin

Before you can create and execute Remote Packages, you must configure the authentication credentials that allow your local Business Central environment to connect securely to the remote environment. This chapter walks you through all the required setup steps, from creating an Azure AD app registration to entering the credentials in the ToolBox Setup page.

If you are not familiar with what Remote Packages are or how they work, review the Remote Packages Overview first.

Prerequisites

To complete the Remote Packages setup, you need the following:

Erik's ToolBox installed in both environments. The ToolBox must be installed and licensed in both the local (target) environment and the remote (source) environment. The remote environment requires the ToolBox so that the API endpoints used for data retrieval are available.
Access to the Azure Portal. You need access to the Azure Portal for the Azure AD tenant that hosts the remote Business Central environment. You will create an app registration in this tenant.
Administrator or Application Administrator role. To create app registrations and grant admin consent in Azure AD, you need the appropriate Azure AD role (typically Global Administrator or Application Administrator).
ToolBox Setup access. You must be able to open and edit the ToolBox Setup page in your local Business Central environment. This typically requires the SUPER permission set or an equivalent ToolBox administrator role.

Global Remote Configuration

The OAuth2 credentials for connecting to the remote environment are configured globally in the ToolBox Setup page. These credentials apply to all Remote Packages and are used whenever the ToolBox connects to a remote environment.

Accessing the ToolBox Setup

To open the ToolBox Setup page, use the search bar in Business Central and search for "ToolBox Setup," or navigate to it from the Erik's ToolBox administration area. The remote configuration fields are located in the setup page and include:

Field	Description
Remote Tenant ID	The Azure AD (Entra ID) tenant ID of the remote Business Central environment. This is a GUID that identifies the Azure AD tenant where the remote environment is hosted.
Remote Application ID	The Application (Client) ID from the Azure AD app registration. This GUID identifies the app registration that the ToolBox uses to authenticate against the remote environment.
Remote Secret	The client secret generated for the Azure AD app registration. This value is used to prove the app's identity during the OAuth2 authentication flow. The secret is stored securely using Business Central's isolated storage mechanism.

You must fill in all three fields before you can execute any Remote Package. If any of these fields are missing or incorrect, the ToolBox will not be able to authenticate against the remote environment and the package execution will fail.

Azure AD App Registration

The Remote Packages feature uses OAuth2 client credentials flow to authenticate against the remote Business Central environment. This requires an Azure AD app registration in the tenant that hosts the remote environment.

Step 1: Create the App Registration

Sign in to the Azure Portal using an account with Global Administrator or Application Administrator permissions.
Navigate to Azure Active Directory (or Microsoft Entra ID) > App registrations.
Click New registration.
Enter a meaningful name for the registration, such as "Erik's ToolBox Remote Packages" or "BC ToolBox Data Transfer."
Under Supported account types, select the option appropriate for your scenario:
- Single tenant if the local and remote environments are in the same Azure AD tenant.
- Multitenant if the local and remote environments are in different Azure AD tenants.
You do not need to configure a redirect URI for the client credentials flow.
Click Register to create the app registration.

After registration, you will see the app registration's overview page. Note the Application (client) ID -- you will need this value for the Remote Application ID field in the ToolBox Setup.

Step 2: Add Business Central API Permissions

In the app registration, navigate to API permissions.
Click Add a permission.
Select Dynamics 365 Business Central from the list of Microsoft APIs.
Choose Application permissions (not Delegated permissions), since the ToolBox uses the client credentials flow without user interaction.
Select the appropriate permissions. At a minimum, you need:
- API.ReadWrite.All -- Allows the app to read and write data through the Business Central API.
- app_access -- Grants application-level access to Business Central.
Click Add permissions to save your selections.

The specific permissions you need may vary depending on your Business Central version and configuration. Consult your Azure AD administrator if you are unsure which permissions are required for your environment.

Application permissions require admin consent before they take effect:

On the API permissions page, click Grant admin consent for [your tenant name].
Confirm the consent when prompted.
Verify that the Status column shows "Granted for [your tenant name]" for each permission.

If you do not have permission to grant admin consent yourself, you will need to request this from your Azure AD Global Administrator.

Step 4: Generate a Client Secret

In the app registration, navigate to Certificates & secrets.
Under the Client secrets tab, click New client secret.
Enter a description for the secret, such as "ToolBox Remote Packages."
Select an expiration period. Choose a duration that aligns with your organization's security policy. Common choices are 6 months, 12 months, or 24 months.
Click Add to generate the secret.
Immediately copy the secret value. This value is only displayed once. If you navigate away from this page without copying it, you will need to generate a new secret.

This secret value is what you will enter in the Remote Secret field in the ToolBox Setup.

Step 5: Note Your Tenant ID

If you do not already know your Azure AD tenant ID:

In the Azure Portal, navigate to Azure Active Directory (or Microsoft Entra ID) > Overview.
The Tenant ID is displayed on the overview page.

Alternatively, you can find the tenant ID on the app registration's overview page under Directory (tenant) ID.

Configuring the Remote Environment

The remote (source) Business Central environment must be configured to accept API connections from the app registration you created.

Register the App in Business Central

For the app registration to access Business Central data, you must register it within Business Central on the remote environment:

Open the remote Business Central environment.
Search for Azure Active Directory Applications (or Microsoft Entra ID Applications).
Create a new entry using the Application (Client) ID from your app registration.
Set the State to Enabled.
Assign the appropriate permission sets to the app. At a minimum, the app needs read access to all tables that you plan to include in your Remote Packages. For general use, you may assign the SUPER permission set, though this should be done with caution in production environments.

Without this registration in Business Central, the app will be able to authenticate at the Azure AD level but will be denied access to Business Central data.

Verify API Access

To confirm that the remote environment is accessible:

Ensure the Business Central environment is running and accessible.
Verify that the API endpoint is enabled. For SaaS environments, the API is enabled by default. For on-premises environments, check that the OData or API services are enabled in the Business Central Server Administration tool.
If your organization uses network restrictions (such as IP whitelisting or conditional access policies), ensure that your local environment's outbound traffic is permitted to reach the remote environment.

Entering Credentials in ToolBox Setup

After completing the Azure AD app registration and configuring the remote environment, enter the credentials in your local Business Central environment:

Open the ToolBox Setup page in your local Business Central environment.
Locate the remote configuration fields.
Enter the Remote Tenant ID (the Azure AD tenant ID of the remote environment).
Enter the Remote Application ID (the Application/Client ID from the app registration).
Enter the Remote Secret (the client secret value you generated).
Save the setup page.

The ToolBox stores the Remote Secret securely using Business Central's isolated storage. The secret value is not visible in plain text after you save it.

Per-Package Configuration

In addition to the global authentication credentials, each Remote Package has its own configuration settings that control the scope and behavior of the data transfer.

Package Identity

When you create a new Remote Package (from the Remote Packages page or the Remote Package Card page), you define:

Package Name. A meaningful name that identifies the purpose of the package (for example, "Customer Master Data" or "Chart of Accounts Sync").
Description. An optional description that provides additional detail about the package's purpose, scope, or intended use.

Company Mapping

Each package includes company mapping fields:

Source Company. The company on the remote environment from which data will be read. This must match an existing company name on the remote environment.
Target Company. The company on your local environment into which data will be written. This must match an existing company name on your local environment.

Accurate company mapping is essential. If the source company name does not match a company on the remote environment, the API calls will fail. Similarly, if the target company name does not match a local company, the data cannot be written.

Table Selection

For each table you want to include in the package, you add an entry using the Remote Pack. Table Subform page. Each table entry specifies:

Table ID. The ID of the Business Central table to transfer.
Filters. Optional record filters that limit which records are included. Filters are managed through the Remote Package Filters page and stored in the Remote Package Table Filter table.
Field Exceptions. Optional field exclusions that control which fields are transferred. Field exceptions are managed through the Remote Pack. Fields page and stored in the Remote Package Field Exception table.

Field Exceptions

Not all fields in a table need to be transferred. Field exceptions let you exclude specific fields from the data transfer. Common reasons to exclude fields include:

System fields. Fields managed by the system (such as SystemId, SystemCreatedAt, SystemModifiedAt) that should not be overwritten.
Calculated fields. FlowFields and other calculated fields that are computed from other data and do not need to be transferred.
Blob fields. Large binary fields (such as images or documents) that significantly increase transfer volume and may not be needed.
Environment-specific fields. Fields that contain values specific to the source environment (such as integration keys or external references) that would be meaningless or incorrect in the target environment.

To configure field exceptions, open the Remote Pack. Fields page for the selected table. This page displays all fields in the table and allows you to toggle each field between included and excluded.

Security Considerations

When configuring Remote Packages, you should follow security best practices to protect your environments and data.

Credential Management

Store credentials securely. The ToolBox uses Business Central's isolated storage for the Remote Secret, which provides encryption at rest. Do not store credentials in external files or share them through insecure channels.
Rotate secrets regularly. Azure AD client secrets have expiration dates. Monitor your secret's expiration and rotate it before it expires to avoid service disruptions. When you generate a new secret, update the Remote Secret field in the ToolBox Setup.
Limit who can access the ToolBox Setup. Only authorized administrators should be able to view or modify the remote configuration fields. Use Business Central permission sets to restrict access to the setup page.

Least-Privilege Permissions

Assign minimal permissions. When registering the app in Business Central on the remote environment, grant only the permissions necessary for the tables you plan to transfer. Avoid assigning the SUPER permission set in production unless absolutely required.
Review permissions periodically. As your Remote Package configurations evolve, review the permissions assigned to the app registration to ensure they still align with your actual data transfer needs.

Data Protection

Review package contents before execution. Before running a Remote Package for the first time, review the table selections, filters, and field exceptions to ensure that only the intended data will be transferred.
Test with non-production data first. Before executing packages against production environments, test them in a sandbox or development environment to verify correct behavior.
Be cautious with sensitive data. If your tables contain personally identifiable information (PII), financial data, or other sensitive information, ensure that the data transfer complies with your organization's data governance policies and any applicable regulations.
Monitor API access. Use Azure AD sign-in logs and Business Central audit trails to monitor when and how the app registration accesses the remote environment.

Network Security

Use HTTPS. All communication between the local and remote environments occurs over HTTPS, which provides encryption in transit. Do not attempt to use HTTP connections.
Conditional access policies. If your organization uses Azure AD conditional access policies, ensure that the app registration is permitted to access Business Central from the network location of your local environment.

Troubleshooting Setup Issues

If you encounter problems during setup, check the following common causes.

Authentication Failures

Invalid credentials. Verify that the Remote Tenant ID, Remote Application ID, and Remote Secret are all correct and match the app registration exactly.
Expired secret. Client secrets have expiration dates. If your secret has expired, generate a new one in the Azure Portal and update the Remote Secret field.
Missing admin consent. Application permissions require admin consent. Verify that consent has been granted on the API permissions page in the Azure Portal.
App not registered in remote BC. The app registration must be registered and enabled in the Azure Active Directory Applications page in the remote Business Central environment.

Connection Errors

Network connectivity. Verify that your local environment can reach the remote environment's API endpoint. For SaaS environments, the endpoint is typically https://api.businesscentral.dynamics.com.
Firewall or proxy issues. Check whether network policies block outbound HTTPS traffic to the remote environment.
Environment not available. Confirm that the remote Business Central environment is running and accessible.

Permission Errors

Insufficient API permissions. Verify that the app registration has the required Business Central API permissions and that admin consent has been granted.
Insufficient BC permissions. Verify that the app registration has adequate permission sets assigned in the remote Business Central environment's Azure Active Directory Applications page.
Wrong company name. If the source company name in the package does not match a company on the remote environment, you will receive an error. Verify the company name is spelled exactly as it appears on the remote environment.

Verifying Your Setup

After completing all configuration steps, verify that everything is working correctly:

Open the ToolBox Setup page and confirm that the Remote Tenant ID, Remote Application ID, and Remote Secret fields are filled in.
Create a small test package with a single table that contains a small number of records (for example, the Country/Region table).
Use PullPackageSizes() to verify that the ToolBox can connect to the remote environment and retrieve record counts. If this succeeds, your authentication and connectivity are working.
Execute the test package using PullPackage() and verify that the data appears in the target table on your local environment.

If the test succeeds, your setup is complete and you can proceed to create packages for your actual data transfer needs.

Next Steps

With setup complete, you are ready to create and execute Remote Packages:

Follow the Remote Packages Usage guide for detailed instructions on creating packages, configuring table selections, previewing data, and executing transfers.