There are 2 types of Lookups:

• Data Lookups: Used to dynamically populate existing form elements with data
• Element Lookups: Used to dynamically generate form elements

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

Data Lookup  

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

For example, if you want to type just the Employee Identification Number (EIN) of a business and have the rest of that business's information automatically populate based on that specific EIN. 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 specific elements.

For example, to do a stocktake of a warehouse where you have a list of items that you 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 you 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.

Custom URL vs. Hosted API vs. Built-In

Custom URL

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.

Hosted API

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. 

Built-In

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. jane@civicplus.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

Automatic Lookups

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.

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.