Dynamics 365 for Finance and Operations - Workflows and E-mails

A basic function that clients often are interested in when making use of the Dynamics' workflow functionality, is being able to send and receive an e-mail when a workflow action occurs. Unfortunately, it is also one of those areas of the system where the configuration easily can get a bit tricky, given the number of required steps and lack of detailed Microsoft documentation.

In order to assist future D365FO-workflow newcomers, I have decided to make this tutorial, which hopefully can help you avoid the trial-and-error process that I initially had to go through. The article sections include step-by-step instructions on how to set up a simple (but dynamic) e-mail template or message, which automatically gets its information from a message configured within a workflow.

STEP 1: FIND OUT WHETHER YOUR WORKFLOW REQUIRES THE SETUP OF AN E-MAIL TEMPLATE OR E-MAIL MESSAGE

There is a subtle difference between "Email templates" and "Email messages" in D365FO (and AX2012 for that matter), which easily can be missed by those that are unaware. The difference between the two can be boiled down to three key points:

• An email template is company-specific (i.e. needs to be set up in each of the legal entities), while an email message is organization-wide (i.e. it's global and only needs only to be set up once).
• They are set up two different places in the system. Email templates are set up in the "Organization administration"-module (Organization administration > Setup > Email templates), while email messages are set up in "System administration"-module (System administration > Setup > Email > Email messages).
• Users cannot freely choose between the two, given that the choice depends on the workflow that the user is attempting to configure. Luckily, Technet has a list of the different workflow types in AX2012, which provides an overview of whether the individual workflow types are company-specific or organization-wide. The list can be used to find out whether an email template or message must be set up in your specific case (Link: Technet - Workflow types, AX2012). Fortunately, the list of workflow types also applies to D365FO.

STEP 2: EMAIL PARAMETERS

Set up the e-mail parameters (System administration > Setup > Email > Email parameters) in accordance with the instructions provided here by Microsoft (Link: Microsoft Docs - Email Parameters).

STEP 3: SETUP OF EMAIL TEMPLATES / EMAIL MESSAGES

The forms related to the setup of the actual email templates and email messages are more or less the same. In the following case, I will demonstrate how to set up an email message for when a expense report is submitted, approved, delegated and escalated - but anyone should be able to make use of the provided instructions for any other company-specific or organization-wide workflow type.

On the "Email message"-form, enter the following information:

• "Email ID"-field: Specify a unique ID related to the e-mail message.
• "Email description"-field: Provide a general description of the e-mail message, in order to be able to distinguish between the different e-mail messages.
• "Sender name"-field: Enter the name of the e-mail sender. The name will appear in the e-mail that is sent, so make sure to chose something suitable / trustworthy.
• "Sender email"-field: Specify the e-mail address that will be seen together with the "sender name" on the header of the e-mail that is received. The entered e-mail will need to be the one, which has been set on the "SMTP-settings"-tab on the "Email parameters"-form. If the e-mail address deviates from this requirement, the e-mail sending status will become "Failed" on the "Email sending status"-form (System administration > Periodic tasks > Email processing > Email sending status).
• "Subject"-field: Specify the e-mail subject that will appear on the "Subject"-line in the e-mail that is sent. You can either "hard code" the subject (e.g. "Expense management notification"), or use a placeholder that automatically picks up an appropriate subject from a notification set up within a workflow. In the latter case, enter the expression "%subject%" (without the quotation marks).
• "Language"-field: Specify the language of the e-mail. Multiple e-mail messages with different languages can be set up. The version that the user will receive depends on the language specified on the "User options"-form.

• Body of e-mail message: In D365FO, the body of an e-mail message/e-mail template is configured by uploading a file containing appropriate HTML-content. A simple way to handle this (if you are an HTML-rookie, like me) is to create a .txt-file, containing the code presented in the screenshot below. Once created, save the file. The %message%-part of the code is a placeholder that automatically picks up the notification text that has been set up on the workflow.

• Upload of body of e-mail message: Once the txt-file has been prepared, click on the "Email message"-button on the ActionPane. On the "Upload email template"-form, click on the "Browse"-button and find the file. After that, click on the "Upload"-button, and the "%message%"-part within the file will appear in the read-only text box. Click "OK" to finalize the setup of the e-mail message template.

STEP 4: CONNECTING AN EMAIL MESSAGE OR EMAIL TEMPLATE TO A WORKFLOW

Once the email message or template has been configured, open the workflow to which you would like to connect it. In the screenshot below, I have configured a simple workflow containing one fork (conditional decision), which routes the work item depending on who the submitting user is. Once the the Workflow Editor has been opened, do the following:

1. Select the frame of the workflow that you have configured.
2. Click on the "Basic settings"-button.
3. On the "Properties"-form that appears, select the e-mail message or e-mail template that you created earlier in the "Email template for workflow notifications"-field. If the e-mail message or e-mail template that you had set up does not appear, it probably means that you have configured an e-mail template instead of an email message (or vice versa) - depending on the type of workflow.

STEP 5: SPECIFYING THE ACTUAL E-MAIL MESSAGE

When configuring a workflow, you will have the option to send different e-mails depending on the workflow action that is executed - e.g. when (1) a user submits the work item, (2) approves it, (3) delegates it, (4) rejects it, or (5) when the a work item is escalated by the system. In order to set this up, select on one of the "Approval"-elements in your workflow, and click on the "Level down"-button on the ActionPane.

Execute the following steps:

1. Once you have gone a level down, select the "Step"-item and click on the "Basic settings"-button on the ActionPane.
2. In the "Work item subject"-field on the "Properties"-form, enter the text that should appear in the subject line of the e-mail that will be sent.
3. In the "Work item instructions"-field, enter the text that should appear in the main body of the e-mail.
4. In order to make the content of the e-mails dynamic, remember to make use of the standard placeholders that D365FO provides. The placeholders can be entered manually, or alternatively be found and selected by clicking on the "Insert placeholders"-buttons.

The outcome of the configuration above can be seen from the screenshot below, which contains an example of the e-mail that is received by an approver, once a user has submitted the work item.

Now all that's left, is to set up the e-mail messages for the remaining workflow actions. To do so, follow these instructions:

1. Click on the frame around the "Step"-item.
2. Click on the "Notifications"-button on the ActionPane.
3. Select one of the events on the "Properties"-form, and make sure to enable it.
4. For each workflow event/action, enter a message in the "Notification text"-field that must appear in the e-mail that is sent. Remember to make use of the placeholders to make the content of the e-mail dynamic and informative.
5. Specify the recipient(s) of the approve-, delegate-, escalate-, and reject-emails that are sent. To do so, fill out the information on the "Recipient"- and "Workflow user"-tabs. In most cases, you would want only the submitting user/workflow originator to be the one that gets informed. To set this up, select "Workflow user" on the "Recipient"-tab and "Workflow originator" on the "Workflow user"-tab.

Once done, make sure to save and activate the workflow with the latest changes.

STEP 6: ENABLE EMAIL DISTRIBUTOR BATCH JOB

When the workflow e-mails are sent directly from the server via SMTP, an "Email distributor"-batch job must be set up for the system to process the email queue. To create the batch job, go to "System administration > Periodic tasks > Email processing > Batch".

Remember to enable the "Batch processing"-switch, and specify the recurrence interval. The specified interval will determine how fast the e-mail will be sent after it has been generated.

STEP 7: USER SETTINGS

In order to enable workflow e-mails (and for users to avoid receiving a prompt every time e-mail is sent), the following set up must be performed for all users. Instructions:

1. Select the "Gear"-icon in the top right of the screen, and click on the "User options"-button.
2. Select the "Account"-tab.
3. Choose an e-mail provider in the "Email provider ID"-field. In this case, I am using the D365FO e-mail client (rather than the Exchange Online-server associated with the tenant, or an e-mail app like Outlook).
4. In the "Email"-field, enter the e-mail address to which you would like workflow e-mails to be sent. The e-mail in the "Alias"-field will by default be present in this field - but if you are a consultant attempting to test the configuration in a client-environment (e.g. by using a user with a "@onmicrosoft.com"-account), you are able to change the e-mail to your own here.
5. Click on the "Workflow"-tab.
6. Make sure that the "Send notifications in email"-switch has been activated.

That's it - you have now completed the setup of a simple (but dynamic) e-mail message/template, which automatically gets its information from a message configured within a workflow.

TROUBLESHOOTING

Good questions to ask yourself if the system refuses to distribute an workflow-generated e-mail:

• Is the work item being routed correctly through the workflow? If not, you might want to check your position hierarchy, or make sure that the workflow assignment-settings are correct.
• Is the "E-mail distributor batch"-batch job running? What is the recurrence interval? Could it be that the e-mails are just sent once every hour?
• Have you remembered to select the e-mail template/message on the workflow?
• Have you selected the right recipient on the workflow?
• Have have you remembered to upload a TXT-file with some HTML-coding that uses the %message%-placeholder?
• Is your e-mail on the "User settings"-form correct?
• Have you remembered to enable the "Send notifications in email"-switch on the "User settings"-form?
• Have the "Email parameters" been specified correctly?
• Have the workflow message placeholders or the email message/email template placeholders been specified correctly? If yes, try and remove some of the placeholders - e.g. the ones in the subject line - and re-test. I once experienced a situation in which a placeholder (%subject%) that I had used on the subject line of a e-mail template was blocking the e-mails from being sent.
• Have you entered the correct e-mail in the "Email sender"-field on the "Email messages" or "Email templates"-form?
• ... if you can answer yes to all of the above, it might have something to do with the email-server, in which case you most likely will have to contact your IT-department and/or Microsoft.