Skip to content
Skills Library
Data & analytics · Building & coding

render-export-template

/render-export-template

Author, render, and iterate on Rossum Custom Format Templating export templates — the legacy Jinja2 templates stored inside an export hook's settings.export_configs that turn an annotation into a flat file, CSV, XML, EDI, or custom JSON. Pull a template out of a hook into a local file, render it faithfully against a real annotation to preview the exact export output, and generate hook settings back from an edited template. Use whenever the user wants to edit, test, preview, debug, or build an export template, mentions file_content_template / file_content_template_multiline / export_reference_k

Licence
MIT
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
5
Scripts
2
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 2 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/render_export_template.py, tests/test_render_export_template.py

What it does and when to use it

Author, render, and iterate on Rossum Custom Format Templating export templates — the legacy Jinja2 templates stored inside an export hook's settings.export_configs that turn an annotation into a flat file, CSV, XML, EDI, or custom JSON. Pull a template out of a hook into a local file, render it faithfully against a real annotation to preview the exact export output, and generate hook settings back from an edited template. Use whenever the user wants to edit, test, preview, debug, or build an export template, mentions file_content_template / file_content_template_multiline / export_reference_k

Arguments

/render-export-template [hook-id-or-url] [annotation-id-or-url] [--key=<export_reference_key>] [--env=<name>]
Original author description

Author, render, and iterate on Rossum Custom Format Templating export templates — the legacy Jinja2 templates stored inside an export hook's settings.export_configs that turn an annotation into a flat file, CSV, XML, EDI, or custom JSON. Pull a template out of a hook into a local file, render it faithfully against a real annotation to preview the exact export output, and generate hook settings back from an edited template. Use whenever the user wants to edit, test, preview, debug, or build an export template, mentions file_content_template / file_content_template_multiline / export_reference_k

How it works

  1. When to use this skill
  2. Safety: remote-write confirmation gate
  3. How an export hook stores the template
  4. The render context — what the template can reference
  5. The three verbs
  6. The iteration loop
  7. Gotchas
  8. When to stop / hand off
  9. Important
Original SKILL.md headings · 164 lines, 1,791 words
SKILL.md preview
---
name: render-export-template
description: Author, render, and iterate on Rossum Custom Format Templating export templates — the legacy Jinja2 templates stored inside an export hook's settings.export_configs that turn an annotation into a flat file, CSV, XML, EDI, or custom JSON. Pull a template out of a hook into a local file, render it faithfully against a real annotation to preview the exact export output, and generate hook settings back from an edited template. Use whenever the user wants to edit, test, preview, debug, or build an export template, mentions file_content_template / file_content_template_multiline / export_reference_key, or says things like "render the export template for hook X", "test my export template against annotation Y", "pull the export template", "why does my export file come out wrong", "change the export format". This is the legacy template-based export — NOT the JSON-stage Request Processor (for that, see export-pipeline-reference).
argument-hint: "[hook-id-or-url] [annotation-id-or-url] [--key=<export_reference_key>] [--env=<name>]"
allowed-tools: Read, Edit, Write, Grep, Glob, Bash
---

# Render & Iterate on a Custom Format Templating Export Template

You are a Rossum.ai Solution Architect working on an **export template** — the Jinja2 template that the legacy *Custom Format Templating* export step renders into the file a downstream system ingests (flat file, CSV, XML, EDI, custom JSON). The whole reason this is hard by hand: the template lives as escaped lines inside a hook's `settings`, and the only way to know what it actually emits is to render it against a real annotation. Rendering JSON-via-Jinja is unforgiving — one misplaced comma from a `loop.last` guard, one wrong `| tojson` escape, and the export is invalid. So the core of this skill is a **faithful render loop**: pull the template into a local file, render it against a real document with the real Jinja2 engine, eyeball the exact output, edit, repeat — then push the finished template back into the hook.

> Hook / annotation / context: $ARGUMENTS

## When to use this skill

Pick this up automatically when **any** of the following holds:

- The user wants to **edit, preview, test, debug, or build** an export template, or asks "what does my export file look like", "why is the export malformed", "change the export format / mapping".
- The request mentions `export_configs`, `file_content_template`, `file_content_template_multiline`, `export_reference_key`, or "Custom Format Templating".
- The user says "render the export template for hook X", "test this template against annotation Y", "pull the export template into a file", or any equivalent.

**Disambiguation — read this before starting.** Rossum has two unrelated "export" mechanisms:

- **Custom Format Templating** (this skill): a Jinja2 *template* renders the annotation to a file. The template sits in `settings.export_configs[].file_content_template_multiline`.
- **Request Processor** (NOT this skill): a multi-stage JSON pipeline that calls external APIs — no Jinja2 templates. If the hook's settings have `stages`/`requests`/`call_api`, this is the wrong skill → use `export-pipeline-reference`.

If you are unsure which one a hook uses, `rossum_get_hook` and look at the shape of `settings`. For the **format/Jinja2 details** of Custom Format Templating itself, lean on `rossum-reference`; this skill is the *workflow*, not the format spec.

## Safety: remote-write confirmation gate

<HARD-GATE>
Two of the three verbs are read-only. The only operation that **changes a remote Rossum environment** is pushing generated settings back into a hook. Before ANY `rossum_patch_hook` (or `prd2 push`) that writes export settings, you MUST:

1. **Show exactly what will change** — hook id, target environment, the `export_reference_key`, and a diff or summary of the template lines being written.
2. **Wait for an explicit "yes"** — never batch a push in with other steps.
3. **Never push to a production hook.** If the hook belongs to a `prod` queue, stop and ask for a sandbox/UAT hook instead. `rossum_extract_export_template` returns the connection `base_url` — read it to identify the environment (e.g. a production `*.rossum.app` org) rather than guessing from queue names. If you cannot tell the environment, ask before writing.

`rossum_get_hook`, `rossum_extract_export_template`, `rossum_generate_export_settings`, `rossum_generate_export_payload`, and running the local render script are all read-only / local — no confirmation needed.
</HARD-GATE>

## How an export hook stores the template

The template is **not** a single string. It lives under `settings.export_configs` — an **array**, because one hook can emit several files:

```jsonc
{
  "export_configs": [
    {
      "export_reference_key": "coupa_invoice",        // names this output
      "content_encoding": "utf-8",
      "file_content_template_multiline": [             // the template, one array entry per line
        "{",
        "  \"invoice-number\": \"{{ field.document_id }}\",",
        "  \"invoice-lines\": [",
        "  {% for item in field.line_items %}{ ... }{% if not loop.last %},{% endif %}{% endfor %}]",
        "}"
      ]
    }
  ]
}
```

- Join `file_content_template_multiline` with `\n` to reconstruct the template.
- Older hooks may instead carry a single-string `file_content_template` — read both, but **write** the multiline form.
- If `export_configs` has more than one entry and the user did not say which, **list the `export_reference_key`s and ask** which one to work on.

## The render context — what the template can reference

The render engine builds exactly two top-level variables and nothing else:

- **`field`** — the annotation flattened to `{schema_id: value}`. Simple datapoints become their value (the `normalized_value` if present, else `value`); a tuple becomes a nested dict; a multivalue becomes a list. So `field.currency` is a scalar and `field.line_items` is a **list of dicts**.
- **`payload`** — the raw export payload, e.g. `payload['annotation']['automated']`.

Inside `{% for item in field.line_items %}`, `item` is one line-item dict, so `item.item_description` etc. resolve. There are **no custom filters** — `| default(0, true)` and `| tojson` are Jinja2 built-ins. If a template references something outside `field`/`payload`, that is a template bug, not an engine gap.

## The three verbs

### 1. extract — hook → local file

Pull the live template into a local file you can edit.

```
rossum_extract_export_template(hookId=<id>, exportReferenceKey="<key>")   # key optional if only one config
```

Returns the joined template string, its `export_reference_key`, and `content_encoding`. Write it to a local `.j2` file (suggest `<reference_key>.j2`) so you can edit and version it. If the tool reports multiple configs and no key was given, show the keys and ask.

### 2. render — template + annotation → faithful output

This is the heart of the loop. Two steps: get the payload (via the live connection), then render locally with the real engine.

```
rossum_generate_export_payload(hookId=<id>, annotationId=<id>)   # -> the export payload JSON
```

Write that payload to a temp file (e.g. `/tmp/eth-payload-<aid>.json`), then run the bundled render script:

**The payload is sensitive.** A `generate_payload` response contains `rossum_authorization_token` and the hook's `secrets`. Write it to a temp file, never echo it into the conversation, and delete it when done. The rendered *output* is safe (it only contains what the template emits), but the payload file is not.

Use `rossum_generate_export_payload` here specifically: it returns the payload **unredacted**, which the render script needs. `rossum_generate_hook_payload` covers any event/action but redacts credentials, making it the right tool for inspecting payload *shape* in-conversation and the wrong one for rendering.

```
python3 "<this-skill-dir>/scripts/render_export_template.py" \
    --template <your-template>.j2 \
    --payload  /tmp/eth-payload-<aid>.json
```

The script prints the rendered file to stdout — this is **exactly** what the export would produce. If the template emits JSON, pipe it through `python3 -m json.tool` to confirm it parses (a comma/`loop.last` mistake fails here loudly).

**jinja2 availability.** The script needs `jinja2` importable. Try the command above first; if it fails with `ModuleNotFoundError: jinja2`, create a one-time cached venv and use its interpreter:

```
python3 -m venv ~/.cache/rossum-sa/eth-venv && ~/.cache/rossum-sa/eth-venv/bin/pip -q install jinja2
~/.cache/rossum-sa/eth-venv/bin/python "<this-skill-dir>/scripts/render_export_template.py" --template ... --payload ...
```

Reuse that venv on later renders. Never add `jinja2` to the MCP server — it is deliberately dependency-free.

**Offline mode.** If the user hands you a saved payload JSON instead of a live annotation, skip `rossum_generate_export_payload` and point `--payload` straight at their file.

### 3. generate — local file → hook settings

When the template is right, turn the edited file back into hook settings.

```
rossum_generate_export_settings(templatePath="<your-template>.j2", exportReferenceKey="<key>", contentEncoding="utf-8")
```

Returns the `export_configs` JSON block. To apply it, merge it into the hook's `settings` and push **through the hard-gate**:

- In a **prd2 project**, prefer editing the local hook JSON and `prd2 push` (per the project's `CLAUDE.md` workflow) over a direct API patch.
- Otherwise, `rossum_patch_hook(hookId=<id>, settings=<merged settings>)` — only after showing the change and getting a "yes". `export_configs` is among the largest settings objects in the product, so for anything but a small template pull the hook first with `rossum_get_hook` + `out_file_path` and write the merge back with `settings_file_path` rather than inlining it.

## The iteration loop

Repeat until the rendered output matches the target format, then push once at the end:

1. **Extract** the current template to a local file (or start a new file if building from scratch).
2. **Render** it against a representative annotation. Read the actual output. If JSON, validate it parses.
3. **Diff against the goal.** State it plainly: "target format wants X, render produced Y." Common gaps: trailing/leading commas in loops (`{% if not loop.last %}`), unescaped strings (needs `| tojson`), empty values (needs `| default(...)`), date/number formatting.
4. **Edit the local file** and re-render. Stay in this local loop — no remote writes while iterating.
5. **When correct, generate** settings and push **once**, through the hard-gate. Re-extract or re-render against the live hook to confirm the round-trip if the user wants belt-and-suspenders.

Keep a representative annotation handy — ideally one with line items, an empty optional field, and a special character, so the loop exercises the loop/`default`/`tojson` paths.

## Gotchas

- **Commas are the #1 failure.** JSON emitted from a `{% for %}` needs `{% if not loop.last %},{% endif %}` between items and care around optional `{% if %}` blocks. Always validate rendered JSON by parsing it.
- **`tojson` for any string that may contain quotes/newlines/unicode** — `"x": {{ item.description | tojson }}` (note: no surrounding quotes, `tojson` adds them). Hand-quoting `"{{ ... }}"` breaks on special characters.
- **`normalized_value` vs `value`.** The flattener prefers `normalized_value`, so dates/amounts render in their normalized form — the same value the real export sees. If a template looks "wrong", check whether you expected the raw OCR string.
- **Multiple `export_configs`.** Don't guess — list the keys and ask. Generate/extract operate on one key at a time.
- **Write the multiline form.** `generate` emits `file_content_template_multiline`; even if you extracted a legacy single-string `file_content_template`, write back multiline.
- **`content_encoding` matters for non-UTF8 targets** (some EDI/legacy systems want `latin-1` etc.). Preserve what you extracted unless the user wants it changed.
- **The render script is local and pure** — it makes no Rossum calls. All Rossum HTTP goes through the MCP tools, so auth lives in one place (the MCP connection).
- **`generate_payload` returns secrets.** Its response carries `rossum_authorization_token` and the hook's `secrets` alongside the annotation content. Treat the saved payload file as a credential: temp-only, never echoed, deleted after rendering.

## When to stop / hand off

- **Output matches the target and the push succeeded** → confirm with the user, done.
- **The hook turns out to be a Request Processor** (no `export_configs`) → hand off to `export-pipeline-reference`.
- **You need to verify the change across many documents**, not just one → after pushing, hand off to `test-behavioral-equivalence`.
- **The mismatch is upstream data, not the template** (a field is empty because a prior hook/formula didn't populate it) → that's an `iterate` problem on that hook/formula, not a template fix.

## Important

- Render is **always** the real engine — never hand-render JSON in your head and call it the output.
- Two verbs are read-only; only the push writes — and every push passes through the hard-gate, never to prod.
- One `export_reference_key` at a time; ask when there are several.
- Keep the edit→render loop local and fast; touch the remote hook only to extract at the start and push at the end.
Files in this package (5)
  • SKILL.md 13 KB
  • scripts/render_export_template.py 4 KB
  • tests/test_render_export_template.py 3 KB
  • tests/fixtures/sample_payload.json 2 KB
  • tests/fixtures/sample_template.j2 1 KB

Versions

The database has no other skills named render-export-template.

Database snapshot: 13.11.2026 · package version 637bddb3474b (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 96export-pipeline-reference
    Request Processor (export pipeline) configuration reference for Rossum. Covers the multi-stage JSON-based engine for integrating Rossum with external APIs — stages, variable templating, evaluate conditions, get_content sources, call_api with auth/iteration/file uploads, response…
  • 100iterate
    Iterate on a Rossum deliverable (hook, formula, rule, schema change) against a specific annotation until a stated goal is met. Provides the re-fire primitives via MCP — soft re-fire (start → content/validate → cancel), status toggle, in-place re-extract, re-upload, and export…
  • 100fused-render-custom-templates
    Use when registering custom preview template for file extension, or overriding/reordering built-in template modes.
  • 100csv-manual-export
    CSV Manual Export: a UTF-8 CSV template from a confirmed field list, empty by default, with no invented columns or values. Use for an import, staging or handoff file.
  • 100csv-manual-export
    CSV Manual Export: a UTF-8 CSV template from a confirmed field list, empty by default, with no invented columns or values. Use for an import, staging or handoff file.
  • 100export-data
    Use when the user wants to export session data — e.g. 'export my sessions', 'download data', 'export to CSV', 'get my data

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.