Report templates
A report template is a report written by an operator without code: a query of a connector provides the rows, parameters are asked when the report runs, and a Jinja markdown template turns the rows into the document. Once saved, the report appears on the Reports page (/reports) beside the reports the applications ship, and downloads as PDF or markdown.
Open it from Liberty Next → Insight → Report templates (superusers).
At a glance
The list
The page shows the file the templates are saved in and how many there are, then one card per template: its title, its id (custom:<slug>) and the query it reads (<connector>.<query>), with Edit and Delete — a deletion is confirmed first. New template and Reload config are in the page header.
A save validates every template, writes them and refreshes the list of reports at once: no restart is needed.
The editor
New template, or Edit on a card, opens the window New custom report / Edit custom report.
| Field | Use |
|---|---|
| Slug (URL segment) | The report's id, part of its address: lowercase letters, digits, - and _. Unique among the templates. |
| Title | The headline on the Reports page and on the PDF cover. |
| Data connector, Named query | Where the rows come from: a query of a connector. Both are required. |
| Description | Shown under the title on the Reports page. |
| Parameters | One line per input the report needs at run time: a name, a label, a type (string, int, float, bool) and required. Add parameter adds one. The query receives the parameters by their name. |
| Jinja markdown template | The body of the report, in markdown with Jinja tags. |
Writing the template
The template reads a context, ctx:
| Name | Content |
|---|---|
ctx.data.rows | The rows of the query, each a set of columns: {{ row.STATUS }}. |
ctx.data.columns | The query's columns, with their name and label. |
ctx.params | The values the user entered for the parameters. |
The standard Jinja filters are available (length, join, sort, selectattr…). The template runs in a closed environment: nothing outside this context is reachable. The editor completes the column names of the query as you type.
Above the editor, Insert example offers four starters — Bullet list, Markdown table, Grouped sections, Summary + table — each replacing the body after a confirmation. Scaffold from query writes a markdown table of every column the query returns; it waits for a connector and a query.
Test render
Under the editor, Test parameters takes a value per parameter, and Test render runs the query with them and renders the template beside the editor — on 200 rows at most, nothing saved. The head of the preview says how many rows were rendered (Rendered 3 of 3 rows) or that the render failed, with the reason. When the query returns more rows, the preview says so; the real report holds every row.
Running a report
The Reports page lists the reports the user may run, operator-written ones included. Run opens a form with the parameters and the format (PDF or markdown); Run & download produces the file. The PDF follows the install's branding — Liberty Next → Administer → App → PDF branding.
Access
- Writing templates: superusers, in Liberty Next → Insight → Report templates.
- Running them: a role that holds
reports:custom:*:runsees every operator-written report on the Reports page — entered as a pattern in the role editor, see Roles and permissions. - The query runs under the user's data scope, as everywhere else.
Tips & best practices
- Write one query per report, returning exactly the columns the template prints; let the query do the sorting and the totals.
- Start from Scaffold from query or an example, then Test render with realistic parameters before saving.
- Give every required input a parameter rather than a constant in the query: the same template then serves every company or period.