Protocols - External Data

Overview

External Data along with the External Data Gadget allows an institution to setup an institutionally maintained data source to populate as a dropdown list or typeahead search in their Protocol forms. This allows a compliance administrator to setup values that can be updated without updating their protocol templates. Common use cases for this are buildings and rooms on campus where research can take place, or a list of available species for inclusion in an IACUC protocol.

API Configuration

The first step to setting up the External Data Gadget is to build a restful API endpoint that delivers the values you need to populate your External Data gadget as JSON. The External Data system does not support validation, so this API will need to be publicly available. This should not be used to share datasets that cannot be public.  Below is an example set of results along with an explanation of how to configure this example in the Kuali Protocols system.

Example JSON: {"results":[{"id":1,"Animal":"Dolphin","type":"Mammal"},{"id":2,"Animal":"Rat","type":"Mammal"},{"id":7,"Animal":"Terry","type":"Mammal"},{"id":4,"Animal":"Platypus","type":"Mammal"},{"id":3,"Animal":"Chihuahua","type":"Mammal"}]}

First click on the External Data page

Click the New API + Button

Complete the following fields

• Name: This is the name of this dataset assigned in the Kuali Protocols system. This will be used to select this dataset when configuring the External Data gadget in your FormDesigner template.
• URL: The URL of your API endpoint.
• Value: This is the JSON attribute that will display in the dropdown list once a value is selected when  this is configured in a protocol form. In the example above this should be configured as Animal
• Key: This is the JSON attribute that will save in the database when a value is selected when this is selected in a protocol form. In the example above this should be configured as id
• Results Path: This is where in the JSON response to find the array of options. In the example above this should be configured as results.
• Auth Token: This is an optional field.  If your API has an API bearer token requirement you can list this here.  Once you've added the API key it will no longer be visible in the system.  You can clear it and apply a new key as necessary based on your key expiration policy.
• Training Data Source (usable only with the training gadget): If this is turned on the system will ignore the Value, Key, and Results path fields. They are still required by the configuration, but you can enter any value such as "unused" in these fields. This allows an institution to provide data for the Training Gadget. An institution that wants to setup this integration from a third party system should work with their Customer Success Manager.

Once you've entered all of this information press the Save button.

Form Designer Configuration

Next edit the Form Designer template that you want to link to the API configured above and add the External Data Gadget to the appropriate location in your form.

Complete the following information for your External Data Gadget.

• External Data: Select the name you assigned above.
• Control Type: Select one of the Control Types indicated below
  • Typeahead: This will add a typeahead search field based on the Value of the linked dataset.
  • Dropdown: This will add a dropdown field populated with the Values from the linked dataset.
• Display Blank Options: If this is checked then any options listed in the JSON dataset that do not have a Value assigned will still appear as blank options in the form.

Progressive Display for External Data: If you need to base progressive display on an External Data gadget you can compare against contains or does not contain. When you select this option a free text field will display as the third field in the Progressive Disclosure statement. Unlike the text input fields this gadget does have a fixed dataset to pull from, but the potential for very large external datasets makes it impractical to display all possible answers in the Progressive Disclosure interface. Progressive display for this field is based on the ID, not the Value.