{"title":"Developing a custom report render","url":"https://jonas-paprotka.de/docs/dev-itpro/developer/devenv-report-custom-render/","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-custom-render, 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-custom-render","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":"Describe the custom report render logic and how to implement it in AL code.","date":"2026-03-03","meta":{"topic":"concept-article"},"outline":[{"level":1,"title":"Developing a custom report render","slug":"developing-a-custom-report-render","at":0,"chars":6392},{"level":2,"title":"History and context","slug":"history-and-context","at":501,"chars":596},{"level":2,"title":"Layout declaration for a custom render","slug":"layout-declaration-for-a-custom-render","at":1097,"chars":454},{"level":2,"title":"Sample AL code","slug":"sample-al-code","at":1551,"chars":3734},{"level":2,"title":"File extension and MIME type","slug":"file-extension-and-mime-type","at":5285,"chars":871},{"level":2,"title":"Related information","slug":"related-information","at":6156,"chars":236}],"text":"# Developing a custom report render\n> APPLIES TO: Business Central 2022 release wave 1 and later\nThis article describes the concept of a custom report render. The custom report render manages the rendering of a generated report dataset with a layout type specified by an extension. The actual rendering takes place in the application by using the OnCustomDocumentMergerEx event provided by the ReportManagement codeunit. The layout must be specified in the rendering section in the report definition.\n## History and context\nThe custom render feature is a substitute for the business events that were used in the OnDocumentMerge event provided by the DocumentManagement codeunit for rendering Word documents in the application. When using the custom render logic, the report can support multiple layouts and the event code won't have dependencies to standard Word layout processing in the platform or application. The layout files that are provided in the extension are imported without any further processing, whereas the Word documents are aligned with the platform requirements for that format.\n## Layout declaration for a custom render\n```al\nreport 50000 \"Standard Report Layout\"\n{\n    DefaultRenderingLayout = CustomLayout;\n    ...\n    rendering\n    {\n        layout(CustomLayout)\n        {\n            Type = Custom;\n            LayoutFile = './StandardReportLayout.custom';\n            Caption = 'First custom layout';\n            Summary = 'First custom layout summary';\n            MimeType = 'ReportLayout/MyExtension';\n        }\n    }\n}\n```\n## Sample AL code\nThe simplest possible custom document render can be implemented as in the following sample. The example uses the existing application logic to render XML datasets into Microsoft Word or PDF documents using a given template (Word template).\n```al\n    [EventSubscriber(ObjectType::Codeunit, Codeunit::ReportManagement, 'OnCustomDocumentMergerEx', '', true, true)]\n    local procedure OnCustomDocumentMergerEx(ObjectID: Integer; ReportAction: Option SaveAsPdf,SaveAsWord,SaveAsExcel,Preview,Print,SaveAsHtml; ObjectPayload: JsonObject; XmlData: InStream; LayoutData: InStream; var DocumentStream: OutStream; var IsHandled: Boolean)\n    var\n        DocumentReportMgt: Codeunit \"Document Report Mgt.\";\n        TempBlob: Codeunit \"Temp Blob\";\n        DataInStream: InStream;\n        DataOutStream: OutStream;\n        ObjectName: JsonToken;\n        DocumentTypeParts: List of [Text];\n        DocumentType: JsonToken;\n        Extension: Text;\n        Token: JsonToken;\n        MimeType: Text;\n        LayoutName: Text;\n        LayoutModel: Text;\n        JsonText: Text;\n        JsonFile: File;\n    begin\n        if IsHandled then\n            exit;\n\n        Init();\n\n        // Sample code to persist the json object to disk\n        ObjectPayload.WriteTo(JsonText);\n        JsonFile.TextMode := true;\n        JsonFile.Create(TempFolderPath + 'OnCustomDocumentMergerEx.json', TextEncoding::UTF8);\n        JsonFile.Write(JsonText);\n        JsonFile.Close();\n\n        // Get report options from the json object\n        ObjectPayload.Get('objectname', ObjectName);\n        ObjectPayload.Get('documenttype', DocumentType);\n        ObjectPayload.Get('layoutmimetype', Token);\n        MimeType := Token.AsValue().AsText();\n\n        ObjectPayload.Get('layoutname', Token);\n        LayoutName := Token.AsValue().AsText();\n\n        ObjectPayload.Get('layoutmodel', Token);\n        LayoutModel := Token.AsValue().AsText();\n\n        DocumentTypeParts := DocumentType.AsValue().AsText().Split('/');\n\n        // Notice that the Extension below have to be remapped to a standard file extension based on the document mimetype.\n        Extension := DocumentTypeParts.Get(DocumentTypeParts.Count);\n\n        TempBlob.CreateOutStream(DataOutStream);\n\n        // The\n        case ReportAction of\n            ReportAction::SaveAsPdf, ReportAction::Preview, ReportAction::Print:\n                begin\n                    if not DocumentReportMgt.TryXmlMergeWordDocument(LayoutData, XmlData, DataOutStream) then\n                        error('Unable to handle custom document merge');\n                    DocumentReportMgt.ConvertWordToPdf(TempBlob, ObjectID);\n                    TempBlob.CreateInStream(DataInStream);\n                    CopyStream(DocumentStream, DataInStream);\n                    IsHandled := true;\n                end;\n            ReportAction::SaveAsHtml:\n                begin\n                    if not DocumentReportMgt.TryXmlMergeWordDocument(LayoutData, XmlData, DataOutStream) then\n                        error('Unable to handle custom document merge');\n                    DocumentReportMgt.ConvertWordToHtml(TempBlob);\n                    TempBlob.CreateInStream(DataInStream);\n                    CopyStream(DocumentStream, DataInStream);\n                    IsHandled := true;\n                end;\n            ReportAction::SaveAsWord:\n                begin\n                    if not DocumentReportMgt.TryXmlMergeWordDocument(LayoutData, XmlData, DocumentStream) then\n                        error('Unable to handle custom document merge');\n                    IsHandled := true;\n                end;\n            else\n                error('Unsupported report action %0', ReportAction);\n        end;\n    end;\n```\n## File extension and MIME type\nWhen you export a layout or open/edit it through OneDrive in Business Central, the file extension is resolved from the layout metadata, not from report output actions.\n The export file name is built from the layout name and the resolved file extension.\n The layout's stored MIME type is checked first. If the MIME type contains `reportlayout/`, that value is used to derive the extension.\n If no usable MIME type is available, it falls back to layout format defaults: Word = docx, RDLC = rdl, Excel = xlsx.\n For custom layouts, there's no default fallback extension, so the MIME type must provide the extension if you want a deterministic file name/extension when exporting or editing the layout.\nFor this reason, when defining custom layouts, make sure the MIME type is aligned with the intended file extension used by export/edit flows.\n## Related information\nWorking with and troubleshooting payloads<devenv-reports-troubleshoot-printing>\ndevenv-oncustomdocumentmergerex-event\ndevenv-events-in-al\ndevenv-publishing-events\ndevenv-raising-events\ndevenv-subscribing-to-events"}