Improved Email Templates – Creating Email Body with Dynamic Table

In D365FO you can set up Email templates for sending email notifications for Retail orders, workflows, alerts, etc.
With Docentric AX Free Edition you can:

  • use an advanced HTML editor to format email bodies within D365FO,
  • pick a placeholder from a list of available placeholders for the current email, if you need to create a dynamic email body.

Learn the basic stuff about Email Templates improved with Docentric >>

In this article we will demonstrate how to create and send a dynamic email body with a dynamic table, e.g. a Sales Order Confirmation email, which will contain some header/footer dynamic information such as Customer name and Sales ID but also a list of all ordered items and their prices.

First, we need to create a custom Docentric email handler class, which will provide the list of both header and line placeholders. This class can also contain logic for suppling the values for these placeholders. Then we need to set up an email template using Docentric and the created custom email handler class. In the end we will discuss options on how to send an email based on the created email template.

Create custom email handler class

Create a new X++ class that extends the DocEmailTemplateHandlerBase class and implement at least two methods: description() and defineCustomPlaceholders():

Set up email template with custom email handler class

Navigate to Organization administration -> Setup -> Email templates. Click the Docentric settings tab page and turn on the Use Docentric email editor checkbox. Then select previously created DocOrderConfirmWithLinesEmailHandler class (you have to build the belonging model first) as Class for placeholders.

After you click the Edit button located above the Email message content grid, the form with Docentric email body editor is open. You can see that the Field dropdown list contains placeholders defined by your DocOrderConfirmWithLinesEmailHandler class.

You will design the email template more easily if you switch to Full Screen.

You can finish designing your template using the email editor's formatting features and both header and line placeholders regularly. Notice that in the custom email handler class we created placeholders for header with friendly names starting with CO (Confirmation Order) while placeholders for lines have friendly names starting with COL (Confirmation Order Line).

After we finish the whole template, we need to take some additional steps to enable dynamic lines, i.e. dynamic table.

Inserting hidden placeholders for the repeating table row

Scroll through the placeholder's dropdown list and find two special placeholders:

  • Hidden table begin tag
  • Hidden table end tag

Insert them temporarily in the email body and follow the instructions on the screenshots below.

 

 

To enable rendering of the dynamic table these special placeholders wrapped in HTML comment tags, i.e. <!‐‐%HIDDEN_TABLEBEGIN%‐‐> and <!‐‐%HIDDEN_TABLEEND%‐‐>, should enfold the repeating table row directly in HTML of the email body. That is why they will not be visible in Normal view of Docentric email body editor.

Sending emails with a dynamic table in the body

In D365 only Retail orders support such a scenario with a dynamic table in the body, and if you are using this built-in logic for sending email notifications for retail orders you will need to add two more placeholders to enable tagging of the repeating table row, in addition to all other custom placeholders in your email handler class:

  • tablebegin.salesline
  • tableend.salesline

You need to use these two placeholder instead of <!‐‐%HIDDEN_TABLEBEGIN%‐‐> and <!‐‐%HIDDEN_TABLEEND%‐‐> to wrap the repeating table row in an email body with a dynamic table, following the instructions from the previous section.

Check the RetailOENInfo built-in class – you will find there actually the whole list of all header and line placeholders for Retail orders.

However, if you want to send emails with a dynamic table in the body in some other scenarios, you can use Docentric APIs for sending emails, or write your own code.

Sending emails using Docentric APIs

You can use the DocEmailTemplateManager::sendMail() method to send emails with dynamic table in the body:

In order for this to work your custom email handler class should contain logic for supplying values for both header and line placeholders, i.e. it should implement the fillMappingsWithCustomPlaceholderValues() and fillLineMappingsWithCustomPlaceholderValues() methods:

If your custom email handler class doesn't provide values for header and line placeholders, i.e. it doesn't implement the fillMappingsWithCustomPlaceholderValues() and fillLineMappingsWithCustomPlaceholderValues() methods, then you first have to fill the mappings Placeholder name -> Placeholder value for both header and line placeholders, and afterwards to use the DocEmailTemplateManager::sendMail() method in order to send an email with a dynamic table in the body, as shown below.

Sending emails using your own X++ method

You can also use your own logic for sending emails with a dynamic table in the body but you need first to fill mappings for header and line placeholders using the DocEmailTemplateHandlerBase::fillMappings() method, and afterwards to replace all placeholders in the email body and subject using the DocEmailTemplateManager::generateEmailBodyAndSubjectWithDynamicLines() method.

Resources

Download custom email handler class >>
Learn about sending emails using Docentric APIs >>
Read how-to manual on improved Email templates >>

7 thoughts on “Improved Email Templates – Creating Email Body with Dynamic Table

  1. Hi Team,

    I would like to know on how feasible it works for generating data from join tables and display method or calculation values.

    Regards,

    Ravisankar

    1. Hi Ravisankar,

      You can achieve quite complex scenarios using Email templates but in order to help you, please describe your concrete scenario. You can also contact us at support@docentric.com. We are always eager to hear about different use cases!

      Kind regards,
      Ana

  2. Hi Team,

    How can I hide the dynamic table when there is no data in it?

    Example:

    The dynamic table has 0 rows, but it still shows the header and values as zero. I need to hide the table when there is no data.

    1. Hi,

      Before creating and sending an email message, you can check if there is no data (lines) used for populating the dynamic table in the email template, so in that case you can use a different email template without the dynamic table.

      Alternatively, you can create a pre-event handler for the DocEmailTemplateManager::generateEmailBodyAndSubjectWithDynamicLines() method and pre-process the email body with placeholders as a string containing HTML to remove the empty HTML table. This code could look like this:

      const str repeatingBlockMarkStart = '<!‐‐%HIDDEN_TABLEBEGIN%‐‐>';
      const str repeatingBlockMarkEnd = '<!‐‐%HIDDEN_TABLEEND%‐‐>';
      int posBegin = strScan(_emailBodyWithPlaceholders, repeatingBlockMarkStart, 1,
          strLen(_emailBodyWithPlaceholders));
      int posEnd = strScan(_emailBodyWithPlaceholders, repeatingBlockMarkEnd, 1,
          strLen(_emailBodyWithPlaceholders)) + strLen(repeatingBlockMarkEnd);

      if ((posEnd – posBegin) > strLen(repeatingBlockMarkStart) + strLen(repeatingBlockMarkEnd))
      {
        emailBody_FirstPart = subStr(_emailBodyWithPlaceholders, 1, posBegin – 1);
        emailBody_LastPart = subStr(_emailBodyWithPlaceholders, posEnd,
              strLen(_emailBodyWithPlaceholders));
        newEmailBody = emailBody_FirstPart + '<BR>' + emailBody_LastPart;
      }

      Hope that this helps.
      Kind regards,
      Ana

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 >>