B8786 - We beschrijven saga’s als onderdeel van de standaard

Besluit

We beschrijven saga’s in ieder geval vanuit het perspectief van technische data-integriteit. In een CRUD-API waar verplichte relaties voorkomen kunnen situaties ontstaan waardoor één gewenste functionele transacties in twee technische transacties moet worden uitgevoerd. Dat betekent dat na de eerste technische transactie er een inconsistentie ontstaat die door de tweede transactie opgeheven wordt. In de saga wordt beschreven wat de gevolgen zijn als de tweede transactie niet slaagt en welke actie er moet worden ondernomen om de eerste transactie ongedaan te maken.

Deze saga-beschrijvingen worden in de functie-beschrijvingen opgenomen waar dat van toepassing is. Een voorbeeld daarvan is te vinden in F7554 - Registreer partij

Saga’s die vanuit functioneel perspectief gewenst zijn worden (vooralsnog) niet beschreven. Reden daarvoor is dat deze Saga’s in feite tot handelingen moeten leiden die in een handelingen-API in één call (en dus transactie) moeten kunnen worden afgehandeld door de consumer).

Ook als er alleen sprake is van een CRUD-API zou je deze handelingen willen beschrijven en als dat gedaan wordt dan is het raadzaam om ook de daarbij behorende saga te beschrijven. Om deze wijze kan eenduidig aan de consumer-developer uitgelegd worden hoe de functionaliteit geïmplementeerd zou moeten worden.

Vraagstuk

In de functie F2173 - Registreer klantcontact zou bijvoorbeeld de volgende passage opgenomen kunnen worden:

Indien het aanmaken van een informatieobject niet lukt, wordt deze opgeslagen als onderdeel van de bijlage. Op een later moment wordt alsnog geprobeerd het bijbehorende informatieobject aan te maken en wordt de identificatie hiervan geregistreerd in de bijlage.

Dit is feitelijk de uitwerking van een mogelijke saga om transactie issues te voorkomen.

Redenen om dit wel op te nemen:

• We weten zeker dat er rekening gehouden wordt met dit soort situaties.
• Het gedrag van de API is voorspelbaar, dat is fijn voor de clients die er mee moeten werken.
  • Zo is duidelijk dat er geen bijzondere foutmeldingen (of events nav compensating transactions) zullen komen omdat een deel niet opgeslagen kan worden.
  • Het is ook duidelijk dat informatieobjecten mogelijk niet direct zichtbaar zullen zijn in een DMS.

Redenen om dit niet op te nemen:

• In principe wil je niet voorschrijven hoe iets gebouwd moet worden.
• Je zou gedrag ook duidelijk kunnen maken door eisen te stellen aan de API. Bijvoorbeeld:
  • De functie dient in één keer alle aangeboden gegevens op te slaan. Ook in situaties waarin het register waarin de informatieobjecten opgeslagen moeten worden niet beschikbaar is.
  • Het is niet toegestaan om:
    • een foutmelding te geven als dit register niet beschikbaar is
    • te wachten tot het weer beschikbaar is
    • als opslaan uiteindelijk niet lukt een compensating transaction uit te voeren (en de client hierover te notificeren)
  • Het is wel toegestaan om:
    • gegevens die in andere registers opgeslagen moeten worden, tijdelijk in het klantcontact register op te slaan
    • de client kan er dus niet vanuit gaan dat de informatieobjecten direct in een DMS beschikbaar zijn

In het laatste voorbeeld werk je feitelijk om de concrete beschrijving heen.