Disclaimer: Some content in this article outlines how to use functionalities thet have been publicly released to clients between September 21 and December 31, 2022. If you see differences between this article and your platform, you can download a PDF version of the documentation for the prior release.

Introduction

In your learning platform, you can create custom reports to view and analyze specific information about courses, users, training material or apps that you’ve activated. You can also schedule when to send a custom report so that it will be automatically sent via email, and view a preview of the report that you created and configured.

Your report data is refreshed in the background every hour. The refresh process takes around 15 minutes (this might slightly vary depending on the amount of data on your platform). While the data is being refreshed, you can keep previewing and exporting reports. Once the refresh process has ended, reports will return data of the previous hour.

In the following sections of this article, we will outline how to create, configure and schedule your custom reports.

Discover all of the types of custom reports available in your platform.

Find everything you need to know about how to best transition to the New custom reports feature (the guide also outlines some useful Q&As).

For the proper functioning of custom reports, if you are using a custom domain, make sure that your custom domain is fully secured using a valid SSL Certificate.

Use case scenarios

A useful scenario for Users-Courses report in a company is using the report if you need to analyze which are the activities performed by your users in the courses you created for them (for example, how many times your users accessed the course, their scores in tests, number of users enrolled in the course, etc.).

In this way, as a platform administrator, you’ll be able to keep your managers and colleagues always updated with the progress of the learning activities set up by your company. By having the tools to analyze learners’ progress for each course, you can improve your employees’ learning performance (and thus increase value for the company) by tailoring courses and training material to their needs and skills.

Another scenario for custom reports is when by analyzing the data extracted by a report you discover that, for example, your users access the course you created for them only once a month or spend only a few minutes in the course. Since your users are not dedicating enough time and effort to the learning activities you planned and created for them, you can perform some actions to make the training material in the course more interesting, more focused or to adjust the difficulty level.

You can then run again the report (or create a new and dedicated one), and schedule it to be sent every week, so that you are able to analyze if, thanks to the changes you made, you achieved the desired results. 

Creating a custom report

In order to create a new custom report, log into your platform as a Superadmin. Begin by accessing the Admin menu from the gear icon in the top right corner of your platform. Then, select the New reports item in the E-Learning section. On the main Reports page, switch to the Custom reports builder tab, where you can create and manage your custom reports.

If you have not created any reports yet, you will find an empty page without any reports displayed. If you have already created one or more custom reports, you will find them listed in the Custom reports builder tab, where you will view the reports details, filter your reports by type, schedule status or creation details, and also search your reports using the search field in the action bar at the top of the page.

If you want to preview, schedule or pause the schedule, duplicate, export, edit or delete your report, click the ellipsis icon on the right side of the report row, then select the corresponding option.  To start creating the report, select the plus icon in the top right corner of the page. The Create a new custom report right panel will open, where in the first step (Type) you’ll select the type of report that you want to generate (learn more about the different types of reports). When you’ve chosen the type, select Next to go to the second step.

In the Details step, insert a name and a description for your report. The only mandatory field is Name. When finished, press Create and edit.

Please note: When writing a name for your report, do not use special characters (the only special character allowed is the underscore “_”). If you use a language written in a non-latin alphabet, when you export your report via CSV, the report name will be latinized. Names written in Arabic characters could be truncated.

Viewing and editing the properties of your custom report

The page that will open after having selected Create and edit is composed of five tabs relating to your custom report: Properties, Filters, View options, Schedule and Preview. In the Report info section of the Properties tab, you’ll find the info that you have just inserted in the Create a new custom report right panel and you are free to edit the name and description (but not the type of report chosen) if you need to do so. In the Report download permission from link section below, when the Login required to download the report option is flagged (please note that it is flagged by default) your users need to login to the platform in order to download the report using the link they received via email or at the end of a background job. If you as a Superadmin unflag this option, everyone who has the link can download the report, with the risk of losing control of data. Please note that Power Users can activate or deactivate this option only if you as the Superadmin flag the Report download permission from link option in the Advanced options tab of the platform’s Advanced settings. Otherwise, if the option in the Advanced settings is not flagged, Power Users cannot enable or disable the option in the report.

Next, in the Time zone for date fields section you can insert the time zone in which you want to display and export your report. For example, if your company has ten headquarters, you can create ten different reports and configure the corresponding time zone for each one of them. Remember that the default time zone that you will find in this field is the one that you set in the Preferences section of your My profile page. If you didn’t change the time zone in your profile page, the default time zone will be the one you configured in the Advanced settings menu, Date and time tab of your platform. Information on managing the time zone of your platform.

Finally, in the Visibility area you can configure and manage who will have the permissions to view the report you’ve created. Read the Report Content Visibility section for more info about report visibility.

Report content visibility

In the Visibility area of the Properties tab, you can choose between the following three options:

All Superadmins

The report will be visible to all the Superadmins in the platform as well as to the creator of the report.

All Superadmins and Power Users

The report will be visible to all the Superadmins and Power Users.

All Superadmins and the selected Power Users

The report will be visible to the creator of the report, all the Superadmins and to the Power Users of your choice. If you select this option, you can type the name of one or more Power Users, groups and branches of users in the corresponding sections that appear below. You can also select them by clicking the Select button in the corresponding section. A right panel will open, where you’ll select from the list the Power Users/Groups/Branches of users who will be able to view the report. Remember that when you insert or select a branch or group, only users at Power User level will be considered. Once you have selected all the desired Power Users in the list, press Confirm. Report visibility is now granted to the Power Users you selected.

Reports permissions for Power Users are set in the Power User management area, which you can reach by selecting the Power Users item in the E-Learning section of your Admin menu. 

From the Profiles tab, you can assign the View and/or the Edit permissions to the Power User profile selected. If you select only the View permission for a Power User profile, the Power Users assigned to this profile will only see the Preview of the report and will have the possibility to export the report. If you also select the Edit permission, and the assigned Power User did not create the report, they are able to preview, duplicate and export their custom report; if they created the report, they can also (in addition to preview, duplicate and export it) schedule or pause the schedule for the report, edit and delete it. For more info refer to the article about Power Users, where you will also find the list of Power Users permissions.

If a custom report is run by a Superadmin, the administrator will be able to see all data in the report without any content visibility restrictions, since Superadmin users never have visibility restrictions in the platform. On the other hand, if a Power User views the report, they will only see the report items (Courses, Users, Branches, Catalogs and Locations) for which they have been granted visibility.

If there is the need to limit the information of a report, you as a Superadmin can create several reports with the same subject for the various Power User profiles, matching the information in the report to align with the viewing permissions for each Power User profile. Alternatively, the Superadmin can create different reports for each Power User profile, then the scheduling of the reports must be done by the Power Users themselves.

Notes about report content visibility

Please be aware of the following scenarios and conditions occurring when a new custom report is created and configured by a Power User, and then you as a Superadmin change the visibility rules set by the Power User:

• A Power User creates a new custom report and selects the All Superadmins option in the Visibility rules section in the Properties tab (please refer to the Report content visibility section in this article for more info about report visibility), and then you as the Superadmin edit the report and set the All Superadmins and Power Users option in the Visibility rules section. Then, when the Power User who created the report re-opens it, they will see that the All Superadmins and Power Users option is selected. The Power User can change this option and set the All Superadmins or the All Superadmins and the selected Power Users options, but if they want to change the setting another time, they cannot select the All Superadmins and Power Users option again.
• A Power User creates a new custom report and selects the All Superadmins option in the Visibility rules, and then you as the Superadmin edit the report and set the All Superadmins and the selected Power Users option and you add Power Users/groups/branches on which the Power User who created the report has no visibility permissions. Then, when the Power User who created the report re-opens it, they will see that the All Superadmins and the selected Power Users option is selected, but cannot see any Power Users/groups/branches names in the corresponding fields below the option and is not able to save the report because these fields are empty. This happens because the Power User has no visibility permissions on them. In order to be able to save the report, the Power User needs to change the Visibility rules configuration and set again the All Superadmins option.
• A Power User creates a new custom report and selects the All Superadmins option in the Visibility rules, and then you as the Superadmin edit the report and set the All Superadmins and the selected Power Users option. Then, you add Power Users/groups/branches A and B on which the Power User who created the report has no visibility permissions, and Power Users/groups/branches C and D that the Power User can view. When the Power User reopens the report, they will see that the All Superadmins and the selected Power Users option is selected, and will only be able to see Power Users/groups/branches C and D (and not A and B) in the corresponding fields below the option. The Power User is able to save the report because the fields below the option are filled (with C and D), but by saving the report, they will overwrite some of the changes made by the Superadmin (the addition of A and B will be lost). 

The behavior is the same in the Filters tab, when selecting new users/groups/branches/etc.. Also, the behavior is the same if a Power User creates and configures a custom report, and then a Superadmin removes the permissions that the Power User has on other Power Users/users/courses/etc.

Choosing the filters for your report

Now reach the Filters tab of your custom report page to choose the filters that you want to apply to your report. The information you see in the Filters tab is determined by which type of report you flagged to generate. It could be info relating to users, courses, courses expiration dates, enrollment and completion dates, enrollment statuses, training material types, user additional fields etc. If you display date filters in the report, remember that the time zone is the one set in the Time zone for data fields section in the Properties tab. Note that if you select more than one filter (Users + Branches + Groups) the report will include the results for every selected filter. For more info, refer to the Viewing and Editing the properties of your custom report section in this article.

Once you’ve selected all of the information you would like to include in your custom report, move to the next tab, View options.

Notes about choosing the filters for your report

• If you created a report involving courses, in the Filters tab you find a field where you can add a course category. When selecting a course category, its subcategories are not automatically selected, and as a consequence the courses assigned to the subcategories are not included in the report. If you want to select one subcategory to include its assigned courses into your report, in the right panel that opens to select the category, you need to click the arrow button on the right side of the category row and manually select the subcategory you want to add.

• When you display date filters in the report, remember that the time zone used to save dates is always UTC, regardless of your time zone. As a consequence, it may happen that you find in your report dates that are different from the ones set in the report filters (it can be the day after or the day before), since dates are saved in UTC and not in your time zone.

• When configuring the Filters for the Users-ILT Sessions custom report, remember that the Date options section found in the Filters tab refers to the course and not to the session. Therefore, setting the Completion date filter will filter only for the users who have completed the course and not those who have completed a session.
• When a Power User creates a custom report, they can use the filters only when they are associated with a profile having View permissions over the item selected in the filters. Having said item assigned to the Power User as a resource is not enough to grant them permission to use the corresponding filter. Learn more on Power User permissions.
• If you created a report including courses, in the User options subsection of the Filters tab you find an option allowing you to show in the report only learners, or also users with other course levels (such as instructors). The new custom reports where you find this option are:
• Users – Courses
• Users – Course enrollment time
• Users – Webinar sessions
• Users – ILT sessions
• Groups/Branches – Courses
• Users - Training material

Since with the new management of classroom courses and webinars (ILT courses) the instructors are no longer counted as enrolled users, for reports involving courses remember that you can use the Show only users with learner as user course level option to either include or exclude instructors in the custom report. By default, the new custom reports count the instructors assigned to the ILT course as enrolled users (the option is not enabled), but if you enable the option, instructors will not be counted as enrolled users. Please note that, instead, in the Courses-Users reports the Show only users with learner as user course level option is enabled by default (and instructors are not counted as enrolled users), but you can disable the option when you need to count the instructors as enrolled users.

Configuring the view options for your report

In the View options tab, you can select the fields that you want to display in your report and choose the order in which data are shown.

In the Report fields section of the tab, the fields are grouped according to their area. Please note that the areas differ from report to report, and are determined by which type of report you flagged to generate. Here, select the fields you want to display. Note that some fields are selected by default (they're grayed out) and you cannot deselect them. As an example, in the Users-Courses reports, the default fields are Username and Course name. In the Sorting options section, you can decide to order the data in the report according to the option proposed (it varies in the different types of report). You can also choose a custom field for the report sorting from the dropdown menu, where you can select one of the fields you chose in the Report fields section above. Once selected the field, you can choose if you want to apply the ascending (A-Z) or descending (Z-A) order. 

Remember that selecting a custom field for the report sorting could affect the report generation speed.

In the Columns sorting subsection (Sorting options section), you can configure a custom sorting for the columns in your report (that correspond to the fields you already selected in the Report fields section). In the preview of your report and once exported it, you’ll see the sorting that you choose here. When you select the Configure your custom columns sorting option, the Configure sorting button will appear below. After having pressed it, a right panel opens, where you’ll see the list of all of the report fields you previously selected in the different groups of the Report fields section. Drag & drop the report fields in the list to reorder the columns of your report. When ready, select Confirm to apply the order you chose.

Notes about configuring the View options for your report

• If the custom field you choose from the Select field dropdown menu is an additional field, and if the value of the additional field is a number, numbers won’t be sorted in numerical order, but they will follow lexicographic order. Numbers will be ordered based on the order of their components (digits) and each digit is ordered separately: the first digit is considered first and numbers are ordered based on the first digit, then the second digit, finally the third digit (as an example, if values are sorted by ascending order, 80 will be before 9, because when considering only the first digit, 8 is less than 9).
• If you need to protect sensitive information included in your report, you as a Superadmin can choose to display in the View options additional fields that are invisible to the users, but visible to you and to Power Users with granted permissions (Admin can see invisible fields permission in the Power Users profile management menu).
• If you have selected the Archived Enrollment (Yes/No) checkbox in the Enrollment Fields section, please note that this option does not cover Enrollment Additional Fields. Therefore, if you have added Enrollment Additional Fields to your report, the value will be blank for archived enrollments.
• If you are seeking to report usage for the mobile app, there are view options available in the Courses - Users and Users - Courses reports showing the following usage statistics:

  Courses - Users report

  Training material access from mobile app

  This field shows the number of users enrolled in the course who accessed the training material from the mobile app

  Training material access % from mobile app

  This field shows the percentage of users enrolled in the course who accessed the training material from the mobile app

  Users - Courses report

  Training material access from mobile app

  This field provides a yes or no answer showing if a user accessed the training material for a course from the mobile app

  % of Training material from mobile app

  This field shows the percentage of the total time that the training material of a course was consumed from within the mobile app

  Time in training material from mobile app

  This field shows the time (in seconds) of the session spent by the user consuming training material in the mobile app

Scheduling a custom report

Once you’ve selected all of the information you would like to include in your report, you can schedule when the report will be automatically sent via email. To do so, move to the Schedule tab of your custom report page.

Here, you can create your schedule. First of all, the Enable scheduling for this report toggle in the Activation section on this page should be active in order to be able to schedule your report. If you don’t want to schedule your report, switch this toggle off.

When scheduling your report, define how often you want to send it. In the Schedule this report section, type the number of days, weeks or months, and, in the From field, set the date on which you want to send your report for the first time. In the Start time field, choose at what hour you wish the report to be generated from the drop-down list. Please note that if you set the 31st day of the month in the From field and the following month has only 28, 29 or 30 days, the report will be sent on the last day of the month, even if it’s not the 31st.

Then, in the Recipients section, type the email addresses of the report’s recipients (you can add up to 25 email addresses in this field). To insert an email address, remember to press "Enter" on your keyboard when you finish typing it, otherwise it won't be saved correctly. If you want to check or change the email address that will send the email to recipients, reach the Advanced settings item in the Admin menu. On the Advanced settings page, find the Registrations, lost passwords and background jobs email sender section in the Self registration tab. The address inserted in this field is the one sending the emails.

The emails that you insert can also be external to the platform. A link to download the report will be included in the email sent to all of the users you added in the Email address (required) field. By sending a link instead of an attachment, your users won’t have any issues due to large files to download. Remember that the link expires a month after it has been sent. 

The scheduled report will contain all data included during the configuration steps, regardless of visibility restrictions of recipients, even if the recipients are Power Users with certain visibility restrictions. I.e. a Power User recipient that has only been given permission to view specific branches or users may still see all branches or users in the report, even the ones that they have not been granted permission to view.

A best practice would be to create different reports and different schedules according to Power Users permissions (different reports for Power Users having different permissions, the same report for Power Users sharing the same permissions). This will allow the Power User to view only results specific to the courses, users, catalogs, and locations they have been assigned to.

Remember that you can also schedule your report from the main custom reports page. Here, find the report that you want to schedule in the list of reports you’ve created, then press the ellipsis icon on the right side of the report row. From the dropdown menu, select the Schedule item.

When you’ve finished configuring all of the settings for your report, remember to select Save changes at the bottom of the page (even if you can also save changes in every single tab). The settings you configured will now be applied to your custom report.

Notes About scheduling a custom report

• Report scheduling is available only for customers with Enterprise plan subscription
• When a scheduled report generation is triggered,  the report will contain the latest available data. For more information on the data refresh process, check the corresponding section of this article
• Report schedules are based on the current visibility and permissions of the user (Superadmin or Power User level) who created it, who is its owner. If the report’s owner permissions change and the owner has no longer the permissions needed to schedule the report — for example the Superadmin or Power User who created the report has been deleted or their user level has been changed from Superadmin or Power User to normal user — the scheduling process cannot be executed. In this case, we suggest duplicating the report, so that you become the report’s owner and you are still able to schedule it.
• In order for a scheduled report to be sent out to the recipients, the author of the report must be an activated user. If the author of the report is a deactivated or an expired user, the scheduled report will not be sent out. Duplicate the report as an activated user in order to properly schedule and send the report.

Viewing your custom report’s preview

In the Preview tab on your custom report’s page you will see a preview of the report that you created and then configured in the other tabs of the page (Properties, Filters, View options, and Schedule). Any settings you configured in the first four tabs will be reflected in the report’s preview.

The preview shows the custom report as it will be viewed by the person that will receive it. After having checked the preview, you can then come back to the report settings configured in the tabs of the page to change some of them if you need it.

Remember that you can also preview your report from the main custom reports page. Here, find the report that you want to preview in the list of reports you’ve created, then press the ellipsis icon at the end of the report’s row. From the dropdown menu, select the Preview item.

Please note: The preview displays the first 100 rows of the report (and not all of the rows), so that you can quickly have an idea of how your report looks like. 

Automatic updates of data in your reports

Your report is always refreshed in the background.  The availability of the latest data requires a few minutes after the hour. For this reason, when you schedule your report on the hour you might not see the data of the previous hour but the data of the hour before that. 

Please note!  If Power Users have new resources assigned, they will not be able to immediately perform report extractions for them until the next data refresh despite having full visibility and operability on the resources. As an example, if you edit a Power User’s permissions by adding or removing courses associated to the Power User, the changes you made to the Power User permissions are NOT immediately reflected in the value of the filters available in the menu and are NOT immediately reflected in the courses that are extracted and visible in the report. Instead, filters and reports will remain unchanged until the next data refresh. Keep in mind that this delay concerns all the data so the Power User will not see any change in the data compared to what existed before your changes. For more information on Power Users, read the dedicated article of the Knowledge Base.

Exporting your custom report

You can export your report in CSV (Comma Separated Values) and Excel. The maximum length for a .csv file is 1.5 million rows, while the max length for an .xls file is 1 million rows. You have two possibilities to export a custom report:

• From the report page, press the Export icon in the top right corner, then choose between .csv and .xls file type.
• From the main custom reports page, find the report that you want to export in the list of reports you’ve created, then press the ellipsis icon at the end of the report’s row. From the dropdown menu, select the Export item, then choose between CSV and XLS.

It usually only takes a few minutes to export your report. When you launch the export, the process will run in the background with a background job, so you can continue to use your platform and your device without any restrictions during the export process. When the background job ends, you will be notified via email and a notification will be shown in the background job notification area, accessible by clicking on the arrows icon displayed at the top of the platform while the background job is being executed. More information about background jobs.

Notes about exporting a Custom report

• In order to export reports, the Notifications app must first be enabled
• Your report is always refreshed in the background. The availability of the latest data requires a few minutes after the hour. For this reason, when you schedule your report on the hour you might not see the data of the previous hour but the data of the hour before that.
• When you export a custom report, only alphanumeric characters will be rendered as text in the CSV or XLS file. Special characters are not supported and will not be rendered correctly in the exported file. 
• When exporting New reports, the date format of the exported data cannot be changed

Best practices

• If you want to include all users in the report, we recommend to select the root branch rather than each individual user, so that when you add new users to the system, you will see them included in the report without the need to add to the selection.
• Create different reports and different schedules according to Power Users permissions (different reports for Power Users having different permissions, the same report for Power Users sharing the same permissions). This will allow the Power User to view only results specific to the courses, users, catalogs, and locations they have been assigned to.
• Let’s consider that you need to protect sensitive information included in your report. For this reason, you flag the Login required to download the report option in the Report download permission from link in the Properties tab before moving to the Schedule tab to schedule your report and send the report download link to recipients email address. Then, let’s consider that you delete sensitive info included in your report and decide to unflag the Login required to download the report option (by removing the flag, everyone who has the link can download the report). Be aware that in this case all the links sent to recipients when the option was flagged still relate to the “old” version of the report (the one including sensitive info). In this way, having removed the flag, all of your report’s recipients will be able to download the report without the need to login to the platform, and, considering that the “old” version of the report contains sensitive info, this situation is obviously not ideal for security reasons. If you really need to unflag the Login required to download the report option, please wait until the old link expires (30 days).
• If you are experiencing malfunctioning of your custom reports and you have an Ad Blocker enabled on your browser, please pause the Ad Blocker for Docebo platform's page. Note that issues can be caused by the Ad Blocker that you're using.