Handle generation results
After Valtimo starts document generation, the case should wait until Epistola has finished the PDF.
What a generation leaves behind
The workflow keeps the outcome in a process variable of your choosing. When Epistola accepts the request, that variable holds a request id and the status PENDING. When the document exists, the same variable holds the finished status and the document id — or, if it went wrong, the failure and an error message.
That status ends as completed or failed — there is no third outcome to handle. Until it lands, the variable holds PENDING, so the process can act on the request straight away without mistaking that for a result.
Recommended flow
- Start document generation.
- Wait for the completion message from Epistola.
- If generation succeeded, download the PDF.
- If generation failed, show the error and route to a retry or manual review step.
- Store or send the document only after a successful download.
Two things to watch here:
- The wait is what wakes the process; the result is stored either way. The result wakes the branch waiting for it, and while the case is still running it is written into the result variable regardless. A case that has moved on can still read the outcome or ask for the status later, but nothing resumes it by itself — and once the case has ended there is nothing left to write to. Keep the wait directly after the generation step, with no asynchronous boundary in between, so the result is matched to the branch that is waiting for it.
- Downloading is not the same as filing. The download step makes the document available to the process, by default as a short-lived temporary resource. Getting it into the case’s document store is a separate step afterwards, and it has to happen while the download is still around.
Correcting a failed generation
A failed attempt is rarely the end of the case. The user task can offer a retry with the fields they need to correct, prefilled by evaluating the mapping again against the case as it stands.
What a retry does is worth stating precisely. The corrected values replace the mapped data for that attempt, and the retry is a new generation rather than a second look at the original job. The failed attempt stays in the history, and the document is generated again from scratch.
The error message on that task is the technical reason generation failed. It is useful to the person who can correct the data, and it is not diagnostic text for the case worker.
What users should see
Users should not see technical job details. Show whether the document is waiting, ready, failed, or needs correction. If correction is possible, send the user to a retry form with the fields they can fix.
While no document exists there is nothing to show, and the document component says so in plain language rather than presenting an empty viewer. A failed generation looks the same to that component as one that is still running, which is another reason to route the failure explicitly instead of letting the task sit and wait.
Developer note
The Valtimo plugin stores the technical result state for the workflow. Modelers usually only need the success, failure, and retry paths.
If a case does end up parked on a wait, an administrator can reconcile it from the plugin’s pending jobs screen.
Epistola keeps a generated document for a limited period — three months by default. Treat that copy as something to hand over, not as the archive.