{"title":"Create a custom filter token","url":"https://jonas-paprotka.de/docs/dev-itpro/developer/devenv-adding-filter-tokens/","by":"JOP-AL","license":"Copyright (c) Microsoft Corporation. CC BY 4.0, https://creativecommons.org/licenses/by/4.0/; code samples MIT. From https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-adding-filter-tokens, MicrosoftDocs/dynamics365smb-devitpro-pb at 828b6ee (2026-11-19). Changed: includes filled in, links to this site, and for agents shortened without dropping a fact.","credit":"Microsoft Corporation, CC BY 4.0","origin":"https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-adding-filter-tokens","source":{"name":"Business Central developer and IT pro docs","repo":"https://github.com/MicrosoftDocs/dynamics365smb-devitpro-pb","commit":"828b6ee72fcd75755627cd6011f3d20899217ab2","date":"2026-11-19"},"checked":"2026-11-19","description":"Learn how to create custom filter tokens in AL so users can enter shortcuts that resolve to reusable filter values in Business Central lists.","date":"2026-10-06","meta":{"topic":"concept-article"},"outline":[{"level":1,"title":"Create a custom filter token","slug":"create-a-custom-filter-token","at":0,"chars":4220},{"level":2,"title":"Define the token word and handler","slug":"define-the-token-word-and-handler","at":1077,"chars":847},{"level":2,"title":"Create a custom filter token","slug":"create-a-custom-filter-token-1","at":1924,"chars":1460},{"level":2,"title":"Design considerations","slug":"design-considerations","at":3384,"chars":746},{"level":2,"title":"Related information","slug":"related-information","at":4130,"chars":90}],"text":"# Create a custom filter token\nIn the client, when filtering lists using the filter pane, users can enter filter tokens, which are special words that resolve to one or more values. This powerful feature makes filtering easier by reducing the need to navigate to other pages to look up values to enter as filter criteria.\nBusiness Central provides several useful filter tokens. For example, when you enter `%mycustomers` in a Customer No. field, it resolves to the set of customers in the user's My Customers list, such as `1001|1002`. The resolved filter makes it easy to find relevant sales orders for customers 1001 and 1002.\nYou can add custom filter tokens and make these available in any language and across the application. To add your custom filter token, you need to define the token word that users will enter as filter criteria, and define a handler that resolves the token to a concrete value at runtime. Learn more about filter tokens in https://github.com/microsoft/BCApps/tree/main/src/System%20Application/App/Filter%20Tokens in the BCApps repository on GitHub.\n## Define the token word and handler\nTo create the token word, start by defining a multi-language text string for your word. Subscribe to the OnResolveTextFilterToken event associated with the MakeTextFilter method from the `Filter Tokens` codeunit.\nIn the event subscriber, if the value of the TextToken parameter contains the token string, process its value and construct the final filter string. If the filter string must contain multiple values, handle the operators that join them by adding the `|` filter symbol (OR operation). Complete the operation by setting the TextFilter parameter to the final filter string and the Handled parameter to true.\n> TIP\n> Filter criteria will often contain symbols along with filter tokens. We recommend that you only modify the filter token you have introduced and preserve the rest of the filter string.\n## Create a custom filter token\nThis example shows how you can use the guidelines to create the `%MYTOKEN` filter token. The token returns a filter with the accounts that the user marked as favorites.\n> NOTE\n> To keep this sample short and simple, the entire filter string is overwritten.\n```al\ncodeunit 50101 MyAccountFilterTokenSimple\n{\n    [EventSubscriber(ObjectType::Codeunit, Codeunit::\"Filter Tokens\", 'OnResolveTextFilterToken', '', true, true)]\n    local procedure FilterMyAccounts(TextToken: Text; var TextFilter: Text; var Handled: Boolean)\n    var\n        MyAccount: Record \"My Account\";\n        MaxCount: Integer;\n        MyTokenLbl: Label 'MYTOKEN';\n    begin\n        if StrLen(TextToken) < 3 then\n            exit;\n\n        if StrPos(UpperCase(MyTokenLbl), UpperCase(TextToken)) = 0 then\n            exit;\n\n       Handled := true;\n\n        MaxCount := 20;\n        MyAccount.SetRange(\"User ID\", UserId());\n\n        if MyAccount.FindSet() then begin\n            MaxCount -= 1;\n            TextFilter := MyAccount.\"Account No.\";\n\n            if MyAccount.Next() <> 0 then\n                repeat\n                    MaxCount -= 1;\n                    TextFilter += '|' + MyAccount.\"Account No.\";\n                until (MyAccount.Next() = 0) or (MaxCount <= 0);\n        end;\n    end;\n\n}\n```\nTo try it in the client, open the Chart of Accounts page, filter the No. field, and enter a substring that starts with the chosen token word, such as `%MYTO`.\n## Design considerations\nFilter tokens must resolve quickly and reliably. These events can run for any user task in Business Central. In some cases, they run repeatedly, such as when users search across columns. To improve usability and performance, consider these practices:\n Avoid implementing tokens that are relevant to only a few business tasks or that assume they're used in the context of a specific page.\n Avoid implementing tokens that are time-consuming to resolve. Examples include looking up records in large or poorly indexed tables and fetching data from a remote service.\n Avoid implementing tokens that are complex or unreliable and might result in an error.\n Avoid displaying pages, dialogs, or any other form of interactive UI.\n## Related information\nSorting, searching, and filtering lists</ui-enter-criteria-filters>"}