Dynamic Lookups

Modified on Fri, 10 Oct at 2:47 PM

There are 2 types of Lookup, Data Lookup and Element Lookup.

Data lookups are used to dynamically populate existing form elements with data.

Element lookups are used to dynamically generate form elements.

TABLE OF CONTENTS

Create a Dynamic Lookup
How to Set up
Data Lookup
Element Lookup
Custom URL vs Hosted API vs Built In
Customise Error Messages
Offline
Example Lookup API
Get Help

Create a Dynamic Lookup

Dynamic Lookups can be created by clicking "Dynamic Lookups" on the left side menu and clicking the plus button in the bottom right of the screen.

Choose the Lookup type, Data or Element and the source Custom, Hosted or Built In.

You will then need to give your Lookup a Label and add the URL for the API endpoint.

Lookups can be configured across your environments, allowing for added versioning control across your apps.

For more on Environments, check out this article.

How to Set up

Navigate to the form builder, in the element details, there are the 'Enable Data Lookup' and 'Enable Element Lookup' switches.

Once a switch is turned on, you can select from one of your configured Lookups.

Now the element will include a lookup button to call the lookup endpoint, or for elements like autocomplete, selects, switches and radio buttons, the lookup endpoint will be called once the option is selected.

Data Lookup

The Data Lookup feature allows form elements to be populated form elements dynamically based on the values of specific elements.

For example, I want to search on a list of playgrounds and find the corresponding location and suburb. If you already have this information available, then you can create your own data lookup to automatically populate the location and suburb based on the Playground name.

When the lookup button is clicked, the form submission data is sent to the Lookup Sourc,e which dynamically populates the other configured form elements.

Element Lookup

The Element Lookup feature allows the form to be populated dynamically with elements based on the value of the specific element.

For Example, I want to do a stock take of a warehouse. I have a list of items I want to check are in the warehouse, but the list of items is different for each warehouse.

When the lookup button is clicked, the form submission data is sent to the Lookup Source, which dynamically populates the form with the configured elements.

In doing this, I can dynamically show the list of items based on the specific warehouse ID. Warehouse 123 has a very different list of items from Warehouse 124.

Element lookups can also be used to generate form pages and elements across those pages.

For an example of this, check out our GitHub example here

Custom URL vs Hosted API vs Built In

When creating a Lookup, you can choose to use a Custom URL. When choosing a Custom URL, you will be asked to provide the URL for the specific API endpoint you want the form data to be pushed.

Alternatively, you can use our API Hosting service to create your own custom hosted APIs for your Lookups to point to. When selecting OneBlink Hosted, you will be asked to select an API and a route for each of your available Environments. For more on our API Hosting service, check out GitHub API CLI.

Dynamic Lookups also allow for the user to exclude Form Definitions from the Lookup payload. This will reduce the size of the lookup payload and ensure that only the form submission data is passed through to your lookup endpoint.

We also have the option to use Built-In data as the source of our lookup. Essentially, we capture the logged-in users' information and use that as a data source for our lookup.

These are the following element names that work with Built-In lookups:

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

Customise Error Messages

You are also able to add your own unique error messages.

These are configured in the API.

Offline

Due to the lookup calling an external endpoint, this functionality will only work while online.

Example Lookup API

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

Get Help

If you have any questions or would like assistance with setting up your Lookups, please contact us via this support portal or email support@oneblink.io. We are happy to assist in any way we can.