Report and PDF reference

<report>

The root element: a report's parameters, data sources, preparation and output files. Save and publish a version before running or scheduling it.

Attribute	Type / values	Default	Meaning
schemaVersion	integer	1	Version of the report format. Only 1 is supported.
snapshotRetentionDays	integer	30	Days to keep the data captured for each run, so a failed run can be retried or rendered again; 1 to 3650.

Children: parameters, sources, preparation, transforms, outputs, table-plan, definition. Body: none.

<parameters>

The values a person or schedule supplies when the report runs.

Children: parameter. Body: none.

<parameter>

One input the report asks for when it runs, such as a date range or a customer.

Attribute	Type / values	Default	Meaning
name	string	—	Name used in queries and templates: a letter followed by letters, digits or underscores.
label	string	—	Label shown to the person running the report.
type	STRING, INTEGER, NUMBER, BOOLEAN, DATE, DATETIME, ENTITY	—	Kind of value. ENTITY expects the TypeID of a record.
required	boolean	—	Set to true if the report cannot run without this value.
entityPrefix	string	—	For ENTITY parameters: the TypeID prefix the value must have.

Children: default, options. Body: none.

<default>

The parameter's default, written as JSON: "0012" is text and 12 a number. null is different from leaving it out.

Children: none. Body: json.

<options>

Fixed choices for a STRING parameter: 1 to 100 unique values.

Children: option. Body: none.

<option>

One allowed value.

Children: none. Body: text.

<sources>

The queries that load the report's data.

Children: source. Body: none.

<source>

One query whose rows become a dataset named after the source. Write MicroSQL or a read-only GraphQL query; parameter values are supplied when the report runs.

Attribute	Type / values	Default	Meaning
name	string	—	Name of the dataset this source produces, used by transforms, outputs and templates. parameters, datasets and reportMeta are reserved.
kind	MICRO_SQL, GRAPHQL	—	The query language.
resultPath	string	—	GraphQL only: dot path under data to the rows. Leave it out to use the whole result.
cursorVariable	string	—	GraphQL only: the variable that receives the next page's cursor, so every page is loaded. Needs a resultPath pointing at a connection with edges and pageInfo.

Children: none. Body: query.

<preparation>

Optional Lua script that adds or reshapes datasets before the outputs are generated. It receives the report's data as input and must return it. It has the language and its libraries, including decimal arithmetic, but no ctx: fetch data with <source> queries.

Children: none. Body: lua.

<transforms>

Scripts that process rows one at a time, in the order listed.

Children: transform. Body: none.

<transform>

Lua script that changes or filters each row: it receives the row as input and returns the changed row, or nil to drop it. It cannot query data.

Attribute	Type / values	Default	Meaning
dataset	string	—	The dataset whose rows it processes.

Children: none. Body: lua.

<outputs>

The files each run produces.

Children: output. Body: none.

<output>

One file produced by each run: a PDF, a CSV file or an Excel workbook.

Attribute	Type / values	Default	Meaning
name	string	—	File name, such as customers.csv.
format	PDF, CSV, XLSX	—	File type: PDF, CSV or an Excel workbook (XLSX).
storage	DATABASE, FILE	—	DATABASE keeps the file with the run (up to 8 MiB); FILE puts it in managed file storage (up to 32 MiB).
folderId	string	—	With FILE storage: the folder to store the file in (a TypeID starting fld_).
dataset	string	—	CSV or single-sheet workbook: the dataset to export.

Children: columns, sheets, template, layout. Body: none.

<columns>

The columns to export, in order.

Children: column. Body: none.

<column>

One literal column name, in output order.

Children: none. Body: text.

<sheets>

Workbook only: up to 16 sheets, each with its own dataset and columns. Use this or dataset, not both.

Children: sheet. Body: none.

<sheet>

One worksheet.

Attribute	Type / values	Default	Meaning
name	string	—	Sheet name; unique within the workbook.
dataset	string	—	The dataset shown on this sheet.

Children: columns. Body: none.

<template>

An embedded PDF document. Write a pdf element here; SwiftXMLPDF provides validation and authoring help.

Children: pdf. Body: xml.

<layout>

Visual document layout in JSON. Use either layout or template for an output.

Children: none. Body: json.

<table-plan>

Table selections, filters and ordering in JSON. Sources and parameters must match these selections.

Children: none. Body: json.

<definition>

Complete report definition in JSON. Must be the only child and cannot be combined with report attributes.

Children: none. Body: json.

<pdf>

PDF document. Dimensions are points (72 per inch); default A4 portrait, 40-point margins.

Attribute	Type / values	Default	Meaning
size	A4, Letter	A4	Page size.
orientation	portrait, landscape	portrait	Page orientation.
margin	number	40	Page margin on every side, in points.
t:if	expression	—	Condition; this element is omitted when false.
t:elseif	expression	—	Condition checked when the preceding t:if or t:elseif was false.
t:else	string	—	Fallback branch; use an empty value.
t:for	expression	—	Repeat this element for each item in a list.
t:as	string	—	Name for the current t:for item, or for the t:let value.
t:let	expression	—	Expression whose value is available, under the t:as name, inside this element.
t:attr-<name>	expression	—	Sets any attribute above without a t: prefix from an expression, for example t:attr-width.

Children: view, table, text, spacer, image, barcode, qrcode. Body: none.

<view>

Vertical or horizontal container. Groups child content in the selected layout direction.

Attribute	Type / values	Default	Meaning
width	dimension	—	Points or percentage of available width.
height	dimension	—	Height in points; percentage heights use the content height.
margin-top	number	—	Space above the element, in points.
margin-left	number	—	Space to the left of the element, in points.
padding	number	—	Space between the border and the content, in points.
backgroundColor	color	—	Background colour.
font	string	—	Font name available in your installation.
size	number	—	Font size in points.
color	color	—	Text colour.
align	left, center, right	—	Text alignment.
leading	number	—	Extra space between lines of text, in points.
layout	vertical, horizontal	—	How children are arranged: vertical stacks them, horizontal places them side by side.
borderWidth	number	—	Border thickness in points.
borderColor	color	—	Border colour.
t:if	expression	—	Condition; this element is omitted when false.
t:elseif	expression	—	Condition checked when the preceding t:if or t:elseif was false.
t:else	string	—	Fallback branch; use an empty value.
t:for	expression	—	Repeat this element for each item in a list.
t:as	string	—	Name for the current t:for item, or for the t:let value.
t:let	expression	—	Expression whose value is available, under the t:as name, inside this element.
t:attr-<name>	expression	—	Sets any attribute above without a t: prefix from an expression, for example t:attr-width.

Children: view, table, text, spacer, image, barcode, qrcode. Body: none.

<table>

Table of rows and cells.

Attribute	Type / values	Default	Meaning
width	dimension	—	Points or percentage of available width.
height	dimension	—	Height in points; percentage heights use the content height.
margin-top	number	—	Space above the element, in points.
margin-left	number	—	Space to the left of the element, in points.
padding	number	—	Space between the border and the content, in points.
backgroundColor	color	—	Background colour.
font	string	—	Font name available in your installation.
size	number	—	Font size in points.
color	color	—	Text colour.
align	left, center, right	—	Text alignment.
leading	number	—	Extra space between lines of text, in points.
layout	vertical, horizontal	—	How children are arranged: vertical stacks them, horizontal places them side by side.
borderWidth	number	—	Border thickness in points.
borderColor	color	—	Border colour.
t:if	expression	—	Condition; this element is omitted when false.
t:elseif	expression	—	Condition checked when the preceding t:if or t:elseif was false.
t:else	string	—	Fallback branch; use an empty value.
t:for	expression	—	Repeat this element for each item in a list.
t:as	string	—	Name for the current t:for item, or for the t:let value.
t:let	expression	—	Expression whose value is available, under the t:as name, inside this element.
t:attr-<name>	expression	—	Sets any attribute above without a t: prefix from an expression, for example t:attr-width.

Children: row. Body: none.

<row>

One table row.

Attribute	Type / values	Default	Meaning
width	dimension	—	Points or percentage of available width.
height	dimension	—	Height in points; percentage heights use the content height.
margin-top	number	—	Space above the element, in points.
margin-left	number	—	Space to the left of the element, in points.
padding	number	—	Space between the border and the content, in points.
backgroundColor	color	—	Background colour.
font	string	—	Font name available in your installation.
size	number	—	Font size in points.
color	color	—	Text colour.
align	left, center, right	—	Text alignment.
leading	number	—	Extra space between lines of text, in points.
layout	vertical, horizontal	—	How children are arranged: vertical stacks them, horizontal places them side by side.
borderWidth	number	—	Border thickness in points.
borderColor	color	—	Border colour.
t:if	expression	—	Condition; this element is omitted when false.
t:elseif	expression	—	Condition checked when the preceding t:if or t:elseif was false.
t:else	string	—	Fallback branch; use an empty value.
t:for	expression	—	Repeat this element for each item in a list.
t:as	string	—	Name for the current t:for item, or for the t:let value.
t:let	expression	—	Expression whose value is available, under the t:as name, inside this element.
t:attr-<name>	expression	—	Sets any attribute above without a t: prefix from an expression, for example t:attr-width.

Children: cell. Body: none.

<cell>

One cell in a row; it can hold any content element.

Attribute	Type / values	Default	Meaning
width	dimension	—	Points or percentage of available width.
height	dimension	—	Height in points; percentage heights use the content height.
margin-top	number	—	Space above the element, in points.
margin-left	number	—	Space to the left of the element, in points.
padding	number	—	Space between the border and the content, in points.
backgroundColor	color	—	Background colour.
font	string	—	Font name available in your installation.
size	number	—	Font size in points.
color	color	—	Text colour.
align	left, center, right	—	Text alignment.
leading	number	—	Extra space between lines of text, in points.
layout	vertical, horizontal	—	How children are arranged: vertical stacks them, horizontal places them side by side.
borderWidth	number	—	Border thickness in points.
borderColor	color	—	Border colour.
colspan	integer	—	Columns the cell spans. It does not merge cells, so set explicit cell widths as well.
t:if	expression	—	Condition; this element is omitted when false.
t:elseif	expression	—	Condition checked when the preceding t:if or t:elseif was false.
t:else	string	—	Fallback branch; use an empty value.
t:for	expression	—	Repeat this element for each item in a list.
t:as	string	—	Name for the current t:for item, or for the t:let value.
t:let	expression	—	Expression whose value is available, under the t:as name, inside this element.
t:attr-<name>	expression	—	Sets any attribute above without a t: prefix from an expression, for example t:attr-width.

Children: view, table, text, spacer, image, barcode, qrcode. Body: none.

<text>

Consecutive whitespace becomes a single space. Default Helvetica 12, leading 2; t:text replaces the body.

Attribute	Type / values	Default	Meaning
width	dimension	—	Points or percentage of available width.
height	dimension	—	Height in points; percentage heights use the content height.
margin-top	number	—	Space above the element, in points.
margin-left	number	—	Space to the left of the element, in points.
padding	number	—	Space between the border and the content, in points.
backgroundColor	color	—	Background colour.
font	string	—	Font name available in your installation.
size	number	—	Font size in points.
color	color	—	Text colour.
align	left, center, right	—	Text alignment.
leading	number	—	Extra space between lines of text, in points.
layout	vertical, horizontal	—	How children are arranged: vertical stacks them, horizontal places them side by side.
borderWidth	number	—	Border thickness in points.
borderColor	color	—	Border colour.
t:text	expression	—	Expression whose result replaces the element's text.
t:if	expression	—	Condition; this element is omitted when false.
t:elseif	expression	—	Condition checked when the preceding t:if or t:elseif was false.
t:else	string	—	Fallback branch; use an empty value.
t:for	expression	—	Repeat this element for each item in a list.
t:as	string	—	Name for the current t:for item, or for the t:let value.
t:let	expression	—	Expression whose value is available, under the t:as name, inside this element.
t:attr-<name>	expression	—	Sets any attribute above without a t: prefix from an expression, for example t:attr-width.

Children: none. Body: text.

<spacer>

Empty spacing block; size defaults to 8 points.

Attribute	Type / values	Default	Meaning
width	dimension	—	Points or percentage of available width.
height	dimension	—	Height in points; percentage heights use the content height.
margin-top	number	—	Space above the element, in points.
margin-left	number	—	Space to the left of the element, in points.
padding	number	—	Space between the border and the content, in points.
backgroundColor	color	—	Background colour.
font	string	—	Font name available in your installation.
size	number	—	Font size in points.
color	color	—	Text colour.
align	left, center, right	—	Text alignment.
leading	number	—	Extra space between lines of text, in points.
layout	vertical, horizontal	—	How children are arranged: vertical stacks them, horizontal places them side by side.
borderWidth	number	—	Border thickness in points.
borderColor	color	—	Border colour.
t:if	expression	—	Condition; this element is omitted when false.
t:elseif	expression	—	Condition checked when the preceding t:if or t:elseif was false.
t:else	string	—	Fallback branch; use an empty value.
t:for	expression	—	Repeat this element for each item in a list.
t:as	string	—	Name for the current t:for item, or for the t:let value.
t:let	expression	—	Expression whose value is available, under the t:as name, inside this element.
t:attr-<name>	expression	—	Sets any attribute above without a t: prefix from an expression, for example t:attr-width.

Children: none. Body: none.

<image>

PNG/JPEG source resolved by the CoCoCo app.

Attribute	Type / values	Default	Meaning
width	dimension	—	Points or percentage of available width.
height	dimension	—	Height in points; percentage heights use the content height.
margin-top	number	—	Space above the element, in points.
margin-left	number	—	Space to the left of the element, in points.
padding	number	—	Space between the border and the content, in points.
backgroundColor	color	—	Background colour.
font	string	—	Font name available in your installation.
size	number	—	Font size in points.
color	color	—	Text colour.
align	left, center, right	—	Text alignment.
leading	number	—	Extra space between lines of text, in points.
layout	vertical, horizontal	—	How children are arranged: vertical stacks them, horizontal places them side by side.
borderWidth	number	—	Border thickness in points.
borderColor	color	—	Border colour.
src	string	—	The image, as a PNG or JPEG data: URI.
t:src	expression	—	Expression that gives the image data: URI.
t:if	expression	—	Condition; this element is omitted when false.
t:elseif	expression	—	Condition checked when the preceding t:if or t:elseif was false.
t:else	string	—	Fallback branch; use an empty value.
t:for	expression	—	Repeat this element for each item in a list.
t:as	string	—	Name for the current t:for item, or for the t:let value.
t:let	expression	—	Expression whose value is available, under the t:as name, inside this element.
t:attr-<name>	expression	—	Sets any attribute above without a t: prefix from an expression, for example t:attr-width.

Children: none. Body: none.

<barcode>

Barcode. Invalid values prevent the PDF from being generated.

Attribute	Type / values	Default	Meaning
width	dimension	—	Points or percentage of available width.
height	dimension	—	Height in points; percentage heights use the content height.
margin-top	number	—	Space above the element, in points.
margin-left	number	—	Space to the left of the element, in points.
padding	number	—	Space between the border and the content, in points.
backgroundColor	color	—	Background colour.
font	string	—	Font name available in your installation.
size	number	—	Font size in points.
color	color	—	Text colour.
align	left, center, right	—	Text alignment.
leading	number	—	Extra space between lines of text, in points.
layout	vertical, horizontal	—	How children are arranged: vertical stacks them, horizontal places them side by side.
borderWidth	number	—	Border thickness in points.
borderColor	color	—	Border colour.
value	string	—	The value to encode.
t:value	expression	—	Expression that gives the value to encode.
type	code128, code39, ean13, upca	—	Barcode type.
t:if	expression	—	Condition; this element is omitted when false.
t:elseif	expression	—	Condition checked when the preceding t:if or t:elseif was false.
t:else	string	—	Fallback branch; use an empty value.
t:for	expression	—	Repeat this element for each item in a list.
t:as	string	—	Name for the current t:for item, or for the t:let value.
t:let	expression	—	Expression whose value is available, under the t:as name, inside this element.
t:attr-<name>	expression	—	Sets any attribute above without a t: prefix from an expression, for example t:attr-width.

Children: none. Body: none.

<qrcode>

QR code; default 96 points.

Attribute	Type / values	Default	Meaning
width	dimension	—	Points or percentage of available width.
height	dimension	—	Height in points; percentage heights use the content height.
margin-top	number	—	Space above the element, in points.
margin-left	number	—	Space to the left of the element, in points.
padding	number	—	Space between the border and the content, in points.
backgroundColor	color	—	Background colour.
font	string	—	Font name available in your installation.
size	number	—	Font size in points.
color	color	—	Text colour.
align	left, center, right	—	Text alignment.
leading	number	—	Extra space between lines of text, in points.
layout	vertical, horizontal	—	How children are arranged: vertical stacks them, horizontal places them side by side.
borderWidth	number	—	Border thickness in points.
borderColor	color	—	Border colour.
value	string	—	The value to encode.
t:value	expression	—	Expression that gives the value to encode.
t:if	expression	—	Condition; this element is omitted when false.
t:elseif	expression	—	Condition checked when the preceding t:if or t:elseif was false.
t:else	string	—	Fallback branch; use an empty value.
t:for	expression	—	Repeat this element for each item in a list.
t:as	string	—	Name for the current t:for item, or for the t:let value.
t:let	expression	—	Expression whose value is available, under the t:as name, inside this element.
t:attr-<name>	expression	—	Sets any attribute above without a t: prefix from an expression, for example t:attr-width.

Children: none. Body: none.