Setup API Integrations with Classic Kuali Student

Kuali rest APIs allows you to connect to external data sources including other Classic Kuali products like Kuali Academic Ops. This article goes over how to set up these integrations with some examples to get you started.

• Kuali Academic Ops API Resources
• Some Examples of Kuali Academic Ops Integrations
• Getting Courses, Programs, Experiences, or Specializations
• Getting a List of Subject Codes
• Chaining integrations together to look up Course Information

Classic Kuali Student API Resources

The APIs available for Classic Kuali Student are documented within the CM and Catalog tabs of https://developers.kuali.co. This guide also goes over how to get the necessary API key required for authentication with Classic Kuali Student in the General section.

Some Examples of Kuali Academic Ops Integrations

All of these requests are GET requests, and will look similar to the example shown below when you set up the integration in Kuali (with your specific URL/API key and appropriate Path to Results Array, ID Key, Label Key, Outputs, etc). This example is pulling a list of active courses with a query configured so the dropdown is searchable and limited to 100 results:

https://{domain}.kuali.co/api/cm/courses/queryAll?status=active&limit=100

The resulting lookup will appear like this when running a test or adding to the form:

Once the integration has been created, you can add it to the Kuali form via the Advanced gadget of Data Lookup (List) and point the data source to the newly created integration:

You can also make use of the linked auto-filled gadgets on the form so that when a user provides the course to look up, it will display the associated data on the form.

Here are a few more examples of commonly used API calls to pull information from Classic Kuali Student into Kuali Platform. Hopefully these examples can help you get started and expand on other integrations you may want to set up, but if you have questions or would like to see additional examples - let us know! 

Getting Courses, Programs, Experiences, or Specializations

You can use the API end points noted here in the documentation to query either courses, programs, experiences, or specializations from Classic Kuali Student with filters as desired:

https://developers.kuali.co/#cm-courses,-programs,-experiences,-and-specializations-query-get

For example, if you wanted to create a dropdown field in a form to lookup a list of all active programs, you could use a request like this example in the integration:

/api/cm/programs/queryAll?status=active

You can swap out the bolded text (programs) in this request with courses, experiences, or specializations depending on the area in Classic Kuali Student you want to query.

Note: The item payloads will return only a Kuali ID as the value for any fields that use an option type or reference a group. This is not typically a human-friendly format and may appear as a string of numbers. You can look up the items by their ID to determine their label or human-friendly value with requests such as these:

• /api/cm/options/{id} to look up the value of an option type
• /api/v1/groups/{id} to loop up the value of any group fields

Getting a List of Subject Codes

If you wanted to retrieve a list of all Subject Codes, you can use the end point described here: https://developers.kuali.co/#cm-options-option-type-get.

For example, if you want to get a list of the subject codes housed within the option types, you would use the following URL in the integration:

/api/cm/options/types/subjectcodes

This will return the details of the items housed as subject codes, formatted in JSON. Here is an example of how that data may look:

{
    "name": "ACCT",
    "type": "subjectcodes",
    "active": true,
    "locale": "en-US",
    "createdAt": "2024-02-23T19:50:59.119Z",
    "updatedAt": "2024-02-27T21:21:55.209Z",
    "additionalDescriptions": null,
    "description": "Accounting",
    "linkedGroup": "65d8f9cf47a697001f7e0d09",
    "id": "65d8f723718efa3ac36e9f87"
  }

Chaining integrations together to look up Course Information

There may be scenarios where you want to provide a way for your users to look up course information from Classic CM within Build by the subject code and number, and pulling the most recent version. This can be accomplished by chaining two integrations together.

Step 1: Subject Code Integration

You will need two integrations set up in Build for this to work. This will be required in order to make it possible for your users to look up a course by the subject code and number. The first one will be to get the unique ID for each Subject Code.

• This is required because of the way CM stores the Subject Code data. Although it displays on the form as an easy to read item, such as 'ACCT', it is stored based on the unique ID associated with it. In order for a user to look up a course based on it, they would have to reference it by the unique ID. We know that no one is going to know the subject codes by this ID, so we make a look up to provide it based on the human-friendly code and we will pass that to the second integration.

In Build, you would need to go to the 3 dots menu, then go to Spaces & Settings:

On the Spaces page, you would then need to go to the 'Integrations' section:

On this page, you can then create a new API Integration:

For the Integration Name, provide a name that helps you find it quickly. When you are setting up a gadget in your form later, you'll have to reference it by title - so a carefully selected name will help you find it faster. For example, something such as "Classic CM - Course Subject Code Lookup" is easy to identify, and you can change this later if you need to.

The Description is not required, but providing it can help others understand the purpose of the integration. For example, adding in a description such as 'Returns the ID for the subject codes from Classic CM'.

The Type of Integration should be set to "Get List of Data Items' so that a user can make a selection.

The HTTP Method should be set to "Get" as you will be retrieving data from CM.

The Integration URL is what we will use to tell CM the type of data we want to retrieve. For this scenario, the following URL will be used:  https://{{institution}}.kuali.co/api/cm/options/types/subjectcodes?sort=name&active=true

Note: The {{institution}} portion of this URL needs to be changed to your specific instance of Classic CM.

• This URL references your instance of CM, and points specifically to the Subject Codes option types list. This will return only the items that are currently active and will sort them alphabetically based on their name.

For API Key Header, you'll enter 'Authorization'.

For API Key, you will need to provide an API token. This can be retrieved by going into CM, going to your User Settings, and then going to API Key. Click 'Create Key' for it to generate a new key. This key will be available for one year; and you'll receive notification when it is about to expire. Here are more instructions on how to generate a key, if you need them. Make sure to save this key - once you leave the screen you can not see it again, so if you lose it you'll have to generate a new one. Once you have the key, add it to the API Key field.

Leave Path to Results Array empty. For ID Key enter 'id', and for Label Key enter 'name'.

Skip down in the form until you get to Outputs. Under Label, add 'Subject Code ID'. Under Data Path, add 'id'. Under Gadget, select 'Text'.

Now click Run Test at the bottom. You can not save the integration without a successful test. This will generate a form preview on the right side of the screen.

Under FormLabel, select the dropdown and choose any prefix. If it is working, then under Additional Preview, you'll a value entered for Subject Code ID, like this:

After the successful test, click Save. Make a note of the ID you used when you tested - you're going to need it to test the second integration! 

Step 2: Course Detail Integration

Next, you'll need to create the second integration. This will take the Subject Code Id and use it to look up a course so you can pull in the course data.

Start by going to +Add API Integration again.

For the Integration Name, again, you'll want something very specific so you can find it. For example, 'Classic CM - Course Data Lookup'.

For the Description, same as before - give it something to help clarify what this is for, such as: 'Uses the Subject Code Id to look up courses in CM and return associated data.'

For Type of Integration, you'll select 'Get List of Data Items' again.

For HTTP Method, you'll select 'Get' again.

The Integration URL will be slightly different for this one, since you need to get course data instead of subject code information. This URL will look like: https://{{institution}}.kuali.co/api/cm/courses/queryAll?subjectCode=&number=&status=active&status=draft&status=review&limit=1&sort=number,-dateStart

• This will look up all courses provided you enter the ID for a subject code and a number; and it will return the most recent item based on the date start, as long as it has an active, review, or draft status.

For Authentication Type, it will be 'Bearer Authentication' again, and the API Key Header will use 'Authorization'. The API Key will be required again, and you can use the same one as before.

Path to Results Array will be different this time, and need to include 'res'. The ID Key will be set to 'id' and Label Key will be 'number'

This time, you'll need to enter URL Inputs so that a variable can be passed to look up a course. You have two variables - subject code and number, so you'll need to enter them like this:

Under Proxy Request, check the box to Enable it.

Under Search Parameter, select 'URL Param: Number'.

Under Outputs, you'll need to indicate what fields you want to bring in from CM. You can choose as many fields as you want, and you don't have to show all of them on the form if you do not want to.

Under the Label column, you would put the human friendly version of the field, and the Data Path column needs the API key for the field. The Gadget should indicate the type of information that it should import.

You can change these if you need to, but here is an example of a selection of fields such as Title, Status, Start Term, and Credits. 

Note: Each institution is different, and your field labels and API Keys will be unique - so make sure to double check what is used within your forms to make sure the data imports as expected.

• Start Term is also commonly referred to as either Effective Date or Start Date, but would use the API Key of dateStart. In this example, dateStartLabel is used instead so that it will return the term name rather than the calendar date - such as 'Fall 2024'.
• The Range-Fixed, Credits Min, Credits Max, and Value fields all refer to credits. If you use ranged credits, or provide options, you may need to include each of these values in order to display the credits correctly when importing.

Now, click Run Test. To test it, you will have to enter a Subject Code by Id.

• These integrations aren't yet chained together - so you need to use one to test. Once you have entered the Subject Code, enter a number of an existing course into the Form Label field. I used '193V' as the example.
  
  Your test results should resemble this:

Note: It is okay that 'Value' says Invalid Data Shape. This is because this course does not have any data in that field. You need this field for courses that have a 'fixed' value instead of a 'ranged' value.

Save the integration after a successful test, and now you are ready for Step 3!

Step 3: Add fields to form and chain

Start by adding the Repeater gadget to your form, and be sure to Enable the calculation footer. You can name it anything you like, and you can edit it later if you need.

Drag a Data lookup (List) gadget into the repeater. I named it 'Subject Code'.

Under Data Source, click Choose. Go to External Data, and then lookup the first integration you created - 'Classic CM - Course Subject Code Lookup' and click Continue. This will add a dropdown menu to the form that provides a list of subject codes.

Note: You do not HAVE to display the id. This can be passed into the second integration without being shown to the user.

Now drag a second Data Lookup (List) gadget into the form next to Subject code. I titled this 'Number' and you will use this gadget to pull in all of the other fields. It should look like this to start:

Under Data Source, click Choose. Go to External Data, and then lookup the second integration you created - ;Classic CM - Course Data Lookup' and click Continue.

Once added, there will be a field titled Subject Code in the configuration. This field is required in order to look up a course. The first radio is selected by default, and you need to select the Subject Code field that you just added. Then click the gear icon next to it, and choose 'ID' for the value.

This allows the ID from the first integration to be passed into this one, so that your users can select the human friendly subject code instead of needing to enter the ID.

Next, in the config, turn the toggle on for Add Linked auto-filled Gadgets. This will let you drag fields into the form that are related to the course. Drag in all of the fields you want to display when a course is selected. 

Note: If you would like, you can use the visibility to only show either the ranged credit fields, or the value of a fixed field when relevant, rather than showing all three all the time. For example, you may choose to set 'Value' to display only when the Ranged-Fixed field is set to 'fixed', and the Credits Min and Max fields to only show when the value is 'range'.

Lastly, make sure the repeater has the calculation footer set up so that 'Sum' is selected for Credits Min and Credits Max. (Don't set it for Value as it will error if a course has nothing in this field).

Now you can test it by selecting a subject code and entering a number. For example, ACC 193V:

And you're done! Now your users will be able to look up a course by subject code and number from CM!