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 the 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. From your Kuali Build Dashboard click on the Kuali Build dropdown menu in the upper left corner. Click System 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.
STEP THREE: Configure the Type of Integration
4. Type of Integration: Select "Get Data" 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 and 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. Once you have filled out the requested fields, test your integration by clicking the "Run Test" button at the bottom of the API Integrations screen. When clicked it will run a test with the current configuration and then show a results page.
2. Successful Test: Here's what the results of a successful test look like.
3. Failed Test: Here's what failed test results look like. This should make it easier to troubleshoot issues when configuring an API integration.