Create an API Integration for Smart Gadgets

API Integration – Data Sets Feature

Create API integrations with your institution's systems to populate fields and keep your data consistent. For security reasons, this feature is only available to System Administrators.

Let's get started. You can create a new integration in 4 Steps. 

STEP ONE	Qualify Your Source and Collect the Requisite Information
STEP TWO	Create a New API Integration
STEP THREE	Configure the Integration
STEP FOUR	Test it out!
STEP FIVE	Secure Your API Integration

 

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?

2. The HTTP method: GET, POST, or PUT.

3. The Integration URL

4. Names of the fields or the structure of the JSON that's being returned.

5. The query parameters that the customer API accepts.

STEP TWO: Create a New API Integration

• From your Kuali Build Dashboard click on the Kuali Build dropdown menu in the upper left corner. Click System API Integrations.

• You will find yourself on the API Integration page. Click on + Add API Integration. 

• You will now see the API Integration Panel. Name your Integration and fill in a short description that will help you or other Admins distinguish between sources. This is the name and description that will show up in your list of API Integrations.

STEP THREE: Configure the Integration

Type of Integration

Select the type of data that you want to pull from your source into a form.

• Get List of Data Items: This will return a list of items that the user can choose from on the form.
• Get Single Data Item: This will return a single item that will autofill a field on the form.
• Use in Workflow: This allows Kuali Build to send data to an API endpoint in a Workflow Integration Step. (Note: You will need to configure some middleware in order to make this data consumable by a third-party system.)

HTTP Method

Refer to the source's documentation and determine the HTTP method, either GET, POST or PUT. Click on the dropdown field under "HTTP Method" and choose the correct method for your source.

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

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).
  • OAuth Client Credentials: If you clicked "Oauth authentication (client_credentials)," the configuration panel will prompt you to define where you want to send the credentials, the token URL, the client ID, client secret, and scope. The configuration attempts to follow the client credential Oauth specification found here. If "Credentials Sent In" is set to "In Request Body" and scope is provided in the scope field, it is assumed that you would also like to pass the scope in the request body. In this case, if you need scope passed as a query param, you can add the scope to the token URL.

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.

Example:

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

Example:

ID Key

Refer again to your source's JSON documentation. They should supply a unique identifier for the record you are accessing. 

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.

URL Inputs

The integration URL can be parametrized. For example, if you include {{name}} in your integration URL the name will appear in the URL Inputs and can be labeled.

Query Parameter Inputs (optional)

These can be used to filter the results that are returned from an API integration. Refer to your API documentation to see what query parameters are available.

• Label: This is what will appear in the form when an app administrator configures a field that will utilize this integration.
• Parameter Name: The information that will be passed to the API (not seen by your users/app administrators).
• Required: Check this box if your query parameter is required.

Search Parameter

The Search Parameter dropdown will allow you to select from your URL Inputs or Query Parameter Inputs.

If left blank the form submitter will see a dropdown menu. If something is selected here, then the form submitter will be presented with a typeahead field that will allow them to type and filter down their results. 

Headers

You can configure the http request headers that will be sent to your API.

Outputs

Outputs provide more information about the results that can be used in other places throughout the form. For example, your integration may query some additional information about the form submitter to include on the form. When a form submitter fills out a student id field, subsequent fields in the form could be populated with the student's GPA, address, major, or other details you have made available in the integration.

Note: Outputs are added to the metadata of your form whether or not you actually use them as a field on your form. As such, they can be used to limit visibility of other gadgets on the form. Meaning, it is possible to set up a conditional visibility rule using a linked auto-filled gadget.

With each Output you are able to select the type of gadget that will appear on the form for the end user: text, number, user typeahead, and group typeahead. User and group typeaheads can be referenced in workflows. 

For data to be formatted in a user typeahead, it must be in the format {id:"KUALIUSERID", label:"USER NAME"}. For data to be formated in a group typeahead, the format must be {id:"KUALI GROUP ID", label:"GROUP NAME"}.

STEP FOUR: Test it out!

Once you have configured the settings, 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 display the results in a side panel. You can see what status code, headers, and body are returned and get a demo of what the user experience will be like.

STEP FIVE: Secure Your API Integration

An important note on security. The data that is entered into the form and then subsequently gets passed into your integration is whatever the user says it is. For example, if you have a user lookup, that user can pass in whatever ID they want and lookup information that you may not want them to have access to. 

To ensure that your data is not accessible to those who shouldn't have it, we pass 3 additional headers that you can use to filter data in your API integration. They are:

• x-kuali-user-id: [user ID in Kuali Build]
• x-kuali-user-name: [user's display name]
• x-kuali-user-ssoid: [user's ID that comes from your SSO provider if you have one]

Receive the value of those headers in your system as needed to only return the data that a specific user has access to. 

Note: These headers won't have values if they are used on an anonymous form or as a Workflow integration as there is no user to tie them to.