Using request pages with XMLports

A request page is a page that is run before the XMLport starts to execute. Request pages enable end users to specify options and filters for an XMLport. Request pages are defined as part of designing a XMLport object. The syntax is shown further down in this article. You design the filters on request pages by using the following XMLport properties:

By default, a request page is displayed, unless the UseRequestPage is set to false; then the XMLport will start immediately. In this case, end users can't cancel the XMLport run.

By default, without having set anything else, a request page will always display the following buttons:

• Send to
• Print
• Preview
• Cancel

Additionally, you can add more options on the request page to allow the end user to filter the data displayed.

Filtering on request pages

The columns that you define as RequestFilterFields are shown on the request page and can be used for filtering the data before viewing or printing the report.

Defining the RequestFilterFields property in the tableelement() part of an XMLport is done like this:

XMLport 50104 "Export Customer List"
{
    CaptionML = ENU = 'Export customer List';
    Direction = Export;
    schema
    {
        textelement(root)
        {
            XmlName = 'Root';
            tableelement(Customer; Customer)
            {
                RequestFilterFields = "No.", "Search Name", "Customer Posting Group";
...

For more information about the XMLport object, see XMLport Object.

By default, for every table element in a XMLport, a FastTab for defining filters and sorting is created on the request page. To remove a FastTab from a request page, don't define any RequestFilterFields for the table element and set the SourceTableView property in an XMLport to define sorting. The request page is displayed, but there's no tab for this data item or table element.

If a DataItemTableView or SourceTableView isn't defined, then end users can select a sort column and sort order at runtime.

In a complex XMLport that uses data from several tables, the functionality may depend on a specific key and sort order. Design your XMLports so that end-users can't change the sort order in a way that affects their functionality.

For data items and table elements whose source table contains calculated fields, such as amounts and quantities, the Filter totals by: section is automatically included on the request page, which allows you to adjust various dimensions that influence calculations.

Defining a requestpage section

The following example illustrates how you can define a request page for a XMLport.

...
requestpage
    {
        SaveValues = true;

        // These properties control the title and content of the teaching tip.
        AboutTitle = 'Awesome report';
        AboutText = 'This is an awesome report. Use it to be awesome';
        // Use the multi-language versions AboutTitleML and AboutTextML if you need that.

        // This property defines the help page for this report.
        // Remember to also set contextSensitiveHelpUrl in the app.json
        ContextSensitiveHelpPage = 'business-central/sales-reports';

        layout
        {
            area(content)
            {
                group(Options)
                {
                    Caption = 'Options';
                    field(PostingDate; PostingDateReq)
                    {
                        ApplicationArea = Basic, Suite;
                        Caption = 'Posting Date';
                        ToolTip = 'Specifies the posting date for the invoice(s) that the batch job creates. This field must be filled in.';
                    }
                }
            }
        }

        trigger OnOpenPage()
        begin
            if PostingDateReq = 0D then
                PostingDateReq := WorkDate;
        end;

        var
            PostingDateReq: Date;
    }
...

Adding teaching tips to your XMLports

The primary purpose of a teaching tip is to increase the user's chance of success with the XMLport. So, the title and description of the teaching tip should answer the following hypothetical user questions:

• AboutTitle: What is this XMLport about?
• AboutText: What can I do with this XMLport?

Both of these properties (or their equivalent multi-language versions) must be defined on the request page for the teaching tip to appear.

With teaching tips, you can help explain logic that is relevant to the XMLport therefore allowing users to get on with a data task right away without blocking them. After users dismiss a teaching tip, they can choose or hover over the XMLport title in the request page. This action will reopen the teaching tip.

For more information about designing teaching tips and tours, see Teaching tips and in-app tours for onboarding users.

Adding help links to your XMLports

A key pillar of helping users help themselves is to give them access to help for the particular part of Business Central that they're working in. This also applies for XMLports.

Starting with Business Central 2023 release wave 1 (version 22), you can set the ContextSensitiveHelpPage property on XMLport request pages, which will in turn show the report help link in the Help pane.

Learn more links are generated based on two configuration settings:

• App-level configuration of the URL
• Request page-level configuration of report-specific article

For more information about configuring context-sensitive help, see Configure Context-Sensitive Help.

Related information

XMLport Object
RunRequestPage Method
Configure Context-Sensitive Help for reports
AboutTitle Property
AboutTitleML Property
AboutText Property
AboutTextML Property
ContextSensitiveHelpPage Property
RequestFilterHeading Property
RequestFilterHeadingML Property
RequestFilterFields Property
DataItemTableView