Send Collection Letters with Overdue Invoices in D365FO

In the previous article, Are you ready to collect more of your money?, we described how we can improve the dunning process, but now we want to focus on the technical part.

The article shows you how you can add the functionality of printing and sending a single collection letter, then adding a cherry on top by using the same solution for automation of the dunning process with mass printing and sending of Collection letters.

Printing and sending a single collection letter

In this solution, we assume that the invoices are already created in PDF format and stored in the journal tables or Print archive.

Before we dig into the technical part, let us see how the ending result of the solution will look like.

To start, please download this sample POC project first. Use Import an .axpp file in Visual Studio with the Finance and Operations (Dynamics 365) extension installed, as described here.

When you import the project into Visual Studio, the following tree structure appears in Solution Explorer.

Now let’s get started with a step by step tutorial.

Please note that in the project available for the download from this article, we renamed the artifacts by changing the _DC suffix into _DCL, because only artifacts from the core Docentric AX models should be named with the _DC suffix.

Ten simple steps to create a working solution

We have built the POC project out of 10 simple steps. In the article, we are focusing on the CustCollectionJour related objects in AOT, to understand how things are running under the hood.

In the article, we explain how to create the POC project out of ten simple steps:

  • Step 1: Enable the new functionality with a new subclass controller.
  • Step 2: Create a menu item to extend the forms.
  • Step 3: Extend forms with new menu item button.
  • Step 4: Define new data types for options used on the extended dialog.
  • Step 5: Create a new extension of the contract with new parameters.
  • Step 6: Add new options to the print dialog (UI Builder).
  • Step 7: Create a new DSP class with logic for the Email and other print destinations.
  • Step 8: Register new DSP class to Docentric report setup.
  • Step 9: Define & design how outgoing e-mails will look like.
  • Step 10: Try the solution.
This POC project was done with Docentric Free Edition so you can use it entirely for free.
Learn more about how to install Docentric here.

Step 1: Enable the new functionality with a new subclass controller

When extending the existing UI functionality, we need to know in which cases we should do this (showing and hiding of extended print destination options). That is why we need to create a new subclass controller and implement the class static constructor and the static main() method. In this case, we can then check if the call has come from this controller.

Step 2: Create a menu item to extend the forms

Before we add a new menu item button to the UI form, we need to create an output menu item. We used the menu item for running the created controller subclass DocCustCollectionJourController described in Step 1.

Step 3: Extend forms with new menu item button

Now we are ready to develop form extensions. As the collection letter printing process is accessible from two forms (CustCollectionLetterJournal and CustCollectionLetterNote), we need to extend them both.

Extension of any object can be done from AOT in Visual Studio by right-clicking on the object and selecting the option Create extension.

The important thing is to assign newly created menu item buttons to the form data source CustCollectionLetterJour and the correct output menu item DocPrintoutCollectionLetterWithAttachments, as you can see on the properties panel bellow.

Step 4: Define new data types for options used on the extended dialog

As we needed to control the printing and e-mail sending pipeline, we had to define a few new options. In our case, attaching overdue invoices, the source location of already created PDF documents, and error handling if source invoices are missing, a few new data types were added to the project.

When you create a new data type based on base enum, it is a good practice to set Is Extensible to false. In this case, the data type isn’t extendible, and the enum values have fixed integer numbers assigned to it. You are now in control of the values passed around the D365FO.

Step 5: Create a new extension of the contract with new parameters

To be able to pass new print options to the Docentric pipeline and control what happens happen with the overdue invoice attachments, we need to create an extension of the existing contract class by using the ExtensionOf attribute and add additional parameters to it.

Keep in mind that in this case, you are writing an extension of the existing contract used on the existing dialog, and the newly added parameters are automatically shown as fields on the dialog using it. Therefore, we used a non-existing group on the UI to prevent the SrsReportDataContractUIBuilder from adding the new parameters as DialogField on the dialog (the fields are not visible when UI builder is building the dialog).

Extensions of an existing class with defined attributes using the ExtensionOf attribute are supported in D365FO from the so-called "4th extension wave" Platform update 23, as you can see here.

Step 6: Add new options to the print dialog (UI Builder)

Now the exciting part. How to display new fields on the dialog, but only when we are using newly added menu item buttons? As we have used our controller on the output menu item, we can control the build processes of the print dialog by checking if the controller used is DocCustCollectionJourController. But to do this, we must create an extension of the CustCollectionJourUIBuilder class.

The tricky part here is that the existing CustCollectionJourContract contract class extended in Step 5 already has defined the dialog creation strategy.

How can we change this? Is it even possible?

In short, the answer is Yes. We can change the dialog by implementing build() and postBuild() methods by using Method Wrapping and CoC (Chain Of Command) principle.

But first, we need to add new DialogField to the dialog. For this purpose, we are using the build() method of CustCollectionJourUIBuilder.

Then we need to enable or disable other print options on the user interface if the option Attach overdue invoices is disabled.

In this case, we are also extending the behavior of newly added controls to the dialog, so we need to extend the postBuild() method. Therefore, we are registering an event to execute on the OnModified event handler, where you can change the visibility of the new dialog fields.

Step 7: Create a new DSP class with logic for the Email and other print destinations

Now we start modifying the output of print destinations. When you installed Docentric AX, you got replica designs of the original SSRS reports and DSP (Data Source Provider) class DocCustCollectionJourReportDSP.

You can find here more information about what Docentric SSRS replicas and DSP classes are. Docentric SSRS replicas and DSP classes are available for download here.

In this case, extending of the DocCustCollectionJourReportDSP class is needed to handle our new functionality:

  • If the selected print destination is Docentric Email, to attach overdue invoices as separate PDF files or Merged PDF file or a ZIP file containing overdue invoice PDFs.
  • Otherwise, to download all overdue invoices as zipped PDF file.

In the extended DSP class, the main logic goes in the overrideReportRunSettings method, where we need to do the following:

  1. Check if attaching of overdue invoices is enabled by using parameters passed to the DSP class through the implemented contract in Step 5.

  1. Read all overdue invoices into memory from various locations depending on the invoice type.

Overdue invoice PDF files must be created and stored before sending a collection letter either in a journal or Print archive. Keep in mind that the data source location of the invoices may vary depending on the type of the invoice. Free text and Customer invoices are saved in the CustInvoiceJour table, while Project invoices are stored in the ProjInvoiceJour table. Invoice PDF files can be created as eInvoice attachments, by using Docentric File Print destination and the Save to Attachments option, or by saving to Print archive.
  1. Create overdue invoice files depending on the print destination

As we now have all the PDF streams, the only thing left is to create the result. If the print destination is other than Email, a ZIP file with overdue invoices in PDF format is available for download. On the other hand, if the selected print destination is Email, then you can send overdue invoices as Separate files, Merged PDF or ZIP file containing PDF files.

You can find more about writing custom DSP class in our how-to manuals.

Step 8: Register new DSP class to Docentric report setup

Before we start to register the newly created data source provider class, don’t forget to build the project and models. When the build process completes, you can assign the new DSP class to the Collection letter note report in Docentric report setup. You can do this by clicking in D365FO on Workspaces > Docentric AX > Reports > Report CustCollectionJour.Report > Data source and selecting the correct DSP class.

Step 9: Define & design how outgoing e-mails will look like

The only thing left is to define & design the outgoing e-mail. We can do this as we run the print action on the collection letter or in Docentric AX workspace under print management. In this case, we are using the standard print action.

Docentric AX supports dynamic placeholders of data used in the current collection letter. You can use them when you define & design an outgoing e-mail to fill some information automatically.

Note that standard D365FO generates outgoing e-mail without an e-mail body. Also, you cannot dynamically specify the subject, body, or attachment of an e-mail. E-mails without e-mail body can spoil the Spam Score, and your e-mails will most likely not reach your customers. You can learn more about this topic in one of our previous articles here.

You can use this defined template for testing this solution.

  • E-mail TO field template: @Invoice@;@@
  • E-mail SUBJECT field template: @COMPANYNAME@: @CollLetterTitle@ - @CollLetterNum@ » Overdue payments on @DueDate@
  • E-mail BODY field HTML template is available here for download.

Step 10: Try the solution

Now we are done, and you can try the solution at hand. For those of you who don’t have the time to try this out, you can watch this short video and see the demo in action.

Mass printing and sending

We have taken a look at how to create the solution for a single collection, but now let us focus on the mass printing of collection letters by using the same functionality as for printing a single collection letter. The only thing left is to create a new menu item inside the main menu of the D365 Modules > Credit and collections > Collection letter > Collection letter report with attached invoices. To extend the Credit and Collection menu, you need to create an extension of the exiting CreditAndCollection menu. Then you need to create an output menu item DocCustReport_collectionLetterAllWithAttachments and attach it to the DocCustCollectionJourController controller. Then you need to add the new menu to the extension of the CreditAndCollection menu.

And here is the result in D365FO of a newly added menu item.


The POC solution at hand will get you started. By using Docentric AX Free edition and simple modifications of existing D365 FO functionality, you can provide an automated way in the dunning process for printing and sending collection letters with attached overdue invoices.

3 thoughts on “Send Collection Letters with Overdue Invoices in D365FO

  1. note if you have Collection letter setup as ER report/Business Document and you are using the free version the print function will without any result and no error message will show.
    reason for that: free version not support ER report/Business Documen, just full….
    solution: revert to standard SSRS report or upgrade to full version

    1. Hi Bence , are you was able to make that working with ER ? I understand i need to make right change in DSP class

      1. Hi Marcin,
        ER uses its own execution pipeline and ER destinations for printing. The example in this article uses the SSRS report execution pipeline in combination with Docentric APIs. To use ER, you need a Full Edition of Docentric AX, in which you can use ER data model and model mapping configurations and create Docentric report templates using the data from these configurations. The reports created in this way can be printed just like the SSRS reports and you can apply the solution from this article.

Leave a Reply

Your email address will not be published. Required fields are marked *


Docentric respects your privacy. Learn how your comment data is processed >>

Docentric respects your privacy. Learn how your comment data is processed >>