Guides

Using Smart Templates

Suggest Edits

The Smart Template plugin helps Midaz Ledger users create dynamic, data-driven reports without writing SQL. Instead of building complex queries, you define domains, tables, and fields using simple placeholders.


Typical usage

Here’s how the workflow goes from start to finish:

Step 1 – Create the .tpl file

Write your template using the structure that matches your desired output — HTML, XML, CSV, or TXT.
For example, if your goal is an XML report, the file should follow XML syntax and include Smart Template blocks.

🚧

Attention

Regardless of the format, the file must be saved with a .tpl extension. This is required for proper processing.


Step 2 – Upload the template

Once your .tpl file is ready, upload it using the Upload a Template endpoint.

  • Set the outputFormat field to define the expected report format.
  • The system automatically names the file using a UUID: 0196159b-4f26-7300-b3d9-f4f68a7c85f3.tpl.
Managing templates

You can manage your templates with the following endpoints:

  • List Templates – View all templates in your organization.
  • Retrieve Template details – Access the information for a specific template.
  • Update a Template – Replace the .tpl file, edit the description, or change the output format.
  • Delete a Template – Marks a template as deleted by setting the deletedAt timestamp. The data remains stored, but won’t appear in standard queries.

Step 3 – Generate the report

With your template uploaded, use the Create a Report endpoint to trigger report generation.

  • The API returns a reportId that you can use to track the process and fetch the final output when it’s ready.

Step 4 – Check the report status

Use the Check Report Status endpoint to monitor progress.

  • You’ll see whether the report is processing or finished.
  • Additional context may be included to help troubleshoot or confirm completion.

Step 5 – Download the report

Once the report status is finished, download the file using the Download a Report endpoint.

  • The file is returned in the response body.
  • The Content-Disposition header sets the correct filename and format to support a smooth download experience.

Updated 4 days ago