Working with Variables in SpringBoard

Overview

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.

165.png  166.png

Common Variables

Some of the more commonly used variables are described below.

  • Common Order Variables
  • 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.

Have more questions? Submit a request

Comments

Powered by Zendesk