Using the Template Builder

Build report templates visually by assembling blocks instead of writing .tpl code manually, and let the builder generate it for you.

Use Template Builder to create or maintain a Template visually. The builder converts blocks into .tpl code, so operators can define report structure without writing the Template file manually.

Objective

---

Build a Template from visual blocks and save it for future Report generation.

For example, a monthly transaction Template can use fixed text for the header, a Loop for each transaction row, Variable blocks for fields such as amount and date, and an Aggregation block for the total.

When to use

---

Use Template Builder when:

• operators need to create a Template without editing .tpl code;
• a Template Builder Template needs to be maintained visually;
• the report structure depends on fields, loops, conditions, or totals from a Data Source;
• the team wants to download the generated .tpl file after building it.

Use .tpl upload instead when a technical team already created and reviewed the Template outside the Console.

Before you start

---

Confirm:

• at least one relevant Data Source exists if the Template needs database fields. It can be an internal source already configured for the environment or an external source added from Data Sources;
• the Data Source was tested when connection health or schema visibility is uncertain, so its tables and fields are available in the sidebar;
• the expected output format is known: XML, HTML, CSV, TXT, or PDF;
• the operator knows the report structure, such as required header, rows, totals, or conditional sections.

Blocks define the output structure. Filters applied during Report generation define which records enter that structure.

Step by step

---

1. Open the builder

   Go to the Templates page and click Template Builder.

2. Name the Template

   Edit the Template name in the header. Use a name that operators can identify during report generation.

3. Choose the output format

   Select XML, HTML, CSV, TXT, or PDF.

   When PDF is selected, the generated template code uses HTML format and is converted to PDF during report generation.

4. Add blocks to the canvas

   Use the blocks toolbar to add structure. Common blocks are Text, Variable, Loop, Conditional, and Aggregation.

5. Connect fields from Data Sources

   Use the Data Sources sidebar to browse schemas, tables, and fields. Click a field to add a Variable block for that field.

6. Review generated code when needed

   Switch from Visual to Code to inspect the generated .tpl preview. The code view is for review and copy/download, not manual editing.

7. Save the Template

   Click Save. The builder validates required block fields, generates .tpl code, and saves the Template.

Field guide

---

Builder-level fields and controls

Field or control	What it does	Example
Template name	Required name in the builder header. It maps to name and becomes the saved Template label and generated .tpl filename prefix.	Monthly transaction CSV
Output format	Required format. Use xml, html, csv, txt, or pdf. When pdf is selected, code generation uses HTML internally.	pdf
Visual	Block editor mode for assembling the Template. Technical state: viewMode = visual.	Use while arranging blocks
Code	Read-only preview of generated .tpl code. Technical state: viewMode = code.	Review generated .tpl
Download .tpl file	Downloads the generated .tpl without saving a new Template.	monthly-transaction-csv.tpl
Save	Validates blocks, generates .tpl code, and uploads or updates the Template. Requires a nonblank name and at least one block.	Save after blocks are valid

Block field guide

Block	Fields to configure	Effect
Text	Content (content)	Renders fixed text such as CSV headers, XML tags, or HTML fragments.
Variable	Data Source, Table, Field, Index (optional), Filters (dataSource, table, field, index, filters[])	Inserts a field value. Inside a parent Loop, Data Source can be auto-filled from the loop iterator.
Loop	Iterator name and Iterable source (iteratorName, iterableSource)	Repeats child blocks over a collection. Use dataSource.table format for the iterable source.
Conditional	Condition and Include else block (condition, hasElse)	Renders child blocks only when the condition is true; optional else content can render when false.
Aggregation	Aggregation type, Source, Field, optional grouping/order/result fields (aggregationType, source, aggregationField)	Produces totals, counts, averages, min/max, or Last Item by Group values from a source collection.
Calculation	Expression (expression)	Renders a calculated value. Supported operators shown in the UI include +, -, *, /, **, and %.
Date/Time	Format and Date source (format, dateSource)	Formats a date value, for example YYYY-MM-DD from transaction.createdAt.
Counter	Mode, Counter name, and Counter names (counterMode, counterName, counterNames[])	Increment advances one counter. Display outputs one or more counters.
Comment	Comment (commentText)	Stores an internal Template note and does not appear in the final Report.
Section	Section title (sectionTitle)	Groups child blocks to organize larger Templates.
With (Assign)	Variable name and Assignment expression (variableName, assignment)	Creates a reusable variable from an expression for child blocks.
Expression	Expression (inlineExpression)	Renders an inline expression such as item.name|upper.
Custom Tag	Tag name and Tag arguments (tagName, tagArgs)	Emits an advanced Template tag such as include with arguments like "header.html" or key=value.

Block types

---

Block	What it represents in practice
Text	Fixed content that always appears in the output, such as a header or label.
Variable	A value from a data source field, such as document number, amount, or status.
Loop	A repeated section, such as one row for each transaction.
Conditional	Content that appears only when a rule is true, such as account.status == "active".
Aggregation	A total, count, average, min, max, or last item by group.
Calculation	A calculated value, such as value * 1.05.
Date/Time	A formatted date or time value.
Counter	A row number or sequence value.
Comment	Internal Template note that does not appear in the generated Report.
Section	A named group of blocks for organizing larger Templates.
With (Assign)	A reusable variable created from an expression.
Expression	An inline expression rendered into the output.
Custom Tag	A custom Template tag when advanced Template syntax is needed.

Working with blocks

---

• Click a block type in the toolbar to add it to the canvas.
• Drag blocks to reorder the output.
• Configure each block inline. For example, a Variable needs a source and field, while a Conditional needs a condition.
• Use Inline when the block should render without a line break after it.
• Use Trim whitespace to remove extra spaces around block output.
• Use Duplicate to copy a configured block.
• Use Delete to remove a block from the Template.

Container blocks such as Loop, Conditional, Section, and With can hold child blocks. Use them when the output needs repeated or grouped content.

Expected result

---

After saving, the Template appears on the Templates page and can be selected in the Generate Report wizard. You can also download the generated .tpl file from the builder.

Common errors and care points

---

No Data Sources appear in the sidebar

The sidebar only shows configured Data Sources. If the expected internal source is not listed, confirm setup with the Reporter administrator. If the report needs an external database, add and test that Data Source before using database fields in the Template.

Required block fields are missing

The builder validates blocks during save. If a block is missing a source, field, condition, or expression, fix that block before saving.

Using filters inside the wrong part of the workflow

Template blocks define the file structure. Report filters are selected later during report generation and decide which records enter the output.

Choosing PDF without understanding the generated code

PDF output is generated from HTML. Build the Template as HTML-compatible content when the final output format is PDF.

Next steps

---

• Use Generate a Report to test the Template with real filters.
• Use Update a Template to edit the Template later.
• Use Add a Template if you need to upload a prepared .tpl file instead.

API equivalent

There is no separate API endpoint for the visual builder. Use Upload template endpoint with a prepared .tpl file.