Dynamic Lookups

Modified on Thu, 9 Jul at 12:48 PM

Dynamic Lookups allow forms to dynamically return data or form elements from a configured lookup source.

There are two types of Dynamic Lookup:

Data Lookup: Populates existing form elements with data.
Element Lookup: Generates form elements dynamically.

TABLE OF CONTENTS

Create a Dynamic Lookup
Configure a Dynamic Lookup on a Form Element
Data Lookup
Element Lookup
Lookup Sources
Custom Error Messages
Offline Use
Example Lookup API
Getting Help

Create a Dynamic Lookup

Dynamic Lookups are created from the Dynamic Lookups menu.

Step 1: Open the Dynamic Lookups menu from the left side menu under Developer Tools.

Step 2: Click the plus (+) button in the bottom-right corner of the screen.

Step 3: Choose the lookup type.

You can choose either Data or Element.

Step 4: Choose the lookup source.

You can choose Custom, Hosted, or Built In.

Step 5: Enter the lookup details.

Add a Label and, if required for the selected source, enter the URL for the API endpoint.

Dynamic Lookups can be configured across environments, giving you more control over versioning across your apps. For more on environments, check out the Environments article.

Configure a Dynamic Lookup on a Form Element

Dynamic Lookups are enabled from the element details in the form builder.

Step 1: Open the form in the form builder.

Step 2: Select the form element that will trigger the lookup.

Step 3: In the element details, turn on either Enable Data Lookup or Enable Element Lookup.

Step 4: Select one of your configured lookups.

Once configured, the element will include a lookup button that calls the lookup endpoint.

For elements such as autocomplete, select, switch, and radio button elements, the lookup endpoint is called once an option is selected.

Data Lookup

Data Lookups populate existing form elements dynamically based on values entered into specific elements.

For example, you may have a list of playgrounds and want to automatically populate the related location and suburb. If this data is already available, a Data Lookup can use the selected playground name to return the matching location and suburb.

When the lookup button is selected, the form submission data is sent to the lookup source. The lookup source then returns data that populates the configured form elements.

Element Lookup

Element Lookups dynamically generate form elements based on the value of a specific element.

For example, you may need to complete a warehouse stocktake where the required item list changes depending on the selected warehouse. An Element Lookup can use the warehouse ID to return the relevant list of items for that warehouse.

When the lookup button is selected, the form submission data is sent to the lookup source. The lookup source then returns the configured elements and adds them to the form.

Element Lookups can also generate form pages and elements across those pages.

For example, check out the GitHub Element Lookup example.

Lookup Sources

When creating a Dynamic Lookup, you can choose the source that the lookup will use.

Custom URL

A Custom URL allows you to connect the lookup to a specific API endpoint. When this option is selected, you will need to provide the URL that the form data will be sent to.

OneBlink Hosted

OneBlink Hosted allows you to use the OneBlink API Hosting service to create custom hosted APIs for your lookups.

When this option is selected, you will need to select an API and route for each available environment.

For more on API Hosting, check out the GitHub API CLI documentation.

Dynamic Lookups also allow you to exclude Form Definitions from the lookup payload. This reduces the size of the payload and ensures that only the form submission data is sent to the lookup endpoint.

Built-In

The Built-In lookup source uses information about the logged-in user as the data source for the lookup.

The following form element names work with Built-In lookups:

Form Element Name	Description
`fullName`	The current user's full name
`firstName`	The current user's given name
`middleName`	The current user's middle name
`lastName`	The current user's surname
`address`	The current user's address
`picture`	A URL for a picture of the current user
`email`	The current user's email address
`phoneNumber`	The current user's phone number
`role`	The current user's role or job title
`supervisorProviderUserId`	The current user's supervisor's user identifier
`supervisorEmail`	The current user's supervisor's email address
`supervisorFullName`	The current user's supervisor's full name
`areaCode`	The current user's area code
`city`	The current user's city
`state`	The current user's state
`country`	The current user's country
`countryCallingCode`	The current user's country calling code
`department`	The current user's department
`division`	The current user's division
`bargain`	The current user's bargain
`employeeNumber`	The current user's employee number
`departmentHeadFullName`	The current user's department head's full name
`departmentHeadEmail`	The current user's department head's email address
`username`	Returns the logged-in username
`userId`	Returns the logged-in user's ID
`providerType`	Returns the logged-in user's provider
`providerUserId`	Returns the logged-in user's provider ID
`isSAMLUser`	Returns whether the user is a SAML user (`true` or `false`)
`emailVerified`	Returns whether the email address has been verified (`true` or `false`)
`phoneNumberVerified`	Returns whether the phone number has been verified (`true` or `false`)
`groups`	A comma-separated string containing groups used to grant the current user access to approvals
`zipCode`	The current user's zip code
`postalCode`	The current user's postal code

Custom Error Messages

You can configure custom error messages for your Dynamic Lookup.

These error messages are configured in the API.

Offline Use

Dynamic Lookups call an external endpoint, so this functionality only works while the user is online.

Example Lookup API

For information on creating your own lookup API, check out the API Hosting lookup examples.

Getting Help

If you need any assistance with Dynamic Lookups, please reach out through the Report Issue menu or email support@oneblink.io.