Connect to Valtimo
Use the Valtimo plugin when a case process should generate an Epistola document on its own, at the step where the case needs it. The document is built from case data that is already in Valtimo, so nobody has to switch between systems.
What the plugin adds
The plugin is configured once per Epistola installation: the base URL, an API key, and the tenant to work in. A default environment can be set here as well, and overridden per action.
It also adds three actions you can place on a process step:
- Generate Document — submits a generation request to Epistola.
- Check Job Status — checks the status of a request separately.
- Download Document — fetches the finished PDF and makes it available to the process.
Steps
- Configure the Epistola connection in Valtimo.
- Make sure the version you need is published and deployed to the environment you target.
- Add the Generate Document action to the step that needs the document.
- Select the catalog, the template, and the variant.
- Map the case information to the document fields.
- Save the process and run it with a realistic case.
Choosing a variant
A template can have several variants — the same content in a different language, channel, or house style. Leave the variant out and Epistola uses the template’s default. Name a variant when the process knows exactly which presentation it needs. Or describe the variant by attributes and let Epistola pick the one that matches the case. Naming a variant and describing one by attributes cannot be combined.
Mapping the case data
The mapping is a JSONata expression. The case document and the process variables are available to it, and it has to return an object that matches the template’s data contract — the same fields the template expects to receive. Work from the contract, not from the document you have in mind: the template renders whatever the contract describes.
The document is not ready immediately
Generation is asynchronous. The action returns a request id as soon as Epistola has accepted the request, and stores it in the process variable you chose — but the PDF does not exist yet at that point. Give the process a wait step after generation that waits for Epistola’s completion message, and route the process on the outcome. A later step that assumes the document is already there will carry on without it.
Some problems are caught when the request is submitted: if a template, a variant, or the environment does not exist — or no environment is chosen and the template has no published version at all — Epistola refuses the request and the step fails right away. But a version that is published without being deployed to that environment is not caught then: Epistola accepts the request, and the job fails later, which surfaces when the completion message arrives.
Keep the split clear
Use Valtimo to decide when a document is needed and which case data goes in. Use Epistola to decide what the document contains and looks like: the template, the variant, and the theme. Keep layout and wording in Epistola, and process logic in Valtimo.