Skip to main content
Important Support System Updates Are Underway | Learn More...

Search

We are excited to announce the launch of updated product names, logos, and headers within our user interfaces as part of the CivicPlus® Solution Rebranding initiative. These changes mark the first step toward creating a cohesive and seamless user experience across all solutions in our portfolio. As part of this transition, users may notice minor design updates. While the functionality you rely on remains unchanged, we are in the process of updating screenshots and other resources on our Help Centers to reflect the new branding. We appreciate your patience and understanding as we work to complete these updates.

Dynamic Lookups Overview

  • Updated:

There are two types of Dynamic Lookups:

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

 

Dynamic 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, you 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.

 

Lookup example on a form.

 

 

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.

 

Element lookups can also be used to generate form pages and elements across that page. Check out our GitHub example.

 

Custom URL vs. Hosted API vs. Built-In

Lookups source buttons.

 

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 (Application Programming Interface) 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. For more on our API Hosting service check out the Github API CLI (Command Line Interface).

 

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.

 

The following element names work with Built-In lookups:

 

Element Name Description
fullName The current user's full name
firstName The current user's given name
middleName The current user's middle name
lastName The current user's surname
address The current user's address
picture A URL for a picture of the current user
email The current user's email address
phoneNumber The current user's phone number
role The current user's role or job title
supervisorProviderUserId The current user's supervisor's user identifier
supervisorEmail The current user's supervisor's email address
supervisorFullName The current user's supervisor's full name
areaCode The current user's area code
city The current user's city
state The current user's state
country The current user's country
countryCallingCode The current user's country calling code
department The current user's department
division The current user's division
bargain The current user's bargain
employeeNumber The current user's employee number
departmentHeadFullName The current user's department head's full name
departmentHeadEmail The current user's 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 provider ID
isSAMLUser Returns whether the user is a SAML (Security Assertion Markup Language) 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 user's zip code
postalCode The current user's postal code

 

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.

 

Supporting Articles

Comments

Let us know what was helpful or not helpful about the article.

1 comment

Date Votes
  • Chris Lee

    According to CivicPlus, Dynamic Lookups are processed on the client and are therefore subject to CORS rules, which are discussed in the Dynamic Lists Overview.  This means that visitors can inspect the network traffic made by Dynamic Lookups and Dynamic Lists, so design your API accordingly.

    0

Please sign in to leave a comment.