There are 2 types of Lookups: 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.
Create a Lookup
Lookup can be created by selecting Lookup 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). Read more about these below.
You will then need to give your Lookup an informative name (Lookup Label) and add the URL for the API endpoint
Lookups can be configured across your environments, allowing for added versioning control across your apps.
How to Set Up Lookup
Navigate to the form builder. In the element details, there are the Enable Data Lookup and Enable Element Lookup switches.
Once a switch is activated, you can select from one of your configured Lookups.
Now the element will include a lookup button.
- Note: This will be disabled until the input contains a value.
The Data Lookup feature allows form elements to be populated with form elements dynamically based on the values of specific elements.
For example, I want to type just the ABN of a business and have the rest of that business's information automatically populate based on that specific ABN.
When the lookup button is clicked, the form submission data is sent to the Lookup Source which dynamically populates the other configured form elements.
The Element Lookup feature allows the form to be populated dynamically with elements based on the value of specific elements.
For example, I want to do a stocktake of a warehouse. I have a list of items that I want to check and locate 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.
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 that you want the form data to be pushed to.
Alternatively, you can use our API Hosting service to create your own custom hosted APIs for your Lookups to point to. When selecting Hosted API, 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.
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:
- email — returns the logged-in users email address e.g. email@example.com
- firstName — returns the logged-in user's first name e.g. Jane
- lastName — returns the logged-in user's first name e.g. Citizen
- fullName — returns the logged-in user's full name e.g. Jane Citizen
- username — returns the logged-in username
- userId — returns the logged-in user's ID
- providerType — returns the logged-in user's provider e.g. Google | Cognito | SAML
- providerUserId — returns the logged-in user's providers ID
- isSAMLUser — returns whether the user is a SAML user e.g. true | false
- supervisorFullName — returns the logged-in user's Supervisor's full name
- supervisorEmail — returns the logged-in user's Supervisor's email address
- supervisorProviderUserId — returns the logged-in user's Supervisor providers ID
- picture — returns the logged-in user's picture as a URL
Lookups can be run automatically. If a lookup includes default or pre-populated 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.
Customize Error Messages
You are also able to add your own unique error messages.
These are configured in the API.
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.