Create an API Integration

• What is an Integration?
• Create a New API Integration
• Configure the Integration
• Test the Integration
• Control Access to Integrations
• Secure API Integrations
• Utilizing Integrations in Anonymous Forms

Note: Anonymous forms only allow integrations that point to external data and cannot pull information from Kuali Users, Groups, or other App data for security reasons.  Please see the Utilizing Integrations in Anonymous Forms section below for more information.

What is an Integration?

Kuali has a rest API (Application Programming Interface) configuration tool that allows you to easily  connect Kuali to your local systems/tools (i.e. HR, Financials, Student, Asana, etc.).  This means you can build out integrations to pull external information into Kuali or post information from Kuali to other systems at your institution. Whether that's pulling employee information from your HR system, course info from your Student system, room/building information from your resource management system, or creating an Asana task from a form submission - the possibilities are endless!  As long as your local system offers rest APIs, then Kuali can connect.

You can do that by creating an integration with your local system and then adding that integration to your form - more information on that can be found in the API Integrations for Advanced Gadgets article. Also, to get you started on your API journey with Kuali, you can see the Kuali API Documentation. Additional resources can also be found in the API Integrations section of the Knowledge Base.

Below outlines how custom integrations can be created but you can also leverage our Built-In integration or advanced Bridge Integration options - that allow more complex integration scenarios.

Create a New API Integration

• Click on the Suite Menu icon (), then navigate to System Settings. (Spaces & Settings for Enterprise customers).  Please note, that only System Administrators or Space Administrators (for Enterprise customers) will have access to create integrations.

• 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 in Custom Integrations.
  • The +Add Advanced option is only available for Enterprise customers.  Also, if you have Bridge advanced integrations you will also have the +Add Bridge option.
  • Also, there are Built-In Integration options where you can leverage out of the box integrations using AI models, Teams, Slack, etc.
• 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

If you click "Ethos API", the configuration panel will prompt you to define an Auth URL and Access Token which allows you to access Ellucian Ethos endpoints. Kuali is an official Ellucian partner with verified integrations (more info here). 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, Email, Number, Boolean, Group Typeahead, User Typeahead, Rich Text, User Multiselect, Timestamp, Currency, and Table. 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 formatted 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.

Note: When using a Table Gadget as an Output you'll need to configure json for the table into the Table Config box:

Here is an example of the format that we would expect when configuring integration data to display in a table and what you would put in the Table Config of the output:.
 

[ 
  { 
    "formKey": "0", 
    "id": "000000", 
    "label": "Column 1", 
    "type": "Text" 
  }, 
  { 
    "formKey": "1", 
    "id": "000001", 
    "label": "Column 2", 
    "type": "Text" 
  } 
]

This is a flat array of objects - data cannot be nested in order to work with the table output. Each object in the array represents a different gadget/column within the table. This output builds the structure for how the table is going to display on the form when the data is brought in.

Keys breakdown:

• formKey: This is the key you'll end up storing the data for this gadget on. Must be unique. In the above example, there are two different form keys shown, "0" and "1". 
• id: Similarly must be unique, this one is more for internal things to work correctly. In the above example, you'll see two different IDs, "000000" and "000001".
• label: Optional, this is the text that shows up at the top of the associated column. In the above example, you'll see "Column 1" and "Column 2".

• type: This must be a valid gadget type (IE: "Text", "Url", "Number", etc).
  
  Along with this example of how to add information into the output gadget, here is how the data should be formatted when you send to our integration services for the integration to read the data correctly.  

  In this example the returned data is will provide information to fill in two rows. You'll notice that within the first data key (courseHoursTable) is an array of two objects. Each of these objects represents a row, and in each row object there is a formKey for each of the gadgets you outlined above, followed by an assigned value that is associated with that gadget on that row.
   

  "courseHoursTable": [
      {
        "0": "Info test 1",
        "1": "Info Test 2"
      }

  This returns an example that looks like this:

  

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.

Utilizing Integrations in Anonymous Forms

Anonymous forms only allow integrations that point to external data and cannot pull information from Kuali Users, Groups, or other App data for security reasons.  Once you enable the 'Create documents in this app' permission for All Anonymous Users in App Permissions you'll see that the Advanced Data Lookup gadget options in the Form designer are locked down and must be enabled:

Upon clicking 'Enable' you'll get a warning message alerting you of the risks utilizing integrations in anonymous forms.  It's important to understand that an anonymous form runs without a logged in user. That means that all backend API calls that the anonymous form makes are accessible to anyone on the internet who can determine what those urls are - sensitive data should never be shared in anonymous forms, even in the lookups.