OpenAC 3 Server installatie

Systeemeisen

OpenAC 3 is beschikbaar in twee varianten:

• win7-x64​ (Windows Server 2008 R2, 64-bit)
• win81-x64​ (Windows Server 2012, 64-bit)

Een zip-bestand van één van deze varianten kan worden gedownload op de Server releases pagina. Er wordt sterk aangeraden om met minimaal Windows Server 2012 te werken.

De OpenAC webapplicatie werkt met de browsers Google Chrome, Mozilla Firefox en Microsoft Edge. Microsoft Internet Explorer wordt niet meer ondersteund.

Ondersteunde databases:

• Microsoft SQL Server: OpenAC ondersteunt de oudste versie die door de fabrikant wordt ondersteund (op het moment van schrijven MS SQL Server 2012).
• MySQL: minimaal versie 5.5

Installatie

Het installeren van OpenAC bestaat uit de volgende stappen:

• Uitpakken van het zip-bestand
• Configuratie
• Eerste keer starten
• Controle logbestanden
• Testen werking Message Queue (agendaserver)
• Installeren Windows service
• Installeren protocol handler (optioneel)
• Installeren document server (WebDAV, optioneel)

Uitpakken van het zip-bestand

Maak een map aan en pak het zip-bestand hierin uit. Na de installatie moet OpenAC worden geconfigureerd voordat het kan worden gestart.

Configuratie

OpenAC kent een viertal configuratiebestanden. Ze zijn te vinden in de root van de installatiemap en kunnen de eerste keer hier worden geconfigureerd. OpenAC zal de bestanden bij de eerste start kopiëren. Standaard gaan ze naar de ProgramData\OpenACWeb map maar dit kan gespecificeerd worden met de -c of --config parameter gevolgd door het pad van de map. In het vervolg moeten ze op die locatie worden gewijzigd. De volledige locatie kun je opzoeken in het OpenAC statusscherm.

appsettings.json	Configuratie van database- en applicatie-specifieke instellingen
hosting.json	Configuratie van de OpenAC webserver
messagequeue.json	Configuratie van de OpenAC Message Queue (agendaserver)
nlog.config	Configuratie van de logbestanden

Zie het kopje Configuratiebestanden voor meer informatie over het configureren van OpenAC.

Eerste keer starten

Test de configuratie door OpenAC te starten in de console. Open een command prompt en ga naar de installatiemap. Start de server op met:

OpenACWeb.exe

Navigeer met een browser naar de homepage op ​http://localhost:<poort>/ en kijk of je kunt inloggen. Als je kunt inloggen dan is de database correct geconfigureerd. Op de statuspagina, bereikbaar via Beheer -> Status kun je o.a. zien wat de data- en configuratie directory is die OpenAC gebruikt:

Controle logbestanden

In de standaardconfiguratie maakt OpenAC twee logbestanden aan:

openac-alles-<datum>.log	De meest uitgebreide logging, inclusief alle binnenkomende request
openac-applicatie-<datum>.log	OpenAC-specifieke logging, inclusief eventuele foutmeldingen. Als ontwikkelaars een logbestand opvragen gaat het bijna altijd om dit bestand

De logdirectory, het aantal logbestanden en de inhoud hiervan kan worden geconfigureerd met nlog.config. Controleer na de eerste keer starten of de logbestanden zijn aangemaakt en dat de inhoud overeenkomt met wat je verwacht.

Testen werking Message Queue (agendaserver)

De OpenAC Message Queue wordt hoofdzakelijk gebruikt om de agenda's te synchroniseren. Als iemand iets wijzigt in een agenda dan wordt dit via de Message Queue doorgegeven aan alle OpenAC werkstations die een verbinding hebben met de OpenAC 3 server. Als de server is gestart dan kun je de werking van de Message Queue testen.

In het instellingenscherm van OpenAC 2 moet onder het kopje "OpenAC Server" het vinkje voor "Start client" aanstaan. De instellingen achter "Server" en "MessageQueue? Poort" moeten overeenkomen met de instellingen in messagequeue.json.

Zorg er ook voor dat bovengenoemde instellingen zijn aangevinkt bij "Instelling voor alle gebruikers" zodat ze in de database worden opgeslagen en daardoor voor iedereen gelijk zijn.

De Message Queue kan worden getest door twee instanties van OpenAC 2 op te starten. Wijzigingen die je in de agenda van de één doet moeten na een korte vertraging automatisch verschijnen in de agenda van de ander. Let er wel op dat de agendalocatie voor beide instanties van OpenAC gelijk is.

Key Server

OpenAC 3 heeft een ingebouwde key server om database keys uit te geven. Zie voor meer informatie de Key Server moduleconfiguratie.

(optioneel) Installeren Windows service

Een belangrijk voordeel van het installeren als een Windows service is dat de applicatie de resources efficiënter gebruikt waardoor de applicatie sneller wordt. Voor het installeren of de-installeren van een service zijn Administrator bevoegdheden nodig.

de-installeren oude service

Als de oude agendaserver nog in gebruik is dan moet je deze allereerst verwijderen.

Voor OpenAC 3 gebruikten we een stand-alone Message Queue (agendaserver) om de agenda's te synchroniseren. Deze agendaserver kon als Windows service worden geïnstalleerd en is herkenbaar aan de executable "openac-server.exe". In het overzicht met Windows services heet de service "OpenACService".

Als deze service nog in gebruik is dan dien je hem te verwijderen voordat je de OpenAC 3 service kunt installeren. Ga eerst naar het services scherm en stop de oude service. Zet voor de zekerheid opstarttype op handmatig om te voorkomen dat de oude service automatisch wordt gestart als het verwijderen zou mislukken. Om de service te verwijderen open je een command prompt als administrator. Voer het volgende commando uit:

sc delete OpenACService

Als de oude service met een andere dan de default naam is geïnstalleerd dan de default naam, voer dan bovenstaand commando uit met de overeenkomstige naam.

installeren nieuwe service

De server kan als service worden geïnstalleerd door de executable te starten met parameter --install-service. Open een command prompt als adminstrator en ga naar de installatiemap. Installeer de service met:

openacweb.exe --install-service

Standaard is de naam van de service OpenAC-Service maar die kan gespecificeerd worden met parameter -n of --servicename gevolgd door de naam. Als het installeren van de service is gelukt volgt de melding:

De OpenAC service is met succes ge-installeerd.

Wanneer een andere naam dan de standaard gebruikt wordt, dan wordt die in de melding meegenomen (... met de naam [...]). Wanneer de parameter -c of --config gebruikt wordt dan zal de service de aangepaste locatie van configuratiebestanden gebruiken.

Als het installeren van de service gelukt is dan moet hij de eerste keer handmatig worden gestart vanuit het services scherm.

de-installeren nieuwe service

Om de service te verwijderen ga eerst naar het services scherm en stop de service. Open daarna een command prompt als administrator. Voer het volgende commando uit:

sc delete OpenAC-Service

Voor het installeren van een nieuwe versie van OpenAC 3 is het niet nodig om de service te de-installeren. De service stoppen en na de upgrade opnieuw starten is voldoende.

Configuratiebestanden

appsettings.json

Configuratie van database- en applicatie-specifieke instellingen. Voordat de server kan worden getest moet eerst de database worden geconfigureerd. Dat kan in appsettings.json. Voorbeeld voor MySQL:

 /*
   * De database verbinding wordt geregeld door een database provider;
   * voor de provider geldt een connection string om de verbinding te
   * configureren.
   *
   * Geldige waarden voor ProviderName zijn: MySql, MSSql (niet-case-sensitive).
   * Geldige waarden voor ConnectionString hangen af van de gekozen provider.
   */
  "Database": {
    "ProviderName": "MySql",
    "ConnectionString": "server=127.0.0.1;userid=userid;password=password;database=database;SslMode=none"
  }

Voorbeeld voor SQL Server met gebruikersnaam en wachtwoord:

"Database": {
    "ProviderName": "MSSql",
    "ConnectionString": "Server=server\instance;Database=database;User Id=userid;Password=password;"
}

In plaats van server\instance is het ook mogelijk een adres te gebruiken. Let op, server authentication moet zijn ingesteld op "SQL Server and Windows Authentication mode" (mixed mode), anders werkt inloggen met gebruikersnaam en wachtwoord niet.

Voorbeeld voor SQL Server met Windows Integrated Security:

"Database": {
    "ProviderName": "MSSql",
    "ConnectionString": "Server=server\instance;Trusted_Connection=True;"
}

In plaats van server\instance is het ook mogelijk een adres te gebruiken. De datatabase wordt nu benaderd met de identity waarmee de windows sessie is gestart. Deze zal dus voldoende rechten op de database moeten hebben.

Configureren serieprefix

De serie-prefix sectie komt overeen met de serieprefix-functie in de eigen adaptatie van OpenAC 2, maar dan configuratie-gestuurd.

Keys in OpenAC tabellen bevatten vaak een zogenaamde serieprefix. In de key ACH-17H12345 is "ACH" de centrumprefix en "17H" de serieprefix. Configureer serieprefixen door in appsettings.json een sectie "Serieprefix" toe te voegen aan de sectie "Agb".

Voor elke tabel/locatie-combinatie kan een eigen serieprefix worden opgegeven. De locatiecomponent is optioneel, je zou kunnen volstaan met alleen een "default"-sectie.

In de prefixspecificatie kunnen de volgende variabelen worden gebruikt:

locatiecode	De locatiecode
jaar	De vier cijfers van het jaar
jaar2	De laatste twee cijfers van het jaar
jaarletter	Het jaar geconverteerd naar een letter
maand	De maand in twee cijfers

Variabelen moeten tussen accolades staan.

Als voorbeeld: de specificatie "{jaar2}{locatiecode}" wordt in 2023 en locatiecode "H" vertaald naar "23H".

Onderstaand voorbeeld configureert een serieprefix voor tabellen "patient" en "relatie":

    "Serieprefix": {
      "patient": {
        "Q": "H{jaar2}-",
        "default": "OA"
      },
      "relatie": {
        "default": "R{jaar2}{locatiecode}"
      }
    },

De serieprefix wordt "H23-" voor tabel "patient" en locatie "Q" in 2023. Voor alle locaties geldt de default-sectie en wordt de serieprefix "OA". Voor tabel "relatie" wordt de serieprefix "R23X" voor alle locaties in 2023, waarbij X staat voor de locatiecode.

T/m build 3.2023.0418 werd de specificatie automatisch "{jaar2}{locatie}" voor alle tabellen zonder eigen specificatie. Bij alle builds na 3.2023.0418 is het mogelijk om niet alleen voor locaties maar ook voor tabellen een default-sectie op te nemen:

    "Serieprefix": {
      "patient": {
        "Q": "H{jaar2}-",
        "default": "OA"
      },
      "relatie": {
        "default": "R{jaar2}{locatiecode}"
      },
      "default": {
        "H": "{jaarletter}{maand}",
        "default": "{jaar2}{locatiecode}"
    },

In bovenstaand voorbeeld krijgen alle tabellen behalve "patient" en "relatie" serieprefix "{jaarletter}{maand}" voor locatie "H" en anders "{jaar2}{locatiecode}"

Als alle tabellen en locaties dezelfde serieprefix moeten krijgen kan dit als volgt worden geconfigureerd:

    "Serieprefix": {
      "default": {
        "default": "{jaarletter}{maand}"
    },

Configureren keylengte

Keys in OpenAC tabellen krijgen een bepaalde lengte toegewezen voor het volgnummer. De centrumprefix doen niet mee bij het bepalen van de keylengte, de serieprefix wel. In de key ACH-H12345 is de keylengte 6. In dit voorbeeld is de centrumprefix is "ACH-" en de key "H12345". De key bestaat uit een serieprefix en een volgnummer. De lengte van het volgnummer is dus gelijk aan de lengte van de key minus de lengte van de serieprefix. In OpenAC 2 is de keylengte terug te vinden in het scherm Beheer - Tabeldefinities. Als een keylengte is gedefinieerd als "patient+1" en de keylengte van patient is 6, dan wordt de keylengte 7 in OpenAC 3. Gebruik dus niet de constructie patient+1. OpenAC 3 hanteert een default keylengte van 8. Je hoeft in appsettings dus alleen keylengtes op te nemen voor tabellen met een keylengte ongelijk aan 8.

Het kan zijn dat een oplopend volgnummer ervoor zorgt dat de key langer wordt dan de keylengte in de tabeldefinitie. Als de keylengte van patient 6 is, de seriprefix "H" en het aantal patienten binnen een serie groter dan 99999, dan wordt de eerstvolgende key H100000. Deze key heeft een lengte van 7 en is dus langer dan de definitie die 6 voorschrijft. Dit kan verder geen kwaad.

Configureer keylengtes door in appsettings.json een sectie "TabelKeyLengtes" toe te voegen aan de sectie "Agb".

    "TabelKeyLengtes": {
        "patient": 6,
        "behandeldag": 7
    },

Configureren nieuwe stijl keys

Voor de meeste tabellen gebruikt OpenAC primary keys die zijn opgebouwd volgens het patroon <centrumprefix>-<serieprefix><volgnummer>. AC's bepalen zelf de samenstelling van de serieprefix. Vaak bevat deze informatie over het jaar van uitgifte en/of de locatie. Zie de voorgaande paragrafen voor meer informatie. Nadeel van dit soort keys is dat bij het uitgeven van nieuwe primary keys de tabel moet worden gelockt om conflicten te voorkomen. Deze locks veroorzaken regelmatig lock wait foutmeldingen in OpenAC.

Voorbeelden van tabellen waar bij gebruik van OpenAC veel records voor worden aangemaakt zijn behandeldag (bezoek) en plandag (reserveringen, richtafspraken, afspraken en annuleringen). Deze tabellen hebben op het moment van schrijven al een paar jaar een apart veld voor het registreren van de locatie. De locatie hoeft dus niet meer in de key te worden gecodeerd. We kunnen veel van de lock conflicten voorkomen door voor deze tabellen "nieuwe stijl keys" te gaan gebruiken. Nieuwe stijl keys zijn gebaseerd op een date/time-stamp. Deze keys zijn niet nieuw voor OpenAC; ze worden al geruime tijd gebruikt voor tabel tijdvak. Gebruik van nieuwe stijl keys voor andere tabellen dan tijdvak is mogelijk sinds build 3.2024.0217. Hiertoe moet je in appsettings.json onder "Database" een sectie "NieuweStijlKeys?" opnemen als volgt:

"Database": {
    "ProviderName": "MSSql",
    "ConnectionString": "Server=LT-006;Database=ac_hoensbroek2;User Id=fenac;Password=*;TrustServerCertificate=true",
    "NieuweStijlKeys" : {
        "behandeldag": true,
        "plandag": true
    }
},

Na elke wijziging in appsettings moet je de OpenAC service opnieuw starten. Mocht je terug willen schakelen naar oude stijl keys dan kun je true veranderen in false, of de sectie "NieuweStijlKeys?" helemaal verwijderen. We willen geleidelijk bij meer tabellen nieuwe stijl keys gaan gebruiken. Hiervoor kunnen we simpelweg het lijstje tabellen in de sectie NieuweStijlKeys? uitbreiden. Er zijn geen verdere updates voor nodig. Doe dit altijd in overleg met de Fenac.

Configureren HTTPS

Het is mogelijk om urls met https te specificeren in hosting.json (zie hier onder) met een eigen certificaat. Het certificaat kan verkregen worden op meerdere plekken, maar dat is buiten de scope van deze documentatie. Het certificaat, opgeslagen in een PFX bestand, met het wachtwoord kan gebruikt worden of niet (Enabled op false). Zo niet, dan zal OpenAC3 het certificaat niet gebruiken, specificeer dan ook geen https url in hosting.json.
Specificeer als volgt een blokje in appsettings.json:

  "HTTPS": {
    "Enabled": true,
    "CertificateFile": "C:\\ProgramData\\OpenACWeb\\letsencrypt.pfx",
    "CertificatePassword": "SuPeRgEhEiM"
  }

Als OpenAC3 draait op een Windows versie lager dan Windows 10 of Windows Server 2019 dan zal HTTPS activeren er voor zorgen dat HTTP1.1 wordt gebruikt in plaats van HTTP/2, wat mogelijk performance beïnvloedt.

hosting.json

Configuratie van de OpenAC webserver. De interface:poort combinatie waarop de server luistert.

{
  "server.urls": "http://0.0.0.0:5000"
}

0.0.0.0 betekent dat de server op elke netwerk interface luistert. Dit is de geadviseerde instelling. Het poortnummer moet overeenkomen met nummer achter "Webserver Poort" in de sectie "OpenAC Server" van het instellingenscherm van OpenAC 2.

messagequeue.json

Configuratie van de OpenAC Message Queue (agendaserver). De OpenAC Message Queue is belangrijk voor optimaal functioneren van OpenAC 2 waarvoor het ondermeer het synchroniseren van de agenda's verzorgt.

{
  "MessageQueue": {
    "Port": 2200,
    "Start": true
  }
}

Het nummer achter "Port" moet overeenkomen met het nummer achter "MessageQueue Poort" in de sectie "OpenAC Server" van het instellingenscherm van OpenAC 2. Door "Start" op false te zetten wordt de MessageQueue niet gestart.

nlog.config

Configuratie van de logbestanden.

Voor het aanmaken van logbestanden gebruikt OpenAC de logmodule NLog. NLog moet worden geconfigureerd met het configuratiebestand nlog.config waarvan hieronder een voorbeeld te zien is:

<?xml version="1.0" encoding="utf-8" ?>
<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      autoReload="true"
      internalLogLevel="Error"
      internalLogFile="c:\temp\internal-nlog.txt">

  <!-- Zie nlog_readme.txt voor request-ip configuratie -->
  
  <variable name="logDirectory" value="C:\temp" />

  <targets async="true">
    <target xsi:type="File"
            name="allfile"
            fileName="${logDirectory}\openac-alles-${shortdate}.log"
            layout="${longdate}|${uppercase:${level}}|${event-properties:item=EventId.Id}|${logger}|${message} ${exception}"
            keepFileOpen="true"
            concurrentWrites="true"
            archiveAboveSize="10000000"
            maxArchiveFiles="500"
            autoFlush="false"
            openFileFlushTimeout="5"
            archiveOldFileOnStartup="true"
            fileAttributes="NotContentIndexed"
          />
   
    <target xsi:type="File"
            name="ownFile"
            fileName="${logDirectory}\openac-applicatie-${shortdate}.log"
            layout="${longdate}|${uppercase:${level}}|${event-properties:item=EventId.Id}|${aspnet-Request-IP}|${logger}|${message} ${exception}" 
            keepFileOpen="true"
            concurrentWrites="true"
            archiveAboveSize="10000000"
            maxArchiveFiles="500"
            autoFlush="false"
            openFileFlushTimeout="5"
            archiveOldFileOnStartup="true"
            fileAttributes="NotContentIndexed"
          />

    <target xsi:type="Null" name="blackhole" />
  </targets>

  <rules>
    <!--All logs, including from Microsoft-->
    <logger name="*" minlevel="Debug" writeTo="allfile" />

    <!--Skip Microsoft logs and so log only own logs-->
    <logger name="Microsoft.*" minlevel="Debug" writeTo="blackhole" final="true" />
    <logger name="*" minlevel="Debug" writeTo="ownFile" />
  </rules>
</nlog>

Begin met het instellen van de gewenste logdirectory. Standaard staat deze ingesteld op c:\temp. Vergeet niet dat de logdirectory moet bestaan en dat OpenAC moet kunnen schrijven naar deze directory. Loggen naar een lokale file, op een lokale hard disk, is sneller t.o.v. loggen naar een file op het netwerk.

De volgende stap is het instellen van het minimum loglevel. NLog kent een aantal loglevels en alles wat OpenAC logt met het minimum level en hoger komt in de logbestanden terecht. Dus hoe hoger het minimum loglevel, hoe minder er in de logbestanden komt.

De loglevels zijn in aflopende volgorde:

Fatal	Alleen fatale fouten
Error	Fouten en hoger
Warn	Waarschuwingen en hoger
Info	Meldingen en hoger
Debug	Debug-meldingen en hoger. Bedoeld om fouten op te sporen
Trace	Trace-meldingen en hoger. Logt het begin en einde van elke functie-aanroep. Genereert extreem veel logmeldingen

We adviseren om minlevel in te stellen op "Info". Bij het oplossen van problemen zal de FENAC soms vragen om minlevel tijdelijk op "Debug" of "Trace" te zetten.

Ook het formaat van elke logregel kan worden geconfigureerd met nlog.config. Hiervoor kun je een regel-template opgeven achter het keyword "layout". De variabelen die je in de regel-template kunt gebruiken kun je terugvinden in de NLog-documentatie op ​https://github.com/nlog/nlog/wiki/Layout-Renderers. Let wel dat het mogelijk is dat de versie van NLog die OpenAC gebruikt niet alle variabelen ondersteunt die in de documentatie zijn terug te vinden.

We adviseren om ${longdate}|${uppercase:${level}}| aan het begin van elke logregel te zetten. Ook kan het handig zijn om ${aspnet-Request-IP} op te nemen zodat het IP-adres van elke client wordt gelogd.

Met de url http://<openac3-server>:<poort>/logleveltest kan de logconfiguratie worden getest. Dit genereert entries in het log die er afhankelijk van de configuratie ongeveer als volgt uitzien:

2018-02-19 13:54:31.0369|FATAL||192.168.0.234|OpenACLogica.Controllers.StatusController|Here is a Fatal message. 
2018-02-19 13:54:31.0539|ERROR||192.168.0.234|OpenACLogica.Controllers.StatusController|Here is a Error message 
2018-02-19 13:54:31.0539|WARN||192.168.0.234|OpenACLogica.Controllers.StatusController|Here is a Warning message 
2018-02-19 13:54:31.0769|INFO||192.168.0.234|OpenACLogica.Controllers.StatusController|Here is a Information message 
2018-02-19 13:54:31.0879|DEBUG||192.168.0.234|OpenACLogica.Controllers.StatusController|Here is a Debug message. 
2018-02-19 13:54:31.1013|DEBUG||192.168.0.234|OpenACLogica.Controllers.StatusController|Here is a DebugInfo message. 

Logregels kunnen uitgevoerd worden naar aparte bestanden. Om bijvoorbeeld alle fouten in een los bestand te verzamelen kan een nieuw target met rule gedefinieerd worden. Match de waarde van het "writeTo" attribuut met de naam van het target.

 <targets>
    ...
    <target xsi:type="File"
            name="errorfile"
            fileName="${logDirectory}\openac-errors-${shortdate}.log"
            layout="${longdate}|${uppercase:${level}}|${event-properties:item=EventId.Id}|${logger}|${message} ${exception}"
            ...
          />


  <rules>
     ...
	<logger name="*" minlevel="Error" writeTo="errorfile" />