Lookup Field

Premium Checkbox Feature

Usage of this feature requires account access to Premium Checkbox features. For queries related to your licence agreement, ask your account administrator to contact your Checkbox Account Manager.

 

What is a Lookup Field?

A Lookup field is a field that allows one App to lookup and retrieve data from a Database or another App (i.e. a Flow App).

 

When would you use Lookup fields?

Lookup fields should be used when trying to automatically fill in the current App FORM fields based on a matching key variable.

Common use cases include:

Reference data examples (via the Lookup field):

  • Prefill commonly used data (e.g. Employee information, vendor information)
  • Audit - ongoing audit over a long period of time and revisit previous audit data on a regular basis
  • Human Resources – Looking up different employee details stored in a Database from an App for EOI, referrals, and performance reviews
  • Workflow – approvers or system owners to assign as an Approver

 

Lookup field glossary:

Source App: A "Source App" refers to the App you wish to retrieve data from. Source Apps can only ever be Apps within the same Solution (i.e. to retrieve data in one App from another App, they must both reside in the same Solution).

Database: A Database is an entity on Checkbox that stores data and acts as a single source of truth.

Key Variable: The variable that acts as the filter to retrieve the relevant data

 

How to configure a Lookup Field

Note: The following instructions will also assume that you already have a Database set up where you wish to retrieve data from

  1. Navigate to a FORM block in the App Studio of your chosen App

  2. Click "OPEN FORM BUILDER" to configure the FORM block

  3. From the left panel, drag in or click onto the "Lookup" field

  4. In the Property Editor (right panel), select from the radio options to lookup from either a "Database" or "Flow App" (i.e. an App). Skip to step 6 if you selected "Database"

  5. Use the initial "Lookup Source App" dropdown, and select the App you wish to retrieve data from

    Note: A "Source App" refers to the App you wish to retrieve data from. Source Apps can only ever be Apps within the same Solution (i.e. to retrieve data in one App from another App, they must both reside in the same Solution).
  6. Use the initial "Lookup Database" or "Lookup Source App" dropdown, and select the Database or App you wish to retrieve data from

    Note: Only Databases that have connected to/given permitted access to the respective Solution will be shown in this dropdown. Learn how to connect a Solution to a Database.
  7. In the "Match with Key Variable in Source App", select the variable in the Database or source App you wish to use as the filter to retrieve the rest of the related data

  8. In the "Map variables between this Form and Database (or Source App)" dropdown, select the variables you wish to pre-fill values in the current App with the variables from the Database or source App

    Note: The variables that are matched and mapped from the Source App must be exposed (variables from the Database are exposed by default). Also, the matching variables must have the same variable type (i.e. NUM variables in one App can only be matched by NUM variables from the other App).

  9. Click "+Add Variables" to create more mapped variables and repeat step 6 until satisfied

  10. In the "Columns to display in lookup result" dropdown, select the columns you wish to show when the lookup results show from the Lookup field when the user enters a matching key variable

  11. Click "+Add Columns" to add more columns to display when lookup results are shown

  12. Repeat step 8 - 11 until satisfied