USD – Email Templates

I recently needed to configure my USD application to send an email based on a template. Here is how I achieved this.

The situation I faced was that I wanted a toolbar button that would send an email to a customer associated with a case. This email was to contain details of a support case I have found in the knowledge base.

I am going to assume you’re a USD “expert”! By that I mean you already have the required logic to open the case and knowledge base article. In this post I will focus only on how the email template operates.

I will present the logic of using email templates using the example I have mentioned, hopefully you will be able to review and adapt to other purposes.

For my example, I needed five actions, a toolbar button and of course an email template.

I will break this change down into the following steps;

  1. Create email template.
  2. Create action, clear data parameter.
  3. Create action, to get email template.
  4. Create action, to open new email.
  5. Create action, to inject the template details into the email.
  6. Create action, ExecuteOnDataAvailable, to pause.
  7. Create toolbar button.

Step One – Create email template

The first step was to create an email template, well I say create. I actually copied this one from the Microsoft USD sample package! The important thing to notice is how I have inserted several USD style replacement parameters into my email template.

Step Two – Create Action, clear data parameter

So why do I need this? I found that my logic could fail it I sent multiple emails within one session. The reason relates to the ExecuteOnDataAvailable action we will see in a second. What I am doing here is clearing any existing data relating to a previous email. I am effectively clearing the stage ready for this new email.

Item Description
Name CRM Global Manager – Clear Data Parameter (email)
Order 5 (The order is significant!)
Hosted Control CRM Global Manager
Action ClearDataParameter
Data name=email

Here we are simply listing the name of the parameters I want to clear from the context.

Step Three – Create action, to get email template

The next step is to create an action that will copy the email template details into the context. My action looked like this;

Item Description
Name CRM Global Manager – Get Template (SendLinkInEmailFromKM)
Order 10 (The order is significant!)
Hosted Control CRM Global Manager
Action GetTemplate
Data name=SendLinkInEmailFromKM

id=[[incident.Id]+]

Here we are providing the email template name and the ID of the entity to associate with this template for the merge operation.

At this point it might be worth considering the result of this action! Having run it we will have copied some details, they show as replacement parameters in USD. These parameters are “under” CRM Global Manager#template, so [[CRM Global Manager#template.description]] etc.

Step Four – Create action, to open new email

Now we need an action to create an email. Mine is shown below, I used a New_CRM_Page action.

Item Description
Name Email – New CRM Page (Regarding case, to customer)
Order 20 (The order is significant!)
Hosted Control Email
Action New_CRM_Page
Data LogicalName=email

regardingobjectid=[[Incident.Id]]

regardingobjectidname=[[Incident.title]]

regardingobjecttypecode=incident

Here we I am providing the name of the entity to open and the regarding details. As I will want my email to be regarding the current case / incident.

Notice that I’m not setting the “to” field. There is a reason, I will mention later!

Step Five – Create action, to inject the template details into the email

Now we need an action to use the replacement parameters we grabbed from the template. [[CRM Global Manager#template.description]].

NOTE:
When I use these I add +v into them! [[CRM Global Manager#template.description]+v]. The “v” means that we expect the template description to contain replacement parameters of it’s own and they should also be replaced.

But the code below does more than just add the template in the subject and description of the email. I am also setting the “to” field. I could have set the “to” field in my “New_CRM_Page” action, so didn’t I? The reason is connected with entity type. As on the case I have the name of the entity for the customer field. That being “account” or “contact”. But the New_CRM_Page action need the entity number, so 1 for account etc. To get round this I decide to set the “to” field using the code below.

Item Description
Name Email – RunXrmCommand (Complete Template Details)
Order Blank, I don’t care about the order on this one!
Hosted Control Email
Action RunXrmCommand
Data Some code! (Shown below)

// ** Update the subject and description of the email
Xrm.Page.getAttribute("subject").setValue('[[CRM Global Manager#template.subject]+v]');
Xrm.Page.getAttribute("description").setValue('[[CRM Global Manager#template.description]+v]');

// ** Set the email to be to the "customer", which can be a contact or an account
var toLookupValue = new Array();
toLookupValue[0] = new Object();
toLookupValue[0].id = "{[[incident.customerid.Id]+]}";
toLookupValue[0].name = "[[incident.customerid.name]+]";
toLookupValue[0].entityType = "[[incident.customerid.LogicalName]+]";
var toObject = Xrm.Page.getAttribute("to");
if(toObject != null) {
  toObject.setValue(toLookupValue);
}

Step Six – Create action, ExecuteOnDataAvailable, to pause

The RunXrmCommand I have created needs to be run only once the email page is loaded. I therefore use an ExecuteOnDataAvailable action to wait for this to happen. The value I wait for can be any replacement parameter from the email. So I opted for [[email.Id]].

Item Description
Name CRM Global Manager – Execute On Data Available (Email, ready for Template!)
Order 30 (The order is significant!)
Hosted Control CRM Global Manager
Action ExecuteOnDataAvailable
Data Milliseconds=500

[[email.Id]]

The milliseconds wait time might be optional. I just added it to hopefully be confident I’d waited long enough!

Once created you will need to add a sub-action to this action! So select sub action calls from the navigation.

Then add the RunXrmCommand action we created earlier to this ExecuteOnDataAvailable action. The result is we are simply saying execute the RunXrmCommand action after waiting for the email to load.

Step Seven – Create toolbar button

The final step is to create a toolbar button and add the actions we’ve created. My toolbar button looked like this ….

I used an image for my toolbar button. It happens to be an email icon that I thought was appropriate. You could use a different image or simply opt to have some button text.

Notice the order of the actions we’ve created. This is significant!

Also notice I have a condition on my button. As I don’t want the button to show until I have selected a knowledge base article and an incident.

In my application the final result looked like this. Clicking on the email icon loaded the email. Populated the “to” and “regarding” fields. Plus filled in the subject line and description of the email. Complete with personalised data based on the information found in the case and knowledge base article.

Hopefully you will have found this post useful. I am confident I will be adding more email templates into my application as they really help to make the agents job easier.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s