How To: Use the CNC Kaltura API
Owning ITS Area:
Devlopment
Priority (Definitions):
Medium
Need for the Article:
Last Date Reviewed:
Jan 23rd, 2024
The Kaltura Admin access is via https://tools.cnc.bc.ca/kaltura.
Only a select set of administrators will have access to use the tool. If any additional Kaltura admins need access please contact the IT Department.
CNC Kaltura Admin Pages
The user reports page is where user data can be searched and viewed. There are three ways to search for users. Each method will result in a list of users and their data. Optionally, the media ids are included in the search results.
Method 1: Search by date range
This method for searching date ranges has two properties that can be searched upon. For each property there is a date range that the property was updated in. The two properties that can be used is the "Last Login Date and Time" and the "User Updated Date and Time". For CNC users the vast majority will never sign into the Kaltura system. They will only use Kaltura through the Moodle GUI. Therefore, the search by the login date and time will yield very few results (and they will be admin users). The STATUS update is changed every time a user has their account changed which includes logging in and updating their media. Most standard users will have their updated time and date as the user creation time and date.
To search using the date range
1. Select the property to search using the date range. Options are selected using the drop-down menu:
LOGIN: Find users that last logged in between the selected date ranges
STATUS: Find users whose status was updated between the selected date ranges
2. Select the date range
Date range can be typed or copied/pasted into the text selection box or by clicking within the box can be selected using the date picker.
3. Optional: Select to include the media Ids when returning user data
This option requires more processing time on the server and will be a slower returned set of results; however, including the media Ids within the search results will make them easier to find and organize, especially if exporting the results to a spreadsheet.
4. Find the users
Select the "Find Entries" button to find users with the selected dates and optional media ids
Method 2: List All Users
This will fetch all of the users from the Kaltura API user base. The media ids will never be included in this type of lookup. The results are presented in the results table.
Method 3: List Users not active in CNC
This option will make use of the CNC database to filter the user results. The CNC user database is queried and all users that are not in the 'deleted' state are found. These CNC users are compared against the Kaltura Users to find the list that is in Kaltura but not active in CNC. The resulting list of users are strong candidates for deletion; however, the results will also show Kaltura accounts that shouldn't be removed like the user id "0" and user ids that start with "__kms".
Similar to the date range search, there is the option to add the media ids to the results table. This option is slower than the normal lookup but will additionally provide the media ids that are also strong candidates for deletion.
Loading Icon
While fetching any results, the loading icon is shown and will remain until the lookup is complete. If the loading icon is still visible, then the search is still ongoing. If the loading icon is gone and the results table is not updated, there are no results found.
Media can be found using two search methods. Both of the search methods use the same filters to reduce the number of results. The filters are a date range when the media was created and an optional date that the media was last played before (or the media was never played). The first method will show results for all media matching the search parameters. The second method further analyzes the search results to find the media that doesn't have an active user account as the owner.
The first search method finds media. The second method finds orphaned media. Due to the restricted Kaltura API the maximum results that can be queried is 10,000. If the date range has more than 10000 media entries created within that range, then only the first 10000 will be returned and the rest cannot be accessed. To access all the media, reduce the date range and ensure that the total number of media found is under 10000. If the number is 10000 in the found results, then there is very likely media that fits the search results that will not be displayed. Look at the bottom of the results table to see the total number found.
The orphaned media will only check results that are also within the 10000 found. It is suggested that the media be found using only the date ranges. If the total number in the table is less than 10000 then it should be safe to use the Find Orphaned Media to find all the media without owners within the date range. In the screenshot above, 10000 values were returned so the date range should be reduced before using the output data to ensure that less than 10000 results are shown (aka all the results for the date range are shown). In the following screen shot, the value is less than 10000 so all results are shown that were created within the given date range.
Finding media:
1. Enter the date range to find media created between the given values. Dates can be copied/pasted, manually written in date form, or selected using the date picker by clicking in the box.
Ex Find media created between July 7th, 2021 and May 23rd, 2023
2. Optionally the results can be reduced by using the "Include last played at date cutoff by clicking the checkbox and entering a date
The media created betwen July 7th 2021 and May 23rd 2023 that has not been viewed (or never viewed) since Jan 1st 2023
3. Hit the Find Entries button to find media within the dates and optional last played filter
The results are shown in the results table.
Finding Orphaned Media:
It is suggested that media be found following the step above prior to using the "Find Orphaned Media" button. That way the number of results can be observed and if less than 10000 to continue with the orphaned media.
The search results from the media date range and optional played at value are used as inputs. These results are examined and compared against the active Kaltura user base. Any media that doesn't have an active user in the user base is returned in the results table.
Media found by the orphaned media button can probably be removed from Kaltura. The user that owned the media is no longer a Kaltura user.
Results Table
The results table will display the found users or media from the search parameters. The results table has additional features that can aid the Kaltura admins in finding certain users or media.
WARNING: The table filters and sorting applied will remain until they are cleared or the page is refreshed. Performing another search will not reset the filters so new results will be filtered/sorted the same way as the last set of results
User Details
On most of the results tables the user ID is a hyperlink. By clicking the link a new tab is opened and the user details are displayed. The basic data is displayed at the top and the user's media is displayed below. If there is no data displayed and the page shows that the user id was not found, that indicates that the user doesn't exist anymore or never existed.
Excel
Firstly all the tables have an "Export to Excel" button at the top of the table. This will create an excel spreadsheet that the admin can save to their computer for later use. The export button will export the table in its current state. If the table has been filtered using the table filters (see below), then only the filtered values will be exported to excel. If the columns are turned off (see below) then only the active columns will be exported to excel. The excel export is very much a "what you see is what you get" type of export.
Sorting
The data in the columns can be sorted in ascending or descending order by two methods. The first is to simply click the title of the column and it will sort by that column. In addition, by clicking the "three dots" it opens up the selection to sort in ascending or descending order.
Filtering
The data can be filtered within the results by clicking the "three dots", selecting Filter, and then choosing the type of filter. To remove a filter, open the filter options and hit "Clear". Note, when the table results are filtered only the results shown will be exported to excel files. Filtering can be a direct match, includes a string, does not include a string, etc.
For example, User Ids can be filtered to show only Ids that contain the CNC domain.
1. Click the three dots and select Filter. Find Contains in the drop box
2. Enter the term that the values must contain
3. Now the results only show values that contain "cnc.bc.ca" in the user Id. If the "Export to Excel" is selected at this point, only Ids that contain cnc.bc.ca will have rows in the exported spreadsheet.
Columns Visible
When clicking the "three dots" there is also a Columns option with a checklist. The columns that are checked will be displayed in the table (and exported to excel). Columns that are unchecked will not be visible in the table and those columns will not be included in the exported spreadsheet.
The user details for any user can be opened by clicking the ID hyperlink of the user ID from any of the pages on the site. ONce opened the user's basic details are displayed and below them is a table for the media that user has associated with their account.
An example user details page for a test use is shown below:
Just like all of the other tables on the site, the media table for the user can be filtered or exported to excel.
If the user has been removed from Kaltura or the user never existed the User Details page will indicate this at the top of the page:
Below the user's id at the top of the page is a "Delete User" button. This will remove the user's media and then the user from the Kaltura system. This is a permenant deletion process that cannot be undone. When clicked a confimation dialog is opened.
Clicking OK will proceed to remove all of the media and the user from the userbase.
If successful the dialog will show success:
A success dialog means the user is deleted and all their media has been removed; however, due to the browser the users details will still be displayed until the page is refreshed.
Note: after deleting a user the page is not automatically refreshed. Hit F5 or refresh the browser to confirm the user no longer exists.
If anything goes wrong during the deletion a dialog will be displayed with a basic information message about what went wrong.
If any errors persist after refreshing and retrying, please contact the IT department to investigate the issue.
The media filtering way taps directly into the Kaltura API Sources to get the table results. The other tables in the web tool will use "client" side filtering in the browser which means they must download signifigantly more data from the server on every page refresh. This page will only fetch results for the number needed in the table (start table size = 30 results). This is much faster but due to the Kaltura API restrictions, only certain fields can be used for sorting and filtering. In addition, some types of filters (like the contains or doesn't contain) are not available on this page.
The export to excel features work just like the other pages. To get the full table's results and not just the rows visible, the server needs to lookup all the data and is a much slower lookup.
The table will always have results showing for the full filtering being performed. To update the rows shown in the table, update some field to filter or sort differently. The initial sorting is by creation date showing the newest first.
The Number of Views and the Number of Plays are not fields that Kaltura allows sorting or filtering. To filter by these fields (or any field that doesn't allow a robust set of options) it is suggested to export the results to excel and perform the rest of the filtering and sorting within excel.
To search media by the name
Select the contains filter and type in the search term. For example, search for media names that contain "Media":
To Filter by Dates
The dates can be selected using the filter menu. Before Date, After Date, or both are available to be entered.
Finding media that was created during the month of Feb 2023:
To Reset All Filters
To return the page to the initial setting hit the "Clear Filters" button.
The Bulk Deletion page offers a way to bulk remove media and/or bulk remove users from the Kaltura base.
The options to remove users or media is selected using the radio buttons:
Once selected the option to add the Ids within a text box is presented. Enter the Ids of either the media or the users depending upon the type of operation into the text box. These can be space " " or comma "," separated (or both) to allow copy/paste from various sources.
Once the Ids are pasted into the text box, hit "Ingest Ids" to parse the list and present the targeted Ids in a list for a final confirmation prior to deletion.
Once the list of users/media to remove looks correct, hit the Delete Users/Media button to complete the bulk deletion. When clicked, a Loading... icon is visible until the operation is complete.
If there are any errors during the process, a table will be presented with the errors found. Media or users that are not in the Error Table have been successfully removed from Kaltura.
- Navigate to the User Reports page
- Select the option to include the media Ids under the List Users not active in CNC heading
- Select the Find Entries button under the List Users not active in CNC heading
- In the results table filter the ID column by Contains and "cnc.bc.ca" to reduce the values to those with CNC login names
- Export the list to excel
This will produce a spreadsheet of non-active CNC users who still have accounts in Kaltura with all of their media Ids are included.
These are likely candidates for a bulk deletion from Kaltura.
- Navigate to the Video Reports page
- Select Jan 1 2021 in the first date picker box
- Select Dec 31 2021 in the second date picker box
- Click the optional checkbox for last played at
- Select Jan 1 2022 in the last played at date picker
- Select Find Entries to display the results
- Navigate to the Video Reports page
- Select Jan 1 2021 in the first date picker box
- Select Dec 31 2021 in the second date picker box
- Select "Find Orphaned Media" to display the results
- Navigate to the Bulk Deletion page
- Select Users or Media from the radio button group
- Paste the Ids into the text box and hit "Ingest Ids"
- Review list of target Ids to ensure correctness
- Hit Delete button
- Optional: Review the list of errors, if any