[reports]

Report-template configuration.

Controls discovery of .html.j2 templates rendered by ubc report and the ubCode reports viewer, the output-size cap applied at render time, and the declared insights (templates with a need input and Cypher queries). Engine-level safety limits are fixed, not configuration: template fuel, recursion depth, and for an insight a 10 s deadline shared by all its queries, at most 10,000 rows per query and at most 4,000,000 intermediate rows in any one step of a query (over any of these, the render fails).

Guide: Writing reports.

reports.directory
Type:
string
Default:
"reports"

Directory (relative to the ubproject.toml, or absolute) that contains .html.j2 report templates.

reports.insights
Type:
table of tables
Default:
{}

Named insights: a report template plus a declaration of its need input and the Cypher queries that run before the template renders. The table key is the insight’s name, used by ubc report <name>: a letter or _, then letters, digits, _ or -; not a Windows device name (con, nul, com1, …), and not another insight’s name in different letter case. A template without a declaration still renders as a plain report.

Each entry: An insight: a report template with declared inputs and queries.

reports.insights.<name>.description
Type:
string

Short description, available to the template as insight.description.

reports.insights.<name>.input
Type:
string
Default:
"none"

Which needs the insight is rendered for: none (a global report), need (exactly one need) or needs (one or more needs).

Values:

  • "none": No input: a global report.

  • "need": Exactly one need.

  • "needs": One or more needs.

reports.insights.<name>.queries
Type:
table of (string or table)
Default:
{}

Named Cypher queries, run before the template renders; the template reads each result as queries.<name>, a list of rows keyed by the RETURN aliases, so a name is a letter or _, then letters, digits or _. A value is the query text, or { file = "..." } naming a file relative to [reports].directory. The input needs are bound as $current_id (input need) and $current_ids (inputs need and needs); $var and $build_tags are available as in ubc query cypher. All queries of a render share a 10 s deadline, a query may return at most 10,000 rows, and it may build at most 4,000,000 intermediate rows in any one step; over any of these, the render fails.

Each entry: An insight query: the Cypher text, or a file holding it.

Forms:

  • a string: The Cypher query text.

  • a table with file: A file holding the Cypher query.

reports.insights.<name>.queries.<name>.file
Type:
string

Path of the query file, relative to [reports].directory and inside it: /-separated, with no leading /, drive (C:), .., hidden (.) segment or backslash.

reports.insights.<name>.template
Type:
string

The .html.j2 template to render, relative to [reports].directory: /-separated, with no leading /, drive (C:), .., hidden (.) segment or backslash.

reports.insights.<name>.title
Type:
string

Human-readable title, shown by editors and available to the template as insight.title. Defaults to the insight’s name.

reports.insights.<name>.types
Type:
array of strings
Default:
[]

Need types the insight accepts as input. Empty accepts every type. Editors offer the insight only on needs of these types. Ignored when input is none: such an insight takes no need.

reports.max_output_bytes
Type:
integer
Default:
52428800

Maximum size, in bytes, of a rendered report. Rendering is aborted as soon as the output exceeds this cap.