119 lines
4.1 KiB
Markdown
119 lines
4.1 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```json
|
|
{
|
|
"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
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
Omit `"parameterForm"` if no params form.
|
|
|
|
Preserve the existing file structure and all other entries. Write the updated `vitruvio.json` back.
|
|
|
|
## Step 6 — Report
|
|
|
|
Tell the user:
|
|
- Entry registered in `vitruvio.json` with key `<key>` and type `<type>`
|
|
- For MODELO_ESTATICO: remind them to place the `.jrxml` at `reports/<key>.jrxml`, designed in Jaspersoft Studio 6.21.2
|
|
- For DINAMICO_QUERY_SQL: remind them to place the template at `reports/<key>/template.jrxml`
|
|
- If a params form is needed: what file to create and that it follows the same Vaadin XML schema as panels
|