This guide is the fifth in a new series of new guides brought to you by
A common question is how to mark a large amount of users complete within a course with a certain date. While there are methods to do this from the front-end UI, they can be error prone and take a while as you have to select all the correct users. There is an API endpoint that allows you to update enrollments for a bulk group of users: PUT - /learn/v1/enrollments
Before we go further, note that this will only work for cases where the user is already enrolled in the course. If they are not found in the course, the endpoint will return an error and not process the completion status. If you are trying to enroll and mark the user complete in the same action, stay tuned as that is coming in another guide soon.
Important Note: The API endpoint we will be using requires a PUT call, meaning it will update and change information on your system. It is highly recommended to test in a sandbox environment before doing this in a production setting. Additionally, it is always advisable to download a backup report of all current statuses, especially completions, prior to performing this API call (just for safety).
Getting the Information Together
In order to leverage this endpoint, you will need to gather a few pieces of information—some easy, others not quite as easy. Some of these can be retrieved in more ways than one, so choose your preferred method for doing so.
Docebo User IDs
First and foremost, if you are going to be updating a large amount of users, you need to know which users those are. Ultimately we need this to be a comma separated list of the User Unique IDs.
Note: Due to performance considerations, this operation will be capped at 1,000 users per call. You can easily make batches of users and swap them out to quickly unenroll more than 1,000 users.
While there are several methods for retrieving these IDs, in this particular case I highly recommend simply making a ‘Users – Courses’ or a ‘Users – Learning Plans’ report, whichever is appropriate. When defining your report, make sure to check the box ‘User Unique ID’ under the User Fields selection area:
This will add a column of the exact IDs we need. Use the report to sort/filter/organize your data to identify the users.
When you are ready, we need to convert the column of ‘User Unique IDs’ to a block of comma separated values. There are many ways to do this, so feel free to use your own preference (i.e. concatenating a comma to the end of each row, using TEXTJOIN to merge a defined range, etc.). If you do not have a good or fast way to do this, the easiest is to:
-
Copy the column of ‘User Unique IDs’ that you want to use to your clipboard.
Note: Skip the heading, we only want the User ID numbers.
-
In the top box, paste the User IDs into it:
-
Scroll down to the bottom box and you will find all the IDs separated by a comma, which is exactly what we want. Copy and paste this in a place you can refer to later (or just leave this webpage open for the time being).
Course ID’s
If you are updating the User’s within a Course, you need to know the Docebo Unique ID of the Course. There are three main ways to find this:
Using Reports
The Course Unique ID is available to select under the ‘Course Fields’ area. Simply make sure to select this option when crafting your report and the ID will be easily available to you:
In the Front End
You can also identify individual course IDs directly via the course management area.
-
Navigate to the ‘Course Management’ area in the Admin Menu.
-
Search for and select the course you need the ID of.
-
Look at the URL in the address bar of your browser and the course ID will be found at the end of it:
Using the API Browser
-
Log into your Docebo instances API Browser by going to: https://<yoursubdomain.docebosaas.com>/api-browser/
-
On the ‘Services’ menu, select ‘course’.
-
Scroll down the left side to find and select the ‘Courses’ category.
-
Select the ‘Returns courses available in the platform’ option.
-
You can adjust the parameter fields as much or as little as you want to help find the courses you are interested in. There are a few I would recommend paying attention to:
-
search_text: Enter text to search the course title and code fields. Only the courses that match the search text you enter will be returned. This is useful to narrow down the plans.
-
type: If you have courses with similar names but are different types, this is useful to make sure you don’t mix them up. I typically use either ‘elearning’ or ‘classroom’ in this field to distinguish between them.
-
status: Similar to the ‘type’ parameter listed above, I like to set this to ‘published’ so that only those courses are returned, but you may want to use different values to distinguish courses.
-
page_size: This endpoint can have very long lists. To avoid performance issues it will make pages of results. This lets you set how many items show up on a page. By default it is 10 items. The maximum size is 200 items. Enter an appropriate number for your needs here.
-
page: This endpoint can have very long lists. To avoid performance issues it will make pages of results. This field lets you choose which of those pages you view in the output. For example, if you have 50 courses and the page size was set to 20, 3 pages would be generated. When you initially run the endpoint you will see items 1-20. If you put a 2 in this field you will then get items 21-40, a 3 and you’ll get 41-50, etc.
-
-
Select the ‘OAUTH’ button underneath the options and sign in if you have not done so already.
-
Select the ‘Try’ button.
-
The results will be shown in the middle of the page. The relevant information will be found in the ‘Response Body’ box. The line ‘id’ for each course shown is the ID you are looking for, so make a note of it:
Note: If you are planning to enter more than one course at a time, you will need the IDs in a list separated by commas (similar to the user IDs). It is easy enough to do this while you are collecting the IDs or, if you used the report technique, you can simply enter them into the conversion website like you did with the user IDs.
Updating
OK, you have now gathered all the needed information—User IDs and Course IDs. Now it is time to format the information correctly to do the actual call using the API Browser.
-
Log into your Docebo instances API Browser by going to: https://<yoursubdomain.docebosaas.com>/api-browser/
-
On the ‘Services’ menu, make sure ‘learn’ is selected if it is not already.
-
Scroll down the left side to find and select the ‘Enrollment’ category.
-
Select the ‘Update enrollment of users to courses (Multiple update)’ option.
-
Copy the following into the ‘body’ box:
{
"user_ids": [
0
],
"course_ids": [
0
],
"date_complete": "YYYY-MM-DD HH:MM:SS",
"status": 2
}
-
Copy your block of User IDs from above and replace the ‘0’ in the ‘user_ids’ section. Make sure there is no comma on the end or you may receive a syntax error.
Note: Make sure only 1,000 IDs are placed in here at a maximum. You can easily swap batches of 1,000 users after each call.
-
Replace the ‘0’ under ‘course_ids’ with the course(s) you wish. Make sure there is no comma on the end.
-
In the ‘date_complete’ field, change the ‘YYYY-MM-DD HH:MM:SS’ to the completion date you want reflected on the users’ enrollment record. For example: If I wanted October 31, 2022, I would put: “2022-10-31 12:00:00”.
Note: There should still be double quotation marks around the date when you enter it.
Tip: The LMS will consider the date you enter as being in GMT. If you omit the time or make the time close to midnight, the date may be recorded as the previous day when viewing via the UI (depending on your platform’s time zone).
To avoid this issue, I typically enter the time as noon so there is a safe margin. If you care about the precise time being entered, you will need to factor in for the time change. (I hate time 😊)
-
Your setup should look similar to the example below. Here I have 3 users being updated in one course:
-
Select the ‘OAUTH’ button underneath the options and sign in if you have not done so already.
-
Select the ‘Try’ button.
- The result will show in the middle of the screen in the ‘Response Body’ box. Make sure to review it for potential errors. Each successful update should be noted:
If there is an error, it will be noted in the response. In the example below, one of the users was not enrolled in the course to begin with and could not be updated:
That’s it! The users should now be updated to a complete status with the date you provided. If you had more than 1,000 users or need to do batches of users with different completion dates, just swap the appropriate information and hit ‘Try’ again.
From looking around the community, there seemed to be a regular need for ongoing management here, so hopefully this helps! The big drawback here is that you can only specify one completion date and the courses apply to all the users in the call. If you need more flexibility, there is a way to achieve this, but it requires the users not to be enrolled to begin with. If this suits your needs more, sit tight and keep an eye out for the next guide in this series—where we will cover how to do just that!
More API Browser Quick Grabs:
Bulk Update Course information
Bulk Unenroll Users from Courses or Learning Plans
Bulk Enroll and Mark User Complete in a Course
Bulk Remove Power User Level from Users
How do you use the API Browser? Are there any endpoints you don’t understand or use cases you’re looking for input on? Comment below!
