Use the document in a case
Users should work with generated documents inside the task or case screen where they already make decisions — not in a separate application. That screen is a Valtimo case task: Valtimo owns the case and its tasks, and Epistola supplies the document.
Previewing before you generate
A task can show a preview before the official document exists. That preview is a real render of the current case data through the template, so the user sees how the document will look and can still correct the input before anything is generated. It carries a watermark and it is not stored: nothing is generated, no job is created, and the preview does not appear in the generation history.
That is a different thing from the preview in the editor, which shows a draft with example data while a template is being built. The task preview works from the case; the editor preview works from the template.
Common task features
- Show a preview before the official document is generated.
- Let the user generate or continue the process.
- Show the generated PDF inline.
- Offer a download button when the user needs the file.
- Send failed documents to a retry or review task.
Three components cover these features: the preview, the document view, and the retry form, all placed on the task form. The remaining two are process work — generation runs as a service task, and routing a failure to a retry or review task is a decision in the process model. The preview needs a generate-document step somewhere in the process, and it says so plainly when it is not configured or when the component is opened outside a user task.
What the task components show
The document viewer has two useful states: the PDF, or nothing. While generation is still running there is nothing to show, and a generation that failed leaves no document either. The viewer treats both the same way and reports that the document has not been generated yet, so route the outcome in the process instead of expecting the viewer to announce a failure.
A retry task is the exception. It carries the reason generation failed and offers the fields the user can correct, with a live preview of the result.
Good review flow
Show the document, the case it belongs to, and the action the user can take next. Avoid exposing technical document IDs or background job state unless the user is troubleshooting.
Access control
Valtimo should decide who may see or act on the case task. Epistola generates the PDF; it does not replace case permissions.
That boundary is enforced rather than assumed. The document, preview, and retry endpoints a task form calls take no case reference of their own: they derive the case from the task the user is working on, and refuse the request when the user may not see that task.