Bearbeiten

Freigeben über

Using request pages with XMLports

  • Artikel

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:

Property Description
RequestFilterHeading Property Sets a caption for the request page tab that is related to a report's data item or an XMLport's table element.
RequestFilterHeadingML Property Sets the text used as a RequestFilterHeading Property for a request page tab.
RequestFilterFields Property Specifies which columns are automatically included on the tab of the request page that is related to a report's data item or an XMLport's table element. The user can set filters on these columns.
AboutTitle Property Specifies the title for a teaching tip on the report.
AboutTitleML Property Specifies the multi-language version of the title for a teaching tip on the report.
AboutText Property Specifies the text for a teaching tip on the report.
AboutTextML Property Specifies the multi-language version of the text for a teaching tip on the report.
ContextSensitiveHelpPage Property Specifies the help topic to show when the user presses Help in the UI. Note that the help server on which this help topic is located, must be defined in the app.json file.

Note

Request pages for XMLports aren't supported by the Business Central Web client in versions prior to Dynamics 365 Business Central 2019 release wave 2. If you try to run an XMLport with a request page from the web client in these versions, you receive an error that the XMLport page type is not supported. Alternatively, XMLport request pages do work in the Dynamics NAV Client connected to Business Central.

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.

Note

It's recommended to add columns that the end users of the report will frequently set filters on.

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.

Tip

For information about how to enter filter criteria on the request page, see Filtering in the Business Central application help.

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.

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.

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