Overcoming Email Template Limitations in MS CRM

Printer-friendly version

MS CRM has a limitation that when you create an email template to use in a workflow, you can only base the template on a predefined list of entities. Adding to that is the frustrating fact that once you choose the source entity you can only add fields from a predefined list of related entities, so accessing fields from a custom entity isn’t possible with out of the box functionality.

For example, you can select “Case” as the main entity for an email template. Once you’ve selected that as your base, you can only insert fields from the Case and related User, Account, and Contact entities. The problem? What if you have a custom entity related to Case and you want to insert fields from that entity on your template in a workflow? It can be done, but it involves creating a number of custom workflow steps.

Business scenario

In my example, I’ll use the case entity. Cases are created in an online portal by customers when they receive defective products and need to return them. An email is sent confirming their case was created. As a part of the process of creating their case, they have to choose the brand of the product. To model this, the case entity has a lookup property that represents a link to the Brand entity (new_brand). Each brand record has its own custom email address (attribute named new_reply_email) that is stored on the brand record and inserted as the reply-to email address in the body of an email. Since you can’t access the custom brand entity on the email template to insert the brand email address, it has to be done using custom workflow steps.

Implementing the Changes

As an overview, there are four basic steps:

  • Create an email template. For the field that you want to replace, define (you can make it anything you want – it’s what you’ll use to search and replace later) a token as a placeholder. In my case, in the appropriate place in the body, I’ve inserted the token {!BrandPortalWarrantyEmail}.
  • Use a custom workflow step to create an email based on a template.
  • Use a custom workflow step on the created email to merge in your custom field(s).
  • Use a custom workflow step to send the merged email.

Below, I will expand on each of the above steps. Note: I’m assuming you have a working knowledge of how to create a custom workflow assembly and input/output parameters.

Creating the Email Based on a Template

In this step, there are three input parameters and one output parameter:

  1. The email template is an EntityReference. This input parameter allows you to specify the email template in the workflow designer so it’s not hard coded.
  2. The “to” recipient of the email as an EntityReference. This input parameter will allow you to access the fields on the case, user, account or contact in the workflow designer.
  3. The “from” user of the email as an EntityReference. This input parameter will allow you to access the fields on the case, user, account or contact in the workflow designer.
  4. The email that is generated by the custom workflow assembly is the output parameter, passed as an EntityReference.

The code for this custom workflow step uses InstantiateTemplateRequest to create an instance of the email template. The OrganizationResponse results of the execute request contains the merged, generated email based on the template you specified. The code to retrieve the email looks like this:

var email = ((EntityCollection)response.Results["EntityCollection"])[0]

After getting the generated email, you can use code to set the “to” and “from” recipients. Assign the email an ID by using the Guid.NewGuid() function and use the MS CRM service to create (service.Create) the email. Saving the email is key – things will fail if you don’t. Once the email is created, set the EntityReference to the email output parameter.

Merging Your Custom Fields

In this step, you have two parameters:

An InOutArgument EntityReference which will get populated with the email created in the previous step. It’s defined as an InOutArgument because it gets passed back out for the next custom workflow step.

An InArgument that is an EntityReference to the brand. This value is set in the workflow designer. Remember that the brand is a custom attribute on the case pointing to a custom entity called “Brand”.

This step receives the two parameters listed above. It uses the MS CRM service to retrieve the brand and the email. From the retrieved email, it reads the “description” attribute which is the body of the email. From the retrieved brand record, it gets the value of the field new_reply_email. Here’s where you get done what you really want – populating the custom field on your email template. Once you have those two fields, it’s simply a matter of using the string replace method. My code looks like this:

emailBody = emailBody.Replace("{!BrandPortalWarrantyEmail}", replyAddress);

Of course, this requires that you have the string {!BrandPortalWarrantyEmail} somewhere in your email template body.

After you’ve done your replacement, use the MS CRM service to set the body with your custom merged text and update the email and update the email reference, OutArgument, so you can access it in the last step.

Sending the Email

Once you’ve replaced the text, you can then use a third custom workflow step that will have a single InArgument, a reference to the email. In this last custom workflow step, all you have to do is execute a new SendEmailRequest (see here for an example) using the ID of the input parameter email reference. Your email should then be sent with the text merged in from your custom entity!

About the Author:

TopLine Strategies delivers the complete integration and development of sales, marketing and customer service technologies that enable corporate clientele to improve revenue streams and strengthen customer interactions. Our project management and consulting is designed to achieve timely delivery, 100 percent user adoption of the technologies we implement and deliver measurable returns on investments for our clients.

Comments (1)

Tuan Nguyen replied on

Thanks for the post. Very useful scenario and solution steps.

Related Blogs

TheReact Native Open Source roadmap was announced in Q4 2018 after they decided to invest more in the React Native open source community.

October is not just about pumpkins, fall foliage, and cooler temps anymore. October 2018 also means the exciting introduction of Microsoft Dynamics 365 for Customer Engagement.

Back in 2016, Microsoft introduced its intentions to refresh its CRM and ERP strategy with Dynamics 365. At the heart of its services was the Common Data Model (CDM).