How to Create an API Integration

Contents

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

Create a New API Integration

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

• From your Kuali Build Dashboard click on the Kuali Build dropdown menu in the upper left corner. Click System Spaces
  
  *Spaces is only available with an Enterprise license. If you do not have an Enterprise license, your integrations can be controlled from System Settings
  
  
• You will find yourself on the API Integration page. Click on + Add API Integration or Add Advanced 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.

• Fill in the remaining information. 

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

If the url you're using points to an external source (i.e. Googlesheet, etc) you'll need to provide the authentication info to access (if any).  Refer to your source's documentation, and click on the type of authentication stipulated, either No authentication, Basic authentication, Bearer authentication, or Oauth authentication.

• Verifying Authentication to access the API Source
  • 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 Googlesheet anyone with link can access).
  • 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 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 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 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"}.

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. 

• To do this navigate to the System API Integrations list. From the Kuali Build dashboard click on the Build menu at the top left of the screen.
• Select System API Integrations and find the integration you just created.
• Click on the cog icon. 
• From there you can determine the availability of your integration:
  • Do not share the data
  • Share with ALL Build apps (default)
  • Share with only SPECIFIC Build apps.
• If you select Share with only SPECIFIC Build apps you will then be prompted to add a list of apps that can access the data from this integration.
• 

IMPORTANT NOTE: 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 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]

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.