{"title":"Declare report layouts in AL","url":"https://jonas-paprotka.de/docs/dev-itpro/developer/devenv-report-layout-declaration/","by":"JOP-AL","license":"Copyright (c) Microsoft Corporation. CC BY 4.0, https://creativecommons.org/licenses/by/4.0/; code samples MIT. From https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-report-layout-declaration, MicrosoftDocs/dynamics365smb-devitpro-pb at 828b6ee (2026-11-19). Changed: includes filled in, links to this site, and for agents shortened without dropping a fact.","credit":"Microsoft Corporation, CC BY 4.0","origin":"https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-report-layout-declaration","source":{"name":"Business Central developer and IT pro docs","repo":"https://github.com/MicrosoftDocs/dynamics365smb-devitpro-pb","commit":"828b6ee72fcd75755627cd6011f3d20899217ab2","date":"2026-11-19"},"checked":"2026-11-19","description":"Learn how to declare report layouts in AL, use portable layout file paths, and create Word layouts with subtypes for header/footer and theme parts.","date":"2026-09-03","meta":{"topic":"how-to"},"outline":[{"level":1,"title":"Declare report layouts in AL","slug":"declare-report-layouts-in-al","at":0,"chars":10094},{"level":2,"title":"Use portable layout file paths","slug":"use-portable-layout-file-paths","at":1292,"chars":720},{"level":2,"title":"Create Word layouts for the Word Add-in","slug":"create-word-layouts-for-the-word-add-in","at":2012,"chars":754},{"level":2,"title":"Define layouts in the rendering section","slug":"define-layouts-in-the-rendering-section","at":2766,"chars":5315},{"level":3,"title":"Layout declaration in AL","slug":"layout-declaration-in-al","at":2882,"chars":1282},{"level":3,"title":"Subtype property for Word layouts","slug":"subtype-property-for-word-layouts","at":4164,"chars":2443},{"level":4,"title":"Example","slug":"example","at":5487,"chars":1120},{"level":3,"title":"Default header/footer and theme parts for composite Word layouts","slug":"default-headerfooter-and-theme-parts-for-composite-word-layouts","at":6607,"chars":1474},{"level":2,"title":"Compare legacy and rendering layout declarations","slug":"compare-legacy-and-rendering-layout-declarations","at":8081,"chars":1460},{"level":3,"title":"Sample code for the legacy layout declaration","slug":"sample-code-for-the-legacy-layout-declaration","at":8133,"chars":522},{"level":3,"title":"Sample code for the new layout declaration","slug":"sample-code-for-the-new-layout-declaration","at":8655,"chars":886},{"level":2,"title":"Related information","slug":"related-information","at":9541,"chars":553}],"text":"# Declare report layouts in AL\n> APPLIES TO: Business Central 2022 release wave 1 and later\nWhen you create a new report, complete two main tasks. First, define the report dataset of data items and columns. Then, design the report layout. Use the devenv-report-object and Report Extension Object<devenv-report-ext-object> to define reports in AL. When you define the layout section of a report, you have two options.\n1. In versions prior to 2022 release wave 1, layout definitions support the use of one RDL layout and one Microsoft Word layout per AL object. You then specify which report layout type is the default. This article refers to this syntax as the legacy layout.\n2. From 2022 release wave 1, the rendering section within the AL object allows you to specify multiple named layouts in the object and you specify the default layout by name and not by type.\n> NOTE\n> The rendering syntax is the recommended syntax to use.\nThe development environment contains a code action that can convert the legacy layout definition into the new rendering section for easy update during application update. To use this code action, you must enable code actions in Visual Studio Code. Learn more about enabling code actions in AL Language Extension Configuration<devenv-al-extension-configuration>.\n## Use portable layout file paths\n> APPLIES TO: Business Central 2026 release wave 2 and later\nStarting with runtime 18.0, the RDLCLayout, WordLayout, ExcelLayout, LayoutFile, and DefinitionFile properties accept both `/` and `\\` as directory separators on all operating systems. DefinitionFile specifies an analysis view file. The other properties specify report layout files.\nThe same AL source therefore compiles on Windows and Linux. You don't need to change path separators for each operating system. The compiler doesn't report an AL0363<diagnostics/diagnostic-al363> for an incompatible directory separator. The AL0363 diagnostic ID remains reserved to preserve backward compatibility for suppression directives.\n## Create Word layouts for the Word Add-in\n> APPLIES TO: Business Central 2026 release wave 2 and later\nStarting with runtime 18.0, the compiler always includes the extended custom XML parts that make Word report layouts compatible with the Word Add-in. You don't need the WordAddInCompatibleLayouts compiler feature flag. Treat this flag as deprecated when you target runtime 18.0 or later.\nThe custom XML parts also include a CompanyMetadata element inside the BCReportInformation element. Composite Word layouts have `Subtype = Body`. They use the CompanyMetadata element to resolve their header/footer and theme parts when the layout renders. You don't need to set or read this element directly. The compiler and the Word Add-in maintain it for you.\n## Define layouts in the rendering section\nThe rendering section consists of one or more named layout declarations.\n### Layout declaration in AL\nWhen you declare a layout in AL, you must include the properties properties/devenv-type-property and properties/devenv-layoutfile-property. The properties properties/devenv-caption-property and properties/devenv-summary-property are optional, but recommended. The application shows the translated caption and summaries to the end-user, with fallback to the layout name if the caption is undefined. To learn more about defining multiple report layouts, see Defining Multiple Report Layouts<devenv-multiple-report-layouts>.\nThe properties/devenv-mimetype-property property is only supported if the Type is declared as Custom, and is a free-text string.\nSet it to follow the standard naming for MIME types or set it to a path equivalent to: `Application/Report/<ExtensionName>` where `<ExtensionName>` is a short-form that identifies the owning extension. When users copy custom-render layouts for customization, the MIME type follows the layout and can be verified during selection.\nThe syntax is as follows:\n```al\nlayout(name)\n{\n    Type = RDLC | Word | Excel | Custom;\n    Subtype = Default | Body | HeaderFooter | Theme;  // Word layouts only\n    LayoutFile = <file name>;\n    Caption = <string>;\n    Summary = <string>;\n    MimeType = <string>;\n}\n```\n### Subtype property for Word layouts\n> APPLIES TO: Business Central 2026 release wave 2 and later\nThe Subtype property is available on Word layouts and specifies the role of the layout file within a report. The following values are supported:\nValue|Description\nDefault|A standalone Word document layout (`.docx`). This value is used when Subtype isn't specified.\nBody|A Word document layout (`.docx`) that supports composite rendering. A Body layout can use separate header and footer and theme parts set by the report's DefaultHeaderFooterPart and DefaultThemePart properties.\nHeaderFooter|A Word document (`.docx`) that provides header and footer content for a Body layout.\nTheme|A Word template (`.dotx`) that provides theme formatting, such as fonts, colors, and styles, for a Body layout.\n> NOTE\n> Layouts with `Subtype = Theme` must use a template file with the `.dotx` file extension. Layouts with `Subtype = Default`, Body, or HeaderFooter use the `.docx` file extension.\nUse the properties/devenv-defaultheaderfooterpart-property and properties/devenv-defaultthemepart-property report properties to reference layouts declared in the same rendering section. DefaultHeaderFooterPart must reference a layout that has `Subtype = HeaderFooter`, and DefaultThemePart must reference a layout that has `Subtype = Theme`.\n#### Example\nThe following example defines a standalone Default layout and a composite Body layout that references separate header and footer and theme parts.\n```al\nreport 50000 \"Report With Parts\"\n{\n    DefaultRenderingLayout = StandaloneLayout;\n    DefaultHeaderFooterPart = StandardHeaderFooter;\n    DefaultThemePart = StandardTheme;\n\n    dataset\n    {\n    }\n\n    requestpage\n    {\n    }\n\n    rendering\n    {\n        layout(StandaloneLayout)\n        {\n            Type = Word;\n            Subtype = Default;\n            LayoutFile = 'Reports\\Layouts\\StandaloneLayout.docx';\n        }\n        layout(CompositeBody)\n        {\n            Type = Word;\n            Subtype = Body;\n            LayoutFile = 'Reports\\Layouts\\CompositeBody.docx';\n        }\n        layout(StandardHeaderFooter)\n        {\n            Type = Word;\n            Subtype = HeaderFooter;\n            LayoutFile = 'Reports\\Layouts\\StandardHeaderFooter.docx';\n        }\n        layout(StandardTheme)\n        {\n            Type = Word;\n            Subtype = Theme;\n            LayoutFile = 'Reports\\Layouts\\StandardTheme.dotx';\n        }\n    }\n}\n```\n### Default header/footer and theme parts for composite Word layouts\n> APPLIES TO: Business Central 2026 release wave 2 and later\nThe DefaultHeaderFooterPart and DefaultThemePart report properties let a report specify the default header and footer and theme parts used by its Body Word layouts. Following the same pattern as properties/devenv-defaultrenderinglayout-property, each property references the name of a layout declared in the report's rendering section. DefaultHeaderFooterPart must reference a layout that has `Subtype = HeaderFooter`, and DefaultThemePart must reference a layout that has `Subtype = Theme`. Referencing a layout with a different subtype results in a compiler error.\n```al\nreport 50000 \"Report With Parts\"\n{\n    DefaultRenderingLayout = DefaultPart;\n    DefaultHeaderFooterPart = StandardHeaderFooter;\n    DefaultThemePart = StandardTheme;\n\n    dataset\n    {\n    }\n\n    requestpage\n    {\n    }\n\n    rendering\n    {\n        layout(DefaultPart)\n        {\n            Type = Word;\n            Subtype = Body;\n            LayoutFile = 'Reports\\Layouts\\DefaultPart.docx';\n        }\n        layout(StandardHeaderFooter)\n        {\n            Type = Word;\n            Subtype = HeaderFooter;\n            LayoutFile = 'Reports\\Layouts\\StandardHeaderFooter.docx';\n        }\n        layout(StandardTheme)\n        {\n            Type = Word;\n            Subtype = Theme;\n            LayoutFile = 'Reports\\Layouts\\StandardTheme.dotx';\n        }\n    }\n}\n```\n## Compare legacy and rendering layout declarations\n### Sample code for the legacy layout declaration\nThe legacy layout declaration consists of three report properties as shown in the sample below. The report must specify at least one of the supported formats unless it's a processing only report. The sample defines both an RDLC and a Microsoft Word report layout and sets the default type to Word.\n```al\nreport 50000 \"Standard Report Layout\"\n{\n    RDLCLayout = './StandardReportLayout.rdlc';\n    WordLayout = './StandardReportLayout.docx';\n    DefaultLayout = Word;\n}\n```\n### Sample code for the new layout declaration\nThe new layout declaration moves the layouts to a rendering section, which you must declare just after the request page section in the report object. Specify the default layout by name by using the DefaultRenderingLayout property.\n```al\nreport 50000 \"Standard Report Layout\"\n{\n    DefaultRenderingLayout = RDLCLayout;\n    ...\n    rendering\n    {\n        layout(RDLCLayout)\n        {\n            Type = RDLC;\n            LayoutFile = './StandardReportLayout.rdlc';\n            Caption = 'Standard Report Layout (RDL)';\n            Summary = 'Legacy layout';\n        }\n        layout(WordLayout)\n        {\n            Type = Word;\n            LayoutFile = './StandardReportLayout.docx';\n            Caption = 'Standard Report Layout (Word)';\n            Summary = 'Standard layout suitable for user facing documents.';\n        }\n    }\n}\n```\n## Related information\ndevenv-multiple-report-layouts\nDefault rendering layout property<properties/devenv-defaultrenderinglayout-property>\nRDLC layout property<properties/devenv-rdlclayout-property>\nWord layout property<properties/devenv-wordlayout-property>\nDefault layout<properties/devenv-defaultlayout-property>\nReport properties<properties/devenv-report-property-overview>\nproperties/devenv-defaultheaderfooterpart-property\nproperties/devenv-defaultthemepart-property\nproperties/devenv-headerfooterpart-property\nproperties/devenv-themepart-property"}