If you want to have better designed emails for your workflow notifications, check out how our free Dynamics 365 for Finance and Operations Add-On – Docentric AX Free Edition – can help you.
In this article we will demonstrate how to customize workflow email notifications for the Purchase requisition review workflow by adding WF specific placeholders such as Purchase requisition ID, Description and Total amount to the email body. Additionally, we will enable a dynamic table bound to the lines of a current purchase requisition containing Item, Line amount, Quantity, etc.
HTML designer with placeholders for Email templates
After installing the add-on, you will notice a new tab page Docentric settings. You need to turn on the Use Docentric email editor option first in order to use Email templates improved by Docentric. Because we will work on a workflow template, the Workflow emails option should be turned on as well. There is also a third field on this form Class for placeholders that you need to adjust but only if you want to have workflow specific placeholders in your emails, but we will come to this later. If you want to use only standard WF placeholders such as %subject% and %message%, it’s enough to select DocEmailTemplateAdvancedHandlerWFAL as Class for placeholders.
Note that because we are demonstrating how to customize emails sent out from the Purchase requisition review workflow, which is an organization-wide workflow (i.e. company neutral), we need to work with System email templates. The completely same procedure should be applied on Organization email templates when working with company specific workflow such as Purchase order review.
When you click the Edit button as shown in the image below, instead of the built-in read-only rich text enabled textbox you will enjoy the professional HTML email body editor.
Besides the editor with rich formatting options, you can use:
- WF specific placeholders such as %PurchReqId%, %LineItemName% and %LineAmount%. In order to use them, a developer has to extend the existing DocEmailTemplateAdvancedHandlerWFAL class to be used as Class for placeholders. For this example we created one such class DocPurchReqWorkflowEmailNotificationETHL that you can download at the end of the article..
- WF standard placeholders such as %subject%, %message% and %for%. If you need to use only these placeholders in the Field dropdown list, turn on the Workflow emails option. You can choose the default Class for placeholders (DocEmailTemplateDefaultHandler) or DocEmailTemplateAdvancedHandlerWFAL (which adds the WF entity link placeholder).
- Email templates standard placeholders such as %WORKER% and %COMPANYNAME%.. These placeholders you will always see in the Field dropdown list if you turn on the Use Docentric email editor option on the main form. Then DocEmailTemplateDefaultHandler is used for Class for placeholders. However, if you want to have %COMPANYLOGO% and %WORKERIMAGE% among them, then you have to choose DocEmailTemplateDefaultHandlerWithImages as Class for placeholders.
Note that not only text but also image placeholders can be used in the email body. Out-of-the-box we provide Company logo and Worker image, but you can define your own images (e.g. product images for Retail order emails) by implementing your custom Class for placeholders.
Besides, you will notice the Entity URL placeholder. When used, in the final email the navigation link to the workflow entity will appear, in our case to the corresponding purchase requisition. By clicking it, you will be navigated in your browser to the purchase requisition that you need to approve, directly from the received email.
When you click the Source button, you will see the HTML code. You will need to go to this mode for the following reasons:
- To adjust the dimensions of dynamic images. Note that you have to keep HTML attributes width and height beside the style attribute that also contain width and height properties, because of MS Outlook.
- To adjust the href attribute of the link to the WF entity. You will need to remove https:// from it.
- To wrap the repeating row of the dynamic table with the
<!--%HIDDEN_TABLEBEGIN--%> and <!--%HIDDEN_TABLEEND--%> tags.
This is how our email template looks like. The source HTML code is provided within the DocPurchReqWorkflowEmailNotificationETH class that you can download at the end of the article.
The next thing you can do before putting this email template in use is to send a test email using the Send test email button. You can choose between the Email provider and Email processing options. Email provider will send the test email directly to the specified email address while Email processing will save the email to Email sending status.
Set up which email template a workflow will use
Let’s go now to Procurement and sourcing workflows and set the email template we want to use for the Purchase requisition review workflow.
We also need to set when to send notifications (including emails). Let’s say that we want to be notified when a workflow is started and completed, but also when a purchase requisition is submitted for the approval.
Sending workflow email notifications
First check if you have workflow email notifications enabled in User options.
Now let’s create a purchase requisition with three lines and submit it to the review workflow.
Afterwards, when we open Email sending status we will see two new emails: one created when the workflow started, and the second created when the approval step started.
You will be able to click the navigation link directly in your email to open the approving purchase order in browser.
Take a look once again what was the template and what is the resulting email:
If you want to enable WF specific header and/or line placeholders in your workflow notification emails, just download this custom Class for placeholders and learn on a concrete example on how to do it. If you stumble upon any difficulties please feel free to contact us any time at firstname.lastname@example.org. We will be more than happy to help!