Working with email templates in Unified Service Desk

Email templates are quite useful for creating consistent email experiences for customers. Of course, email templates also save a good deal of typing.  In this post, I will first discuss email templates in CRM, then discuss how Unified Service Desk can enhance the usage of email templates for your Contact Centers.

Templates in CRM

In CRM, there are two types of email templates, global and entity based. 

Global Templates are those which are not associated with any particular entity. When creating the template, you have access to data fields from only one entity, the systemuser or the currently logged in user's record. This is perhaps most useful for creating a standard signature for these emails. Such emails cannot contain data fields for other entities that might be useful. For example, suppose you wanted to pull in the contact's name to insert into the email body. This is not possible in a global email template in your standard CRM email experience.  That brings us to the second type of email template in CRM, that of the entity type. These are email templates that are related to some entity or record in the system. These can have Data Field Values from that entity and related entities. In our example, we could insert the contact's name in our email. What makes these types different is that entity type templates require you to have selected the record in the system from which the email will be created. Within the UI, this manifests itself by filtering the available list of templates to global and entity templates that relate to the entity that is selected.

A contact template, for example, may have links to data field values that will be populated with data from the selected contact record and merged at runtime.  In the template editor in CRM, these fields will be encoded and will appear as yellow fields as shown below.

 When the email is sent, the values from the selected record are applied to the template for the email creation process.  The resulting email looks like the following.

Templates in Unified Service Desk

When templates are used within Unified Service Desk, their capabilities are expanded significantly.  Templates are no longer limited to pulling data from a single entity, global templates or entity templates.  In fact, templates that are used in USD can contain replacement parameters which allow data to be included from any entity or even external applications where data was captured from the automation tools. Additionally, when we are using Unified Service Desk, we can do the merge, create the email, and then display it to the user so that the user could do final edits before sending it out, if desired. 

When a template is going to be used in Unified Service Desk, you can include replacement parameters as in the following email template.

You may also mix and match and include traditional data fields as desired.  Keep in mind that if you create email templates like this, these fields will not be replaced when using the Send Direct Email link directly in CRM.  It is important to understand this so you can create a strategy to either remove this option, or to name your USD templates such that they do not get confused with ones that will work in the CRM web client. 

Once we create our USD enabled email template, we can use it within the application.  Let us suppose that we are viewing a KB article within Unified Service Desk and we want to use the above template to send a link of the article to our contact.  For now, lets plan to display the resulting email before sending it out so the user has the opportunity to make final edits before clicking Send.  There are a few steps we need to perform to achieve the desired result.

1) Create and generate the merged template

Unified Service Desk's CRM Global Manager hosted control has an available action called GetTemplate. This action is used to obtain a CRM template and optionally merge traditional data field values. The name parameter should specify the name of the template to be retrieved from the system. The following Action Call would obtain a global email template with the name, "SendLinkInEmailFromKBArticle."

If you are using an entity template instead, you must include the id of the record that will be associated with the merge process.  For example, if we have an account email template, we should include the id= parameter in the above action call and provide an account id as a replacement parameter as in the following:

When this Action Call runs, it will pick up the current account id from USD's data parameter list and use it to merge data field values into the resulting template.  Once this action call is complete, a template data parameter will be created with the resulting merged template.

Notice that the data parameters still contain replacement parameters.  These values will not get replaced until the template is used and this is intentional. 

2) Create a new email

Now that we have the template in our replacement parameter list, we want to use it. The next thing we want to do is create and display the email. We could use CreateEntity to create the initial email if we wish, but to allow users the option of cancelling the email without the existence of the email activity surviving in the system, we will use the new email form instead. It turns out that the Create email form can be created and partially populated simply using URL addressable forms. We can display the email this way by calling navigate on the email control, which is setup as a CRM Page. This method allows us to auto populate the regardingobjectid field, which is helpful. 

After the navigate completes, the following new email will be displayed in the email hosted control. Notice that the Regarding field is populated. While this is a good start, we don't have the template inserted into the email just yet. Note that because URL's are limited to 2000 characters, we cannot just put the template data into the URL. That would not work.

3) Insert template into new email

Now that we have the email created and we have the template merged into our data parameter list, we are ready to insert the fields into the email to create the desired result. The next action call needs to run after the email is loaded. This is because we are going to inject some client side javascript. You can utilize the ExecuteOnDataAvailable action to create the delay, or simply put this action call in the BrowserDocumentComplete, which runs when the crmForm is loaded. In this case, we'll assume you place this in the BrowserDocumentComplete or PageLoadComplete for the Email control.

The RunXrmCommand runs javascript in the context of the crmForm. The script that is entered here should utilize the CRM Client SDK to maintain supportability.

Notice we are using the script to populate the description field, which is the body of the email, along with the subject, which is the subject line of the email. These are the fields for which the template supplies data. Ultimately the CRM Client SDK call boils down to a single method.

Xrm.Page.getAttribute("description").setValue('[[template.description]v+]');

This call does a couple things. First, it obtains a reference to the description field on the email. It then calls setValue, which sets the content of this field. Of course, we want to supply the data from the template that we captured earlier. This is where we use the replacement parameter to refer to the template data. The "+" option on this replacement parameter simply means that if the description in the template is blank or missing, we just want to insert a blank and still try to populate the subject. There is a special option on this parameter, "v". This option means that we expect the template description to contain replacement parameters of it's own and they should also be replaced. Think of it as a recursive call to replace parameters.

Once this Action Call completes, you'll see the subject and email body populated as follows.

That is basically all there is to using a template in USD. To complete the email, we may also want to auto-populate the "to" field as well. We can use the same technique of script injection to populate other fields on the form. To populate the To Field, use this script.

After this Action Call runs, the email is complete and displayed to the user. 

The only thing left is for the user to click the Send button to send the email and create the activity in the CRM server. The CRM server and email server will take care of the rest.

Example

This example is implemented in the Knowledge Management template for USD available in the USD Deployer tool.

How to use

Now that we have established the pattern for utilizing templates within Unified Service Desk, consider different ways we might initiate the process of utilizing this process. Perhaps the most common is to include a button on a USD toolbar to initiate the process. This is the method used in the KM deployer solution included with USD. Another way that I've seen customers initiate this process is from an agent script. Consider the scenario where the user selects a category of email templates, followed by selecting a subject, and then a specific template in a hierarchical method using the Agent Scripting control. This would allow for management, organization and use of a large number of templates. 

Another little interesting tweak on this scenario is that we could use various methods for detecting the language of the customer perhaps using azure translator to detect the chat language or perhaps using the preferred language of the customer to further refine which template will be used for the outbound email. Lets say a customer chats an agent and perhaps the chat system does live translation, such as Parature chat. The native chat language of the customer side could be obtained from the properties of the chat. Then when the agent selects the template to utilize for the outbound customer email and the template selected in the Agent scripting control, the system could automatically select the email template in the proper language that was pre-translated. In this way, the system could be more versatile in working with foreign languages and utilizing email templates in such scenarios. Of course, you could also use USD's Azure Translation action to auto translate the email on the fly if machine translation was acceptable in the business scenario.