Monday 12 November 2018

How to email invoices in the right way in Dynamics 365 for Finance and Operations

In my previous blog, I have mentioned that I got a requirement to email invoices with the nicely designed email body and subject containing customer related information such as Invoice ID and Customer account number. Besides, I needed to attach some additional documents to outgoing emails and sent them together with invoices. This is, I would say, such a common scenario for emailing invoices but unfortunately still not provided in D365FO OOTB.

So for achieving this requirement I have found a completely free tool called Docentric that provides far more options regarding all print destinations for all SSRS reports, not just Email print destination and Customer invoice. Read more about its features in my previous blog >>

In this article I will discuss how we can use Docentric free-edition tool to achieve the above described scenario:
  1. Send emails to customers with the professionally looking email body.
  2. Provide sender display name through Docentric AX parameters setup.
  3. Provide dynamic email subject, company logo and email body content using placeholders for Invoice ID, Customer name, Customer reference, etc.
  4. Create a new custom placeholder for Customer requisition.
  5. Add additional email attachment InvoiceSpecification_<InvoiceId>.pdf.
For this blog example, I have set up Docentric Email as the target print destination for the Customer invoice report in Print management setup for Accounts receivable: Accounts receivable -> Setup -> Forms -> Form setup -> General (Side menu) -> Print Management (link) -> Customer invoice -> Original <default>.

You can easily test these settings when posting an invoice from a sales order or from Invoice journal as show on the image below.

Email an invoice:
Accounts receivable -> Inquiries and reports -> Invoices -> Invoice journal -> Invoice (Menu) -> Document (Submenu) -> View (Submenu option) -> Use print management.

Note: For emailing, you need to setup Email parameters: System administration -> Setup -> Email -> Email parameters.
There are two email providers: 1) SMTP 2) Exchange.

Please make sure your email settings are working otherwise you will not be able to send emails. From the 8.1 app version you can send a test email directly from this form. Now let’s back to the blog topic.

Requirement 1:

Send an email with the nicely designed body. Docentric free-edition tool provides both designer editor and html source code editor so you can design your emails easily. For this example I have got an email template as html file. You can find email templates over the Internet or create your own custom design.

View in design editor of Docentric free-edition tool.

View in source code editor of Docentric free-edition tool. Here you can see the HTML & CSS code.

Requirement 2:

Provide sender display name through Docentric AX parameters setup.

Sender display name can be provided in the Docentric AX parameters form: Workspace -> Docentric AX (menu) -> Related links -> Docentric AX parameters.

Under the
Emailing option, you can find the Email sender display name field and enter any text as you like (in my case “Docentric services”).

Requirement 3:

Provide dynamic email subject, company logo and email body content using placeholders.

3.1 Email subject can be provided at the highlighted section in below screenshot. By giving a placeholder, at runtime Docentric will resolve this placeholder with its value.

Note: You can make attachment name also dynamic, for example: Invoice_@InvoiceId@.pdf. In fact, you can use placeholders in any of print destination settings where this makes sense.

3.2 Company logo is the OOTB placeholder. You can find it in the Fields drop-down list. When you place company logo in the email body, it automatically resolves into image as shown below.

3.3 Placeholders for email body content. You can simple click a placeholder from the Fields drop-down list and the editor will create the placeholder in your email body.

Requirement 4:

Create a new custom placeholder for Customer requisition of corresponding sales order.

Docentric free-edition tool provides OOTB placeholders for Invoice and other reports. But you can also create your own custom placeholders by doing very minimal coding in one of Docentric model’s classes.

OOTB placeholders already appears in the Fields drop-down list as you can see in above screenshots. For our new custom placeholder Customer requisition we need to customize so called Docentric DSP (Data Source Provider) class for Customer invoice in the Docentric AX SSRS Replicas model: DocSalesInvoiceReportDSP. This model is not part of the product but it’s an optional model that serves as starting point for customization like this.

Note: For better understanding of Docentric DSP classes, you can read this documentation.

In next steps, I am going to add a new Customer requisition placeholder, which should contain value from the Customer requisition field of the corresponding sales order.

Source Code Explanation:
  • Declare the Customer requisition placeholder variable that will hold its value.

  • Fill the placeholder value in the onSelectedRdpTableRecord() method:
       SalesTable salesTable = SalesTable::find(header.SalesId);
       placeholder_customerRequisition = SalesTable.PurchOrderFormNum;

Source Code Screenshot:

  • Declare a macro.
  • In the overrideReportRunSettings() method add DocPlaceholderAttribute for Customer requisition.
DocPlaceholderAttribute(#CustomerRequisition, 'INV - Customer Requisition')
  •        Add the X++ code in overrideReportRunSetting() method, which replaces each occurrences of the @CustomerRequisition@ placeholder with its value.
// -- Placeholder @CustomerRequisition@
placeholderMng.replacePlaceholderInCurrentPrintDest(#CustomerRequisition, placeholder_customerRequisition);

Source Code Screenshot:

Then build and sync your code. Please see the result in Docentric free-edition email editor on the screenshot below – our new custom placeholder is now shown in the Fields dropdown list.


Requirement 5:

Add additional email attachment.

In Docentric free-edition tool you will be able to add additional email attachments using the same DSP class that handles placeholders. It’s up to you where to store documents that need to be picked and emailed as additional attachments of your outgoing emails. Common place is Attachments of the context execution table record, in our case Sales order.

Note: To add a document to Attachments to your relevant sales order record(s) follow bellow steps.

Step 1:

Step 2:

For adding an attached document as additional email attachment using Docentric free-edition tool we need to write some code in the same overrideReportRunSetting() method as we did for the custom placeholder Customer requisition.

Source Code Explanation:
  • The addAdditionalAttachment() method adds an additional email attachment to the email that will be sent together with the report itself in case of Email print destination.
  • Method signature has two arguments.
    • Additional attachment name (e.g. 'InvoiceSpecifcation_InvoiceId.pdf').
    • Attachment file content.
  • For attachment name I am concatenating InvoiceSpecification with InvoiceId.
  • For attachment file content I am getting invoice specification document for the related sales order from the DocuRef table .This table contains the references between documents and their associated tables and records.
//Add additional document.           
strFmt('InvoiceSpecification_%1.pdf', placeholder_invoiceId),                DocumentManagement::getAttachmentAsContainer(DocuRef::findTableIdRecId(curExt(), tableNum(SalesTable), SalesTable::find(placeholder_salesId).RecId)));

Source Code Screenshot:

Now build and sync the code and let see the final result of the email body, placeholders, sender display name and additional attachment.

Final Result:


  1. The Docentric Free version was installed in our D365-FO Test environment last year. I was requested to investigate it trying a very similar task that you show above with emailing invoices. I discovered the InvoiceId & InvoicingName fields that you show above are not available in the Fields list and do not automatically resolve at runtime. I am not an X++ programmer but it appears that it may be required to add placeholders for them. Is that correct? Is it a file that can be imported instead? Any advice on a resolution is appreciated before I can recommend using it for our production environment.

    1. Hi,
      There is an additional model to get those placeholders called Docentric SSRS Replicas. (
      If you don't want to use Docentric SSRS Replicas or you need to add additional placeholders, this can be done only via X++ and it is described here:


  2. unable to see docentric in print destinations setting.
    goal is to send purchaseorder report in email with Body.
    can anyone help?

    1. Go through this link

  3. Hi Team,

    We have a same requirement to add additional attachments and body place holder with no use of third part. The additional documents are saved in my docref table. But what will be the entry point to provide the converted bytes for email attachment for Post Invoice Journal process via email.


How to Get Customer Free Text Invoice "Totals" form field value with X++ in D365FO

Customer free text invoices are an essential aspect of financial management in D365FO. In this blog, I have compiled all the code needed to ...