Form.io Reporting Module

The Form.io Reporting Module lets you design and generate reports from form submission data. You can pull data from one or multiple forms within a project, perform calculations, and present the result

Overview

How It Works

The Reporting Module uses MongoDB's Aggregation Pipeline, a framework for transforming and combining data from multiple sources. This allows you to:

• Join data from multiple forms

• Perform calculations on field values

• Group and summarize data

• Filter and sort results

You don't need MongoDB expertise to use basic reporting features. However, understanding aggregation concepts helps when creating advanced reports.

Learn More: See MongoDB Aggregation Pipeline for detailed information.

Prerequisites

A Form.io Library License with Reporting Module enabled is required to use the @formio/reporting module . Contact [email protected] to acquire or upgrade your license.

Technical Requirements

• formio-enterprise v8.4.1 or greater

Access Requirements

Your users need these permissions to view reports:

Access Context	Permission Required
Project Level	Read All: Authenticated
Reporting UI Resource	Read All Submission: Authenticated
Source Forms	Read All Submission: Authenticated

Getting Started

This section walks you through creating and embedding your first report.

Step 1: Enable Reports in Your Project

Once the Reporting Module is enabled on your license, a Reports section appears in your project's navigation sidebar.

Note for Existing Projects: Projects created before Reporting Module activation may lack the Reporting UI resource. See Troubleshooting to resolve this.

Step 2: Create Your First Report

1. Navigate to your project in the Form.io portal

2. Click Reports in the left sidebar

3. Click New Report

4. Enter a Report Title

5. Click the Source Forms tab

6. Select one or more forms from the dropdown

7. Click the Columns tab

8. Select the columns you want to display

9. Click Submit Form to save

Your report now appears in the Reports list. Click Preview to see the report structure.

Note: The portal preview doesn't fetch live data. To see actual submission data, embed the report in an application.

Step 3: Embed the Report

Install the reporting module in your application:

npm install --save @formio/reporting

Or with yarn:

yarn add @formio/reporting

Add the report to your application:

import { Formio } from '@formio/js';
import { Reporting } from '@formio/reporting';
import '@formio/reporting/reporting.css';

// Register the Reporting module
Formio.use(Reporting);

// Set your license key
Formio.setLicense('YOUR_LICENSE_KEY');

// Create the report
const reportElement = document.getElementById('report-container');
const reportUrl = 'https://your-project.form.io/report/employee-overview';

Formio.Report.create(reportElement, reportUrl)
  .then((report) => {
    console.log('Report loaded successfully');
  })
  .catch((error) => {
    console.error('Failed to load report:', error);
  });

Expected Result: The report grid displays in your #report-container element with your form's submission data.

Report Structure

An embedded report consists of two main components:

Reporting Grid

The main data display area. It provides:

• Pagination - Navigate through large data sets

• Sorting - Click column headers to sort ascending/descending

• Row Selection - Select rows for bulk actions

• Column Filtering - Filter data within specific columns (when Controls are disabled)

• Column Visibility - Show/hide columns from the grid header menu

Reporting Controls (Optional)

A collapsible panel above the grid for data management:

• Filters - Apply custom filters to the data

• Column Visibility - Toggle which columns display

• Actions - Execute operations on selected rows (export, custom actions)

You can enable or disable the Controls panel in the report settings.

---

Guides

Prerequisites

To follow along with the guides, import the example Forms into a project using the following embed URLs.

1. Import the Department Resource using the embed URL below into your project https://documentation.form.io/department

2. Import the Salary Resource using the embed URL below into your project https://documentation.form.io/salary

   • Edit the Department select component and navigate to the Data tab.

   • Click the Resource dropdown and select the Department Resource.

   • Click the Value Property field and select Department

3. Import the Employee form into your project https://documentation.form.io/employee

   • Edit the Department select component and navigate to the Data tab.

   • Click the Resource dropdown and select the Department Resource.

   • Click the Value Property field and select Department

4. Import the Employee Evaluation form into your Project https://documentation.form.io/employeeevaluation

   • Edit the Department select component and navigate to the Data tab.

   • Click the Resource dropdown and select the Department Resource.

   • Click the Value Property field and select Department

Create a Single-Form Report

Use this approach when reporting on data from one form.

Scenario: Create an Employee Overview report showing employee names, departments, and start dates.

1. Go to Reports > New Report

2. Set Report Title to "Employee Overview"

3. Click Source Forms tab

4. Select Employee from the dropdown

5. Click Columns tab

6. Select columns: Employee ID, First Name, Last Name, Department, Start Date

7. Click Submit Form

Result: A report displaying all Employee submissions with the selected columns.

---

Create Calculated Columns

Use calculated columns to derive new values from existing fields.

Scenario: Combine First Name and Last Name into a single "Full Name" column.

1. Open your report for editing

2. Click the Calculated Columns tab

3. Click + Add Column

4. Set Column Title to "Full Name"

5. Set Column Key to "fullName"

6. Select Concatenate Strings from the Operator dropdown

7. In Arguments, click + Add Another and select:

   • First argument: First Name

   • Second argument: (space character or add another field)

   • Third argument: Last Name

8. Click Save

9. Go to Columns tab and add "Full Name" to your selected columns

10. Click Submit Form

Available Operators:

Operator	Description	Example Use
Array Size	Count items in an array	Count languages spoken
Concatenate Strings	Join text values	Combine first + last name
Date Difference	Calculate time between dates	Employee tenure
Day of Month/Week/Year	Extract date parts	Group by day
Month Number	Extract month (1-12)	Monthly reports
Week Number	Extract week (0-53)	Weekly reports
Year	Extract year	Annual reports
Divide	Divide two numbers	Calculate ratios
Multiply	Multiply numbers	Calculate totals
Summarize (Sum)	Add numbers together	Sum values

Reference: See MongoDB documentation for each operator: Aggregation Operators

---

Join Multiple Forms

Use this approach when you need data from multiple related forms.

Scenario: Create a report joining Employee data with Salary data, where both forms share a Department field.

Prerequisites:

• Two or more forms with at least one common field

• The common field must contain matching values (e.g., same Department IDs)

Steps:

1. Go to Reports > New Report

2. Set Report Title to "Employee Salary Report"

3. Click Source Forms tab

4. Select Employee from the dropdown

5. Select Salary from the dropdown (you now have 2 forms selected)

6. In Forms Connections, click + Add Connection

7. Configure the connection:

   • Base Form: Employee

   • Connecting Field of Base Form: Department

   • Joining Form: Salary

   • Connecting Field of Joining Form: Department

8. Click Save on the connection

9. Go to Columns tab—you now see fields from both forms

10. Select your desired columns

11. Click Submit Form

Path to Connecting Value:

If your field stores an object (e.g., the entire Department submission), specify the path to the ID:

• Base Form Path: _id or data.departmentId

• Joining Form Path: _id or data.departmentId

---

Create Aggregated Reports

Use aggregation to group data and calculate summaries.

Scenario: Show total employees and average salary per department.

1. Create a multi-form report with Employee and Salary forms (see above)

2. Click the Aggregation tab

3. In Fields to group by, select Department Name

4. In Group Calculated Columns, click + Add Column

5. Add first aggregation:

   • Column Title: Total Employees

   • Column Key: totalEmployees

   • Operator: Count

6. Click + Add Column again

7. Add second aggregation:

   • Column Title: Average Salary

   • Column Key: avgSalary

   • Operator: Average

   • Argument: Salary Amount

   • Decimal Places: 2

8. Go to Columns tab and select: Department Name, Total Employees, Average Salary

9. Click Submit Form

Available Aggregation Operators:

Operator	Description
Average	Mean value of numeric field
Count	Number of records in group
Max	Highest value in group
Min	Lowest value in group
Sum	Total of numeric values

---

Configure Filters

Allow report viewers to filter data interactively.

Prerequisites: Reporting Controls must be enabled.

1. Click the Reporting Controls tab

2. Check Enable Control Panel

3. Click the Filters tab

4. Set Number of Filters Per Row (e.g., 3)

5. Set Filter Label Position (Top, Left, or Right)

6. In Control Panel Filters, click + Add Filter

7. Configure the filter:

   • Field: Select the field to filter (e.g., Department)

   • Filter Type: Select operator (Contains, Equals, Greater Than, etc.)

   • Filter Title: Label shown to users (optional)

8. Add additional filters as needed

9. Click Submit Form

Filter Types by Field Type:

Field Type	Available Filters
Text	Contains, Equals, Starts With, Ends With, Is Empty
Number	Equals, Greater Than, Less Than, Between, Is Empty
Date	Equals, Before, After, Between, Is Empty
Select	Equals, Is Empty

---

Add Export Actions

Let users export selected rows to CSV or PDF.

1. Ensure Reporting Controls is enabled

2. Click the Controls Actions tab

3. Click + Add Action

4. Configure the action:

   • Title: Export to CSV

   • Type: Export CSV

   • Columns: Visible Columns Only (or All Available)

5. Add another action for PDF if needed:

   • Title: Download PDF

   • Type: Download PDF

6. Click Submit Form

Custom Actions:

For advanced workflows, use Custom actions with JavaScript:

// Custom action example: Send selected rows to an API
promise = new Promise((resolve, reject) => {
  const selectedData = rows.map(row => ({
    id: row._id,
    name: row.data.fullName
  }));

  fetch('/api/process-employees', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(selectedData)
  })
  .then(response => response.json())
  .then(result => {
    alert(`Processed ${result.count} employees`);
    resolve(true); // Return true to refresh the grid
  })
  .catch(error => {
    alert('Error: ' + error.message);
    resolve(false);
  });
});

---

Configure Permissions

Ensure users can access reports and underlying data.

Project Level:

1. Go to Project Settings > Access

2. Find your Authenticated role

3. Enable Read All

Reporting UI Resource:

1. Go to Resources > Reporting UI

2. Click the Access tab

3. Enable Read All Submission for the Authenticated role

Source Forms:

1. Go to each form used in your report

2. Click the Access tab

3. Enable Read All Submission for the Authenticated role

Important: Users need Read All Submission on ALL source forms to see data in the report.

---

Reference

Report Configuration Options

Basic Settings

Option	Required	Description
Report Title	Yes	Display name for the report
Report Name	Yes	Unique identifier (alphanumeric, underscores, dots, dashes)
Items per page	No	Records per page (default: 10)
Cache requests	No	Store results in cache for performance
Cell max width	No	Maximum width of grid cells in pixels

Reporting Controls Settings

Option	Description
Enable Control Panel	Show/hide the controls panel
Control Panel Title	Header text for the panel
Controls Panel Theme	Bootstrap theme (default, primary, success, etc.)
Initially Collapsed	Start with panel collapsed

Embedding Options

Using Report URL:

Formio.Report.create(element, 'https://your-project.form.io/report/report-name');

Using Report JSON:

const reportSchema = { /* your report JSON */ };
Formio.Report.create(element, reportSchema, {
  projectEndpoint: 'https://your-project.form.io'
});

Report Events

Subscribe to events for custom behavior:

Formio.Report.create(element, reportUrl).then((report) => {

  // Row clicked
  report.on('rowClick', (rowData, rowIndex) => {
    console.log('Clicked row:', rowIndex, rowData);
  });

  // Row selection changed
  report.on('rowSelectChange', (selectedRows, gridInstance) => {
    console.log('Selected:', selectedRows.length, 'rows');
  });

  // Data fetch error
  report.on('fetchDataErrors', (error, gridInstance) => {
    console.error('Failed to fetch data:', error);
  });

  // Page changed
  report.on('page', (currentPage, gridInstance) => {
    console.log('Now on page:', currentPage);
  });

  // Items per page changed
  report.on('changeItemsPerPage', (itemsPerPage) => {
    console.log('Showing', itemsPerPage, 'items per page');
  });

});

Event	Arguments	Description
rowClick	rowData, rowIndex	User clicked a row
rowSelectChange	selectedRows, gridInstance	Selection changed
fetchDataErrors	error, gridInstance	Data fetch failed
page	currentPage, gridInstance	Page navigation
changeItemsPerPage	itemsPerPage	Items per page changed

Data Persistence

Report settings (filters, column visibility, sorting) persist in the browser's local storage.

To reset settings programmatically:

// Clear all report settings
localStorage.removeItem('formio-report-settings');

// Or clear settings for a specific report
const reportKey = 'formio-report-' + reportName;
localStorage.removeItem(reportKey);

---

Troubleshooting

Reports Loading Error

Symptom: Error when accessing the Reports tab in projects created before Reporting Module activation.

Cause: The project lacks the Reporting UI configuration resource.

Solution:

1. Go to Resources in your project

2. Click Import

3. Enter this embed URL: {{ yourServerUrl }}/reportingui/config

4. Ensure the resource is titled Reporting UI

5. Ensure the resource name and path is reportingui (exact spelling)

---

Unauthorized Error

Symptom: "Unauthorized" error when viewing an embedded report.

Cause: User lacks required permissions.

Solution: Verify these permissions are configured:

1. Project Level Access

   • Navigate to Project Settings > Access

   • Add "Read All" for your user role

2. Reporting UI Resource

   • Navigate to Resources > Reporting UI > Access

   • Add "Read All Submission" for your user role

3. Source Forms

   • Navigate to each source form > Access tab

   • Add "Read All Submission" for your user role

---

Module Not Found

Symptom: Cannot find module '@formio/reporting'

Cause: Module not installed correctly.

Solution:

# Verify installation
npm list @formio/reporting

# Reinstall if needed
npm install --save @formio/reporting

---

Report.create is Not a Function

Symptom: Formio.Report.create is not a function or Formio.Report is undefined

Cause: Reporting module not registered before use.

Solution: Call Formio.use(Reporting) before creating reports:

import { Formio } from '@formio/js';
import { Reporting } from '@formio/reporting';

// Must register BEFORE creating reports
Formio.use(Reporting);
Formio.setLicense('yourLicenseKey');

// Now create reports
Formio.Report.create(element, reportUrl);

---

Changes Not Appearing

Symptom: Report updates in the portal don't appear in your application.

Cause: Browser caching report settings in local storage.

Solution:

1. Clear local storage: Open browser DevTools > Application > Local Storage > Clear

2. Hard refresh: Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac)

Or programmatically:

localStorage.clear();
location.reload(true);

---

Date Operators Not Available

Symptom: Date operators (Date Difference, Day of Month, etc.) unavailable for some date fields.

Cause: Different date components save data in different formats.

Details:

• Date/Time component: Saves as ISO format (works with date operators)

• Textfield with Calendar: Saves as string (limited operator support)

Solution: Use the Date/Time component for fields you want to use with date operators.

---

Report Displays Incorrect Order

Symptom: Data appears in unexpected order.

Cause: Database updates can temporarily affect sort order.

Solution:

1. Click a column header to re-sort

2. Refresh the page

3. If persistent, check your default sort configuration