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

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)
    var
        SentEmail: Record "Sent Email";
        EmailOutbox: Record "Email Outbox";
    begin
        SentEmail.ChangeCompany(CompanyName);
        SentEmail.DeleteAll();

        EmailOutbox.ChangeCompany(CompanyName);
        EmailOutbox.ModifyAll(Status, Enum::"Email Status"::" ");
        EmailOutbox.DeleteAll();
    end;

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)
    var
        PaymentMethod: Record "Payment Method";
        PaymentTerms: Record "Payment Terms";
    begin
        PaymentMethod.ChangeCompany(CompanyName);
        PaymentMethod.DeleteAll();

        PaymentTerms.ChangeCompany(CompanyName);
        PaymentTerms.ModifyAll(Description, 'Sandbox Description');
    end;
}

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)

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.

END

Hope this will help.

Thanks for reading.

ZHU