This guide is fairly technical. If you find the process to be confusing, you may want to reach out to a member of your team who is familiar with working within an API - but please do not hesitate to reach out to our Support team for assistance. It is strongly recommended to test within your staging or sandbox environment prior to running any updates of this type or Production.
Occasionally, you may find that you need to make an update to a large number of records at a time - and while there aren't any tools in the UI to process a bulk update - you can achieve this by using the API.
There are two things to keep in mind when you are considering making a bulk update: you need to identify all of the records you will be making a change to and you will need to ensure the updated information is formatted correctly in JSON.
It might sound a little overwhelming at first if you have never worked with an API or JSON - but if you take it slowly and go step-by-step, you'll become proficient in it pretty quickly! If you have any questions while you are attempting this process, please be sure to reach out to our Support Team.
Identifying Records to Update
The first step will be to identify which records you will need to update. This will include the item type (programs, courses, specializations, experiences, or policies), the status, and then any other criteria you have to narrow down by, and you will need to prepare these records in a CSV to be able to update via the API.
There are two ways that you can obtain the information regarding your records: either the Reports module in the UI, or you can use the API to retrieve the data.
Identifying Records via Reports
To use the Reports module, start by selecting Reports from the left navigation. Next, you will need to select the specific type of content you need to update - for the examples used in this guide, I'll refer to Courses.
Next, you will need to specify the columns you will need. At a minimum, you will need to make sure that you include the Item ID and the field you need to modify. You may choose to include additional columns as needed to help you identify each record, but they are not required.
- If you are going to be adding content that hasn't existed before, first be sure that the field has been added to your form. If the field has not yet been added, make sure to reach out to our Support Team to have it added.
For this example, I will be updating course records to include a radio field titled Level, and adding in the value for either Graduate or Undergraduate.
In the report, you would start by selecting Configure Columns from the upper right corner.
Next, you will need to select all of the fields you need in your report. For this example, you will need Item ID - but it will be helpful to include the Code and Title fields so that you can easily identify each course.
To add a field, ensure the box to the right is checked. To remove a field, uncheck the same box. You can also drag and drop the fields in the list if you would like to reorder them.
Next, you will go to the Filters tab to narrow down the results. The first setting is the Status - not all records can be modified, so it is helpful to select only the options you will be able to make changes to.
- You are able to update records with a status of Active, Retired, Inactive, Draft, and Under Review.
- Active, Retired, and Inactive records will be the current version of an item.
- Drafts will refer to any items that have not yet been entered into the workflow.
- Under Review will be items currently going through workflow.
- You will not be able to update records that use the Approved, Denied, or Revision status.
- These statuses refer to the proposals involved, not the actual record, and can not be modified either through the API or directly on the item itself.
Once all of your selections have been made, you can return to the Actions tab, and select Download CSV. You may also choose to save the report, if you may need to refer to it again later.
Once the file has downloaded, you will need to begin the steps to prepare your CSV for import.
Identifying Records via the API
If you would prefer, you can retrieve data through the API directly rather than using the reports module. Although you can run calls within the browser, you may find it helpful to use a tool such as Postman to review the data. This example will show screenshots using Postman, so if you are using a different tool the steps you take may be a little different.
Within Postman, select the option to create a new request.
Next, you'll set up your request to retrieve specific data.
- You can refer to https://developers.kuali.co/ for information on available endpoints
To start creating the request, in the Get field, you'll enter the URL for the data you want to retrieve. The URL will include the address for your instance of CM, the type of item you want to retrieve, and what attributes you need.
In this example, in order to refer to course information - my sample call would look like this: https://monsters2-stg.kuali.co/api/cm/courses/queryAll
Tools like Postman are particularly helpful for building out your requests, as you can enter data into the various fields to populate the full URL for you.
Under the URL field, there is a row of tabs to select that are used to finish building out the URL and entering any other needed information - such as log in attributes.
The Params tab will help identify the information being called. The two primary fields being used are key and value. Key will be the field you want to reference, and value will be the data within. When you are looking for the data in specific fields on all records, you can enter fields as the key, and the name of the field for the value.
In this example, enter fields as the key, and then enter _id,subjectCode,number,title into the value - with no spaces between. The comma is used to separate the field names. You'll see the URL update as you enter information. Entering it this way looks for all of these fields on each record.
Next, you will add in a second key for status - not all records can be modified, so it is helpful to select only the options you will be able to make changes to.
- You are able to update records with a status of Active, Retired, Inactive, Draft, and Under Review.
- Active, Retired, and Inactive records will be the current version of an item.
- Drafts will refer to any items that have not yet been entered into the workflow.
- Under Review will be items currently going through workflow.
- You will not be able to update records that use the Approved, Denied, or Revision status.
- These statuses refer to the proposals involved, not the actual record, and can not be modified either through the API or directly on the item itself.
Unlike the fields key, this time you will enter five keys - one for the active, retired, inactive, draft, and review statuses.
Next, you will need to select the Headers tab to enter your authorization. There are two fields that need to be filled in - Key and Value. In the key field, you'll select Authorization, and in the value field, you'll enter Bearer followed by your API key. You can see how to generate the API here if you don't already have one.
Your results will be returned in JSON, and because of the fields selected, will include the id, subjectcode, title, and number for each course that needs to be updated. If you are not familiar or comfortable with the format of the JSON provided, you can click the copy icon in the corner and use a tool to convert the information into a CSV.
Now you are ready to begin the steps to prepare your CSV for import.
Preparing your CSV
Once your information is within a CSV, you can begin preparing the file for import.
CSV from Report
If you have exported the report from CM directly, and are following the steps above, then your report will include only three fields: Item Id, Code, and Title.
You will only actually need Item Id to process the import, but Code and Title can be used to help you identify the courses for the purpose of updating.
The next step will be to add in the new information that will be used to update the courses. For this example, we are adding in a value of either graduate or undergraduate into a radio field titled 'Level'. Add a column into your CSV for Level, and then review your courses and enter the appropriate value for each one.
In this example, the values on the form are either Undergraduate or Graduate, but you'll need to use the API label for each value to update the courses. An API label will always start with a lowercase letter, and will not contain any spaces. In this case, we will have undergraduate or graduate as options.
Once your values are added, you can remove all columns except for Item Id and the field you're updating - level. This step isn't required, but it's always easier to work with a file that is as small as possible - and it helps reduce errors.
Once your file has reached this point, make sure to save it as a CSV, and then continue on to updating via the API.
CSV from API
If you have exported the report from the API, and are following the steps above, then your report will include number, title, subjectCode and id.
You will only actually need id to process the import, but number, subjectCode and Title can be used to help you identify the courses for the purpose of updating.
The next step will be to add in the new information that will be used to update the courses. For this example, we are adding in a value of either graduate or undergraduate into a radio field titled 'Level'. Add a column into your CSV for Level, and then review your courses and enter the appropriate value for each one.
In this example, the values on the form are either Undergraduate or Graduate, but you'll need to use the API label for each value to update the courses. An API label will always start with a lowercase letter, and will not contain any spaces. In this case, we will have undergraduate or graduate as options.
Once your values are added, you can remove all columns except for id and the field you're updating - level. This step isn't required, but it's always easier to work with a file that is as small as possible - and it helps reduce errors.
Once your file has reached this point, make sure to save it as a CSV, and then continue on to updating via the API.
Updating via the API
Once your CSV has been prepared, you're ready to import the new values into CM directly. you may find it helpful to use a tool such as Postman to review the data. This example will show screenshots using Postman, so if you are using a different tool the steps you take may be a little different.
Within Postman, select the option to create a new request.
Next, you'll set up your request to send specific data.
- You can refer to https://developers.kuali.co/ for information on available endpoints
To start creating the request, in the Get field, change the dropdown and select Put. Next, you'll enter the URL to indicate where the information will be sent. The URL will include the address for your instance of CM, the type of item you want to update, and the unique identifier for each item to be updated.
Part of the preparation for this process involved making sure the item id was included within your CSV - this will serve as the unique identifier for each item, and allows us to set a variable in the URL using brackets: {{id}}
In this example, to update my course information - my sample call would look like this: https://monsters2-stg.kuali.co/api/cm/courses/{{id}}
Under the URL field, there is a row of tabs to select that are used to finish building out the URL and entering any other needed information - such as log in attributes.
Select the Headers tab to enter your authorization. There are two fields that need to be filled in - Key and Value. In the key field, you'll select Authorization, and in the value field, you'll enter Bearer followed by your API key. You can see how to generate the API here if you don't already have one.
Next, select the Body tab. Under the the tab will be a row of options - select Raw, and then change the drop-down from Text to JSON.
In the text field, you will need to provide the details of what is being updated, formatted in JSON. In this example, we will be updating a radio field called Level with a value from our CSV under the the column for 'Level'. Formatted in JSON, that would look like this:
{"level": "{{level}}"}
Once this has been entered, if you are using Postman, save your request. Next, select Runner from the bottom of the window.
On the right, choose Select File and select your CSV. Once selected, the Iterations shown should match the number of rows in your file.
From the left, drag the saved request into the Run Order window.
Then select Run from the right to begin processing the records. As it runs, each item in the file will process and provide a result. If you see 200 OK, then item was processed successfully.
You can now view your courses in CM and see the update that has been applied. Running a report on the updated field will quickly show you the new value.
Comments
0 comments
Article is closed for comments.