Introduktion

Formål

Dette dokument er rettet mod systemadministratorer og driftspersoner, som skal kunne håndtere driftsmæssige aspekter af FSK Registry Adapter.

...

Specielle krav til backup er beskrevet i afsnit 7, ligesom procedure ved reetablering af komponenten ud fra backup beskrives.

Læsevejledning

Læseren forventes at have kendskab til National Sundheds-IT’s platform NSP, samt generelt kendskab til WildFly applikationsserver samt Ubuntu Linux operativ system.

Dokumenthistorik

Dette dokument er oprettet i forbindelse med den initielle udviklings af komponenten.

Definitioner og referencer

Komponenten

FSK Registry Adapter komponenten kan beskrives som følger:

• FSK Registry Adapter

• Type: Webservice

• Filnavn: fskregistry.war

• Url: <serverurl>/fskregistry

• Helbredsurl: <serverurl>/fskregistry/health

Daglig drift

Dette afsnit beskriver den daglige drift af systemet.

Database

FSK Registry Adapter anvender en database til persistering og afhentning af metadata. Denne database ejes imidlertid af en anden komponten: FSK Repository. Det er FSK Repository komponentens ansvar at beskrive backupprocedurer for databasen.

Relaterede services

FSK Registry Adapter afhænger af:

...

Ved fejl i forbindelse til denne denne vil FSK Registry Adapter returnere svar til anvendere, hvoraf det fremgår, at der er fejl.

Konfiguration

Opsætningen for FSK Registry Adapter sker i propertyfilen fskreg.properties.

Denne indlæses fra WildFly modulet:

Hvis FSK registry startes vha. docker-compose, så bliver konfigurationsfilerne automatisk flyttet til de foldere, som er angivet docker-compose opskriften.

...

Den primære folder, hvor flest konfigurationsfiler, som skal bruges af FSK registry er:

/pack/wildfly8/modules/sds/fskregistry/configuration/

...

main/

Desuden bruges følgende til deploy af datasource konfigurationer:
/pack/wildfly8/standalone/deployments/

Og til konfiguration af AccessHandler bruges:
/pack/wildfly8/modules/system/layers/base/dk/sds/nsp/accesshandler/main/

Konfiguration af FSK Resgitry

Opsætningen for FSK Registry Adapter sker i propertyfilen fskreg.properties.

Et eksempel på sådan konfiguration er:

cprexists.validationlevel=WARNING
cprexists.url=http://test1-cnsp.ekstern-test.nspop.dk:8080/stamdata-cprexists

documentEntry.title=Fælles stamkort

documentEntry.mimeType=text/xml
documentEntry.languageCode=da-DK

documentEntry.patient.assigningAuthority.root=1.

Et eksempel på sådan konfiguration er:

documentEntry.title=TestTitle

documentEntry.mimeType=text/xml
documentEntry.languageCode=da-DK

documentEntry.patient.assigningAuthority.root=1.2.208.176.1.2
documentEntry.organisation.assigningAuthority.root=1.2.208.176.1.2
documentEntry.organisation.assigningAuthority.root=1.2.208.176.1.1

documentEntry.homeCommunityId=1.2.3208.7176.8.1.12
documentEntry.repositoryUniqueId=31.42.6.7208.176.43210.8.10.12

documentEntry.confidentialityCodehealthcareFacilityTypeCode.code=N554041000005106
documentEntry.confidentialityCodehealthcareFacilityTypeCode.schemeName=2.16.840.1.113883.56.2596
documentEntry.confidentialityCodehealthcareFacilityTypeCode.name=Normalsundhedsforvaltning

documentEntry.healthcareFacilityTypeCodeclassCode.code=22232009001
documentEntry.healthcareFacilityTypeCodeclassCode.schemeName=1.2.16208.840184.1.113883.6.96100.9
documentEntry.healthcareFacilityTypeCodeclassCode.name=hospitalKlinisk rapport

documentEntry.author.practiceSettingCodeorganisation.codeid=4084430031126211000016009
documentEntry.author.organisation.name=Fælles Stamkort udstedelse

documentEntry.practiceSettingCode.code=408443003
documentEntry.practiceSettingCode.schemeName=2.16.840.1.113883.6.96
documentEntry.practiceSettingCode.name=almen medicin

documentEntry.classCodeconfidentialityCode.code=001N
documentEntry.classCodeconfidentialityCode.schemeName=12.16.2840.2081.184113883.1005.925
documentEntry.classCodeconfidentialityCode.name=Klinisk rapport

documentEntry.formatCode.codenormal

# formatCodeCode og typeCode par i tabel. Hver par har eget løbenummer
documentEntry.metadata.metadataEntry[0].formatCodeCode=urn:ad:dk:medcom:appointmentsummarypdc-v2.0:full
documentEntry.formatCode.schemeName.metadata.metadataEntry[0].formatCodeScheme=1.2.208.184.100.10
documentEntry.formatCode.namemetadata.metadataEntry[0].formatCodeName=DK Appointment Summary DocumentPDC schema

documentEntry.eventCode.code=39289-4.metadata.metadataEntry[0].typeCodeCode=PDC
documentEntry.eventCode.schemeName=2.16.840.1.113883.6.1
documentEntry.eventCode.name=Dato og tidspunkt for møde mellem patient og sundhedsperson

documentEntry.typeCode.code=39289-4
documentEntry.typeCode.schemeName=2.16.840.1.113883.6.1
documentEntry.typeCode.name=Dato og tidspunkt for møde mellem patient og sundhedsperson

documentEntry.author.organisation.id=291000016008
documentEntry.author.organisation.name=Region Test

#documentEntry.patient.assigningAuthority.name=CPRmetadata.metadataEntry[0].typeCodeScheme=1.2.208.184.100.1
documentEntry.metadata.metadataEntry[0].typeCodeName=Stamkort

documentEntry.metadata.metadataEntry[1].formatCodeCode=urn:ad:dk:medcom:pdc-v3.0:full
documentEntry.metadata.metadataEntry[1].formatCodeScheme=1.2.208.184.100.10
documentEntry.metadata.metadataEntry[1].formatCodeName=DK PDC schema
documentEntry.metadata.metadataEntry[1].typeCodeCode=PDC
documentEntry.metadata.metadataEntry[1].typeCodeScheme=1.2.208.184.100.1
documentEntry.metadata.metadataEntry[1].typeCodeName=Stamkort

Properties beskrives ifølge tabel: 

documentEntry.title

documentEntry.mimeType

documentEntry.languageCode

documentEntry.patient.assigningAuthority.root

documentEntry.organisation.assigningAuthority.root

documentEntry.homeCommunityId

documentEntry.repositoryUniqueId

documentEntry.confidentialityCode.code, schemaName, name

documentEntry.title

documentEntry.healthcareFacilityTypeCode.code, schemaName, name

documentEntry.practiceSettingCode.code, schemaName, namemimeType

documentEntry.classCode.code, schemaName, namelanguageCode

documentEntry.formatCode.code, schemaName, namepatient.assigningAuthority.root

documentEntry.eventCode.code, schemaName, nameorganisation.assigningAuthority.root

documentEntry.typeCode.code, schemaName, namehomeCommunityId

documentEntry.

repositoryUniqueId

documentEntry.healthcareFacilityTypeCode.code, schemaName, name

documentEntry.author.organisation.id

documentEntry.author.organisation.nameauthor.organisation.id

Som det fremgår af navnene ovenfor anvendes disse properties til at udfylde DocumentEntries ved søgninger mod FSK Registry. DocumentEntry metadata værdierne bør koordineres og opsættes, så de passer med CDA værdierne, der returneres i dokumenterne fra FSK Repository.

Den eneste property, der varierer fra miljø til miljø er angivelsen af repositoryUniqueId - resten er de samme henover miljøer.

Derudover anvendes parametrene til at afgøre, om FSK Registry skal returnere data ved forspørgsler eller ej. 

Hvis der f.eks. medsendes et søgeparameter i søgningen (ITI-18) på eventCode, så skal søgeværdien matche med værdien documentEntry.eventCode.code for, at der returneres en DocumentEntry for den pågældende borger.

Der filtreres på classCodeshealthcarefacility, typeCodes, eventCodes, confidentialityCodes og formatCodes formatCodes og typeCodes modsvarer lignende navne i søge-parametre efter følgende opskrift:

1. Filterets eventCodes code ikke er tomt, og

2. Ingen af evt. flere eventCodes koder fra søge-parametre findes i filterets eventCodes-listefilterets 

Tilsvarende logik er gældende de øvrige koder i filteret.

Konfiguration af log4j

Log4j konfiguration findes i følgende fil:

• log4j.properties

...

Eksempel på konfiguration:

/pack/wildfly8/modules/sds/fskregistry/configuration/

Eksempel på konfiguration:

log4j.rootCategory=log4j.rootCategory=INFO, FILE
log4j.logger.dk.sds=DEBUG

log4j.appender.FILE=org.apache.log4j.RollingFileAppender
log4j.appender.FILE.File=${jboss.server.log.dir}/fsk-registry.log
log4j.appender.FILE.Append=true
log4j.appender.FILE.MaxFileSize=100MB${dk.nsp.log.MaxFileSize}
log4j.appender.FILE.MaxBackupIndex=10${dk.nsp.log.MaxBackupIndex}
log4j.appender.FILE.layout=org.apache.log4j.PatternLayout
log4j.appender.FILE.layout.ConversionPattern=%d [%-2p] %c - %m%n

Udpegning af SLA-log konfiguration

Følgende fil udpeger hvilken fil, der indeholder konfigurationen af SLA-logning:

• log4j-nspslalog-fskreg.properties

Denne indlæses fra WildFly modulet:

/pack/wildfly8/modules/nsi/ddsprojects/ao/documentmetadataprovider/config/<profil-navn>/

Per default udpeges konfigurationsfilen beskrevet i næste Per default udpeges konfigurationsfilen beskrevet i næste afsnit.

Konfiguration af SLA-log

Per default indlæses konfigurationen af Aftaleoversigt XDS FSK Registry Adapters SLA-logning fra følgende fil:

• log4j-nspslalog-ao-documentmetadataproviderfskreg.properties

Denne indlæses fra WildFly modulet:

/pack/wildfly8/modules/nsi/ddsprojects/ao/documentmetadataprovider/config/<profil-navn>/

Konfiguration af Aftaleoversigt XDS Repository Adapter

Konfiguration af dokumentprovider

XDS Repository Adapter konfigureres i følgende fil:

• aoproviderconfiguration.xmll

Denne indlæses fra WildFly modulet:

/pack/wildfly8/modules/nsi/ddsprojects/ao/documentprovider/config/<profil-navn>/

Et eksempel på indhold i aoproviderconfiguration.xml:

<ProviderConfiguration>
     <homeCommunityId>1.2.3.7.8</homeCommunityId>
     <repositoryUniqueId>1.2.3.4.77.88</repositoryUniqueId>
</ProviderConfiguration>

Udpegning af log4j-konfigurationsfil

Følgende fil, der findes under roden i war-filen ao-documentprovider-<profil-navn>.war, udpeger den fil, der anvendes til konfiguration af log4j:

• documentsharing.log4j.properties

Bemærk, at denne fil (om nødvendigt) skal tilpasses direkte i war-filen og ikke findes i WildFly modulet.

Konfiguration af log4j

Log4j konfiguration findes i følgende fil:

• log4j-ao-documentprovider-ws.xml

Denne indlæses fra WildFly modulet:

/pack/wildfly8/modules/nsi/ddsprojects/ao/documentprovider/config/<profil-navn>/

I konfigurationen er det muligt at aktivere performanceloggeren, der udvalgte steder i adapteren, vil skrive tidsvarighed af kald igennem systemet. Performanceloggeren aktiveres ved at ændre level værdien fra ”OFF” til ”DEBUG”. Eftersom konfigurationen kun indlæses ved opstart af servicen, er det nødvendigt at genstarte servicen efter endt redigering af log4j-ao-documentprovider-ws.xml filen.

Eksempel på konfiguration af performanceloggeren, hvor level værdien er sat til ”OFF”:

<logger name="performancelogger" additivity="false">
	<level value="OFF" />
	<appender-ref ref="PerformanceFile" />
</logger>

Som standard skriver performanceloggeren til ao-<profil-navn>-documentprovider-ws-performance.log i WildFly’ log-folder.

Se yderligere opsætning i installationsvejledningen.

Udpegning af SLA-log konfiguration

Følgende fil udpeger hvilken fil, der indeholder konfigurationen af SLA-logning:

• nspslalog-ao-documentprovider.properties

Denne indlæses fra WildFly modulet:

/pack/wildfly8/modules/nsi/ddsprojects/ao/documentprovider/config/<profil-navn>/

Per default udpeges konfigurationsfilen beskrevet i næste afsnit.

Konfiguration af SLA-log

Per default indlæses konfigurationen af Aftaleoversigt XDS Repository Adapters SLA-logning fra følgende fil:

• log4j-nspslalog-ao-documentprovider.properties

Denne indlæses fra WildFly modulet:

/pack/wildfly8/modules/nsi/ddsprojects/ao/documentprovider/config/<profil-navn>/

HTTP Statuscheck på komponenter i Aftaleoversigt XDS-adaptere

Det er muligt at lave servicetjek på Aftaleoversigtsadaptere ved brug af den generelle service servicecheck.

For at understøtte servicetjek kræves konfiguration af servicecheck servicen, der er både generel og specifikt for aftaleoversigtsadaptere.

Følgende underafsnit beskriver den nødvendige konfiguration.

ServiceCheck.properties

Grundlæggende konfiguration af service-check sker ved tilretning af properties i ServiceCheck.properties filen.

Eksempel på ServiceCheck.properties

jmx.url=service:jmx:rmi://localhost/jndi/rmi://localhost:1090/jmxconnector
jmx.username=nisse
jmx.password=ngyffe
service.config.path=service-check.xml
log4j.path=servicecheck.log4j.properties

Konfiguration af log4j sker ved tilretning af properties i filen servicecheck.log4j.properties:

log4j.logger.service-check=INFO,sclog
log4j.appender.sclog=org.apache.log4j.RollingFileAppender
log4j.appender.sclog.File=${jboss.server.log.dir}/service-check.log
log4j.appender.sclog.layout=org.apache.log4j.PatternLayout
log4j.appender.sclog.layout.ConversionPattern=%d [%t] %-5p %c - %m%n

JMX-Console sikkerhedsopsætning

WildFly

Følgende script afvikles for at tilføje en ny JMX bruger på wildfly:

wildfly\bin\add-user.sh

Under opsætning af brugeren vælges typen ’Management User’ og muligheden for kommunikation på tværs af applikationsservere kræves ikke rettigheder til.

Når brugeren er oprettet med navn og kodeord ændres ServicesCheck.properties, så properties stemmer overens med det indtastede i add-user.sh scriptet.

Se afsnit 4.3.1 for et eksempel på konfiguration af jmx.username og jmx.password.

service-check.xml

Konfiguration af de enkelte checks for en service foretages ved tilretning af settings i service-check.xml filen. Nedenfor ses eksempel på konfiguration af Aftaleoversigt XDS Adapteres service check, der omfatter:

• Check i WildFly at servicen er registreret og aktiv

<service name="ao-documentmetadataprovider-<profil-navn>">
    <assertions resultCode="200">
        <mBeanCheck>         
			<ObjectName>jboss.as:deployment=ao-documentmetadataprovider-<profil-navn>.war,subsystem=undertow,servlet=MetadataProviderWS</ObjectName>
        </mBeanCheck>
    </assertions>
    <assertions resultCode="404">
        <mBeanCheck> 	         
			<ObjectName>jboss.as:deployment=ao-documentmetadataprovider-<profil-navn>.war,subsystem=undertow,servlet=MetadataProviderWS</ObjectName>
            <isRegistered>false</isRegistered>
        </mBeanCheck>
    </assertions>
</service>

<service name="ao-documentprovider-<profil-navn>">
    <assertions resultCode="200">
        <mBeanCheck> 	          
			<ObjectName>jboss.as:deployment=ao-documentprovider-<profil-navn>.war,subsystem=undertow,servlet=DocumentProviderWS</ObjectName>
        </mBeanCheck>
    </assertions>
    <assertions resultCode="404">
        <mBeanCheck> 	         
			<ObjectName>jboss.as:deployment=ao-documentprovider-<profil-navn>.war,subsystem=undertow,servlet=DocumentProviderWS</ObjectName>
            <isRegistered>false</isRegistered>
        </mBeanCheck>
    </assertions>
</service>

Test af service-check konfiguration

Efter konfiguration og deploy af ServiceCheck servicen, kan Aftaleoversigt XDS Adaptere servicecheck testes med følgende kommandoer:

curl –i localhost:9090/service-check/service?servicename=ao-documentmetadataprovider-<profil-navn>
curl –i localhost:9090/service-check/service?servicename=ao-documentprovider-<profil-navn>

Servicen returnerer følgende http koder:

• 200 ved normal situation.

• 404 hvis servicen ikke er deployed

• 405 ved fejlkonfiguration af url til check af service-check funktionen (for at lette fejlsøgning)

• 500 ved anden intern fejl ved forespørgsel i WildFly på den overvågede service

HTTP Versionsnummer-information på Aftaleoversigt XDS-adaptere

Der kan hentes versionsnummer fra kørende Aftaleoversigt XDS adaptere som givet i nedenstående tabel.

...

Aftaleoversigt XDS Repository Adapter

...

Auditlog

Hvis CPR validering kører i WARNING mode, så vil ugyldige (ifølge CPRExits service) CPR numre give anledning til en linje i auditloggen. Logninger af denne type ser således ud:

{"time":"2021-08-09T12:34:34.387Z","category":"dk.sds.nsp.audit.log.fskregistry","audit":{"timestamp":"2021-08-09T14:34:34.325+02:00","components":[{"component":"FskRegistry","contexts":[{"context":"iti-18","information":[{"key":"dk.nsp.cpr.exists.false","type":"SPI","value":"9932000000"},{"key":"dk.nsp.cpr.exists.false","type":"SPI","value":"9932000000"}]}]}]},"access":{"code":200,"duration":57,"httpHeaders":{"Content-Type":"application/soap+xml; charset=UTF-8"},"httpHost":"localhost","method":"POST","path":"/fskregistry/iti18","query":"","port":8060,"protocol":"http","reqSize":1569,"resSize":10307,"soapHeaders":{"w3Action":"urn:ihe:iti:2007:RegistryStoredQuery","w3MessageID":"urn:uuid:6b459c84-ddc1-43d2-84e4-e7e427fa9b7a","w3To":"http://localhost:8060/fskregistry/iti18"},"threadId":"default task-6","time":"2021-08-09T14:34:34.325+02:00","stats":{"handlerDuration":3,"RequestContentDuration":1,"ResponseContentDuration":0,"SecurityProtocolRequestDuration":0,"SecurityProtocolResponseDuration":0,"bufferAllocated":false,"usedBuffers":1,"activeBuffersInPool":1,"idleBuffersInPool":1}}}

HTTP Status- og versionscheck på FSK Registry Adapter

HTTP Statuscheck er i FSK Registry Adapter lagt sammen med HTTP Versionsnummerinformation. 

Ved HTTP Statuscheck oplyses også status på forbindelsen til databasen. 

Efter konfiguration og opstart af FSK Registry Adapter kan versionsnummer hentes med (Eksempel er ved opstart vha. docker-compose fra development):

curl localhost:8060/fskregistry/health

hvilket giver output i stil med:

{ version: "1.2.6-SNAPSHOT", Database: "OK", CprExistsServiceClient : "0 fejl"}

Kaldet til HealthServlet giver en statuskode 200 tilbage, hvis både databasen og forbindelsen til CprExistsService er sund.

Hvis forbindelsen til databasen er i stykker, så vil HealthServlet returnere kode 500.

Hvis kaldene (de sidste 50) til CprExists er fejlede, så vil HealthServlet returnere kode 204.

Overvågning

FSK Registry overvåges af Status og versionstjek URL

Versionsnummeret hentes fra Mavens pom.properties indlejret i jar-filen for fællesartefaktet ao-provider-common.

Test af versionsnummer

Efter konfiguration og deploy af Aftaleoversigt XDS-adaptere kan versionsnummeret for fx Aftaleoversigt XDS Registry Adapter hentes med:

curl localhost:9090/ao-documentmetadataprovider-<profil-navn>/version

hvilket giver output i stil med:

Version: 1.0.0

Tilsvarende hentes versionsnummeret for Aftaleoversigt XDS Repository Adapter blot ved at anvende det andet endpoint i tabellen.

Overvågning

Aftaleoversigt XDS-adaptere overvåges af service-check overvågningsside, hvis url kan aflæses i afsnit 2.

Placering af HTML overvågningsside

Under listen af komponenter først i dette dokument, er der henvisninger til overvågningssiderne.

Fortolkning af HTML overvågningsside

Alle overvågningssider returnerer enten status 200, hvis de i øjeblikket kører fint, status 404, hvis service ikke er deployed og status 500, hvis der er opstået en fejl, og komponenten derfor ikke virker korrekt.

Overvågningstype

Simpel WEB side der anvender JMX til at indhente oplysninger om Web services deployed på serveren. Som udgangspunkt overvåges følgende:

• Verificer service er registreret og aktiveret i WildFly

Det muligt at udvide overvågning med yderligere checks ved at tilføje nye objekter i service-check.xml, se eksempler i afsnit 4.3.2.

Logfiler og fortolkning af disse

Alle logfiler er at finde i log/ under WildFly. Herunder findes en liste over alle logfiler med en beskrivelse af hvilke komponenter der skriver til dem.

...

ao-<profil-navn>-documentmetadataprovider-ws.log

...

For alle webservices er der en tilhørende SLA-log, der sørger for at logge udvalgte elementer fra requests til webservicen.

For Aftaleoversigt XDS-adaptere logges indgående kald, samt udgående kald til Svareksponeringsservicen.
For indgående kald logges ved følgende logpunkter:

...

DocumentRepository_RetrieveDocumentSet

For udgående kald logges ved følgende logpunkter:

...

ao-documentprovider-<profil-navn>

...

DocumentRepository_RetrieveDocumentSet.AppointmentInvoker.invokeAppointment

...

search/appointments

Performance logs forekommer kun ved aktivering af performanceloggeren i komponenternes log4j konfiguration.

Standard fejlsøgning

Fejlsøgning kan ske ved at undersøge de logfiler, der er beskrevet i forudgående afsnit.

Krav til backup

Det anbefales, at aktuelle konfigurationsfiler til Aftaleoversigt XDS-adaptere FSK Registry holdes under versionskontrol og back-up.

Det er ikke nødvendigt at tage backup af databasen, da data heri ikke skal gemmes ("requestscope"Backup af databasen sorterer under FSK Repository (andet system)