Kuali Build allows faculty & staff to build Apps, which are made up of forms and workflows. Apps facilitate the collection of data, and allow you to perform intelligent actions based on that data. Part of the process of using and processing this data can involve Integrations, which read or write data in external systems, like Canvas, Slate, or Colleague.
This article will walk you through all the steps necessary to begin using the integrations available in Kuali Build to augment your forms and workflows.
Some integrations have been provided for you by IT. Additional integrations are available upon request. Use the Request a New Kuali Build Integration form to request a new integration. New integrations are available subject to IT department workload and institutional priorities.
Integration Basics
Integrations are computer programs. As such, they do two things: take input and provide output.
In Kuali, this input can be hand-entered, manually defined, or pulled from an existing field in a form.
The output of an integration is always the same: it becomes a potential field in a form, where it can be reused in conditions, notifications, and further integration steps. Output always comes in a specific type of data. The simplest kind of data is text -- just letters, numbers, and symbols that come back from the integration. Other types include:
- Email - can be used in notification steps as a destination for a notification.
- Number - a numerical value that can be compared with other numbers using "greater than" or "less than" (text cannot be evaluated this way)
- Boolean - a value that is either true or false
- Rich Text - a text value that preserves formatting like bold and italic.
- Timestamp - a value that indicates a specific moment in time. Like a number, this can be compared with other timestamps using "less than" or "greater than".
- Kuali User (called "User Typeahead" in Kuali) - Can be used to assign notifications, tasks and approvalsM
- Multiple Kuali Users (called "User Multiselect" in Kuali) - Similar to Kuali User, but returning multiple values
- Kuali Group (called "Group Typeahead" in Kuali) - Can be used to assign tasks and approvals. Provides access to the roles of the group as well.
There are two main kinds of integrations: integrations that operate as a part of a form (see Form Integrations, below), and Workflow Integrations (see Workflow Integrations, below).
Form Integrations
Form integrations are integrations that are processed as the form is being filled out. The data returned from these integrations gets populated into form fields before the form is submitted.
The use cases below provide examples of how to use form integrations. They are by no means exhaustive, but should give a high-level look on how integrations can be used.
Use Case: Lookup Student Information By ID
Often it will be useful in a form to pull student information from a system like Colleague prior to submitting the form.
In this case, we want to discover a student's proxId from an integration called "CDPAPI - Person Information".
To accomplish this, open the form builder in your app in Kuali, and scroll down and expand the Advanced section of the left sidebar where the form gadgets are kept. From the Advanced section, select Data Lookup (Single Item), and drag it into a spot on your form.
Then, move your focus into the settings sidebar. If you don't see the settings area for the new gadget, click the gadget in the center pane. Name the gadget "Student Info", and then hit the blue choose button in the right-hand sidebar. In the dialog that pops up, select External Data, and then CDPAPI - Person. Kuali will indicate that input (Colleague ID) is required for this integration. Click Continue.
Once you select the integration, Kuali will ask where to get the information to input into the Lookup:
Keep From data in this form selected, and choose Submitter - School ID from the dropdown menu. This will automatically input the School ID (which is automatically populated with a user's Colleague ID on login) into the integration. This will happen as soon as they load the page to fill out the form.
Note: Make sure to use School ID and not ID - ID refers to a user's ID in Kuali Build, which is different than their Colleague ID.
Still in the settings pane, enable Add linked auto-filled gadgets and drag the information you'd like to have in your form from the right sidebar into the form. Feel free to put this data in an "Office use Only" portion of the form if you don't want the submitter to be able to see it.
When the auto-filled gadgets are added to the form, they will have chain link icons to indicate that they are linked to a data look up.
In conditions and workflow steps, these auto-filled fields will appear just like any other form field in the form.
Testing Form Integrations
Unfortunately, Kuali Build the preview mode of the form doesn't allow you to test integrations when the input comes from data intrinsic to the user (i.e. "Submitter School ID"). So, when you use the preview mode of your form, you won't be able to see the data populate based on your ID. The solution to this is to move to the Workflow tab, and (whether or not you have built a workflow), open the workflow simulator by moving the slider at the top of the screen from Design to Test. When you begin to simulate the workflow, it will allow you to fill out the form as yourself, and the data integrations will work correctly.
Use Case: Select a Kuali Group
In this case, we will be selecting a group in the form from the Kuali Build list of groups, for use in an assignment in a workflow step.
As before, open the Advanced gadgets, and drag in Data Lookup (List). Then, in the settings box, click choose, and go to Kuali > Kuali Groups.
This integration does not require input from the form creator, but it does allow you to filter groups by Blueprint. By choosing a blueprint, you limit the selection of items in that gadget to just groups that belong to that specific blueprint.
When a user types in this field (next to the magnifying glass icon), the gadget will search the available groups, and allow them to select one.
What's a Blueprint?
Blueprints are categories of Groups in Kuali. For instance, we have a blueprint called Departments that all the academic departments fall under. These blueprints allow us to define roles that every one of the groups in the category will have defined. For instance, you might have a role in a Department group, called "Department Chair". While this role might be filled by different people in different groups, because it's part of the blueprint, each Department group should have a Department Chair role. You can then use these roles to assign tasks & approvals in workflows to the individuals who have been given that role in the group.
Workflow Integrations
Workflow integrations are created by moving an Integration component into a workflow. These integrations happen at a specific time during the workflow, when the workflow arrives at the integration step. Like the form integrations, they often take input and provide output.
Use Case: Get a Kuali User from a Colleague ID
This use case deals with a common problem -- you might get a Colleague (7-digit) ID from a form input or some other integration, and you want to assign a workflow assignment to the person whose ID you've received. (An existing example of this uses a form integration to get the ID of the submitter's academic advisor). In order to assign an approval to that person, we need to convert that Colleague ID into a Kuali User.
Thankfully, IT has already written an integration that does this.
To start, go to the Workflow tab of your app, and drag an integration step into your workflow diagram where you want the integration to run.
Like the form integration, click Choose, and go to External Data and choose Get Kuali User from Colleague ID.
Then select the form field that you'd like to be used as the input to this integration (could be an integration auto-filled field).
To finish out this use case, drag in an approval step, and choose A person specified on the form for the approver, then select the name of the Integration step with the Kuali User data that was returned.
Use Case: File a Document
For departments that need a copy of their Kuali Build submissions in SharePoint, we use a workflow integration to push those documents into sharepoint.
To use this, select the workflow integration called File A Document. If you don't see this integration, please contact IT and request that the SharePoint integration be set up for your Sharepoint site, and made available to your app. Use the Request a New Kuali Build Integration form for this purpose.
There are no inputs or outputs of this integration, and it's designed to be used at the end of a workflow:
Once you drag it into your workflow, you're done!