Generating salutations for CRM contacts

Scope

In this blog post I’m going to show you how to easily generate salutations for contacts inside your Dynamics365 / Dynamics CRM system.

We’re going to use XTL, a solution that I developed, for text generating purposes.

XTL is a simple programming language, similar to what you can use inside reports or excel formulas. You can find a full reference on GitHub.

We’re going to install and configure it together for getting hands on experience.

XTL solutions are currently only distributed for CRM v9.0 aka Dynamics365, but technically >=v8.0 is supported. There are no solutions distributed for v8.x at this point of time, I hope to get that done soon.

Preparation

First, you’ll need to install the XTL solution from GitHub, just choose the latest release as managed solution.

Import it into your organization (be sure to check the “enable all contained SDK steps” flag) and open the solution afterwards.

 

Configuration

Create SDK step

XTL is a solution specifically targeted at generating texts inside Dynamics365. It offers a configuration editor which can be used for creating, updating, deleting, activating, deactivating and testing your templates.

For generating our first salutation template, open the configuration page inside the solution and select “Manage SDK Steps”. Select “Create New” and choose “Contact” as entity and create as message:

Leave the window open, we’ll come back later.

Localization

As for the template itself, you’ll probably always want a language dependent generation.

For this we can deploy the execution criteria. Execution criteria takes in a XTL expression and evaluates it for the current record. If the expression evaluates to true, the current template is applied, otherwise it is skipped and the record will not be modified.

We can use this behavior for cascading multiple steps after each other. Each of them can check the current record’s language to match his own and only execute in that case.

If you already have some way of saving the language for a contact, you can head over to the next section.

So let’s do this: For our example we create a new entity called language (my publisher prefix is “oss”, so it ends up “oss_language” with one name field and one called “{prefix}_isocode” (which of course is “oss_isocode” for me).

Add it to the form and the language entity is done for now:

 

Now let’s add a lookup named “{prefix}_languageid” to our new language entity on the contact entity and add it to the form:

 

Now our data model is ready. Create a language named “English (US)” with iso code “en-us” and one language named “German” with iso code “de-de” and reference both of them in some contacts.

Configure Template

Now we move on to actually configuring our XTL template.

First we need to define the output field of our template generation. Let’s use the default “salutation” field for this. You should also change the name to include the language that this template is used for.

Now we need to make sure that our template is only applied for German contacts.

For this you need to enter the following XTL code into the execution criteria:

IsEqual(Value("oss_languageid.oss_isocode"), "de-de")

This code jumps from the contact record to the language record using the oss_languageid field and retrieves the oss_isocode field of it. Afterwards it is compared to “de-de”.

As said above, this template will only be applied if the comparison evaluates to true.

For the template itself, we configure the following:

Sehr ${{If(IsEqual(Value("gendercode"), 1), "geehrter Herr", "geehrte Frau")}} ${{Value("lastname")}}

This code has a static “Sehr ” which is followed by either “geehrter Herr” if the contact is male (gendercode 1) or “geehrte Frau” if the contact is female (gendercode 2).

In both cases the last name is retrieved and appended.

Notice the ${{…}} around all expressions? This is how to tell XTL to resolve the expression inside the brackets, all other content is used as static content. You only need this inside the template, the execution criteria must not contain those brackets, as it must consist only of a XTL expression.

Now you can use the “Select Target” button for simulating your template with a contact. Select one that you set as German and click “Preview”. The result field should now properly show the salutation that was generated.

Inside the trace field you’ll find the interpreter output which shows you which XTL tokens were found, how they were processed and what they were resolved to. It is of great help to debug templates if you’re having issues.

Click on “Save” and the template is saved and will be executed on all contacts that you create:

Now create a new template for the English salutation.

Repeat the steps from above, i.e. adjust the name and enter salutation as field.

For the execution criteria enter the following:

IsEqual(Value("oss_languageid.oss_isocode"), "en-us")

Just as previously, this will check for the iso code and only apply the template, if the contact’s language is en-us.

Enter the following as template:

Dear ${{If(IsEqual(Value("gendercode"), 1), "Mr.", "Mrs.")}} ${{Value("lastname")}}

Again, this checks for the gender to be male and uses “Mr.” in that case, otherwise it uses “Mrs.”. These examples have been chosen for simplicity, if you ever need more than 2 cases, you can always nest if-expressions.

Select an English speaking contact as target and preview again. It should correctly generate an english salutation:

 

For our steps to be applied on updates of contacts as well (you’ll want to cover changes of their language, last name, gender), we need to recreate our two previous steps with the same configuration, but with Update as message name of our step. In addition to that, we need to highlight our trigger fields to define our template to be executed once one of the fields is changed:

Testing

Now we’re finally ready to test directly on the forms.

Head over to the contacts list and create a new one. After creating, the salutation should be set according to the language that you selected. On updates of last name, language or gender the salutation should be generated again:

Perspective

As we saw, it is pretty simple to create localized templates using XTL.

You can quickly edit and test them using the editor.

In the future you can also define more complex templates, take a look at all the functions that are available: https://github.com/DigitalFlow/Xrm-Templating-Language#functions

In addition to that, you can use XTL for much more than just generating solutions: Maybe try using it as advanced e-mail templating engine which can insert tables of child records and retrieve data from further away than the CRM editor allows (more than 1 jump from your target).

Or use it to generate custom compound addresses and much more, have fun and profit!

If you find bugs or have new feature ideas, please submit them on GitHub.

Leave a Reply

Your email address will not be published.

RELATED POST

Link to Dynamics 365 records in UCI

Scope With the UCI getting used more and more, some have already noticed that the record links that can be…

HTML E-Mails with place holders in Dynamics 365

Scope E-Mails in CRM are very simple by default. But what if we want to have styles in them by…

Advanced Dynamics CRM E-Mail Templating

Scope Often customers have extended requirements for their mailing purposes. Not only do they often need a lot of information…