Gears Macros

Overview

FreeMarker is the templating framework used throughout Accelerator. It is a powerful language that allows the use of dynamic information within Templates. Many resources are available on FreeMarker including the Official FreeMarker documentation and a beginner's guide.

While FreeMarker is a powerful tool in its own right, there are things specific to the needs of MessageGears that are not included by default. To address this, MessageGears has created some custom Macros to answer specific needs within the MessageGears product.

${Gears.date} and ${.now}

Gears.date and .now are both options for displaying the current datetime stamp. Both macros perform the same functions. Each datetime stamp benefits from additional parameters. These parameters allow for must customized formatting for dates. This is especially important if using these functions within the Audience SQL query.

Gears.date returns a value that needs to be converted. The ?string() function is an easy way to do this.

The commonly used parameters are:

.now functions accept the same parameters and more.

More modifiers for datetime values can be found here.

${Gears.requestId} 

The Gears.requestId macro returns the MessageGears-generated Campaign requestId. This value is only available after a Campaign request has been sent to the Cloud environment. The requestId is used when reporting on Campaigns or reaching out to MessageGears support. This requestId value is unique for each Job launched.

${Gears.correlationId}

This is a Cloud-specific value. The correlationId() is an optional value that can be populated with the unique id value used in the original data source. Assigning a value to the correlationId inserts a correlationId field in the Recipient XML.

${Gears.JobCategory}

Job category returns a value used for grouping Campaigns together for reporting purposes. A JobCategory is similar to a label. With this tool, multiple Campaigns can be labeled as a "Coupon Offer" JobCategory. This JobCategory can then be used to report on multiple Campaigns at once.

Setting a JobCategory is done within Accelerator. Navigate to Campaigns > Marketing and open a Marketing Campaign. Select the Settings tab. Within this tab, there is a field called Category.

Referencing the Gears.JobCategory macro pulls the value listed here for the Campaign. This value can also be seen in the Real Time Data Feed.

${Gears.doNotSend()}

If this tag is included in the Template of an email contact, then that contact will not be sent. This tag is often included within an IF statement to selectively cancel contacts based on conditions.

This macro can work with or without the parenthesis and additional arguments. Including a string with the doNotSend macro will display within the Accelerator error and is included within the logs of the Job.

This allows for multiple doNotSend macros within a template. Each instance may have a different reason included within the doNotSend macro.

<#if Recipient.days_since_last_purchase lte 15 && Recipient.lifetime_value gte 500>
 ${Gears.doNotSend("Recent High Value")}
<#elseif Recipient.coupon_enroll == "false">
 ${Gears.doNotSend("Coupon Opt Out")}
<#else>
 New Coupons in store!
</#if>

${Gears.addDate(<number of units>,"<date unit>","<Date>"}

The Gears.addDate macro is used to add to a Date value. It returns a date value that must be parsed and presented into a format. The same conversions available for the Gears.now and Gears.date macros above apply to the returned value of Gears.addDate.

The Gears.addDate macro takes three arguments:

1. Number of units - This value is an integer value for how many units (the units are the chosen in the second argument) will be added to the date.
2. Date unit - This value can be YEAR, MONTH, DAY, HOUR, MINUTE, SECOND, or MILLISECOND. This value must be entered into the second argument and is case sensitive.
3. Date - This date value can be presented in two possible formats: "yyyy-MM-dd HH:mm:ss" or "MMM dd, yyyy".

The first is the number of units to be added to the target date. The second is the unit of measurement that will be added. The final argument is the starting date.

Your next payment is due in 5 days on ${Gears.addDate(5, "DAY", Gears.date?string('yyyy-MM-dd HH:mm:ss'))?date}

${Gears.hash("<Hashing Algorithm>","<Value to Hash>")}

Returns a hash of its argument, typically used in click tracking and webpage reporting. Most common hashing algorithms are supported, including SHA-101, SHA-256, SHA-384, SHA-512, and md5.

${Gears.hash("md5", "Value to hash")}

${Gears.microsite()}

In some situations, a customer may have issues viewing the rendered email within a mobile device or due to email settings. A common way of handling this is to include a link to view the email content within a dedicated webpage.

A microsite() generates a link to this dedicated webpage that hosts the email content. The microsite() link is typically used within HTML as a link.

Click <a href="${Gears.microsite()}">here</a> to view content.

${Gears.isMicrosite()}

Another common use of microsites is to display sensitive information when the microsite is being viewed. If viewing the email content, sensitive information is hidden. If viewing the content within a microsite, sensitive information is now displayed.

The Gears.isMicrosite() macro returns a boolean value to determine if the content is being viewed through a microsite or through a web browser.

<#if Gears.isMicrosite()>
 Sensitive Information
<#else>
 Click <a href="${Gears.microsite()}"here</a> to view content through a web browser.
</#if>

${Gears.isForwardToAFriend()}

Returns a boolean value to determine if the email content has been forwarded to another party. This tool can be used to change links or hide personal information.

<#if Gears.isForwardToAFriend()}
 Have an account? Sign in <a href="www.oursite.com/account/email%20redirect/">here</a>.
<#else>
 View your account <a href="www.oursite.com/account/${Recipient.accountNumber}">here</a>.
</#if>

${Gears.track(link,link_id,link_name,url_append)}

This macro generates a tracking link using the provided parameters. It is used similarly to the unsubscribe and microsite macros. This function returns the redirect link with the appropriate information included.

Click <a href="${Gears.track('www.messagegears.com', '2', 'Redirect', '&account=Recipient.account')}">here</a> to visit the MessageGears website.

${Gears.deepTrack(link, link_id, link_name, url_append)}

${Gears.deepTrack(link, link_id, link_name, url_append)}

Create and track a deep link - used as part of our Deep Linking offering.

${Gears.beacon()}

Beacons are used to track what recipients have opened emails. By default, a beacon is inserted at the bottom of the email page by MessageGears. In most cases, this reliably returns information. Some email browsers may cut longer emails off and not render the bottom part of the email. If this is the case, then the default beacon is not triggered on email open unless the recipient selects an option to view the full email.

Using the beacon() macro, a beacon can be manually placed elsewhere within the email.

${Gears.unsubscribe()}

Generates and inserts the default MessageGears unsubscribe link.

Click <a href="${Gears.unsubscribe()}">here</a> to unsubscribe.

${Gears.replyToAddress()}

When configuring a Template, include the replyToAddress() macro within the Reply-to Address Header.

Navigate to Content > Templates. Open a Template, select the Email Content, and click the Subject/From Address tab. Here, email headers are configured.

Preview the Reply-to Address.

To avoid displaying the actual Reply-to address, populate the Reply-to Name within the Email Header.

Now, when previewing the email Template, the Reply-to Name is displayed.

${Gears.recipientLinkToken()}

The recipientLinkToken() macro generates a token for the recipient. This is used for Post Click Tracking. If a link goes from the Email contact to another platform like an App, this token can be communicated to the App for continuous tracking. The token generated by the recipientLinkToken() macro is unique to the recipient.

Setup of Post Click Tracking is predominantly outside of the MessageGears environment.

${Gears.sequenceAppend()}

A function that concatenates values into a provided sequence. FreeMarker does this already, but in an inefficient manner. The Gears macro that concatenates sequences compiles quicker.

The format is as follows:

<#assign [seq_name] = Gears.sequenceAppend([target_seq], [val1], [val2], ...) >

This macro can combine multiple sequences into one:

<#assign my_seq = Gears.sequenceAppend(seq_a, seq_b) />

This also supports combining individual values into a sequence:

<#assign new_seq = Gears.sequenceAppend(my_seq, 100, "string value", seq_b) />

Each argument given to this Macro is another value appended to the sequence.

To display the results of a sequence, a loop must be used:

<#list new_seq as x>
 <p>${x}</p>
</#list> 

${Gears.record('key', 'value')}

The gears.record macro allows users to record custom, non-recipient information (ex: which offer was shown to the recipient) on the MessageGears Render Event. Pass in a string, object, Gears FreeMarker Macro, or Recipient field into the value parameter and it will be recorded under the <Metadata> tag for consumption on the Real Time Data Feed.

1. Navigate to a template

2. Paste ${Gears.record('key', 'value')} into the template

3. Define ‘key’ as the identifier for the renderable value you wish to record. Example, ‘LoyaltyTier’

4. Define ‘value’ as the renderable value you wish to record. You can pass in a string, object, Gears Macro, or recipient field.
   
   When passing in a recipient field, you must first use FreeMarker Assignment to assign the recipient field to a variable. Then, you must pass the variable into the macro, not the recipient field name itself.

   1. String example:
      ${Gears.record('Promotion', '20off')}

   2. Gears Macro example:
      ${Gears.record('EmailAddress', Gears.hash('md5',Recipient.EmailAddress))}

   3. Recipient field example:
      <#assign Loyalty = Recipient.LOYALTYLEVEL>
${Gears.record('LoyaltyTier',Loyalty)}
      Use the personalization helper for quick access to FreeMarker Assignment

5. Preview your template to ensure there are no errors.

6. Set up a campaign using the Template and the Audience used for the Template.

7. When you launch the campaign, the rendered value will be recorded on the Render event under the <Metadata> tag along with each key for each recipient. Example: ${Gears.record('LoyaltyTier', Loyalty)} would record {“LoyaltyTier”:”Platinum”} if the recipient’s LoyaltyLevel is Platinum.

8. The rendered values can be accessed in Snowflake by using the job’s Request ID. The values will be in the recipient’s metadata

9. The values will also be included in the XML Render Event on the SQS queue

10. The user can access this information using the Real Time Data Feed.

For a full description of how to use this feature, click the following link.