Creating a Word layout report

When you create a new report, there are two main tasks. First, you define the report dataset of data items and columns. Then, you design the report layout. These steps show how to create a report based on a Word layout. Learn more about the report object in Report object and Report extension object.

How to create a new Word layout from Visual Studio Code

If you want to create a new Word layout from Visual Studio Code, do the following steps:

1. Open the report object in Visual Studio Code.
2. Navigate to the rendering section (or create one).
3. Add a new layout entry of type Word and set the LayoutFile property to a value that is a valid name for a Word file, such as 'MyWordReport.docx'.
4. Now build the extension (Ctrl+Shift+B) to generate the Word file that includes the Custom XML part.

Using Word to author your report layout

Microsoft Word offers various features to help you format and layout your document reports. You can customize the margins, page orientation, and line spacing to suit your needs. You can define advanced header/footers, utilize sections to change the layout style in different places of the report layout, and utilize fonts to get just the typography that matches your organization.

Learn more in Using Word to author your report layout.

Design guidelines for a report dataset designed for Word layouts

With Word layouts, Word is used as the editor for the report. The person designing the layout interacts with the labels, data items, and fields from the dataset from the data picker in the Word add-in (or using the legacy XML Mapping Pane). If you want users to be able to change the layout, consider using friendly names for labels, data items, and fields.

Using system dataitems

APPLIES TO: Business Central 2025 release wave 1 (v26) and later.

Similar to Excel layouts, you can access report and request metadata in a Word layout. As a layout designer, this information helps you understand a report dataset better. You can also add the metadata as controls on the Word layouts, making it available to users who run the report.

In Word layouts, metadata is available in the XML Mapping pane as columns in two system dataitems: ReportMetadata and ReportRequest.

These two dataitems aren't part of the report dataset but are only present in the Word layout XML.

ReportMetadata

The ReportMetadata dataitem includes metadata columns that provide information from the report object.

ReportRequest

The ReportRequest dataitem includes metadata columns from the report request (the report invocation that created the document).

Report labels in Word layouts

Report labels are used by report layouts as, for example, the heading for a field in a table, the title for a chart, or the title for the report itself.

Report labels defined in the Labels section of the report object and captions included on dataitem columns using the IncludeCaption property are available as in the Labels part of the XML Mapping pane in Word:

Learn more about labels in Report labels.

Formatting data in Word layouts

It's often desirable to format data in a report in a different way than how the same data appears in tables, queries, or pages. For example, if a decimal field in a table has precision of five digits, the same level of precision might not be needed in the report.

Specifically for Word layouts, there's no way to control formatting of data elements in Word. Therefore, you need to do the formatting in the report dataset. Learn more in Formatting field values in report datasets.

How to iterate a Word layout over a data item

When you specify a data item in the WordMergeDataItem property, the Business Central Server iterates over that dataitem and does a "Mail merge" between that data item (and the ones below it) and the Word layout when rendering the report using the Word layout. This way, the Word layout is applied to each element in the specified data item.

Learn more, including an example, in WordMergeDataItem Property.

How to do totals in Word layouts

Compared to the layout types Excel or RDL, it isn't possible to do calculations in a Word layout. If you want to add totals to your report, you need to calculate them in AL variables in the report object and then use a data item based on an Integer table to expose them to the XML Mapping pane in Word.

The following example illustrates how to code totals. The example is based on report 1306 "Standard Sales - Invoice" from the base application.

report 50142 "My Sales Invoice report"
{
  // report properties

  dataset
  {
    // In some dataitem here, vTotalAmount and vTotalVATBaseLCY are calculated in the OnAfterGetRecord trigger

    ...

    dataitem(Totals; "Integer")
    {
      // maybe some dataitem properties here

      column(TotalNetAmount; Format(vTotalAmount, 0, AutoFormat.ResolveAutoFormat("Auto Format"::AmountFormat, Header."Currency Code")))
      {
      }
      column(TotalVATBaseLCY; vTotalVATBaseLCY)
      {
      }
    }
  }

  // layouts defined here
  rendering {}

  // labels defined here
  labels {}

  ...

  protected var
    vTotalVATBaseLCY: Decimal;
    vTotalAmount: Decimal

}

Example: Create a Word layout report

The following example extends the Customer List page with a trigger that runs the report as soon as the Customer List page is opened.

1. Create a new extension to the Customer List page that contains code to run the report and a report object by adding the following lines of code:

   pageextension 50100 MyExtension extends "Customer List"
   {
     trigger OnOpenPage();
     begin
       report.Run(Report::MyWordReport);
     end;
   }
   
   report 50124 MyWordReport
   {
   }
   

2. Add the Customer table as the data item and the Name field as a column to the report by adding the following lines of code to the report. Learn more about defining a dataset in Report Dataset.

   report 50124 MyWordReport
   {
     WordMergeDataItem = Customer; // Set this if you want to iterate the report layout over each customer
     // Maybe also set other report properties
   
     dataset
     {
       dataitem(Customer; Customer)
       {
         column(Name; Name)
         {
         }
       }
     } 
   
     rendering 
     {
       layout(MyWordLayout)
       {
         Type = Word;
         Caption = 'Customer list for print';
         Summary = 'Customer list in Word that is designed for printing.';
         LayoutFile = 'MyWordReport.docx';
       }
     }
   }
   

3. Build the extension (Ctrl+Shift+B) to generate the MyWordReport.docx file.

4. Open the generated report layout file in Word.

5. In Word, edit the layout using the XML Mapping Pane on the Developer tab.

   Note

   If you don't see the Developer tab, go to Options, then Customize Ribbon, and in the Main tabs section, select the Developer check box.

6. In Word in the Custom XML part lookup, locate the report, and then open the layout.

7. Right-click on the Customer table, and in Insert Content Control, select Repeating to add the repeater data item.

8. Right-click on the Name field and in Insert Content Control, select Plain Text to add the column as a text box.

9. Save the report layout when you're done and then close it.

10. Back in Visual Studio Code, select Ctrl+F5 to compile and run the report.

The generated report is displayed in preview mode.

"al.compilationOptions": {
  "generateReportLayout": true
}

Enabling the Microsoft Word rendering engine

APPLIES TO: Business Central versions 20, 21, and 22

An application feature key controls the rendering of Word reports. Enabling the key RenderWordReportsInPlatform in the Feature Management page in Business Central switches the Microsoft Word report rendering to the new platform rendering, which supports multiple layouts and new triggers for Save and Download actions.

The following AL snippet can be used in code to implement rendering differentiation in extensions.

 var
    FeatureKey: Record "Feature Key";
    PlatformRenderingInPlatformTxt: Label 'RenderWordReportsInPlatform', Locked = true;

// code snippet
if (FeatureKey.Get(PlatformRenderingInPlatformTxt) and (FeatureKey.Enabled = FeatureKey.Enabled::"All Users")) then
    // Platform rendering of Word reports, Custom layout types will be handled by the OnCustomDocumentMerger event
    ....
else
    // App rendering - The report type will be treated like a Word file and rendered by the application
    ...

Learn more about feature management in Enabling Upcoming Features Ahead of Time.

Report limit - maximum number of documents that can be merged in report

The Business Central platform has built-in limits to protect the stability of the system from a single report consuming too many resources. For example, there's a limit on the maximum number of documents that can be merged in a report using a Word layout.

Learn more about report limits in Report limits.

Difference between RDL and Word layouts

If you're switching from developing reports with RDL layouts to using Word layouts, you might need to change your mindset on how you develop reports and their layouts. RDL allows you to dynamically change many properties in the layout but it isn't possible in Word. For many logic-related conditions, you do them in the report dataset in AL and then utilize the methods outlined in this article.

For reports where you expect customers to adjust the layout or use themes to change the overall look-and-feel of the document, consider using a Word layout over an RDL layout.

How to create a new Word layout document from scratch

If you need an empty Word document that includes the custom XML part for a report's dataset, you have a few options depending on your Business Central version:

How to update a layout with the latest report dataset definition

APPLIES TO: Business Central 2024 release wave 2 and later.

The Report layouts page in the client, helps you update a layout with the latest report dataset definition.

1. Sign in to Business Central and open the Report layouts page.

2. Select the report in the list and then select Update and Export Layout.

   The updated layout file is downloaded to your computer.

3. Open the updated layout file in Word. Then make changes and save the file.

4. In Business Central, import the updated layout either as a new layout, by using the New action, or as a replacement to the existing layout, by the Replace Layout action.

How to convert an RDL layout to a Word layout

There's no way to directly convert an RDL layout to a Word layout, but if you want to create a new Word layout based on an RDL layout, then do as follows:

1. Create a new blank Word layout. To learn more, go to How to create a new Word layout document from scratch.
2. Get a version of the report RDL layout rendered as a Word document:
   1. From the Report layouts page, find the RDL layout you want to base the new Word layout on.
   2. From the top pane menu, select the Run Report action. This opens the request page for the report.
   3. In the bottom of the request page, select the Send to... button. This opens a Choose file type... modal dialog.
   4. Select Microsoft Word Document and then choose the OK button. This downloads the report rendered as a Word document (where the dataset was merged with the layout and where the Custom XML part isn't present.).
3. Mark all content that you want to base the new layout on from the rendered Word document and copy it to the empty Word layout that you created in step 1.
4. Now it's time to adjust the Word document to make it a real layout:
   1. For each table, keep the header and remove all but one row with values. For the latter row, add a repeater from the XML Mapping pane. For the header row, add labels/captions from the XML Mapping pane.
   2. For each text not in a table, replace the text with the corresponding content control from the XML Mapping pane.
   3. For each image not in the dataset, encapsulate it with a table to control overflow. Consider resizing it.
   4. For each image in the dataset, replace the text with the corresponding content control from the XML Mapping pane.
5. You can test the layout either by launching a new session from Visual Studio Code or directly from the Report layouts page:
   1. For the initial test of the new layout, from the Report layouts page, find the report you want to add the new Word layout to. From the top pane menu, select the New action to upload the layout for the first time.
   2. For subsequent tests of the new layout, from the Report layouts page, find the report you want to add the new Word layout to. From the top pane menu, select the Replace layout action to replace the layout with the latest version.

How to convert an existing document design to a Word layout

In implementation projects, a common specification for document layouts is to design them to match the client’s existing document layouts. There's no way to directly convert a PDF document to a Word layout, but if you want to create a new Word layout based on a PDF document, then do as follows:

1. Get a version of the PDF document as a Word document as follows:

   1. Open Word.
   2. From the File menu, select the Open action and find the PDF document. Select OK. This opens a dialog stating that "Word will now convert your PDF to an editable Word document". Select OK. The resulting Word document might not match the PDF 100%, but it's a start.
   3. If the PDF document is read-only, the resulting Word document is also read-only. In this case, mark all content by selecting Ctrl+a, copy to clipboard, create a new Word document, and paste the content in the new Word document.

2. Follow the step-by-step guide in the section How to convert an RDL layout to a Word layout, skipping the step Get a version of the report RDL layout rendered as a Word document.

How to compare two versions of a Word layout

If you need to compare two versions of a Word layout, then do as follows:

1. Open Word.
2. On the Review menu, select Compare Documents.
3. In the Original document list, select the original document.
4. In the Revised document list, browse to the other version of the document, and then select OK.

Learn more in Compare and merge two versions of a Word document.

Related information

Using hyperlinks in Word layouts
WordMergeDataItem property
Report design overview
Report object
Report extension object
Developing a custom report render
Creating an RDL layout report
Creating an Excel layout report