Remote Packages Usage

Introduction

This chapter provides step-by-step instructions for creating, configuring, and executing Remote Packages in Erik's ToolBox. It covers the complete workflow from creating a new package to verifying the transferred data in your local environment.

Before following these instructions, ensure that you have completed the setup described in Remote Packages Setup. All OAuth2 credentials must be configured in the ToolBox Setup, and both the local and remote environments must have the ToolBox installed.

Creating a Package

To create a new Remote Package, follow these steps:

Step 1: Open the Remote Packages

Use the search bar in Business Central and search for "Remote Packages" to open the Remote Packages page. This page displays all existing Remote Packages and provides actions for creating new ones.

Step 2: Create a New Package

From the Remote Packages, create a new entry. This opens the Remote Package Card page where you configure the package details.

Step 3: Set Package Name and Description

Enter a meaningful name for your package that clearly identifies its purpose. For example:

"Customer Master Data - Production to Sandbox"
"Chart of Accounts Sync"
"Item Catalog - January 2026"

Optionally add a description that provides additional context, such as the intended use, frequency of execution, or any special considerations.

Step 4: Configure Company Mapping

Set the source and target company fields:

Source Company. Enter the exact name of the company on the remote environment from which data will be read. The name must match the company name on the remote environment exactly, including capitalization and spacing.
Target Company. Enter the exact name of the company on your local environment into which data will be written.

If you are transferring data between identically named companies, both fields will have the same value. If the companies have different names on each environment, map them accordingly.

Step 5: Save the Package

Save the package to persist the basic configuration. You can now proceed to add tables and configure filters.

Adding Tables to a Package

Each Remote Package contains one or more table definitions that specify which tables to include in the data transfer. You manage these definitions using the Remote Pack. Table Subform page, which is embedded as a subform on the Remote Package Card.

Adding a Table

In the table subform on the Remote Package Card, create a new line.
Select the table you want to include by entering the table ID or using the lookup to browse available tables.
Repeat for each additional table you want to include in the package.

You can add as many tables as needed. Common combinations include:

Master data set. Customer, Vendor, Item, G/L Account, and related setup tables.
Posting setup. General Posting Setup, VAT Posting Setup, Customer Posting Group, Vendor Posting Group.
Dimensions. Dimension, Dimension Value, Default Dimension.
Single table. A single table for focused, targeted transfers.

Ordering Tables

Consider the order in which tables are listed in the package. While the ToolBox does not enforce referential integrity during the transfer, having parent tables listed before child tables can help you identify issues more easily when reviewing results.

Configuring Table Filters

Filters allow you to limit which records are transferred for each table. Without filters, all records in the table on the remote environment will be included.

Setting Filters

Select a table entry in the table subform.
Open the filter configuration using the Remote Package Filters page.
Add one or more filter entries, each specifying a field and a filter expression.

Filter Expressions

Filter expressions follow the standard Business Central filter syntax. Common patterns include:

Pattern	Example	Description
Exact match	`10000`	Records where the field equals exactly 10000.
Range	`10000..20000`	Records where the field is between 10000 and 20000, inclusive.
Wildcard	`A*`	Records where the field starts with "A."
Multiple values	`10000	20000	30000`	Records where the field equals any of the listed values.
Not equal	`<>0`	Records where the field is not equal to 0.
Date filter	`01/01/2026..01/31/2026`	Records within the specified date range.

You can combine multiple filters on different fields. All filters are applied with AND logic, meaning a record must satisfy all filters to be included.

Why Use Filters

Filters are important for several reasons:

Reduce data volume. Transferring only the records you need is faster and reduces the load on both environments.
Target specific data. If you only need customers from a specific region or items from a specific category, filters let you isolate exactly the records you want.
Avoid conflicts. By filtering out records that already exist in the target or that should not be overwritten, you can minimize data conflicts.
Test safely. When testing a package, you can apply restrictive filters to transfer only a handful of records and verify the results before running the full transfer.

Configuring Field Exceptions

Field exceptions let you exclude specific fields from the data transfer for each table. This is useful when certain fields should not be overwritten in the target environment or when large binary fields would unnecessarily slow down the transfer.

Viewing and Editing Field Exceptions

Select a table entry in the table subform.
Open the field configuration using the Remote Pack. Fields page.
This page displays all fields in the selected table, each with an include/exclude toggle.
Set fields to excluded for any fields you do not want to transfer.

Common Field Exceptions

The following types of fields are commonly excluded:

System fields. Fields like SystemId, SystemCreatedAt, SystemCreatedBy, SystemModifiedAt, and SystemModifiedBy are managed by the platform and should typically not be overwritten.
FlowFields. Calculated fields (FlowFields) derive their values from other data and do not need to be transferred. They will be recalculated automatically in the target environment.
Blob fields. Fields that store large binary data (images, documents, attachments) can dramatically increase transfer time. Exclude them unless the binary data is specifically needed.
Integration fields. Fields that store integration keys, external system references, or environment-specific identifiers may have different values in the target environment and should be excluded.
Audit fields. Fields that record who created or last modified a record may need to be excluded if you want the target environment to reflect its own audit trail.

Field Exception Strategy

When deciding which fields to exclude, consider the following approach:

Start with all fields included (the default).
Exclude system fields and FlowFields, which are almost never appropriate to transfer.
Exclude blob fields unless you specifically need the binary data.
Review remaining fields and exclude any that are environment-specific or should retain their current values in the target.
Test the package with a small dataset to verify that the included fields transfer correctly.

Previewing Record Counts

Before executing a package, you should always preview the expected data volume. The PullPackageSizes() function connects to the remote environment and retrieves the number of records that match your filters for each table in the package.

Running PullPackageSizes

Open the Remote Package Card for the package you want to preview.
Run the PullPackageSizes action.
The ToolBox connects to the remote environment and queries each table with the configured filters.
The record counts are displayed in the table subform, showing how many records will be transferred for each table.

Interpreting the Results

Review the record counts and verify that they match your expectations:

Zero records. If a table shows zero records, your filters may be too restrictive, or the table may be empty in the source company. Review the filter configuration.
Unexpectedly high counts. If the record count is much higher than expected, your filters may be too broad. Refine the filters to limit the dataset.
Expected counts. If the counts match what you expect, the package is likely configured correctly and ready for execution.

PullPackageSizes is a read-only operation. It does not modify any data in either environment. You can run it as many times as needed while adjusting filters to achieve the desired result.

Executing a Package

Once you have configured the package and verified the record counts, you can execute the data transfer.

Running PullPackage

Open the Remote Package Card for the package you want to execute, or select it from the Remote Packages.
Run the PullPackage action.
The ToolBox begins the data transfer process:
- It authenticates against the remote environment using the OAuth2 credentials from the ToolBox Setup.
- It queries each table in the package with the configured filters.
- It downloads the matching records, excluding any fields marked as exceptions.
- It writes the data into the corresponding tables in the target company on your local environment.
Monitor the progress as the transfer runs. The ToolBox provides feedback on which table is currently being processed.

Reviewing Results

After the transfer completes:

Navigate to the target tables in Business Central and verify that the expected records are present.
Spot-check individual records to confirm that field values match the source data.
Verify that excluded fields were not overwritten (they should retain their original values in the target).
Check for any error messages or warnings that may have been generated during the transfer.

Handling Errors

If errors occur during execution:

Authentication errors. Verify that the OAuth2 credentials in the ToolBox Setup are correct and that the client secret has not expired. See Remote Packages Setup for troubleshooting guidance.
Table not found. Verify that the table exists and is accessible on the remote environment. The table structure may differ between environments if different extension versions are installed.
Permission denied. Verify that the app registration has adequate permissions on the remote environment for the tables being transferred.
Timeout or network errors. Large transfers may time out if the network connection is slow or unstable. Consider breaking the package into smaller packages or applying more restrictive filters.

Managing Packages

Over time, you will accumulate multiple packages for different data transfer scenarios. The following practices help you manage them effectively.

Editing Existing Packages

You can modify any aspect of an existing package at any time:

Change the package name or description to reflect updated purposes.
Add or remove tables from the table subform.
Adjust filters to broaden or narrow the data selection.
Update field exceptions as your requirements change.
Change the company mapping if your environment structure changes.

All changes take effect the next time you execute the package. Previous executions are not affected by subsequent changes to the package definition.

Duplicating Packages

If you need a package that is similar to an existing one but with some differences, you can duplicate the existing package and modify the copy. This saves time compared to creating a new package from scratch, especially for packages with many tables and complex filter configurations.

Common duplication scenarios include:

Creating environment-specific variants (production-to-sandbox vs. production-to-test).
Creating date-specific variants (same tables but different date filters for each period).
Creating subset variants (a full package and a lightweight version with fewer tables).

Deleting Packages

When a package is no longer needed, you can delete it from the Remote Packages. Deleting a package removes the package definition, all associated table entries, filters, and field exceptions. This operation cannot be undone, so verify that the package is truly no longer needed before deleting it.

Best Practices

The following best practices will help you get the most out of Remote Packages while minimizing risk.

Start Small

When creating a new package, begin with a single table and a restrictive filter that limits the transfer to a small number of records (for example, 10-50). Execute the package, verify the results, and then expand the scope by adding more tables and relaxing filters. This incremental approach helps you catch configuration issues early before they affect large volumes of data.

Use Descriptive Names

Give your packages clear, descriptive names that communicate their purpose at a glance. Include relevant details such as the direction of transfer, the type of data, or the intended frequency. For example, "Customer Master - Prod to Sandbox - Monthly" is more informative than "Package 1."

Filter Aggressively

Always apply filters unless you genuinely need all records from a table. Even for master data tables, you can often filter out inactive or obsolete records. Aggressive filtering reduces transfer time, minimizes the risk of overwriting data you did not intend to change, and makes it easier to review results.

Exclude Unnecessary Fields

Review the field list for each table and exclude fields that are not needed for your use case. In particular:

Always exclude FlowFields, as they are recalculated and cannot be meaningfully transferred.
Exclude blob fields unless the binary content is essential.
Exclude system fields to avoid overwriting platform-managed metadata.

Run During Off-Peak Hours

For large data transfers, schedule the execution during off-peak hours when both the local and remote environments have lower user activity. This reduces the impact on other users and decreases the likelihood of timeout errors caused by resource contention.

Verify Data Integrity

After every package execution, verify the transferred data:

Check record counts in the target tables.
Spot-check field values for a sample of records.
Verify that related records are consistent (for example, if you transferred customers and customer posting groups, confirm that the posting group codes referenced by customers exist in the target).
If the transferred tables have dependencies on other tables that were not included in the package, verify that those dependencies are satisfied.

Document Your Packages

Use the description field to document the purpose and configuration rationale for each package. This is especially important if multiple team members use Remote Packages or if packages are executed infrequently. A clear description helps anyone understand why a package exists and what it does without having to inspect every table and filter.

Test Before Production

Always test a new or modified package in a non-production environment before running it against production data. Create a sandbox or test environment that mirrors your production setup, execute the package there, and verify the results. Only after successful testing should you execute the package in production.

Example Workflow

The following example illustrates a typical end-to-end workflow for transferring customer master data from a production environment to a sandbox environment.

Open the Remote Packages. Search for "Remote Packages" in Business Central.
Create a new package. Name it "Customer Master Data - Prod to Sandbox." Add a description: "Transfers active customers and related posting groups from the production environment to the sandbox for testing."
Configure company mapping. Set the source company to "CRONUS International Ltd." (the company name in production) and the target company to "CRONUS International Ltd." (the same name in the sandbox).
Add tables. In the table subform, add:
- Table 18 (Customer)
- Table 92 (Customer Posting Group)
Set filters on the Customer table. Open the filter list for Table 18 and add a filter on the Blocked field: set it to ' ' (empty, meaning not blocked) to transfer only active customers.
Configure field exceptions for the Customer table. Open the fields list for Table 18 and exclude:
- SystemId, SystemCreatedAt, SystemCreatedBy, SystemModifiedAt, SystemModifiedBy
- Any FlowFields (such as Balance, Balance (LCY), Net Change)
- The Image field (blob) if customer images are not needed
Preview record counts. Run PullPackageSizes to verify the counts. You expect approximately 500 active customers and 5 posting groups.
Execute the package. Run PullPackage to transfer the data.
Verify the results. Open the Customer list in the sandbox and confirm that the expected customers are present. Spot-check a few records to verify field values. Open the Customer Posting Groups and confirm the posting group entries are present.

Next Steps

Now that you know how to create and execute Remote Packages, you can explore related features:

Review the Remote Packages Overview for a deeper understanding of the architecture and design principles.
Revisit the Remote Packages Setup if you need to update credentials or troubleshoot connectivity.
Explore Data in GitHub for version-controlled data management as an alternative or complement to Remote Packages.