Create Vitruvio Report

All messages shown to the user must be written in Portuguese.

You are registering a new report inside a Vitruvio repository. Follow these steps in order.

Step 1 — Confirm you are inside a Vitruvio repo

ls vitruvio.json 2>/dev/null && echo "OK" || echo "NOT_A_VITRUVIO_REPO"

If NOT_A_VITRUVIO_REPO, stop and tell the user to cd into the correct repo.

Step 2 — Identify the report type

Ask the user which type applies (if not already clear from the request):

Type	When to use
MODELO_ESTATICO	A Jasper report whose layout is fully designed in a `.jrxml` file (Jaspersoft Studio). The dev provides or will provide the `.jrxml`.
DINAMICO_QUERY_SQL	A Vitruvio-managed report where data comes from a named query and columns/layout are configured in `vitruvio.json`. The `.jrxml` is still needed but is simpler — Vitruvio drives the structure.

Step 3 — Collect details

Ask the user (in a single message, only ask what is missing):

Both types:

Key — kebab-case or snake_case unique identifier.
Name — human-readable label shown in the UI.
Category — display category (e.g. "Compras", "Auditoria/Gondola").
Owner — Vitruvio username of the responsible person.
Orientation — RETRATO (portrait) or PAISAGEM (landscape). Default: RETRATO.
Allowed groups / users — who can access this report (can be empty arrays).
Has parameters? — does the user fill in parameters before running it? If yes, a params form is needed.

DINAMICO_QUERY_SQL only:

Query key — the named query that feeds the report (must be registered in vitruvio.json).
Columns — list of columns: name (DB column), label, alignment (LEFT/CENTER/RIGHT), width (px), aggregation (null, SUM, COUNT, etc.).

Step 4 — Create the files

MODELO_ESTATICO

Files live flat in reports/:

reports/<key>.jrxml — do not generate this file; tell the user to place the Jaspersoft-designed template here. Must target JasperReports 6.21.2 — do not save with a newer version.
reports/<key>-params.xml — only if the report has parameters (follows the same Vaadin XML form schema as panels).

DINAMICO_QUERY_SQL

Files live in a subdirectory:

reports/<key>/template.jrxml — do not generate this file; tell the user to place the template here.
reports/<key>/params.xml — only if the report has parameters.

Step 5 — Register in vitruvio.json

Read vitruvio.json, find or create the "reports" array, and add the entry.

MODELO_ESTATICO entry

{
  "key": "<key>",
  "name": "<name>",
  "type": "MODELO_ESTATICO",
  "category": "<category>",
  "owner": "<owner>",
  "template": "reports/<key>.jrxml",
  "parameterForm": "reports/<key>-params.xml",
  "orientation": "RETRATO",
  "allowedGroups": [],
  "allowedUsers": [],
  "columns": [],
  "schedules": []
}

Omit "parameterForm" if no params form.

DINAMICO_QUERY_SQL entry

{
  "key": "<key>",
  "name": "<name>",
  "description": "<description>",
  "type": "DINAMICO_QUERY_SQL",
  "category": "<category>",
  "owner": "<owner>",
  "template": "reports/<key>/template.jrxml",
  "parameterForm": "reports/<key>/params.xml",
  "query": "<query-key>",
  "orientation": "RETRATO",
  "allowedGroups": [],
  "allowedUsers": [],
  "columns": [
    {
      "name": "COLUMN_NAME",
      "label": "Column Label",
      "align": "LEFT",
      "width": 100,
      "aggregation": null
    }
  ]
}