Manipulate PDF files in Dynamics 365 with iText

When making archivable invoices in Dynamics 365 Finance & Supply Chain Management, PDF handling may be a topic: we must ensure PDF/A-3 compliance, and guarantee that invoices remain readable for customers and auditors. In this series, I will show you how to manipulate PDFs directly from X++ using the iText 7 for .NET library.

The iText is a popular open-source library for creating and manipulating PDF files programmatically. It offers support for advanced use cases such as: converting HTML to PDF, filling interactive PDF forms, embedding attachments, converting to PDF/A (archival standards). This makes iText a versatile tool when extending Electronic Reporting (ER) or custom document generation in Dynamics 365 FO.

At first glance, you might be tempted to take the latest version of iText. Unfortunately, in Dynamics 365 FO, that’s not possible. From version 8 onwards, iText introduced a breaking change; it requires one of two mutually exclusive cryptography connectors: BouncyCastle Adapter or BouncyCastle FIPS Adapter. In a normal .NET Core or Java application, you could choose one. But in Dynamics 365 FO, we are bound by the AOS linking rules: both cannot coexist, and we cannot configure mutually exclusive linking at runtime. That’s why we stick to iText 7 for .NET, the last major version without this restriction.

DLL libraries

Library	Purpose	NuGet / Download
`itext.commons`	Common utilities, required by all modules	commons.nuget 7.2.6
`itext.kernel`	Core PDF document model	itext7.nuget 7.26
`itext.io`	Low-level PDF parsing and writing, required by kernel
`itext.forms`	AcroForms support (reading/writing fields)
`itext.layout`	High-level layout, form value appearances
`BouncyCastle.Crypto`	Cryptography provider, required by kernel	Portable.BouncyCastle 1.9.0

Put these into the bin folder of the model, then add these to your project -> References, browsing and picking them from the folder.

PdfDocument initialisation and “Stamping”

Here’s a real-world method implemented in Dynamics 365 FO. It takes an existing PDF, flattens all form fields (so values from XFDF imports remain visible), and returns a memory stream you can pass further to the archive as an attachment.

Stamping mode means that you take an existing PDF, open it for reading, and at the same time prepare a writer to save changes into a new file or stream. In iText this is controlled by the constructor of PdfDocument. If you pass only a PdfWriter, you start with a blank PDF and stamping is not possible. If you pass only a PdfReader, you can read the document but you cannot modify it. If you pass both a PdfReader and a PdfWriter, the document is opened in stamping mode. That is the case in the below Dynamics 365 example.

				
					using iText.Kernel.Pdf;
public class ERFileDestinationPostProcessor
{
    protected System.IO.MemoryStream postProcessPDF(System.IO.Stream _pdfStream)
    {
        System.IO.MemoryStream outputStream = new System.IO.MemoryStream();
        try
        {
            // Setup reader + writer
            PdfWriter writer = new PdfWriter(outputStream); // itext.commons and bouncyCastle invoked
            writer.SetCloseStream(false); // keep outputStream usable after close
            PdfReader reader = new PdfReader(_pdfStream);

            PdfDocument pdfDoc = new PdfDocument(reader, writer);

            // Flatten AcroForm fields so values remain visible (XFDF values preserved)
            iText.Forms.PdfAcroForm form = iText.Forms.PdfAcroForm::GetAcroForm(pdfDoc, true);
            if (form != null)
            {
                form.SetGenerateAppearance(true);            
                var Fields = form.GetFormFields();
                if (Fields.Count > 0) // Touch every field to generate appearence
                {
                    var Enumerator = Fields.GetEnumerator();
                    while (Enumerator.MoveNext())
                    {
                        var KeyValuePair = Enumerator.get_Current();
                        var Field = KeyValuePair.get_Value();
                        str value = Field.GetValueAsString();

                        if (value)
                        {
                            // Set the value to itself, Force regenerate appearance
                            Field.SetValue(value); // itext.layout is leveraged here
                        }
                    }
                }
                form.SetNeedAppearances(false); // PDF/A requirement: NeedAppearances must be false or absent
                form.FlattenFields();
            }            
            pdfDoc.Close();
            reader.Close();
            writer.Flush();
        }
        catch (Exception::CLRError)
        {
            System.Exception exception = CLRInterop::getLastException();
            if (exception != null)
            {
                warning(exception.get_InnerException() ? exception.get_InnerException().get_Message() : exception.get_Message());
            }
        }
        return outputStream;
    }
}

This flattening is important because it guarantees that all the values filled into the PDF form remain permanently visible and readable even if the file is opened outside of Adobe Reader. To meet PDF/A compliance rules, the NeedAppearances flag must be set to false, so viewers do not depend on dynamic rendering of the fields. By assigning each field’s value back to itself, the code forces iText to regenerate the visual appearance; otherwise, the .FlattenFields() call is going to wipe all form data from the document.

Embedding an ICC profile

A PDF/A document must declare its output intent. The output intent tells a PDF viewer how colours should be interpreted, and this is done by embedding an ICC profile. For most business documents, the standard profile is sRGB IEC61966-2.1, which defines an RGB color space suitable for PDFs primarily displayed on the screen. You may download it here: https://www.color.org/srgbprofiles.xalter. Without a profile, the PDF is not going not pass validation for PDF/A.

In Dynamics 365 we cannot rely on a file path, so the ICC profile is added as an embedded resource (AOT/Resources). At runtime the code checks whether the PDF already contains an output intent, then loads the profile from the resources and attaches it to the document. There should not be more than 1 profile in the document:

				
					            // Check if there is already an ICC profile embedded
            PdfDictionary catalog = pdfDoc.GetCatalog().GetPdfObject();
            PdfArray outputIntents = catalog.GetAsArray(new PdfName("OutputIntents"));
            if (outputIntents == null || outputIntents.Size() == 0)
            {
                // Load sRGB Preference ICC profile from the embedded resource
                ResourceNode iccResourceNode = SysResource::getResourceNode(resourceStr(sRGB_v4_ICC_preference));
                container iccInContainer = SysResource::getResourceNodeData(iccResourceNode);

                System.IO.Stream iccStream = Binary::constructFromContainer(iccInContainer).getMemoryStream();
                if (iccStream)
                {
                    // Add output intent (required by PDF/A)
                    PdfOutputIntent outputIntent = new PdfOutputIntent(
                        'Custom',
                        "", // outputCondition
                        'http://www.color.org',
                        'sRGB IEC61966-2.1',
                        iccStream);
                    pdfDoc.AddOutputIntent(outputIntent);
                }
                else
                {
                    warning("ICC profile is not found in D365...");
                }
            }

Replacing the PDF before archiving

Microsoft provides the ERDocuManagementEvents class and event handlers that allow you to intercept how Electronic Reporting saves files in Organisation administration > Electronic reporting > Electronic reporting jobs, see https://learn.microsoft.com/en-us/dynamics365/fin-ops-core/dev-itpro/analytics/er-custom-storage-generated-documents.

Action-dependent ER destinations For the screen destination to work, make sure that the feature "Configure action-dependent ER destinations" (see https://learn.microsoft.com/en-us/dynamics365/fin-ops-core/dev-itpro/analytics/er-action-dependent-destinations) remains inactive: the selection Document type in the ER destination must be set to Any. This is a known bug in D365 FO v41-45 and earlier versions.

The following event handler subscribes to the point where ER is about to save the file. We check if the file is a PDF we wish to intercept, and if so, we run our own post-processing logic before handing the stream back to ER. If the “handled” state is sent back to ER with fileEventArgs.markAsHandled(), then the archive receives the replaced file.

				
					using Microsoft.Dynamics365.LocalizationFramework;
/// <summary>
/// This is the main trigger for the PDF post-processing
/// </summary>
class ERDocuSubscriptionCopy
{
    /// <summary>
    /// Capture an attempt by ER to save an attachment, react to a DocuTypeId with a magic pattern in the name
    /// </summary>
    /// <param name = "_args">Attachment context</param>
    [SubscribesTo(classStr(ERDocuManagementEvents), staticDelegateStr(ERDocuManagementEvents, attachingFile))]
    public static void ERDocuManagementEvents_attachingFile(ERDocuManagementAttachingFileEventArgs _args)
    {
        ERDocuManagementAttachingFileEventArgs fileEventArgs = _args;
        if (fileEventArgs.isHandled())
        {
            return;
        }
        if (! strContains(fileEventArgs.getDocuTypeId(), "MyDocuType"))
        {
            return;
        }

        var inputStream = fileEventArgs.getStream();
        // Rewind
        if (inputStream.CanSeek)
        {
            inputStream.Seek(0, System.IO.SeekOrigin::Begin);
        }

        ERFileDestinationPostProcessor postProcessor = new ERFileDestinationPostProcessor();
        System.IO.MemoryStream outputStream = postProcessor.postProcessPDF(inputStream);

        // Do something with the  PDF
        if (outputStream != null)
        {
            boolean attachmentHandled;            
            try
            {
                DocuRef     docuRef;
                docuRef = this.createDocuRef(outputStream,
                                         fileEventArgs.getOwner().TableId,
                                         fileEventArgs.getOwner().RecId,
                                         fileEventArgs.getOwner().DataAreaId);
                if (docuRef)
                {
                    fileEventArgs.setDocuRef(docuRef);
                    attachmentHandled = true;
                }
            }
            finally
            {
                attachmentHandled = false;
            }

            if (attachmentHandled)
            {
                fileEventArgs.markAsHandled();
            }
        }
    }
}

X++ programming blog series

Further reading:

Import a D365 FO entity with a virtual KEY field
Print a custom product label: a Template solution in Process Guide Framework, with detours
Extending SysOperation contracts with DataMemberAttribute
X++ Decorator pattern in Dynamics 365
Get a cost center in D365FO
Find and merge a DimensionAttributeValue
SysExtension framework pitfall: avoid new()
Input validation and messaging in the Process Guide Framework

Customer invoice falsifier for D365 for Finance

In certain business scenarios, it may become necessary to update and reprint customer invoices in Dynamics 365 for Finance with corrected or intentionally adjusted figures. By selectively mapping only specific invoice header and invoice line fields for update, the ER configuration we are sharing here enables targeted adjustments without triggering recalculations of dependent totals. These electronic reporting configurations may also be used as a tutorial for the Excel imports in D365.

Check the above screenshot: assuming we’ve initially issued an invoice with 19% VAT instead of the reduced 7% VAT, the ratio between the SalesBalance (amount before VAT) and SumTax (total VAT amount) may be shifted while keeping the total invoice amount the same. Beware: to reflect the VAT manipulations in the tax books a separate [cumulative] GL journal must be posted manually. Please ensure any misaligned invoice reprints are clearly marked as adjusted copies to avoid confusion or compliance issues, though.

The underlying method uses the Electronic Reporting import configuration capabilities in Dynamics 365 for Finance. You may download the ER configurations here: CustInvoiceUpdater.zip. Unpack and import into the ER tree one by one, starting with the model. Use it at your own risk!

Key elements include:

Data Model – definition of the conceptual invoice structure (header amounts, line amounts, tax values, etc.).
Model Mapping for export and a model mapping To destination for the import (both in the same model mapping ER configuration) – links the data model fields to the relevant Dynamics 365 tables and columns.
Formats – define the export file structure (Excel) and the same import file structure and maps the file’s data to the model fields.

For a detailed description of the ER import concept and practical configuration guidance, check Electronic Reporting in Data Migration.

The process follows a three-step cycle:

Export: extract invoice data from Dynamics 365 into an Excel using the “CustInvoiceJourDump format” ER export configuration.
Adjust / Transform: modify the extracted data in Excel, changing selected amounts while leaving others untouched.
Import: re-import the adjusted file by selecting the “CustInvoiceJour mapping” in the ER tree, clicking Designer, then Run at the “To destination” mapping, and uploading the Excel file. If the file is well formed and there is a match for every RecId of the invoice headers/lines, it updates the records in Dynamics 365 and says “Operation completed“.

In our scenario, the import mapping is deliberately limited to only 3 or better to say 6 amounts, both in the transaction currency and the accounting currency (the “MST” amounts): Sales subtotal amount, Total charges, VAT amount. A built-in validation ensures these three values still sum to the original invoice total, maintaining internal consistency while allowing the reprint to reflect updated breakdowns.

The “CustInvoiceTrans mapping” for invoice lines does not have this safeguard, since the invoice lines to not hold grand totals in D365.

The total invoice amount field was intentionally excluded from the update, because this may lead to a mismatch between the general ledger and the AR subledger.

Electronic reporting blog series

Filling PDF Forms with Electronic Reporting in Dynamics 365 for Finance

Dynamics 365 Electronic Reporting (ER) supports output into Excel, Word, and PDF formats. Excel and Word templates are well-covered in documentation and practice, but PDFs remain obscure – there’s only a short article Design ER configurations to fill in PDF templates – Finance & Operations | Dynamics 365 | Microsoft Learn from Microsoft.

The PDF/File component in ER is usable, it fills out static PDF forms. For example, one may take the VAT return or another tax declaration form, import into the ER configuration designer and get it filled out.

Technically, this resembles the old Dynamics Axapta approach using XFDF to inject data into form fields. That still seems to happen under the hood: you map values to fields, and the form gets filled in and flattened into a non-editable PDF. However, PDFs don’t support repeatable ranges like Excel – everything is fixed on the page. If there are – let’s say – several lines, then the subtotals below won’t slide on the PDF page. They’ll remain on the same page as placed on the PDF form, and remain on the exact place on the form.

To simulate Excel-like ranges, Microsoft introduced a naming trick. You create form fields named, e.g., LineNo1, LineNo2, …, LineNo10. In ER, you create a Field group containing a single LineNo field. ER fills LineNo1 with the first record, LineNo2 with the second, and so on. If only two records are present, only LineNo1 and LineNo2 get filled—the rest stay blank. You must not exceed the number of fields available in the form: 11 records will crash the report.

To prepare such a form, you need Adobe Acrobat (not the free Reader). Create a fillable form and assign field names. For repeated fields like headers or footers (e.g. Total_pages), it’s okay to copy-paste – Acrobat auto-numbers them visually (Total_pages#1, #2) but they’re still internally just one field, and ER will fill all copies identically. That is ideal for values repeated on every page.
For tables where every row must be unique, the fields must have unique names (LineNo1, LineNo2, etc.). Renaming manually gets tedious fast. A handy script Acrobat — Rename Duplicate Fields to Unique Fields | Try67 | Custom PDF tools (the script is commercial + Adobe Acrobat Pro is required) automates this: draw a rectangle over the fields, and it appends unique suffixes to overlapping fields across pages. You can prepare a single line of fields, copy-paste the line (do not shuffle but always keep adding them in the strict order from top to bottom: Acrobat keeps track of their numbers and sorts them internally), then start replicating blocks of lines until the page is full, copy-paste full pages in the Acrobat’s “Organize pages” tool, and then batch-rename everything.
Back in ER: in the Format mode, add a PDF/File object and point it to your PDF template. Use the button Import / Update from PDF once to pull in field definitions. Don’t use “Update from PDF” again – it can scramble your mapping. Grouping fields by suffix (e.g., LineNo1..10) doesn’t always work automatically, so you might have to manually create a field group and drop in the core field (LineNo) without suffix.
Apply ENUMERATE(Lines) to record lists to create a structure where @.Number gives you the index (1-based) and @.Value gives the record. Then, in the Mapping mode, set the Name property of the line field in the lower right corner to "LineNo"&TEXT(@.Number), then assign the value from @.Value.YourField as usual with the Bind button. By the way, the order of fields doesn’t matter – unlike Excel, where rows and columns are positional, the PDF is filled at once using a key-value approach (essentially, an FDF file).
Don’t exceed the number of fields in your form. There’s no pagination or overflow – ER won’t split lines across multiple copies of the form. You may limit the data source with the formula like WHERE(@.LinesEnumerated,@.LinesEnumerated.Number<=10) to harden the report. You may also design a custom warning if the number of lines exceeds a certain threshold: Validate Electronic Reporting on execution and show errors or warnings – Arcadi Burria.

In short, ER’s PDF support is usable and powerful enough but static. With proper naming and field repetition strategy, it’s good for things like tax forms, returns, invoices with known limits, etc. The main challenge is preparing the template, not the mapping itself.

Yearly Archives: 2025

Manipulate PDF files in Dynamics 365 with iText

Manipulate PDF files in Dynamics 365 with iText

DLL libraries

PdfDocument initialisation and “Stamping”

Embedding an ICC profile

Replacing the PDF before archiving

X++ programming blog series

Customer invoice falsifier for D365 for Finance

Customer invoice falsifier for D365 for Finance

Electronic reporting blog series

Filling PDF Forms with Electronic Reporting in Dynamics 365 for Finance

Filling PDF Forms with Electronic Reporting in Dynamics 365 for Finance

E-invoice and configurable business documents blog series