Then six months later someone asks for a small change. Add a line to the totals, move the delivery address, change the wording of the overdue notice. You open the template and it looks like this:

That's an invoice. It works, and it renders the invoice further down this post. But look at what it asks of the person editing it:

• The total is worked out in full three times: in the overdue notice, in the totals table and in the payment line. If you want to change how it's calculated you have to find and change all three, the same way.
• The tags are styled to look like their output, so the overdue line is one long run of red bold tags. Click in the wrong place and you risk splitting the formatting, or the tag.
• The billing and delivery addresses are the same three lines with different paths.
• The page doesn't look like an invoice. A tag is rarely as wide as the value it becomes, so the line breaks and column widths you see aren't the ones you'll get in the finished document.

None of this is unusual. Any system that puts logic into a Word, Excel or PowerPoint file has the same problem, and my own early ETCH templates looked just like this. The good news is that most of it can be avoided, and over the last year a lot of what I've added to ETCH has been about exactly that. Here's the same invoice rebuilt:

Both templates render the same invoice from the same data:

But I know which template I'd rather maintain.

These are the ten things that made the difference.

1. Put the tags in comments

Instead of typing {{customer.name}} into the page, you can type a realistic placeholder value, "Sample Customer Ltd", select it, and add a Word comment holding the tag. When ETCH renders the template, the selected text is replaced by the value, the value keeps the sample's formatting, and the comment is removed.

The template now looks much more like the document it would produce, so the layout you see is the layout you get. Anyone can read it, including people who've never seen a tag. And the formatting is applied to ordinary text, so it looks more natural.

It works on more than a word or two. A comment on a whole table row holding {{#each lines}} repeats the row once for each line, and comments on the cells inside it say what goes in each cell. A comment on a paragraph holding {{#if invoice.overdue}} shows or hides the whole paragraph.

Excel works the same way, with a comment or a note on a cell, and so does PowerPoint, on text, pictures, charts and tables etc. Typed tags still work, and the two mix freely. In this invoice I've typed the short ones and used comments where the sample text matters.

2. Calculate it once with {{#var}}

The "before" template calculates the total three times. With {{#var}} it's calculated once, at the top, and each variable can build on the ones before it:

{{#var subtotal (sum lines "amount")}}{{#var vat $subtotal * vat_rate}}{{#var total $subtotal + $vat}}

Everywhere else the total is just specified as {{$total | currency "£"}}. If the calculation changes, there's one place to change it, and the tags that use it are short enough to read.

One thing to know: a variable is worked out once, where you define it. If you need a different value on every row of a table, you can define it inside the loop.

3. Write it once with {{#define}}

The billing and delivery addresses are the same shape in the JSON, so they're defined once, as a snippet with a parameter:

{{#define address(a)}}
{{a.line1}}
{{a.city}} {{a.postcode}}
{{/define}}

Each address in the invoice is then one short tag, {{> address(customer.billing)}} and {{> address(customer.delivery)}}. The definition doesn't appear in the output.

You can even apply formatting and styling to the {{#define}}...{{/define}} block and it will be retained in the output!

4. Shorter paths with {{#with}}

Long paths make every tag longer than it needs to be. {{#with}} sets where the paths start for a block, so the line under the invoice's title reads:

{{#with invoice}}Invoice {{number}} · Issued {{date | date "D MMMM YYYY"}} · Due {{due | date "D MMMM YYYY"}}{{/with}}

so instead of having to use {{invoice.number}} and {{invoice.due}} we can use the {{#with invoice}} and now when we reference {{number}} and {{due}} ETCH knows we are referencing the invoice element. You can also use {{#root <object>}} at the document level too if you want to just use a deeply nested object of your JSON

5. Define a style with {{#format}}

When a tag has to be typed into running text, it's tempting to style the tag itself to match the output, which is how the red bold tags in the "before" template were done. {{#format}} lets you style a sample once and give it a name:

{{#format money}}£0.00{{/format}}

That definition is bold in the template, and the format tag itself is removed from the output. Then {{$total | currency "£" | format money}} anywhere in the document comes out bold.

This lets you define styles once in your template and reuse them while maintaining a central place for any changes.

6. Pictures and charts: lay them out, and bind them with Alt Text

A picture that comes from your data, like the QR code on the invoice, doesn't need a tag on the page at all. Insert any placeholder picture, size and position it where you want it, and put the tag in its Alt Text:

{{#qr invoice.pay_url}}QR code to pay invoice {{invoice.number}} online

ETCH swaps the picture and keeps the size, position and crop you gave it. The text after the tag becomes the picture's real Alt Text in the output, so the document is accessible as well.

Charts work the same way. Draw and style a chart in PowerPoint (or Word) with dummy data, and put {{#chart regions x="region" y="sales"}} in its Alt Text. ETCH replaces the chart's data and leaves its design exactly how you designed it. In Excel the same tag writes the rows into the chart's source cells, so the chart stays linked to cells you can still see and edit.

7. Leave a note to your future self with {{!-- --}}

The most useful thing in a template six months later is a note from whoever built it. A template comment, {{! … }} or {{!-- … --}} for a multiline longer one, is removed from the output and nothing inside it is evaluated:

{{!-- Totals are worked out once, in the variables after this note. Addresses use the address snippet. --}}

The long form is the one to use when the note itself mentions a tag, as in {{!-- see {{customer.name}} --}}, because the short form ends at the first }}.

8. Exclude a whole section with {{#exclude}}

For more than a line, {{#exclude}} hides everything up to {{#include}}, or to the end of the document if there isn't an {{#include}} tag. I use it for a "notes for whoever edits this next" section at the end of the template, with a worked example or a list of the fields the data has.

In Excel it does something much more interesting: {{#exclude}} anywhere on a worksheet leaves that whole sheet out of the workbook. So the notes can live on their own sheet, next to the sheet they describe.

9. Check it before you save it with etch validate

Editing a template you didn't write, or don't remember writing, is exactly when a typo can sneak in. The etch validate CLI command checks a Word, Excel or PowerPoint template for split tags, blocks that don't close, and, given some sample data, paths that aren't in the data:

10. Live reload the results as you edit the template

This is one of my favourites.

The etch watch CLI command live reloads a rendered copy of the template output and re-renders it again every time you save:

etch watch -t invoice-after.docx -d invoice.json

It runs the same validation first, and when there's an error the preview opens as your template with a comment on the error. With comments in the template, it's where you check that the layout you designed around the sample values still looks right with the real data.

The ETCH add-in for Office also does a similar job. It shows the fields in your data and lets you easily insert tags and data elements, then validates the template and previews the value each tag will get. There's a five-minute video of it.

It's still a template

None of this makes a complicated document simple. An invoice with three kinds of discount and a different layout for every country will have a complicated template, whatever you build it with. What these features do is put the complexity somewhere you can find it: calculations at the top, repeated blocks in one place, notes next to the things they explain, and a page that looks like the document it generates.

etch validate and etch watch come with the ETCH CLI, which is on the Professional plan. The add-in inserts, validates and previews on any plan, and generating from it needs Standard. The tags themselves work whichever way you call ETCH: from APEX, Python, JavaScript, Go, Java or the CLI.

If you build document templates, in ETCH or anything else, I'd like to know what makes yours difficult to come back to. Leave a comment and let me know!

I've heard that so many times and it's a big part of why I built ETCH. There are of course some other solutions to the problem, but ETCH tries to bridge the gap between simplicity and ultimate flexibility in some unique ways which I'll cover in more detail in later posts.

This post covers installing ETCH into APEX from scratch. I created a new workspace and schema for it, with a small Orders application, so every step here is from a working installation. By the end, the Orders report has a Download report entry in its Actions menu that turns the report, as the user has filtered it, into a Word document.

Before you start

You need three things (sign up for a free ETCH account to test it out):

• The release zip for your APEX version, from the downloads area on get-etch.app once you're signed in. There's one zip per APEX version, because plugin exports only import into the version they were built for: take the highest one at or below yours. I'm on APEX 26.1, I'm using etch-apex-client-26.1-v26.10.17.3.zip.
• An API key, from the API keys page of the same dashboard.
• SQLcl (or SQL*Plus), and potentially a DBA for one step if your network ACLs need configured

The free plan includes the APEX plugin, so you can do all this to test it out yourself.

Unzip the release into a folder.

1. The DBA check (optional if ACLs are already configured)

ETCH calls the ETCH server from the database, so the parsing schema needs a network ACL for api.get-etch.app. The zip has a script that checks that, and the grants, for a schema you name. It doesn't change anything: it prints the SQL for whatever's missing. Your DBA runs it as SYS or another DBA account, before or after the install:

@etch_dba_setup.sql DEMO

![SQLcl running @etch_dba_setup.sql DEMO: APEX schema APEX_260100 found; ETCH not installed in DEMO yet; the grants CREATE SESSION, TABLE, PROCEDURE, SEQUENCE and the quota all OK; under Network ACL, a [MISS] for DEMO followed by a ready-to-run DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE block, and OK for the APEX schema; "1 issue(s) found".](https://cdn.hashnode.com/uploads/covers/6ab92eb45048a85288a71c45/addb9d28-11a9-4f35-b8e8-25f5613978d7.gif align="center")

The only thing missing for my new schema was the ACL. The DBA runs the block it printed, which for me was:

BEGIN
  DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
    host => 'api.get-etch.app',
    ace  => xs$ace_type(
      privilege_list => xs$name_list('connect', 'resolve'),
      principal_name => 'DEMO',
      principal_type => xs_acl.ptype_db));
END;
/

Your output may list more, such as a grant, or the ACL for the APEX schema itself. Run what yours prints.

2. Install the packages

Connect as the APEX parsing schema and run the install script:

@install.sql

It creates a small ETCH_LOG table and compiles four packages. It's safe to run again when you upgrade.

3. Check it can reach the ETCH Server

@preflight.sql

Everything passes. The one warning is about the API key (you don't need to worry about it, it's only if you want enhanced debugging).

4. Configure the API key in a Web Credential (Recommended)

You could paste the key into the plugin's settings, but then it's stored in the application and would be included with every export of it. A Web Credential keeps it secure, and APEX can be configured to only send it to the URLs you allow.

In Shared Components, open Credentials (it takes you to Workspace Utilities > Web Credentials) and create one:

5. Import the plugins

The zip's plugins folder has three files. Import each one in Shared Components > Plug-ins > Import, with File Type set to Plug-in:

• dynamic_action_plugin_etch_dynamic_action_plugin.sql,
• process_type_plugin_etch_process_plugin.sql,
• dynamic_action_plugin_etch_helper_plugin.sql

Which Plugin you use depends on your exact requirements, the Dynamic Action plugin is suitable for 99% of user interaction related processing, the Process Type plugin can be used whenever the Dynamic Action plugin isn't suitable (you will almost always want to also use the ETCH Helper Plugin whenever you use the Process type plugin, it's not required for the Dynamic Action plugin). We'll cover this in a later post.

After the dynamic action plugin imports, APEX opens its Component Settings. Leave ETCH Server URL as https://api.get-etch.app, leave API Key empty, and put the credential's Static ID, etch_api_key, in API Key Web Credential. Do the same for the process plugin, because each plugin keeps its own component level settings. The helper plugin has nothing to set.

6. Create your first template

The template is an ordinary Word document (but it could be Excel or PowerPoint). Mine has a heading, a line that says when it was printed, and one tag that stands for the whole report:

{{#apex_region "rgnOrders"}} is replaced by the Interactive Report with that HTML DOM ID, with the user's columns, filters, highlights and sort, as they're set on screen at the time. I uploaded the file to Shared Components > Static Application Files:

7. The dynamic action

The plugin finds the report by its HTML DOM ID (or Static ID in versions of APEX prior to 26.1), so in Page Designer I gave the Orders region one, under Advanced:

Then a dynamic action on Page Load, with one True action of type ETCH Dynamic Action Plugin. With Generate on trigger unticked, Page Load itself makes no document: the action just puts its entry in the report's Actions menu when the page renders, and the document is made when someone picks it. These are its settings:

• Template: Application Static File, orders-report.docx.
• Data: Region(s), with rgnOrders as the Region Static ID. Rows to Export is Selected Rows, else All: if the user has ticked rows, only those go in. That needs the report's row selector, which this report has.
• Output: Word, downloaded, named orders-{{etch.date:YYYYMMDD}}-{{etch.user}}, so the file name carries the date and who made it.
• Report Menu: Actions Menu ticked, Generate on trigger unticked, and the label Download report.

Save the page, and that's the setup done.

Run it

On the running page I filtered out the delivered orders, left the Overdue highlight on, ticked three rows, and chose Actions > Download report (the first screenshot in this post). Word opened this:

The photos came from a BLOB column in the products table. The column headings, the filter and highlight lines, and the yellow row all came from the report itself, and the template only has to say where it goes. With nothing ticked, the same menu entry gives all nine filtered orders, over three pages.

Where next

The APEX tutorial video goes through the same install and then two more templates: one that puts the report under your own table style, and one with its own layout built with {{#each}}, with a barcode and a QR code for every order. If you'd rather see ETCH used from other Client libraries code, the ETCH blog has posts for Python and Node.js, and the docs cover the rest.

Everything covered here is also available in our examples repository, so you can clone it and run each one yourself.

Before you start

You need Node.js 22 or later, and an ETCH account. The free plan is enough for everything in this post. From the dashboard you need two things:

• a package token, from the Integrations page, so your package manager can download the client;
• an API key, from the API keys page, which your code uses to call ETCH.

The client is published via the ETCH package registry rather than npmjs.com. Make a project:

mkdir etch-hello
cd etch-hello
npm init -y

Then create a file called .npmrc in the project folder, with these two lines:

@get-etch:registry=https://packages.get-etch.app/npm/
//packages.get-etch.app/npm/:_authToken=${ETCH_TOKEN}

The first line means npm fetches only @get-etch packages from the ETCH registry and everything else from npmjs.com as usual. The second reads your token from the ETCH_TOKEN environment variable. Then give npm your token and install:

export ETCH_TOKEN=<your package token>
npm install @get-etch/etch-client

The token stays in your environment and isn't written to any file in the project. If you use pnpm, Yarn or Windows, the install guide has the commands.

Finally, set your API key:

export ETCH_API_KEY=<your API key>

Your first document

Here's the whole program for the first example. It reads the data from a JSON file and renders an invoice template:

import { readFile } from 'node:fs/promises';
import { ETCHClient } from '@get-etch/etch-client';

const data = JSON.parse(await readFile('invoice.json', 'utf8'));

const client = new ETCHClient(); // reads ETCH_API_KEY
const result = await client.process({ template: 'invoice.docx', data });

await result.saveToFile(`invoice-${data.number}.docx`);

Save it as render.mjs, run it with node render.mjs, and you get a Word document. On the left is the template, an ordinary Word file; on the right is what came back:

Each tag names a field in the data. {{customer.name}} becomes "Kwame Placeholder", and {{unitPrice | currency "$"}} formats a number as money. The line items row starts with {{#each items}} and ends with {{/each}}, so it's repeated once for each item. The fonts, colours and spacing all come from the template, so if someone wants the invoice to look different, they change the Word file and the code stays as it is.

The data doesn't have to come from a file, so you can build it from a database query or an API response or a URL etc.

Using TypeScript? The types come with the client.

Adding a logo

Let's add a picture into the data, as a data: URI. The client has a helper that makes one from a file:

import { ETCHClient, imageFromFile } from '@get-etch/etch-client';

data.logo = await imageFromFile('images/logo.png');

In the template, {{#image logo width="56"}} marks where it goes and how wide it is. Each customer's documents could carry their own logo this way, from the same template.

QR codes and barcodes

You can generate QR codes and barcodes from the data too. The shipping label example uses three tags:

{{#barcode type="code128" width="340" height="80" shipment.tracking}}
{{#qr shipment.trackingUrl size="110"}}
{{#barcode type="ean13" width="190" height="60" ean}}

The first draws the tracking number as a Code 128 barcode, the second a QR code of the tracking page's address, and the third, inside the packing slip's loop, an EAN-13 barcode for each product. The JavaScript code is the same as for the invoice. Only the template and the data have changed.

Excel

To generate a workbook, use an Excel template.

The sales workbook has a summary row with {{#each regions}} at the start and {{/each}} at the end, which becomes one row per region. The total underneath is an ordinary Excel formula, =SUM(C5:C5), and ETCH stretches it to cover the new rows. The chart beside it was drawn in Excel over that same row, and its ranges grow in the same way, so it shows a bar for every region. A second sheet, marked with {{#sheet-each regions}}, is copied once per region and named after the region.

The numbers become native Excel numbers, so the formulas and number formats in the template still work with them.

PowerPoint

The project update deck has three slides in the template, and the finished deck has five. The middle slide starts with {{#slide-each projects}}, so ETCH makes a copy of it for each project, and the milestones on each slide come from a loop of their own.

The status colour comes from the data. Each project has a statusColor such as C0392B, and the pill's text starts with {{#fill statusColor}}, which fills the shape with that colour. The same goes for the table cells on the summary slide.

The chart on the summary slide is one I drew and styled in PowerPoint with placeholder figures. Its Alt Text holds {{#chart projects x="name" y="progress"}}, so ETCH replaces the placeholder bars with one per project and keeps the colours and labels I gave it. The tag is easy to miss when you open the template, because it isn't on the slide. To see it, right-click the chart and choose View Alt Text.

Anything after the tag is kept as the finished chart's Alt Text, so in the deck ETCH produces, a screen reader still hears "Progress by project".

PDF and multiple documents at once

You can easily change the output format to PDF by adding outputFormat to the request:

const pdf = await client.process({
  template: 'invoice.docx',
  data,
  outputFormat: 'pdf',
});

And when you have multiple records, such as a month of invoice data, you can send them in one request. The batch template starts with {{#document-each invoices filename="invoice-{{number}}.docx"}}, and renderBatch returns one document per invoice:

const result = await client.renderBatch({ template: 'invoice-batch.docx', data });

console.log(`Rendered ${result.succeeded} of ${result.total} invoices`);
await result.saveAll('output/invoices');
await result.saveArchive('output/invoices.zip');

If one record has a problem, it will fail in isolation, and result.failures tells you which one failed. The other documents still come back.

Where to go next

The JavaScript examples have 28 of these, each with a README. They cover conditionals, formatters, helpers that add up and rank figures in the template, reusable blocks, stored templates, error handling and running several renders in parallel. The Node.js video builds the invoice template in Word from scratch, renders it from a short Node script, and then makes an Excel workbook with the same code.

You can sign up for the free plan, which gives you 200 documents a month and includes the client libraries. The same examples exist for Python, which has its own post, and for Java, whose post is coming next.

Everything covered here is also available in our examples repository, so you can clone it and run each one yourself.

Before you start

You need Python 3.9 or later, and an ETCH account. The free plan is enough for everything in this post. From the dashboard you need two things:

• a package token, from the Integrations page, so your package manager can download the client;
• an API key, from the API keys page, which your code uses to call ETCH.

The client is published via the ETCH package registry rather than PyPI. With uv, make a project and tell it where etch-client comes from:

uv init etch-hello
cd etch-hello

Add this to the end of pyproject.toml:

[[tool.uv.index]]
name = "etch"
url = "https://packages.get-etch.app/pypi/simple/"
explicit = true

[tool.uv.sources]
etch-client = { index = "etch" }

explicit = true means uv fetches only etch-client from the ETCH registry and everything else from PyPI as usual. Then give uv your token and install:

export UV_INDEX_ETCH_USERNAME=__token__
export UV_INDEX_ETCH_PASSWORD=<your package token>
uv add etch-client

The token stays in your environment and isn't written to any file in the project. If you use pip, or Windows, the install guide has the commands.

Finally, set your API key:

export ETCH_API_KEY=<your API key>

Your first document

Here's the whole program for the first example. It reads the data from a JSON file and renders an invoice template:

import json
from pathlib import Path

from etch import ETCHClient

data = json.loads(Path("invoice.json").read_text(encoding="utf-8"))

with ETCHClient() as client:  # reads ETCH_API_KEY
    result = client.process({"template": "invoice.docx", "data": data})

result.save_to_file(Path(f"invoice-{data['number']}.docx"))

Run it with uv run render.py, and you get a Word document. On the left is the template, an ordinary Word file; on the right is what came back:

Each tag names a field in the data. {{customer.name}} becomes "Kwame Placeholder", and {{unitPrice | currency "$"}} formats a number as money. The line items row starts with {{#each items}} and ends with {{/each}}, so it's repeated once for each item. The fonts, colours and spacing all come from the template, so if someone wants the invoice to look different, they change the Word file and the code stays as it is.

The data doesn't have to come from a file, so you can build it from a database query or an API response or a URL etc.

Adding a logo

Let's add a picture into the data, as a data: URI. The client has a helper that makes one from a file:

from etch import ETCHClient, image_from_file

data["logo"] = image_from_file(Path("images/logo.png"))

In the template, {{#image logo width="56"}} marks where it goes and how wide it is. Each customer's documents could carry their own logo this way, from the same template.

QR codes and barcodes

You can generate QR codes and barcodes from the data too. The shipping label example uses three tags:

{{#barcode type="code128" width="340" height="80" shipment.tracking}}
{{#qr shipment.trackingUrl size="110"}}
{{#barcode type="ean13" width="190" height="60" ean}}

The first draws the tracking number as a Code 128 barcode, the second a QR code of the tracking page's address, and the third, inside the packing slip's loop, an EAN-13 barcode for each product. The Python code is the same as for the invoice. Only the template and the data have changed.

Excel

To generate a workbook, use an Excel template.

The sales workbook has a summary row with {{#each regions}} at the start and {{/each}} at the end, which becomes one row per region. The total underneath is an ordinary Excel formula, =SUM(C5:C5), and ETCH stretches it to cover the new rows. The chart beside it was drawn in Excel over that same row, and its ranges grow in the same way, so it shows a bar for every region. A second sheet, marked with {{#sheet-each regions}}, is copied once per region and named after the region.

The numbers become native Excel numbers, so the formulas and number formats in the template still work with them.

PowerPoint

The project update deck has three slides in the template, and the finished deck has five. The middle slide starts with {{#slide-each projects}}, so ETCH makes a copy of it for each project, and the milestones on each slide come from a loop of their own.

The status colour comes from the data. Each project has a statusColor such as C0392B, and the pill's text starts with {{#fill statusColor}}, which fills the shape with that colour. The same goes for the table cells on the summary slide.

The chart on the summary slide is one I drew and styled in PowerPoint with placeholder figures. Its Alt Text holds {{#chart projects x="name" y="progress"}}, so ETCH replaces the placeholder bars with one per project and keeps the colours and labels I gave it. The tag is easy to miss when you open the template, because it isn't on the slide. To see it, right-click the chart and choose View Alt Text.

Anything after the tag is kept as the finished chart's Alt Text, so in the deck ETCH produces, a screen reader still hears "Progress by project".

PDF, and multiple documents at once

You can easily change the output format to PDF by adding output_format to the request:

from etch import ETCHClient, OutputFormat

pdf = client.process({
    "template": "invoice.docx",
    "data": data,
    "output_format": OutputFormat.PDF,
})

And when you have multiple records, such as a month of invoices, you can send them in one request. The batch template starts with {{#document-each invoices filename="invoice-{{number}}.docx"}}, and render_batch returns one document per invoice:

with ETCHClient() as client:
    result = client.render_batch({"template": "invoice-batch.docx", "data": data})

print(f"Rendered {result.succeeded} of {result.total} invoices")
result.save_all(Path("output/invoices"))
result.save_zip(Path("output/invoices.zip"))

If one record has a problem, it fails in isolation, and result.failures tells you which one failed. The other documents still come back.

Where to go next

The Python examples have 28 of these, each with a README. They cover conditionals, formatters, helpers that add up and rank figures in the template, reusable blocks, stored templates, error handling and running several renders in parallel. The Python video builds the invoice template in Word from scratch and renders it from Python, with uv and with pip.

You can sign up for the free plan, which gives you 200 documents a month and includes the client libraries. The same examples exist for JavaScript and Java, and those posts are coming next.

Then the messages start...

The two problems

The first is copies of copies. The document is out of date as soon as it's created and sent out, because the data was typed in by hand. A correction to that data involves a whole lot of manual work and verification, and everyone who keeps their own copy of the spreadsheet believes theirs is the latest and greatest. There's no central source of the truth.

The second problem turns up when a team does automate it, often the output document layout is baked into the program to generate it. So whenever the document needs to be changed it results in code needing to be changed and all the overhead and time that comes with that process.

How ETCH Helps

ETCH takes a template you design in Word, Excel, PowerPoint, Markdown or PDF and fills it with your data as JSON, and outputs the finished document in exactly the style you defined.

The template is an ordinary Office file, where you want data to appear you type a tag such as {{kpis.revenue}}, and you style it however you like. The formatting and layout you give to the template is the formatting the finished document will have.

Keeping the template and data separate pays off in both directions, where the template needs to be changed you don't need to change any code and vice-versa you are free to modify the code to change how the processing happens without having to worry about the document itself changing.

The data can be a JSON file, or your own code can build it dynamically or fetch it from a URL. In Oracle APEX it can come straight from a SQL query or an interactive report, interactive grid, chart or anywhere else.

A worked example: the quarterly deck

To show it properly, I built the deck from that folder: a five-slide board report for a made-up company, Placeholder Trading Ltd. Every figure in it is invented.

Here's slide 4, the one the message said had last quarter's figures. On the left is the template; on the right is what ETCH generated from the Q1 data.

The table row is a loop. {{#each regions}} repeats it once per region, {{#if revenue >= target}} chooses between "Ahead" and "Behind", and the total underneath is {{sum regions "revenue"}}, added up in the template itself.

The data is a plain JSON file. The part slide 4 uses looks like this:

{
  "company": "Placeholder Trading Ltd",
  "quarter": "Q1",
  "year": 2026,
  "regions": [
    { "name": "London and South East", "revenue": 452000, "target": 430000 },
    { "name": "Midlands", "revenue": 298000, "target": 310000 },
    { "name": "North", "revenue": 341000, "target": 320000 },
    { "name": "Scotland", "revenue": 193000, "target": 190000 }
  ]
}

The chart on slide 3 is worth a callout, because in the template it looks like any other chart. I drew and styled it in PowerPoint with placeholder figures, and put {{#chart months x="month"}} in its Alt Text. ETCH replaces the months and the figures with the data, and matches the Revenue and Costs series by name, so they keep the colours and styling I gave them.

Next quarter, nobody needs to copy anything. Finance send a new JSON file, and the deck is made again from the same template.

Workflow

The quickest way to iterate on template design is using the etch watch command in the ETCH command line tool (available on selected plans).

You keep the template open in PowerPoint, and a preview beside it is refreshed each time you save the template or the data changes.

etch watch -t "Q1 Quarterly Report.pptx" -d q1-figures.json --open

In this recording I add {{quarter}} to the title on slide 1 and save. Then finance's month end figures land on top of the data file, and slide 2 goes from £1.28M to £1.31M without anyone opening the deck.

On slide 2 the template holds tags such as £{{kpis.revenue | compact 2}} and {{kpis.revenueChange | abs | percentage}}, and the preview shows what they turn into.

Previews are normally free and carry a watermark. I recorded this one with --no-watermark, which renders a clean copy and counts each save as one of the month's documents. The command line tool comes with the Professional and Enterprise plans.

To make the finished file rather than a preview:

etch process -t quarterly-report.pptx -d q1-2026.json -o "Q1 Quarterly Report.pptx"

Client Library Support

Oracle APEX

Oracle APEX is where I've spent most of my working life, and it's where I've seen this problem most often. The ETCH plugins for APEX add a dynamic action and a page process plugin. You choose a template and the data, which can be a SQL query or an interactive report or grid, and the user gets the document in their browser. An interactive report or grid comes across with whatever filters and sorting the user has applied.

The APEX tutorial video goes through it from start to finish.

Python

import json
from pathlib import Path

from etch import ETCHClient

data = json.loads(Path("q1-2026.json").read_text(encoding="utf-8"))

with ETCHClient() as client:  # reads your API key from ETCH_API_KEY
    result = client.process({
        "template": "quarterly-report.pptx",
        "data": data,
    })

result.save_to_file(Path("Q1 Quarterly Report.pptx"))

The client installs from the ETCH package registry with the package token from your dashboard; the install steps cover uv and pip. There's a Python video too.

JavaScript and Node.js

import { readFile } from 'node:fs/promises';
import { ETCHClient } from '@get-etch/etch-client';

const data = JSON.parse(await readFile('q1-2026.json', 'utf8'));

const client = new ETCHClient(); // reads your API key from ETCH_API_KEY
const result = await client.process({ template: 'quarterly-report.pptx', data });
await result.saveToFile('Q1 Quarterly Report.pptx');

The install steps cover npm and Yarn, and there's a Node.js video.

Other languages

We support Oracle APEX, Python, JavaScript and Node.js, Java, Go, Swift and REST API

Try ETCH Today

Sign up today at https://get-etch.app you can try the free plan, which gives you 200 documents a month and includes access to all the client libraries and then upgrade to whatever paid plan suits you.

Over the coming weeks we'll be posting a lot more about ETCH and the capabilities and features available, so follow the blog to be notified about updates.