Generieke bulk import

De generieke bulk import functionaliteit van OpenWave is gemaakt met het idee om flexibiliteit te bieden aan de organisaties m.b.t. het kunnen inlezen van data in OpenWave. Het uitgangspunt van de functionaliteit is dat deze gebruikt kan worden voor bijvoorbeeld het periodiek aanmaken van de geplande controles bij inrichtingen, en overige toepassingen waarbij men een lijst met gegevens heeft die bij OpenWave ingelezen moeten worden. Vooralsnog is het alleen mogelijk om te kunnen inlezen: daarmee wordt bedoeld kaarten aanmaken in tabellen in OpenWave. In de toekomst zal de functionaliteit uitgebreid kunnen worden met andere mogelijkheden zoals updaten/wijzigen van bestaande kaarten in OpenWave.

De generieke bulk import gaat uit van een document (een Excel of CSV file) waarin de gegevens staan die men wilt inlezen met behulp van een importmatrijstabel in OpenWave. Hierin staat beschreven hoe EN waar de programmatuur van OpenWave de data uit de aangewezen file moet inlezen. Het definiëren van regels in de importmatrijstabel zal men zelf doen. Zo kan elke organisatie voor iedere benodigde importactie, eigen definities maken.

Op deze pagina wordt in het algemeen uitgelegd hoe de generieke bulk importactie werkt en hoe deze acties ingericht kunnen worden. Tevens zijn er twee voorbeeldsituaties uitgeschreven op onderliggende pagina's in de dokuwiki: daar staat uitgeschreven hoe men in tbimportmatrijs, tbimportmatrijsregels en tbimportsleutel de inrichting moet maken om de voorbeeld bulk importactie te kunnen uitvoeren.
Zie voor deze voorbeelden:

• Voorbeeld: Inspecties aanmaken bij inrichtingen
• Voorbeeld: Toezicht zaken aanmaken bij inrichtingen

Een generieke bulk importactie zal eerst ingericht moeten worden alvorens deze gestart kan worden. Het inrichten vindt plaats in beheerportaal(nieuw) onder kolom Dieper beheer. Hiervoor zijn de tegels Import Matrijzen en Import sleutels benodigd. Deze zijn standaard toegewezen aan medewerkers met beheerniveau > 98. Voor tegeldefinities zie pagina's Import matrijzen en Import Sleutels.

Voordat men begint met het inrichten van een generieke bulk importactie moet men het proces van de gewenste importactie uitwerken:

• wat moet de importactie doen? Bijvoorbeeld stel men wilt inrichtingen aanmaken en daaronder inspecties aanmaken en daaronder weer inspectiebezoeken. Dan zal ingericht moeten worden:
  • een hoofdactie voor het aanmaken van inrichtingen (nieuwe regel in tbimportmatrijs met dlhoofdmatrijs = T)
  • een vervolgactie voor aanmaken inspecties onder de aangemaakte inrichtingen (nieuwe regel in tbimportmatrijs met dlhoofdmatrijs = F)
  • bij de hoofdmatrijs als vervolgmatrijs kiezen de net aangemaakte vervolgactie voor inspecties aanmaken
  • een tweede vervolgactie voor aanmaken inspectiebezoeken onder de aangemaakte inspecties (nieuwe regel in tbimportmatrijs met dlhoofdmatrijs = F)
  • bij de importmatrijs voor inspecties aanmaken als vervolgmatrijs kiezen de net aangemaakte vervolgactie voor bezoeken aanmaken
• welke gegevens zijn er nodig voor het kunnen aanmaken van regels in de tabellen?
  • dus in bovengenoemd voorbeeld: opzoeken van de verplichte velden, eventueel aangevuld met de overige gewenste te vullen velden in tbmilinrichtingen, tbinspecties en tbinspbezoeken
• de benodigde gegevens beschikbaar stellen in een Excel of CSV file
  • dit kan bijvoorbeeld d.m.v. rapport(en) draaien en naar Excel exporteren
  • of indien men van de functionaliteit Bulk aanmaken van inspecties/toezichtzaken gebruik maakt kan men de daar gebruikte Excel mallen gebruiken

Na het uitdenken van het proces kan men starten met het inrichten van de gewenste bulk importactie. Te beginnen met het bestand wat men wilt gaan uploaden bij deze importactie:

Het bestand met daarin de in OpenWave in te lezen data mag in principe zo opgesteld zijn als men zelf wilt.
Het is wel belangrijk om te weten in welke (combinatie van) kolommen, welke data staat die men wilt inlezen. Dit is benodigd voor het correct inrichten van een bulk importactie in OpenWave.
Het zal in de praktijk voorkomen dat men de basis van het bestand blijft gebruiken voor gelijke importacties. Stel dat men een import heeft ingericht voor inspecties aanmaken bij inrichtingen, dan zal de opzet van het bestand wat men upload steeds gelijk zijn (in kolom1 staat bijv. altijd de waarde voor inspectieaanleiding) maar de daadwerkelijke waardes per kolom/regel zal wijzigen.
De inhoud van het bestand zal wel wijzigen voor iedere importactie: immers eenmaal ingelezen zal men niet opnieuw dezelfde data in willen lezen (m.u.v. opnieuw draaien van importactie indien men de importactie heeft teruggedraaid. Zie kopje Terugdraaien van import actie op deze pagina). Vandaar dat bij iedere importactie gevraagd wordt aan diegene die de actie start, om het juiste bestand aan te wijzen.

Voor het inrichten van iedere generieke bulk importactie zijn een aantal zaken van belang om te weten die met de file te maken hebben:

• opzet van bestand waarin de in te lezen waardes staan (in welke kolom van de CSV of Excel staat welke waarde)
• bestandtype van de file (CSV of Excel)
  • indien CSV dan zal opgegeven worden bij het inrichten in tbimportmatrijs:
    • CSVlimit: met welk teken de kolommen van elkaar gescheiden zijn (indien niet opgegeven gaat programmatuur uit van default teken: puntkomma)
    • CSVQuote (omgrenzingswaarde): tussen welk teken de waarde binnen een kolom staan (indien niet opgegeven gaat programmatuur uit dat er geen omgrenzingswaarde is)
    • of null/lege waardes in een kolom ook omsloten zijn door het bovengenoemde omgrenzingsteken
  • indien Excel dan kan men met verschillende werkbladen werken:
    • indien dit zo is dan kan per importmatrijs opgegeven worden de naam van het werkblad waar de programmatuur naar moet kijken
    • indien dit niet zo is dan kan bij de importmatrijs het veld voor werkblad leeggelaten worden: de programmatuur kijkt dan altijd naar het eerste tabblad van de Excel file
• de beginregel van de file (zowel bij Excel als CSV van toepassing):
  • indien men gebruik maakt van kopregels dan moet per importmatrijs aangegeven worden vanaf welke regel de programmatuur de file moet gaan verwerken (de eerste regel waar de daadwerkelijke data staat om ingelezen te worden)
  • indien men gelijk vanaf eerste regel in de file de data om ingelezen te worden heeft staan, dan hoeft men niet de beginregel te vullen bij de importmatrijs

Met deze informatie kan men beginnen met het daadwerkelijk aanmaken van regels in de tabellen bedoelt voor inrichten van bulk importacties. Daarbij wordt gestart met het aanmaken van een regel in de tabel tbimportmatrijs:

Onder de tegel Import Matrijzen wordt ingericht in welke tabel(len) een importactie regels gaat inlezen en hoe de programmatuur de data moet gaan opslaan in deze tabel(len).
Afhankelijk van wat er gewenst is zal men voor een importactie, één hoofdactie inrichten EN eventueel vervolgacties. Zowel de hoofdactie als vervolgacties zijn aparte regels in de tabel tbimportmatrijs. Bij het definiëren van deze regels in tbimportmatrijs wordt de hoofd- en vervolgrelatie opgegeven. Samen vormen deze regels dan één generieke bulk importactie.
De regels in de tbimportmatrijs tabel worden aangemaakt via de plus-knop in de lijst van Import matrijzen.

Bij het aanmaken van een regel in de importmatrijstabel wordt aangegeven:

• de naam van de import
• of het om een hoofdmatrijs gaat (start van de import? dan hoofdmatrijs AAN, vervolgactie? dan hoofdmatrijs UIT)
• de vervolg/parentrelatie met andere regels uit tbimportmatrijs (vervolgmatrijs kan gekozen worden, het veld parentmatrijs wordt automatisch gevuld)
• of het om een Excel of CSV file gaat
• de doeltabel waarin regels ingelezen gaan worden
• de beginregel van het bestand
• indien CSV:
  • scheidingsteken tussen de kolommen
  • begrenzingsteken waarde in kolom
  • of null waardes ook begrensd zijn
• indien Excel:
  • naam van het werkblad

In de lijst met importmatrijsregels, zie blok Kolommen in het detailscherm van een importmatrijs, wordt vervolgens per veld benodigd voor de insert in de doeltabel een regel gemaakt om te definiëren hoe de waardes voor de insert opgehaald moeten worden.

In de lijst met importmatrijsregels wordt via de plus-knop een wizard gestart waarmee een importmatrijsregel wordt aangemaakt.
Er moeten evenzoveel importmatrijsregels worden aangemaakt als men velden benodigd heeft voor een insertactie.
Dus bijvoorbeeld als de doeltabel van de bovenliggende matrijs 4 verplichte velden heeft en 3 velden die men ook wilt meegeven, dan moeten er 7 regels worden aangemaakt in tbimpormatrijsregels.
Samen maken de importmatrijsregels onder één importmatrijs dan de definitie van één insert voor een regel in de doeltabel.
Indien er tijdens de daadwerkelijke importactie (dus tijdens het draaien van de generieke bulk import) in de vervolgactie(s) verwezen moet worden naar de net aangemaakte kaarten in de doeltabel, dan zal er ook een kaartje aangemaakt moeten worden in tbimportsleutels.
Dit gebeurd automatisch indien men één importmatrijsregel aanmaakt met als naam van het veld IkBenSleutelVeld. In de bron/kolombewerking schrijft men vervolgens uit hoe gerefereerd gaat worden naar het aangemaakte kaartje. Zie kopje Import sleutels voor een voorbeeld.

Iedere importmatrijsregel wordt als volgt gedefinieerd:

• de naam van het veld uit de doeltabel wordt gekozen
• de bron/kolombewerking wordt gekozen
  • dit betekent dat hier in SQL staat hoe de waarde voor het tabelveld, uit het bestand OF uit de tabel tbimportsleutels opgehaald moet worden
• eventueel wordt de sleuteltabelnaam gevuld (alleen nodig indien een vaste sleutelwaarde moet opgehaald worden uit tbimportsleutels

Klikken op een importmatrijsregel in de lijst geeft het openen van het detailscherm van de importmatrijsregel. Daar kan de definitie van de aangemaakte importmatrijsregel gewijzigd worden.
De min-knop in de lijst zal een wizard starten om een importmatrijsregel te verwijderen.

Voor de inrichting kan het mogelijk zijn, afhankelijk van wat men wilt, om met vaste sleutelwaardes te werken. Deze sleutelwaardes worden of vooraf gedefinieerd bij de importsleuteltabel (via tegel Import sleutels), of ze worden ingelezen in de importsleuteltabel tijdens een generieke bulk importactie.
Hoe dit werkt wordt aan de hand van onderstaand voorbeeld uitgelegd:
Stel in het bestand met de in te lezen data staan gegevens van aan te maken inspecties en inspectiebezoeken en de inrichtingnummers waaronder deze inspecties aan te maken.
Voor het inlezen van de inspecties is het nodig om de corresponderende dnkey van de inrichting op te halen. Dit kan met een select statement in tbimportmatrijsregels. Maar kan ook door in de tabel voor import sleutels de dnkeys van de inrichtingen vast te leggen.
Dit doet men als volgt:

• klik op de plus-knop in de lijst van import sleutels
  • kies hier de naam van de tabel waarin het veld staat waarnaar verwezen moet worden. In het voorbeeld is dit tbmilinrichtingen
  • vervolgens bij pointer/keywaarde wordt de waarde van het veld gevuld. In dit geval de dnkey van tbmilinrichtingen (bijvoorbeeld: 123432)
  • bij zoeksleutel wordt de waarde gevuld die in het bestand staat/ met de select bij importmatrijsregel wordt opgehaald. In het voorbeeld zetten we hier het inrichtingnummer van de inrichting
• dit herhaalt men totdat alle benodigde sleutels zijn aangemaakt

De importmatrijsregel voor de dnkeymilinrichtingen vullen bij tbinpspecties is dan als volgt gedefinieerd:

• doelveld = dnkeymilinrichtingen
• Bron/kolombewerking = {kolom:1}
  • de kolom in het bestand waarin het inrichtingnummer staat, als voorbeeld is hiervoor kolom 1 genomen
• sleutel = tbmilinrichtingen

Dit zorgt ervoor dat bij het draaien van de generieke bulk import, regels worden aangemaakt in tbinspecties onder de inrichting van het opgegeven inrichtingnummer in het bestand.
Bovengenoemd voorbeeld is het vooraf vastleggen van vaste sleutelwaardes.
Het tijdens de bulk importactie vastleggen van nieuwe vaste sleutelwaardes is ook benodigd in ons voorbeeld. Want onder de aangemaakte inspecties, wil men graag bezoeken aanmaken.
Hiervoor zijn er rijtjes in tbimportsleutels nodig voor de net aangemaakte inspecties. Dit wordt geregeld, zoals hierboven al genoemd, door bij de importmatrijs voor tbinspecties, een importmatrijsregel aan te maken met als veldnaam IkBenSleutelVeld.
Zo'n importmatrijsregel ziet er dan als volgt uit:

• doelveld = IkBenSleutelVeld
• Bron/kolombewerking = {kolom:2}
  • de kolom in het bestand waarin de verwijzing naar inspectie staat (bijvoorbeeld de aan te maken inspectiecode), als voorbeeld is hiervoor kolom 2 genomen
• sleutelveld is leeg → Niet gevuld

Bij het draaien van de bulk importactie zal dan voor iedere aangemaakte rij in tbinspecties, ook een rij aangemaakt worden in de sleuteltabel met als tabelnaam tbinspecties, als pointer de dnkeywaarde van deze inspectie als zoeksleutel de verwijzing naar deze sleutelwaarde.
Voor de vervolgactie van het aanmaken van bezoeken, definieert men dan in tbimportmatrijsregels voor veld dnkeyinspecties dat deze gevuld wordt door ophalen van de juiste waarde uit de sleuteltabel.

In het Operationsportaal is onder kolom Import nieuwe tegel Start generieke bulk import (Start generieke bulk import) zichtbaar. Deze tegel start de wizard voor het starten van een bulk importactie. De wizard zal vragen om een importmatrijs aan te wijzen waarvoor geldt dat dit een hoofdmatrijs is. Dit is de starttabel van de import. Daarnaast vraagt de wizard om het aanwijzen van een bestand. Dit moet zoals hierboven genoemd een CSV (.csv) of Excel (.xlsx)-file zijn met daarin de data die men wilt inlezen. Bij klikken op uitvoeren in de wizard wordt op de achtergrond de bulk importactie uitgevoerd. In de operationslog is de voortgang bij te houden.

De importactie zal beginnen met het controleren van een aantal zaken:

• rechtencheck: de medewerker die de import start moet waarde T hebben voor veld tbmedewerkers.dlmagbulkimporteren (zie detailscherm van medewerkerkaart)
• of er op dat moment al een generieke bulk importactie draait (is het geval indien instelling Sectie: Operations, Item: GeneriekeBulkImport Getal1 waarde 1 heeft)
• of het aangewezen bestand te vinden is (upload goed gegaan tijdens de wizard) en of deze de juiste extensie heeft (.csv of .xlsx)

Daarna zal de programmatuur kijken bij de aangewezen hoofdmatrijs hoe het bestand verwerkt moet worden:

• beginregel wordt opgezocht (indien leeg dan begint de programmatuur bij de eerste bestandsregel)
• indien Excel dan de werkbladnaam indien deze gevuld is
• indien CSV dan wordt er gekeken naar scheidingsteken tussen de kolommen (niet gevuld dan default verwacht puntkomma), Begrenzingsteken in kolom (niet gevuld dan wordt verwacht dat de kolomwaardes zelf niet omhult zijn met een teken) en of null waardes ook begrensd zijn (indien F/niet aangevinkt dan niet, anders wel)
• bepalen wat de doeltabel is van de importactie: tabel waarin data ingelezen moet worden
• het doel van de importactie: is voor nu altijd insert. Kan in de toekomst uitgebreid worden met update of delete bijvoorbeeld
• bepalen of er een vervolgmatrijs is (waarde van tbimportmatrijs.dnkeyvervolgmatrijs, mag leeg zijn)

Vervolgens wordt er gekeken in de tabel tbimportmatrijsregels die horen bij de aangewezen importmatrijs, uit welke velden de insert actie bestaat voor iedere regel op de doeltabel. Plus hoe ieder veld gevuld moet worden: de selects/kolomverwijzingen die in de tbimportmatrijsregels staan worden door de programmatuur gecheckt met het geüploade bestand om zo de juiste waardes op te halen.

De programmatuur zal vervolgens voor iedere regel in het bestand, een insert actie (proberen te) uitvoeren. Indien er een importmatrijsregel bestaat met veldnaam IkBenSleutelVeld dan zal na iedere insert actie in de doeltabel ook een nieuwe regel aangemaakt worden in de sleuteltabel (tbimportsleutels).

Als de programmatuur klaar is met het verwerken van de importmatrijs waar deze mee bezig is, alle regels in het bestand (bij Excel: de regels van het werkblad) zijn doorlopen en de insert acties zijn uitgevoerd, dan wordt er gekeken of er nog een vervolgactie is.
Dit is het geval indien tbimportmatrijs.dnkeyvervolgmatrijs gevuld is.
De programmatuur gaat (indien aanwezig) de vervolgactie uitvoeren op dezelfde manier als de hoofdactie.
Er wordt niet opnieuw gekeken naar het bestandstype: voor 1 overall bulk importactie kan dus maar 1 bestand worden geüpload.
Maar er wordt gekeken in de importmatrijstabel van de vervolgactie op welk werkblad de gegevens staan voor de vervolgactie (indien Excel) en/of naar de beginregel (Excel en CSV).
Na uitvoeren van de vervolgactie wordt weer gekeken of er nog een vervolg is enz. enz. tot alle inleesacties in de bulk importactie zijn uitgevoerd.

De voortgang van het op de achtergrond draaien van een bulk importactie is in te zien via de operationslog. Er zal een regel worden aangemaakt met als code GeneriekeBulkImport.
Tevens is in de configuratietabel terug te zien of er al een bulk importactie draait: dit is het geval indien Getal1 = 1 bij instelling Sectie: Operations, Item: GeneriekeBulkImport (de instelling wordt automatisch aangemaakt bij eerste keer starten van de generieke bulk import).

De logging bij de regel in de operationslog is als volgt opgebouwd:

• iedere importactie (dus voor iedere importmatrijs) wordt gelogd
  • de start is altijd een hoofdimportmatrijs en de logging van deze importactie staat bovenaan
• de logging van iedere importactie begint met een regel die aangeeft welke matrijs verwerkt wordt
• daarna volgen de regels die niet gelukt zijn om aan te maken met de waardes van de insert die de programmatuur heeft geprobeerd uit te voeren
  • indien alle regels goed gaan dan zijn er uiteraard geen mislukte regels
• vervolgens volgt een eind overzicht van deze enkele importactie actie met:
  • Aantal aangemaakte regels
  • Aantal overgeslagen regels
  • Totaal aantal verwerkte regels
• indien er vervolg-importmatrijzen zijn dan volgt er een witregel en daaronder begint dan de logging van de vervolg importactie
• enzovoorts totdat alle importacties in deze bulk importactie gelogd zijn

Het kan natuurlijk voorkomen dat een gedraaide bulk importactie niet het gewenste resultaat geeft, bijvoorbeeld als de inrichting niet helemaal correct is of de data uit het inleesbestand niet juist bleek. Wat de aanleiding ook is, er is altijd de mogelijkheid in OpenWave om de via de bulk import aangemaakte regels te verwijderen.

Omwille van het mogelijk kunnen terugdraaien van een bulk importactie wordt er in OpenWave bijgehouden in welke tabellen, welke regels (primary key) worden aangemaakt tijdens een bulk importactie.
Dit werkt als volgt: tijdens het draaien van een generieke bulk importactie wordt voor iedere regel die in een tabel wordt aangemaakt, in tbaudit een regel aangemaakt met naam van de tabel, primary key van de nieuwe regel, dat het om een insert gaat, en veld dvbron krijgt waarde ‘I' om aan te geven dat de regel uit de bulk import komt.

In het lijstscherm van de Audit is linksonder een knop beschikbaar gekomen die een wizard start om de bulkactie ongedaan te maken. Vooralsnog zal deze wizard vragen om een vanaf datum en tijd, en een tot en met datum en tijd waarin men de regels die aangemaakt zijn weer wilt verwijderen. Zo kan men zelf bepalen welke regels die verkeerd zijn aangemaakt, ook weer verwijderd zullen worden.
Stel een bulk importactie heeft regels aangemaakt in tbmilinrichtingen, tbinspecties en tbinspbezoeken dan kan men d.m.v. tijdstip aanwijzen in de wizard zelf reguleren welke regels verwijderd zullen worden uit de tabellen.
De voortgang van de terugdraaiactie kan worden ingezien bij de operationslog. Daar zal men in de logging tevens kunnen vinden of het gelukt is om de regels te verwijderen.

De terugdraaiactie is te volgen via de operationslog. Er zal een regel worden aangemaakt met als code GeneriekeBulkImportDeleteRegels.
Tevens is in de configuratietabel terug te zien of er al een proces draait voor terugdraaien van een bulk importactie: dit is het geval indien Getal1 = 1 bij instelling Sectie: Operations, Item: GeneriekeBulkImportDeleteRegels (de instelling wordt automatisch aangemaakt bij eerste keer starten van de terugdraaiactie).
In de logging bij de regel in de operationslog is terug te zien:

• als een regel niet verwijderd kon worden, waarom dit niet gedaan is (mislukt of niet gevonden of uitzonderingstabel)
• of het proces klaar is
• het aantal verwijderde regels
• het aantal niet gevonden regels
• totaal aantal niet verwijderde regels (regels waarbij verwijderen mislukt is)
• totaal aantal verwerkte regels