Data references

How it works

The most common uses of data references are:

• Pre-filling a field, such as the signed-in customer's email address, as its Default value
• Showing a field only to some customers, for example to one customer group, with display logic
• Putting the customer's answers into a notification email in a workflow

SparkLayer works out a reference's value when the form is viewed, submitted or updated, or when a workflow runs. You can use references in these places:

• Display logic and validation rules
• Default field values
• Options for select, radio and other choice fields
• Workflow conditions and actions
• Emails, API requests and calculations
• Entry views, filters and columns

Choose a reference

You pick references from the Select a reference picker, rather than typing reference paths.

1. Next to a setting that supports references, click Reference. In a text template, such as an email's From Name, click + Reference under the field.
2. In Select a reference, search with Search within results..., or browse. Click Open on an item to look inside it, or Select to use it.
3. The picker starts with common options, such as the form's own fields. For everything else, click See advanced options: Current entry, Data Tables, Forms and SparkLayer. To go back, click Return to common options.

The picker only offers references that fit the setting you're configuring. For example, a workflow calculation shows values you can calculate with, and an option data source shows lists. Items that don't fit are marked Wrong shape and can't be selected. That usually means:

• The setting expects one value, but the reference is a list
• The setting expects a list, but the reference is one value
• The type of value isn't compatible with the setting

Text templates also have + Condition and + Loop, and a Visual / Text switch to see the template as text.

Common references

Use this table to find the reference you need in the picker:

Current entry

The current entry is the form entry being viewed, submitted or processed. You can reference its answers, status, entry ID and internal fields. You can also reference the SparkLayer customer ID and details, the entry's created, updated and submitted dates, and its Dashboard admin URL.

For example: show a field when another answer has a certain value, include answers in an email, send form data to an external API, update an internal status field, or link to the entry in an admin notification.

Logged-in SparkLayer customer

When a logged-in SparkLayer customer fills in a form, references can use the customer linked to the entry. The form can then respond to who the customer is, not only what they typed. You can reference their:

• First and last name, email address and company name
• SparkLayer customer ID, external ID or accounting ID
• Customer group, customer status and role
• Tax exempt status and discount percentage
• Default billing or shipping address IDs
• Payment on account details, such as credit limit, balance, currency and net terms

For example: show different fields to different customer groups, route entries by customer group, include account details in workflow emails, send customer identifiers to an external system, or apply approval rules for customers with payment on account.

SparkLayer data

The SparkLayer references use wider B2B data from SparkLayer, not only the current form. Depending on where you use them, this includes customer groups and their settings, store details, customers and purchases.

Customer groups and settings

Use these when a form or workflow should follow rules you've already set up in SparkLayer. For example: show fields only to certain groups, check a request against group rules, route approvals by available payment methods, check whether quotes or checkout are turned on, or include group details in a notification.

What you can reference for a customer group

A group's slug, name and parent group, and its settings for price lists, address editing, checkout permissions, allowed payment methods, order quantity and total limits, credit limit enforcement, quotes and stock display.

Store details

Your store's name, email, phone number, website and address. Use them in templates, messages and workflow steps, for example in an email's From and To fields.

Purchases

Purchase references give access to SparkLayer purchases, including orders and quotes. For example: route a workflow by purchase or quote status, include totals in emails or API requests, look up a customer's purchases, check payment status or method, or use purchases, packages and line items as options for a select field. See the account credit request form for a worked example.

What you can reference for a purchase

• The purchase type, and purchase and customer identifiers
• Payment method and status, currency and calculated totals
• Quote status and dates
• Shipping and billing addresses
• Line items (quantities, SKUs and totals) and tax lines
• Shipments, with tracking details

Data tables

Data tables hold reusable lists. Use them as options for select or radio fields, or to look up values in workflows. Typical lists are items, regions or territories, dealer locations, approval rules, discount bands, licence types, industry categories, or mappings from customer group to approval outcome.

For example: fill a product dropdown from a data table, show only active dealer locations, look up a sales region from the selected country, find an approval rule by order value, or use a discount band in a calculation.

Other forms

Reference entries from another form when information is spread across forms. For example: offer submitted partner records as options in another form, look up a previous application, create a related entry in another form, update a connected record from a workflow, or build internal admin processes across forms.

Workflow and loop data

Inside a workflow, references can use calculation results, API request outputs, values created or updated by earlier steps, and the current item, index or item key in a For each loop.

For example: calculate a total and write it to the entry, use an API response in a later email, update each line item in a loop, branch on an earlier step's output, or send calculated values to another system.

Use references in conditions

Display logic, validation rules and workflow Condition steps all use conditions. The picker helps you choose compatible values for each side. For example:

• Show VAT number when Country equals "United Kingdom"
• Require Trade licence when Business type equals "Licensed trade"
• Continue a workflow only when Approval status equals "Approved"
• Apply a discount when Order total is greater than 1000
• Route an entry when the customer group equals "Wholesale"

Use references in templates

Some workflow settings and messages are templates, where you can insert references into text. Use + Reference to insert them, rather than typing reference paths. For example:

• Email subject: New application from {{ Customer Name }}
• Email body: Customer email: {{ Email }}
• API URL: https://example.com/customers/{{ Customer ID }}
• API body: include answers in a JSON payload
• Calculation: use numeric answers to work out totals, discounts or scores

Templates are used in emails, API requests, success messages and workflow calculations.

Use references as options

Select, radio and similar fields can take their options from a reference, instead of a list you type. This suits options that change often, long lists, and lists used in several places.

1. Select the field and open the Options section.
2. Switch from Manual to Data source.
3. Click Select data source... and choose a list in the picker. It shows Connected once a source is set.
4. If the source is a list of rows or objects, choose an Option label field: the value customers see for each option.

To start again, click Clear data source.

When the source is a list of simple values, each value is used as the label.

What's stored when a customer picks an option

The option's stored value is always the item's ID, such as a SparkLayer customer or purchase ID, a customer group slug or a repeater instance key.

For example: fill a product dropdown from a data table, list dealer locations matching the customer's group, let admins choose from submitted partner records, or use a repeatable field as the source for another choice field.

Filter references

You can filter some references before you use them. A filter narrows a list of entries, rows, customers or objects to the records that matter. Filters can use fixed values or other references. For example:

• Only data table rows where "Active" is true
• Products where "Category" equals "Accessories"
• The rule where "Country" equals the customer's selected country
• Form entries whose status is complete
• The first matching row, using one field from it
• Purchases for the entry's customer with a certain payment status

For example, a form asks for the customer's country. A workflow finds the data table row for that country and uses it to assign the right sales region.

Once you add a filter, it's listed under Active Filters, where you can Remove it. Then choose what to do next:

• Select this filtered set uses the list.
• Add another filter narrows it further.
• Clear all filters starts again.
• Navigate into filtered set picks a value from inside it.

The operators available depend on the field you filter, and include equals, not equals, contains, greater than, less than, is empty, is not empty, is true and is false.

Lists and single values

If you can't select a reference, check what the setting expects. Some settings need one value, and others need a list.

Settings that need one value include an email address, a customer name, a number for a calculation, a field to update, the first matching data table row or a customer group name.

Settings that need a list include rows used as options, items in a repeatable group, entries for a For each loop, a filtered set of data table rows or purchase line items.

Format values

In workflow templates, formatters change a value before it's used, for example to show "Not provided" when an answer is empty.

Every formatter

Formatter	What it does
Set fallback value	Uses this value if the reference is empty, for example "Not provided".
Convert to uppercase / Convert to lowercase	Changes the case of text.
Capitalize first letter	Capitalises the first character.
Truncate to N words / Truncate to N characters	Shortens text, adding "..." if it was cut.
Format decimal places	Shows a number to a set number of decimal places.
Convert to yes/no	Turns true or false into your own text, such as "Active,Inactive".
Format date	Formats a date or time. The format is written as an example date (a Go layout): 2006-01-02 gives YYYY-MM-DD, and 02/01/2006 gives DD/MM/YYYY.

Formatters can also join a list into one line of text (such as tags as a comma-separated list), extract one field from each item in a list, count items (such as line items) and format numbers.

Tips

• Use data tables for long or reusable option lists.
• Use customer references when logic depends on who's filling in the form, rather than asking customers to re-enter what SparkLayer already knows.
• Use SparkLayer references when logic depends on customer groups, settings, purchases, quotes or store data.
• Filter references to keep them specific. A filtered reference is usually safer than a whole list.
• Test with real examples: empty values, unexpected values, different customer groups and several entries. Test on the Preview tab, and above all on your store, signed in with the kind of customer account (or none) your customers will use.