Reports - COMING SOON

The Form.io Reporting Module is in active development, and will be released in an upcoming release. Please contact [email protected] for more information regarding this module. 
Introduction
Reports enable the display of [multiple] forms' submissions into the Form.io submission grid. 
The Form.io Reporting Module leverages the MongoDB aggregation operations under the hood that makes the following possible in reports:
joining of submissions from several forms based on common field(s);
calculations which are Report fields that are based on the report source forms submissions, but not fields from the original source form(s);
grouping of submission data using certain criteria.
Reports allow the management of report data in several ways, which can all be configured by the developer creating this report:
sorting
filtering
addition / removal of columns in the end user UX
pagination
selection of data rows
Execution of actions on selected rows of data. Default Actions include Export to CSV and Download to PDF. Custom Actions can also be defined, for addition to any report. 
Report Structure
Reports include the following UI elements: 
1.Reporting Grid. This is the main part of the report that displays the report data. It provides the ability to paginate and sort data as well as select rows. Additionally, when the Reporting Controls are disabled, it gives the ability to filter data by columns and control the visibility of columns.
2.Reporting Controls. This part is responsible for the report data management, such as filtering, columns visibility and actions on the rows data of the Reporting Grid. Reporting Controls are optional and can be enabled/disabled in the report settings. 
​
Report Structure
Reports Availability
The reporting functionality is available only for self-hosted environments and only when the reporting is a part of your server license.
Contact [email protected] to acquire a License
Once the reporting is enabled for your license key, you will see the Reports section in the sidebar of your projects.
Reports Section
When you open the Reports section for the projects that were created before the reporting was enabled for your license, you may see the Reports Loading Error. It may appear because there is no Reporting UI Configuration form in this project. To fix it, import the reporting UI configuration form to the project resources using the URL:  {{ yourServerUrl }}/reportingui/config . The resource name and path must be 'reportingui'.
For newly created projects, the Reporting UI configuration resource is added by default.
Reports section enables the creation of reports and a preview mode that excludes the report data fetch. This is an intentional preview for the UI / UX of the report, while all external scripts and APIs are not executable from the context of the Portal Application. 
To see the fully functioning report inclusive of Data Fetch, embed the Report into an Application as described below. 
Report Embedding
Please follow the steps to embed a report into your application:
1.Install the @formio/reporting module into your application:
npm i --save @formio/reporting 
or
yarn add @formio/reporting
2.Connect the reporting module in your application:
import {Formio} from 'formiojs';
import reporting from '@formio/reporting';
​
Formio.use(reporting, {license: 'yourLibraryLicense'});
​
Please note that you need a library license with the reporting enabled to use the @formio/reporting module.
Contact [email protected] to acquire a License
Once you connect @formio/reporting module in your app, the Report class is available in global Formio.
3.Create a report. For the report embedding you can use the report URL or the report JSON schema.
embed report URL:
Copy the report URL from the report Embed tab and use it for report creation.
import {  Formio } from 'formiojs';
​
Formio.Report.create(element, 'reportUrl').then(report => {
 // some custom code if needed
})
 embed report JSON:
import {  Formio } from 'formiojs';
​
Formio.Report.create(element, reportJSON, { projectEndpoint: 'projectURL' }).then(report => {
    // some custom code if needed
});
Report Creation
To create a report, go to the Reports section of your project and click the New Report button. You will see the report configuration wizard.
Basic Settings
Basic Settings Tab
Title - report title. This is a required field;
Name - report name. Name is required and must be a unique among other project reports. The name must only contain alphanumeric characters, underscores, dots and dashes and should not be ended by dash or dot.
Reporting Grid Basic Settings:
Items Per Page defines how many records to display on each page of the Reporting Grid;
Enable to Store Request Result in the Cache. When checked, the requests and its results will be stored in the cache and if the Report tries to make the request to the same URL with the same parameters, the cached data will be returned. It allows to increase performance, but if the source's data is changing quite often and you always need to keep it up-to-date, uncheck this option.
Cell max width sets the maximum width of the Reporting Grid cells.
Data Source(s)
Data Source(s) tab
Form(s) to create Report - project forms that are the data source for the report. You can select one or more forms/resources for your report. Please note that each selected form must have at least one field in common with at least one other selected form, when more then one forms are selected. 
Forms Connections. This settings is available when the report has more than one source forms - the multiform report. Here you must set connections between pairs of selected source forms by their common fields. If there are 3 source forms in the report, then 2 forms connections must be set (1: form1-form2, 2: form1-form3 or form2-form3), for 5 forms - 4 connections, and so on.
Base Form - the source form that has a common field with the Joining Form;
Connecting Field of Base Form - the Field of the Base Form that can have the same values (common values) as the Connecting Field of the Joining Form has;
Base Form Path to Connecting Value - path to the common value in the Connecting Field Value of the Base Form; 
Joining Form - the source form that has a common field with the Base Form;
Connecting Field of Joining Form - the Field (Component) of the Base Form that have the same values (common values) as the Connecting Field of the Base Form has;
Joining Form Path to Connecting Value - path to the common value in the Connecting Field Value of the Joining Form.
​
Example
Our report has two source forms:
Department Info that has 'Department Name' and 'Department Id' (key - departmentId) fields;
Employee with 'Department' field that is a select component. The 'Department' populates the options from the Department Info  resource and saves Department Id as a value.
Those forms are connected with each other by department id. The connection setting will be the following: 
Connection settings
If the Employee form saves the 'Department' field value as the entire submission object of the Department form, the connection setting will look the following:  
Connection settings with path
Calculated Extra Columns
Using this tab, you can add additional columns to your Reporting Grid that are calculated based on the fields of the source forms.
Calculated Extra Columns Tab
Column Title - the title of the calculated column.
Column Key. The key must only contain alphanumeric characters, underscores, dots and dashes and should not be ended by dash or dot.
Operator that is used to calculate the column value. For a numeric value, you can limit the number of decimal places in the calculated value. The following operators are available:
Array Size counts and returns the total number of items in an array;
Concatenate Strings concatenates strings and returns the concatenated string;
Date Difference returns the difference between two dates;
Day of Month returns the day of the month for a date as a number between 1 and 31;
Day of Week returns the day of the week for a date as a number between 1 (Sunday) and 7 (Saturday);
Day of Year returns the day of the year for a date as a number between 1 and 366;
Month Number returns the month of a date as a number between 1 and 12;
Week Number returns the week of the year for a date as a number between 0 and 53;
Year returns the year portion of a date;
Divide divides one number by another and returns the result;
Summarize calculates and returns the collective sum of numeric values;
Multiply multiplies numbers together and returns the result.
Grouping
Using this tab, you can create a grouped report. This is based on the MongoDB $group operator and separates the source forms submissions into groups according to the group fields.
Grouping Tab
Fields to group by - the field(s) of the report source form or calculated extra column used as criteria for grouping. 
Group Calculated Columns allow to add columns with values calculated per group. 
Column Title - the title of the group calculated column.
Column Key. The key must only contain alphanumeric characters, underscores, dots and dashes and should not be ended by dash or dot.
Operator that is used to calculate the column value. The following operators are available:
Count returns the number of records in a group;
Max returns the maximum value in a group;
Min returns the minimum value in a group;
Average returns the average value of the numeric values in a group;
Summarize computes the total amount of numeric values in a group.
Columns
Using this tab, you can define which columns are available for display in the Reporting Grid, as well as which columns are displayed by default.
Columns Tab
Available Columns set the columns that are available for display in the Reporting Grid and which visibility is managed from the controls panel (if enabled) or Reporting Grid UI. The columns appear in the Reporting Grid in the order they are added to the Available Columns data grid. Display Title option is available for not calculated columns. If Display Title is not set, the selected column component title displays as a columns title.
Default Columns defines which Available Columns are displayed in the Reporting Grid by default. If not set, all Available Columns are displayed.
Reporting Controls
In this tab, you can enable the Reporting Controls UI and set basic configuration for it. 
Controls Settings Tab
Reporting Controls Basic Settings:
Controls Title sets the title of the controls panel;
Controls Theme sets Bootstrap theme for the controls panel. 
Collapse Controls Panel Initially. When the option is enabled, the controls panel is displayed as collapsed when the report is loaded.
Controls Filters
This tab is available only when the Reporting Controls is enabled. Here you can add custom filters for the report data.
Controls Filters Tab
Number Of Filters Per Row sets the number of filters that will be displayed on the filter tab of the Reporting Controls on each row.
Filter Label Position set the position of the filter label for all filters. The Top, Left, Right options are available.
Reporting Filters set custom filters for the Report data.
Field defines the source form component or calculated columns to filter by.
Filter Type setы the filter operator that is used to determine the values that match the filter. The filter type options depend on the value type of the field, e.g. for the field of number type it can be Less Than/Greater Then/Is Equal To/Is Empty and other.
Filter Title sets the filter label. The field component title is used by default.

Controls Actions
This tab is available only when the Reporting Controls is enabled. Here you can add actions that will be executed for the selected Reporting Grid rows.
Controls Actions Tab
Title - a title of the action that the user will see in the actions dropdown.
Type. The following action types are available:
Export CSV exports selected rows data as CSV. You can export data for only the visible columns in the reporting table, or for all available columns.
Export CSV action settings
Download PDF exports selected rows data as PDF. You can download data for only the visible columns in the reporting table, or for all available columns. Each row's data is displayed on a separate page in the PDF document.
Custom action executes custom code for selected rows. You need to assign the promise to  a promise variable. If the promise returns the true, the Reporting Grid will be redrawn and the Report data reloaded after the action is executed.
Custom action settings
Examples
Preconditions
Before we start creating reports, we need to add some forms and resources to our project that will be the sources of data for our reports.
1.create a resource title name department and add the following components:
textField with title Department ID and API key departmentId;
textField with title Department Name and API key departmentName.
Department resource
Make several submissions for the department resource.
2.create a resource with title position and add the following components:
Text Field with title Position ID and API key positionId;
Text Field  with title Position Name and API key positionName.
Position resource
Make several submissions for the position resource.
3.create a resource with title salary and add the following components:
Select with title Position and API key positionId (Data Source Type - resource, Resource - position, Value Property - Position ID, Item Template  - '<span>{{ item.data.positionName }}</span>');
Number with title Salary and API key salary.
Salary resource
Make several submissions for the salary resource.
4.create a form with title employee and add the following components:
Text Field with title Employee ID and API key id;
Container with title Personal Info and API key personalInfo. Add components to the container:
Text Field with title First Name and API key name;
Text Field with title Last Name and API key lastName;
Select with title Foreign Languages and API key foreignLanguages  (Data Source Type - values, add several language values like English, French and so on,  Multiple Values - true);
Container with title Work Info and API key workInfo. Add components to the container:
Select with title Department and API key department (Data Source Type - resource, Resource - department, Value Property - Department ID, Item Template  - '<span>{{ item.data.departmentName }}</span>');
Select with title Position and API key position (Data Source Type - resource, Resource - position, Value Property - Position ID, Item Template  - '<span>{{ item.data.positionName }}</span>');
Date/Time with title Start Date and API key startDate;
Date/Time with title End Date and API key endDate;
Container with title Wage Info and API key wageInfo and add inside Number component with title Incremental Wage Rate and API key incrementalWageRate;
Select with title Foreign Languages and API key foreignLanguages  (Data Source Type - values, add several language values like English, French and so on,  Multiple Values - true);
Select with title Status and API key status (Data Source Type - values, Data Source Values - 'active' and 'dismissed', Multiple Values - true);
Text Field with title Notes and API key notes.
Employee form
Make several submissions for the employee form.
Simple Monoform Report without Controls
1.Click New Report button in the Reports section
2.Fill in Basic Reporting Settings (title, name, items per page) and click Next:
Basic Report Settings
3.Select the employee form as a report source form and click Next:
4.Skip Calculated Extra Columns and Grouping Configurations.
5.Go to Columns tab, configure Available Columns and Default Columns and click Next:
6.Save the report by clicking Submit Form.
7.The final report looks like this:
Simple Monoform report without controls
This report does not have the Reporting Controls enabled. All data operations are available in the Reporting Grid UI.
Monoform Report With Calculated Columns and Controls Enabled
1.Basic Settings configuration:
2.Select the employee form as a report source form:
3.Add 3 calculated columns to the report:
Calculated columns configuration:
Full Name:
Worked Total - difference between the date when the employee was hired and dismissed:
Languages - the number of foreign languages that the employee speaks.
4.Add columns:
Set the Display Title for the Employee ID (ID will be displayed as a columns name in the Reporting Grid instead of Employee ID).
5.Enable Controls and set Controls Title:
6.Configure Controls Filters:
7.Add some actions:
Actions:
Download PDF with all available columns in selected rows:
Download PDF with visible columns in selected rows:
Export CSV with all available columns in selected rows:
Export CSV with visible columns in selected rows:
Custom action that sets dismissed status and add the date of dismissal for the selected employees:
Custom JS Code:
const formioInstances = [];
_.each(selectedRows, (row) => {
  formioInstances.push(new Formio(`${Formio.getProjectUrl()}/employee/submission/${row._id}`))
});
​
promise = Formio.Promise.all(_.map(formioInstances, inst => inst.loadSubmission()))
  .then(submissions => {
    const transformedSubmissions = _.map(submissions, subm => {
      _.set(subm, 'data.status', 'dismissed');
      _.set(subm, 'data.workInfo.endDate', new Date().toISOString());
      return subm;
    });
    return Formio.Promise.all(_.map(formioInstances, (inst, ind) => inst.saveSubmission(transformedSubmissions[ind])));
  });
Custom action that sets active status and remove the date of dismissal for the selected employees:
Custom JS Code:
const formioInstances = [];
_.each(selectedRows, (row) => {
  formioInstances.push(new Formio(`${Formio.getProjectUrl()}/employee/submission/${row._id}`))
});
​
promise = Formio.Promise.all(_.map(formioInstances, inst => inst.loadSubmission()))
  .then(submissions => {
    const transformedSubmissions = _.map(submissions, subm => {
      _.set(subm, 'data.status', 'active');
      _.set(subm, 'data.workInfo.endDate', '');
      return subm;
    });
    return Formio.Promise.all(_.map(formioInstances, (inst, ind) => inst.saveSubmission(transformedSubmissions[ind])));
  });
8.The report looks like this:
The report with set filters and sorting:
You can manage the report columns visibility from the Columns tab of the Controls:
All actions are available in the Actions tab. To perform an action, select one or more rows, select an  action and click the Perform Action button:
Action result:
 Multiform Report with Calculated Columns and Controls Enabled
1.Basic Settings Configuration:
2.Add report source forms and set connections between them:
Data Source Report Settings
Connection between employee and department
Connection between employee and position
Connection between salary and position
3.Add calculated columns:
employee Full Name:
employee Total Salary - the salary amount taken from the salary resource multiplied by the Incremental Wage Rage taken from the employee form: 
4.Add the Reporting Grid columns:
5.Enable Controls:
6.Add some filters:
7.Add default actions:
8.The final report looks like this:
Multiform Report
Multiform Report with set filters
​
Grouped Multiform Report
1.Configure the report basic settings:
2.Add source forms and set connections for them:
Data Sources Configuration
Connections between source forms
3.Add a calculated column and save:
4.Add group criteria and some calculated columns for groups. We group all our submissions by department.
Groups Configuration
Group calculated columns:
Total Employees shows the number of employees for each department:
Average Salary shows the average salary per each department:
Spent On Salary Per Month summarizes total salary of each department employee and shows total department expenses for salary.
Max Incremental Wage Rate shows the maximum incremental wage rate in the department
5.Configure the Reporting Grid columns:
6.Enable the Reporting Controls:
7.Add some filters:
8.Add default actions:
9.The final report looks like this:
Report Styles
Import the reporting module styles in your application:
import '@formio/reporting/reporting.css';
Data Persistence
Report settings such as:
filters,
columns
sorting 
are persistent and stored in local storage. If you want to reset settings (e.g., when the user leaves the page, logs out), you need to add the appropriate logic to your application.
Reports Access
Technically Reports are the submissions of the Reporting UI resource. Access to reports is managed on the Access tab of the Reporting UI resource. Access to the Reports data is managed in the Access tab of each report source form.
Report Events
You can subscribe to the Reporting Grid events and perform some custom logic on them:
import {  Formio } from 'formiojs';
​
Formio.Report.create(...).then(report => {
  report.on('eventName', (arg1, arg2 ...) => {
   // custom code
  });
 });
Events:
rowClick (args: rowData, rowIndex) - emitted each time the Reporting Grid row is clicked;
rowSelectChange (args:  selectedRows, reportingGridInstance) - emitted each time the Reporting Grid row is selected/deselected ;
fetchDataErrors (args:  error, reportingGridInstance) - emitted when there is an error fetching the Reporting Grid data;
page (args:  currentPage, reportingGridInstance) - emitted each time the Reporting Grid page changes;
changeItemsPerPage (args: itemsPerPage) - emitted each time the number of items for the Reporting Grid page changes.
Last modified 1mo ago