Data References

data reference picker ui data references let you use dynamic data from forms, entries, customers, data tables, workflows, and sparklayer records across your form setup instead of typing a fixed value, you can reference data that already exists sparklayer resolves the reference when the form is viewed, submitted, updated, or when a workflow runs data references are used in places such as display logic validation rules default field values workflow conditions and actions emails, api requests, and calculations select, radio, and other option based fields entry views, filters, and columns common things you can reference here is a list of common references you might want to use, and where to find this in the reference picker ui what you want to use data reference in picker ui a value submitted on the current form current entry → entry answers admin only values attached to 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 data sparklayer → purchases reusable option lists (data tables) data tables entries from another form forms a previous workflow result current workflow run the current item in a loop current iteration how the reference picker works fields and configurations that support data references include a reference button references can also be inserted into templated fields the picker only shows references that are relevant to the place you are configuring for example, a workflow calculation will show values that can be used in a calculation, while an option data source will show lists that can be used as options some items can be opened to browse deeper others can be selected immediately if a reference cannot be selected, it usually means one of the following the field expects a single value, but the reference is a list the field expects a list, but the reference is a single value the value type is not compatible for the current context example of an incompatible reference option current entry references the current entry is the form entry being viewed, submitted, or processed you can reference submitted answers entry status entry id sparklayer customer id and data created, updated, and submitted dates dashboard admin url internal fields common examples show a field when another answer has a specific value include submitted answers in an email send form data to an external api update an internal status field in a workflow use the entry url in an admin notification logged in sparklayer customer when a form is used by a logged in sparklayer customer, data references can access the customer connected to the current entry this is useful when the form should respond to who the customer is, not just what they typed into the form you can reference customer data such as first and last name email address company name sparklayer customer id external id or accounting id customer group customer status role information tax exempt status discount percentage default billing or shipping address ids payment on account details, such as credit limit, balance, currency, and net terms common examples show different fields for different customer groups route submissions based on customer group or other details include customer account details in workflow emails send customer identifiers to an external system apply approval rules for customers with payment on account enabled please note that if a form is embedded on a page where the sparklayer core script is not included or loaded, or where the customer is not actively logged in, the form submission entry is created without an associated customer sparklayer objects sparklayer objects let references use wider b2b data from sparklayer, not only data from the current form depending on where the reference is used, this can include customer groups customer group settings store details customers purchases important please make sure that you filter any data references to the correct customer records when building external customer facing forms for example, when attaching purchases data source to a select field, ensure to filter by entry > customer > id to ensure the customers only see their own purchases customer groups and settings customer group references are useful when forms or workflows need to follow rules already configured in sparklayer you can reference data such as group slug group name parent group price list settings address editing settings checkout permissions allowed payment methods order quantity limits order total limits credit limit enforcement quote settings stock display settings common examples show fields only for customers in certain groups validate a request against customer group rules route approvals based on payment method availability check whether quote or checkout behaviour is enabled include customer group details in an internal notification store details store details can be used in templates, messages, and workflow steps you can reference store name store email store phone number store website store address common examples add store contact details to email from and to fields include store information in generated messages purchases purchase references can access sparklayer purchasing you can reference data such as purchase type purchase identifiers customer identifiers payment method payment status currency calculated totals quote status purchase dates shipping or billing address details line items, quantities, skus, and totals tax lines shipments and tracking details common examples route workflows based on purchase or quote status include purchase totals in emails or api requests look up purchase data for a customer check payment status or payment method use purchases, packages and line item data as the options data source for select fields data tables data tables are useful for reusable lists of structured data examples selectable items lists regions or territories dealer locations approval rules discount bands licence types industry categories customer group to approval logic outcome mappings data tables can be used as option sources for select or radio fields, or as lookup data inside workflows common examples populate a product dropdown from a data table show only active dealer locations look up a sales region from a selected country find an approval rule based on order value use a discount band in a calculation other forms you can reference entries from another form when information is managed across multiple forms common examples use submitted partner records as options in another form look up a previous application create a related entry in another form update a connected record through a workflow build internal admin processes across multiple forms this is useful when one form collects data and another form needs to reuse or act on it workflow and loop data inside workflows, data references can use data from previous workflow steps you can reference calculation results api request outputs values created or updated by earlier steps the current item in a for each loop the current loop index or item key common examples calculate a total, then write it back to the entry use an api response in a later email loop through line items and update each item branch a workflow based on a previous step output send calculated or looked up values to another system using references in conditions conditions are used in display logic, validation rules, and workflow branches example conditions 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” the reference picker helps you choose compatible values for each side of the condition using references in templates some workflow fields and messages support templates in these areas, references can be inserted into text examples email subject new application from {{ customer name }} email body customer email {{ email }} api url https //example com/customers/{{ customer id }} api body include submitted answers in a json payload calculation use numeric answers to calculate totals, discounts, or scores templates are commonly used in emails, api requests, success messages, and workflow calculations using references for option data sources select, radio, and similar fields can use a data reference as their option source instead of manually entered options this is useful when options change regularly, are a long list, or are used in multiple places common examples populate a product dropdown from a data table show a list of matching dealer locations based on current customer's group let admins select from submitted partner records use a repeatable field as the source for another option field when the source is a list of simple values, sparklayer can use each value directly as the option label when the source is a list of rows or objects, choose which field should be used as the visible option label the option value is the id of the item for instance, it might be the sparklayer customer or purchase id, a customer group slug, or a repeater instance key filters and lookups reference filters ui some references can be filtered before they are used filters help narrow a list of entries, rows, customers, or objects to only the records that matter examples use only data table rows where “active” is true find products where “category” equals “accessories” look up a rule where “country” equals the customer’s selected country select form entries where “status” equals complete find the first matching row and use one field from it find purchases for the customer associated with the current entry and where the payment status matches a certain value filters can use fixed values or dynamic values from other references example a form asks for the customer’s country a workflow looks up a data table row where the country matches that answer, then uses the matching row to assign the correct sales region available filter options depend on the type of field being filtered common operators include equals not equals contains greater than less than is empty is not empty is true is false lists vs single values some places need one value others need a list single value examples an email address a customer name a number used in a calculation a target field to update the first matching data table row a customer group name list examples rows used as select options items in a repeatable group entries processed by a for each workflow step a filtered set of data table rows purchase line items if a reference cannot be selected, it may be because the place you are configuring expects a single value but the reference points to a list, or the other way around formatters in workflow template based fields, formatters can change a referenced value before it is used examples convert text to uppercase or lowercase use a fallback value if the reference is empty join a list into a single line of text extract one field from each item in a list count items in a list format a date format a number common examples join selected tags into a comma separated list count the number of line items format a submitted date for an email use “not provided” when an optional answer is empty best practices use data tables for reusable or long lists of options use customer references when logic depends on who is submitting the form this is often better than asking the customer to re enter information sparklayer already knows use sparklayer object references when logic depends on customer groups, settings, purchases, quotes, or store data use filters to keep references specific a filtered reference is usually safer than referencing an entire list test with real examples check empty values, unexpected values, different customer groups, and multiple entries test both in the preview tab, but more importantly on the actual store, using the type of customer account (or not logged in) that the target user will use