Running Reports

Users can run reports through the admin UI or from relevant application views using the actions provided by the Reports add-on. The report engine loads the report definition and the template from the application code or from the database and generates the output document:

run 1
Figure 1. Running a report

Running from Reports List

The easiest way to run reports is from the Run report view. The user must have the permission to access this view. The list will contain all reports that are available to the user in accordance with their role. If the report has external parameters, they will be requested in a special form when running the report.

Running from Views

Users can run reports from arbitrary views using special actions and associated buttons or component context menu items. In this case, the availability of the report in this view is checked in addition to the user role.

Action types and examples of their use are described below.

RunReportAction

io.jmix.reportsflowui.action.RunReportAction is a standard action for running the reports associated with the current view or list component. It should be defined for a Button or a list component (dataGrid, treeDataGrid).

Below is an example of using the declarative action for the DataGrid:

<hbox id="buttonsPanel" classNames="buttons-panel">
    <!-- ...  -->
    <button id="runBtn" action="booksDataGrid.run"/> (1)
</hbox>
<dataGrid id="booksDataGrid"
          width="100%"
          minHeight="20em"
          dataContainer="booksDc">
    <actions>
        <!-- ...  -->
        <action id="run" type="report_runReport"/> (2)
    </actions>
</dataGrid>
1 Add a button with run report action.
2 The type attribute defines a specific report_runReport action type, provided by the Reports add-on.

Example of programmatically creating the action together with a button declared in the view XML descriptor:

@ViewComponent
private JmixButton runBtn;

@Autowired
private Actions actions;

@Subscribe
public void onInit(final InitEvent event) {
    RunReportAction<Book> action = actions.create(RunReportAction.ID);

    runBtn.setAction(action);
}

When the action is performed, a modal Run report dialog will appear, displaying reports related to the current view. When the user selects a report from the list, the parameters input form is displayed (if any have been defined) and the report will be generated.

RunListEntityReportAction

io.jmix.reportsflowui.action.RunListEntityReportAction is a standard action for printing reports for entity instances associated with a list component (dataGrid, treeDataGrid).

The action only selects reports having an external parameter of the Entity or the List of entities type and where the parameter entity type matches the entity type displayed by the list component. If only one report is available as a result of selection, it is invoked immediately. If several reports are available, their list is offered to the user for selection.

The external parameter value is passed to the report using the following rules:

  • If the parameter has the List of entities type, the list of instances currently selected in the list component is passed into it.

  • If the parameter has the Entity type, and the list component has a single instance selected (one row is highlighted), then this instance is passed into the report.

  • If the parameter is of the Entity type, and the list component has several rows selected, then the report runs several times according to the number of selected instances. After execution, the user gets a single ZIP archive containing all generated reports.

Below is an example of using the declarative action for the DataGrid:

<hbox id="buttonsPanel" classNames="buttons-panel">
    <!-- ...  -->
    <button id="runListBtn" action="authorsDataGrid.runList"/> (1)
</hbox>
<dataGrid id="authorsDataGrid"
          width="100%"
          minHeight="20em"
          dataContainer="authorsDc">
    <actions>
        <!-- ...  -->
        <action id="runList" type="report_runListEntityReport"/> (2)
    </actions>
</dataGrid>
1 Add a button with run list entity report action.
2 The type attribute defines a specific report_runListEntityReport action type, provided by the framework.

Example of programmatically creating the action together with a button declared in the view XML descriptor:

@ViewComponent
private JmixButton runListBtn;

@Autowired
private Actions actions;

@Subscribe
public void onInit(final InitEvent event) {
    RunListEntityReportAction<Author> action = actions.create(RunListEntityReportAction.ID);

    runListBtn.setAction(action);
}

When the action is performed, if no entities were selected from the list component, a confirmation window will be displayed.

run list entity report action confirmation

After that, the modal Run report dialog will open where reports related to the current view will be displayed. From this modal view, the user can run some report for the selected entity.

RunSingleEntityReportAction

io.jmix.reportsflowui.action.RunSingleEntityReportAction is an action associated with an entity detail view. The action only selects reports having an external parameter of the Entity or the List of entities type and where the parameter entity type matches the edited entity type. If only one report is available as a result of selection, it is invoked immediately. If several reports are available, their list is offered to user for selection.

The external parameter value - edited entity instance - is passed into the report. If the parameter has the List of entities type, then a list containing a single item is passed.

Below is an example of using the action in a button located near the standard OK and Cancel buttons:

<hbox id="detailActions">
    <button id="saveAndCloseBtn" action="saveAction"/>
    <button id="closeBtn" action="closeAction"/>
    <button id="reportButton" icon="PRINT"/>
</hbox>
@Autowired
private Actions actions;

@ViewComponent
private JmixButton reportButton;

@Subscribe
public void onInitEntity(final InitEntityEvent<Book> event) {
    RunSingleEntityReportAction<Book> action = actions.create(RunSingleEntityReportAction.ID);
    action.setReportOutputName(null);

    reportButton.setAction(action);
}

Reports API

Use Code Snippets to generate code for running reports using the API.

ReportRunner

ReportRunner is an interface used for running reports. All its methods return the ReportOutputDocument object that contains the result of report execution.

Below are a few examples using ReportRunner.

  1. Running a report based on the information specified in the ReportRunContext object:

    @Autowired
private ReportRunner reportRunner;

@Subscribe("rrcBtn2")
public void onRrcBtn2Click(ClickEvent<JmixButton> event) {
    ReportOutputDocument document = reportRunner
            .run(new ReportRunContext(report).setParams(paramsMap)); (1)
}
    1 The ReportRunContext contains the report entity and parameters.

  2. Running a report by its code and additional information specified using the fluent interface:

    @Autowired
private ReportRunner reportRunner;

@Subscribe("rrBtn1")
public void onRrBtn1Click(ClickEvent<JmixButton> event) {
    ReportOutputDocument document = reportRunner.byReportCode("BOOKS") (1)
            .addParam("type", type) (2)
            .withTemplateCode("books-template") (3)
            .run(); (4)
}
    1 Entry point to the fluent interface for a report with a specified code.
    2 Adds an input parameter to the parameter map.
    3 Sets a code of template that will be used to run a report.
    4 Builds a ReportRunContext instance and runs a report using this run context.

  3. Running a report by the report entity and additional information specified using the fluent interface:

    @Autowired
private ReportRunner reportRunner;

@Subscribe("rrBtn2")
public void onRrBtn2Click(ClickEvent<JmixButton> event) {
    ReportOutputDocument document = reportRunner.byReportEntity(report)
            .addParam("type", type)
            .withOutputType(ReportOutputType.PDF) (1)
            .withOutputNamePattern("Books") (2)
            .run();
}
    1 Sets a type of output document.
    2 Sets a name pattern of an output document.

You can get the report contents and file name directly from ReportOutputDocument:

String documentName = document.getDocumentName();

byte[] content = document.getContent();

UiReportRunner

UiReportRunner is an interface for executing reports from the application views. In addition to the options required to run a report, UiReportRunner allows you to configure the following features:

  • Displaying the result of the report execution in the browser (in the case of table templates).

    uiReportRunner.runAndShow(new UiReportRunContext(report));

  • Whether to show a dialog to input the report parameters before run. Use ParametersDialogShowMode for this purpose. Three modes are supported:

    • YES - to show the dialog to input the report parameters.

    • NO - do not show the dialog to input the report parameters.

    • IF_REQUIRED - to show the dialog to input the report parameters if:

      • The report has input parameters;

      • The report has several templates;

      • The report has one template with an alterable output type.

  • Execute report generation synchronously or in the background:

    uiReportRunner.byReportEntity(report)
        .withParametersDialogShowMode(ParametersDialogShowMode.IF_REQUIRED)
        .inBackground(RunReportView.this)
        .runAndShow();

  • Run a report several times for the specified parameter alias and values:

    uiReportRunner.byReportEntity(report)
        .withOutputType(ReportOutputType.PDF)
        .withTemplateCode("publication-template")
        .withParametersDialogShowMode(ParametersDialogShowMode.NO)
        .runMultipleReports("entity", publicationList);

    The runMultipleReports() method runs a report for each object from the specified collection. Objects in the collection should have the same type as an input parameter with specified alias.

ReportRunContext

The ReportRunContext class stores the following information required for report running:

  • The Report entity;

  • The ReportTemplate entity: if not specified, the default template is used;

  • Input parameters;

  • Type of output document;

  • Output name pattern.

Let’s look at examples of creating a ReportRunContext:

ReportRunContext context = new ReportRunContext(report)
        .addParam("type", type)
        .setOutputNamePattern("Books");

ReportRunContext context = new ReportRunContext(report)
        .setReportTemplate(template)
        .setOutputType(ReportOutputType.PDF)
        .setParams(paramsMap);

ReportZipUtils

The ReportZipUtils interface helps package a list of ReportOutputDocument objects into one ZIP archive.

byte[] zipArchiveContent = reportZipUtils.createZipArchive(documents);
downloader.download(zipArchiveContent, "Reports.zip", DownloadFormat.ZIP);