Integration Tools – Taakopzet voor Integration Tool stappen met meerlaags data

Voor het opzetten van integraties middels BPA Platform wordt frequent gebruik gemaakt van Integration Tools – BPA Platform Stappen die gebruikt worden om een koppeling met een specifiek extern systeem te realiseren. Deze stappen bieden de mogelijkheid om binnen BPA Platform opgehaalde data te koppelen aan een extern systeem voor verdere verwerking.

Bij het koppelen van data binnen de Integration Tools is vaak de verwachting dat de data gelaagd wordt aangeboden. Hiermee wordt bedoeld dat aangeleverde data binnen de Integration Tool een kop / subregel structuur moet hebben om deze juist te kunnen verwerken. Denk qua structuur hierbij aan een verkooporder, welke per order kopregel een of meerdere orderregels aan kan bieden.

Wanneer een Integration Tool actie gebruikt wordt die meerlaags data verwacht is het noodzakelijk om een specifieke taakopzet te gebruiken om deze data correct aan te bieden. Dit knowledgebase artikel gaat in op de correcte inrichting van een dergelijke taak.

Voor de voorbeelden in dit artikel maken we gebruik van de "Exact Entity Services Integration Tool". Deze zelfde taakopzet is echter van toepassing voor alle verschillende Integration Tools die gebruik maken van gelaagde data.

Wanneer een Integration Tool actie in een taak geplaatst wordt, kan men op het tabblad "Mapping" een object en een uit te voeren actie selecteren. In de onderstaande screenshots is het mapping scherm te zien van het object "Sales Order" met de operatie "Add Sales Order" van de Exact Entity Services Integration Tool.

Aan de rechterzijde van de mapping zijn de beschikbare velden voor deze operatie te zien. Wanneer een operatie meerdere lagen bevat, zal binnen de koppelbare velden een regel te zien zijn welke voorafgegaan wordt door een [+] teken.

Regels met een [+] teken kunnen met een klik opengeklapt worden om de onderliggende velden voor deze regel weer te geven. Wanneer men een [+] teken bij de mapping ziet staan geeft dit aan dat de aangeboden data in meerdere lagen doorgegeven moet worden.

In het onderstaande voorbeeld wordt gedemonstreerd hoe een taak opgezet kan worden om met meerlaags XML data om te gaan. In dit voorbeeld gebruiken we de "Exact Entity Services Integration Tool" operatie "Add Sales Order" om verkooporders in Exact Globe aan te maken. In dit specifieke voorbeeld willen we een tweetal verkooporders aanmaken met de onderstaande eigenschappen:

• Een verkooporder voor debiteur 1 ("Orbis Software") bestaande uit twee orderregels.
• Een verkooporder voor debiteur 2 ("Ask Us") bestaande uit een enkele orderregel.

De meest basale taakopzet die gebruikt kan worden is te zien in onderstaand screenshot.

In deze taak worden de onderstaande staptypes gebruikt.

• ODBC Query: Ophalen data kopregels
• ODBC Query: Ophalen data orderregels
• Recordset to XML: Meerlaags XML data aanmaken
• Exact Entity Services Integration Tool: Aanmaken Order

Bij het aanspreken van Integration Tool stappen die uit meerdere lagen bestaan, is het noodzakelijk om voor iedere laag een separate query stap aan te maken. De resultaten van deze query stappen worden hierna in de "Recordset to XML" aan elkaar gekoppeld om de gelaagde XML te genereren.

Inhoudelijk zijn de stappen ingericht als onderstaande.

In de stap "Ophalen data kopregels" gebruiken we als voorbeeld onderstaande query. In deze query halen we enkel een orderdebiteurnummer op en een omschrijving van de verkooporder die aangemaakt moet worden.

Select
'1' as OrderDebtor,
'Bestelling Lunch - Orbis Software' as YourReference
UNION ALL
Select
'2' as OrderDebtor,
'Bestelling Lunch - Ask Us' as YourReference


In de stap "Ophalen data orderregels" maken we gebruik van onderstaande query om de data voor de verschillende orderregels op te halen. In deze query halen we het debiteurnummer van de besteller op evenals de gegevens van de orderregel zelf zoals de artikelcode, het aantal artikelen dat besteld is en de prijs van het artikel.

Select
'1' as OrderDebtor,
'Maaltijdsalade' as Itemcode,
'1' as Quantity,
'4.95' as Price
UNION ALL
Select
'1' as OrderDebtor,
'Stokbrood' as Itemcode,
'1' as Quantity,
'2.10' as Price
UNION ALL
Select
'2' as OrderDebtor,
'Stokbrood' as Itemcode,
'5' as Quantity,
'2.10' as Price


In de stap "Meerlaags XML Data aanmaken" koppelen we de resultaten van beide query stappen aan elkaar om de meerlaags XML te genereren. Om dit uit te voeren vinken we op het "Main" tabblad de beide voorgaande ODBC query stappen aan als input recordsets.

Nadat deze beide stappen aangevinkt zijn kan middels Click-n-drag een koppeling gelegd worden tussen de velden uit beide recordsets. Het idee hierachter is dat in beide query’s een veld of combinatie van velden terugkomt die het mogelijk maakt om specifieke kopregel aan een specifieke set regels te koppelen. In onderstaand voorbeeld hebben we de koppeling gelegd op het veld "OrderDebtor". Daarbij hebben we de aanname gedaan dat we per unieke debiteur een enkele order aan willen maken. Dit hoeft natuurlijk niet altijd het geval te zijn: als voor een enkele debiteur meerdere orders aangemaakt moeten worden moet de mapping hierop aangepast worden.

Let wel op dat de mapping tussen beide recordsets juist gelegd wordt. Aan de kant van de kopregels moet altijd het "Sleutel" icoon staan terwijl aan de kant van de subregels altijd een lemniscaat ("Liggende acht") getoond moet worden. Om dit te bereiken sleept men standaard velden van de "Regel" zijde van de mapping naar velden aan de "Kop" zijde van de mapping.

Binnen de Exact Entity Services Integration Tool gebruiken we de aangemaakte XML structuur uit de voorgaande stappen om daadwerkelijk de gelaagde data naar Exact Globe te communiceren. Op het tabblad "General" wordt eerst bij de sectie "Data Source" gekozen dat we data uit een "Task Step" als bron voor deze stap willen gebruiken. In dit voorbeeld willen we de XML gebruikten uit de stap "Meerlaags XML Data aanmaken":

Op het tabblad "Connection" wordt de administratie geselecteerd waarna data doorgezet dient te worden. Wanneer dit gedaan is, kan op het tabblad "Mapping" daadwerkelijk de data gekoppeld worden. In onderstaand screenshot is hiervan een voorbeeld te zien waarbij de mapping reeds gelegd is.

Wat zal opvallen is dat aan de linkerzijde van de mapping (de input data kant) de data gelaagd weergegeven wordt. Dit geeft aan dat we een correcte kop / subregel XML structuur gemaakt hebben die gekoppeld kan worden binnen de Integration Tool.

Let wel op: koppel NOOIT velden die aan de linkerzijde op kopregel niveau staan aan velden die bij de rechterzijde op regel niveau staan, of velden die aan de linkerzijde op regel niveau staan aan velden die aan de rechterzijde op kopregelniveau staan. Wanneer velden over meerdere lagen heen gekoppeld worden zorgt dit ervoor dat de data niet juist gelaagd doorgegeven kan worden aan het externe softwarepakket; Het effect hiervan is dat de data niet of niet juist verwerkt zal kunnen worden.

Wanneer we deze voorbeeld taak uitvoeren zullen de gewenste twee orders aangemaakt worden. In de onderstaande afbeelding is te zien dat er inderdaad twee orders aangemaakt zijn.

Wanneer we de voorbeeld order voor Orbis Software openklikken is te zien dat inderdaad twee orderregels binnen deze order aangemaakt zijn:

Met deze opzet kan men correct objecten aanspreken.

Met de bovenstaande opzet kan men correct Integration Tool operaties aanspreken welke data verwachten die bestaat uit meerdere lagen. Hoewel in dit voorbeeld gebruik gemaakt is van de "Exact Entity Services Integration Tool" kan deze opzet gehanteerd worden voor alle verschillende Integration Tools.

Belangrijk hierbij is dat het meegeven van meerlaags data niet optioneel is bij stappen die dit type data verwachten. Wanneer een Integration Tool stap een operatie bevat die meerlaags data verwacht zal het koppelen van een enkele query er standaard voor zorgen dat iedere regel afzonderlijk aangeboden wordt. In ons voorgaande voorbeeld zou dit ervoor gezorgd hebben dat voor iedere orderregel een separate order aangemaakt zou worden. Zorg er daarom altijd voor dat de juiste structuur aan de Integration Tool aangeboden wordt – enkel dan kan de juiste werking van de tool gegarandeerd worden.