> ## 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.
# Getting started with Reporter
> Walk through the four-stage reporting lifecycle in Reporter — from designing a template to downloading a finished regulatory or business report.
This guide walks through the reporting lifecycle in Reporter, from uploading your first template to downloading a finished report. It focuses on the concepts and decisions involved at each stage.
For step-by-step API instructions with request and response examples, see the [Reporter API quick start](/en/reference/reporter/reporter-developer-quick-start).
## The reporting lifecycle
***
Every report in Reporter follows the same four-stage lifecycle:
Write a `.tpl` file that defines the structure and content of your report.
Register the template with Reporter so it can be reused across report runs.
Submit a request with optional filters to produce a report from the template.
Retrieve the finished file in the format you need.
The sections below explain each stage.
## Design a template
***
A **template** is a plain-text file with a `.tpl` extension that defines how your report looks and what data it includes. Templates mirror the structure of the final output — if you want an XML report, you write XML inside the `.tpl` file; if you want HTML, you write HTML.
Instead of writing SQL queries, you reference data through **placeholders** that follow a simple path syntax:
```
{{ datasource.table.field }}
```
For example, `{{ midaz_onboarding.account.name }}` pulls the account name from the Midaz onboarding database.
### What you can do in templates
| Capability | Description |
| ---------------- | ----------------------------------------------------------------------------- |
| **Loops** | Iterate over collections of records |
| **Conditions** | Show or hide content based on data values |
| **Aggregations** | Calculate sums, averages, counts, min, and max |
| **Arithmetic** | Perform calculations on numeric fields |
| **Filters** | Transform values inline (format numbers, replace strings, extract substrings) |
| **Counters** | Track and display running totals across iterations |
### Supported output formats
| Template content | Output format |
| ---------------------- | ---------------- |
| CSV-structured `.tpl` | CSV file |
| XML-structured `.tpl` | XML file |
| HTML-structured `.tpl` | HTML or PDF file |
| TXT-structured `.tpl` | TXT file |
See [Template formats](/en/reporter/template-examples) for complete examples of each format.
## Upload the template
***
Once your `.tpl` file is ready, upload it to Reporter. During upload, you specify:
* **The template file** — your `.tpl` file
* **Output format** — the format Reporter should generate (CSV, XML, HTML, PDF, or TXT)
* **Description** — an optional label to help identify the template later
Reporter stores the template in S3-compatible object storage and assigns it a unique ID. You can then list, update, or delete templates as your reporting needs evolve.
Templates are reusable. Upload once, generate reports from the same template as many times as needed with different filters.
API reference: [Upload template](/en/reference/reporter/upload-template) | [List templates](/en/reference/reporter/list-templates)
## Generate a report
***
To generate a report, submit a request with the template ID and optional **filters** that narrow the data.
### How filters work
Filters follow a structured path: **data source > table > field**. You can filter by equality, ranges, greater/less than, and list membership.
For example, to generate a report for a specific date range and account status:
| Filter | What it does |
| ------------------------------------------------- | --------------------------------------- |
| `createdAt: between ["2024-01-01", "2024-01-31"]` | Only include records from January 2024 |
| `status: in ["active", "pending"]` | Only include active or pending accounts |
| `id: eq ["123", "456"]` | Only include specific account IDs |
### Supported filter operators
| Operator | Description |
| ------------ | ------------------------------------ |
| `eq` | Equal to |
| `gt` / `gte` | Greater than / greater than or equal |
| `lt` / `lte` | Less than / less than or equal |
| `between` | Value falls within a range |
| `in` / `nin` | Value is / is not in a list |
### Processing
Report generation is **asynchronous**. After submitting a request, Reporter returns a report ID that you use to check progress. Reports move through these statuses:
| Status | Meaning |
| ------------------- | --------------------------------------------------------------------------------- |
| `PendingExtraction` | The report is waiting for data extraction to complete before generation can begin |
| `Processing` | Reporter is querying data and rendering the template |
| `Finished` | The report is ready for download |
API reference: [Create report](/en/reference/reporter/create-report) | [Check report status](/en/reference/reporter/check-report-status)
## Download the output
***
Once a report reaches `Finished` status, download it. The file is returned in the format specified during template upload — CSV, XML, HTML, PDF, or TXT.
API reference: [Download report](/en/reference/reporter/download-report)
## Data sources
***
Reporter connects to your databases and pulls data based on what your templates reference. It supports:
| Database | Use case |
| -------------- | -------------------------------------------------------- |
| **PostgreSQL** | Relational data — accounts, transactions, ledger entries |
| **MongoDB** | Document data — metadata, flexible schemas |
Data sources are configured at the infrastructure level through environment variables. Once configured, they become available to all templates through their assigned name (for example, `midaz_onboarding` or `midaz_transaction`).
### Multi-schema support
For PostgreSQL databases with multiple schemas, templates can query across schemas using explicit syntax:
```
{{ datasource:schema.table.field }}
```
This is useful when your data spans schemas like `sales`, `inventory`, and `reporting` within a single database.
API reference: [List data sources](/en/reference/reporter/list-data-sources) | [Retrieve data source](/en/reference/reporter/retrieve-data-source)
## Example scenario
***
A fintech company needs to generate a daily account summary for its operations team.
**Setup:**
* A template designer writes an HTML template with account balances, transaction counts, and daily totals using Reporter's aggregation tags
* The template is uploaded once with output format set to PDF
**Daily workflow:**
1. An automated job submits a report request with a date filter for the current day.
2. Reporter queries the Midaz database, applies the template logic, and renders the output.
3. The report reaches `Finished` status within seconds.
4. The operations team downloads the PDF and reviews the daily summary.
5. The same template is reused every day — only the date filter changes.
## Brazilian regulatory reporting
***
Reporter includes ready-to-use templates for Brazilian Central Bank (BACEN) regulatory reports:
| Template | Purpose |
| --------------------- | ----------------------------------------- |
| **CADOC 4010 / 4016** | Trial balance and balance sheet reporting |
| **CADOC 4111** | Detailed transaction reporting |
| **CCS** | Customer and account registry reporting |
These templates follow the official BACEN structure and can be customized to match your institution's chart of accounts.
See [BACEN templates](/en/reporter/reporter-bacen-templates) for details on each regulatory template.
## Next steps
***
Full overview of Reporter's architecture and capabilities.
Practical examples for HTML, XML, and TXT templates.
End-to-end guide for generating trial balances with Midaz and Reporter.
Ready-to-use templates for Brazilian regulatory reporting.