Working with Variables in SpringBoard
Almost all of the information generated or gathered when a customer makes an order is stored in our internal variable structure. These variables can be used in multiple places within SpringBoard, including email fulfillments, external tracking, notifications, and custom reports. This article is meant to provide a general overview of how the variables work and what you can do with them; it is not meant to show how a specific task can be accomplished in a specific part of SpringBoard.
Variables
Variable names are constructed by combining static names together in a string, in descending order of specificity. For example, a customer email is held in the variable #{order.customer.email}. Each variable must open with #{ and is terminated with }. The links below can be used to explore the entire hierarchy of variables available in the system. Please note: you need to be logged in to SpringBoard to access these pages.
- Order variables: These variables relate to a completed order and are most often used in Order Completed Notifications, external tracking, and anywhere OrderItem variables are available.
- OrderItem variables: These variables relate to a specific product within a completed order, and are most often used in Email Fulfillments and Order Completed (one per product) Notifications.
- Subscription variables: These variables are used only with subscription products, and are most often used in subscription notifications, such as Subscription Activated Notifications and Subscription Deactivated Notifications.
- Return variables: These variables contain information related to the return or partial refund of an order.
When you click on any of the variable links above, some of the variables will be shown in blue and end with .___} as shown below. These variables are actually the highest level of name for the variable, and are just the start of a number of different variables. Clicking on these blue links will open a new window that will show all of the possible variables associated with the name. For example, clicking #{order.address.___} will bring up eight specific variables, including the first and second lines of an address, the city, and the country.
Common Variables
Some of the more commonly used variables are described below.
- Common Order Variables
#{order.id}is the ID of a customer's order#{order.customer.___}is information about a customer, such as first and last name, email address, and phone number.#{order.address.___}is information about a customer, such as first and second address line, city, and country.#{order.referrer}is the website that referred the order, the variable that is used to pass values into the order process and then get them at the end, the value gathered while using the process to collect previous license codes, and has a number of other uses.#{order.tags.<key>}is the value of any tag set as part of the order process, where <key> is the tag name.#{order.totalUSD}is the total value of an order in USD.
- Common Order Item Variables
#{orderItem.display}is a product name as displayed to the customer#{orderItem.fulfillment.file.url}is the secure download link so that the customer can download a file fulfillment you have on a product.#{orderItem.subscription.reference}is the main identifier, or API key, for a subscription. Note: The item must be a subscription product.
- Common Subscription Variables
#{subscription.reference}is the main identifier, or API key, for a subscription.
- Common Return Variables
#{return.original.id}is the ID of a customer's original order as related to the return or partial refund of the order
- There are many variables that are used commonly in Email and Web Templates.
Using Control Structures with Variables
While the majority of the time, you will want to get the variable value and display it, sometimes you may want to do more advanced logic based upon the variable values. The basic control structures available are:
<if test="xxx"></if><if has="xxx"></if><repeat value="xxx" var="yyy"></repeat><choose><when test="xxx"></when><otherwise></otherwise></choose><choose><when has="xxx"></when><otherwise></otherwise></choose>
When using advanced logic based upon the variable values, you can use the following abbreviations for logical comparisons:
- eq means equal
- ne means not equal
- gt means greater than
- lt means less than
Examples of Control Structures with Variables
To determine if a tag is present in an order:
<if test="#{order.tags.tagname gt 0}">Tag is Present</if>
To display each product name in an order:
<repeat value="#{order.allItems}" var="product">#{product.display}</repeat>
To determine if a custom referrer was passed into an order:
<if test="#{order.referrer eq order.httpReferrer}">Has custom referrer</if>
To display all coupons from an order:
<repeat value="#{order.coupons}" var="value">#{value} </repeat>
To display something based on the numeric quantity of a product
<choose><when test="#{orderItem.quantity eq 1}">Quantity: 1</when><otherwise>Quantity: More than 1</otherwise></choose>
To display download link and related text, based on the existence of the value:
<if has="#{orderItem.fulfillment.file}">Download Link: #{orderItem.fulfillment.file.url}</if>
We're Here to Help
If you need assistance writing a control structure with variables for a specific scenario, please open a support ticket.