{"title":"OnCustomDocumentMergerEx event","url":"https://jonas-paprotka.de/docs/dev-itpro/developer/devenv-oncustomdocumentmergerex-event/","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-oncustomdocumentmergerex-event, 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-oncustomdocumentmergerex-event","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 OnCustomDocumentMergerEx Event in Business Central.","date":"2023-12-20","meta":{"topic":"article"},"outline":[{"level":2,"title":"Usage","slug":"usage","at":246,"chars":329},{"level":2,"title":"Publisher","slug":"publisher","at":575,"chars":43},{"level":2,"title":"Raised","slug":"raised","at":618,"chars":110},{"level":2,"title":"Syntax","slug":"syntax","at":728,"chars":317},{"level":2,"title":"Parameters","slug":"parameters","at":1045,"chars":1796},{"level":3,"title":"ObjectID","slug":"objectid","at":1059,"chars":97},{"level":3,"title":"ReportAction","slug":"reportaction","at":1156,"chars":629},{"level":3,"title":"ObjectPayload","slug":"objectpayload","at":1785,"chars":147},{"level":3,"title":"XmlData","slug":"xmldata","at":1932,"chars":203},{"level":3,"title":"LayoutData","slug":"layoutdata","at":2135,"chars":274},{"level":3,"title":"Success","slug":"success","at":2409,"chars":432},{"level":2,"title":"Report payload","slug":"report-payload","at":2841,"chars":4858},{"level":3,"title":"Attributes","slug":"attributes","at":4244,"chars":3455},{"level":4,"title":"objectname","slug":"objectname","at":4259,"chars":50},{"level":4,"title":"objectid","slug":"objectid-1","at":4309,"chars":46},{"level":4,"title":"documenttype","slug":"documenttype","at":4355,"chars":217},{"level":4,"title":"invokedby","slug":"invokedby","at":4572,"chars":74},{"level":4,"title":"invokeddatetime","slug":"invokeddatetime","at":4646,"chars":184},{"level":4,"title":"companyname","slug":"companyname","at":4830,"chars":57},{"level":4,"title":"version","slug":"version","at":4887,"chars":120},{"level":4,"title":"duplex","slug":"duplex","at":5007,"chars":175},{"level":4,"title":"color","slug":"color","at":5182,"chars":161},{"level":4,"title":"defaultcopies","slug":"defaultcopies","at":5343,"chars":160},{"level":4,"title":"filterviews","slug":"filterviews","at":5503,"chars":64},{"level":4,"title":"name","slug":"name","at":5567,"chars":75},{"level":4,"title":"tableid","slug":"tableid","at":5642,"chars":57},{"level":4,"title":"view","slug":"view","at":5699,"chars":42},{"level":4,"title":"papertray","slug":"papertray","at":5741,"chars":123},{"level":4,"title":"papersourcekind","slug":"papersourcekind","at":5864,"chars":190},{"level":4,"title":"paperkind","slug":"paperkind","at":6054,"chars":145},{"level":4,"title":"landscape","slug":"landscape","at":6199,"chars":119},{"level":4,"title":"units","slug":"units","at":6318,"chars":279},{"level":4,"title":"height","slug":"height","at":6597,"chars":105},{"level":4,"title":"width","slug":"width","at":6702,"chars":103},{"level":4,"title":"intent","slug":"intent","at":6805,"chars":169},{"level":4,"title":"layoutmodel","slug":"layoutmodel","at":6974,"chars":157},{"level":4,"title":"layoutname","slug":"layoutname","at":7131,"chars":77},{"level":4,"title":"layoutmimetype","slug":"layoutmimetype","at":7208,"chars":210},{"level":4,"title":"layoutapplicationid","slug":"layoutapplicationid","at":7418,"chars":96},{"level":4,"title":"reportrunid","slug":"reportrunid","at":7514,"chars":185},{"level":2,"title":"Sample code","slug":"sample-code","at":7699,"chars":4360},{"level":2,"title":"Related information","slug":"related-information","at":12059,"chars":413}],"text":"This article describes the syntax of the OnCustomDocumentMergerEx event, which will enable use of custom renders given a dataset and a layout. The layout must be specified as a Custom Layout in the rendering section within the report definition.\n## Usage\nUse the OnCustomDocumentMergerEx event to specify what happens when the user has specified a custom report layout type that is to be rendered into an artifact in application code. For more information about subscribing to this event, see Developing Report Custom Render Extensions Overview<devenv-report-custom-render>.\n## Publisher\nCodeunit 44 ReportManagement.\n## Raised\nWhen a user runs a report that uses a custom layout format handled by application code (extension).\n## Syntax\n```al\n [IntegrationEvent(false, false)]\nlocal 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```\n## Parameters\n### ObjectID\nType: methods-auto/integer/integer-data-type\nThe ID of the report object to be run.\n### ReportAction\nType: [Option]\nSpecifies the action to take in the custom document merge process.\nValid values include:\n SaveAsPdf Generates a PDF document in the target stream.\n SaveAsWord Generates a Microsoft Word document in the target stream.\n SaveAsExcel Generates a Microsoft Excel document in the target stream.\n SaveAsHtml Generates an HTML document in the target stream.\n Preview Generates a PDF document in the target stream, which the platform downloads to the client for preview.\n Print Generates a PDF document in the target stream, which the platform prints using the printer specified for the present report ID.\n### ObjectPayload\nType: methods-auto/jsonobject/jsonobject-data-type\nInstance of the report payload. See Report payload structure<#reportpayload>.\n### XmlData\nType: methods-auto/instream/instream-data-type\nA stream object that contains the XML dataset generated by the platform runtime. This stream contains the input data for the rendering process.\n### LayoutData\nType: methods-auto/instream/instream-data-type\nA stream object that contains the report layout to be used in the rendering process. The platform provides this data from the standard report layout selection logic and it contains the currently selected layout.\n### Success\nType: methods-auto/boolean/boolean-data-type\nSpecifies whether the extension handled the merge action successfully.\n> NOTE\n> The platform will handle further processing of the result stream and the extension code must return the rendered artifact in the target stream. The platform will handle:\n > Saving to a specified file in save-as scenarios\n > Saving to a given stream\n > Download to the client\n > Print or preview\n## Report payload\nThe report payload contains metadata for the report object and a list of attributes that identifies that current invocation. The payload consists of several attributes and has the following structure.\n```json\n{\n    \"filterviews\":\n    [\n        {\"name\":\"Header\",\"tableid\":112,\"view\":\"VERSION(1) SORTING(Field3) WHERE(Field3=1(103027))\"},\n        {\"name\":\"Line\",\"tableid\":113,\"view\":\"VERSION(1) SORTING(Field3,Field4) WHERE(Field4=1(0..10000))\"},\n        {\"name\":\"ShipmentLine\",\"tableid\":7190,\"view\":\"VERSION(1) SORTING(Field1,Field2,Field3) WHERE(Field2=1(10000))\"}\n    ],\n    \"version\":1,\n    \"objectname\":\"Standard Sales - Invoice\",\n    \"objectid\":1306,\n    \"documenttype\":\"application/pdf\",\n    \"invokedby\":\"00000000-0000-0000-0000-000000000001\",\n    \"invokeddatetime\":\"2020-01-17T15:33:52.48+01:00\",\n    \"companyname\":\"CRONUS International Ltd.\",\n    \"printername\":\"My Printer\",\n    \"duplex\":false,\n    \"color\":false,\n    \"defaultcopies\":1,\n    \"papertray\":\n    {\n        \"papersourcekind\":257,\n        \"paperkind\":0,\n        \"landscape\":false,\n        \"units\":0,\n        \"height\":1268,\n        \"width\":929\n    },\n    \"intent\":\"Print\",\n    \"layoutmodel\": \"Rdlc\",\n    \"layoutname\": \"RDLCLayout\",\n    \"layoutmimetype\": \"Application/ReportLayout/Rdlc\",\n    \"layoutapplicationid\": \"00001111-aaaa-2222-bbbb-3333cccc4444\",\n    \"reportrunid\": \"6a3742c1-65ef-44a6-af58-3ef4a902932b\"\n}\n\n```\n### Attributes\n#### objectname\nSpecifies the name of the object.\n#### objectid\nSpecifies the ID of the object.\n#### documenttype\nSpecifies the MIME type of the document. Currently only `application/pdf` is supported for printing, other intents can have types specific to the report layout model and selected output target type.\n#### invokedby\nSpecifies the ID of the user who invoked the print action.\n#### invokeddatetime\nSpecifies the date and time that the print action was invoked, for example, `2019-10-22T22:25:54.338+02:00`. The value is the date and time on the client machine.\n#### companyname\nSpecifies the Business Central company.\n#### version\nSpecifies the version of the report payload. Currently, the only supported version for the payload is `1`.\n#### duplex\nSpecifies whether to use duplex (2-sided) printing. true specifies duplex printing; otherwise false.\n> NOTE\n> duplex is currently not used and ignored at runtime.\n#### color\nSpecifies whether color printing is set. true specifies color printing; otherwise false.\n> NOTE\n> color is currently not used and ignored at runtime.\n#### defaultcopies\nSpecifies the number of copies to print by default. The default is `1`.\n> NOTE\n> defaultcopies is currently not used and ignored at runtime.\n#### filterviews\nSpecifies views that are used on the document.\n#### name\nSpecifies the name of data item that the filter view applies to.\n#### tableid\nSpecifies the ID of the table for the view.\n#### view\nSpecifies the name of the view.\n#### papertray\nSpecifies the paper tray settings from the printer payload<devenv-onaftersetupprinters-event#printpayload>.\n#### papersourcekind\nSpecifies a standard paper source for the paper tray. The value can be either the text representation (such as AutomaticFeed) or the corresponding number (such as `7`).\n#### paperkind\nSpecifies the paper size. The value can be either the text representation (such as A4) or the corresponding number (such as `9`).\n#### landscape\nSpecifies whether landscape orientation is used. true specifies landscape orientation; otherwise false.\n#### units\nSpecifies the units of measurement for values in height and width attributes. Valid values include:\n HI for hundredths of an inch (default value).\n TI for thousandths of an inch.\n IN for inches.\n CM for centimeters.\n MM for millimeters.\n PC for picas.\n PT for points.\n#### height\nSpecifies the height of the paper. The values include positive integers up to 2,147,483,647.\n#### width\nSpecifies the width of the paper. The values include positive integers up to 2,147,483,647.\n#### intent\nSpecifies the intent of the current report invocation, which can be one of the following values.\n None\n Print\n Preview\n Save\n Schedule\n Download\n Parameters\n#### layoutmodel\nSpecifies the layout model selected for the current report invocation, which can be one of the following values.\n Rdlc\n Word\n Excel\n Custom\n#### layoutname\nSpecifies the layout name for the currently selected layout.\n#### layoutmimetype\nSpecifies the layout mimetype for the currently selected layout. The built-in layout types are:\n Application/ReportLayout/Rdlc\n Application/ReportLayout/Word\n Application/ReportLayout/Excel\n#### layoutapplicationid\nSpecifies the ID of the application that provides the selected layout.\n#### reportrunid\nSpecifies a unique ID of type Guid that identifies the current report invocation. This value can be used to correlate calls to report event that support json payloads.\n## Sample code\nThe simplest possible custom document render can be implemented as shown in the following sample, which will use 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        SharedXmlData: InStream;\n        SharedLayoutData: InStream;\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        // Setup shared streams\n\n        // Empty stream, no actions possible on the stream so return immediately\n        if XmlData.Length < 1 then\n            exit;\n\n        // Use a shared stream and reset the read pointer to beginning of stream\n        SharedXmlData := XmlData;\n        if SharedXmlData.Position > 1 then\n            SharedXmlData.ResetPosition();\n\n        SharedLayoutData := LayoutData;\n        if SharedLayoutData.Position > 1 then\n            SharedLayoutData.ResetPosition();\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 string below have to be remapped to a standard file extension\n        // 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(SharedLayoutData, SharedXmlData, 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(SharedLayoutData, SharedXmlData, 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(SharedLayoutData, SharedXmlData, 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## Related information\nWorking With and Troubleshooting Payloads<devenv-reports-troubleshoot-printing>\nDeveloping Report Custom Render Extensions Overview<devenv-report-custom-render>\nDeveloping Printer Extensions Overview<devenv-reports-printing>\nCreating a Printer Extension<devenv-reports-create-printer-extension>\ndevenv-events-in-al\ndevenv-publishing-events\ndevenv-raising-events\ndevenv-subscribing-to-events"}