API Integration – Data Sets Feature
Yes. Create API integrations with your institution's systems to populate fields and avoid false data factories. For security reasons, this feature is only available to System Administrators - those Super Admins with Super Powers and Tech Know-how.
Let's get started: You can create a new integration in 6 Steps.
|STEP ONE||Qualify your Source and Collect the Requisite Information|
|STEP TWO||Create a New API Integration|
|STEP THREE||Configure the Type of Integration|
|STEP FOUR||Authenticate Access to Source|
|STEP FIVE||Configure JSON Path to Results Array|
|STEP SIX||Test it out!|
STEP ONE: Qualify Your Source and Collect the Requisite Information
Creating an API Integration requires a certain amount of information from the source. A qualified source must have a publicly accessible api endpoint that returns JSON formatted data and provides api documentation and authentication credentials.
To create an api integration data set in Kuali Build, you will need to know:
1. Authentication: Does the source use basic authentication or bearer authentication? (Please note: we do not currently support OAuth, but this is on short term roadmap.)
2. The HTTP method: GET or POST.
3. The Integration URL
4. Names of the fields or the structure of the JSON that's being returned.
STEP TWO: Create a new API Integration
1. Go to your Kuali Build Dashboard and click on the System Settings (gear icon). This is found in the lower left toolbar. You should find yourself on the System Settings page.
Click on API Integrations.
2. You will find yourself on the API Integration page. Click on Add API Integration.
3. You will now see the API Integration Panel. Name your Integration and fill in a short description that will help you or other Super Admins distinguish between sources. This is the name and description that will show up in your list of API Integrations here.
STEP THREE: Configure the Type of Integration
4. Type of Integration: Below the description field, click "Get" to signal that you want to pull information from your source into a form.
5. HTTP Method: Refer to the source's documentation and determine the HTTP method, either GET or POST. Click on the dropdown field under "HTTP Method" and choose the correct method for your source.
6. Integration URL: Refer to the source's documentation for the source's url: enter the source's Integration URL in the field provided. This will reveal more configuration.
STEP FOUR: Authenticate Access to Source
7. Authentication Type: Refer to your source's documentation: click on the type of authentication stipulated. Either Basic authentication or Bearer Authentication.
Verifying Authentication to access the API Source
Username and Password: If you clicked "Basic Authentication," the configuration panel will prompt you to enter the username and password for the individual who has the permission to access the system/source to which you are connecting. This may or may not be you.
API Key Header and API Key: If you clicked "Bearer Authentication," the configuration panel will prompt you to enter the API Key Header and the API Key for authentication. The instructions on generating this API key will be found in the source's documentation (each source having their own method).
STEP FIVE: Configure JSON Path to Results Array
8. Path to Results Array: In the configuration panel, below the Authentication Type, you will find "Path to Results Array."
If you are not a technical person, we highly recommend you find someone to help with JSON results configuration.
JSON returns information in an array (a collection/list). You need the name of the path that your source uses for that array. If the array is at the root of the JSON, then you would leave this field blank.
If the path of the array is nested, you would enter the name of that path in the "Path to the Results Array" field. In this example, you would enter "accounts" (no punctuation) to the "Path to the Results Array" field.
9. ID Key: Refer again to your source's JSON documentation. They should supply a unique identifier for the record you are accessing.
10. Label Key: Refer again to your source's JSON documentation. This is the name of the key for the values that will appear in your data set.
STEP SIX: Test it out!
1. Go to an existing form or create a new form in Kuali Build.
2. From the gadget list in the left side panel, drag and drop the Data Set gadget into the wysiwyg form builder.
3. In the right side panel, click on the drop down list labelled, "Select a source of data to populate this dropdown." A list of API Integrations should appear. And, your new integration should be in that list!
CONGRATULATIONS ON YOUR NEW API INTEGRATION!