Wat is veldmapping?

Veldmapping in twee zinnen

Twee systemen bewaren zelden hetzelfde gegeven op dezelfde manier. Shopify kent een klant aan zijn e-mailadres, Exact Online aan een intern id; Shopify bewaart een prijs inclusief btw, Exact exclusief. Veldmapping is de lijst die per veld vastlegt hoe het ene in het andere wordt vertaald.

Een regel uit zo'n lijst ziet er zo uit:

{
  "bron": "shopify.order.lineItems.discountedUnitPriceSet",
  "doel": "exact.SalesOrderLines.UnitPrice",
  "soort": "omzetten",
  "regel": "als taxesIncluded = true: delen door 1 + btw-tarief van de regel",
  "afronden": "2 decimalen, per regel",
  "bij fout": "order op de controlelijst"
}

Een koppeling tussen een webshop en een ERP heeft al snel tientallen van zulke regels: voor klanten, artikelen, orders, adressen, betalingen en btw. Bij de meeste is één regel tekst genoeg. Bij een handvol zit het echte werk.

Drie soorten mapping

Elke regel valt in een van drie soorten.

Direct lijkt het eenvoudigst, maar ook daar zit een grens. In Exact Online heeft een artikel een Description van 60 tekens. Een producttitel van 74 tekens gaat er direct heen en komt er afgekapt uit, zonder melding. Bij een directe mapping hoort dus een controle op lengte en type.

Opzoeken is de soort die het vaakst ontbreekt in een eerste opzet. Het doelsysteem verwacht een eigen sleutel en de bron heeft die niet. Een vertaaltabel is daarbij iets anders dan een zoekactie. Een zoekactie vraagt het doelsysteem welk record bij een e-mailadres hoort. Een vertaaltabel is een lijst die iemand bijhoudt: betaalmethode iDEAL wordt conditie ID, land BE wordt omzetrekening 8010. Komt er een nieuwe betaalmethode bij, dan moet de tabel mee.

Rekenvoorbeeld: één Shopify-order naar Exact Online

Bakker Installatie B.V. bestelt 12 stuks van artikel KB-2210 in de webshop. De prijs in Shopify is 18,15 inclusief 21% btw. Zo landen de velden in een verkooporder in Exact Online:

• name en lineItems.quantity gaan direct over.
• De prijs wordt omgezet: 18,15 gedeeld door 1,21 is 15,00. Twaalf stuks is 180,00 exclusief en 217,80 inclusief btw, gelijk aan 12 keer 18,15 in de webshop. Bij een prijs die niet zo mooi deelt, zoals 17,99, levert afronden per stuk (14,87 maal 12 is 178,44) een ander bedrag op dan afronden over de regel (17,99 maal 12 gedeeld door 1,21 is 178,41). Drie cent per regel is genoeg om een automatische afletterregel te laten mislukken; de keuze staat daarom in de mapping. De uitwerking staat in bedragen en btw mappen.
• email en lineItems.sku worden opgezocht. Exact verwacht in OrderedBy en Item een intern id, en beide velden zijn volgens de API-documentatie van Exact verplicht.
• paymentGatewayNames gaat via de vertaaltabel naar PaymentCondition.

Opzoeken kost verzoeken, en Exact Online staat 60 verzoeken per minuut en 5.000 per dag per administratie toe. Een webshop met 40 orders per dag en gemiddeld 3 orderregels zoekt per order 1 klant en 3 artikelen op: 40 maal 4 is 160 verzoeken per dag, alleen om ids te vinden. Een koppeling die de 4.000 artikelen één keer per nacht ophaalt via het bulk-endpoint, met 1.000 artikelen per verzoek, doet dat in 4 verzoeken en zoekt daarna lokaal. Hoe zo'n budget verder wordt verdeeld, staat in Exact Online API limieten.

Wat gebeurt er als twee velden naar één veld gaan?

Een doelveld kan maar één waarde hebben. Worden er twee bronvelden naartoe gemapt, dan moet de regel zeggen welke wint. Ontbreekt die regel, dan wint meestal de laatste toewijzing. Er zijn standaardkoppelingen die dat zo documenteren: de laatst bekende waarde gaat mee, ook als die leeg is.

Een voorbeeld. De bedrijfsnaam voor het afleveradres wordt eerst gevuld uit het factuuradres en daarna uit het afleveradres:

De klant liet de bedrijfsnaam bij het afleveradres open, omdat hij gelijk is. Stap 2 overschrijft een goede waarde met niets, en op het verzendlabel ontbreekt de bedrijfsnaam. De regel die het oplost is één zin: neem het afleveradres, en als dat leeg is het factuuradres. Wie zo'n regel niet uitschrijft, ontdekt het bij een pakket dat terugkomt. Meer over adressen staat in adresvelden mappen.

Hetzelfde speelt per systeem. Als de prijs uit het ERP komt en ook in de webshop wordt aangepast, overschrijven de twee elkaar bij elke ronde. Per veld staat daarom vast welk systeem leidend is, niet per systeem.

Verplichte velden die de bron niet heeft

Elk doelsysteem heeft velden zonder welke het een record weigert. Bij een verkooporder in Exact Online zijn dat OrderedBy en de orderregels met Item, allebei een id dat alleen Exact kent. Andere velden zijn niet verplicht, maar wel nodig voor een goede boeking. WarehouseID op de order werkt volgens de documentatie alleen in de edities Plus, Professional en Premium van Handel en Productie.

Voor elk verplicht veld legt de mapping een van drie dingen vast:

Een vaste waarde is de valkuil. Hij werkt tot het tweede magazijn erbij komt, en dan gaan alle orders nog steeds naar het eerste. De volledige lijst van zulke velden per systeem staat in verplichte velden die de bron niet heeft.

Waarom mapping het meeste werk is

Een verbinding met een API leggen is het kleinste deel van een koppeling. De mapping is het grootste, omdat elke regel een vraag is over jouw administratie en niet over de techniek. Welke grootboekrekening hoort bij een bestelling uit België? Is een klant die met een ander e-mailadres bestelt een nieuwe debiteur? Welke voorraad mag de webshop zien?

Validatie hoort bij elke regel. Een record dat niet door de mapping komt, gaat op een controlelijst met het veld en de reden, en wordt niet stil overgeslagen.

Wat betekent dit voor je koppeling?

De mapping is het deel van de koppeling dat bij jouw bedrijf hoort. Wij leggen hem met je vast, veld voor veld, inclusief de vertaaltabellen, de regels voor lege velden en welk systeem per veld leidend is. Daarna bouwen we de koppeling erop, en de eerste runs draaien droog: je ziet per record welke waarden er in het doelsysteem zouden komen voordat er iets geboekt wordt.

Verandert er later iets, een nieuwe betaalmethode of een tweede magazijn, dan passen wij de mapping aan en zie je in het dashboard welke records eronder vallen. Een overzicht van alle stromen staat op koppelingen tussen je webshop en de systemen erachter. Vertel welke systemen je wilt koppelen, dan hoor je welke velden daar het werk zitten.