> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Add a Template

> Create a Template in Reporter using Template Builder or by uploading a prepared .tpl file.

Use this page to create the Template that Reporter will use to generate a Report. A Template is the reusable structure of the output file: it defines the layout, fields, conditions, loops, calculations, and final format.

## Objective

***

Add a Template that operators can select when generating Reports.

For example, a monthly tax Template can define a CSV header, one row per transaction, and a total amount at the end of the file. A regulatory XML Template can define the required XML tags and fill them with values from a Data Source.

## When to use

***

Use this task when:

* you are setting up the first Template for a report whose Data Source already exists;
* a new report obligation requires a new output structure;
* your team already has a reviewed `.tpl` file and needs to make it available in the Console;
* an operator needs to build the Template visually instead of editing `.tpl` code.

Do not use this task to fix a Template that already exists. Use [Update a Template](/en/lerian-console/reporter-console/updating-a-template) instead.

## Before you start

***

Confirm:

* the Data Source that will feed the Template is available when the Template needs database fields. It may be an internal source already configured for the environment or an external source added from **Data Sources**;
* the expected output format is known: CSV, XML, HTML, TXT, or PDF;
* the Template will be created in **Template Builder** or uploaded as a `.tpl` file;
* the report owner has confirmed the fields that must appear in the output.

<Note>
  A Template is not a generated Report. It is the reusable definition that Reporter applies later during report generation.
</Note>

## Option 1: Build in Template Builder

***

Use Template Builder when an operator needs to assemble the Template visually from blocks.

<Steps>
  <Step title="Open Template Builder">
    Go to the **Templates** page and click **Template Builder**.
  </Step>

  <Step title="Name the Template">
    Use a name operators can recognize later, such as `Monthly tax CSV` or `Daily transaction PDF`.
  </Step>

  <Step title="Choose the output format">
    Select the format that the generated Report must produce: XML, HTML, CSV, TXT, or PDF.
  </Step>

  <Step title="Add the Template blocks">
    Add blocks such as **Text**, **Variable**, **Loop**, **Conditional**, or **Aggregation**. In practice, blocks represent the pieces of the final file: fixed text, database values, repeated rows, conditional sections, or totals.
  </Step>

  <Step title="Connect fields to data">
    Use the Data Sources sidebar to select fields from the configured database connection. For example, use a **Variable** block to place `transactions.amount` in the output.
  </Step>

  <Step title="Save the Template">
    Click **Save** to validate the blocks and save the generated `.tpl` file.
  </Step>
</Steps>

## Option 2: Upload a `.tpl` file

***

Use upload when a technical team already maintains the Template outside the Console.

<Steps>
  <Step title="Open the upload wizard">
    Go to the **Templates** page and click **New Template**.
  </Step>

  <Step title="Upload the file">
    In the **File** step, drag the `.tpl` file to **Drag file here**, or click **to select** to browse your computer.
  </Step>

  <Step title="Configure the Template">
    In the **Config** step, fill in **Template Name** and **Output Format**.
  </Step>

  <Step title="Review the summary">
    In the **Review** step, confirm the file, name, and output format. Use the edit buttons if any field is wrong.
  </Step>

  <Step title="Save the Template">
    Click **Save Template**.
  </Step>
</Steps>

<Tip>
  **API equivalent**: [Upload template endpoint](/en/reference/reporter/upload-template)
</Tip>

## Field guide

***

### Upload wizard fields

| Field                    | What to enter                                                                                                                    | Example           |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
| **Template File (.tpl)** | Required `.tpl` file used as the Template source. It must be larger than 0 bytes and no larger than 5 MB. API field: `template`. | `monthly-tax.tpl` |
| **Template Name**        | Required operator-facing name. It maps to `name` in the Console and to `description` in the Reporter API.                        | `Monthly tax CSV` |
| **Output Format**        | Required output type. Use one of `csv`, `xml`, `html`, `txt`, or `pdf`.                                                          | `csv`             |

### Template Builder fields

| Field                | What to enter                                                                                                                       | Example                                                              |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| **Template name**    | Required name in the builder header. It becomes the saved Template name and generated `.tpl` filename prefix.                       | `Daily transaction PDF`                                              |
| Block toolbar        | Add at least one block before saving. Blocks become the generated `.tpl` code.                                                      | **Text** header + **Loop** over transactions + **Aggregation** total |
| Data Sources sidebar | Use configured Data Sources to insert fields into **Variable** blocks. Technical fields include `dataSource`, `table`, and `field`. | `production-postgres.transactions.amount`                            |

## Expected result

***

After saving, the Template appears on the **Templates** page and can be selected in the **Generate Report** wizard.

## Common errors and care points

***

<AccordionGroup>
  <Accordion title="Uploading a file that is not `.tpl`">
    Upload only accepts `.tpl` files. If the Template is still being designed, use **Template Builder** first or prepare the `.tpl` file outside the Console.
  </Accordion>

  <Accordion title="Choosing the wrong output format">
    The output format controls what kind of file operators will download after generating a Report. Confirm the required format before saving.
  </Accordion>

  <Accordion title="Creating a Template before the Data Source is ready">
    Templates can reference fields from Data Sources. If the required source is missing or untested, operators may not know which fields are safe to use.
  </Accordion>
</AccordionGroup>

## Next steps

***

* Use [Generate a Report](/en/lerian-console/reporter-console/generating-a-report) to create a Report from the Template.
* Use [Update a Template](/en/lerian-console/reporter-console/updating-a-template) if the structure, file, name, or output format needs correction.
* Use [Template Builder](/en/lerian-console/reporter-console/template-builder) when operators need to maintain the Template visually.