Below are some restrictions to keep in mind when using FreeMarker code to dynamically reference fields.
Test Emails
Most FreeMarker code will not populate in an email that's been sent via the Test button. This is normal. This is because there is no specific recipient (Account or Contact) associated with the test email that is sent (clicks and opens are not tracked either on Test emails for this reason). Click processes emails sent using the Test button in a different way than emails sent using the Send button or by another means of executing an Email Send, read more about Test emails here.
Relationships
1. FreeMarker can only pull data from the recipient’s Contact/Account record and from records of entities that this Contact/Account has an N:1 relationship with.
You can think of it this way: if the recipient’s Contact/Account record can have more than one related record of a given entity (a 1:N or N:N relationship), the FreeMarker has no way to determine which of those potentially multiple related records to pull from.
2. FreeMarker can only reach one level beyond the recipient’s Contact/Account record.
For example, you can pull data from the recipient’s Contact’s related Owning User record, but you cannot go further and pull from a record that is related to this Owning User.
NOTE: FreeMarker references to fields from the Email Send record are restricted to fields that are on the record itself. Data from entities linked to the Email Send via lookup field, such as the associated Campaign, are not accessible.
3. FreeMarker cannot pull from multiple lookup fields that reference the same entity within a single template, even if the lookup fields point to different records.
For example, you can pull from the recipient’s Contact/Account record’s Owning User record, but you could not in the same template pull from another different User record that is also related to that Contact/Account.
Making Child Record Data Accessible to Dynamic Content
As mentioned above, data from child records that the recipient Contact/Account record has a 1:N or N:N relationship with cannot be directly accessed via Freemarker, but there is a workaround that allows for that data to be referenced. The basic idea is to use custom fields and processes to take data from the FreeMarker-inaccessible child records and place this data onto a FreeMarker-accessible Contact/Account record.
For example, create two custom "Upcoming Appointment" fields on the Contact entity and then set up a workflow that runs on the creation of an Appointment record and updates the associated Contact’s "Upcoming Appointment 1" or "Upcoming Appointment 2" field as appropriate. Once this is set up, you can pull data from the Contact’s "Upcoming Appointment" fields just like you would any other field on the Contact record.
Look-up Fields
Data from a record connected to the recipient via a Lookup field, such as a Contact's parent Account, can be referenced in an email via FreeMarker, but the FreeMarker will need to be modified in order to reference any data other than the connected record's name.
${Recipient.contact.parentcustomerid[0]!""}, the out-of-the-box FreeMarker for the Contact's Company Name field, will let you reference the name of a Contact's parent Account's name, but nothing beyond that. To reference additional data from the Account record, the FreeMarker will need to be expanded to include the name of the entity connected through the Lookup field as well as the name of the field that should be referenced.
For example, ${Recipient.contact.parentcustomerid.account.emailaddress1[0]!""} will let you reference the value in the Email field on the Account record linked to the recipient Contact via the Company Name (parentcustomerid) field.
The FreeMarker for referencing parent Account fields is provided in the same Personalization menu as FreeMarker for the Contact record's fields (they are listed alphabetically after all of the fields on the Contact itself), but FreeMarker for any data accessed through other Lookup fields will need to be created manually.
Combining Look-up and Additional Fields
When a template includes freemarker that references a lookup field as well as freemarker that “reaches through” that same lookup field, this creates an ambiguous situation that the freemarker engine cannot resolve and will cause the Email Send to fail with a render error: "Only elements with no child elements can be processed as text."
This can be easily worked around by adding ?children before the [0] at the end of the freemarker interpolation that directly targets the lookup field (i.e. the shorter interpolation that does not “reach through”).
To illustrate, when your template contains these kinds of interpolations it will fail with an error:
- Reaches Through: ${Recipient.contact.new_division_id.new_division_entity.new_division_name[0]!""}
- Does Not Reach Through: ${Recipient.contact.new_division_id[0]!""}
To prevent the error, add “?children” as shown below.
- Reaches Through: ${Recipient.contact.new_division_id.new_division_entity.new_division_name[0]!""}
- Does Not Reach Through: ${Recipient.contact.new_division_id?children[0]!""}
For a more in depth discussion on Freemarker syntax, click here.
Quick Sends & Opportunities
When you choose to send a Quick Send email from an Opportunity record, Click will automatically connect the Opportunity record to the Email Send using your environment's Connections. This allows you to use FreeMarker to pull values from fields on the Opportunity record with this format: ${Recipient.opportunity.fieldname[0]!""}
If there is a lookup field on the Opportunity, you can get the value of the lookup field itself, but you will not be able to reference any other information from the connected record.
Parameters in URLs
When using Freemarker to add parameters to your URLs, the Freemarker code will require some minor edits in order to work properly. For example, the following code will not work if inserted in its current form into the link manager:
www.yourcompany.com?email=${Recipient.contact.emailaddress1[0]!""}
This is because the exclamation mark and extra quotation marks ( !"" ) at the end will cause the HTML behind the email to close prematurely and prevent the email from sending. To send correctly, you would need to remove the extra quotation marks like this:
www.yourcompany.com?email=${Recipient.contact.emailaddress1[0]}
Please note that making this change will prevent a backup value from being set for the Freemarker, so you may encounter issues if any participants do not have data in the referenced field.
Data Limits For Field Contents
We strongly recommend against using Freemarker to pull long strings of text data (i.e. entire paragraphs or more) from individual fields. Freemarker is intended to be used to pull pieces of content from your environment - using it to grab entire paragraphs or sections of text from Dynamics fields can cause your Email Send to go into an Error Recovery loop due to timeouts in your environment or due to Freemarker data processing limits in our email sending platform.