Custom Lookup Options
 Please note that this page is currently under construction. There is more information to come.
|
Contents
Overview
The Custom Lookup Options is a feature that allows you to import custom datasets for lookups and validation based on client-specific needs. For example, you can upload a CSV file whose data can be used as options within a select-type custom field such as Select One – Dropdown, Select One - Radio Button, or Lookup - Autocomplete Options.
Custom lookups can be used to provide large selection sets for your users, such as item inventory codes, code dictionaries, or geographic lookups. You can also easily setup dynamic sub-filtering conditions across multiple fields. For example, you could set up parent and child fields for selecting the country, university, faculty, and courses where the available options for each subsequent field is dependent upon the value of a previous field. This new functionality is advantageous since you don't need any of the data to exist as records in your system (as with the current Enable Dynamic Content option within a custom field) and it will be easier to update the options by importing them rather than editing large amounts of text in the custom field Edit screen.
This article will show you how to import a custom lookup, update a lookup, and the various ways it can later be referenced and used on your instance. You will need to be a Global Administrator to access these settings.
Configuration - Essentials
As an example, let's upload a custom lookup CSV containing university and course information. A sample of this CSV data can be found at the end of this article for reference.
Importing a New Custom Lookup
- Navigate to Global Settings > Custom Lookup Options and click on the Import Custom Lookup Options button represented by an import icon.
- You will now access step 1 one of the Custom Lookup Options Import wizard. Upload a CSV containing your custom data. The first row of the CSV must include column headers. A sample CSV is provided under the Settings Explained section below.
- Give your custom lookup a descriptive name under Lookup Name that will help you remember what it is for. For our example, we will call our lookup "UniversityCourseLookup".
- Select one of the columns for the Lookup Key. The lookup key is a non-unique identifier that is associated with one or more records in the table. In our example, our lookup key is the "University ID" because this number corresponds to the different universities in our dataset.
- The Primary Key is optional. A primary key is a unique identifier that corresponds to a single record in our table. For our example, the primary key is "Course ID" because each row in the table has a uniquely different Course ID that distinguishes it from every other row. Click Next to continue.
- Check over the sample of the uploaded data to ensure it has been processed as intended. Toggle which columns you want to include in the final import. Click Next to proceed.
- The last step will let you review the final changes. Click Next to complete the import process.
Updating an Existing Custom Lookup
- To update an existing custom lookup, import the updated file and be sure to type out the exact name of the lookup you want to update in the Lookup Name field. Specify the lookup key and any primary key needed. Click Next to continue.
- You will see a warning that notifies you that an existing lookup with the same name already exists. All existing records for that lookup will be deleted and re-imported with the new updated data. Click Next to continue and click Yes on the alert pop-up.
- Click Next to finish the import.
Viewing Custom Lookup Data
To view the data of any custom lookup, navigate to Global Settings > Custom Lookup Options to see a list of imported lookups. Click the name of the lookup you want to see in more detail. This will allow you to see the uploaded data in a list view format organized by the Lookup Key.
The list of values under Lookup Value form an attribute-value pair of column values for the specified row. To see this data in more detail, click the icon on the far left marked Open on any row. Based on the expanded Lookup Value data, we can see that this specific row contains the values for our table columns "Course ID", "University", and "Course".
Configuration - Advanced
Setting Up a Standalone Dropdown List
The easiest way to make use of your imported custom lookup options is to use a standalone dropdown list. We will use our university course lookup as an example.
- Create a custom field of type Select One - Dropdown List.
- Toggle on Enable Dynamic Content
- You should now see a new toggle called Use Custom Lookup Options. Toggle this on.
- You should now see additional settings for the custom lookup. Under the Lookup Name dropdown, select the custom lookup you want to reference. Under Option Text Identifier, type the name of the lookup column whose values you want to populate in the dropdown. In our example, we want to expose the available course names in the dropdown so we will type the name of the column that contains that information: "Course".
Setting Up a Parent-Child Dropdown List
Custom lookups can be incorporated into dynamic dropdown lists using the parent and child relationship between data. After uploading a CSV for your custom data, you can set up a series of parent and child dropdown lists that can further filter user options based on previous selections.
Configuring the Parent Dropdown
- Create a custom field of type Select One - Dropdown List.
- In the Predefined Options field, map the various lookup keys of your custom lookup data to the options you want to surface in the dropdown. In our example, our lookup keys span a range of 100 to 600, with each 100 increment corresponding to a different university. Mapping the lookup keys in this way will allow the child dropdown we set up later to be filtered by the selected lookup key. For example, if the user selects "Totally Totes College" (with a lookup key mapped to 100), the corresponding child dropdown options will filter the custom lookup data by this lookup key and only return the courses available to that university.
Configuring the Child Dropdown
- Create a custom field of type Select One - Dropdown List and set the Parent Field to the parent dropdown list created above.
- Toggle on Enable Dynamic Content
- You should now see a new toggle called Use Custom Lookup Options. Toggle this on.
- You should now see additional settings for the custom lookup. Under the Lookup Name dropdown, select the custom lookup you want to reference. Under Option Text Identifier, type the name of the lookup column whose values you want to populate in the dropdown. In our example, we want to expose the available course names in the dropdown so we will type the name of the column that contains that information: "Course".
End Result of Parent-Child Dropdown
The available options within the child dropdown should now change depending on the selections made in the parent dropdown. In our example, changing the university in the parent dropdown will change the available courses we can select in the child dropdown.
Setting Up a Successive Dropdown Lists
In the previous example, all the predefined options had to be hardcoded into to the custom field configuration settings. This could be a tedious an inefficient process if the custom data needs regular updates or new entries. The process can be simplified by importing multiple lookups. The section will illustrate how to use successive dropdown lists and reference multiple custom lookups without having to hardcode predefined options.
As an example, we want to set up a chain of parent-child dropdowns for course registration. We want the user to first select from a list of available universities, then select from a list of available faculties at that selected university, and lastly, we want the user to select from a list of available courses under that university faculty.
All referenced CSV files are provided in the appendix below.
Configuring the Parent Dropdown
- Import UniversityLookup.csv with the University ID as the Lookup Key
Configuring the First Child Dropdown
- Import FacultyLookup.csv with the University ID as the Lookup Key and the Faculty ID as the Primary Key
Configuring the Second Child Dropdown
- Import UniversityCourseLookup.csv with the Faculty ID as the Lookup Key and the Course ID as the Primary Key
Settings Explained
Import Settings
| Option | Description |
|---|---|
| Lookup Name | The Lookup Name is used to identify the set of lookup options. If you want to update an existing custom lookup, ensure the Lookup Name is the same as the existing custom lookup. |
| Lookup Key | The Lookup Key is a non-unique identifier used to return all records with a matching Lookup Name. |
| Primary Key | (Optional) The Primary Key is an optional unique key used to return a single record that matches the Lookup Name and Primary Key value. Records without a matching Primary Key will be imported as new records. |
Configuration Settings
| Option | Description |
|---|---|
| Option Text Identifier | The name of the column header from your custom dataset whose values you want to display in the dropdown. |
| Option Value Identifier | (Optional) The name of the column header from your custom dataset whose values are unique for each row. If a Primary Key has been defined for the custom lookup, |
Appendix
UniversityLookup.csv
University ID,Course ID,University,Course 0,0,--- Please Select ---,--- Please Select --- 100,1001,Totally Totes College,Introduction to Art 100,1002,Totally Totes College,Intermediary Art 100,1003,Totally Totes College,Advanced Art 100,1004,Totally Totes College,Introduction to Music 100,1005,Totally Totes College,Intermediary Music 100,1006,Totally Totes College,Advanced Music 200,2001,Obviously OBVI College,Introduction to Art 200,2002,Obviously OBVI College,Intermediary Art 200,2003,Obviously OBVI College,Advanced Art 200,2004,Obviously OBVI College,Introduction to Music 200,2005,Obviously OBVI College,Intermediary Music 200,2006,Obviously OBVI College,Advanced Music 300,3001,Artisanal Art College,Introduction to Art 300,3002,Artisanal Art College,Intermediary Art 300,3003,Artisanal Art College,Advanced Art 300,3004,Artisanal Art College,Introduction to Music 300,3005,Artisanal Art College,Intermediary Music 300,3006,Artisanal Art College,Advanced Music 400,4001,Coffee for Me University,Introduction to Art 400,4002,Coffee for Me University,Intermediary Art 400,4003,Coffee for Me University,Advanced Art 400,4004,Coffee for Me University,Introduction to Music 400,4005,Coffee for Me University,Intermediary Music 400,4006,Coffee for Me University,Advanced Music 500,5001,Asymmetrical University of Aesthetics,Introduction to Art 500,5002,Asymmetrical University of Aesthetics,Intermediary Art 500,5003,Asymmetrical University of Aesthetics,Advanced Art 500,5004,Asymmetrical University of Aesthetics,Introduction to Music 500,5005,Asymmetrical University of Aesthetics,Intermediary Music 500,5006,Asymmetrical University of Aesthetics,Advanced Music 600,6001,University of Cold-pressed Flannel,Introduction to Art 600,6002,University of Cold-pressed Flannel,Intermediary Art 600,6003,University of Cold-pressed Flannel,Advanced Art 600,6004,University of Cold-pressed Flannel,Introduction to Music 600,6005,University of Cold-pressed Flannel,Intermediary Music 600,6006,University of Cold-pressed Flannel,Advanced Music
