I cannot express the number of times I’ve spoken with other Marketo users who are interested in getting started with using Velocity Script tokens, but they have no idea where to start. The truth is, it IS hard to get started, but only because there aren’t a ton of resources that help paint the broad picture for what Velocity is, how it works, and why it might make sense to use. Hopefully this piece can start to fill that gap.
Overview
- Introduction to Velocity
- When to Use Velocity Script Tokens
- Tools of the Trade & Best Practices
- Creating & Testing Tokens
Introduction to Velocity: What is Velocity Scripting?
Velocity is a coding language built on Java used for scripting content. With it, you can create powerful personalization in your email assets, resulting in more customized experiences for your prospects and customers.
As we get started here, I want to state upfront that Velocity can be… a bit of a rabbit hole. But we don’t need to go down it right now. Developers can use Velocity to do some truly incredible things, but in this intro we’re going to focus on some simpler applications of Velocity that marketers can take advantage of to improve their email marketing campaigns.
Velocity can access fields on your contact object, and it can also access Opportunity data and Custom Objects, which can all be used to create more advanced logic to power dynamic content in emails. If you’re not familiar with the opportunity object or custom objects, literally ignore this paragraph. Not everyone uses them and you don't need to know anything about them to start using Velocity!
In Short: Velocity is a coding language for dynamic content that is more detailed and robust than snippets or traditional dynamic content.
MOST IMPORTANTLY: It’s Not Scary!
When to Use Velocity Script Tokens
The biggest question I get asked is WHEN should I consider a script token instead of more traditional snippets or dynamic content.
A few easy examples are:
- You need to reference multiple attributes on a contact record simultaneously. For example: You want to combine a Gender field + Last Name to create a single dynamic Hi [Mr./Ms./Mrs.] Lastname token.
- Show/Hide content section based on user preferences or other attributes. For example: Show a particular piece of content to customers if they are located in specific region.
For more on scenarios where it might make sense to choose Velocity over other approaches, there's an excellent Master Class piece by @Beth_Massura on Tokens vs. Snippets vs. Dynamic Content in Marketo Community.
Personally, I’ve run into so many seemingly relatively simple personalization ideas where building a segmentation and then creating the different versions in a piece of dynamic content just isn’t scalable. You want to combine 3 or 4 attributes into a segmentation, and all of a sudden you'd need to make 80 segments to account for your combinations. In those types of cases, Velocity scripts can be significantly easier to maintain at scale compared to segmentations, snippets, and dynamic content.
Tools of the Trade & Best Practices
Where to work? Marketo Editor vs. Offline Editor
Personally, I prefer to work with an offline editor like Notepad++ for a few reasons. Specifically, I like maintain a history of my tokens as I make changes, and I don’t have to live in fear of becoming disconnected from the internet randomly and losing all of my work. Of course you can always use Marketo’s editor, but it’s just personal preference.
- Marketo editor - Can be finicky, always online, possibility of disconnected from network and no changes saved. Easily access field names/references.
- Offline Editor (Notepad++) - Able to work offline, keep offline history of past token values, no fear of disconnected network. Negative: need to access Marketo editor for field names.
You can see in the editor, you have the left pane where you create/edit your code, and your right panel where you can access fields on opportunities, persons, and any custom objects you have connected to Marketo.
Personally I use Notepad++ with an updated highlighter that mimics the color coding of the Marketo editor (see the appendix at the bottom for how to set this up, makes my life a lot easier!)
Other Tips
Maintain an Offline Archive of Tokens
Keep in mind that Marketo does not maintain a history other than the date that a token was updated. I strongly encourage everyone to keep an offline archive of your tokens and try to maintain a history, that way you can always revert back to previous versions of your token if needed!
Document Changes to Tokens
With new versions of tokens, keep notes in the offline files documenting what changed in the logic with this new version of the logic. Or, use comments (more on that in a minute) to document changes right in the token logic itself.
Where you store tokens in Marketo matters!
Tokens can be stored in a Marketo Activities Folder or an individual Program. Tokens are accessible to all sub-folders and programs below the folder where the token is created, so make sure you’re creating tokens knowing where you intend to use it inside your programs.
Tokens intended to be used globally should be placed in the highest level folder of your instance. Some tokens may be program specific, build them into that program.
If you modify a token in a child folder, an "override" version of that token is created locally within that child folder and below. This can make things messy and should be avoided where possible!
Be Aware of Field Types
One other thing really as an FYI that's a little more advanced – Marketo-only and CRM Fields all get converted to strings when they are used in Velocity. What that means in normal human speak is that if you want to have your script do something like comparing numbers (e.g. greater than, less than, etc.), you have to convert those fields BACK to numeric values in your velocity script before you do the comparison. Honestly, that's another explanation entirely, but something you should be aware of!
Creating Tokens
At its core, Velocity scripting is like a big IFTTT (If This Then That) problem. If a record matches a certain set of conditions, do this thing or show this information.
Primary Query Operators:
#if – Starts an "If" statement. Works just like excel to check if a record matches your criteria.
#elseif – Allows for multiple #if statements if the record does not qualify for your first set of criteria.
#if recordtype equals "1", do this thing -> #elseif recordtype equals "2", do this other thing, etc.
#else as default choice for records that do not match any of your if statement criteria.
#end to close the script. If you forget #end, your email will likely fail to approve or send.
Logic Rules:
Once you start your #if statement, you use a few rules operators to write the criteria for the logic rules you are trying to achieve. Here are some basic rules operators that you can get started using:
AND: &&
OR: ||
Equals: $lead.fieldName.equals("value")
Does Not Equal: !$lead.fieldName.equals("value")
Contains: $lead.FieldName.contains("value")
Check if the Field Is Empty: $lead.FieldName.isEmpty()
Check if the Field is Not Empty: !$lead.FieldName.isEmpty()
SIDEBAR: Depending on your instance, if you want to use "contains" logic, it may make sense to make the value all lowercase so you don’t get tripped up by a rogue capital letter. You can do that with: $variable.toLowerCase().contains("value")
By combining your query operators with your logic rules, you can write a statement that will have a single or multiple conditions to check for, and then you can define what you’d like to show when someone meets your criteria. You can combine multiple operators using parenthesis just like advanced Smart List logic in Marketo, so you could say:
#if ($lead.fieldNameA.equals("1") && $lead.fieldNameB.equals("2"))
and the logic will look for BOTH conditions to be true.
If you want to use a True/False (Boolean) field in your logic, that should be coded as a "1" or a "0" for true or false.
Please understand that the logic rules of equals, and, or, contains, and isEmpty are only the some basic operators you can use in velocity. You can do extremely advanced searches in text, you can do sorting and ordered lists in your output, you can even build loops that run over and over for each condition that applied to that unique record. For this intro, I really wanted to simply highlight these simpler operators to get people introduced to Velocity.
Comments
Lastly, you can add comments or notes right inside your token code by starting a line with ## and Velocity will ignore that line. You’ll see the text turn gray and that won’t show anywhere in the output, but instead just lets you keep some notes right in context of your code so you remember what you did or what is supposed to happen in that section of code. I like to comment out my logic as much as possible so others can interpret what I am creating without me having to explain it in person.
Keep in Mind
People will only qualify for the FIRST #if statement they match. If you need to have outputs for multiple reasons, those are all separate #if statements, not #elseif statements.
So ALL that said, this is how you structure your token:
#if statement
Output for people who meet your if statement rules, can use token values here if you’d like.
#elseif for as many subsequent sets of criteria you have
Output for next set of criteria
#else
Default output for everyone who did not meet any of the if statements we created
#end
Identifying Field Names For Your Token
Probably the most confusing thing for people to figure out is how do you know what field names to use when you’re writing your logic? When you create dynamic content or snippets, you’re using your segmentations to pick when to personalize, but here you have to reference the field names themselves.
Easiest way: Open the Marketo Token Editor, find the field in the right-side pane, and drag it into the editor. Boom. You have your field name.
For your code, you should remove the backets {} around variable names as they are not necessary and clean up your code.
Examples
Honestly, I think seeing examples is the easiest way to learn Velocity, so let’s look at a couple.
In this example: We are creating a token to place in the Email From Name field that will show the contact’s Sales Rep Name for clients in Sales Groups 3 or 4 for the West region, and will show our brand name for everyone else.
You can see where we start our if statement, use our "||" and "&&" operators for our OR and AND rules, and then reference the Sales Owner First/Last name fields. Notice we have the final #else statement where we put the ‘default’ value for anyone who doesn’t qualify for our #if statement. Finally, our #end statement to close the script.
Creating & Testing Tokens
Putting your Code into Marketo
After you create your code, navigate to the folder where you want the token to be housed in Marketo, click on the My Tokens tab, and drag an "Email Script" token from the right panel into the pane.
Name your token
Click "edit"
Paste your code
IMPORTANT: On the right "Integration" pane, you have to check the box next to any field used in your token code! Otherwise, Marketo will not be able to access that field when running the script.
Testing your Token:
To test your token, you have two options.
- Send an email to test leads that meet your conditions (i.e., create test records and update them so that they pass or fail your script rules)
- Add real leads into a static list, and preview your email by that list.
Unfortunately due to the way test emails in Marketo are generated, you will want to avoid "Test Send" emails to test your velocity tokens. It does some weird things on the back sometimes don't always allow velocity to run correctly, so you'll want to stick with real email sends or previewing your email by your test list.
When you're creating or looking for leads in your database for your testing, make sure you're selecting leads that both should and should NOT meet your logic criteria, that way you can double check the logic is working as expected. In addition, make sure to test people where their values are blank for any or all of the fields you’re using in your code.
Troubleshooting tokens can be challenging at first, but as you learn Velocity and get more exposure, it will get easier to understand where your logic is failing!
Troubleshooting & Other Tips:
When the Marketo Editor first loads, it takes 3-5 seconds for the integration pane to load. Wait until this pane loads to begin editing / updating your token code in the window!
- Editing too quickly can cause an issue on the backend of Marketo where all integrations get reset behind the scene. Basically, your token stops working.
- Wait the 3-5 seconds for the right pane to load and begin working, you’ll never have the issue.
Sometimes the "Integrations" pane on the right side of the Marketo editor does not populate with any information ever. Try Hard Refreshing (CTRL+SHIFT+R) your Marketo window to resolve the issue.
Closing Out
Ok. That was a lot. A LOT a lot.
Here’s your checklist for making a new token:
- (Optional) Setup your offline editor, see appendix!
- Write out your logic requirements / rules
- You can do this using psudo (fake) code, or just writing down your rules in sentences. This can help you better understand your desired outputs for when you go to write your code.
- Use the Marketo editor to pull the field names you will use in your logic.
- Write your logic conditions and if statements using your fields.
- Find where you want to create your token in Marketo, add a script token, and open the editor.
- Once the integration pane loads, paste your code into the editor window
- Check off the boxes next to the fields referenced in your code in the integration pane, save your token.
- Identify your test cases and find your test records in your database.
- Add your token to a test email and send an email for your test records, or preview by list.
Custom Object Considerations
This is pretty technical, but if you DO want to use fields inside custom objects, those fields aren't 100% of the time available to velocity scripting. Custom Object data available to velocity scripting varies based on the Custom Object type (e.g. Marketo vs SFDC vs MSD) and the Custom Object record association (e.g. Contact vs Account related). The following matrices identify what field values are and aren’t available:
A complex CRM schema can create both positive and negative exceptions to the above with regard to SFDC and MSD. Every schema and CRM are implemented differently, check with you admins to investigate your implementations. If this whole section is confusing, don't worry about it. Bottom line is, the best way to really know if something on a custom object is accessible to use in Velocity is to open the editor and try dragging the field in.
Other Resources:
Honestly, the best resource for you to learn Velocity is the community. You can access any discussions tagged with Velocity here, or use the search to look for keywords closer to your exact scenario. There are countless threads discussing how to create certain tokens, specific logic, testing, etc. Besides that, the official velocity documentation was something I used a lot when I got started, but it’s not exactly thrilling reading (although, was this????), and obviously Google and Github can be resources to help answer a specific question you’re looking to answer. The TEKNKL Blog also has great info on Velocity!
BUT WAIT... THERE'S MORE
Can we look at one more quick example?
A really common thing I have seem firms use velocity for is showing/hiding a specific piece of content based on a user’s choices. Let’s say you have a lead collection form at your booth at a conference. In that form, you give the user 3 choices to select which topics they are interested in hearing from your organization about. Now, when you send your follow up you want to SHOW the content they selected on the form, and HIDE the things they didn’t select.
Doing this with snippets is insane, since you’d need to create a segmentation that accounts for every combination of those 3 choices (1; 1 and 2; 1 and 3; 1 and 2 and 3; etc…). With velocity, you simply write 3 quick tokens, one for each choice, which shows the HTML where that field is true, and shows nothing when it’s false. Pop those 3 tokens into the body of your email, and you’re done.
Using Velocity for dynamic content sections
The Real Closing
I know that’s a crazy amount of information. Re-read, start playing, you can do it. It’s really NOT that hard, just takes some time to get your head around. Questions, post a question and tag me @Chris_Wilcox . Follow me, connect, I’m around. I’m sure @SanfordWhiteman will have plenty to say too about your velocity scripts 😁
See you in the community! ALRIGHT, I’M OUT
-----
Appendix: Notepad++ Setup
- Install Notepad++
- Download @Casey_Grimes's Syntax Highlighter from Github
- Open Notepad++, Navigate to Language > Define your language
- Click "Import" and select the highlighter xml file
- Notepad++ will now color code files that end in .vm just like the Marketo editor does!
13 Comments
.png)