Report builder Configuration

This feature is part of Moodle Workplace™, which is available through Moodle Certified Partners and Service Providers only.

---

Managing custom reports

You can access the management of custom reports via Site administration > Reports > Manage custom reports, or directly via the Report builder icon in the Workplace launcher. This functionality is available only if the Enable custom reports setting (enablecustomreports) in Site administration > General > Advanced features is enabled.

For each report, the following information is shown:

• Name of the rule
• Shared space labels (optional)
• Report source (see below)
• Tags that have been applied to the report
• Time created: Report's creation date
• Time modified: Last report's modification date
• Modified by: User who modified the report
• Actions:
  • Edit report content
  • Edit report details
  • View report
  • Duplicate report
  • Delete report (cannot be undone)

Creating custom reports

To create a new report, select the New report button.

A report contains two required settings: Name (displayed whenever the report is being made available to users) and Report source (defines where the data for the report will come from). When the Include default setup option is enabled, the report will be populated with several predefined columns, conditions, and filters. If the Remove any duplicate rows setting is enabled and identical rows exist, only a single row will be retained. This setting does not apply if report columns are aggregated. Additionally, optional Tags can be provided for improved report management and more powerful filtering.

If Custom report fields have been defined, they will be displayed in a separate section on the screen. Here, we have three custom fields: Type, Public, and Review.

The following report sources are available in Moodle Workplace, grouped by report plugin:

• Site
  • Badges: Badge details, badges issued, badges received, and courses
  • Blogs: Blog content, tags, users, and courses
  • Cohorts: Cohorts and cohort members
  • Comments: Comments and users
  • Competencies: Competency frameworks, competencies, and related user information
  • Course categories: Category details and courses, cohorts, roles, and users
  • Course participants: Course details, user enrolments, course completion, jobs, and tenants
  • Courses: Courses and course categories
  • Groups: Course, groups, groupings, and assigned users
  • Files: Files and users
  • Groups: Groups, groupings, and group memberships
  • Notes: Notes, recipients, authors, and courses
  • Roles: Roles, role assignments, contexts, and users
  • Tags: Tag collections, tags, tag instances, and tag authors
  • Task logs: Tasks and users
  • User badges: Badges issued to users in courses, including badge details
  • Users: Users and their job assignments
• Forum
  • Forum posts: Forums, discussions, and post alongside their courses and users
• Appointment
  • Appointments: Seminars, sessions and participants
• Certificate manager
  • Certificate templates: Available certificate templates
  • Issued certificates: Issued certificates to users
• Certifications
  • Certification users allocation and completion: Certification details, including users’ progress information
  • Certification users historical completion: Certification details and historical certifications completion
  • Certifications: Certification details
• Datastore
  • Course completion from datastore: Data in Workplace datastore
  • Historical site information: Information on active number of users and logins (requires \tool_datastore\task\siteinfo to run in Scheduled tasks)
• Program
  • Program users allocation and completion: Program details, including users’ progress information
  • Programs: Program details
• Workplace
  • Course reset for individual user: Course resetting data during recertification

Once you have created the report, you will be redirected to the actual report builder.

Report Editor

The interface of the report builder is divided into three panels:

• Columns sidebar (left): Shows the list of available data fields grouped by entities, including a live search option. To add a field to the report, simply select the respective field name.
• Preview window (middle): Shows the data according to the current report configuration. Column headings and aggregation methods can be edited inline. To grasp a view of what the report will look like to users, select the Preview button.
• Settings sidebar (right): Lets you configure conditions, filters, sorting, and card view options.

Viewers also have the option to download the table data in various formats, namely CSV, XLSX, HTML, JSON, ODS, and PDF. You can reduce or rearrange the options in that list in Site administration > Plugins > Data formats > Manage data formats.

Configuring fields

In the left-hand side panel of the report generator, you will see all available fields for the selected report source, which have been grouped into entities. Each entity can be expanded or collapsed for better usability. You can also search for field entries to limit the number of displayed items.

To add columns to the report, click on the selected field in the list on the left. The column will be added automatically as the rightmost column in the table. You can then rearrange the column order via the standard Move handle. To remove a column, click on the standard delete icon.

The following field types are available to be added as columns to a report:

• Text fields: For example, full name, job, or program name. Some text fields are preprocessed by the report generator to support additional functionality:
  • Hyperlinked text fields: Mainly to direct viewers directly to entries, for example, to a user profile or a program
  • Highlighted text fields: To visualise a status, for example, status fields in programs and certifications
  • Calculated text fields: To provide a numeric value, for example, the number of courses in a certification or the course progress for each user as a percentage
  • Grouped text fields: To provide multiple data points as a single cell, for example, all users registered for an appointment. The values are available one per line or comma-separated.
• Image fields: For example, program icon or user picture
• Actions: For example, sending a message to a user or viewing a progress report

Custom fields, such as custom user profile fields or custom program fields, are fully supported by the report generator. However, if the visibility of a custom field can be configured (for example, custom user profile fields), it has to be set to "Visible to everyone" for the field to appear in the list of available fields.

Aggregation and Grouping

The Workplace report generator supports various aggregation and grouping operations at the column level. Depending on the data field selected, a set of possible aggregation methods is offered. Here is a full list of methods, along with their SQL function used internally:

• Average: Average of all (numeric) values / AVG()
• Count: Number of values in column / COUNT()
• Count distinct: Number of unique values in column / COUNT DISTINCT()
• Comma separate values: List of data points, separated by comma / GROUP_CONCAT()
• Comma separate distinct values: List of unique data points, separated by comma / GROUP_CONCAT(DISTINCT)
• Date: Grouping by the timestamp rounded down to the start of the day (only for date and time fields). Example: an event happening on 26/01/26 at 10:00 and then at 11:00 would group to two events on the same day (26/01/26) / GROUP BY
• Maximum: Biggest (numeric) value in column / MAX()
• Minimum: Smallest (numeric) value in column / MIN()
• Percentage: Ratio of (boolean) values in percent / AVG()
• Sum: Sum of all (numeric) values in column / SUM()

An aggregate function calculates on a set of values and returns a single value. Because an aggregate function operates on a set of values, it regularly applies grouping to fields, which divides the result set into groups of value, where the aggregate function returns a single value for each group. In the examples below, you can see the impact on grouping on the Seminar field, once the Average function has been applied to the Capacity field.

Report settings

The accordion panel on the right lets you define conditions and filters, set the default sorting order, and configure card view options.

Conditions

Conditions let you limit the number of data that is being presented to the report viewer. They are a predefined set of criteria that are applied when viewing a report. Conditions cannot be changed in viewing mode. Depending on the selected report source, the available conditions might differ slightly from the list of available fields.

There is a special condition related to users called Relation to the report viewer, which specifies which users should be listed in a report relative to the person viewing it. Using this condition, it is possible to create a single report that shows different results to different users, depending on their department or managerial duties.

The first relation is called Themselves, which limits the report to information relating to the report viewer. The Customise... option provides the following two user relations:

• Reports to the report viewer: For users with a managerial position, this option will include users who report to the user viewing the report.
• Direct reports only: This narrows down the previous option to users who report directly to the user viewing the report. A direct report is a manager user in a position that is a direct child of the managers position.
• In the same department as the report viewer: Includes users of the same department (optionally including sub-departments) as the user viewing the report.

If both options are selected, it is possible to combine them with the AND and OR Boolean operators to refine the report content further. According to the user who is viewing the report, both relations take effect, meaning it will return different results according to the report viewer and/or their own position within the organisation.

Filters

Filters are a predefined set of criteria that are not applied automatically but are available for report viewers (via the Filters icon). Viewers of the report then have the ability to reduce the amount of data further via filters.

There is no limit to the number of filters in a report. Furthermore, the list of filters is not limited to the fields shown in the report - you might add a filter to narrow down the search by fields that are not shown in the report but available in the data.

Sorting

Sorting defines the initial order that fields are being ordered by.

Once a field has been selected, the sorting order can be reversed by toggling the Up/Down icon. When in viewing mode, the order of all selected fields will initially be applied. Once a user has clicked on a column name, the data will be sorted by this field. When the same column is clicked again, the sort order will be reversed.

Card View

The card view feature supports responsive layout design in the report builder. Card View allows the configuration of the report layout for narrow views when the block is in the sidebar or a smaller device is used. A report will automatically switch to card view when displayed on small screens or in a narrow container via the Report and chart block or Report block, for instance, on the dashboard.

The card view also drives the layout and content of reports in the Moodle Workplace app.

The following card view configuration options are available for every custom report:

• Columns visible: indicates the number of columns that will be displayed expanded in the card view.
• First column title: whether the first column title is shown or not.

In the screenshot below, the number of columns always visible has been set to 3 with the first column title hidden.

Report Audiences

Report audiences indicate which users have access to the report. They can also be used as recipients in scheduled reports. To access audiences, select the Audiences tab of a report.

In addition to selecting which position and department within an organisation should be included, it is also possible to manually select individual users and/or e-mail addresses. You can create the following audiences:

• General
  • All users: Use this audience to give access to all users in the tenant to any report
  • Assigned system role: Select at least one system role
  • Manually added users: Select at least one user (via name or e-mail address). Only email addresses of registered users being are supported as schedule recipients.
  • Member of cohort: Select at least one cohort
  • Site administrators: Grant access to all site admins
• Organisation structure
  • Job assignments: Select a Department and a Position, and optionally include subdepartments and subpositions, respectively
  • Managers: Make reports available to managers. The Manager type options available are Manager, Manager (assigned manually), and Department Lead.
• Multi-tenancy
  • Tenant administrators: Grant access to the admins in the tenant

To confirm which users now have access to the report, switch to the Access tab.

Scheduling Reports

All reports are available as pull reports; that is, users have to select and view a report proactively. The report scheduler lets you configure the automatic delivery of reports to specific audiences, also known as push reports.

To access the scheduler, select the Schedules tab of a report and select the + New Schedule button at the top right.

Each schedule contains four parts:

• General
  • Schedule name is only used in the list of schedules
  • Format: Any file format that has been allowed in Site administration > Plugins > Data formats > Manage data formats
  • Starting from: Specifies when the report is to be sent for the first time
  • Recurrence: Lets you specify whether the report should be sent once (None) or sent frequently: Daily, Daily (weekdays only), Weekly, Monthly, Annually
  • View report data as: You can specify as which user the created report will be viewed as.
    • Schedule creator (default): The generated report will contain data as if viewed by the user who created the schedule
    • Schedule recipient: The generated report will contain data as if viewed by the recipient; that is, each user will potentially receive a different (personalised) report
    • Select user: If a user is selected, the report data will be included as if viewed by the selected user; that is, all recipients will receive the same report
• Audience: To select which users will receive the scheduled report, you need to select at least one report audience. Scheduling a report will not be possible without any audiences, which have to be created first.

• Message content: Standard elements of any email message, namely Subject and Message.
• Advanced:
  • If the report is empty: Choose an option what should happen when the report to be sent contains no data. The self-explanatory options are Send message with empty report (default), Send message without report, and Don't send message.

The cron process triggers the execution of the report. If you want to send a report straight away, select the Send schedule option from the actions in the list of schedules.

Report Access

By default, all users with permission moodle/reportbuilder:view or moodle/reportbuilder:edit can view all custom reports defined in their tenant. Additional audiences can be specified to grant access to a report.

To see who can view the report, select the Access tab of a report. Users who can see all reports in the tenant are labelled "Can view all reports"

In addition to granting user access to reports, it is also possible to specify which users should be listed in any given report. To achieve this, the "Relation to the report viewer" condition should be added to the report. This allows a manager to create a single report for others to view information about themselves or users in their departments or reporting lines. The condition takes effect according to the user who is viewing the report, meaning it will return different results according to the report viewer and/or their own position within the organisation.

Data visualisation

The Report and Chart block allows you to embed reports with charts, supporting pie, bar, and line chart types. You can add charts to the dashboard, inside courses, or in any location that permits adding Moodle Workplace blocks.

Note: There exists also a Report block for Moodle Workplace and Moodle LMS. It contains all the features of the Report and chart block, except the visualisation elements.

For guidance on adding and managing blocks, refer to the Block settings page. Once you add a block, the standard sections Where this block appears and On this page will be available for configuration.

Ensure that the capability block/reportchart:addinstance is allowed for any user who should be able to add the block.

The Report and chart block contains the following elements:

(1) Report title
(2)	Chart, Report, All toggle	(6)	Edit chart configuration
(3)	Report header	(7)	Edit table layout
(4)	Full-screen mode toggle	(8)	Refresh report data
(5)	Report filter options	(9)	Report footer

Toggle preferences (such as "Show chart and report") carried out the by users are saved between sessions.

If the block has been configured in a way that it shows no data, the following warning will be shown. You have to adjust settings in the report source or revisit applied filters.

The Report and chart block contains the following sections:

Block settings

The Block title appears in the heading of each block (1). You must select a report from the drop-down list.

Visualisation

The following settings determine how the data of the selected report will be presented:

• Chart type: Choose between Line chart, Bar chart or Pie chart
• Rows per page: Specify the number of rows displayed. If multiple pages are available and the data is shown as a table, a page navigator will allow users to browse through the data. For graphs, this determines the number of data points, bars, and pie segments, respectively.
• Block view: If the Show chart and report option is selected, a toggle will appear in the block, allowing users to switch between Chart, Report, and All (3). If the Show chart only option is selected, the toggle and the Filters button (5) will be hidden.
• Enable expanded view: If selected, the same options available the block view will appear. The expanded view allows users to display the report in full-screen mode via the Expand button(4).
• Header: Contains the text displayed above the report (3).
• Footer: Contains the text displayed below the report (9).

Advanced

The Report and chart block supports automatic on-screen data refreshing to keep reports up to date. Once Auto refresh is enabled, you can specify the time interval.

If the Display refresh button option is selected, the time of the last report update and a button to manually refresh the report will be displayed at the bottom of the block (8).

Chart and table layout

The layout of both the chart and the table can be further customised. Ensure that editing mode is turned on.

Edit chart layout

Once you select the Edit chart button (6), you can select which columns to use in a chart. The Chart columns section has the following options:

• X-axis: Select the column to be used for the horizontal axis (or equivalent in a pie chart)
• Y-axis: Select the column to be used for the vertical axis (or equivalent in a pie chart)

Only numeric columns can be selected as chart series, which prevents visual errors and ensures the accuracy of your reporting data.

However, aggregation influences the column type: when a text column uses a numeric aggregation method, it is treated as an integer and can then be plotted on a chart’s Y-axis. For instance, applying the Count or Count Distinct aggregation to a text field produces a numeric result, allowing it to be used in charts just like any other numeric field.

By default, Moodle Workplace selects the first numeric column from the report source as the chart series (the Y-axis). Non-numeric columns will be ignored during this default selection process. This prevents visual errors and ensures that a meaningful numeric value is chosen by default, which aligns with best practices for chart visualisation. You still have full control to manually select any available column for the X and Y axes, as long as a valid numeric column is selected for the chart series.

Additionally, you can change the Aspect ratio of the graph. In addition to popular rations like 16:9 or 4:3, you can specify a Custom ratio. This is particularly useful for creating narrow graphs, such as a 5:1 ratio. The aspect ratio only affects the height of the graph; the width will always fill the container.

The Additional JSON option allows the addidion of custom JSON objects to adjust the chart's appearance. If the entered code is invalid, an error will be displayed when you attempt to save changes. You can refer to the ChartJS documentation for guidance. In particular, these sub-pages might be useful: www.chartjs.org/docs/latest/configuration/elements.html, www.chartjs.org/docs/latest/general/options.html, and www.chartjs.org/docs/latest/axes/styling.html.

For example, if you wish to add a chart title, use the following JSON:

{"title": "My Custom Report Title"}

Edit table layout

The table columns are specified in the Report editor. You can change the table view using the Edit table button (7), where the following styles are available:

• Adaptive: If sufficient space is available, the data is displayed as a table. If the screen or block is too narrow to show all columents, it will switch to the cards view.
• Cards: The data is shown in card view, as defined in the report's card view configuration. The settings Columns visisble and First column title are taken into account.
• Table: The data is shown in table view

Users can limit the displayed data using the Filters button (6). The options available are derived from the filter settings in the report. Filter values are stored on a per-user basis.

Exporting charts

If you wish to export a chart, you can use the native Save image function from your browser vie a left-click on the image.

The menu might look different depending on the browser used, installed browser extensions, and system settings.