[Sharing the learning] - Merge fields in email templates

This is the first blog of a series where I want to share the learnings with you all. I have spent enough hours working on various approaches and found out the 'working' approach. I do not say that these are the best ways or only ways, but definitely they are not bad.

So, now to the topic..

Use case: Send email to the user and the mentor (manager field in user) when there is change in mentor. Simple right?

First thing that would come to your mind is to use workflow email alert. Even I thought so. First problem is you cannot access Manager's email directly in workflow email alert. There are some ideas (https://success.salesforce.com/ideaView?id=08730000000Y3KuAAK, https://success.salesforce.com/ideaView?id=08730000000hhSFAAY) in IdeaExchange.

Second, the email alert is always sent to the user who changed it, even when you use 'User Fields' under 'Available Merge Fields' in email template.

Definitely apex trigger is a solution. But it is always good if you can avoid coding if the solution can be achieved using point-and-click.

What I used is mix of custom field and workflows, as many of us have been doing for years now.

• Create a custom email field (Manager_Email__c) in user (hide it from page layout, ideally), because workflow email alert will not consider formula fields too
• Now create a workflow field update to populate this field with Manager's email address. You can use either,
• 'created, and any time it's edited to subsequently meet criteria' where the rule criteria will be Manager not blank
• Or 'created, and every time it's edited' where the rule criteria will be OR( ISNEW(), ISCHANGED( Manager ))
• Ensure that you check 'Re-evaluate Workflow Rules after Field Change'
• Next, create a workflow or create email alert to send email using this email field.

The catch here is the email template. The first template I used was as below:

Dear {!User.Name}, 

Please note the change of mentor / mentee with effect from {!Today}. 

Mentor: {!User.Manager}
Mentee: {!User.Name} 

Thanks & Regards
Salesforce Helpdesk.

I used the User Fields under Available Merge Fields

The result was surprising (at least till I understood the usage of merge fields). Whatever test I did, I, the current user, got the email alert, with my name and my mentor details.

After many hit-and-try, finally I read through the article on considerations for using merge fields in email templates. Highlighting below that is relevant to this blog/issue, but would encourage you all to read through the article.

User Fields — Use these merge fields to represent the sending user. Merge fields named {!User.field_name} return values from the user record of the person who created or updated the record that triggered the workflow rule.
Workflow Target User Fields — Use these merge fields only in email templates for workflow rules on the User object. Merge fields named {!Target_User.field_name} return values from the user record that was created or updated to trigger the workflow rule.

So the culprit was {!User.fieldName}. I changed the email template to the following:

Dear {!Target_User.Name}, 

Please note the change of mentor / mentee with effect from {!Today}.

Mentor: {!Target_User.Manager}

Mentee: {!Target_User.Name}

Thanks & Regards

Salesforce Helpdesk.

Though it looks very simple I had to spend lot of time understanding this.

To understand further, there are set of fields available under Sending User Fields and Receiving User Fields. Note that these merge fields work only for mass email and are not available in Visualforce email templates. Also to use it the user will need 'Manager Users' permission.

Trust this helps people who end up writing apex code, either a trigger or call apex through Process Builder. As always I welcome suggestions on making this easier or optimal.