Skip to main content

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​

New custom reportSLUG (URL SEGMENT)orders-summaryTITLEOrders summaryDATA CONNECTORsales ▾NAMED QUERYorders_by_status_get ▾DESCRIPTIONOpen and closed orders, per statusPARAMETERScompanyCompanystring ▾required🗑+ Add parameterJINJA MARKDOWN TEMPLATEInsert example:Bullet listMarkdown tableGrouped sectionsSummary + table✦ Scaffold from query1## Summary23- Total rows: {{ ctx.data.rows | length }}45{% for row in ctx.data.rows %}6- {{ row.STATUS }} : {{ row.N }}7{% endfor %}Rendered 3 of 3 rows✕Summary• Total rows: 3• Open : 98• Closed : 3314• Cancelled : 12TEST PARAMETERScompany00001▷ Test renderSaveCancelSlugthe report's addressDataa query of a connectorParametersasked when the report runsJinja markdownctx.data.rows, ctx.paramsStartersexamples, or a table of the columnsPreviewthe template rendered on real rowsTest render200 rows at most, nothing saved

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.

FieldUse
Slug (URL segment)The report's id, part of its address: lowercase letters, digits, - and _. Unique among the templates.
TitleThe headline on the Reports page and on the PDF cover.
Data connector, Named queryWhere the rows come from: a query of a connector. Both are required.
DescriptionShown under the title on the Reports page.
ParametersOne 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 templateThe body of the report, in markdown with Jinja tags.

Writing the template​

The template reads a context, ctx:

NameContent
ctx.data.rowsThe rows of the query, each a set of columns: {{ row.STATUS }}.
ctx.data.columnsThe query's columns, with their name and label.
ctx.paramsThe 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:*:run sees 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.