Automatisering

Systemen koppelen: API, bestandsuitwisseling of message queue

Elke maandagochtend haalt iemand een bestand uit het ene systeem en tikt de regels over in het andere. Het werkt, tot diegene ziek is, tot er een regel wordt overgeslagen, of tot twee mensen dezelfde stapel verwerken. U wilt dat de systemen dat zelf doen, en u wilt kunnen zien dat het goed is gegaan.

Systemen koppelen is niet in de eerste plaats een technisch probleem. Voor het transport bestaan drie beproefde vormen, alle drie goed gedocumenteerd. Het moeilijke zit elders: afspreken wat een klant, een order of een uur precies betekent aan beide kanten van de lijn, en vooraf vastleggen wat er gebeurt als de andere kant niet antwoordt. Een koppeling die alleen werkt als alles meezit is geen koppeling maar een demo.

Wanneer u een koppeling nodig heeft

De vraag begint niet bij de techniek, maar bij een van deze situaties.

Dezelfde gegevens worden twee keer ingevoerd, in twee systemen, door twee verschillende mensen.
Er gaat dagelijks of wekelijks een export en een import heen en weer, met de hand, en niemand ziet het als een stap wordt overgeslagen.
Een klant of leverancier vraagt of u een koppelvlak heeft om gegevens aan te leveren.
Er is al een koppeling, maar u merkt pas dat die stilstaat als er iemand belt.
De cijfers in twee systemen lopen uiteen en niemand kan aanwijzen waar dat begint.

Wat de opdracht omvat

Bouwen is het kleinste deel. Dit is de rest.

De vorm kiezen. Een API-koppeling als gegevens direct moeten kloppen; bestandsuitwisseling als het om grote hoeveelheden op een vast ritme gaat en u het bestand later wilt kunnen teruglezen; een message queue als beide kanten los van elkaar moeten kunnen draaien. Ik onderbouw ook waarom de andere twee het niet worden.
De datadefinitie. Welk veld betekent wat, welke waarden zijn toegestaan, en welk systeem heeft gelijk als beide iets anders beweren. Dit is het zwaarste deel van het werk, en het enige deel dat techniek niet voor u oplost.
Foutafhandeling. Wat er gebeurt bij een afgekeurd record, een time-out of een tegenpartij die een dag onbereikbaar is. Berichten wachten in plaats van verdwijnen, met nieuwe pogingen met oplopende tussenpozen en een grens aan het aantal.
Herhaalbaarheid. Hetzelfde bericht mag twee keer binnenkomen zonder dat er een tweede order ontstaat. Dat vraagt een kenmerk per bericht en een controle aan de ontvangende kant.
Bewaking en toegang. Zichtbaar maken dat de koppeling heeft gedraaid en hoeveel er door is gegaan, met een melding aan een mens als dat uitblijft. Plus: hoe beide kanten zich identificeren en wie de sleutels vervangt als iemand vertrekt.
Testen met uw eigen gegevens, inclusief de rommelige records. Een koppeling struikelt over uitzonderingen, niet over het voorbeeld uit de handleiding.

Wat u krijgt

Een koppeling is pas af als iemand anders hem kan draaien. Dat is werkende software, plus het papier dat nodig is om te begrijpen wat er gebeurt als het misgaat.

Een werkende koppeling in uw eigen omgeving, met broncode en configuratie bij u.
Een koppelvlakdocument: welke gegevens gaan er over, in welke richting, in welk formaat, en wat de velden betekenen.
Bewaking die u zelf kunt bekijken, met een melding wanneer de doorvoer stilvalt of de foutenrij oploopt.
Een korte storingshandleiding: wat te doen als de andere kant onbereikbaar was, hoe u opnieuw aanbiedt, en hoe u controleert dat er niets dubbel is verwerkt.
Een overdracht aan uw eigen mensen of uw beheerpartij, zodat doorgaan niet van mij afhangt.

Wat het niet is

Geen vervanging van een van beide systemen. Een koppeling herstelt een proces, geen verkeerd ingericht systeem.
Geen eenmalige datamigratie. Verwant werk, andere risico's, aparte afweging.
Geen rapportage- of dashboardtraject. Gegevens verplaatsen is iets anders dan gegevens ontsluiten voor analyse.
Geen doorlopende beheerdienst met piket. Ik lever de koppeling en de bewaking op; wie 's nachts de telefoon opneemt, spreken we apart af.
Geen koppeling buiten de andere partij om. Wil de tegenpartij geen koppelvlak bieden, dan is dat eerst een gesprek en geen bouwopdracht.

Veelgestelde vragen

API, bestandsuitwisseling of message queue: wat moet ik hebben?

Twee vragen bepalen het antwoord: hoe vers moeten de gegevens zijn, en wat mag er gebeuren als de andere kant niet reageert. Moet een wijziging binnen seconden zichtbaar zijn, dan is een API-koppeling het eenvoudigst. Gaat het om grote hoeveelheden op een vast moment, dan is bestandsuitwisseling robuuster en beter te controleren: het bestand is er nog. Moeten beide kanten los van elkaar kunnen draaien, of komen er pieken die de ontvanger niet direct aankan, dan hoort er een queue tussen: de zender levert af en is klaar, de ontvanger werkt weg in eigen tempo. Twee vormen naast elkaar in één landschap is geen ontwerpfout.

Het andere systeem heeft geen API. Kan het dan wel?

Ja, alleen langs een andere weg. We zoeken een andere uitgang: een geplande export naar een beveiligde map, een rapportage in een vast formaat, of leesrechten op een database. Wat verandert is niet de haalbaarheid maar de frequentie en de foutafhandeling. Wat ik afraad is een koppeling die de schermen van een systeem nabootst: die breekt bij de eerstvolgende update, en niemand ziet dat aankomen.

Wat gebeurt er als het andere systeem een dag plat ligt?

Dat is een ontwerpkeuze, geen ongeluk. Een bericht hoort te wachten in plaats van te verdwijnen: het blijft staan, er volgen nieuwe pogingen met oplopende tussenpozen, en na een afgesproken aantal pogingen gaat het naar een aparte stapel met een melding erbij. Komt de andere kant terug, dan loopt de achterstand vanzelf leeg. Wat u niet wilt is een koppeling die na een storing doorgaat alsof er niets is blijven liggen.

Wat als hetzelfde bericht twee keer binnenkomt?

Dan mag er niets dubbel gebeuren. Dat is wat idempotentie betekent: dezelfde opdracht twee keer uitvoeren geeft hetzelfde resultaat als één keer. Concreet krijgt elk bericht een eigen kenmerk en houdt de ontvangende kant bij welke kenmerken al verwerkt zijn. Het is het verschil tussen een koppeling die u na een storing gerust opnieuw aanzet, en een koppeling waarbij niemand de herstart durft te doen.

Hoe lang duurt het, en wat bepaalt de prijs?

Niet het bouwen bepaalt de doorlooptijd. Wat die wel bepaalt: de datadefinitie (hoeveel velden, hoeveel uitzonderingen, hoeveel partijen het eens moeten worden), de vraag of de tegenpartij een bruikbaar koppelvlak en documentatie heeft, het bestaan van een testomgeving, en de vraag of er persoonsgegevens of financiële transacties doorheen lopen. Eén koppeling tussen twee systemen die allebei een fatsoenlijk koppelvlak hebben is een korte opdracht van enkele dagen. Moet het koppelvlak nog ontworpen worden, of zitten er drie partijen aan tafel, dan wordt het een traject. De vorm spreken we vooraf af: op nacalculatie met een maximum dat ik niet overschrijd zonder overleg, of een vaste prijs per resultaat als de scope scherp is.

Wie beheert de koppeling daarna?

Uw eigen mensen of uw beheerpartij. Ik lever op met broncode, configuratie, bewaking en storingshandleiding, en draag over aan wie hem gaat draaien. Blijf ik daarna in beeld, dan is dat een losse afspraak en geen voorwaarde. Een koppeling die alleen de bouwer kan onderhouden is een risico dat u er gratis bij krijgt.

Meer binnen deze dienst

Twee systemen die nog niet met elkaar praten?

Schets kort om welke systemen het gaat en wat er nu met de hand heen en weer gaat. In een eerste gesprek zeg ik welke vorm past, en of een koppeling werkelijk het antwoord is.

Plan een kennismaking Stuur een bericht