{"title":"Attach files, append, and protect report PDFs in AL","url":"https://jonas-paprotka.de/docs/dev-itpro/developer/devenv-post-process-report-pdf/","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-post-process-report-pdf, 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-post-process-report-pdf","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 to attach files, append PDFs, and password protect report PDFs in AL. Follow best practices for compliance and secure document handling.","date":"2025-05-26","meta":{"topic":"how-to"},"outline":[{"level":1,"title":"Attach files, append, and protect report PDFs in AL","slug":"attach-files-append-and-protect-report-pdfs-in-al","at":0,"chars":12006},{"level":2,"title":"Overview","slug":"overview","at":173,"chars":764},{"level":2,"title":"How it works","slug":"how-it-works","at":937,"chars":5994},{"level":3,"title":"Report actions that apply output options","slug":"report-actions-that-apply-output-options","at":2004,"chars":315},{"level":3,"title":"Example","slug":"example","at":2319,"chars":4126},{"level":3,"title":"Report rendering payload","slug":"report-rendering-payload","at":6445,"chars":486},{"level":2,"title":"Limitations and known issues","slug":"limitations-and-known-issues","at":6931,"chars":433},{"level":2,"title":"Report rendering payload schema definition","slug":"report-rendering-payload-schema-definition","at":7364,"chars":4409},{"level":3,"title":"Element definitions","slug":"element-definitions","at":9167,"chars":2606},{"level":2,"title":"Related information","slug":"related-information","at":11773,"chars":233}],"text":"# Attach files, append, and protect report PDFs in AL\nThis article explains how AL developers can enhance the PDF output when a report is downloaded, previewed, or printed.\n## Overview\nUsing AL, you can change the report PDF output in the following ways:\n Add attachments\n  Attach files that are embedded in the report PDF output. The attachments show in the Attachments side panel in a PDF reader, like Adobe Acrobat Reader. You can attach different file formats like images, PDFs, Word documents, Excel spreadsheets, and multimedia files.\n Append additional documents\n  Append other PDF documents to the end of the report PDF to create a single PDF.\n Protect with passwords\n  Set user and admin passwords on the output that users must provide to open or print the PDF.\nThese options are designed to support requirements such as e-invoicing and regulatory requirements for embedded documents, additional files, and document protection.\n## How it works\nThis functionality is enabled by the OnPreRendering trigger, which runs after the last data item trigger and before OnPostReport. Learn where the trigger is with respect to other report trigger in Report Triggers and Runtime Operations<devenv-report-triggers#overall-report-trigger-and-operations> in the report triggers.\nThe OnPreRendering trigger is available on report and report extension objects and has the following syntax:\n```al\ntrigger OnPreRendering(var RenderingPayload: JsonObject)\nbegin\n    //Code to build the report payload json\nend;\n```\nYou add code to the trigger to specify the output modifications you want&mdash;attach, additional documents, or protect&mdash;according to the #report-rendering-payload-schema-definition.\nThe trigger collects report rendering data in a JSON payload. It doesn't invoke processing instructions directly. Instead, it builds the JSON object with a list of attached and appended files, and user or admin passwords. The platform uses this payload to apply the requested changes to the report PDF output.\n### Report actions that apply output options\nNot all output options apply to every report action. This table shows which output options apply to each report action.\nAction|Attachments|Additional documents|Protect\nSend to PDF (SaveAs)|✓|✓|✓\nSchedule|-|-|-\nPreview|-|✓|-\nPrint (universal)|-|✓|-\nPrint (browser)|-|✓|✓\n### Example\n> NOTE\n> The capability in described in this article works with both Business Central online and on-premises. However, some parts of this example apply to on-premises only. For more detailed examples, go to Business Central Tech Samples on GitHub<https://github.com/microsoft/BCTech/tree/master/samples/ReportTech/PdfAttachments>.\nThe following AL code example create a report extension object that modifies the Customer - List report PDF output to include an attached file and append it with the Customer - Top 10 List report. In the OnPreRendering trigger of the report extension, the code:\n Adds a version number to the rendering payload.\n Creates a sample XML file and attaches it as a file to the report's PDF output.\n  To view the attachment in the rendered PDF, select Send to > PDF on the report request page, download the PDF, and open it in a PDF viewer like Adobe Reader.\n Generates a PDF file of the Customer - Top 10 List report and appends it to the main report output as an additional document.\n  To observe the Customer - Top 10 List report in the rendered PDF, select any of these actions from the request page: Send to PDF, Preview, Print.\n Adds password protection information to the rendering payload.\n  To test the password on the rendered PDF, use the Send to PDF action from the request page and open downloaded file.\nThe code uses AL's JsonObject and JsonArray types to build the JSON payload for the report rendering engine. The output includes attachments, additional documents, and protection settings.\n```al\nreportextension 50136 MyCustRepExtension extends \"Customer - List\"\n{\n    dataset\n    {\n    }\n\n    requestpage\n    {\n    }\n\n    rendering\n    {\n        layout(LayoutName)\n        {\n            Type = Word;\n            LayoutFile = 'mycustlayout.docx';\n        }\n    }\n\n    trigger OnPreRendering(var RenderingPayload: JsonObject)\n    var\n        Name: Text;\n        FileName: Text;\n        ProtectionObj: JsonObject;\n        AttachmentsArray: JsonArray;\n        AttachmentObj: JsonObject;\n        AdditionalDocumentsArray: JsonArray;\n        AdditionalDocObj: JsonObject;\n        Top10PdfFile: Text;\n    begin\n        RenderingPayload.Add('version', '1.0.0.0');\n\n        // Create a simple attachment object\n        Name := 'sample-attachment.xml';\n        FileName := CreateXmlFile(Name, 'This is a sample xml file');\n        AttachmentObj.Add('name', Name);\n        AttachmentObj.Add('filename', FileName);\n        AttachmentObj.Add('description', 'This is a sample xml document');\n        AttachmentObj.Add('relationship', 'Data');\n        AttachmentObj.Add('mimetype', 'text/xml');\n        // Add the attachment object to rendering payload\n        AttachmentsArray.Add(AttachmentObj);\n        RenderingPayload.Add('attachments', AttachmentsArray);\n\n        // Create PDF of Customer - Top 10 List report for appending\n        Top10PdfFile := CreatePdfFile('CustomerTop10.pdf', '');\n        // Add PDF to rendering payload\n        AdditionalDocumentsArray.Add(Top10PdfFile);\n        RenderingPayload.Add('additionalDocuments', AdditionalDocumentsArray);\n\n        // Create the protection object with user password\n        ProtectionObj.Add('user', 'UserPasswordHere');\n        // Add protection object to rendering payload\n        RenderingPayload.Add('protection', ProtectionObj);\n    end;\n\n    local procedure CreatePdfFile(Filename: Text; Content: Text) FilePath: Text\n    begin\n        FilePath := System.TemporaryPath + Filename;\n        Report.SaveAsPdf(Report::\"Customer - Top 10 List\", FilePath);\n    end;\n\n    local procedure CreateXmlFile(Filename: Text; Content: Text) FilePath: Text\n    var\n        FileObject: File;\n        OutStream: OutStream;\n    begin\n        FilePath := System.TemporaryPath + Filename;\n        FileObject.TextMode := true;\n        FileObject.Create(FilePath);\n        FileObject.CreateOutStream(OutStream);\n        OutStream.WriteText('<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"yes\"?>');\n        OutStream.WriteText('<root><test>');\n        OutStream.WriteText(Content);\n        OutStream.WriteText('</test></root>');\n    end;\n}\n```\n### Report rendering payload\nThe payload sent from OnPreRendering for the example:\n```json\n{\n  \"version\": \"1.0.0.0\",\n  \"saveformat\": \"Einvoice\",\n  \"attachments\": [\n    {\n      \"name\": \"sample-attachment.xml\",\n      \"description\": \"This is a sample xml document\",\n      \"relationship\": \"Data\",\n      \"mimetype\": \"text/xml\",\n      \"filename\": \"sample-attachment.xml\"\n    }\n  ],\n  \"additionalDocuments\": [\n    \"Top10PdfFile\"\n  ],\n  \"protection\": {\n    \"user\": \"UserPasswordHere\"\n  }\n}\n```\n## Limitations and known issues\n Attachment file size - The maximum attachment file size is limited to 100 MB per attachment[^2].\n Pdf/A compliance - Conversion to PDF/A isn't fully functional because of problems in the Non-Microsoft component that it uses. The file is converted but fails compliance validation due to lack of font substitution and internal data structure.\n Browser printing doesn't support password-protected PDFs.\n## Report rendering payload schema definition\n```json\n{\n  \"\\$schema\": \"http://json-schema.org/draft-04/schema#\",\n  \"description\": \"\",\n  \"type\": \"object\",\n  \"properties\": {\n    \"version\": {\n      \"type\": \"string\",\n      \"minLength\": 1\n    },\n    \"saveformat\": {\n      \"type\": \"string\",\n      \"enum\": \\[ \"Default\", \"PdfA3B\", \"Einvoice\" \\]\n    },\n    \"primaryDocument\": {\n      \"type\": \"string\",\n      \"minLength\": 1\n    },\n    \"attachments\": {\n      \"type\": \"array\",\n      \"uniqueItems\": true,\n      \"minItems\": 0,\n      \"items\": {\n        \"required\": \\[\n          \"name\",\n          \"description\",\n          \"relationship\",\n          \"mimetype\",\n          \"filename\"\n        \\],\n        \"properties\": {\n          \"name\": {\n            \"type\": \"string\",\n            \"minLength\": 1\n          },\n          \"description\": {\n            \"type\": \"string\",\n            \"minLength\": 1\n          },\n          \"relationship\": {\n            \"type\": \"string\",\n            \"enum\": \\[ \"Source\", \"Data\", \"Alternative\", \"Supplement\",\n\"Unspecified\" \\]\n          },\n          \"mimetype\": {\n            \"type\": \"string\",\n            \"minLength\": 1\n          },\n          \"filename\": {\n            \"type\": \"string\",\n            \"minLength\": 1\n          }\n        }\n      }\n    },\n    \"additionalDocuments\": {\n      \"type\": \"array\",\n      \"items\": {\n        \"type\": \"string\"\n      }\n    },\n    \"protection\": {\n      \"type\": \"object\",\n      \"properties\": {\n        \"user\": {\n          \"type\": \"string\",\n          \"minLength\": 0\n        },\n        \"admin\": {\n          \"type\": \"string\",\n          \"minLength\": 0\n        }\n      },\n      \"required\": \\[\n        \"user\",\n        \"admin\"\n      \\]\n    }\n  },\n  \"required\": \\[\n    \"version\",\n    \"saveformat\",\n    \"attachments\",\n    \"additionalDocuments\",\n    \"protection\"\n  \\]\n}\n```\n### Element definitions\n|Element Description|\n|-|-|\n|version|JSON schema version in the format X.X.X.X.|\n|saveformat|Sets the final PDF file format. Values include:<ul><li>Default - Saves the PDF in the default format and version, decided by the platform.</li><li>PdfA3B - Converts the PDF to PDF/A-3B format. This value doesn't update the embedded XMP metadata.</li><li>Einvoice - Converts the PDF to PDF/A-3B and adds XMP metadata for CrossIndustryDocument/invoice compliance. The document is added to the XMP metadata as the DocumentFileName.</li></ul>|\n|primaryDocument|Name of the document that represents the alternative version of the user-facing PDF, such as the invoicing XML document. This document is added to the XMP metadata as the DocumentFileName of the primary document.<br><br>When primaryDocument is set and saveformat is set to Einvoice, this attachment is promoted to the alternative representation of the main PDF document (invoice type) and added to the XMP PDF metadata for identification in electronic payment systems. The relationship is set based on the JSON properties defined for the attachment: use Alternative for the primary document and Data for others.|\n|attachments|List of attachments as a JSON array.|\n|`attachments\\name`|Name of the attachment stored in the PDF.|\n|`attachments\\description`|Description of the attachment.|\n|`attachments\\relationship`|Relationship type as defined by the Adobe PDF standard. Values include:<ul><li>Data - Use this value when the attached file has data for the visual representation in the PDF.</li><li>Source - Use this value when the attached file has the source data for the visual representation in the PDF. For example, use this value for a PDF file created from an embedded XML source file or a Microsoft Word file.</li><li>Alternative - Use this value when the attached file isn't the source or an alternative representation, but has additional information.</li><li>Supplement - Use this value when no other relationship values apply, or if the data relationship is unknown.</li><li>Unspecified</li></ul>|\n|`attachments\\mimetype`|Attachment MIME type. The alternative invoice must use `text/xml`.|\n|`attachments\\filename`|File name of the object to attach. Business Central deletes the file when the operation is complete.|\n|additionalDocuments|List of PDF files to append to the resulting document.|\n|protection|Optional document passwords.|\n|`protection\\user`|User password required to open the document.|\n|`protection\\admin`|Admin password that gives full access to the document. If empty, the platform uses the user password.|\n## Related information\ntriggers-auto/report/devenv-onprerendering-report-trigger\nOnPreRendering (report extension) trigger<triggers-auto/reportextension/devenv-onprerendering-reportextension-trigger>\nDesigning reports<devenv-reports>"}