Adding Pages and Reports to Tell me

The Business Central client includes the Tell me feature that lets users find objects by entering search terms. When you have added a page or a report in your extension, you most likely want it to be discoverable to users in Tell me. In AL, you make a page or report searchable from Tell me by setting the UsageCategory property in code. The UsageCategory setting will make the page or report searchable, and the value chosen for the setting will further sub categorize the item.


Tell me finds pages and reports by searching the captions that are specified on page and report objects by the CaptionML property.

Working with the UsageCategory property

When you create a Page or a Report, you add the UsageCategory Property. If the UsageCategory is set to None, or if you do not specify UsageCategory, the page or report will not show up when you search in Dynamics 365 Business Central.


The UsageCategory is also used to categorize pages and reports shown in the role explorer of the client. The role explorer includes two actions: Reports and Analysis and Administration. Pages and reports set to ReportsAndAnalysis will show when the Reports and Analysis action is selected. Pages and reports set to Administration will show when the Administration action is selected. For more information, see Finding Pages with the Role Explorer.

UsageCategory property values

The values for the UsageCategory property are listed below. The sub category will help the user navigate through the search results and it is a best practice to be consistent when categorizing the pages and the reports that you add. A consistent approach will help guiding the user and improve productivity.

Value Description
None The page or report is not included in search.
Lists The page or report is listed as Lists under the Pages and Tasks category.
Tasks The page or report is listed as Tasks under the Pages and Tasks category.
ReportsAndAnalysis The page or report is listed as Reports and Analysis under the Reports and Analysis category.
Documents The page or report is listed as Documents under the Reports and Analysis category.
History The page or report is listed as Archive under the Reports and Analysis category.
Administration The page or report is listed as Administration under the Pages and Tasks category.

Adding additional search terms

You can specify other words or phrases that can help users find a page or report by using the AdditionalSearchTerms and AdditionalSearchTermsML properties. If the page or report is searchable by Tell me (that is, th UsageCategory property is set a value other than None), the search terms specified by these properties are used in addition to the caption of the page or report. These properties are useful when the caption does not always reflect what users will look for. A good example of this in Business Central is pages and reports associated with Item. Users unfamiliar with Business Central might look for 'product' or 'merchandise' instead of 'item'.


For Business Central on-premises, the Business Central Web Server configuration file (navsettings.json) includes a setting called UseAdditionalSearchTerms that enables or disables the use of additional search terms by the Tell me. For more information, see Configuring Business Central Web Server Instances.


The following example creates a SimpleItemList page and sets a UsageCategory property to the page, so that the SimpleItemList page is discoverable through search using the Tell me feature. Also, the example sets the AdditionalSearchTerms property to add two search terms for the page.

page 50210 SimpleItemList 
    PageType = List; 
    SourceTable = Item; 
    UsageCategory = Lists;
    AccessByPermission = page SimpleItemList = X;
    ApplicationArea = All;
    AdditionalSearchTerms = 'product, merchandise';

                field("No.";"No.") {} 
                field(Name;Name) {} 
                field(Description;Description) {} 

Optional settings

In addition to making a page or report searchable, you can control the access of an object by providing Read, Insert, Modify, Delete, and Execute (RIMDX) permissions by adding the AccessByPermission property. Likewise, control the application area access on the specified object by adding the ApplicationArea Property.

The AccessByPermission property and ApplicationArea property are the optional settings, which can be applied with the UsageCategory property. These settings are used to set restrictions on an object when you enable the Search functionality.

Working in the Dynamics NAV Development Environment


Dynamics NAV Development Environment is DISCONTINUED AFTER: Business Central Spring 2019.

If you are using the Dynamics NAV Development Environment, you can also set UsageCategory, AdditionalSearchTerms, AccessByPermission, and ApplicationArea properties on pages and reports to control their search.

After you change these properties by using the Dynamics NAV Development Environment, before the changes take effect in the client, you must run Build Object Search Index from the Tools menu.

See Also

Adding Menus to the Navigation Pane
UsageCategory Property
Page Object
Report Object
AL Development Environment