Xwift Boost: de saaie integratie die al jaren draait

Het order dat vier keer wordt ingetikt

De klant is een productiebedrijf, en die producten moeten naar werven in heel Europa. Elke levering begint als een transportorder.

Voor dit platform bestond, werd dat order meer dan één keer ingetikt. Eén keer in het transportmanagementsysteem, zodat de planner het zag. Eén keer in het formaat dat het systeem van de vervoerder wou. Nog eens, net iets anders, voor het trackingplatform. En ten slotte in de facturatie, want iemand moet dat transport factureren.

Vier systemen, één order, en telkens een mens die ertussen overtikt. Elke overtik is een kans om twee cijfers in een postcode om te wisselen, of de ophaalcontactpersoon kwijt te spelen, of het tarief van het verkeerde land te factureren.

De fout is nooit spectaculair. Er crasht niets.

Een vrachtwagen staat gewoon op het verkeerde adres, en iemand hangt een namiddag aan de telefoon om uit te zoeken waarom.

Een laadperron 's nachts onder natriumlicht, een chauffeur die een papieren vrachtbrief vergelijkt met de etiketten op een stapel kratten Eén order, vier systemen, en bij elke overdracht een nieuwe kans om een adres verkeerd in te tikken.

Wat het platform doet

Een order komt binnen als webhook. Hun systeem post het, geauthenticeerd met een gedeeld geheim, en vanaf dat moment raakt niemand het nog met de hand aan.

Het platform leest de payload, of die nu als JSON of als XML aankomt. Het zoekt de prijstabel op voor het bestemmingsland en berekent de transportkost. Het mapt de klantcodes van de klant op interne opdrachtgevers, zoekt of maakt het opdrachtgeverrecord, en zoekt of maakt drie aparte contacten, want een transportorder heeft een factuuradres, een leveradres en een ophaaladres, en dat zijn zelden dezelfde plaatsen.

Daarna schrijft het het order weg en genereert het TAS XML, het formaat dat de transportpartners spreken.

Die XML vertrekt drie kanten op: via FTP naar Xwift, via FTP naar Go4Log en via SFTP naar FleetGo. Afhankelijk van hoe de opdrachtgever ingesteld staat, gaat ze ook naar TransForm of naar XwiftOS.

De facturatie loopt via Billit, live tegen de productie-API, niet tegen een sandbox.

Een order dat om negen uur binnenkomt, zit in elk systeem stroomafwaarts voor iemand het beheerscherm opent.

Eén binnenkomend order, één keer ingelezen, daarna weggeschreven naar elk systeem dat het nodig heeft.

De beheerkant

Bovenop dit alles zit een Next.js-beheerinterface, want automatisering die je niet kan inspecteren is geen automatisering maar een zwarte doos die af en toe je week verpest.

Planners kunnen elk order opzoeken, zien wat er binnenkwam, zien wat er gegenereerd werd, en de integratielog van elke uploadpoging bekijken. Ze kunnen een PDF hergenereren, mailen, de factuur aanmaken, of het order opnieuw naar de integraties duwen als de FTP-server van een partner plat lag op het moment van de webhook.

Dat laatste weegt zwaarder dan het klinkt. Partnersystemen vallen uit. Dat de gegenereerde XML per order op schijf blijft staan, is precies waarom een replay een knop is en geen supportticket.

In de stack zit ook een kleine Go-service die één ding doet: cellen opzoeken in geüploade spreadsheets. Landspecifieke prijzen komen als XLSX vanuit de business, en in plaats van iemand te vragen dat om te zetten, leest het platform het waar het aankomt.

Een planner op het eind van de dag aan een volle bureau in een schemerig kantoor, scrollend door records op een laptop met afdrukken ernaast Automatisering verdient vertrouwen door zichtbaar te zijn, niet door stil te zijn.

Drie talen, met reden

De API is PHP 8.2 op Symfony 6.4 met MySQL. De beheerinterface is Next.js 13 met React en Material UI. De spreadsheetlookup is Go 1.21, gegenereerd uit een eigen Swagger-spec.

Dat is geen architectuurmode. Elk stuk heeft de vorm van zijn taak. De Symfony-API bevat de businessregels, de integraties en de persistentie, en het is saaie gelaagde code: presentatie, applicatie, infrastructuur, met de webhookflow als een dunne controller die naar één actie delegeert. De frontend is een frontend. De spreadsheetlezer is veertig bestanden die een cel uit een XLSX halen en heeft geen databank.

Daarnaast loopt een geleidelijke herschrijving van het PHP-orderpad naar Go, op dezelfde MySQL-databank, per order omschakelbaar met een vlag. Vandaag staat die vlag uit in productie en houdt PHP de flow.

Migraties die je order per order kan uitzetten zijn de enige soort die de moeite loont op een systeem van deze leeftijd.

Wat jaren productie je leren

Dit platform draait al jaren, en dat is iets anders dan er een lanceren.

De klantmapping is code, geen configuratie. De klantcodes van de klant mappen naar interne opdrachtgevers in een klasse die je moet aanpassen als de mapping verandert. Niet elegant. Wel eerlijk: die mapping is businesslogica met uitzonderingen erin, en doen alsof het een configuratietabel is had de uitzonderingen verstopt, niet weggenomen.

Het bestandssysteem hoort bij het ontwerp. De binnenkomende JSON en de gegenereerde XML staan per order op schijf, en de integratielog leest ze terug. Dat leek jarenlang een implementatiedetail. Het is het auditspoor, en het is wat replay mogelijk maakt.

Uploads kunnen uit. In productie kan het webhookpad de uploads overslaan terwijl het bewaarpad in de beheerinterface ze wel duwt. Dat je die twee kan loskoppelen, is wat je toelaat een partnerintegratie te debuggen zonder de orderinstroom stil te leggen.

Omgevingen lopen uiteen. Productie draait op Docker Compose op een oude host, staging is verhuisd naar k3s, en de DNS van beide wijst toevallig naar hetzelfde adres. Wie ooit een uur de verkeerde omgeving heeft zitten debuggen, weet waarom dat feit in hoofdletters genoteerd staat.

Wie dit nodig heeft

Fabrikanten die veel verzenden en de trucks uitbesteden. Wil elke transportpartner een ander bestand op een andere plaats, dan is die integratie jouw probleem, niet het hunne.

Iedereen wiens orderdata meer dan twee systemen doorkruist. De kost van een overtik is niet de minuut die het duurt. Het is de foute levering, drie weken later, die niemand nog kan traceren.

Bedrijven met een werkend proces en geen zin om het te vervangen. Dit platform verving de systemen van de klant niet, en die van Xwift, FleetGo of Billit evenmin. Het zit ertussen en verplaatst het order.

Waar het op neerkomt

Er is hier geen dashboard met een cijfer dat omhoog gaat. De maatstaf is dat transportorders correct in elk systeem terechtkomen dat ze nodig heeft, zonder dat iemand ze een tweede keer intikt, en dat dit al jaren klopt.

Zo ziet een goede integratie eruit. Saai, in de beste zin. Het interessante is wat er gestopt is met gebeuren.

Xwift Boost is gebouwd door glue.blue - wij plakken oplossingen op problemen. Definitief.

Wordt jouw order in vier systemen overgetikt? → Neem contact op

Gepost in: Transport, Logistiek, Systeemintegratie, Productie