# Data references

URL: https://docs.sparklayer.io/help/forms/data-references

Use data references in SparkLayer Forms to pull answers, logged-in customer data, customer groups, purchases and data tables into logic, options and templates.

> **Quick summary**
>
> - A data reference points to data that already exists, such as another answer, the logged-in customer, their purchases or a data table, instead of a fixed value you type. Simple forms don't need them. They're for forms that react to who's filling them in, or that reuse data you already have.
> - You add one with the **Reference** button (or **+ Reference** in text templates) in the form builder at **Forms** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/forms)). It opens the **Select a reference** picker, so you don't need to type reference paths. Forms is only in the SparkLayer Dashboard, not in the SparkLayer Wholesale app in Shopify admin.
> - References work in display logic, validation, default values, option lists, workflow steps, emails and API requests.
> - On customer-facing forms, always filter lists such as purchases to the current customer.

## 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](https://docs.sparklayer.io/help/forms/conditional-logic.md)
- Putting the customer's answers into a notification email in a [workflow](https://docs.sparklayer.io/help/forms/workflows.md)

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:

| What you want to use | Where to find it in the picker |
| --- | --- |
| An answer on the current form | Current entry > Entry answers |
| Admin-only values on an entry | Current entry > Internal fields |
| The logged-in SparkLayer customer | Current entry > Customer |
| Customer group rules and settings | SparkLayer > Customer Groups |
| Store name, email, phone or address | SparkLayer > Store Details |
| Orders and quotes | SparkLayer > Purchases |
| Reusable option lists | Data Tables |
| Entries from another form | Forms |
| A result from an earlier workflow step | Current workflow run |
| The current item in a loop | Current iteration |

## 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.

> **The customer must be signed in on your store**
>
> If the form is on a page where the SparkLayer Core Script isn't loaded, or the customer isn't signed in, the entry is created without a customer. The form builder's **Preview** tab has no customer either, so test customer-based forms on your store.

## 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.

> **Filter customer data on customer-facing forms**
>
> On forms customers fill in, filter references to the right customer. For example, when you use purchases as the options for a select field, filter them by `Entry -> Customer -> ID` so customers only see their own 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](https://docs.sparklayer.io/help/forms/account-credit-request-form.md) 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](https://docs.sparklayer.io/help/forms/data-tables.md) 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](https://docs.sparklayer.io/help/forms/workflows.md), 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.