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 Visibility section for more info about report visibility.

Report visibility

In the Visibility area of the Properties tab, you can set the visibility rules for a report. These will determine which users will be able to see the report listed in the New reports page:

All Superadmins

The report will be visible to all the Superadmins of the platform. It will not be visible to any Power User, apart from the one who creates the report (subject to their report permissions).

All Superadmins and Power Users

The report will be visible to all the Superadmins, and to all Power Users (with report permissions) of the platform.

All Superadmins and the selected Power Users

The report will be visible to all the Superadmins, to its creator (subject to their report permissions) and to a selected subset of Power Users. You can:
- specify individual Power Users by name
- specify groups or branches
The report will be visible to the Power Users (with report permissions) who are either individually named here, or who belong to one of the groups or branches specified.

Visibility on the contents of a report

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. 

Notes on changing a report's visibility rules

Please be aware of the following scenarios which may occur when a Power User creates a custom report, but its visibility rules are later changed by a Superadmin:

Initial scenario (applies to all the following cases): A Power User creates a new custom report and selects the All Superadmins option in the Visibility rules. 

Case 1: A Superadmin edits the report and changes the visibility to All Superadmins and Power Users.
→ When the Power User who created the report re-opens it, they will see that the option All Superadmins and Power Users is selected, and they are able to change it to one of the others (All Superadmins or All Superadmins and selected Power Users ). However if they do so, when they come back to edit the report, they will no longer be able to select All Superadmins and Power Users again.

Case 2: A Superadmin edits the report and changes the visibility to All Superadmins and the selected Power Users, and specifies Power Users/groups/branches over which the report creator has no visibility permissions.
→ When the Power User who created the report re-opens it, they will see that the option All Superadmins and the selected Power Users is selected, but (owing to lack of visibility permissions) they will not see any Power Users / groups / branches in the fields below, and so cannot save the report because those fields are empty.
→ To be able to save the report the Power User must set the All Superadmins option again.

Case 3: A Superadmin edits the report and changes the visibility to All Superadmins and the selected Power Users, and specifies some Power Users/ groups / branches (A and B) over which the report’s creator has no visibility, plus others (C and D) which the report’s creator can view.
→ When the Power User who created the report re-opens it, they will see that the option All Superadmins and the selected Power Users is selected, but in the fields below they will only see the Power Users / groups /branches (C and D) that they have visibility on. 
→ The Power User can save the report, but in so doing they will overwrite some of the changes made by the Superadmin (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.

• 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.

Notes on date filters

If you apply 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. 

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. 

For the Users-ILT sessions custom report, remember that the date option filters are referred to the course and not the session. For example, the Completion date filter will select only the users who have completed the course, not those who have completed a session in the course. 

Notes on user selection filters

If you set multiple User selection filters (Users and/or Branches and/or Groups), please note that the report will include results that match at least one of the selected filters (OR logic). 

Notes on filter option to show only learners

The reports on courses listed below contain a User filter option to Show only users with learner as user course level. This lets you either include or exclude instructors from the report.

• • Users – Courses
  • Users – Course enrollment time
  • Users – Webinar sessions
  • Users – ILT sessions
  • Groups/Branches – Courses
  • Users - Training material

Since instructors are counted as enrolled users in e-learning courses but are excluded from the user count for ILT courses, you can use the Show only users with learner as user course level option to either include or exclude instructors in the user count in the custom report. New custom reports count instructors as enrolled users by default (the option is not enabled) except for the Courses-Users reports, where the Show only users with learner as user course level option is enabled by default (and instructors are not counted as enrolled users).

Notes on course category filters

Reports involving courses include a filter field where you can specify a course category. Click Select category and navigate the category tree until you find the desired one. You can specify only one category. Please note that when you select a category, its subcategories are not included. The report will only include courses directly assigned the category that you set. 

Notes on e-commerce transactions filters

For the e-commerce transactions report, you can set filters to define the types of transactions to include in the report: 

• In Payment method you can set whether to include purchases made with real currency, with training credits, or both. 

In Selection of courses, learning plans, subscription plans and training credit packs you can set All to include all types of purchased items in the report, or set Custom selection to specify which individual items to include.

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.

Report fields

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. 

• 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 select the Archived enrollments option 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.

Mobile app statistics report fields : The Courses-Users and Users-Courses reports include the following fields to report usage for the mobile app.

Sorting options

In this area you can set the ordering of the items and columns in the report

Order by: Here you can define the vertical ordering of the items (rows) in the report. The specific options available vary depending on the type of report.
- You can select one of the available preset options, for example Username (A-Z). 
- Alternatively, you can select Custom field and from the drop-down list choose one of the previously enabled report fields. Then set whether to apply ascending (A-Z) or descending (Z-A) order*.

*If the selected custom field is an additional field whose value is a number, please note that the numbers won’t be sorted in numerical order, but will instead follow lexicographic order. This means that numbers will be ordered like any other text string, considering the leftmost character (digit) first, and then using the next digits for sub-orderings. For example, in ascending order 80 will be before 9, because when considering only the first digit, 8 is less than 9. 

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

Columns sorting: Here you can customize the left-to-right order of the columns that appear in your report. The columns correspond to the fields that you selected in the Report fields section. To do this: 

• Select the option Configure your custom columns sorting and click the Configure sorting button that appears. 
• In the panel that opens you can rearrange the report fields by dragging-and-dropping them. When ready, select Confirm to apply the order you chose.

The column ordering will be applied in both the report preview, and when you export it.

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. 

  Remember: Even with Reports/View and Reports/Edit permissions, Power Users can only schedule the reports which they themselves have created.
  - This means they cannot schedule reports created by Superadmins or by other Power Users.
  - However they can duplicate reports created by others, and then edit or schedule the duplicated 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.