Dynamics 365 Business Central: How to clean up your data when copying to a sandbox environment (Sandbox Clean up)

Dynamics 365 Business Central

Hi, Readers.
Today I would like to talk about how to clean up your data when copying to a sandbox environment.

A sandbox environment is a non-production instance of Business Central. Isolated from production, a sandbox environment is the place to safely explore, learn, demo, develop, and test the service without the risk of affecting the data and settings of your production environment. When you create a new sandbox environment, you can copy an existing production environment.

When you create a sandbox environment as a copy of another environment, the new environment is created on the same application version as the environment that you are copying. The new environment will contain all data and all per-tenant extensions and AppSource extensions that are installed and published in the original environment that is being copied.

But if we have data that we don’t want to copy to Sandbox, or data that needs to be modified after copying to Sandbox, is there a way to handle it?

Yes, we can use the following codeunit.

codeunit 1884 “Sandbox Cleanup”: Codeunit that raises an event that could be used to clean up data when copying a company to sandbox environment.

It contains two procedures.

OnClearCompanyConfiguration(CompanyName: Text): Subscribe to this event to clean up company-specific data when copying to a sandbox environment.

OnClearDatabaseConfiguration(): Subscribe to this event to clean up environment-specific data when copying to a sandbox environment.

These two methods are called in the following codeunit.
codeunit 1885 “Sandbox Cleanup Impl.”

Next let’s see if they are used in the standard code of Business Central.

You can find an example in codeunit 8900 “Email Impl”.
Verison: 18.0.23013.24016

Source Code:

    [EventSubscriber(ObjectType::Codeunit, Codeunit::"Sandbox Cleanup", 'OnClearCompanyConfiguration', '', false, false)]
    local procedure DeleteEmailsForSandbox(CompanyName: Text)
        SentEmail: Record "Sent Email";
        EmailOutbox: Record "Email Outbox";

        EmailOutbox.ModifyAll(Status, Enum::"Email Status"::" ");

Note: This code was removed in BC18.1.

Let me refer to the standard code to make a simple example.
When copying to a sandbox environment:
1. Clear all payment methods

2. Modify the description of all payment terms to ‘Sandbox Description’

Okay, let’s start.

Source code:

codeunit 50102 EnvironmentTriggersTest
    [EventSubscriber(ObjectType::Codeunit, Codeunit::"Sandbox Cleanup", 'OnClearCompanyConfiguration', '', false, false)]
    local procedure RenameCustomers(CompanyName: Text)
        PaymentMethod: Record "Payment Method";
        PaymentTerms: Record "Payment Terms";

        PaymentTerms.ModifyAll(Description, 'Sandbox Description');

In sandbox:

Test video: From 1:20 to 5:04 is the sandbox environment creation process, which you can skip. (You can set the quality to 720p)

Dynamics 365 Business Central: How to clean up your data when copying to a sandbox environment

Note: If an error occurs in this codeunit, or if there are insufficient permissions, or if a table is modified that is not allowed, the Sandbox will not be created correctly. The status in the admin center will change from Preparing to Removing. So please do a complete test.

PS: codeunit 1884 “Sandbox Cleanup” is Replaced by Environment Cleanup module.


Hope this will help.

Thanks for reading.



Copied title and URL