Skip to main content

Create and Open Reports

This page describes the recommended ADITO workflow for building a report: create the JasperReports design, prepare the data in JDito, connect it to a Report ViewTemplate, and open it in the client.

  1. Create the report design (*_report) in the Designer.
  2. Define the report fields and parameters in JasperReports.
  3. Create an EntityField that prepares the report payload in JDito.
  4. Bind that field to the reportData property of a Report ViewTemplate.
  5. Open the report view through neon.openContextWithRecipe(...).

1. Create the report design​

Create a new report in the appropriate project and use a descriptive name that ends with _report, for example OrganisationReport_report.

Inside the report, define:

  • the fields that should receive row-based data,
  • the parameters that should receive one-off values such as dates, translations, or flags,
  • the layout bands and text fields that render the output.

2. Keep fields and parameters explicit​

The handover from JDito to JasperReports depends on exact names.

  • Field names in the report must match the field names used in your ReportData object.
  • Parameter names in the report must match the names you fill in JDito.
  • Field order matters when you add row data as a table-like array.
warning

Field and parameter names are case-sensitive. If the Jasper design says ORGNAME, your JDito data must use ORGNAME as well.

3. Prepare the report data in JDito​

The following example shows the common pattern: create a report object, prepare parameters, prepare field data, and return the exported report payload from an EntityField.

import { datetime, result } from "@aditosoftware/jdito-types";
import { newSelect } from "SqlBuilder_lib";
import { Report, ReportData } from "Report_lib";

const report = new Report("OrganisationReport_report");

const reportFields = ["ORGNAME", "CUSTOMERCODE"];
const reportData = new ReportData(reportFields);

const params = {};
params.date = datetime.toDate(datetime.date(), "dd.MM.yyyy");
report.addReportParams(params);

const data = newSelect("NAME, CUSTOMERCODE")
  .from("ORGANISATION")
  .table();

reportData.add(data);
report.setReportData(reportData);

result.string(report.exportReport()[1]);

Notes on the example​

  • ReportData receives the field names in the same order as the SQL result columns.
  • addReportParams(...) maps single values into Jasper parameters.
  • result.string(report.exportReport()[1]) returns the binary payload that the Report ViewTemplate expects in reportData.

If your project exposes reporting helpers via a differently named library, adapt the import accordingly.

4. Bind the field to a Report ViewTemplate​

Create a dedicated report view such as OrganisationReport_view and add the Report ViewTemplate to it.

Set the following properties:

  • entityField: usually #ENTITY
  • reportData: the EntityField whose valueProcess returns the exported report payload
  • favoriteActionGroup1-3: optional action groups for report actions such as export or dispatch

See also: Report ViewTemplate

5. Open the report view​

The recommended way to open a report is through a dedicated report view and neon.openContextWithRecipe(...).

import { neon, neonFilter, vars } from "@aditosoftware/jdito-types";

const recipe = neonFilter
  .createEntityRecordsRecipeBuilder()
  .parameters({
    OrganisationReportData_param: true,
  })
  .uidsIncludelist([vars.get("$sys.uid")])
  .toString();

neon.openContextWithRecipe(
  "Organisation",
  "OrganisationReport_view",
  recipe,
  neon.OPERATINGSTATE_VIEW,
  null,
  true
);

This pattern lets you open the report in a normal ADITO context while still controlling exactly when the expensive report field should be calculated.

Performance recommendation​

Generate report data only when the report view is actually opened.

Typical pattern:

  • the action sets a dedicated parameter in the recipe,
  • the report field checks that parameter in valueProcess,
  • the report is generated only when the parameter is present or true.

This avoids unnecessary report generation when the field appears in other contexts or is loaded indirectly.

Reuse logic from libraries​

Keep report assembly logic in reusable JDito libraries whenever possible.

That gives you:

  • one place for SQL and parameter preparation,
  • easier reuse across actions and export flows,
  • simpler maintenance when field or parameter names change.

Server-side export​

If the goal is file export rather than an interactive report view, use the report API instead of opening a view.

Relevant references:

Legacy note​

neon.openReport() still exists for legacy compatibility, but it is deprecated. New implementations should prefer report views and neon.openContextWithRecipe(...).