Gebruiken van OnsDB 5

Voordat OnsDB voor de eerste keer op een computer gebruikt kan worden is het noodzakelijk dat er een certificaat aangevraagd wordt bij Nedap en dat het certificaat goedgekeurd wordt. Hoe dat precies in zijn werk gaat wordt in dit artikel toegelicht.

Starten van de applicatie

OnsDB wordt altijd gebruikt door middel van de command prompt. Dit maakt het makkelijk om via een taskscheduler op vaste tijdstippen de download te laten plaatsvinden.

• Start de command prompt.

• Ga naar het pad waar de OnsDB 5 executable staat.

• Start het programma met een configuratiebestand als parameter. Het starten van OnsDB met een bestaand configuratiebestand genaamd onsdb.cfg in dezelfde map kan bijvoorbeeld als volgt:

  • Windows

 C:\onsdb>onsdb.exe --config onsdb.cfg

• • Unix

 ./onsdb --config onsdb.cfg

Standaard maakt OnsDB de geselecteerde tabellen opnieuw aan en verwijdert het alle overige tabellen uit de doel-database. Met keep-existing-records = true blijven compatibele tabellen met een primary key en hun bestaande records behouden; gedownloade records worden ingevoegd of bijgewerkt. Compatibele tabellen zonder primary key worden geleegd en opnieuw gevuld; ontbrekende of niet-compatibele tabellen worden opnieuw aangemaakt. Stel drop-unselected-tables = false in om niet-geselecteerde tabellen te behouden. Zie Configuratiebestand voor OnsDB 5 voor deze instellingen.

Gegevens behouden en downloads herhalen

Een gewone download met keep-existing-records = false vervangt de geselecteerde tabellen. Met keep-existing-records = true worden nieuwe records toegevoegd en bestaande records met dezelfde primary key bijgewerkt in compatibele tabellen. Records die niet in de nieuwe download voorkomen blijven dan staan. Dit geldt ook voor gegevens buiten de gekozen periode en gegevens die inmiddels in Ons zijn verwijderd; dit is dus geen automatische verwerking van verwijderingen uit Ons.

Gebruik desgewenst een relatieve periode, bijvoorbeeld start = now-30d en end = yesterday, om bij iedere run een recente periode opnieuw op te halen. De datumfilter is de periode die de tabel ondersteunt; hij betekent niet dat alleen sinds de vorige run gewijzigde records worden opgehaald. Kies een periode die de wijzigingen bevat die je wilt verversen, of ververs de volledige tabel. Je kunt de periode en keep-existing-records ook per tabel instellen.

Een fout of afgebroken download kan al wijzigingen hebben opgeslagen. Het terugdraaien van de volledige run wordt niet gegarandeerd. In compatibele behouden tabellen met een primary key blijven de vooraf aanwezige keys behouden. Controleer de uitkomst voordat rapportages de nieuwe download gebruiken. Zie voor een toelichting  de informatie onder het kopje Exitcodes in deze handleiding. 

Beschikbare datamodellen

Je kunt de ondersteunde datamodelversies voor de ingestelde omgeving opvragen zonder de doel-database te wijzigen:

onsdb.exe --config onsdb.cfg --list-versions

Op Linux/macOS gebruik je ./onsdb --config onsdb.cfg --list-versions. Hiervoor zijn een geldig configuratiebestand, een goedgekeurd certificaat en toegang tot de omgeving nodig. De uitvoer bevat de versienummers en verschijningsdatums. Stel zo nodig [onsdb] schema-version in op een beschikbare versie; zonder die instelling gebruikt OnsDB het nieuwste datamodel. Raadpleeg Datamodellen in OnsDB voor de beschrijvingen en ondersteuning.

Met onsdb.exe --help of ./onsdb --help toon je de beschikbare CLI-argumenten zonder configuratiebestand of verbinding.

Logbestand en voortgang

OnsDB maakt een logbestand met de naam onsdb-YYYY-MM-DD_HH-MM-SS.log. Na het verwerken van alle pagina's van een resource verschijnt één samenvattingsregel met het aantal geschreven records, het aantal waarschuwingen en fouten als die er zijn, de gedownloade (eventueel gecomprimeerde) en uitgepakte grootte, en de download- en verwerkingstijd. De tijden zijn opgeteld over de workers; downloaden en verwerken kunnen overlappen. Het aantal waarschuwingen omvat afgekapte stringwaarden en opnieuw uitgevoerde downloadpogingen. Een resource met recordfouten wordt als completed with errors vermeld; een mislukte resource wordt als failed vermeld.

Met log-jobs = false in [onsdb] kun je de afzonderlijke taakmeldingen uitschakelen. De samenvattingen, waarschuwingen, foutmeldingen en live voortgang blijven zichtbaar.

Exitcodes

OnsDB gebruikt de volgende exitcodes. Een geplande taak of script kan hiermee controleren of de opdracht is geslaagd.

Waarschuwingen tijdens de download, zoals het afkappen van een te lange string, veranderen de exitcode niet. Een run met job- of recordfouten logt Completed with N errors, schrijft het ingestelde rapport waar mogelijk, en eindigt met code 2. Code 3 betekent dat de gedownloade gegevens succesvol zijn opgeslagen, maar het rapport niet kon worden geschreven. Bij zowel downloadfouten als een rapportfout krijgt code 2 voorrang en worden beide fouten vermeld. Geen van deze foutcodes betekent dat wijzigingen worden teruggedraaid.

Wijziging ten opzichte van OnsDB 4: runs met job- of recordfouten geven nu exitcode 2 terug. Houd hiermee rekening in scripts en geplande taken.

Eerste certificaataanvraag

Voor het aanvragen van het certificaat moet eerst het configuratiebestand gevuld zijn. Zie voor een uitleg over hoe het configuratiebestand opgebouwd moet worden de handleiding over de Configuratiebestand voor OnsDB 5.

1. De eerste keer dat OnsDB gestart wordt op een nieuwe machine of voor een nieuwe klantomgeving, wordt automatisch een nieuw certificaat aangevraagd. 
   
   OnsDB bewaart de nieuwe sleutel in de map ssl in de huidige werkmap. Laat deze map staan wanneer je de aanvraag bevestigt en opnieuw start.
   
   
2. Zodra de client een eerste keer gedraaid heeft, dan wordt een link naar het Ons API Dashboard gelogged. Deze link kan gebruikt worden om te bevestigen dat de aanvraag daadwerkelijk gedaan is door de correcte partij.
   
   Als de client aangeeft dat de klantcode of connector naam niet bekend is, dan is er waarschijnlijk een typefout gemaakt voor een van de twee. Weet je niet welke connector naam je moet gebruiken? Lees dan OnsDB Toegang configureren via Ons API Dashboard.

3. Voor een klantomgeving op staging of productie moet de zorgorganisatie via Ons Podium toestemming geven voor de koppeling en de gekozen versie. Volg hiervoor de stappen onder het kopje Toegang tot klantomgevingen in de handleiding OnsDB 5:Toegang configureren via Ons API Dashboard. Voor de ontwikkelomgeving TE1002 is deze klanttoestemming niet nodig; de certificaataanvraag moet wel worden bevestigd.

4. Zolang de bevestiging of benodigde toestemming ontbreekt, stopt de client met exitcode 1. Nadat beide geregeld zijn zal bij een eerstvolgende poging een download starten.

Vernieuwing certificaat

Een certificaat heeft een geldigheid van één jaar. OnsDB zal één maand voor het verlopen een nieuw certificaat aanvraag doen. Deze moet weer bevestigd worden in het Ons API Dashboard door de link die de OnsDB client logt te gebruiken.