Improved Email Templates

In Dynamics 365 for Finance and Operations and Dynamics AX 2102 you can set up Email templates for sending email notifications for Retail orders, workflows, alerts, etc. Often these emails need to include some dynamic information, and this can be achieved using placeholders.

However, in order to use placeholders in the built-in editor you need to know exactly what their names are. Unlike in AX 2012, in Dynamics 365 you don’t really have an editor at your disposal – you can upload already prepared HTML file that represents a dynamic email body, i.e. a body with placeholders.

Docentric AX Free Edition enables you to:

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

Let’s see how this work.

Docentric email body editor

Navigate to Organization administration -> Setup -> Email templates. Click the Docentric settings tab page and turn on the Use Docentric email editor checkbox.

When you click the Edit button located above the Email message content grid, the pop-up form is open but it contains Docentric email body editor instead of the built-in read-only HTML control.

Standard placeholders

In Docentric email body editor notice the Field dropdown list. It contains placeholders for the currently selected email, and this is defined by the Class for placeholders field.
When you turn on Use Docentric email editor option, a default handler class for placeholders is selected by default. This means that the Field dropdown list will contain only so called Standard placeholders such as Company info, Email description, Sender name, Worker info, Current date and time, etc.

This is not preventing you from using any other placeholder, but it would be nice that you can pick it from the Field dropdown list, right? This kind of placeholders that are specific per email we called Custom placeholders and they can be defined by introducing a custom email handler class.

Custom placeholders

Custom placeholders will appear in the Field dropdown list in Docentric email body editor if we choose a custom email handler class from the Class for placeholders combobox.

For example, if we select the Order Confirmation email handler class, we will get the following list of custom placeholders.

Now, the question is, how to create such a class and which rules should be followed.

Custom email handler class

When you need to define custom placeholders for an email, a new custom email handler class should be introduced. It should derive from the DocEmailTemplateHandlerBase class and implement at least two methods: description() and defineCustomPlaceholders():

You can also provide logic for supplying values for custom placeholders. This is not a mandatory step if you are using your own logic for sending emails, when you can fill the Placeholder name -> Placeholder value mapping outside this class before sending an email.

Let’s assume that we will supply the values for the custom placeholder within the class. We need to override and implement the fillMappingsWithCustomPlaceholderValues() method:

If you are using the built-in mechanism for sending emails, i.e. SysEmailTable::sendEmailTable(), or you are using Docentric APIs for sending emails, then you are done.

See how to use Docentric’s APIs to send emails >>

If you are using your own method for sending emails, then you need to invoke the DocEmailTemplateHandlerBase::fillMappings(_emailId, _languageId, _mappings) method before sending an email based on a template with the given _emailId.

This method will fill the _mappings Placeholder name -> Placeholder value with the values for all standard placeholders, and in case that you have implemented the fillMappingsWithCustomPlaceholderValues() method in your email handler class, it will provide the values for all custom placeholders as well. Otherwise, you will need to fill the same _mappings with the all custom placeholders’ values manually.

Before sending an email, you will also have to replace all placeholders used in the email body and subject. Learn how >>

Use email templates for workflow notifications

If you need to send email notifications from a workflow, you don’t have to introduce a custom email handler class. It’s enough to turn on the Workflow emails checkbox.

With the Workflow emails option turned on, all workflow related placeholders will appear in the Field dropdown list automatically.

Resources

Download custom email handler class >>
See how to create an email body with a dynamic table >>
Learn about sending emails using Docentric APIs >>

Leave a Reply

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