Adding fields to reports with ReportExtensions

One of the awesome new features of Microsoft Dynamics 365 Business Central 2021 Wave 1 (version 18) is the ability to extend reports. In this video I explore the simplest reportextension possible, adding a single field to the dataset of the standard invoice report.

https://youtu.be/HxixMUEqEmE

In this video, Erik walks through one of the most exciting features introduced in Business Central version 18 (2021 Wave 1): Report Extensions. This feature allows developers to add fields to standard reports without copying the entire report object from the base application. Erik demonstrates the process by adding a new field to the Standard Sales Invoice report (1306) using a report extension object, then updating the Word layout to include the new field.

The Problem: Customizing Standard Reports Before Report Extensions

Before version 18, if you wanted to add a field to a standard report in Business Central, the process was painful:

  1. Extract the source code of the report from the base application
  2. Make a full copy of the report object
  3. Modify the copy to add your field
  4. Use the report substitution event to redirect the system to use your custom report instead of the built-in one

This was tedious, error-prone, and created maintenance headaches whenever Microsoft updated the original report. With report extensions, that entire process is no longer necessary.

Setting Up the Project

Erik starts with a fresh AL extension project in Visual Studio Code. The key configuration in the app.json file is the runtime property. Report extensions require at least runtime 7.0, which corresponds to Business Central version 18 (you add 11 to the runtime version to get the Business Central version number).

{
  "id": "001fcd7c-3e4a-4cc2-a669-8be9e7ee26e3",
  "name": "ReportExtensions",
  "publisher": "Default publisher",
  "version": "1.0.0.0",
  "brief": "",
  "description": "",
  "privacyStatement": "",
  "EULA": "",
  "help": "",
  "url": "",
  "logo": "",
  "dependencies": [],
  "screenshots": [],
  "platform": "1.0.0.0",
  "application": "22.0.0.0",
  "idRanges": [
    {
      "from": 50100,
      "to": 50149
    }
  ],
  "resourceExposurePolicy": {
    "allowDebugging": true,
    "allowDownloadingSource": true,
    "includeSourceInSymbolFile": true
  },
  "runtime": "11.0",
  "features": [
    "NoImplicitWith"
  ]
}

Creating the Report Extension

Erik creates a new file called report.al and starts building the report extension object. The syntax is very similar to page extensions and table extensions that AL developers are already familiar with.

Identifying the Correct Report

A useful tip Erik shares: after typing the report name you want to extend, place your cursor on the name and press F12 (Go to Definition). This opens the source for that report object, allowing you to verify you’re extending the correct one. Erik notes this is a classic mistake — thinking you’re editing one report when it’s actually another.

The Report Extension Structure

Inside a report extension, you have several capabilities:

  • Change the layout — you can supply a new layout to replace the default one
  • Modify the dataset — add columns to existing data items

Within the dataset, you have familiar modification keywords:

  • add — add to a specific section
  • addafter — add after a specific column
  • addbefore — add before a specific column
  • addfirst — add as the first column
  • addlast — add as the last column
  • modify — modify an existing column

Each of these requires you to select an anchor — the data item section you’re targeting. For report 1306, the available anchors include Header, Line, Totals, and several others.

Writing the Code

Erik chooses to add a field to the Header section. Since the Header data item is connected to the Sales Invoice Header table, IntelliSense automatically presents all available fields from that table. He selects the "Transaction Type" field — a field he knows isn’t already on the report, making it easy to verify.

reportextension 50100 "My Invoice" extends "Standard Sales - Invoice"
{
    dataset
    {
        add(Header)
        {
            column(TransactionType; "Transaction Type")
            {
            }
        }
    }
}

That’s the entire report extension. The column definition simply makes the "Transaction Type" field available in the report’s dataset.

Deploying and Updating the Layout

After pressing F5 to deploy the extension to the server, Erik walks through the process of getting the new field into the Word layout:

  1. Navigate to Custom Report Layouts in Business Central
  2. Find the layout for report 1306
  3. Click Update Layout — this is critical because the dataset has changed and the layout needs to be refreshed to recognize the new field
  4. Export the updated layout as a Word document

Working with the Word Layout

To add the field to the Word layout, you need the Developer ribbon enabled in Microsoft Word. If it’s not visible:

  • Right-click the ribbon and select Customize the Ribbon
  • Check the Developer option to enable it

Once the Developer ribbon is active:

  1. Open the XML Mapping Pane from the Developer ribbon
  2. Find the Business Central XML namespace for report 1306 (urn:microsoft-dynamics-nav/reports/StandardSalesInvoice/1306)
  3. Expand the Header section
  4. Locate the new TransactionType field
  5. Place your cursor where you want the field in the document
  6. Right-click the field and select Insert Content Control → Plain Text

After inserting the field, save the Word document and import it back into Business Central via the Custom Report Layouts page.

The Key Takeaway

The entire process — from creating the report extension to seeing the field available in the Word layout — took less than 11 minutes. Here’s what was accomplished:

  1. Created a report extension object targeting report 1306
  2. Added a single column to the Header data item in the dataset
  3. Deployed the extension
  4. Updated the custom layout to pick up the dataset change
  5. Inserted the new field into the Word layout

Compare this to the old approach of copying the entire report, modifying it, and wiring up substitution events. Report extensions are a massive improvement for maintainability and simplicity.

Conclusion

Report extensions in AL bring the same extensibility model that developers have been using for pages and tables directly to reports. For the common scenario of adding a field to a standard report, the process is now remarkably straightforward: define a report extension, add your column to the appropriate data item, deploy, and update the layout. This feature eliminates one of the most cumbersome customization workflows in Business Central development and opens the door for cleaner, more upgrade-safe report modifications.

Picture of hougaard

hougaard