FreeMarker: Understanding Basic Render Errors

If FreeMarker is formatted incorrectly within an email template, you may experience a render error when you attempt to send the email.  If your email has a render error, it cannot be processed or sent out.

Goals

• Learn about simple FreeMarker mistakes that can prevent an email from sending.

Here are some basic causes of some render errors:

Forgotten Characters:

Every opening bracket needs a closing bracket. Every opening statement needs a closing statement.

• ${Recipient.contact.firstname[0]!""} is correctly formatted
• ${Recipient.contact.firstname[0]!"" would throw a render error since it is missing the closing bracket.

Incorrect Manual FreeMarker:

 When manually creating FreeMarker interpolations, incorrect references to entity fields that are inaccessible will cause render errors (remember, FreeMarker can only reach one level beyond the recipient's Lead/Contact/Account record).

• ${Recipient.contact.firstname[0]!""} is valid
• ${Recipient.contact.parentcustomerid.account.name[0]!""} is valid
• ${Recipient.contact.parentcustomerid.account.ownerid.user.fullname[0]!""} is not valid because the account owner's user record it too far removed from the contact to be referenced.

Custom fields in CRM are not recognized:

 When making custom fields in CRM on the Lead/Contact/Account record, be sure to not only publish your customizations, but also publish metadata within ClickDimensions Settings.  Custom fields will not appear within the personalization menu until after metadata has been published.

Missing tags in conditional statements: 

When using conditional statements in an email template, the Email Send will return a render error if any if Statements do not have a corresponding closing if tag.

• <#if firstname=="John"> Hi, John <#else> Hi, friend </#if> is valid
• <#if firstname=="John"> Hi, John <#else> Hi, friend will throw a render error since there is no corresponding </#if> tag

Spaces in Variable Names

Variables must be one word, otherwise they will throw a render error when you try to send the email. If you want to dynamically reference a CRM field whose name is more than one word, like Marital Status, you could represent that as a variable name as maritalstatus, marital_status, or any other style that removes the space between words. The variable name does not have to match the CRM field name, but we do recommend at least using a similar name so it is clear what the variable is being used for.

Curly Quotes:

Some programs, such as Wordpress or Microsoft Word, will generate curly quotation marks rather than straight quotation marks. Although this seems like just an aesthetic difference, using curly quotes instead of straight quotes in Freemarker will cause a render error. If you create your Freemarker directly within ClickDimensions' Email Editors, you will always get straight quotes. However, if you create your content in another program and paste it into the Email Editor, you may want to try deleting the quotation marks in your Freemarker and typing them back in to avoid this problem.

How to Check for Render Errors

Render error indications can be seen in a few places within your CRM environment:

Email Events:

It is normal for the first Email Event record in an Email Send to display the message "Request accepted. Beginning processing."  However, this message will display multiple times with no other type of Email Event records when a render error occurs.

Email Event Type=Render Error:

Some render errors will become apparent from an Email Event record type=Render Error.  The message will usually include details about what caused the render error to occur.

Background Processes:

 Navigate to the Sent Email Send record in question (CRM Marketing > Email Sends > Sent view > open the Email Send) and select Background Processes from the related menu.

Background Processes will show the set of workflows used to process and send out the Email Send. Open the workflow that indicates the error or failure, and scroll to the Details portion of the page. This will indicate what caused the render error.