Create API integrations with your institution's systems to populate fields and keep your data consistent. This will allow you to utilize these integrations in your form with an Advanced Gadget: Data Lookup (Single Item), Data Lookup (List), or Data Lookup (Multiselect). For security, the integrations feature is only available to System Administrators.
- Qualify Source and Collect Requisite Information
- Create a New API Integration
- Configure the Integration
- Test the Integration
- Control Access to Integrations
- Secure Your API Integration
- Add to Your Form
Qualify Source and Collect Requisite Information
Creating an API Integration requires a certain amount of information from the source. To be considered a qualified source, it must meet two requirements:
- Publicly accessible API endpoint that returns JSON-formatted data
- Provides API documentation and authentication credentials.
To create an API integration data set in Kuali, you will need:
- Authentication: Does the source use basic authentication or bearer authentication?
- The HTTP method:
GET
,POST
, orPUT
. - The Integration URL
- Names of the fields or the structure of the JSON that's being returned.
- The query parameters that the customer API accepts.
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.
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.
- 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.
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.
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.
Add to Your Form
Once the integration has been tested and confirmed, you can reference the data on a form with an Advanced Gadget. Using either the Data Lookup (Single Item), Data Lookup (List), or Data Lookup (Multiselect) gadgets, you can then select the newly created integration as the Data Source.
- Once the gadget has been added, click the Choose button under Data Source within the settings panel.
- Select External Data under sources.
- Select the integration you would like to use, and then click Continue.
- Once added, additional settings will become available for the gadget.
- The user filling out the document loads the document.
- The user enters or changes a value in any input field required by the form integration
After the document is submitted, the data from the form integrations becomes form data just like any other gadget data.
Comments
0 comments
Article is closed for comments.