Gekoppelde systemen

De meeste teams genereren productiedocumenten vanuit een ander systeem, zoals Valtimo, een zaaksysteem, workflow engine of maatwerkapplicatie. Epistola is de documentservice; het gekoppelde systeem levert de bedrijfsgegevens en start de generatieaanvraag.

Hoe de koppeling werkt

De integratie volgt een eenvoudige flow:

Een proces of gebruikersactie in het gekoppelde systeem start documentgeneratie.
Het systeem selecteert een Epistola-omgeving, template en—waar nodig—een variant. Epistola bepaalt de versie die in die omgeving actief is.
Het verstuurt JSON-gegevens die bij het datacontract van het template passen, samen met een eventuele variantselectie of attributen.
Epistola evalueert expressies, lost de template-resources op en genereert het document.
Het gekoppelde systeem bewaart, toont of verstuurt het resultaat en handelt fouten af volgens het procesontwerp.

De integratie gebruikt een API-sleutel met alleen de benodigde rechten. Configureer credentials en toegangsrechten los van de templatecontent; zie Toegang en rechten voor het toegangsmodel.

Bereid Epistola voor

Controleer dat:

De template gepubliceerd is.
De juiste versie naar de doelomgeving is gedeployed.
Het gekoppelde systeem weet welke template, variant en outputafhandeling gebruikt moeten worden.
Variantregels zijn gedocumenteerd wanneer het template meerdere varianten heeft.
Het datacontract en de verplichte velden van het template bekend zijn bij het integratieteam.

Bereid het gekoppelde systeem voor

Het gekoppelde systeem moet:

Kunnen authenticeren met een aparte API-sleutel.
Gegevens kunnen versturen in de vorm die de gekozen templateversie verwacht.
Expliciet een variant kunnen kiezen of de attributen voor automatische resolutie kunnen meegeven.
Het gegenereerde document en een correlatie- of bedrijfsidentifier kunnen opslaan.
Een succesvolle response kunnen onderscheiden van validatie-, autorisatie- en generatieproblemen.

Een Valtimo-proces kan bijvoorbeeld een generate-document-actie gebruiken om proces- en casegegevens naar een Epistola-template te mappen. Nadat de generatie is voltooid, kan een download-document-actie de PDF beschikbaar maken om deze aan de case te koppelen. Een maatwerkapplicatie kan dezelfde flow rechtstreeks tegen de Epistola-API implementeren.

Plan foutafhandeling

Maak het succes- en foutpad expliciet voordat je live gaat. Bepaal wat er gebeurt als verplichte gegevens ontbreken, een variant niet kan worden gevonden, de API-sleutel wordt geweigerd of documentgeneratie mislukt. Afhankelijk van het proces kan een retry, een user task om gegevens te corrigeren of een operationele melding passend zijn. Iemand moet mislukte documenten en de oorspronkelijke requestcontext kunnen beoordelen.

Wat geef je aan het implementatieteam?

Geef ontwikkelaars de templatenaam en gepubliceerde versie, doelomgeving, variantregels, verplichte velden, voorbeeldpayloads, outputafhandeling en gewenste fout- en reviewflow. Houd low-level endpoint- en deploymentdetails in ontwikkelaarsdocumentatie of projectnotities.

Gebruikersverantwoordelijkheid

Gebruikers en proceseigenaren controleren of het gegenereerde document klopt voor echte zaken. Ontwikkelaars controleren authenticatie, payloadmapping, templategeselectie, outputafhandeling en retries.