Overview

The Custom Lookup Options feature enables the importation of custom datasets for lookups and validation tailored to client-specific requirements. For instance, you may upload a CSV file whose data serves as options within select-type custom fields such as Select One – Dropdown, Select One - Radio Button, or Lookup - Autocomplete Options.

Custom lookups facilitate the provision of extensive selection sets for users, including item inventory codes, code dictionaries, or geographic lookups. Additionally, dynamic sub-filtering conditions can be easily configured across multiple fields. For example, you can establish parent and child fields for selecting country, university, faculty, and courses, where the available options in each subsequent field depend on the value selected in the preceding field. This functionality is advantageous as it eliminates the need for the data to exist as records within your system (unlike the current Enable Dynamic Content option within a custom field) and simplifies updating options by importing them rather than manually editing large amounts of text in the custom field Edit screen.

This article provides instructions on how to import a custom lookup, update an existing lookup, and the various methods by which it can be referenced and utilized within your instance. Access to these settings requires Global Administrator privileges.

Configuration - Essentials

As an example, we will upload a custom lookup CSV containing university and course information. A sample file, UniversityCourseLookup.csv, is included in the appendix at the conclusion of this article.

Importing a New Custom Lookup

1. Navigate to Global Settings > Custom Lookup Options and click the Import Custom Lookup Options button, represented by an import icon.

1. You will then access step one of the Custom Lookup Options Import wizard. Upload a CSV file containing your custom data. The first row of the CSV must include column headers. A sample file, UniversityCourseLookup.csv, is provided in the appendix at the end of this article.
2. Assign a descriptive name to your custom lookup under Lookup Name to facilitate future identification. For this example, we will name the lookup "UniversityCourseLookup".
3. Select one of the columns to serve as the Lookup Key. The lookup key is a non-unique identifier associated with one or more rows in the table. In our example, the lookup key is "University ID" because this number corresponds to the different universities within our dataset.
4. The Primary Key is optional. A primary key uniquely identifies a single row in the table. In this example, the primary key is "Course ID" because each row contains a unique Course ID that distinguishes it from all others. Click Next to proceed.
5. Review the sample of the uploaded data to ensure it has been processed correctly. Select which columns you wish to include in the final import. Click Next to continue.
6. The final step allows you to review the changes before completion. Click Next to finalize the import process.

Updating an Existing Custom Lookup

1. To update an existing custom lookup, import the updated CSV file and ensure you enter the exact name of the lookup you intend to update in the Lookup Name field. Specify the lookup key and any required primary key. Click Next to proceed.
2. A warning will appear indicating that a lookup with the same name already exists. All existing rows associated with that lookup name will be deleted and replaced with the newly imported data. Click Next to continue and confirm by selecting Yes on the alert popup.
3. Click Next to complete the import process.

Viewing Custom Lookup Data

To view the data of any custom lookup, navigate to Global Settings > Custom Lookup Options to access a list of imported lookups. Click the name of the desired lookup to view its data in detail. This will display the uploaded data in a list view organized by the Lookup Key.

The values listed under Lookup Value represent attribute-value pairs corresponding to column values for the specified row. To examine this data in greater detail, click the icon labeled Open located on the far left of any row. The expanded Lookup Value data reveals that this specific row contains values for the columns "Course ID," "University," and "Course."

Configuration - Advanced

Setting Up a Standalone Dropdown List

The most straightforward method to utilize your imported custom lookup options is by creating a standalone dropdown list. We will demonstrate this using our university course lookup example.

1. Create a custom field of type Select One - Dropdown List.
2. Enable the Enable Dynamic Content toggle.
3. A new toggle labeled Use Custom Lookup Options will appear; enable this toggle.
4. Additional settings for the custom lookup will become visible. From the Lookup Name dropdown, select the custom lookup you wish to reference. In the Option Text Identifier field, enter the name of the lookup column whose values should populate the dropdown. In this example, to display available course names, enter the column name "Course."

Setting Up a Parent-Child Dropdown List

Custom lookups can be integrated into dynamic dropdown lists by establishing parent-child relationships between data elements. After uploading a CSV containing your custom data, you can configure a series of parent and child dropdown lists that filter user options based on prior selections.

Configuring the Parent Dropdown

1. Create a custom field of type Select One - Dropdown List.
2. In the Predefined Options field, map the various lookup keys from your custom lookup data to the options you intend to display in the dropdown. For example, if your lookup keys range from 100 to 600, with each increment of 100 corresponding to a different university, mapping the lookup keys accordingly will enable the child dropdown to filter the custom lookup data based on the selected lookup key. For instance, if a user selects "Totally Totes College" (mapped to lookup key 100), the child dropdown will filter and display only the courses available at that university.

Configuring the Child Dropdown

1. Create a custom field of type Select One - Dropdown List and assign the Parent Field to the previously created parent dropdown list.
2. Enable the Enable Dynamic Content option.
3. A new toggle labeled Use Custom Lookup Options will appear. Activate this toggle.
4. Additional settings for the custom lookup will become available. From the Lookup Name dropdown, select the desired custom lookup to reference. In the Option Text Identifier field, enter the name of the lookup column whose values should populate the dropdown. For example, to display available course names in the dropdown, input the column name "Course".

Final Outcome of Parent-Child Dropdown

The options available within the child dropdown will dynamically update based on the selection made in the parent dropdown. For instance, selecting a university in the parent dropdown will modify the list of courses available for selection in the child dropdown.

Establishing Successive Dropdown Lists

In the previous example, all predefined options were manually entered into the custom field configuration settings. This process can be time-consuming when frequent updates or additions to the custom data are required. The procedure can be streamlined by importing multiple lookups. This section demonstrates how to implement successive dropdown lists and reference multiple custom lookups without hardcoding predefined options.

For example, we aim to configure a sequence of parent-child dropdowns for course registration. The user will first select a university from a list, then choose a faculty associated with that university, and finally select a course within the chosen faculty.

All referenced CSV files are provided in the appendix below.

Configuring the Parent Dropdown

1. Import UniversityLookup.csv using "University ID" as the Lookup Key and "Primary Key" as the Primary Key. Set the Lookup Name to "UniversityLookup".
2. Create a custom field of type Select One - Dropdown List and assign it the caption "University".
3. Enable both the Enable Dynamic Content and Use Custom Lookup Options toggles.
4. Select "UniversityLookup" under Lookup Name. In the Option Text Identifier, enter the column name to be displayed; in this case, "University".

Configuring the First Child Dropdown

1. Import FacultyLookup.csv using "University ID" as the Lookup Key and "Faculty ID" as the Primary Key. Set the Lookup Name to "FacultyLookup".
2. Create a custom field of type Select One - Dropdown List and assign it the caption "Faculty".
3. Set the Parent Field to the previously created "University" dropdown custom field.
4. Enable both the Enable Dynamic Content and Use Custom Lookup Options toggles.
5. Select "FacultyLookup" under Lookup Name. In the Option Text Identifier, enter the column name to be displayed; in this case, "Faculty".

Configuring the Second Child Dropdown

1. Import UniversityCourseLookup.csv using "Faculty ID" as the Lookup Key and "Course ID" as the Primary Key. Set the Lookup Name to "UniversityCourseLookup".
2. Create a custom field of type Select One - Dropdown List and assign it the caption "Course".
3. Set the Parent Field to the previously created "Faculty" dropdown custom field.
4. Enable both the Enable Dynamic Content and Use Custom Lookup Options toggles.
5. Select "UniversityCourseLookup" under Lookup Name. In the Option Text Identifier, enter the column name to be displayed; in this case, "Course".

Final Outcome of Successive Parent-Child Dropdowns

The options available within each child dropdown will dynamically update based on the selections made in the respective parent dropdown. For example, selecting a university in the parent dropdown will filter the faculty options in the subsequent dropdown. The selection made in the faculty dropdown will then determine the options available in the course dropdown.

Explanation of Settings

Import Settings

Configuration Settings

Appendix

UniversityLookup.csv

University ID,Primary Key,University
100,100,--- Please Select ---
100,100,Totally Totes College
200,200,Obviously OBVI College
300,300,Artisanal Art College
400,400,Coffee for Me University
500,500,Asymmetrical University of Aesthetics
600,600,University of Cold-pressed Flannel

FacultyLookup.csv

University ID,Faculty ID,Faculty,University
100,100,--- Please Select ---,--- Please Select ---
100,101,Arts & Literature ,Totally Totes College
100,102,Natural Sciences,Totally Totes College
100,103,Humanities,Totally Totes College
100,104,Mathematics,Totally Totes College
200,201,English Literature,Obviously OBVI College
200,202,Physical Sciences,Obviously OBVI College
200,203,History & Humanities,Obviously OBVI College
200,204,Mathematics & Computer Science,Obviously OBVI College
300,301,Literature ,Artisanal Art College
300,302,Biology, Chemistry, and Physics,Artisanal Art College
300,303,History, Anthropology, and Psychology,Artisanal Art College
300,304,Mathematics & Philosophical Sciences,Artisanal Art College
400,401,Faculty of English Literature,Coffee for Me University
400,402,Faculty of Natural Sciences,Coffee for Me University
400,403,Faculty of History,Coffee for Me University
400,404,Faculty of Mathematics & Computing,Coffee for Me University
500,501,Modern Arts & Literature,Asymmetrical University of Aesthetics
500,502,Hard Sciences,Asymmetrical University of Aesthetics
500,503,Modern History & Anthropology,Asymmetrical University of Aesthetics
500,504,Mathematics & Computing,Asymmetrical University of Aesthetics
600,601,Department of English,University of Cold-pressed Flannel
600,602,Department of Science,University of Cold-pressed Flannel
600,603,Department of History,University of Cold-pressed Flannel
600,604,Department of Mathematics,University of Cold-pressed Flannel

UniversityCourseLookup.csv

University ID,Course ID,Faculty ID,University,Faculty,Course
100,1000,100,--- Please Select ---,--- Please Select ---,--- Please Select ---
100,1001,101,Totally Totes College,Arts & Literature,Gothic Literature in the 19th Century
100,1002,102,Totally Totes College,Natural Sciences,Organic Compounds in Chemistry
100,1003,103,Totally Totes College,Humanities,Introduction to Modern History
100,1004,104,Totally Totes College,Mathematics,Introduction to Calculus 
100,1005,101,Totally Totes College,Arts & Literature,Comparitive Mythology & Folklore
100,1006,101,Totally Totes College,Arts & Literature,Introduction to Latin American Literature
200,2001,202,Obviously OBVI College,Physical Sciences,Fluid Dynamics in Brownian Motion
200,2002,204,Obviously OBVI College,Mathematics & Computer Science,Advanced Lorentz Transformations
200,2003,201,Obviously OBVI College,English Literature,Analysis of Arthurian Legend
200,2004,202,Obviously OBVI College,Physical Sciences,Morphology in Evolution
200,2005,202,Obviously OBVI College,Physical Sciences,Thermodynamics
200,2006,203,Obviously OBVI College,History & Humanities,Early Modern Period
300,3001,303,Artisanal Art College,History, Anthropology, and Psychology,Architecture of the Roman Empire
300,3002,302,Artisanal Art College,Biology, Chemistry, and Physics,Anatomy of the Human Body
300,3003,304,Artisanal Art College,Mathematics & Philosophical Sciences,Topology of Non-Euclidean Systems 
300,3004,301,Artisanal Art College,Literature ,Ancient Epics and Poetry
300,3005,303,Artisanal Art College,History, Anthropology, and Psychology,History of the Dutch Golden Age
300,3006,302,Artisanal Art College,Biology, Chemistry, and Physics,Virology and Epidemiology
400,4001,402,Coffee for Me University,Faculty of Natural Sciences,Inorganic Compounds in Chemistry
400,4002,401,Coffee for Me University,Faculty of English Literature,Russian Literature in the 19th Century
400,4003,401,Coffee for Me University,Faculty of English Literature,Proto-Indo European Folklore (Thesis)
400,4004,401,Coffee for Me University,Faculty of English Literature,Introduction to English Literature
400,4005,402,Coffee for Me University,Faculty of Natural Sciences,Nomenclature of Organic Compounds
400,4006,403,Coffee for Me University,Faculty of History,Monarchies Through the Ages
500,5001,504,Asymmetrical University of Aesthetics,Mathematics & Computing,Polynomial Differentiation
500,5002,501,Asymmetrical University of Aesthetics,Modern Arts & Literature,Ancient Greek Classics
500,5003,501,Asymmetrical University of Aesthetics,Modern Arts & Literature,Introduction to Renaissance Literature
500,5004,502,Asymmetrical University of Aesthetics,Hard Sciences,Quantum Mechanics
500,5005,504,Asymmetrical University of Aesthetics,Mathematics & Computing,Introduction to Algebraic Topology
500,5006,501,Asymmetrical University of Aesthetics,Modern Arts & Literature,Magic Realism in Latin American Literature
600,6001,602,University of Cold-pressed Flannel,Department of Science,Radiation and Thermonuclear Reactions
600,6002,602,University of Cold-pressed Flannel,Department of Science,Kinematics and Dynamics
600,6003,603,University of Cold-pressed Flannel,Department of History,Rise and Fall of the Mughal Empire
600,6004,603,University of Cold-pressed Flannel,Department of History,Neo-Classical Architecture Through the Ages
600,6005,602,University of Cold-pressed Flannel,Department of Science,Cardiovascular System Processes
600,6006,604,University of Cold-pressed Flannel,Department of Mathematics,Polynomial Field Theory