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

This 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.

Within Kuali data sets you'll have the options of Edit Available Data and Advanced Settings. The Edit Available Data allows you select the desired fields from the internal source to be available in the Add linked auto-filled gadgets options (and to filter upon). 

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.

You can also put additional lookup filtering to limit lookup values based on certain criteria from the available data (i.e. Workflow status, Multiple choice, Date picker, etc.). 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):

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)