Reporting Engine Reference

Purpose: This article provides a reference guide to the Administrate Reporting Engine, including terminology, entities, relations, permissions, and a worked example.

If you are learning how to build reports, start with Reporting in Administrate and Create a report.

This reference article explains how reporting components work together and how to interpret reporting behavior when building more advanced reports.

When to use this article

Use this article when you need deeper understanding of the reporting engine or when troubleshooting reporting behavior.

• to understand reporting terminology
• to understand entities, fields, and relations
• to learn how output columns and ordering work
• to understand reporting permissions
• to see a worked example of report creation
• to troubleshoot reporting behavior

Terminology

Please familiarize yourself with the following terminology used in the Reporting Engine:

• Condition
• Entity
• Field
• Group
• Ordering
• Output Column
• Relation
• Section Grouping

Condition

Conditions filter your report results. They determine which records are included and how fields are queried.

Different operators are available for different condition types:

• Text fields use text operators
• Numerical fields use number operators
• Date fields use date operators

For ranges, set two conditions: one for the start of the range and one for the end.

Note: the is in week operator can produce ranges you may not expect because week definitions vary by configuration. If results are unexpected, use explicit date ranges instead.

Entity

When you create a new report, the first step is to choose your entity. This determines which fields you can query and which relations you can access.

This is the most important reporting decision, because it determines what you can report on and how the results will be displayed.

• What do you want to report on?
• What do you want the results displayed in relation to?

Field

A field is the specific information in your Administrate database you want to query or display. Available fields depend on the selected entity and the relations you follow.

Group

You can group a set of conditions together so they count as one condition. This allows more powerful filtering logic.

Creating groups from the top level is generally easiest unless you intentionally want nested groups.

Ordering

Ordering sorts your results using your output columns. You can sort ascending or descending and set priority.

For example, you might sort primarily by student name and secondarily by event date.

Output Column

Output columns are the fields you want to display in your report. If you export your report, these output columns form the top row of your results.

For numerical output columns, you can also return statistical values such as:

• Sum (Total)
• Average
• Maximum
• Minimum
• Count Results

You can also create basic formulas using the Advanced checkbox.

Relation

Relations are the connections that different entities have with each other. Using relations, you can find related fields to the entity your report is based on.

For example, if your entity is Delegate, you can display an event location name using:

Event → Location → Name

Section Grouping

When you have a large list of results, it can be easier to read if you group by an output column.

Permissions

You can set user role permissions for the Reports system to control who can view or edit reports. Permissions determine access to reports users create and reports created by others.

Reports belong to companies. When you create a report, the system assigns it to your company automatically, and the report displays only your company’s data.

You see reports from your company only. Set a report to “All Companies” to make it global. Global reports allow users from any company to access the report and see data across all companies.

To view a report, you need permissions for every entity included in that report. If a report includes Events and Contacts, you need permissions for both. Missing permissions for even one entity blocks access to the report.

When you build a report, you only see entities you have permission to view.

Worked Example: Marketer

Scenario

You want to target a new course, Advanced First Aid, to learners who previously attended both First Aid at Work and First Aid Basics. You will export the results to CSV so you can import them into another tool for a campaign.

Entity and Filter Conditions

Because you want to base the report on learners who attended specific events, choose the base entity as Delegate.

You may also want to exclude cancelled learners and include only learners who have an email address.

1. Click Create New Report and select Delegates.
2. Ensure the top-left text says the report is matching ALL the following conditions.
3. Add the first event condition using Event → Course → Title.
4. Set the operator to is, then enter First Aid at Work.
5. Add the second event condition using Event → Course → Title.
6. Set the operator to is, then enter First Aid Basics.
7. Add a condition for Cancelled Date.
8. Set the operator to does not exist.
9. Add a condition for Contact → Email.
10. Set the operator to exists.

Output Columns

You will not be able to view the report until you add output columns.

1. Click the Output Columns tab.
2. Add Contact → Name.
3. Relabel it if desired.
4. Add Contact → Email.
5. Relabel it if desired.

Ordering

1. Click the Ordering tab.
2. Click Contact → Name to sort by learner name.
3. Leave sort direction as Ascending.

Save

1. When you are satisfied with the report, click Save Changes, then Save As.
2. Name your report.
3. Select the folder in your DMS.
4. Click Save.

Export

1. View the report.
2. Select CSV as the file format.
3. Select Full to export rows.
4. Download the file.

Your CSV file downloads and is ready to import into another tool.

Frequently Asked Questions

Why do some users see dates display as dd/MM/yyyy while others see M/d/yy?

Users in Administrate are associated with companies, and the Reporting Engine uses the date format of the locale selected for the user’s company.

If your instance has multiple companies with different locales, users in those companies may see the same report date values displayed differently.

Why am I encountering “414 Request-URI Too Large” when I export?

You may encounter this error if you try to export or download a report that contains unsaved edits.

To avoid this error, click Save Changes first, then try exporting again.

Related guides

• Reporting in Administrate
• Create a report
• Edit report filters (Filter Conditions)
• Add or change output columns
• Using sections to group reporting results
• Sort reporting results (Ordering)
• Export report results
• Reporting Engine entities