Using Reporter

Reporter assists Midaz Ledger users in creating dynamic, data-driven reports without SQL knowledge. You define domains, tables, and fields using simple placeholders rather than constructing complex queries.

Typical usage

Step 1 — Create the `.tpl` file

Write a template matching your desired output format (HTML, XML, CSV, or TXT). The template should incorporate Reporter blocks and follow the appropriate syntax for your output format. See Template examples for guidance.

The file must be saved with a .tpl extension. This is required for proper processing.

Step 2 — Upload the template

Once ready, upload the .tpl file using the Upload a Template endpoint. Set the outputFormat field to specify the report format. The system assigns a UUID filename (for example, 0196159b-4f26-7300-b3d9-f4f68a7c85f3.tpl). Template management endpoints:

List Templates — View organizational templates.
Retrieve Template details — Access specific template information.
Update a Template — Modify the .tpl file, description, or output format.
Delete a Template — Mark templates as deleted via deletedAt timestamp.

Step 3 — Generate the report

Use the Create a Report endpoint to initiate generation. Pass a templateId and optional filters in the request body:

{
  "templateId": "0196159b-4f26-7300-b3d9-f4f68a7c85f3",
  "filters": {
    "midaz_transaction": {
      "transaction": {
        "id": { "eq": ["0196d983-a2c2-7d5a-a5b7-029fe0dcb710"] }
      }
    }
  }
}

The API returns a reportId for tracking and retrieving the output.

Step 4 — Check the report status

The Check Report Status endpoint monitors progress, displaying whether the report is processing or finished.

Step 5 — Download the report

Once finished, download the report using the Download a Report endpoint. The file appears in the response body with proper Content-Disposition headers.

Mapping data sources for dynamic filters

Two supporting endpoints enable dynamic filtering:

List Data Sources — Lists available data sources with their schemas and tables.
Retrieve a Data Source by id — Returns the schema for a specific data source, including tables and fields.

These endpoints are optional and designed for advanced use cases, like building custom UIs or automating report workflows based on schema data.

Configuring storage

Reporter stores templates and generated reports in S3-compatible object storage. It supports AWS S3, MinIO, and SeaweedFS out of the box. All files are stored in a single bucket with internal prefixes:

templates/ — for uploaded template files
reports/ — for generated report files

Storage environment variables

Variable	Description	Default
`OBJECT_STORAGE_ENDPOINT`	S3-compatible endpoint URL. Leave empty for AWS S3.	—
`OBJECT_STORAGE_REGION`	AWS region	`us-east-1`
`OBJECT_STORAGE_ACCESS_KEY_ID`	Access key for authentication	—
`OBJECT_STORAGE_SECRET_KEY`	Secret key for authentication	—
`OBJECT_STORAGE_USE_PATH_STYLE`	Use path-style URLs. Required for MinIO and SeaweedFS.	`false`
`OBJECT_STORAGE_DISABLE_SSL`	Disable SSL verification. Use for local development only.	`false`
`OBJECT_STORAGE_BUCKET`	Bucket name	`reporter-storage`

Configuration examples by provider

AWS S3

OBJECT_STORAGE_ENDPOINT=
OBJECT_STORAGE_REGION=us-west-2
OBJECT_STORAGE_ACCESS_KEY_ID=AKIA...
OBJECT_STORAGE_SECRET_KEY=your-secret-key
OBJECT_STORAGE_USE_PATH_STYLE=false
OBJECT_STORAGE_DISABLE_SSL=false
OBJECT_STORAGE_BUCKET=reporter-prod-bucket

MinIO

OBJECT_STORAGE_ENDPOINT=http://minio:9000
OBJECT_STORAGE_REGION=us-east-1
OBJECT_STORAGE_ACCESS_KEY_ID=minioadmin
OBJECT_STORAGE_SECRET_KEY=minioadmin
OBJECT_STORAGE_USE_PATH_STYLE=true
OBJECT_STORAGE_DISABLE_SSL=true
OBJECT_STORAGE_BUCKET=reporter-storage

SeaweedFS (local development)

OBJECT_STORAGE_ENDPOINT=http://reporter-seaweedfs:8333
OBJECT_STORAGE_REGION=us-east-1
OBJECT_STORAGE_ACCESS_KEY_ID=any
OBJECT_STORAGE_SECRET_KEY=any
OBJECT_STORAGE_USE_PATH_STYLE=true
OBJECT_STORAGE_DISABLE_SSL=true
OBJECT_STORAGE_BUCKET=reporter-storage

S3 does not support per-object TTL. To automatically expire generated reports, configure S3 bucket lifecycle policies on your bucket.

Configuring external data sources

Reporter connects to external databases (PostgreSQL and MongoDB) as data sources for your templates. Each data source is configured through environment variables following the pattern DATASOURCE_<NAME>_*.

Data source environment variables

Variable	Description	Required
`DATASOURCE_<NAME>_CONFIG_NAME`	Unique identifier used in templates (for example, `midaz_onboarding`)	Yes
`DATASOURCE_<NAME>_HOST`	Database host	Yes
`DATASOURCE_<NAME>_PORT`	Database port	Yes
`DATASOURCE_<NAME>_USER`	Database user	Yes
`DATASOURCE_<NAME>_PASSWORD`	Database password	Yes
`DATASOURCE_<NAME>_DATABASE`	Database name	Yes
`DATASOURCE_<NAME>_TYPE`	Database type: `postgresql` or `mongodb`	Yes
`DATASOURCE_<NAME>_SSLMODE`	SSL mode for PostgreSQL (`disable`, `require`)	PostgreSQL only
`DATASOURCE_<NAME>_SSLROOTCERT`	SSL root certificate path for PostgreSQL	PostgreSQL only
`DATASOURCE_<NAME>_SSL`	Enable SSL for MongoDB (`true` or `false`)	MongoDB only
`DATASOURCE_<NAME>_SSLCA`	CA certificate file path for MongoDB	MongoDB only
`DATASOURCE_<NAME>_OPTIONS`	Additional URI options for MongoDB	MongoDB only
`DATASOURCE_<NAME>_SCHEMAS`	Comma-separated list of schemas to expose	PostgreSQL only

Single data source example

DATASOURCE_ONBOARDING_CONFIG_NAME=midaz_onboarding
DATASOURCE_ONBOARDING_HOST=midaz-postgres-replica
DATASOURCE_ONBOARDING_PORT=5702
DATASOURCE_ONBOARDING_USER=midaz
DATASOURCE_ONBOARDING_PASSWORD=lerian
DATASOURCE_ONBOARDING_DATABASE=onboarding
DATASOURCE_ONBOARDING_TYPE=postgresql
DATASOURCE_ONBOARDING_SSLMODE=disable

In templates, you reference this data source as midaz_onboarding:

{% for account in midaz_onboarding.account %}
  {{ account.id }} - {{ account.name }}
{% endfor %}

Multi-schema data source

To query tables across multiple PostgreSQL schemas, set the DATASOURCE_<NAME>_SCHEMAS variable with a comma-separated list:

DATASOURCE_EXTERNAL_CONFIG_NAME=external_db
DATASOURCE_EXTERNAL_HOST=external-postgres
DATASOURCE_EXTERNAL_PORT=5432
DATASOURCE_EXTERNAL_USER=db_user
DATASOURCE_EXTERNAL_PASSWORD=db_password
DATASOURCE_EXTERNAL_DATABASE=external_database
DATASOURCE_EXTERNAL_TYPE=postgresql
DATASOURCE_EXTERNAL_SSLMODE=disable
DATASOURCE_EXTERNAL_SCHEMAS=sales,inventory,reporting

In templates, use the explicit schema syntax database:schema.table:

{% for order in external_db:sales.orders %}
  {{ order.id }} - {{ order.total }}

  {% for item in external_db:inventory.items|where:"order_id:{{ order.id }}" %}
    Item: {{ item.name }} ({{ item.quantity }} in stock)
  {% endfor %}
{% endfor %}

When generating a report with filters, use schema.table as the table key:

{
  "templateId": "00000000-0000-0000-0000-000000000000",
  "filters": {
    "external_db": {
      "sales.orders": {
        "created_at": { "gte": ["2025-01-01"] }
      }
    }
  }
}

When DATASOURCE_<NAME>_SCHEMAS is not set, Reporter defaults to the public schema only.

Connection behavior

Reporter uses two initialization strategies:

Manager component (lazy): Loads configuration without connecting. Connects on-demand when a template references the data source. This provides faster startup.
Worker component (eager): Attempts connection on startup with exponential backoff retry (up to 5 retries). Continues with degraded functionality if a data source is unavailable.

Complete environment variables reference

Application

Variable	Description	Default
`ENV_NAME`	Environment name	`development`
`LOG_LEVEL`	Log level (`debug`, `info`, `warn`, `error`)	`debug`
`SERVER_PORT`	Manager HTTP port	`4005`
`SERVER_ADDRESS`	Manager bind address	`:4005`

Object storage (S3-compatible)

Variable	Description	Default
`OBJECT_STORAGE_ENDPOINT`	S3 endpoint URL	—
`OBJECT_STORAGE_REGION`	AWS region	`us-east-1`
`OBJECT_STORAGE_ACCESS_KEY_ID`	Access key	—
`OBJECT_STORAGE_SECRET_KEY`	Secret key	—
`OBJECT_STORAGE_USE_PATH_STYLE`	Path-style URLs	`false`
`OBJECT_STORAGE_DISABLE_SSL`	Disable SSL	`false`
`OBJECT_STORAGE_BUCKET`	Bucket name	`reporter-storage`

MongoDB

Variable	Description	Default
`MONGO_URI`	URI scheme (`mongodb` or `mongodb+srv`)	—
`MONGO_HOST`	MongoDB host	—
`MONGO_NAME`	Database name	—
`MONGO_USER`	Database user	—
`MONGO_PASSWORD`	Database password	—
`MONGO_PORT`	Database port	—
`MONGO_MAX_POOL_SIZE`	Connection pool size	`1000`
`MONGO_PARAMETERS`	Additional URI parameters	—

RabbitMQ

Variable	Description	Default
`RABBITMQ_URI`	URI scheme (`amqp`)	—
`RABBITMQ_HOST`	RabbitMQ host	—
`RABBITMQ_PORT_AMQP`	AMQP port	—
`RABBITMQ_PORT_HOST`	Management port	—
`RABBITMQ_DEFAULT_USER`	User	—
`RABBITMQ_DEFAULT_PASS`	Password	—
`RABBITMQ_GENERATE_REPORT_QUEUE`	Queue name for report generation	—
`RABBITMQ_NUMBERS_OF_WORKERS`	Number of consumer workers (worker only)	`5`

Redis / Valkey

Variable	Description	Default
`REDIS_HOST`	Redis host with port (for example, `host:6379`)	—
`REDIS_PASSWORD`	Redis password	—
`REDIS_DB`	Database number	`0`
`REDIS_PROTOCOL`	Redis protocol version	`3`
`REDIS_MASTER_NAME`	Sentinel master name (if using Sentinel)	—
`REDIS_TLS`	Enable TLS	`false`

PDF generation (worker only)

Variable	Description	Default
`PDF_POOL_WORKERS`	Number of parallel PDF generation workers	`2`
`PDF_TIMEOUT_SECONDS`	Timeout per PDF generation in seconds	`90`

Telemetry (OpenTelemetry)

Variable	Description	Default
`OTEL_RESOURCE_SERVICE_NAME`	Service name for traces	—
`OTEL_LIBRARY_NAME`	Instrumentation library name	—
`OTEL_RESOURCE_SERVICE_VERSION`	Service version	—
`OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT`	Deployment environment	—
`OTEL_EXPORTER_OTLP_ENDPOINT`	OTLP exporter endpoint	—
`ENABLE_TELEMETRY`	Enable telemetry collection	`false`

Authentication

Variable	Description	Default
`PLUGIN_AUTH_ADDRESS`	Auth service URL	—
`PLUGIN_AUTH_ENABLED`	Enable authentication	`false`

License

Variable	Description	Default
`LICENSE_KEY`	License key for Reporter	—
`ORGANIZATION_IDS`	Organization IDs for license validation	—

Introduction

Template examples

Brazilian templates

Using Reporter

Typical usage

Step 1 — Create the `.tpl` file

Step 2 — Upload the template

Step 3 — Generate the report

Step 4 — Check the report status

Step 5 — Download the report

Mapping data sources for dynamic filters

Configuring storage

Storage environment variables

Configuration examples by provider

Configuring external data sources

Data source environment variables

Single data source example

Multi-schema data source

Connection behavior

Complete environment variables reference

Application

Object storage (S3-compatible)

MongoDB

RabbitMQ

Redis / Valkey

PDF generation (worker only)

Telemetry (OpenTelemetry)

Authentication

License

Introduction

Template examples

Brazilian templates

​Typical usage

​Step 1 — Create the .tpl file

​Step 2 — Upload the template

​Step 3 — Generate the report

​Step 4 — Check the report status

​Step 5 — Download the report

​Mapping data sources for dynamic filters

​Configuring storage

​Storage environment variables

​Configuration examples by provider

​Configuring external data sources

​Data source environment variables

​Single data source example

​Multi-schema data source

​Connection behavior

​Complete environment variables reference

​Application

​Object storage (S3-compatible)

​MongoDB

​RabbitMQ

​Redis / Valkey

​PDF generation (worker only)

​Telemetry (OpenTelemetry)

​Authentication

​License

Typical usage

Step 1 — Create the `.tpl` file

Step 2 — Upload the template

Step 3 — Generate the report

Step 4 — Check the report status

Step 5 — Download the report

Mapping data sources for dynamic filters

Configuring storage

Storage environment variables

Configuration examples by provider

Configuring external data sources

Data source environment variables

Single data source example

Multi-schema data source

Connection behavior

Complete environment variables reference

Application

Object storage (S3-compatible)

MongoDB

RabbitMQ

Redis / Valkey

PDF generation (worker only)

Telemetry (OpenTelemetry)

Authentication

License