Connected Systems

Most teams generate production documents from another system, such as Valtimo, a case system, a workflow engine, or a custom application. Epistola is the document service; the connected system supplies the business data and starts the generation request.

How the connection works

The integration follows a simple flow:

A process or user action in the connected system starts document generation.
The system selects an Epistola environment, template, and—where needed—a variant. Epistola resolves the version active in that environment.
It sends JSON data that matches the template’s data contract, together with any variant selection or attributes.
Epistola evaluates expressions, resolves the template resources, and generates the document.
The connected system stores, displays, or sends the resulting document and handles failures according to the process design.

The integration uses an API key with the minimum permissions required for its job. Configure credentials and access separately from the template content; see Access & Permissions for the access model.

Prepare the Epistola side

Check that:

The template is published.
The right version is deployed to the target environment.
The connected system knows which template, variant, and output handling to use.
Variant rules are documented when the template has multiple variants.
The template’s required fields and data contract are known to the integration team.

Prepare the connected system

The connected system should be able to:

Authenticate with a dedicated API key.
Send data in the shape expected by the selected template version.
Select a variant explicitly or provide the attributes used for automatic resolution.
Store the generated document and its correlation or business identifier.
Distinguish a successful response from validation, authorization, and generation failures.

For example, a Valtimo process can use a generate-document action to map process and case data to an Epistola template. After generation completes, a download-document action can make the PDF available for storage with the case. A custom application can implement the same flow directly against the Epistola API.

Plan failure handling

Make the success and failure paths explicit before going live. Decide what happens when required data is missing, a variant cannot be resolved, the API key is rejected, or document generation fails. Depending on the process, the right response may be a retry, a user task to correct data, or an operational alert. Someone should be able to review failed documents and the original request context.

What to give the implementation team

Give developers the template name and published version, target environment, variant rules, required fields, example payloads, output handling, and expected failure/review flow. Keep low-level endpoint and deployment details in developer documentation or project implementation notes.

User responsibility

Users and process owners validate that the generated document is correct for real cases. Developers validate authentication, payload mapping, template selection, output handling, and retries.