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.

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 beheersniveau > 98. Voor tegeldefinities zie pagina's Import matrijzen en Import Sleutels.

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). Voor de inrichting kan het mogelijk zijn, afhankelijk van wat men wilt, om met vaste sleutelwaardes te werken. Deze sleutelwaardes definieert men of vooraf bij de importsleuteltabel, of ze worden ingelezen in de importsleuteltabel tijdens een generieke bulk importactie. De importsleutelfunctionaliteit wordt verderop uitgelegd onder kopje Import sleutels op deze pagina.

Hier wordt eerst uitgelegd hoe de importmatrijzen gevuld moeten worden om een importactie in te richten. Afhankelijk van wat er gewenst is zal men voor een importactie, één hoofdactie inrichten met 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.

Om de regels aan te maken in tbimportmatrijs 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 importmastrijs 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, eventueel aangevuld met gewenste te vullen, velden in tbmilinrichtingen, tbinspecties en tbinspbezoeken
  • voor ieder opgezocht veld een regel aanmaken in tbimportmatrijsregels (via blok Kolommen in detailscherm van de importmatrijs):
    • via de plusknop maakt men voor ieder veld, één kaartje aan in tbimportmatrijsregels
      • in de wizard kiest men de naam van het veld uit de tabel waarin ingelezen moet worden
      • de kolomnummers(s) met bewerking uit importbestand (zie kopje verderop op deze pagina Bron/kolombewerking importmatrijsregel)
      • eventueel de sleuteltabelnaam uit tbimportsleutels (indien deze gevuld is dan wordt de waarde voor het gekozen veld opgehaald uit tbimportsleutels). Is meestal alleen gevuld indien men een foreign key verwijzing op wilt halen
    • in het detailscherm van een importmatrijsregel kan men indien nodig de definitie nog wijzigen
• 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

Er wordt een voorbeeldsituatie uitgeschreven voor zowel een bulk importactie gebaseerd op een Excel file als een bulk importactie gebaseerd op een CSV file. Hier wordt concreet uitgeschreven hoe men in tbimportmatrijs, tbimportmatrijsregels en tbimportsleutel de inrichting moet maken om de voorbeeld bulk importactie te kunnen uitvoeren. Zie voor deze voorbeelden: <hier komt nog een link>

Dit is een file die qua inhoud steeds zal 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. 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.

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

in de importmatrijstabel wordt dus 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.
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

Samen maken de importmatrijsregels onder 1 importmatrijs dan samen de definitie van 1 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 1 importmatrijsregel aanmaakt met als naam van het veld IkBenSleutelVeld kiest. In de bron/kolombewerking schrijft men vervolgens uit hoe gerefereerd gaat worden naar het aangemaakte kaartje. Zie kopje Import sleutels voor een voorbeeld.

<hier komt stukje uitleg over sleutels aanmaken/gebruiken>

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 de geüploade bestandsfile om zo de juiste waardes op te halen.
De programmatuur zal vervolgens voor iedere regel in het bestand, een insert actie (proberen te) uitvoeren. Net zo lang tot er geen bestandregels meer zijn. De voortgang en foutgevallen worden bijgehouden in de logging bij de operationslogregel voor de bulk importactie.

Bij het einde aangekomen? Dan wordt er gekeken of er nog een vervolgactie staat.
Ook dit is een regel in tbimportmatrijs met daaronder tbimportmatrijsregels. De programmatuur gaat de vervolgactie uitvoeren op dezelfde manier als de hoofdactie. Waarbij er niet opnieuw gekeken wordt naar bestandstype (voor 1 overall bulk importactie kan dus maar 1 bestand worden geüpload) maar men wel kan aangeven op welk werkblad de gegevens staan voor de vervolgactie (indien Excel) en/of de beginregel (Excel en CSV). Na uitvoeren van de vervolgactie wordt weer gekeken of er nog een vervolg is enz. enz. tot alle acties 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

In de audit tabel van OpenWave wordt 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 is, waarom niet (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