Dynamics 365 Business Central – What can you buy with Filter Tokens?

Do you use Filter Tokens in Microsoft Dynamics 365 Business Central? Have you heard of Filter Tokens?

Filter Tokens are special words that resolve to a filter string of values. Several Filter Tokens are defined in Microsoft Dynamics 365 Business Central; for example, the ‘%mycustomers’ Token (Note: when using a Filter token, an ampersand precedes the filter text) returns a filter of Customer numbers for the user’s My Customers list. The user of the ‘%mycustomers’ filter token simplifies users’ experience when filtering their customers.

You can define token words that users can enter for a filter to simplify the filtering of records. The events found in codeunit 41, “Filter Tokens,” are the key to building your own Filter Token. Subscribe to the appropriate event and compare the FilterToken entered to your word, and then make the proper TextFilter value to return from the event.

The following AL code example demonstrates creating a token, ‘USCUSTOMERS’, that constructs a filter for all customers with a Country/Region Code of ‘US’.

codeunit 50101 "DVLPR FilterToken Management"
{
    [EventSubscriber(ObjectType::Codeunit, Codeunit::"Filter Tokens", 'OnResolveTextFilterToken', '', true, true)]
    local procedure OnResolveTextFilterToken(TextToken: Text; var TextFilter: Text; var Handled: Boolean)
    var
        Customer: Record Customer;
        MaxCount: Integer;
    begin
        if StrLen(TextToken) < 3 then
            exit;

        if StrPos(UpperCase('USCUSTOMERS'), UpperCase(TextToken)) = 0 then
            exit;

        Handled := true;

        MaxCount := 200;
        Customer.SetRange("Country/Region Code", 'US');

        if Customer.FindSet() then begin
            MaxCount -= 1;
            TextFilter := Customer."No.";

            if Customer.Next() <> 0 then
                repeat
                    MaxCount -= 1;
                    TextFilter += '|' + Customer."No.";
                until (Customer.Next() = 0) or (MaxCount <= 0);
        end;
    end;
}

Using the Token %uscustomers for a Filter where a “Customer No.” Filter is expected, returns a filter string containing matching customers.

This example is intended only to demonstrate the use of Filter Tokens. When creating a token design, consider the design of your implementation. Complex, unreliable or time-consuming tokens may result in a less-than-desirable user experience.

Note: The code and information discussed in this article is for informational and demonstration purposes only. This content was created referencing Microsoft Dynamics 365 Business Central 2022 Wave 2 online.