Zoek op
gridsz
GRIDSZ
Neem contact met ons op
Vraag demo aan
GRIDSZ

Equitri-protocol

Equitri is het protocol dat GRIDSZ gebruikt om partijen die aan dezelfde taak werken op elkaar af te stemmen. Het vormt de basis voor de Fulfillment (TASK) en Assurance (SERVICE) API’s en gaat uit van een relatief laag aantal updates bij langlopende taken (die doorgaans langer dan een dag duren). Achter een bewust eenvoudig gehouden API verbergt Equitri de complexiteit van backend-systemen, middleware, nachtelijke batchverwerking en realtime-systemen.

Elke aangesloten partij moet zowel een client als een server implementeren: de client initieert updates en haalt taakinformatie op van de server van een andere partij, terwijl de server de taakgegevens beschikbaar stelt aan de client van een andere partij (meestal Gridsz). De maker (InTask) en de ontvanger (OutTask) maken gebruik van verschillende API’s, maar het onderliggende protocol is identiek.

Na een toelichting op enkele begrippen en het protocol zelf worden op deze pagina de stappen voor beide richtingen beschreven:

  • Gridsz : een nieuwe taak Gridsz of een bestaande taak bijwerken
  • Een geïntegreerd systeem dat een nieuwe taak aanmaakt of een bestaande taak bijwerkt

De termen ‘geïntegreerd systeem’ en ‘u’ verwijzen naar de partij die Equitri implementeert.

Deze pagina gaat niet in op de onderliggende connectiviteit op http(s)-niveau, VPN’s, proxyservers enzovoort, en gaat evenmin in op wat de partij met de ontvangen taakinformatie moet doen. Het absolute minimum is dat het geïntegreerde systeem de Equitri-API (INDICATION / FETCH / SYNC) in beide richtingen kan verwerken met geldige JSON en autorisatie, waarbij rekening wordt gehouden met zowel gunstige als ongunstige scenario’s.

Opmerking: het is mogelijk om de FETCH los van het INDICATION- en SYNC-proces af te handelen – om informatie te verzamelen zonder de taak bij te werken.

Woordenlijst

Een korte toelichting op de gebruikte termen.

Equitri

De naam die is toegekend aan het API-mechanisme zoals dat wordt gebruikt in de GRIDSZ . Dit mechanisme is van toepassing op zowel de Fulfilment- als de Assurance-workflows, en geldt zowel voor de API’s van de aanmaker (InTask) als voor die van de ontvanger (OutTask).

INDICATIE

Een INDICATION is het eerste bericht in het Equitri-protocol. Het is een „fire-and-forget”-POST-bericht waarin eenvoudigweg wordt aangegeven dat er een taak moet worden opgehaald bij het eindpunt van de afzender. In de inhoud van het bericht wordt gespecificeerd welke taak van welk eindpunt moet worden opgehaald. Dit kan zowel een volledig nieuwe taak zijn als een update van een bestaande taak.

FETCH

Een FETCH is het tweede bericht in Equitri en vormt de eigenlijke ‘krachtige slag’. Met een eenvoudige HTTP GET-aanroep naar de juiste URL wordt de volledige inhoud van de taak teruggestuurd. De FETCH kan ook als een op zichzelf staande aanroep worden uitgevoerd, zonder voorafgaande INDICATION, en vereist dan ook geen SYNC.

SYNC

Een SYNC-bericht is het derde en laatste bericht in het Equitri-protocol. Het is een PUT-bericht waarin wordt aangegeven dat de taak is verwerkt en dat er voor deze specifieke update (versie) geen verdere INDICATION-berichten meer moeten worden verzonden. Het SYNC-bericht bevat ook een veld voor toelichting en reden, dat wordt ingevuld indien de update de gegevensvalidaties niet doorstaat.

Aantal updates

Ook wel de ‘versie’ genoemd. Deze geeft aan welke versie een bepaalde taak momenteel heeft. Aan GRIDSZ van GRIDSZ is de versie de master en kan deze alleen hoger worden of gelijk blijven (als de update mislukt).

Regels van het Equitri-protocol

De volgende algemene regels zijn van toepassing:

  1. De sleutelwoorden „MUST“, „MUST NOT“, „REQUIRED“, „SHALL“, „SHALL NOT“, „SHOULD“, „SHOULD NOT“, „RECOMMENDED“, „MAY“ en „OPTIONAL“ in dit document moeten worden geïnterpreteerd zoals beschreven in RFC 2119.
  2. HTTP-headers die niet worden herkend, worden zonder melding genegeerd
  3. Wanneer een partij een taak naar een andere partij verstuurt en direct daarna die taak bij diezelfde partij ophaalt, bevat de ontvangen taak precies dezelfde gegevens als de oorspronkelijke.
  4. Wanneer je een INDICATION voor een taak ontvangt, mag je zelf geen INDICATION voor die taak versturen, totdat je eerst de binnenkomende INDICATION hebt FETCH en SYNC
  5. Wanneer er meerdere updates voor dezelfde taak worden ontvangen, is alleen de laatste update (dat wil zeggen: de update met de hoogste `updateCount`) relevant. Oudere updates worden overgeslagen.
  6. Een taak heeft altijd betrekking op 1 TASK op 1 verbinding. De verbinding (DHid) en het taskType van een bestaande taak mogen niet worden gewijzigd.

Schema opnieuw proberen

Er kunnen dingen misgaan, en dat zal op een gegeven moment ook gebeuren. Wanneer het bijwerken van een bestaande taak misgaat, moet de partij terugvallen op het herhalingsschema:

  • Tenzij er een SYNC-bericht wordt teruggestuurd, zullen de INDICATION-berichten door de andere partij voor altijd opnieuw worden verzonden.
  • Aangezien de ontvangst van een INDICATION vaak als aanleiding wordt gebruikt om een FETCH en een SYNC uit te voeren, bedraagt de minimale tijd tussen twee INDICATION-verzoeken voor dezelfde taak 10 seconden, en begint deze in de productieomgeving doorgaans bij 1 minuut.
  • Implementaties van Equitri zouden een progressieve back-up kunnen toepassen, waarbij de wachttijd tussen twee indicatieverzoeken na elk verzoek toeneemt, tot een maximum van 1 INDICATION per 4 uur.

Alle INDICATON-verzoeken voor dezelfde combinatie van taak en updatecount maken deel uit van hetzelfde gesprek.

Relatieve versiebeheer van taken

Het is mogelijk, en zelfs waarschijnlijk, dat er op een bepaald moment storingen optreden in één of meer systemen van partijen die bij een taak betrokken zijn. Bovendien zullen partijen in verschillende tempo’s reageren op updates binnen een taak. Om versieproblemen te helpen voorkomen, heeft de Equitri-taak altijd een updatecount. De updatecount fungeert als een soort versienummer. Bij een nieuwe taak moet deze altijd beginnen met het gehele getal 1. Bij elke update die een partij aan andere partijen doorgeeft, moet de updateCount met (minstens) 1 worden verhoogd ten opzichte van de huidige waarde.
Wanneer de updateCount 500 of meer bedraagt, is de taak in een (mogelijk eindeloze) lus terechtgekomen. Het geïntegreerde systeem mag geen INDICATION meer verzenden voor deze taak en moet ervoor zorgen dat er handmatig actie wordt ondernomen om de situatie te corrigeren.

UpdateCount is kleiner dan of gelijk aan de huidige updateCount

Dit gebeurt wanneer een andere partij een update verstuurt over een eerdere versie van de taak. De andere partij was waarschijnlijk offline en heeft de laatste updates over de taak niet ontvangen. De versie van de taak GRIDSZgeldt als de hoofdversie.
Zo worden bijvoorbeeld opmerkingen die niet in de versie van het geïntegreerde systeem aanwezig waren, in de juiste volgorde ingevoegd. Bijlagen kunnen worden toegevoegd. Zelfs de status van de taak kan worden bijgewerkt, maar alleen als dit niet in strijd is met de status in de huidige versie van de taak.
Na het samenvoegen zal het systeem SYNC uitvoeren met de andere partij om aan te geven dat de taakupdate is ontvangen en verwerkt. Voor de synchronisatie is het belangrijk dat het geïntegreerde systeem dezelfde updateCount heeft als de versie die momenteel op GRIDSZ staat. Als een lagere updateCount wordt gesynchroniseerd, moet het systeem dat de INDICATION heeft geïnitieerd nog steeds INDICATIONS verzenden voor de niet-gesynchroniseerde laatste updateCount.
Daarna kan het geïntegreerde systeem een nieuwe conversie starten, te beginnen met een INDICATION, om de andere partij op de hoogte te brengen van uw versie van de taak.
Opmerking: het is voor GRIDSZ NIET mogelijk GRIDSZ terug te keren naar een eerdere versie. De huidige versie is en blijft de waarheid, ook als het andere systeem dit niet kan accepteren.

UpdateCount is hoger dan de huidige UpdateCount

Dit is het ‘sunny-day’-scenario. Een andere partij heeft een update doorgevoerd en loopt nu verder voor op de andere partij wat betreft updates. De versie van de taak met de lagere `updateCount` wordt verouderd. En de ontvangen versie van de taak (met de hogere `updateCount`) fungeert als de nieuwe ‘waarheid’.
Het is nu de taak om de ontvangen taak en de opgeslagen taak samen te voegen tot een nieuwe, consistente versie. Meestal is dit zo simpel als het overschrijven van de oude versie van de taak met de opgehaalde versie. Het wordt complexer wanneer de ontvangen update niet acceptabel is voor de andere partij. Bijvoorbeeld als GRIDSZ de taak in een ‘end-status’ GRIDSZ en vervolgens een update ontvangt van het geïntegreerde systeem om deze terug te zetten naar een ‘open-status’.
In dit geval GRIDSZ een SYNC terug met een toelichting en een opgegeven reden. Dit betekent automatisch dat de versie niet wordt geaccepteerd en dat de vorige versie nog steeds de geldende versie is. Aangezien GRIDSZ terugkeren naar een vorige versie, wordt elke SYNC waarbij de `updateCount` gelijk is aan de huidige `updateCount` beschouwd als een ‘SYNC-ok’ van het geïntegreerde systeem, zelfs als de toelichting en reden zijn ingevuld.
Door helemaal geen SYNC te verzenden, zal het andere systeem het herhalingsschema starten en INDICATIONS blijven verzenden. In deze scenario’s wordt aanbevolen om de oorzaak te achterhalen waarom de update niet wordt geaccepteerd. Indien het gaat om een onverwacht JSON-antwoord of een onverwachte waarde, kunt u het beste contact opnemen GRIDSZ dit gezamenlijk nader te onderzoeken.
Opmerking: het is voor GRIDSZ NIET mogelijk GRIDSZ terug GRIDSZ keren naar een eerdere versie. De huidige versie is en blijft de geldende versie, ook als het andere systeem dit niet kan accepteren.

Support rooktests

Het protocol ondersteunt een optionele HTTP-header met de naamgridsz’. Wanneer deze HTTP-header in een verzoek aanwezig is en de waarde ervan ‘TRUE’ is, geeft dit aan dat het betreffende gesprek deel uitmaakt van een test. Deze header wordt doorgaans gebruikt voor rooktests in de productieomgeving. Het verzoek moet op de gebruikelijke manier worden verwerkt, maar er mogen geen daadwerkelijke fysieke acties worden ondernomen. Partijen die het Equitri-protocol implementeren, worden aangemoedigd om logboekregistratie op debug-niveau te implementeren die wordt geactiveerd door dezegridsz.

Een normale taak (aangemaakt zonder de header `gridsz`) die een update ontvangt met de header `gridsz`, is reden tot bezorgdheid. Mogelijk raken testtaken en normale taken door elkaar gehaald. Een testtaak (aangemaakt met de headergridsz) die een update ontvangt zonder de headergridsz is geen reden tot ongerustheid. Mogelijk support de andere partij support HTTP-header niet.
Wees voorzichtig met het gebruik van testtaken in de productieomgeving. Zorg ervoor dat alle betrokken partijen op één lijn zitten, om te voorkomen dat daadwerkelijk werk fysiek wordt voltooid.

GRIDSZ : een bestaande taak GRIDSZ of een nieuwe taak aanmaken

Dit verloopt in drie stappen: het verzoek om een indicatie (Gridsz het geïntegreerde systeem), het opvraagverzoek (waarbij het geïntegreerde systeem informatie aan Gridsz verstrekt) en de synchronisatie ter bevestiging.

1. Indicatie van inkomend verkeer

De indicatie op initiatief van Gridsz:

  1. Geef toestemming voor het verzoek, zoals overeengekomen tijdens de implementatie, op basis van de in Gridsz opgeslagen autorisatiegegevens Gridsz hiervoor kan het nodig zijn om OAuth 2.0-tokens te verzamelen)
  2. (Als de headergridsz de waarde ‘TRUE’ heeft, schakel dan de foutlogboekregistratie in)
  3. Lees updateCount uit de INDICATION
  4. (Zou kunnen: loggen „indicatie ontvangen voor update updatecount op taskId van orgId”)
  5. Sla het feit dat er een update beschikbaar is voor de taak op, samen met de volgende gegevens:
    • orgId (verplicht)
    • systemId (verplicht)
    • taskId (verplicht)
    • updateCount (verplicht)
    • x-request-id (zou kunnen),
    • x-correlatie-id (zou kunnen)
    • requesttime (zou kunnen)
    • waarde vangridsz(verplicht indien aanwezig)
  6. Wis eerdere update-vermeldingen voor dezelfde orgId en taskId met een lagere updatecount

2. Uitgaande opvraging

De opvraging vanuit Gridsz:

  1. Bepaal het op te roepen eindpunt op basis van de omgeving, orgId en taskId in de INDICATION
  2. (Lees de waarde van x-gridz-test en stel, indien gevonden, de http-headergridsz in op die waarde)
  3. Voer een FETCH-verzoek uit op het eindpunt; haal de informatie over de nieuwe taak op
  4. Controleer of de taakgegevens correct zijn opgebouwd:
    • Geldige JSON die voldoet aan de Open API-definitie voor de nieuwste API-versie
    • Geldige JSON die voldoet aan de bedrijfsvalidaties
  5. Als de opdracht niet correct is opgesteld: zoek de oorzaak en neem Gridsz nodig contact op met Gridsz via
    . Opmerking: GRIDSZ INDICATION verzenden totdat er een SYNC is verzonden
    (EINDE VAN DE STROOM)
  6. Als de gegevens correct zijn opgebouwd:
    • Sla de taak op in de taakopslag
    • Oude taakgegevens uit de taakopslag ophalen
    • Voer een samenvoeging uit tussen de oude en nieuwe taakgegevens
    • Als het resultaat van het samenvoegen afwijkt van de oude taakgegevens, sla dan de samengevoegde taakgegevens op in de taakdatabase
    • Ontgrendel de taak in de takenlijst
  7. Stuur SYNC naar het eindpunt.

3. Uitgaande synchronisatie

De synchronisatie ter bevestiging:

  1. Stuur een SYNC-verzoek naar het eindpunt van de FETCH
  2. Er is geen herhalingspoging voor een SYNC-bericht. Als het verzoek/antwoord mislukt, kun je de uitzondering en eventuele foutcodes en toelichtingen, zoals vermeld in het SYNC-bericht, vastleggen. Vertrouw op het herhalingsschema van de andere partij om het opnieuw te proberen.
  3. Verwijder de update-informatie die tijdens de indicatie is opgeslagen

Geïntegreerd systeem voor het bijwerken van een bestaande taak of het aanmaken van een nieuwe taak

Dit kan weer worden onderverdeeld in drie stappen: het indicatieverzoek (het geïntegreerde systeem naar Gridsz), het opvraagverzoek (Gridsz informatieGridsz uit het geïntegreerde systeem) en de synchronisatie ter bevestiging.

1. Indicatie van uitgaande berichten

Het geïntegreerde systeem detecteert een verandering (die Gridsz het vorige scenario niet door Gridsz werd veroorzaakt) en wil Gridsz de hoogte brengen door een melding naar Gridsz te sturen:

  1. Geef toestemming voor het verzoek, zoals overeengekomen tijdens de implementatie (hiervoor kan het nodig zijn om OAuth 2.0-tokens te verzamelen)
  2. (Als de headergridsz de waarde ‘TRUE’ heeft, schakel dan de foutlogboekregistratie in)
  3. Voeg 1 toe aan de waarde van `updateCount` die is opgeslagen in het bestaande taakrecord binnen het geïntegreerde systeem (gebruik 1 voor nieuwe taken)
  4. (Zou kunnen: loggen „verzendindicatie voor update updateCount op taskId van orgId”)
  5. Stuur een melding naar Gridsz de volgende gegevens:
    • orgId (verplicht)
    • systemId (verplicht)
    • taskId (verplicht)
    • updateCount (verplicht)
    • x-request-id (zou kunnen),
    • x-correlatie-id (zou kunnen)
    • requesttime (zou kunnen)
    • waarde vangridsz(verplicht indien aanwezig)

Wacht niet op een reactie en probeer deze ook niet te lezen. Probeer geen uitzonderingen op te vangen, maar vertrouw op het herhalingsschema om het opnieuw te proberen.

2. Inkomende ophaling

Gridsz op de melding uit de vorige stap door de taak op te halen van het afgesproken eindpunt:

  1. Neem de oproep naar het eindpunt aan op basis van de overeengekomen authenticatie
  2. (Lees de waarde van x-gridz-test en stel, indien gevonden, de http-headergridsz in op die waarde)
  3. Geef een 404-foutmelding als de taak niet in het geïntegreerde systeem wordt gevonden
  4. FETCH-informatie verstrekken door de taakgegevens uit het geïntegreerde systeem te laden en op te maken

3. Inkomende synchronisatie

Gridsz de informatie uit de vorige stap en stuurt Gridsz een PUT-verzoek naar het eindpunt om de synchronisatie te bevestigen:

  1. Verwerk het geauthenticeerde SYNC-verzoek naar het eindpunt van de FETCH
  2. Als de SYNC een ingevulde reden en toelichting bevat, betekent dit dat GRIDSZ de update niet GRIDSZ geaccepteerd en dat de vorige versie nog steeds de master is

De Indication-Fetch-Sync verloopt misschien niet altijd vlekkeloos, maar het protocol zou, zoals hierboven beschreven, op een soepele manier een nieuwe poging moeten ondernemen. Foutcodes en toelichtingen uit de synchronisatiestap moeten echter correct worden verwerkt (en aan de gebruikers worden gemeld) om eindeloze lussen te voorkomen.