Report settings
  • 13 Sep 2023
  • 16 minutes to read

Report settings


Article Summary

When creating or editing a report you can configure the following settings on a number of tabs. 

General tab

Here you can update any of the following general report settings:

SettingDescriptionNotes

Report title

This is the name that will appear at the top of your report page and in the Report Manager block.

-

Abstract

A short summary of the report that will be displayed in the user reports list.

Including an Abstract helps users to understand at a glance what the report is for, helping them to find the report they need and preventing duplicate reports from being created.

Description

When a report description is created the information is displayed to users in a box above the search filters on the report page.

The Description field should be used to describe what is shown in the report and when/how it should be used.

Source

The source for this report will be displayed.

Once saved, a report source cannot be changed. To use a different report source a new report must be created.

Hide on user reports list

When checked, this report will not be displayed on the My Reports page for users, but will be accessible via its URL.

-

Disable enforced visibility checks
By default, some reports apply standard visibility checks, which can prevent the use of individual content restrictions. When this setting is enabled the standard checks are disabled, and visibility is solely controlled by content restrictions.
This setting is available for reports using the following report sources:
  • Course completion
  • Course completion including history
  • Course membership
  • Seminar events
  • Seminar sign-ups
  • Seminar sign-in sheet
  • Seminar sessions

Number of records per page

Enter the number of rows that will appear on each page of the report. At the bottom of each page, the user can click to view the next page of data. This also determines the number of rows that will be shown in the report table block.

-

Report type

This is an informational field that displays whether this is a user report or an embedded report.

-

Columns tab

The Columns tab allows you to select the columns that will be available on the report.

A set of default columns will be displayed based on the report source that was selected. Additional columns can be added by clicking the Add another column dropdown.

SettingDescriptionNotes

Column

Data available for reports depends on the source, but may include:

  • User profile information
  • Competency details and completion status
  • Course details and completion status
  • Seminar event details and attendance
  • Assignment submissions
  • Audiences
  • Program details and completion status

See Report sources for more information on available data sources and column options.

Any custom fields added will automatically be available in the relevant report column.

There will be a warning if you use a combination of columns and/or aggregation methods that are incompatible with one another. To fix the problem simply change one of the columns or aggregation methods flagged in the warning. 

Aggregation or grouping

For each record that has the same value a calculation that is related to the column field type can be chosen, this includes:

  • Counts for each record, count of unique values in the field
  • Average, total, max, minimum for numeric columns
  • Time period from hours, days, weeks, months for time columns

Some reports already use data aggregation internally, in which case a warning is displayed under the report Columns tab.

See more on aggregation and groupings, including examples.

Customise heading

Next to each column, tick the check box under the Customise heading and enter a new column title if you want to override the existing title.

-

Options

This column allows you to perform a number of actions:

  • Show/Hide: Use the eye icon to show or hide a column from the report
    • Open eye means the column is visible ()
    • Crossed out eye means it is hidden ()
  • Delete: Use the cross icon () to delete a column from the report
  • Arrange: Use the up () and down () arrow icons to arrange the order of the report columns from left to right

-

Sorting

The Sorting section allows you to set up default behaviour for column sorting.

  • Default column: Choose the default column to sort
  • Default order: Set the order to to sort by

For example, if you selected User's fullname as the Default column and Ascending (A to Z, 1 to 9) as the Default order, then by default the report would be sorted using the ascending alphabetical order of the user fullname column. 

Note that the user running the report will be able to sort by other columns as well by clicking on the column heading.

Graph tab

This tab allows the results from the aggregation of columns in the report to be graphed using a variety of graph types. 

You can change your graph library from the default (ChartJS) by navigating to Quick-access menu > Reports > General settings, then select an option for the Graph Library setting.

SettingDescriptionNotes
Graph type
  • Column
  • Line
  • Horizontal Bar
  • Pie
  • Scatter
  • Area
  • Donut
  • Progress Donut (only works in ChartJS)
-
OrientationDetermines how the report data is interpreted to build the graph. 
  • Data series in columns: Report builder will treat report columns as data series. In most cases this is what you want. 
  • Data series in rows: Report builder treats every item in the column as a separate data series - data rows will be treated as data points. Typically you only want to select this option if you have more columns in your report than rows.
-
CategoryThis is the basis for the graph, for example if you want a graph to show how long a user has been active on the site then you select Time as the category. -
LegendThis is the information that will be used for the graph's legend - this will normally be the same as the CategoryThis setting cannot be edited. 
Data sourceSelect one or more columns to use as data sources for the graph. Only columns with compatible numeric data are included.-
StackedRather than appearing side by side, data will be stacked on top of each other.
See an example in the Chart.js documentation.
Maximum number of used recordsChoose the maximum number of records to be used in the report graph. By default this is 500.Advanced option.
Custom settingsYou can further tailor the graph to your preferences. Find out more about customising your graphs using the advanced options in the developer documentation.Advanced option.

Filters tab

The Filters tab allows you to select the filters which will appear at the top and side of the report.

There are three types of filters available:

  • Standard filters: Standard filters appear at the top of the page above the columns of data in the report. The user can enter/select criteria and click the Search button. Additional filters can be added to the page and hidden behind an Advanced button to allow users access to less commonly used filters.
  • Sidebar filters: Sidebar filter options allows you to customise the filters that appear to the side of your report. Sidebar filters have instant filtering enabled - each change made to a filter will automatically refresh the report data (if certain system requirements are met). The available filters are determined by the Source of the report. Only some types of filters can be placed in the sidebar, so not all standard filters can be placed there. Each report source has a set of default filters.
  • Toolbar search: Toolbar search box allows you to customise the fields that will be searched when using the search box in the report header. The available filters are determined by the Source of the report. Each report source has a set of default fields. If no fields are specified then the search box is not displayed.

Standard filter options

Standard filter options allow you to customise how the filters appear above your report. The available filters are determined by the source of the report. Each report source has a set of default filters.

A filter can appear in either the standard filter area or the sidebar filter area, but not both. Filters can be added, sorted, and removed.

FilterDescriptionNotes

Search Field

Use the Search Field options to select the fields that users will be allowed to search by. Additional filters can be added by clicking the Add another filter dropdown.

-

Customise Field Name

Next to each filter, tick the check box under Customise Field Name and enter a new label that will be displayed next to the filter when the report is run.

-

Advanced?

Check the Advanced? box next to any search options that should be available if the user clicks the Show advanced button on the report. This option is helpful to make infrequently used search options available, but hidden by default.

-

Filtering required

Tick the Filtering required box to make a search field mandatory. This means that users will need to select an option for this search field before they can run and view the report.

The Filtering required option can be used to ensure that report viewers do not run reports that will return huge numbers of results. By requiring viewers to narrow down the number of results (by selecting options for the required fields), you can ensure that this does not happen.

Options

To delete a filter from the report, click the delete icon under the Options column. To rearrange the order of the filters on the page, click the up and down arrows. The filters will appear in the Search by box in the order they are listed.

-

Sidebar filter options

Sidebar filter options allow you to customise the filters on the side of your report. Sidebar filters have instant filtering enabled, meaning each change made to a filter will automatically refresh the report data.

A filter can appear in either the standard filter area or the sidebar filter area, but not both. Filters can be added, sorted and removed.

FilterDescription

Search Field

Use the Search Field options to select the fields that users will be allowed to search by. Additional filters can be added by clicking the Add another filter dropdown.

Customise Field Name

Next to each filter, tick the checkbox under Customise Field Name and enter a new label that will be displayed next to the filter when the report is run.

Advanced?

Check the Advanced? box next to any search options that should be available if the user clicks the Show advanced button on the report. This option is helpful to make infrequently used search options available, but hidden by default.

Toolbar search box

The toolbar search box allows users to search multiple fields by text instead of filtering individual fields.

Disable toolbar search box

Checking this box will prevent the search box from appearing at the top of the page.

Search Field

Use the Search Field options to select the fields that users will be allowed to search by. Additional filters can be added by clicking the Add another search column dropdown.

Options

To delete a filter from the report, click the Delete icon under the Options column. To rearrange the order of the filters on the page, click the up and down arrows. The filters will appear in the Filter by box in the order they are listed.

Content tab

Content controls allow you to restrict report content based on the user who is running the report. This allows Site Administrators to pre-filter the report so that one report can be run by many users on the system by only showing the data most pertinent to the user. For example, a report can be designed for managers to run that will only display data for their direct reports.

SettingDescriptionNotes

Report content

Allows you to select the overall content control settings for this report:

  • Show all records: Every available record for this source will be shown and no restrictions will be placed on the content available
  • Show records matching any of the checked criteria below: Display records that match any of the criteria set below
  • Show records matching all of the checked criteria below: Display records that match all of the criteria set below

It is then possible to configure the criteria for the Report content settings above. The criteria available will differ based on the report sources, and can include restrictions based on users, positions or dates.

-

Enforce user visibility restrictionsWhen enabled, user visibility restrictions (e.g. status or tenant membership) will limit the records shown based on the user viewing the report.-

Show by user

When selected, the report shows different records depending on the user viewing the report and their relationship to other users.

-

Include records from a particular user

Decide whether a user can see only their own records or those of reports (select from direct, indirect and temporary). 

-

Show by the user's current position 

When selected, the report displays results dependent on the user's assigned position.

-

Include records from child positions

Select which level to show reports from. This could be at or below the user's position. 

-

Show by the user's current organisation

When selected, the report displays results dependent on the organisation the user has been assigned to.

-

Include records from child organisations

Select which level to show reports from. This could be at or below the user's organisation. 

-

Show by the organisation when completed

When selected, the report displays results dependent on the organisation the user was assigned to when they completed the course or competency.

-

Show records by audience

Restrict report results by audience so you only see data for that subset of users.

-

Include records fromSelect the audience for which you want to see results.-
Enforce sitewide visibility restrictionsWhen enabled, sitewide visibility restrictions (e.g. audience-based visibility, course-based visibility and workspace visibility) will limit the records shown based on the user viewing the report.
This restriction is always applied for reports using the following report sources (unless the Disable enforced visibility checks setting on the General tab is enabled):
  • Course completion
  • Course completion including history
  • Course membership
  • Seminar events
  • Seminar sign-ups
  • Seminar sign-in sheet
  • Seminar sessions

Show by time created

Show records based on the record date. When selected, the report only displays records within the time frame selected.

-

Include records from

Show records from the past, future, last 30 days, next 30 days, current financial year, or previous financial year. Check the Include record if date missing option to include records with no date in your report.

-

Show by event roles

When enabled, seminar report source content can be restricted to users who hold a particular event role. An event role must be enabled on the seminar global settings in order to select it as a content restriction.

-

Show by the completion dateShow records based on the completion date. When selected, the report only displays records within the time frame selected.
-
Include records fromShow records from the past, future, last 30 days, next 30 days, current financial year, or previous financial year. Check the Include record if date missing option to include records with no date in your report.
-

Access tab

The Access tab is only available for user reports. It allows Site Administrators to grant users access to view the content of the report based on their role. There are two sections, the first allows you to decide whether everyone or only those matching criteria can access the report. The second allows you to set those criteria based on the user's role. 

SettingDescriptionNotes

Restrict access

Allows you to select whether All users can view this report or if Only certain users can view this report based on the controls selected. 

-

Restrict access by role

Set the role criteria for access to the report, using the context as well as the specific role a user has.

  • Context: The location or level within the system that the user has access to. For example a Site Administrator would have system-level access (context), while another user may only have course-level access (context). Context allows you to set the context in which a user has been assigned a role to view the report.
  • Roles with permission to view this report: Restrict the visibility of a report to specific system roles. Only when the user possesses the correct system roles at the time the report is to be viewed will the Reports tab appear in the Totara menu.

Note that the Staff Manager role is typically assigned at the user context rather than the system level. If you need Staff Managers to view the report then you should use the Users may have the role in any context setting.

Performance tab

The Performance tab provides access to performance-based settings for each report.

SettingDescriptionNotes

Restrict initial display

Controls how the report is initially displayed, and is recommended for larger reports where you will be filtering the results. When this setting is enabled, it increases the speed of the report by requiring the user to apply search filters and click the Search button before displaying report data.

This setting will be enabled (ticked) or disabled (unchecked) by default depending on the global setting Restrict initial display in all report builder reports.

Override export formats
Enable this setting to override the available export formats that have been set at the site level (in the Report general settings). You can then select which formats are available using the Export format checkboxes.
You may want to offer a more limited selection of export formats for large reports in order to minimise performance impacts. It is recommended that PDF and Excel formats are disabled for very large reports (e.g. reports with 10,000+ records).

Enable Report Caching

When checked, a copy of this report will be generated on a set schedule and users will see the results of the stored or cached version report. This will make displaying and filtering of the report faster because it does not have to generate results every time it is accessed. Note that the data displayed will be from the last time the report was generated rather than 'live' data. We recommend enabling this setting only if necessary (reports are taking too long to be displayed), and only for specific reports where this is a problem.

To set caching performance options, report caching must be enabled first on the Configure features page. 

Cache Schedule

Determines the schedule used to control how often a new version of the report is generated. The report will be generated by the background server job (a.k.a. cron job) that immediately follows the specified time. For example, if you have set up your cron to run every 20 minutes at 10, 30 and 50 minutes past the hour and you schedule a report to run at midnight, it will actually run at 10 minutes past midnight.

Cached reports are prepared one after another, i.e. when the first is finished the second is started. This is done in one stream to avoid database overload. If there is more than one report requiring caching, a delay is possible depending on the size of the reports. The order is not specified and it is not guaranteed that report caches will be refreshed in the same sequence each time.

Current Server Time

All reports are cached based on server time. Cache status shows you current local time which might be different from the server time. Make sure to take into account your server time when scheduling cache.

-

Generate Now

If checked, then report cache will be generated immediately after changes are saved.

Note that both the Restrict initial display and Enable report caching features are set up on a report-by-report basis and that a report need not have both or either of these options enabled.

Use database clone

It is now possible to configure a second database connection for use by report builder. The purpose of this secondary connection is so that you can direct the main report builder queries at a read-only database clone, in order to improve performance.

These settings should be considered highly advanced. It has to be configured by sysadmin in config.php and has to be manually enabled in individual reports by a Site Administrator via the Report Builder (this setting).

It is suggested that sysadmins create a separate database instance with an exact clone of the production database that is kept in sync automatically.

Support cannot be provided on configuring a read-only slave and so you will need in-house expertise to achieve this.

The only technical requirement for the databases is that the main database must be ACID compliant.

Those wishing to use the second database connection can find instructions for it within config-dist.php. You can use a read-only database clone. These settings allow admin to configure a second database:

// connection that will be used for selected Report Builder reports to improve performance

// and lower the main database load.
 //
 // $CFG->clone_dbname = 'xxx';
 // $CFG->clone_dbhost = $CFG->dbhost; // optional
 // $CFG->clone_dbuser = $CFG->dbuser; // optional
 // $CFG->clone_dbpass = $CFG->dbpass; // optional
 // $CFG->clone_dboptions = $CFG->dboptions; //optional

 

C003 - Reports(1)Get involved in the conversation about Reporting on the Totara Community. 

The Totara Academy has a whole course dedicated to using Reports in Totara. Here you can learn more on how to use reports, see best practice, and give it a go yourself.

© Copyright 2024 Totara Learning Solutions. All rights reserved.


Was this article helpful?

Changing your password will log you out immediately. Use the new password to log back in.
First name must have atleast 2 characters. Numbers and special characters are not allowed.
Last name must have atleast 1 characters. Numbers and special characters are not allowed.
Enter a valid email
Enter a valid password
Your profile has been successfully updated.