Home | Dynamic Content | Guest Post: FreeMarker language demystified

Guest Post: FreeMarker language demystified

The following post is printed with permission from one of our Certified Professionals, Steven Foster. Steven can be contacted at steven.foster@intergen.co.nz or @FozzyNZ or http://www.linkedin.com/in/stevefoster.

So you want to enrich your email content with information from other records in CRM, but you just cannot work out the construct required to enable this, help is at hand. The objective of this post is to make it simple!

The basics: What is this FreeMarker language?

Well you use it each and every time you send an email that includes the recipient's first name. When you select a field from one of the three drop downs – Account, Contact or Lead – then you are adding FreeMarker language to your email.

How can I add information from other records to the email?

There are two ways you can add information to the email from other entities as follows:

  1. Pull information from related records on the Recipient record. You can include any information from a record where a lookup exists on the recipient's form, i.e. you could pull the Parent Customer Account Name on to an email being sent to a contact by referencing the Parent Customer field.
  2. By using connections. When you connect a record to an Email Send record you can pull information from that connection into the email.

So how do I construct the FreeMarker language?

It's actually quite simple when you get your head around it. I will now attempt to break it down for each of the two options.

  1. Related Records approach
    You can pull information from the recipient record where a lookup (n:1 relationship) exists i.e. Parent Customer or any custom relationship you have created.

    For my example, I want to send an email as a follow up to a contact based on information stored on the last campaign that they participated in say an event.

    So in my CRM I have created a new n:1 relationship between Contact and a Campaign, and I populate the last campaign via a workflow when a campaign response is created. So in my customizations it looks like:


Now the key here is to note down the Name of the look up field as you will have to reference this in your FreeMarker language.

So now that I have the new relationship, I want to create an email send record that contains in the body of the email a reference to the Name of the Last Campaign Registered For. My syntax would look like this:

${Recipient.contact.demo_campaign.campaign.name}

Let's break this down:

  1. ${Recipient.contact.demo_campaign.campaign.name} – this represents the contact that the email will be sent to, if I was using lead then it would be $(Recipient.lead.
  2. ${Recipient.contact.demo_campaign.campaign.name} – this represents the schema name of the lookup field, in my case the lookup to the campaign
  3. ${Recipient.contact.demo_campaign.campaign.name} – this represents the primary entity of the relationship in our case Campaign
  4. ${Recipient.contact.demo_campaign.campaign.name} – this represents the field that I want to display in the email, in my case the Campaign Name

The key to getting this right is referencing the primary entity that the lookup refers to, so for parent account fields it would look like:

${Recipient.contact.parentcustomerid.account.name}

Where this will display the account name associated with the Contact.

  1. Via Connections
    This approach is simpler in context. In my scenario again, I want to send an email to all those that responded to a recent campaign, i.e. a campaign response was created and includes on the email, thanks for replying to Campaign "Name".

    I would create my list of recipients as a marketing list or manually add them to an email send via a view of contacts that responded to the campaign. I will then need to create a connection to from my email send to the Campaign using standard out of the box connections so it would look something like this:


Now for the FreeMarker piece, to include the campaign name in my email body I would use:

${Recipient.campaign.name}

Broken down this represents:

  1. ${Recipient.campaign.name} – whether you are sending it to a contact or lead it does not matter in this case so we only need to reference the recipient.
  2. ${Recipient.campaign.name} – the second part represents the entity name of the record you have connected to in this case Campaign, but if you connected the email send to a Case record then it would be incident or if to a custom entity new_customentity.
  3. ${Recipient.campaign.name} – The last part represents the field you want to display, in this case the name of the campaign.

You can now expand on this and connect to any entity and pull any data into an email and you can get quite creative.

One last pointer

You may ask what do the ${Recipient.contact.fullname[0]!""} bits at the end represent? These are optional but are good practice where in some cases the field you are referencing may not have a value as you can use a default value, see example below:

${Recipient.contact.fullname[0]!"Sir/Madam"}

In this case if the fullname is blank then Sir/Madam will be added to the email.

In Summary

Test and double test your syntax and check you have used the right schema names and you should be all good to creating advanced emails.

About the Author:

mm
The ClickDimensions marketing team is committed to helping marketers using Microsoft Dynamics 365 achieve their goals.

4 Comments

  1. Kevin July 14, 2017 at 11:21 am - Reply

    Hi there,

    Great post, thanks for clearing that up. I do have a question regarding the Freemarker, however.

    Would it be possible to combine both techniques used? For example:

    On the marketing campaign entity there’s a relationship with (let’s say) a case (the relationship name is campaign_incident).

    There’s already a connection between an e-mail send and a marketing campaign.

    Would I be able to have freemarker follow that relationship from the marketing campaign to fields on a case? This wil result in:

    ${Recipient.marketingcampaign.campaign_incident.incident.name}

    Your example illustrates this is only possible with the recipient tag.

    Would love to hear your answer.

    • mm
      Liz McBrayer July 14, 2017 at 2:57 pm - Reply

      Thanks for your question! Unfortunately, it isn’t possible to dynamically reference information on a case record that’s linked via lookup field to a campaign that is in turn linked via lookup field to the email send. FreeMarker only allows you to go one level removed via lookup fields.

  2. Prashant Sharma March 12, 2018 at 2:47 am - Reply

    Hi,

    Thanks in Advance.
    I am new to clickdimension, and i have a lot of questions in my mind but i will ask only one.
    Scenario:
    i have a lookup of User entity on Contact (Display Name: Secondary Owner, Schema Name: new_secondaryowner)
    and i am trying to get some details from user record in my email like below;

    ${Recipient.contact.new_secondaryowner.systemuser.fullname[0]!””}
    ${Recipient.contact.new_secondaryowner.systemuser.internalemailaddress[0]!””}
    ${Recipient.contact.new_secondaryowner.systemuser.address1_telephone1[0]!””}

    And i am not getting any value from above Script.
    Please help me

Leave A Comment