Migratiegids OnsDB 5

In dit artikel wordt beschreven hoe te migreren van de OnsDB 4-client naar de nieuwe OnsDB 5-client. De belangrijkste wijzigingen zitten in dataminimalisatie, toegangsbeheer en performance verbeteringen.

Volg dit stappenplan in de aangegeven volgorde. Je bent klaar wanneer de eerste OnsDB 5-run is gecontroleerd en, als er gebruik van een geplande herhaaldelijke taak gemaakt wordt, die taak naar OnsDB 5 verwijst. Bewaar de bestaande OnsDB 4-installatie en configuratie totdat die controle is geslaagd. Gebruik voor de eerste OnsDB 5-run een aparte doel-database of een apart SQLite-bestand, zodat de bestaande download beschikbaar blijft. Laat beide clients niet tegelijk naar dezelfde database schrijven.

Stap 1. Richt de toegang in via het Ons API Dashboard

Het Ons API Dashboard is het platform waar externe koppelingen met Ons worden ingericht. De OnsDB 5-client wordt als externe koppeling behandeld. In het Dashboard bepaal je welke gegevens de client mag downloaden (dataminimalisatie) en regel je de toegang tot omgevingen via Ons Podium.

• Zorg dat je toegang hebt tot het Ons API Dashboard. Heb je nog geen toegang? Kies de juiste route in Toegang tot het Ons API Dashboard voor OnsDB 5: medewerkers van zorgorganisaties die OnsDB zelf gebruiken krijgen toegang via Ons Diensten; koppelpartners melden zich als eigen entiteit aan via de intake en hebben goedkeuring nodig.
• Open de koppeling en ga naar de eerste versie.
  1. Ga naar je koppelingen overzicht: 
     
  2. Indien je nieuw bent op het Ons API Dashboard, gebruik de koppeling die standaard wordt aangemaakt (anders maak een nieuwe koppeling aan): 
     
  3. Open de initiële versie van de koppeling:

• Open het tabblad Ons DB Tables:
• Er zijn drie manieren om te selecteren welke tabellen er nodig zijn:
  1. Maakt je huidige OnsDB-client gebruik van de include of/en exclude parameters in de config? Dan kun je de import config knop gebruiken om op basis van je huidige config de benodigde tabellen te selecteren. 
     
     Importeer hiervoor je huidige OnsDB 4-configuratiebestand. De import gebruikt alleen [onsdb] include en exclude. Controleer de importmelding en de uiteindelijke tabelselectie vóór het vastzetten van de versie.
     
     Bij een import met exclude wordt een vaste selectie van de huidige tabellen opgeslagen. Nieuwe tabellen uit toekomstige datamodellen worden dus niet automatisch toegevoegd, zoals in OnsDB 4 bij een uitsluitend lokale exclude-lijst. Voeg ze later toe in een nieuwe versie van de koppeling en regel daarvoor opnieuw toestemming. Kies alleen Use all OnsDB tables als je ook alle toekomstige tabellen nodig hebt.
  2. Zo niet, moeten de tabellen handmatig toegevoegd worden via +. Zoek de exacte tabelnaam, bijvoorbeeld clients. De afbeelding toont de plaats van de zoekfunctie:
  3. Er zullen uitzonderingen zijn waarbij de OnsDB client alle tabellen nodig heeft. Over het algemeen wordt afgeraden dit te gebruiken i.v.m. dataminimalisatie. Dit is in te stellen via: 
• Zodra de tabelselectie compleet is, kan de de versie vastgezet worden met lock version. Na het vastzetten van de versie is deze niet meer te wijzigen. Mochten er wijzigingen nodig zijn, dan dient er een nieuwe versie gemaakt te worden voor de koppeling. 
  Een koppelpartner kan vooraf op development testen met TE1002, zonder de versie vast te zetten. Een zorgorganisatie gebruikt haar eigen test- of productieomgeving. Daarvoor moet de versie wel vastgezet worden. 
  Een versie kan als volgt vastgezet worden:

Stap 2. Installeer OnsDB 5

Installeer de OnsDB 5-client in een aparte map en maak een kopie van het bestaande OnsDB 4-configuratiebestand. Gebruik die kopie als uitgangspunt voor de nieuwe configuratie.

Controleer eerst de platformvereisten: De macOS-client vereist nu macOS 13 Ventura of nieuwer. Gebruik op Windows Windows 10 of Windows Server 2016 of nieuwer.

Voor SQL Server op Windows is een 64-bits ODBC-driver en gegevensbron nodig. Maak een bestaande 32-bits gegevensbron opnieuw aan in de 64-bits ODBC-beheerder, ook als je dezelfde naam gebruikt. Zie Databaseconfiguratie. De ondersteunde Linux-configuratie staat in de installatiehandleiding.

Stap 3. Werk het configuratiebestand bij

OnsDB 5 weigert onbekende instellingen. Verwijder de hieronder genoemde oude instellingen ook als ze een lege waarde hebben. Het bestand moet de extensie .cfg hebben; hernoem bijvoorbeeld onsdb.ini naar onsdb.cfg en pas ook de opdracht in je geplande taak aan.

• [onsdb] stage: vul de omgeving in: development, staging of production. OnsDB 5 gebruikt één executable voor alle omgevingen; deze instelling bepaalt de omgeving.
• [onsdb] customer-code: vul de klantcode van de gekozen omgeving in. Gebruik TE1002 om te testen op de development omgeving. Deze waarde vervangt de voormalige instelling url om de omgeving te identificeren; verwijder url daarom uit het configuratiebestand.
• [onsdb] connector: vul de technische naam van de koppeling uit het Ons API Dashboard in. De technische naam van de koppeling is op de volgende plek in het Ons API Dashboard te vinden (weet je niet meer hoe je op de koppeling pagina komt, bekijk dan stap 1): 
• [onsdb] email Moet worden verwijderd. OnsDB 5 verstuurt geen rapporten meer per e-mail. Gebruik eventueel [onsdb] report-file om na iedere run een rapportbestand op te slaan, bijvoorbeeld report-file = onsdb-report-{date}.txt. Dit bestand bevat dezelfde informatie als het email-rapport van OnsDB 4 en kan door eigen tooling worden uitgelezen om een notificatie te versturen. In de bestandsnaam wordt {date} vervangen door de startdatum van de run.
• [onsdb] workers: vervang door download-workers. Dit bepaalt het aantal gelijktijdige downloads. Kies een waarde van 1 tot en met 4; de standaardwaarde is 4. Het aantal workers voor het schrijven naar de database kan apart met [database] workers worden ingesteld.
• [onsdb] threads: verwijder deze instelling. Deze oude instelling bepaalde het aantal processorthreads en heeft geen directe vervanger. Heb je alleen threads ingesteld en geen workers, dan kun je download-workers weglaten om de standaardwaarde 4 te gebruiken.
• [onsdb] daysize: verwijder deze instelling. OnsDB 5 gebruikt geen instelbare dagvensters meer om downloads op te delen.
• [onsdb] exclude-retrieval-by-date: verwijder deze instelling. Globale start- en end-grenzen gelden voor alle resources die datumfilters ondersteunen. Zet voor een uitgezonderde tabel start = en end = in de betreffende [resource.<tabelnaam>]-sectie om beide grenzen onbegrensd te maken. Je kunt ook één grens leegmaken; een weggelaten instelling blijft de globale grens erven. Zie Instellingen per resource.
• [onsdb] start en end: de standaardperiode blijft gelijk aan OnsDB 4: 1 januari van het vorige jaar tot en met gisteren. Ontbrekende of uitgecommentarieerde instellingen gebruiken deze standaardwaarden (start = now/y-1y en end = now-1d). Een expliciet lege waarde maakt de betreffende grens onbegrensd; zet zowel start = als end = om de volledige periode op te halen. Een ontbrekende resourcegrens erft de globale grens; een expliciet lege resourcegrens maakt alleen voor die tabel de grens onbegrensd.
• [certificate] email, name en tel moeten worden verwijderd. OnsDB 5 gebruikt deze instellingen niet meer voor het certificaat.
• [database] host en opts worden niet meer ondersteund. Hernoem ze naar respectievelijk hostname en options. Staan beide namen al in het bestand, behoud dan de bestaande waarde van hostname of options en verwijder de oude alias; deze bestaande waarde had ook in OnsDB 4 voorrang.
• [onsdb] include, exclude: controleer na het importeren de tabelselectie in het Ons API Dashboarde lokale include en exclude kunnen de daar verleende toegang alleen verder beperken. Een tabel in include die niet beschikbaar is, of ook door exclude wordt uitgesloten, laat OnsDB stoppen voordat de doel-database wordt gewijzigd. Onbekende namen in exclude worden genegeerd; controleer ze daarom zelf.
• [onsdb] schema-version: controleer of een vastgezet datamodel nog beschikbaar is voor de gekozen omgeving. Gebruik na de certificaataanvraag --list-versions zoals beschreven in Beschikbare datamodellen. Kies zo nodig een ondersteunde versie en controleer je queries, of laat de instelling weg om het nieuwste datamodel te gebruiken.
• [onsdb] pagesize: een ingestelde geldige waarde kan blijven staan. Zonder instelling is de standaardwaarde nu 200.000 in plaats van 50.000; de maximale waarde is 1.000.000. Ook datumgebonden tabellen worden automatisch opgehaald zonder de oude dagvensters. Controleer de doorlooptijd met je eigen tabelselectie.
• [onsdb] drop-unselected-tables: net als OnsDB 4 verwijdert OnsDB 5 standaard tabellen die niet bij de download horen, ook eigen tabellen. Nieuw is dat false dit uitzet; doe dat vóór de eerste run als de database eigen tabellen bevat.

Andere instellingen kunnen blijven staan: [onsdb] proxy en timezone, [database] type, odbc, username, password, database, hostname, port en options, en [certificate] identifier. Pas de databaseverwijzing wel aan voor de aparte eerste download. Stel numerieke waarden en datums in volgens de configuratiereferentie; OnsDB 5 controleert onder meer dat start niet na end ligt. 

Controleer ook waarden die geheel tussen aanhalingstekens of backticks staan. OnsDB 4 behandelde die tekens als onderdeel van de waarde; OnsDB 5 leest ze als INI-notatie en verwijdert de omringende tekens. Bevat bijvoorbeeld het echte databasewachtwoord zulke tekens aan beide uiteinden, geef dan de exacte waarde via ONSDB_DATABASE_PASSWORD mee. Omgevingsvariabelen en --set worden niet als INI-waarden uitgepakt. Tekens zoals #, ; en een afsluitende backslash blijven in het configuratiebestand onderdeel van de waarde; zet opmerkingen op een eigen regel.

Stap 4. Start OnsDB 5 eenmaal

Start de OnsDB 5-client eenmalig om de certificaataanvraag te maken. Bevestig via de link die OnsDB logt in het Ons API Dashboard dat de aanvraag door de juiste partij is gedaan. Zodra via Ons Podium toestemming is gegeven om de OnsDB-client voor de gekozen omgeving te gebruiken, start je OnsDB opnieuw; de OnsDB run kan dan beginnen.

Neem het OnsDB 4-certificaat en de private key niet over. OnsDB 5 maakt in de nieuwe map zelf de map ssl aan voor zijn certificaat en sleutels. De eerste aanvraag stopt met exitcode 1 zolang de bevestiging of toestemming ontbreekt; dat is op dit moment verwacht.

Stap 5. Pas de opdracht en eventuele geplande taak aan

• OnsDB 5 geeft exitcode 2 terug wanneer de download is afgerond met job- of recordfouten. OnsDB 4 kon dan nog exitcode 0 teruggeven. Een succesvolle download gevolgd door een rapportfout geeft exitcode 3; bij zowel downloadfouten als een rapportfout krijgt code 2 voorrang. Als de opdracht niet normaal kan worden afgerond, geeft OnsDB exitcode 1 terug. Waarschuwingen tijdens de download blijven exitcode 0 toestaan. Controleer of je script of geplande taak hiermee rekening houdt. Zie Exitcodes.
• In OnsDB 4 werd het configuratiebestand als los argument meegegeven, zoals: onsdb.exe onsdb.cfg. In OnsDB 5 kan --config worden gebruikt, bijvoorbeeld: onsdb.exe --config onsdb_config.cfg. Als deze niet expliciet wordt meegegeven, wordt standaard onsdb.cfg gebruikt.
• De oude versieopdracht onsdb.exe onsdb.cfg -list-versions wordt onsdb.exe --config onsdb.cfg --list-versions. De oude opdracht -speedtest is niet meer beschikbaar.
• Gebruik desgewenst --set categorie.instelling=waarde voor een runtimewaarde, bijvoorbeeld een databasewachtwoord (--set database.password=secret). Een waarde van --set overschrijft dezelfde instelling in het configuratiebestand. --set kan meerdere keren herhaald worden om meerdere instellingen via de CLI mee te geven. 
• Een instelling kan ook met een omgevingsvariabele worden overschreven, bijvoorbeeld ONSDB_DATABASE_PASSWORD. Gebruik ONSDB_, gevolgd door de sectienaam en instelling in hoofdletters; vervang . en - door _. Omgevingsvariabelen hebben voorrang op het configuratiebestand, maar --set heeft voorrang op beide. 
• Stel de werkmap van de geplande taak expliciet in op de nieuwe OnsDB-map en voorkom dat downloads overlappen.

Stap 6. Controleer de eerste run voordat je de geplande taak inschakelt

• Controleer de log en, indien ingesteld, het lokale rapportbestand op fouten.
• Controleer of alle verwachte tabellen in de doel-database aanwezig zijn.
• SQL Server-datum-tijdkolommen gebruiken in OnsDB 5 DATETIME2(3) in plaats van DATETIME. Dit bewaart milliseconden en ondersteunt datums vanaf 0001-01-01. Datumkolommen blijven DATE. Controleer of eigen queries en tooling met deze kolomtypen werken.
• Controleer of de gegevens tot en met de verwachte einddatum zijn opgehaald.
• Vergelijk, waar mogelijk, de aantallen records met de laatste succesvolle OnsDB 4-run.

Schakel pas daarna de geplande taak voor OnsDB 5 in en zet OnsDB 4 uit.