Veldmapping en regels

De koppeling levert de velden; jij bepaalt waar ze in de hub landen, hoe waarden heten, en welke records meegaan. Drie schermen, in deze volgorde.

1Veldmapping

Koppel → Koppelingen & sync → een koppeling → Wat synchroniseren → Veldkoppeling. Je ziet één tabel: een rij per veld, gelezen in de richting waarin de data reist. Uitgaand staat links het hubveld met wat het leest, en rechts waar het bij het andere systeem landt; inkomend andersom. Een rij die je hebt aangepast krijgt het label override. Rijen zonder dat label volgen automatisch updates van de koppeling.

Kolom	Wat je ziet
Hub field · source	Het hubveld, en wat het leest: delivery_name then customer_name is een terugval, een paarse chip een expressie
Het andere systeem	Waar het landt (of vandaan komt). Het pad dat alle rijen delen staat één keer in de kolomkop
Adjustments	Constant, transforms en default in het kort
Example	Wat de rij oplevert voor een echt record
On	Wisselt deze koppeling dit veld überhaupt uit

De tabel is opgedeeld in secties. Bovenaan het record zelf (Orderkop), daaronder elke verzameling regels met een eigen kopregel, bijvoorbeeld Orderregels · per regel uit items[]: wat de rijen zijn, waar ze vandaan komen en hoeveel velden het zijn. In een regelsectie is item de regel (het record zelf lees je als parent), en de kolom Example toont de waarde van de eerste regel. In de kopregel staat welke dat is (regel 1 van 3); beweeg over een waarde voor die van alle regels. Zoeken, Alleen aangepaste rijen en niet gemapt werken per rij; een sectie waarvan niets overblijft, verdwijnt mee. Hetzelfde geldt voor facturen, verzendingen, retouren, winkelwagens en de varianten en prijzen van een product, en uitgaand voor een regelblok (lines.$each) in wat Nexym verstuurt.

Een regelveld toevoegen

Stuurt de bron per regel iets mee dat de hub nog niet kent, zoals het producttype van Magento, klik dan in de regelsectie op + Regelveld toevoegen:

1. Kies bij Doel een regelveld, of + Nieuw veld… en typ een naam (product_type). Een nieuwe naam wordt bij opslaan een eigen regelveld van je project.
2. Vul bij Bron in wat er uit de regel gelezen moet worden: een veld (product_type), een pad (extension_attributes.x) of een expressie ({{ parent.increment_id }}-{{ item_id }}). De lijst biedt de velden van de eerste regel van het voorbeeldrecord; Velden ontdekken vult hem aan met wat de bron nu echt stuurt.
3. Klik op Opslaan. De volgende import vult het veld op elke regel; tot dan toont Example wat de test op de eerste regel van de bron leest.

Een regelveld haal je weg met Verwijderen in het paneel en daarna Opslaan.

Waar zie je regelvelden?

Een regelveld staat op de regel, niet op de order zelf. Open de order (of factuur, offerte, retour, verzending of winkelwagen) en ga naar het tabblad Lines:

• Boven de tabel staat hoeveel regelvelden er zijn, bijvoorbeeld 2 regelvelden · klik een regel open.
• Rechts op elke regel staat een knopje als 1/2 (ingevuld / totaal). Klik erop, of ergens op de regel, en de regel klapt open met per regelveld de naam, de code (met kopieerknop) en de waarde. De productnaam opent nog steeds het product.
• niet ingevuld betekent dat de bron voor die regel niets meestuurde.
• Wordt gevuld bij de volgende import — of klik Opnieuw ophalen betekent dat de order binnenkwam vóórdat je het regelveld toevoegde. Wacht op de volgende import, of klik bovenaan het paneel op Opnieuw ophalen: die haalt alleen deze order opnieuw op en vult het veld op elke regel.

Het tabblad Fields toont de velden van de order zelf. Onderaan staat een blok Regelvelden met hoeveel waarden er ingevuld zijn en een knop Bekijk per regel naar het tabblad Lines.

Een orderregel heeft ook een Brand name (brand_name): het merk van het artikel op die regel, als naam (“Beko”). Heeft je orderbestand een merkkolom per regel, kies dan bij die kolom Brand name onder de regelvelden. Een lege cel laat het merk leeg.

Inkoopprijs en marge

Elk product en elke variant heeft een Cost price (cost_price): wat het artikel jou kost, zonder btw, in de valuta van de prijs. Magento en Exact vullen hem vanzelf; bij een ERP of een bestand kies je bij de juiste kolom Cost price. Een lege waarde bij de bron haalt de inkoopprijs ook in Nexym weg.

Margin (margin), Margin % (margin_pct) en de twee factoren rekent Nexym zelf uit, ze worden nooit geïmporteerd:

Veld	Berekening	€ 899 incl. 21% btw, inkoop € 650
Margin	verkoopprijs excl. btw − inkoopprijs	€ 92,98
Margin %	marge ÷ verkoopprijs excl. btw × 100	12,51
Margin factor (incl. VAT) (margin_factor)	verkoopprijs incl. btw ÷ inkoopprijs	1,38
Margin factor (excl. VAT) (margin_factor_net)	verkoopprijs excl. btw ÷ inkoopprijs	1,14

De verkoopprijs is de actieprijs zolang die loopt, anders de gewone prijs. Staan je prijzen exclusief btw, dan rekent Nexym de prijs incl. btw uit met het btw-tarief van het product. De factoren zijn afgerond op twee decimalen, en een regel vergelijkt dat afgeronde getal: wat je ziet, is waar de regel op test. Zonder inkoopprijs of zonder prijs (of een prijs van 0) is de marge leeg.

Welke van deze Nexym op het scherm “marge” noemt, kies je onder Beheer → Algemeen → Marge. Die keuze verandert geen veld: een regel op Margin % blijft de brutomarge lezen, ook als je winkel met een factor rekent. Wil je een regel als “marge onder 1,5”, gebruik dan Margin factor (incl. VAT). Je gebruikt ze in regels, rapporten, sjablonen en feeds, en je ziet ze in het productdetail (een negatieve marge in rood).

Opgepast

Inkoopprijs en marge zijn intern. Ze gaan nooit naar je zoekfunctie, de chat, de advisor, pop-ups of publieke API’s, en niet naar een feed of een andere shop tenzij je ze daar zelf koppelt. Magento schrijft zijn eigen cost-attribuut terug naar Magento; dat is een veld dat alleen in de Magento-admin te zien is.

Een rij openen

Klik op een rij en er klapt één paneel open onder die rij, met alles over dat veld. Met het bekerpictogram opent hetzelfde paneel met de test bovenaan.

• Adjustments, in de volgorde waarin de sync ze toepast:
  1. Constant: een vaste waarde. Als je hem invult, wordt de bron niet gelezen en gaat deze waarde verder.
  2. Transforms: bewerkingen op volgorde, elk met een eigen kaart: trimmen, afronden, een datumnotatie, een opzoektabel, zoeken en vervangen, een sjabloon. Verschuif ze met de pijlen.
  3. Default: de standaardwaarde; vult alleen in als er daarna nog niets is.
• Test with: laat het vak leeg om de rij op het voorbeeldrecord (of de eerste regel) uit te voeren, of typ een waarde. Run toont het resultaat en wat elke stap ervan maakte.
• Source en Target: waar de waarde gelezen wordt en waar hij landt. Typ je {{, dan verschijnt een lijst met de velden die je kunt gebruiken; na | de filters.
• Reset zet een aangepaste rij terug naar de koppeling.
• Opslaan bewaart de mapping, met deze rij zoals hij nu is (net als Mapping opslaan onder de tabel; ook ⌘S of Enter in een vak van de rij). Zolang er iets niet is opgeslagen, staat er Niet opgeslagen wijzigingen. Sluit je het paneel dan, vraagt Nexym eerst of je de wijzigingen wilt weggooien.

Een veld dat de koppeling niet vult, voeg je toe met + Add field of via … not mapped boven de tabel. Welk record het voorbeeld is, de recordidentiteit en Preview payload vind je in de uitklapper boven de tabel.

i

Transforms gelden voor elk record. Wil je een waarde alleen voor sommige records veranderen (“als het land BE is, dan …”), gebruik dan een regel met Set a field, zie hieronder.

Sjablonen

De transform Template / computed bouwt tekst uit velden, in dezelfde taal als de rijen van de koppeling zelf:

{{ item.reference }} - {{ item.name }} - {{ brand_name | ifempty:'onbekend' }}

item. is het record (een naam zonder item. werkt ook), __value__ is de waarde die bij deze stap binnenkomt, en filters als upper, ifempty en date werken zoals in de rest van de mapping. Onder het invoerveld staan alle velden van de entiteit, met naam en een voorbeeldwaarde uit het voorbeeldrecord; klik er een aan om hem in te voegen, of typ {{ voor dezelfde lijst. Ook je eigen velden en de extra velden van een koppeling staan erbij, apart onder Eigen velden, en werken in beide richtingen. In een regelblok (lines.$each) zijn het de velden van een orderregel, zoals brand_name. Een sjabloon met enkele accolades ({brand} {name}) van vóór deze schrijfwijze werkt ongewijzigd.

Een voorbeeld: je ERP levert art_oms en de hub wil name. Je kiest bij + Add field het hubveld name, typt art_oms, en controleert hem met Test.

Velden met een vaste lijst

Een paar hubvelden bevatten één woord uit een vaste lijst:

Veld	Kan bevatten
Product Status	active, inactive, draft
Product Type	simple, configurable, bundle, grouped
Variant Status	active, inactive

De gangbare woorden van een bron vertaalt de import zelf: enabled, 1 en publish worden active, disabled, 0, private, trash en archived worden inactive, en pending wordt draft (bij een variant inactive). Voor het type wordt variable configurable. Een lege waarde laat het veld zoals het was. Levert je bron een ander woord, vertaal het dan in die rij met een Value lookup. Anders mislukt dat record, en de run zegt welk veld, welke waarde en welke woorden wel mogen.

Waar een product verkocht wordt

Available on is de lijst van winkelcodes waarop een product aan staat en te vinden is, bijvoorbeeld wonen, tech. Zoeken op je site laat per website alleen de producten zien die die winkelcode hebben. Je kunt het veld gewoon mappen: een lijst, of tekst gescheiden door ,, | of ;. Een lege waarde betekent geen gegevens en het product staat dan overal. Alleen een echt lege lijst betekent nergens.

Heeft de koppeling Store views aangevinkt, dan leest Nexym de beschikbaarheid per winkel zelf uit, en dat gaat voor. Een gemapt Available on wordt dan niet gebruikt.

!

“On” uitzetten wist ook wat er al stond. Dat is met opzet: een kolom die blijft staan op de waarde van de dag dat je hem uitzette, is de slechtste van de twee. Zet je hem weer aan, dan vult de volgende import hem opnieuw.

2Waardevertalingen

Twee systemen die elkaar niet kennen, noemen hetzelfde anders. Onder Value mapping vertaal je per soort: orderstatus, eenheid, land, vervoerder.

ERP           Hub           Shop
"VERZ"    →   shipped   →   "fulfilled"
"GEANN"   →   cancelled →   "cancelled"

De hub heeft één woordenlijst. Elke koppeling vertaalt naar díe woorden, nooit naar die van een ander systeem — anders vertaal je bij een derde systeem weer opnieuw.

Voorraadstatus

Of een product te bestellen is, zegt de hub in drie woorden: in_stock (op voorraad), out_of_stock (niet op voorraad) en backorder (nabestelbaar: nu niets op voorraad, wel te bestellen). De kaart Voorraadstatus staat bij elke koppeling die voorraad importeert, met de standaardvertaling van de connector en de waarden uit je data die nog niet gemapt zijn.

• Magento zegt het niet in een woord maar met de voorraadgegevens. Nexym maakt er een woord van: backorders_allowed (0 of minder op voorraad, nabestellen toegestaan), in_stock (meer dan 0 en op voorraad), in_stock_without_qty (0 of minder maar wel „op voorraad”, bijvoorbeeld zonder voorraadbeheer) en out_of_stock. Standaard worden de middelste twee backorder.
• Een bestand (CSV, feed) kan een kolom met een woord hebben. Map die kolom op Stock status; gangbare woorden als op voorraad, leverbaar, nabestelbaar, uitverkocht, in stock en backorder zijn al vertaald.
• Bron. Zegt je shop het in een productattribuut, zoals een levertijd („Binnen 5 werkdagen”) of een stoplicht, kies dat attribuut dan bovenaan de kaart. De waarden van dat attribuut verschijnen als „in je data, niet gemapt”; map ze op een van de drie woorden.

Een gemapte waarde beslist. Is een waarde niet gemapt, dan beslist de hoeveelheid: boven 0 op voorraad, onder 0 (of 0 met nabestellen toegestaan) nabestelbaar, anders niet op voorraad. Geen voorraadregel ontvangen is „geen voorraaddata”, nooit „niet op voorraad”. Wat je opslaat of als bron kiest, geldt meteen voor de voorraad die al in Nexym staat.

Alles leest dezelfde status: de productlijst en het filter Voorraadstatus, de productdetails, Site search (Alleen op voorraad houdt nabestelbare producten, de tegel zegt „Nabestelbaar”), de chat, de keuzehulp, feeds (availability wordt backorder), de maatwijzer en „Mail mij als hij terug is” (die wacht op echt op voorraad).

3Regels

Rules bepaalt welke records meegaan en hoe ze eruitzien, per koppeling en per richting. Drie soorten secties:

• Exclude — dit gaat niet mee. Bijvoorbeeld: producten zonder afbeelding.
• Include only — alleen dit gaat mee. Bijvoorbeeld: alleen merk ACME.
• Set a field — verander een waarde vlak voor verzending.

Onderaan staat Check quantity. Dat telt tegen de data die al in de hub staat en laat zien: hoeveel records er zijn, hoeveel elke sectie raakt, hoeveel er zouden veranderen en hoeveel er zouden afvallen — met voorbeelden en de reden erbij. Kijk daar altijd naar voor je opslaat.

Een regel op marge, bijvoorbeeld “exclude als Margin % kleiner is dan 20”: een lege marge telt daar als 0. Voeg dus Cost price is not empty toe als tweede voorwaarde, anders valt elk product zonder inkoopprijs ook af.

i

Een regel hoort bij een koppeling, niet bij het record. “Geen artikelen zonder foto naar de webshop” is waar richting de shop en onzin richting je ERP. Daarom staan regels per koppeling én per richting.

Wat een regel met een run doet

Een run leest alleen wat sinds de vorige run veranderde, plus wat nog open staat (wachtend of mislukt). Waar het kan, stelt Nexym je regels meteen bij het ophalen: een export haalt alleen de records op die aan de regel kunnen voldoen, en een import van Magento-orders vraagt de shop zelf om de statussen, winkels of orderdatums uit je Include only-regels. De regel zelf beslist daarna nog steeds per record.

Een record dat een regel tegenhoudt, wordt één keer beoordeeld. Pas als het record verandert, kijkt Nexym opnieuw. Een regel met een rollende datum (“in de laatste 7 dagen”, “meer dan 2 uur geleden”) is de uitzondering: die records worden elke run opnieuw bekeken.

Opgepast

Een gewijzigde regel verstuurt nooit vanzelf oudere records. Voldoen er na je wijziging oudere records aan de regel, dan zie je dat als melding, bijvoorbeeld op het tabblad Exports van Sathena: “N oudere orders voldoen nu aan de regels”. Met Ook deze versturen gaan ze alsnog mee, nadat je het vinkje zet en de naam van de koppeling typt.

Website als voorwaarde. In regels die over een bezoeker gaan (popups, boostregels in Site search) kun je ook kiezen op Website of Taal van de website. In deze regels niet: een synchronisatie, een feed of een segment draait zonder bezoeker op een pagina, dus “op welke website is de bezoeker” heeft hier geen antwoord. Zie Meerdere websites in één project.

Validatieregels

Losse schermen: Data → Datakwaliteit → Validatie. Een validatieregel keurt records af die niet aan een eis voldoen (“een order moet een dienstcode hebben”). Per regel zie je met Check hoe veel records hij vandaag zou tegenhouden, en of een fout het record overslaat of alleen gemeld wordt.

Data → Validatie: zonder regels beweegt elk record. Begin met één regel voor je belangrijkste koppeling.

Wat is het verschil tussen een sync-regel en een validatieregel?

Een sync-regel is een keuze (“dit hoeft niet naar dit systeem”), een validatieregel is een eis (“zonder dit veld deugt het record niet”). De eerste filtert stil, de tweede laat een spoor na in Operaties → Mislukte records, zodat iemand het kan repareren.