Dynamic Lookups

Modified on Mon, 27 Nov, 2023 at 1:00 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 user to dynamically generate form elements.


Create a Lookup


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



Choose the Lookup type either Data or Element and the source either Custom or Hosted (more on these below).

You will then need to give your Lookup and informative name 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 Source 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 to warehouse 124.






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


For an example for this check out out 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:

Element NameDescription
emailreturns the logged-in users email address e.g. jane@oneblink.io
firstNamereturns the logged-in users first name e.g. Jane
lastNamereturns the logged-in users last name e.g. Citizen
fullNamereturns the logged-in users full name e.g. Jane Citizen
usernamereturns the logged-in username
userIdreturns the logged-in users ID
providerTypereturns the logged-in users provider e.g. Google | Cognito | SAML
providerUserIdreturns the logged-in users providers ID
isSAMLUserreturns whether the user is a SAML user e.g. true | false
supervisorFullNamereturns the logged-in users Supervisor's full name
supervisorEmailreturns the logged-in users Supervisor's email address
supervisorProviderUserIdreturns the logged-in users Supervisor providers ID
picture
returns the logged-in users picture as a URL
phoneNumber
returns the logged-in users office or mobile number (depending on the claim)

Automatic Lookups


Lookups can be run automatically. If a lookup includes default or prepopulated data, the lookup will automatically run when the form initially loads. This can be used to populate forms immediately on load, or create entirely dynamic forms.


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 Server CLI examples.


Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select at least one of the reasons
CAPTCHA verification is required.

Feedback sent

We appreciate your effort and will try to fix the article