Create an API Integration

• Create a New API Integration
• Configure the Integration
• Test the Integration
• Control Access to Integrations
• Secure API Integrations

Note: Integrations will only be available on forms where the form submitter is authenticated. For security purposes we do not make them available on anonymous forms.

Create a New API Integration

• Click on the Suite Menu icon (), then navigate to System Settings. (Spaces & Settings for Enterprise customers).

• Non-Enterprise customers will be taken directly to the Integrations tab.

• For Enterprise customers, select the Integrations tab within the appropriate space.

• Click on the + Add API Integration button.
  • The +Add Advanced option is only available for Enterprise customers.
• The New Integration modal window will appear. Provide a name for the integration, and if desired, 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.

• Proceed to configure the integration as needed.

Configure the Integration

• Type of Integration
• HTTP Method
• Integration URL
• Authentication Type
• Path to Results Array
• ID Key
• Label Key
• URL Inputs
• Query Parameter Inputs (optional)
• Proxy Request
• Search Parameter
• Headers
• Outputs

Type of Integration

This will indicate to the system 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. When selected, the fields for Path to Results Array, ID Key, and Label Key will become available on the form. 

Get Single Data Item

This will return a single item that will autofill a field on the form. When selected, the fields for ID Key, and Label Key will become available on the form. 

Use in Workflow

This allows Kuali to send data to an API endpoint in a Workflow Integration Step.

HTTP Method

Refer to the data source's documentation and determine the HTTP method that should be used. Click on the dropdown field under "HTTP Method" and choose the correct method for your data.

GET

Retrieves data from a server at the specified resource without making any changes.

POST

Sends data to a server to create a new resource, typically returning the newly created resource as part of the response.

PUT

Updates an existing resource with new data provided in the request, replacing the current representation of the resource with the one provided.

PATCH

Partially updates an existing resource with the data provided in the request, modifying only the specified fields of the resource.

DELETE

Removes the specified resource from the server.

Integration URL

Refer to the data source's documentation to retrieve the URL. Enter the source's Integration URL in the field provided. Once entered, the Authentication Type field will become available.

Authentication Type

If the URL you're referencing points to an external source (i.e. Google Sheets, etc), you'll need to provide the authentication type details to access (if any).  Refer to your data source's documentation, and select  the type of authentication stipulated. 

No authentication

No additional verification is necessary to access, or you've set the appropriate share settings within the external source to all access (i.e. in a Google Sheet, anyone with link can access).

Basic Authentication

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.

Bearer Authentication

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 authentication

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 follows the client credential Oauth specification; please refer to Oauth API documentation for further details on generating this information. 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.

Ethos API (Preview)

If you click "Ethos API (Preview)", the configuration panel will prompt you to define an Auth URL and Access Token which allows you to access Ellucian Ethos endpoints. Please refer to Ethos API documentation on how to generate the appropriate auth url and token to connect.

Path to Results Array

In the configuration panel, below the Authentication Type, if your Integration Type is set to Get a List of Data Items, you will find the "Path to Results Array" field option.  This allows you to specify the exact path on which you want to retrieve data within the results array when the information may be nested in the JSON.

Note: If you are not a technical person, we highly recommend you find someone to help with JSON results configuration.

Example 1 (Basic)

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 of array at root - it's within the initial [ ] brackets:

Example 2 (Nested Array)

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 in the "Path to the Results Array" field. Example of a nested [ ] array:

Example 3 (Return Single Row Value)

If you want to return a single field from the array always at the same level you can specify the specific result in the list array you want to pull (i.e. first, second, third, etc).  So in the above screenshot of the account results if you always wanted to return the first entry and pull back the accountNumber you would enter  accounts[0].accountNumber in the "Path to the Results Array" field.  You basically specify the path[level].output  Be aware that the first result will always be [0], second entry [1], third entry [2], and so on.

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.

Proxy Request

You have the option to send integrations through the service that utilizes static IP addresses if you require.  

By default this setting is not checked but if enabled the integration will route through the IP addresses referenced in the IP Addresses to Allow article. 

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 the 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, timestamp, rich text, 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"}.  Also note, for data to be recognized as a Timestamp type it must be in UTC format.

Test the Integration

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 codes, headers, and body are returned and get a demo of what the user experience will be like.

Note: It is only possible to test a GET integration at this time.

Control Access to Integrations

Once you have created your integration, you can determine which apps should have access to your integration.

• From the list of Integrations, select the Edit ( ) icon for the API you would like to assign access to. 

• Once selected, navigate to the Data Sharing tab at the top.

• From there you can determine the availability of your integration:
  • Do not share the data
  • Share with ALL apps (default)
  • Share with only SPECIFIC apps.
• If you select Share with only SPECIFIC apps you will then be prompted to add a list of apps that can access the data from this integration.

Secure API Integrations

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

Add the value of those headers to your integration 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.