How Do I Use the Data Lookup (Multiselect) Gadget?

• Overview
• Utilizing in Anonymous Forms
• Data Lookup (Multiselect) Example

Overview

The Data Lookup (Multiselect) advanced gadget allows you to pull Kuali Data or External Data once the appropriate API integration(s) have been configured on the backend (see Create an API Integration for Advanced Gadgets). The only difference is you can make multiple selections vs a single selection and you will see a checkmark next to the options selected in the lookup dropdown.  

If pointing to Kuali Data you can point to People, Groups, or other App Data. If you want to point to other App Data just make sure you've shared it with the given app (more detail in the Data Sharing article). Within Kuali Data you'll notice that the app you're working on is also listed which means you can also reference the data set you are currently working in a data lookup.  Lastly, if pointing to Kuali app data you'll also have the below additional configuration options:

• Display as list - When enabled the selected values in the Data Lookup (Multiselect) gadget will appear in a list which enables the values to be reordered if desired using the handle next to a selected item and dragging it to the desired position
• Link to document - When enabled selected documents in the lookup gadget will appear as clickable links. If the linked Kuali document is accessible, it will open in a new tab. If the user does not have permission to view the linked document, an error message will inform the user.

Within Kuali data sets you'll have the option of Advanced Settings. The Advanced Settings allows you additional configuration options on the data being pulled in the lookup.  

First, you can specify when the data should update in the document if the linked data changes.  You can select 'Never' to not update regardless if it's changed in the primary document or 'When the linked document is saved' so it will reflect the updated data in the primary document once it's saved.  

Note: Please keep in mind the following on data updating:
- By default, all existing data lookups will be set to not update.
- If an admin updates an existing data lookup then it will only work on documents linked in the data lookup after the gadget configuration update is published. It will not impact the update logic on any existing document data.
- If a data lookup is configured to update when document is changed, and the linked document is deleted, the data from that document will be removed from the data lookup and all auto-linked gadgets.
- If a user tries to delete a document linked in a data lookup set to update on save, they will receive a warning. The warning will list the documents that will lose data due to this change.
- Data lookups that are configured to update cannot be used in calculations or integration fields.  If a data lookup is configured to update when changes are made, they will not be able to be used in calculations or integration fields because those fields could get out of date.

Also, if versioning is enabled in the app you're linking to in the gadget you'll have additional document updating and filtering options in Advanced Settings - more information can be found in the Document Versions article.

Note: If pointing to Kuali People you can also narrow down the list of users by a specific Role in a Group. Simply use the Group/Role lookup in the gadget configuration and select the desired Group/Role(s):

Utilizing in Anonymous Forms

Anonymous forms only allow integrations that point to external data and cannot pull information from Kuali Users, Groups, or other App data for security reasons.  Once you enable the 'Create documents in this app' permission for All Anonymous Users in App Permissions you'll see that the Advanced Data Lookup gadget options in the Form designer are locked down and must be enabled:

Upon clicking 'Enable' you'll get a warning message alerting you of the risks utilizing integrations in anonymous forms.  It's important to understand that an anonymous form runs without a logged in user. That means that all backend API calls that the anonymous form makes are accessible to anyone on the internet who can determine what those urls are - sensitive data should never be shared in anonymous forms, even in the lookups.

Data Lookup (Multiselect) Example

Lets explore setting up a Data Lookup (Multiselect) with an external API you've created:

• Let's say I want the student to fill out a field that requests their student ID, and then I want a list of their classes to automatically populate a dropdown menu. Drag and drop the Short Text gadget into the center of your form, and give it the label "Student ID."
• Drag and drop the Data Multiselect gadget into the center panel of your form.
  Fill in the Gadget Label/Question. For example, I want to get a list of this student's current courses, so I have labeled this gadget "Current Courses." This gadget will allow the student to select 1 or more of their courses from the gadget's dropdown menu.

• Choose the Data Source where the information that will populate this gadget comes from.

Note: Some data sources require extra pieces of information to be available in the form or from the submitter in order to work properly. This setting will notify you if that is the case.

• If your data source requires an input, or an additional piece of information, you will then be prompted to select the form field or metadata field where that information can be found. You can also include a Hard-coded value, if needed. I have selected the Student ID field I created earlier.
• Select any other desired settings in the configuration panel on the right side of the screen.

Note: Although all form builder gadgets perform different functions and have unique settings, many of their initial gadget settings are the same. To see more information about some of the shared settings see the Gadget Configuration Settings article.

For more information, see the following article(s):

• Form Gadget Overview - Data Lookup (Multiselect)