Remote Packages Overview

Introduction

Remote Packages in Erik's ToolBox for Business Central allow you to transfer data between separate Business Central environments and tenants. Whether you need to migrate master data from a production environment to a sandbox, synchronize reference data across multiple tenants, or set up a test environment with realistic data, Remote Packages provide a structured and secure way to accomplish these tasks without leaving Business Central.

Rather than exporting data to files, manually transforming it, and importing it into another environment, you define a reusable package that specifies exactly which tables, fields, and records to transfer. The ToolBox then handles the entire data retrieval process over the Business Central API using OAuth2 authentication.

What Are Remote Packages?

A Remote Package is a reusable data transfer definition that describes what data to pull from a remote Business Central environment into your local environment. Each package is stored in the Remote Package table and can contain multiple table selections, each with its own filters and field exceptions.

At its core, a Remote Package defines:

Which tables to include in the transfer.
Which records within those tables to transfer, controlled by filters.
Which fields to include or exclude from the transfer.
Which company to pull data from on the remote environment.
Which company to write data into on the local environment.

Once you have defined a package, you can execute it repeatedly. This makes Remote Packages ideal for recurring data transfer scenarios where you need to pull the same type of data on a regular basis.

Common Use Cases

Remote Packages support a wide range of cross-environment data transfer scenarios. The following are some of the most common situations where you would use this feature.

Data Migration

When you are setting up a new Business Central environment, you often need to bring over master data such as customers, vendors, items, chart of accounts, and posting groups from an existing environment. Remote Packages let you define exactly which tables and records to migrate, execute the transfer, and verify the results -- all from within Business Central.

Environment Synchronization

If you maintain multiple Business Central environments (for example, production and staging), you may need to keep certain reference data in sync across those environments. Remote Packages allow you to define a package that pulls the latest reference data from your production environment into your staging or development environment on demand.

Test Data Setup

When preparing a test or sandbox environment, you need realistic data to validate business processes. Rather than manually creating test records or relying on generic sample data, you can use Remote Packages to pull a filtered subset of production data into your test environment. By using table filters, you can limit the data to specific date ranges, customers, or other criteria to keep the dataset manageable.

Master Data Distribution

Organizations that operate multiple Business Central tenants or companies often need to distribute master data (such as item catalogs, dimension values, or posting setups) from a central source to multiple target environments. Remote Packages let you define a standard package for this purpose and execute it against each target environment as needed.

In scenarios where different business units or subsidiaries operate in separate Azure AD tenants, Remote Packages enable you to pull data across tenant boundaries. The OAuth2 authentication mechanism supports cross-tenant access, provided the appropriate app registration and permissions are in place.

How Remote Packages Work

The Remote Packages feature operates on a pull model. You define a package in your local (target) environment that describes what data to retrieve from a remote (source) environment. When you execute the package, the ToolBox connects to the remote environment's API, retrieves the specified data, and writes it into the corresponding tables in your local environment.

The overall workflow consists of the following steps:

Configure authentication. Set up the OAuth2 credentials (Remote Application ID, Remote Secret, and Remote Tenant ID) in the ToolBox Setup so that your local environment can authenticate against the remote environment's API.
Create a package. Open the Remote Packages and create a new package. Give it a meaningful name and description, and configure the source and target company mapping.
Define table selections. For each table you want to include in the transfer, add an entry to the package's table subform. Specify the table, set any record filters, and configure field exceptions for fields you want to exclude.
Preview record counts. Before executing the package, use the PullPackageSizes() function to retrieve the number of records that match your filters on the remote environment. This lets you verify that your filters are correct and that the data volume is as expected.
Execute the package. Run the PullPackage() function to download the data from the remote environment and write it into the local tables. Monitor the progress and review the results when the transfer completes.

Data Direction

Remote Packages are designed primarily for pulling data from a remote environment into your local environment. The local environment is the target (where data is written), and the remote environment is the source (where data is read from).

This pull-based approach ensures that you maintain control over what data enters your environment. You define the package locally, you initiate the transfer locally, and you review the results locally. The remote environment only needs to expose its API and grant the appropriate permissions -- it does not need any special configuration for Remote Packages.

The Package Concept

A key design principle of Remote Packages is reusability. Rather than performing ad-hoc data transfers, you create package definitions that can be saved, edited, and executed multiple times. This approach offers several advantages:

Consistency. Every time you execute a package, the same tables, filters, and field exceptions are applied. This eliminates the risk of forgetting a table or misconfiguring a filter during a manual transfer.
Efficiency. Once a package is defined, executing it takes just a few clicks. You do not need to reconfigure the transfer each time.
Documentation. The package definition itself serves as documentation of what data is being transferred. You can review a package's configuration at any time to understand its scope and purpose.
Auditability. Because packages are stored as records in Business Central, you can track who created or modified them and when.

Security Model

Remote Packages use OAuth2 authentication to establish a secure connection between your local environment and the remote environment. The authentication is based on an Azure AD (Entra ID) app registration, which provides:

Application (Client) ID. Identifies the app registration that the ToolBox uses to authenticate.
Client Secret. A secret value generated for the app registration, used to prove the app's identity.
Tenant ID. The Azure AD tenant ID of the remote environment, which identifies the target organization.

These credentials are configured globally in the ToolBox Setup page (fields: RemoteApplicationID, RemoteSecret, RemoteTenantID). The ToolBox stores the client secret securely using Business Central's isolated storage mechanism.

Because the authentication uses an app registration rather than a user's personal credentials, you can control access to the remote environment independently of any individual user. You can also revoke access at any time by deleting the client secret or removing the app registration's permissions.

For detailed instructions on configuring authentication, see Remote Packages Setup.

Key Components

The Remote Packages feature is built on several core objects within Erik's ToolBox:

Component	Type	Description
Remote Package	Table	The main table that stores package definitions, including name, description, and company mapping.
Remote Package Table Filter	Table	Stores the record filters applied to each table within a package.
Remote Package Field Exception	Table	Stores the field exceptions (excluded fields) for each table within a package.
Remote Packages	Page	The list page that displays all defined packages. You use this page to create, edit, and manage packages.
Remote Package Card	Page	The card page for viewing and editing the details of a single package, including its table selections, filters, and field exceptions.
Remote Pack. Table Subform	Page	A subform embedded in the package card that lets you add and configure tables for the package.
Remote Pack. Fields	Page	A page that displays all fields for a selected table, allowing you to toggle which fields are included or excluded.
Remote Package Filters	Page	A page that displays and manages the filters applied to a selected table within the package.
Remote Package Management	Codeunit	The management codeunit that contains the core logic for connecting to the remote environment, retrieving data, and processing packages.

Per-Package Company Mapping

Business Central environments can contain multiple companies, and data transfers often need to account for differences in company structure between environments. Remote Packages support per-package company mapping, which means you can specify:

Source company. The company on the remote environment from which data will be read.
Target company. The company on your local environment into which data will be written.

This mapping is configured at the package level, so different packages can transfer data between different company pairs. For example, you might have one package that pulls data from "CRONUS International" on the remote environment into "Production Company" on your local environment, and another package that pulls data from "Test Company" on the remote into "Sandbox Company" locally.

Prerequisites

Before you can use Remote Packages, you must ensure the following:

ToolBox installed in both environments. Erik's ToolBox must be installed and configured in both the source (remote) and target (local) Business Central environments. The remote environment needs the ToolBox so that its API endpoints are available for data retrieval.
Azure AD app registration. You need an Azure AD app registration with the appropriate Business Central API permissions. This app registration provides the credentials used for OAuth2 authentication.
OAuth2 credentials configured. The Remote Tenant ID, Remote Application ID, and Remote Secret must be entered in the ToolBox Setup page on your local environment.
Network connectivity. Your local environment must be able to reach the remote environment's API endpoint over HTTPS.

For step-by-step setup instructions, see Remote Packages Setup.

Limitations and Considerations

When planning your use of Remote Packages, keep the following points in mind:

Data volume. Large data transfers can take significant time depending on the number of records and the network connection between environments. Use filters to limit data to only what you need, and consider running large transfers during off-peak hours.
Field compatibility. The source and target environments should have matching table structures for the tables included in the package. If the target environment has a different version of an extension that modifies a table's structure, field mismatches may occur.
Blob and media fields. Large binary fields (blobs) and media fields can significantly increase transfer times and data volume. Consider excluding these fields using field exceptions unless they are essential for your use case.
Permissions on the remote environment. The app registration used for authentication must have sufficient permissions to read the tables included in the package on the remote environment.
Data integrity. Remote Packages transfer data as-is from the source. They do not run validation triggers on the target environment. You should verify data integrity after a transfer, especially for tables with complex business logic or dependencies.

Next Steps

If you are ready to start using Remote Packages, proceed to the setup guide to configure your authentication credentials and prepare your environments:

Follow the Remote Packages Setup guide to configure OAuth2 authentication and prepare both environments.
Review the Remote Packages Usage guide for step-by-step instructions on creating and executing packages.