Business Central 2026 release wave 1 (BC28): New Method for DataTransfer data type (AddDestinationFilter Method)

Hi, Readers.
Dynamics 365 Business Central 2026 wave 1 (BC28) is generally available. More details: General Available: Dynamics 365 Business Central 2026 release wave 1 (BC28)

I will continue to test and share some new features that I hope will be helpful. In this post, I would like to talk about a new Method for DataTransfer data type: AddDestinationFilter Method.

This new feature is not yet documented in the Business Central 2026 release wave 1 (BC28) release plan and AL Language extension changelog Version 17.0. but is mentioned in What’s new in Business Central 2026 release wave 1: AL Language.

DataTransfer is an AL data type that supports the bulk transferring of data between SQL based tables. Instead of operating on a row-by-row model, like the record API does, DataTransfer produces SQL code that operates on sets. This behavior improves the performance when moving data during upgrade and install.
DataTransfer Data Type: A structure building bulk transfer of data between tables.

We’ve had a brief discussion about this before.

With this wave (BC28), Microsoft introduced a new method, AddDestinationFilter Method.
DataTransfer.AddDestinationFilter(Integer, Text [, Any,…]) Method: Adds a filter for the destination table for the data transfer.

Version: Available or changed with runtime version 17.0.

Let’s see more details. The DataTransfer data type operates based on two distinct tables: the Source Table and the Destination Table.

For the source table, we can use the DataTransfer.AddSourceFilter method to filter the source table. For example,

However, up to BC27 (Runtime 16), filtering the target table was still not possible. With the latest update, that has finally changed with the introduction of AddDestinationFilter.

Syntax:

DataTransfer.AddDestinationFilter(DestinationField: Integer, String: Text [, Value: Any,...])

String: Type: Text
The filter expression. A valid expression consists of alphanumeric characters and one or more of the following operators: <, >, \, &, |, and =. You can use replacement fields (%1, %2, and so on) to insert values at runtime.

In the example below, the data will only be applied to the Purchase line where the Description is empty.

While DataTransfer data type is specialized, the addition of AddDestinationFilter makes it far more ‘usable’ for complex upgrade/install codeunit, give it a try!!!😁

Test code:

        Clear(PurchaseLineDataTransfer);
        PurchaseLineDataTransfer.SetTables(Database::"Purchase Line", Database::"Purchase Line");
        PurchaseLineDataTransfer.AddSourceFilter(PurchaseLine.FieldNo("IC Partner Ref. Type"), '=%1', PurchaseLine."IC Partner Ref. Type"::"Cross Reference");
        PurchaseLineDataTransfer.AddDestinationFilter(PurchaseLine.FieldNo(Description), '=%1', '');
        PurchaseLineDataTransfer.AddFieldValue(PurchaseLine.FieldNo("IC Partner Reference"), PurchaseLine.FieldNo("IC Item Reference No."));
        PurchaseLineDataTransfer.UpdateAuditFields := false;
        PurchaseLineDataTransfer.CopyFields();

END

Hope this will help.

Thanks for reading.

ZHU