1. Introduktion

1.1. Formål

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

Driftsvejledningen indeholder information om DDS Repository komponenten med hensyn til eksterne afhængigheder, standard placering af logfiler og konfigurationsfiler, og evt. krav til genstart af applikationer hvis komponenten ikke er responsiv.

I afsnit 2 er beskrevet hvilke komponenter, der indgår i DDS Repository og deres forventede placering med hensyn til platform.

Afsnit 4 beskriver aktuelle konfigurationsparametre for DDS Repository, samt eksempler på konfigurationsparameter-filer.

Afsnit 5.1, 5.2 og 5.3 beskriver hvorledes DDS Repository komponenterne overvåges.

I afsnit 5.4 er DDS Repository-relaterede logfiler beskrevet, så disse evt. kan overvåges, og tillige danne baggrund for fejlsøgning.

Beskrivelse af standard fejlsøgning og start/stop vejledning for komponenterne er beskrevet i afsnit 6.

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

1.2. Læsevejledning

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

1.3. Dokumenthistorik

Dette dokument er oprettet med udgangspunkt i OHB0011 Driftsvejledning DDS Repository.docx

1.4. Definitioner og referencer

2. Komponenter

Dette dokument dækker følgende komponenter på NSP:

• DDSRepository

• Type: Webservice

• Filnavn: ddsrepository.war

• Url: <serverurl>/ddsrepository

• Servicecheckurl: <serverurl>/ddsrepository/servicecheck

• Statusurl: <serverurl>/ddsrepository/status

• Versionurl: <serverurl>/ddsrepository/version

• DKS-konfiguration: <serverurl>/ddsrepository/dccconfig/dks

DDS Repository komponenten anvender desuden ConsentVerification-servicen, MinLog Registration-servicen, Behandlingsrelationsservicen, STS’en samt nul, et eller flere XDS repositories

3. Daglig drift

Dette afsnit beskriver den daglige drift af systemet.

3.1. Relaterede services

DDS Repository afhænger af tilstedeværelsen af en række andre services, og ved fejl i disse vil DDS Repository fejle tilsvarende. Disse services er:

• STS

• Samtykkeverifikationsservice

Desuden er DDS Repository afhængig af følgende services, hvor fejl ikke bevirker fejl af DDS Repository:

• Behandlingsrelationsservice

• MinLogRegistration-service

3.2. Consent override log

DDS Repository logger brug af værdispring til consent override loggen (ddsrepository-consentoverride.log). Denne skal kunne indsamles og der skal foretages opfølgning på indholdet af dette. Den skal derfor være tilgængelig for indsamling, og må ikke fjernes andet end i denne forbindelse.

4. Konfiguration

Komponenten afvikles i et docker-compose setup, som ligger under https://svn.nspop.dk/svn/components/dds/trunk/compose.

4.1. DDS Repository

4.1.1. Servicekonfiguration

Grundlæggende konfiguration foregår ved redigering i filen DDSRepository.properties.  Filen er placeret i compose/configuration/ddsrepository, og er volume-mappet.

I filen skal følgende properties være definerede:

I den/de properties-filer, der udpeges af de forskellige ”client.*.properties” properties skal flg. properties defineres:

Udover ovenstående skal følgende angives i den properties fil, der er udpeget i propertien ”client.treatment.relation.properties”. Disse forholder sig til værdier i SOAP requesten til behandlingsrelationsservicen og de følgende beskrivelser refererer til elementer i denne.

Eksempel på ”DDSRepository.properties” fil (bemærk at alle ”client.*.properties” udpeger filen selv, og at klient properties derfor er defineret i samme fil):

idcard.version = 1.0.1
sts.test.mode = true

repository.service.name = Dokumentdelingsservicen
log.config.file=ddsrepository.log4j.properties

client.documentrepository.properties = DDSRepository.properties 
client.consentverification.properties = DDSRepository.properties
client.minlog
.properties = DDSRepository.properties
client.treatment.relation.properties = DDSRepository.properties
treatment.relation.service.invoke=true

treatment.relation.service.invoke=true
treatment.relation.service.timeout=3000
treatment.relation.wsdl.location = http://localhost:9090/ddsservices-brs-stub/BRSFacadeService/BRSFacadeStub?wsdl

verification.wsdl.location=http://localhost:9090/consent-verification/service?wsdl
verification.invoker.timeout=30000

treatment.relation.serviceprovider.vendor=vendor
treatment.relation.serviceprovider.version=version
treatment.relation.lookup.timeinterval.start.offset=-1
treatment.relation.lookup.timeinterval.end.offset=1
treatment.relation.timelimit.offset=90
treatment.relation.queryable.cvr=19343634
treatment.relation.external.reference.id=
treatment.relation.acceptable.relations.hospital=A,B,C
treatment.relation.followup.relations.hospital=All
treatment.relation.acceptable.relations.doctor=C,D,E
treatment.relation.followup.relations.doctor=All
treatment.relation.acceptable.relations.organization=A,B,C
treatment.relation.followup.relations.organization=All

documentsourcesds.statement=SELECT * FROM documentsources.documentsource LIMIT 1;
sords.statement=SELECT * FROM stamdata.SORRelationer LIMIT 1;
authds.statement=SELECT * FROM stamdata.autreg LIMIT 1;
whitelistds.statement=SELECT * FROM whitelist.whitelist_config LIMIT 1;

servicestatuscheck.consentverification.failurethreshold = 1
servicestatuscheck.treatmentrelation.failurethreshold = 1
servicestatuscheck.minlog.failurethreshold = 1
servicestatuscheck.database.failurethreshold = 1

repository.retrieve.documents.processing.timeout = 200
retrieved.documents.processing.timeout = 200

idcard.subject.id.type = medcom:cvrnumber
idcard.subject.id = 46837428
idcard.subject.name = NETS DANID A/S - TU VOCES gyldig
idcard.level = 3
idcard.system.name = Dokumentdelingsservicen
sts.endpoint = http://test1-cnsp.ekstern-test.nspop.dk:8080/sts/services/SecurityTokenService
sts.keystore = Statens_Serum_Institut_VOCES.jks
sts.keystore.password = Test1234

minlog.producer.bootstrap.servers=kafka:9092
minlog.producer.client.id=DdsMinLog2-producer
minlog.producer.key.serializer=org.apache.kafka.common.serialization.StringSerializer
minlog.producer.value.serializer=org.apache.kafka.common.serialization.StringSerializer
minlog.topic=MINLOG_TOPIC

dds.minlog.on.idcard.level3.enabled=true 

personinformation.maxTotalConnections=200
personinformation.defaultMaxConnectionsPerRoute=20
personinformation.url=http://test1-cnsp.ekstern-test.nspop.dk:8080/stamdata-personinformation/v1

4.1.2. Log4j Konfiguration

Log4j konfiguration findes i (hvis ovenstående format anvendes) compose/configuration/ddsrepository/ddsrepository.log4j.properties filen.

Se yderligere opsætning i installationsvejledningen.

4.1.3. SLA-log konfiguration

SLA-logning på DDS Repository udføres vha SLALoggingInterceptor,

Konfiguration af SLA-log findes i filen compose/configuration/ddsrepository/nspslalog-ddsrepository.properties.

4.1.4. Whitelist konfiguration

Der foretages whitelisting på to niveauer. Først er der den whitelisting, der skal til for at anvende DDS Repository. Derudover findes en whitelisting, der afgør, hvorvidt en anvender må kalde DDS Repository med et niveua 3 Idkort. De to whitelisting-mekanismer beskrives i det følgende.

4.1.4.1. Whitelisting til anvendelse af DDS Repository

For at tilføje et CVR-nummer til white-list databasen, bruges følgende SQL insert:

INSERT INTO whitelist.whitelist_config ( service_key, service_type, cvr ) VALUES ( 'dk.nsi.ddsrepository', '', 'some-cvr-number-here' );

Da DDSRepository sender Id-kortet videre til samtykkeservice, behandlingsrelationsservice og minlog-registrationservice skal whitelisten også opdateres med følgende værdier:

INSERT INTO whitelist.whitelist_config ( service_key, service_type, cvr ) VALUES ( 'dk.nsi.auth.brs.cvr.list', '', 'some-cvr-number-here' ); 
INSERT INTO whitelist.whitelist_config ( service_key, service_type, cvr ) VALUES ( 'dk.nsi.consent.verification', '', 'some-cvr-number-here' );
INSERT INTO whitelist.whitelist_config ( service_key, service_type, cvr ) VALUES ( 'dk.nsi.minlog.registration', '', 'some-cvr-number-here' );

4.1.4.2. Whitelisting til kald med niveau 3 Idkort

Alle anvendere skal whitelistes som beskrevet ovenfor for at anvende DDS Repository. Derudover findes en ekstra whitelisting mekanisme, som gør det muligt for visse anvendere at kalde DDS Repository med et niveau 3 Idkort. Dette kræver en særlig whitelisting og kan sættes op ved at tilføje oplysninger om anvenderen i konfigurationsparameteren 'whitelisted.level3.cvrs'. På trods af navnet kan whitelisting til niveau 3 sættes op på to niveauer: CVR nummer eller et specifikt certifikat.

Værdien er en kommasepereret liste som vist i følgende eksempel:

whitelisted.level3.cvrs=31908574,CVR:46837428,CERT:CVR:33257872-FID:28250866

Eksemplet viser de tre formater, der kan anvendes:

• Værdi uden type: I eksempelt ovenfor fortolkes værdien '31908574' som et CVR nummer. Dette sikrer bagudkompatibilietet med tidligere opsætninger
• Værdier med typen CVR: I eksemplet ovenfor fortolkes 'CVR:46837428' som et CVR nummer med værdien 46837428
• Værdier med typen CERT: I eksemplet ovenfor fortolkes 'CERT:CVR:33257872-FID:28250866' som whitelisting af certificatet med Subject Serial Number CVR:33257872-FID:28250866.

I forhold til anvenderne, så tjekkes det, om der er en whitelisting af anvenderens CVR nummer og hvis dette ikke er tilfældet, så tjekkes, om det specifikke certifikat, der anvendes er whitelistet. Alle andre forsøg på adgang med niveau 3 Idkort afvises.

4.1.5. DocumentSources konfiguration

For at tilføje et kildesystem til documentsource databasen, bruges følgende SQL insert:

INSERT INTO `documentsource` (`oid`, `type`, `service_endpoint`, `soap_version`, `timeout`, `failurethreshold`) 
VALUES ('some_unique_id','[unique_id_type]','some_endpoint','[SOAP_version] ', '[timeout]', '[failure threshold]');

• oid: OID værdien som for den pågældende XDS dokument kilde, som kan være at typen ’repository_unique_id’ eller ’home_community_id’

• type: Angiver hvilken typen af OID der er angivet, og den skal have én af følgende værdier: [‘repository_unique_id’|’home_community_id’]

• service_endpoint: Angiver URL til XDS dokument kilde

• soap_version: Angiver XDS dokument kildens SOAP version og den skal have én af følgende værdier:

Værdien 1.2_DGWS_NO_ADDR benyttes, når WS-Addressing ikke ønskes anvendt.

• timeout: Angiver hvor lang tid DDS forsøger at hente dokumenter fra eksterne kilder inden forsøget opgives. Tiden angives i millisekunder.

• failurethreshold: Angiver grænseværdi for hvor mange kald mod repositoriet der må fejle før monitoreringssnitfladen melder fejl. Angives som heltal.

Kombinationen oid og unique_id_type skal være unik.

4.1.6. DKS Konfiguration

Indholdet, der returneres ved kald af DCC Konfiguration Service-snitfladen (DKS), indlæses af DDS Repository fra filen:

/pack/wildfly8/modules/nsi/ddsrepository/config/main/dksConfiguration.xml

Filen skal overholde DKS XML-skemaet og beskriver de webservice-operationer DDS Repository udstiller jf. [DKS-beskrivelse].

4.1.6.1. Test af DKS

Efter konfiguration og deployering af DDS Repository servicen, kan DKS-snitfladen testes med:

curl –i localhost:9090/ddsrepository/dccconfig/dks

Succesfuldt svar giver indholdet svarende til dksConfiguration.xml nævnt ovenfor.

4.1.7. Header konfiguration

Det er muligt at konfigurere repository'et til at lede efter HTTP- og SOAP-headere, og videresende dem til bagvedliggende registries. Videresendelse styres af databasetabellen documentsources.documentsource_forwarded_header. Indholdet af tabellen er som følger:

4.2. Monitorering af DDSRepository

Til statuscheck af DDSRepository findes en servicecheck servlet der kalder servicens afhængigheder, samt en statuscheck servlet der monitorerer de kald der foretages fra DDSRepository. Begge servlets udstiller http-snitflader som melder 500 ved fejl.

4.2.1. Test af versionsnummer

Efter konfiguration og deploy af DDS Repository kan versionsnummeret hentes med følgende kommando:

curl localhost:9090/ddsrepository/version

hvilket giver output i stil med:

Version: 2.0.0

I eksemplet kørte servicen på en lokal maskine konfigureret til port 9090.

4.2.2. Specielt vedrørende testConnection på JBoss

På grund af en kendt fejl i JBoss 6, logges en række exceptions i server loggen, hvis følgende filer ikke findes (de må gerne være tomme):

/pack/jboss/server/default/conf/props/roles.properties
/pack/jboss/server/default/conf/props/users.properties

4.2.3. Konfiguration af databasemonitorering

Databasemonitoreringen laver en simpel query mod databasen. Denne query er justbar og kan ændres i DDSRepository.properties

documentsourcesds.statement=SELECT * FROM documentsources. documentsource LIMIT 1;
sords.statement=SELECT * FROM stamdata.sorrelationer LIMIT 1;
authds.statement=SELECT * FROM stamdata.autreg LIMIT 1;
whitelistds.statement=SELECT * FROM whitelist.whitelist_config LIMIT 1;

4.2.4. Test af monitorering af afhængigheder

Til Monitorering af afhængigheder til egen propertyfil, og trådmanager og egen database findes en servlet i DDSRepository.

Efter konfiguration og deploy af DDSRepository, kan den testes med:

curl –i localhost:9090/ddsrepository/servicecheck

Servicen returnerer følgende http koder:

• Der returneres http kode 200 ved normal situation.

• http fejlkode 404 returneres hvis servicen ikke er deployeret

• Hvis en eller flere af afhængighederne mangler eller ved intern fejl i WildFly returneres kode 500. Fejlbeskeden vil kunne ses i ddsrepository-servicecheck.log. Såfremt der ikke er nogen fejlbeskeder i loggen bør property-filen undersøges som det første, da det er herigennem logindstillingerne bestemmes.

4.2.5. Test af monitorering af status

Til Monitorering af forbindelser til BRS, MinLog, SamtykkeVerifikationsservice, PersonInformation, repositories og egen database findes en servlet i DDSRepository. Denne service opsamler data på hvor mange kald til de forskellige andre services der er fejlet, og melder fejl hvis det overstiger de threshold-værdier der er defineret i property-filen.

Efter konfiguration og deploy af DDSRepository, kan den testes med:

curl –i localhost:9090/ddsrepository/status

Servicen returnerer følgende http koder:

• Der returneres http kode 200 ved normal situation.

• http fejlkode 404 returneres hvis servicen ikke er deployeret

• Hvis en eller flere af interne afhængighederne har fejlet nok gange til at nå deres grænseværdi returneres kode 203.

• Hvis en eller flere af ekserne afhængighederne (minlog osv)  har fejlet nok gange til at nå deres grænseværdi returneres kode 500.

• Bemærk at DDSRepository anvender ”service_endpoint” til identifikation af de forskellige repositories.

Fejlbeskeder vil kunne ses i ddsregistry-status.log.

Opsamlingen af kald til en service der fejler nulstilles automatisk efter et antal sekunder. Dette styrres med en properti, servicestatuscheck.unlockdelay.

4.2.6. Nulstilling af opsamling af kald

Opsamlingen af kald der benyttes til monitoring af status kan nustilles. Servicen resetstatuscounters nulstiller alle de opsamlede data omkring fejlkald der har været siden sidste nulstilling.

Der skrives i statusloggen når denne service har været brugt.

curl -i http://localhost:9090/ddsrepository/resetstatuscounters

Servicen returnerer følgende http koder:

• Der returneres http kode 200 ved normal situation.

5. Overvågning

DDS Repository overvåges af en servicespecifik servicechecksnitflade, samt en statussnitflade. Disse to snitfladers url’er kan aflæses i afsnit 2.

5.1. Placering af HTML overvågningsside

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

5.2. Fortolkning af HTML overvågningsside

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

5.3. Overvågningstype

Simpel webside deployeret på serveren. Som udgangspunkt overvåges følgende:

1. Tilstedeværelse og indhold af propertyfil

2. Forbindelse til datasources via JNDI opslag

3. Konfiguration af trådmanager

5.4. Logfiler og fortolkning af disse

Alle logfiler er at finde i log/ under JBoss. Herunder findes en liste over alle logfiler med en beskrivelse af hvilke komponenter der skriver til dem. Hvorvidt der anvendes disse default-logfilnavne eller skrives til andre, er afhængig af servicens konfiguration af log4j.

5.4.1. SLA log

For alle webservices er der en tilhørende SLA-log, der sørger for at logge udvalgte elementer fra requests til webservicen. For DDS Repository logges alle kald til DDSRepositoryWS hvor loggen vil indeholde information om kald til webservicens forskellige serviceoperationer og behandlingstid for kaldet inklusiv kald til kontrolservices.

SLA-logpunkter for indkommende kald til DDS Repository:

• DocumentRepository_RetrieveDocumentSet

SLA-logpunkter for udgående kald fra DDS Repository:

For SLA-logning af udgående kald til XDS Repository:

• logges i feltet GenericCallParms desuden det kaldte XDS Repository’s repositoryUniqueId under parameternavnet repositoryUniqueId.

• logges fejlet kald, på trods af succesfuldt kald, når en eller flere af følgende XDS-fejl/advarsler er indlejret i XDS-fejlstrukturen i svaret:

  • XDSMissingHomeCommunityId

  • XDSRepositoryBusy

  • XDSRepositoryError, medmindre der er tale om advarsel om tilbageholdte oplysninger grundet samtykker

  • XDSRepositoryOutOfResources

  • XDSUnavailableCommunity

  • XDSUnknownCommunity

  • XDSUnknownRepositoryId

5.4.2. Auditlog

Auditlogning foretages med det officielle NSP Audit Log modul.

De forskellige ITI-43 operationer logger patient-id, bruger-id, på-vegne-af-id og for hvert dokument i returneret svar (der kan være frafiltreret dokument(er) pga. samtykker, der kan være forespurgt dokumenter, der ikke er tilgængelige): requestens uniqueId, repositoryUniqueId, homeCommunityId.

Eksempel:

{
   "time": "2018-09-27T19:28:53.476Z",
   "category": "dk.sds.nsp.audit.log.dds",
   "audit": {
      "timestamp": "2018-09-27T21:28:52.996+02:00",
      "components": [
         {
            "component": "DDS",
            "contexts": [
               {
                  "context": "documentRepositoryRetrieveDocumentSet",
                  "information": [
                     {
                        "key": "patient-cpr",
                        "type": "RPI",
                        "value": "2110979420"
                     },
                     {
                        "key": "bruger-cpr",
                        "type": "RPI",
                        "value": "0101584160"
                     },
                     {
                        "key": "on-behalf-of-cpr",
                        "type": "RPI",
                        "value": "0101584160"
                     },
                     {
                        "key": "document_entry.0.homecommunityid",
                        "type": "SPI",
                        "value": "urn:oid:1.3.6.1.4.1.21367.2010.1.2.2045"
                     },
                     {
                        "key": "document_entry.0.repositoryid",
                        "type": "SPI",
                        "value": "1.3.6.1.4.1.21367.2010.1.2.1125"
                     },
                     {
                        "key": "document_entry.0.documentid",
                        "type": "SPI",
                        "value": "8352061236760766124.2930903161888816635.1538046332405"
                     },
                     {
                        "key": "document_entry.1.homecommunityid",
                        "type": "SPI",
                        "value": "urn:oid:1.3.6.1.4.1.21367.2010.1.2.2045"
                     },
                     {
                        "key": "document_entry.1.repositoryid",
                        "type": "SPI",
                        "value": "1.3.6.1.4.1.21367.2010.1.2.1125"
                     },
                     {
                        "key": "document_entry.1.documentid",
                        "type": "SPI",
                        "value": "4869530052539485342.5952203964580776052.1537974946937"
                     }
                  ]
               }
            ]
         }
      ]
   },
   "access": {
      "code": 200,
      "duration": 390,
      "httpHeaders": {
         "Content-Type": "multipart/related; type=\"application/xop+xml\"; boundary=\"uuid:ff2230e6-7a7b-42b5-b8d7-448396803b2b\"; start=\"<root.message@cxf.apache.org>\"; start-info=\"application/soap+xml\""
      },
      "httpHost": "localhost",
      "idCardAttributes": {
         "medcom:CareProviderID": "30808460",
         "medcom:CareProviderName": "NETS DANID A/S",
         "medcom:ITSystemName": "TRUST2408 Systemtest XIX CA",
         "sosi:AuthenticationLevel": "3",
         "sosi:IDCardID": "PJBE7nBkFgG1DN6pvsHUhQ==",
         "sosi:IDCardType": "system",
         "sosi:IDCardVersion": "1.0.1"
      },
      "method": "POST",
      "path": "/ddsrepository/service",
      "query": "",
      "port": 9091,
      "protocol": "http",
      "reqSize": 8962,
      "resSize": 43188,
      "soapHeaders": {
         "Issuer": "TEST1-NSP-STS",
         "MessageID": "AAABZhyBSdBSTccik8TayVNPU0k=",
         "NameID": "SubjectDN={SERIALNUMBER=CVR:30808460-UID:25351738 + CN=NETS DANID A/S - TU VOCES gyldig, O=NETS DANID A/S // CVR:30808460, C=DK},IssuerDN={CN=TRUST2408 Systemtest XIX CA, O=TRUST2408, C=DK},CertSerial={1478025777}",
         "w3Action": "urn:ihe:iti:2007:RetrieveDocumentSet",
         "w3MessageID": "urn:uuid:cde2752b-23a0-4410-b1b7-fd3db1156b5b",
         "w3To": "http://localhost:9091/ddsrepository/service"
      },
      "threadId": "default task-2",
      "time": "2018-09-27T21:28:52.996+02:00",
      "stats": {
         "handlerDuration": 84,
         "bufferAllocated": false,
         "usedBuffers": 2,
         "activeBuffersInPool": 2,
         "idleBuffersInPool": 0
      }
   }
}

6. Standard fejlsøgning

• Ved problemer med indlæsning af servicens konfigurationsfil (DDSRepository.properties) bør man verificere at filen ligger korrekt i conf/ biblioteket. Vær opmærksom på at filen ikke læses hvis den ikke er til stede ved opstart af WildFly serveren.

• Ved manglende logning bør konfigurationsfilen (DDSRepository.properties) checkes, da logindstillingerne sættes herigennem.

• En service eller et job kan stoppes og startes gennem docker.

7. Krav til backup m.m.

Det anbefales at aktuelle konfigurationsfiler til DDS Repository er under versionskontrol og back up.