Add pages and reports to Tell me
Note
We're working on improving the onboarding experience for AL developers. If you've input for this article, we'd love to hear from you. Please use the Feedback section at the bottom of this article to help us make improvements that you’d like to see.
We also welcome contributions to our docs. New to contributing to docs? Don't worry, read more about contributing here Contribute to the help.
The Business Central client includes the Tell me feature that lets users find objects by entering search terms. When you add 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 makes the page or reports searchable, and the value chosen for the setting further sub categorizes the item.
Tell me finds pages and reports by searching the captions that are specified on page and report objects by the CaptionML property.
Work 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 don't specify UsageCategory, the page or report doesn't show up when you search in Dynamics 365 Business Central.
Tip
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 in the table. The sub category helps the user navigate through the search results and it's a best practice to be consistent when categorizing the pages and the reports that you add. A consistent approach helps guiding the user and improves productivity.
| Value | Description |
|---|---|
| None | The page or report isn't 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. |
Add more 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, the 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 doesn't always reflect what users 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'.
Note
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.
Example: Add a page to Tell me
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';
layout
{
area(content)
{
group(General)
{
field("No.";"No.") {}
field(Name;Name) {}
field(Description;Description) {}
}
}
}
}
Example: Add a report to Tell me
The following example creates a Customer List report and sets a UsageCategory property to the page, so that the report is discoverable through search using the Tell me feature. Also, the example sets the AdditionalSearchTerms property to add two search terms for the page.
report 50103 "Customer List"
{
AdditionalSearchTerms = 'Sales, Sold';
UsageCategory = ReportsAndAnalysis;
...
}
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
Note
Dynamics NAV Development Environment is DISCONTINUED AFTER: Business Central Spring 2019.
If you're 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