Introduktion

Formål

Dette dokument er rettet mod systemadministratorer og driftspersoner, som skal kunne håndtere driftsmæssige aspekter af komponenterne fra Svareksponeringsservice XDS-adaptere.
Driftsvejledningen indeholder information om komponenterne 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 Svareksponeringsservice XDS-adaptere og deres forventede placering med hensyn til platform.
Afsnit 4 beskriver aktuelle konfigurationsparametre for komponenterne i Svareksponeringsservice XDS-adaptere, samt eksempler på konfigurationsparameter-filer.
I afsnit 5 beskrives hvorledes Svareksponeringsservice XDS-adapter-komponenterne overvåges.
Beskrivelse af standard fejlsøgning og vejledning for start/stop af komponenterne er beskrevet i afsnit 6.
Specielle krav til backup er beskrevet i afsnit 7, ligesom procedure ved reetablering af komponenterne 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

Definitioner og referencer

Komponenter

Svareksponeringsservice XDS-adaptere er implementeret gennem følgende komponenter:

• Svareksponeringsservice XDS Registry Adapter
  • Type: Webservice
  • Filnavn: sxa-documentmetadataprovider.war
  • Url: <serverurl>/sxa-documentmetadataprovider
  • Status url: <serverurl>/status
  • Alarm url: <serverurl>/alarm
  • Servicecheck url<serverurl>/servicecheck
• Svareksponeringsservice XDS Repository Adapter
  • Type: Webservice
  • Filnavn: sxa-documentprovider.war
  • Url: <serverurl>/sxa-documentprovider
  • Status url: <serverurl>/status
  • Alarm url: <serverurl>/alarm
  • Servicecheck url<serverurl>/servicecheck

Daglig drift

Dette afsnit beskriver den daglige drift af systemet.

Relaterede services

Svareksponeringsservice XDS Repository Adapter afhænger af den eksterne service:

• Svareksponeringsservice hos Laboratoriedatabanken

Ved fejl i denne vil Svareksponeringsservice XDS Repository Adapter returnere svar til anvendere, hvoraf det fremgår, at der er fejl.

Konfiguration

Konfiguration af Svareksponeringsservice XDS Registry Adapter

Konfiguration af Svareksponeringsservice kalder

Opsætningen for kalderen af Svareksponeringsservice konfigureres i SXAConfig.properties.
Denne indlæses fra WildFly modulet:

/pack/wildfly8/modules/nsi/ddsprojects/sxa/documentprovider/config/main/

Et eksempel på sådan konfiguration er:

sxa.labservice.credential.header=X-Labsvar-Credential
sxa.labservice.credential=00000000-0000-0000-0000-000000000000

Properties beskrives ifølge tabel.

Konfiguration af dokument-metadata

Dokument-metadata anvendt af Svareksponeringsservice XDS Registry Adapter, når der laves opslag på en patient, er defineret i følgende fil:

• sxametadataconfiguration.xml

Denne indlæses fra WildFly modulet:

/pack/wildfly8/modules/nsi/ddsprojects/sxa/documentmetadataprovider/config/main/

Et eksempel på indhold i sxametadataconfiguration.xml:

<metadata>
  <classCode class="codedValue">
    <code>001</code>
    <codeSystem>2.16.840.1.113883.3.4208.100.9</codeSystem>
    <description>Klinisk rapport</description>
  </classCode>
  <confidentialityCode class="codedValue">
    <code>N</code>
    <codeSystem>2.16.840.1.113883.5.25</codeSystem>
    <description>Normal</description>
  </confidentialityCode>
  <formatCode class="codedValue">
    <code>urn:ad:dk:medcom:labreports:svareksponeringsservice</code>
    <codeSystem>1.2.208.184.100.10</codeSystem>
    <description>Laboratoriesvar (samling af svar)</description>
  </formatCode>
  <languageCode>da-DK</languageCode>
  <mimeType>text/xml</mimeType>
  <practiceSettingCode class="codedValue">
    <code></code>
    <codeSystem></codeSystem>
    <description></description>
  </practiceSettingCode>
  <typeCode class="codedValue">
    <code>11502-2</code>
    <codeSystem>2.16.840.1.113883.6.1</codeSystem>
    <description>LABORATORY REPORT.TOTAL</description>
  </typeCode>
  <homeCommunityId>1.2.3.5.6</homeCommunityId>
  <repositoryUniqueId>1.2.3.4.55.66</repositoryUniqueId>
  <uniqueIdRoot>1.2.3.4.55.66</uniqueIdRoot>
  <healthcareFacilityTypeCode class="codedValue">
    <code></code>
    <codeSystem>2.16.840.1.113883.6.96</codeSystem>
    <description></description>
  </healthcareFacilityTypeCode>
  <authorInstitution
    class="dk.nsi.documentsharing.core.metadata.model.OrganisationImpl">
    <name>Region Test</name>
    <id class="valueWithAssigningAuthority">
      <value>291000016008</value>
      <assigningAuthority>1.2.208.176.1.1</assigningAuthority>
    </id>
  </authorInstitution>
</metadata>

Konfiguration af filter på dokument-metadata-forespørgsel

Ved opslag på en patient kan der anføres en række søge-parametre. Svareksponeringsservice XDS Registry Adapter har logik, der er afhængig af konkrete søge-parametre og konfigureret filter (beskrevet her), fastlægger hvilket svar, der skal returneres.
Filteret konfigureres i følgende fil:

• sxafilterconfiguration.xml

Denne indlæses fra WildFly modulet:

/pack/wildfly8/modules/nsi/ddsprojects/sxa/documentmetadataprovider/config/main/

I konfiguration specificeres 0, 1 eller flere kode-sæt i hhv. classCodes, typeCodes, eventCodes, confidentialityCodes, formatCodes og practiceSettingCodes?

<filter>
  <classCodes>
  </classCodes>
  <typeCodes>
  </typeCodes>
  <eventCodes>
  </eventCodes>
  <confidentialityCodes>
  </confidentialityCodes>
  <formatCodes>
  </formatCodes>
  <practiceSettingCodes>
  </practiceSettingCodes>
</filter>

Hver kode-sæt, består af:

    <codedValue>
      <code>kode-værdi</code>
      <codeSystem>kode-system</codeSystem>
      <description>menneskelæselig beskrivelse af kode-værdi</description>
    </codedValue>

Filterets classCodes, typeCodes, eventCodes, confidentialityCodes, formatCodes og practiceSettingCodes modsvarer lignende navne i søge-parametre, der kan være anført ved kald af Svareksponeringsservice XDS Registry Adapter opslag. Er et kodesæt anført i søge-parametre for fx eventCodes, da bevirker filteret et tomt svar, når:

1. Filterets eventCodes ikke er tomt, og
2. Ingen af evt. flere eventCodes fra søge-parametre findes i filterets eventCodes-liste

Tilsvarende logik er gældende de øvrige koder i filteret.
Følgende er et eksempel på konfiguration af filteret:

<filter>
  <classCodes/>
  <typeCodes>
    <codedValue>
      <code>11502-2</code>
      <codeSystem>2.16.840.1.113883.6.1</codeSystem>
      <description>LABORATORY REPORT.TOTAL</description>
    </codedValue>
  </typeCodes>
  <eventCodes/>
  <confidentialityCodes>
    <codedValue>
      <code>N</code>
      <codeSystem>2.16.840.1.113883.5.25</codeSystem>
      <description>Normal</description>
    </codedValue>
  </confidentialityCodes>
  <formatCodes>
    <codedValue>
      <code>urn:ad:dk:medcom:labreports:svareksponeringsservice</code>
      <codeSystem>1.2.208.184.100.10</codeSystem>
      <description>Laboratoriesvar (samling af svar)</description>
    </codedValue>
  </formatCodes>
  <practiceSettingCodes>
     <codedValue>
      <code>408454008</code>
      <codeSystem>2.16.840.1.113883.6.96</codeSystem>
      <description>klinisk mikrobiologi</description>
    </codedValue>
    <codedValue>
      <code>394596001</code>
      <codeSystem>2.16.840.1.113883.6.96</codeSystem>
      <description>klinisk biokemi</description>
    </codedValue>
    <codedValue>
      <code>394915009</code>
      <codeSystem>2.16.840.1.113883.6.96</codeSystem>
      <description>patologi anatomi og cytologi</description>
    </codedValue>	  
  </practiceSettingCodes>
</filter>

Konfiguration af mapning til specialer

Ved opslag på en patient kan der anføres en række søge-parametre. Svareksponeringsservice XDS Registry Adapter har logik, der er afhængig af konkrete søge-parametre foretager encoding i dokumentid, der er del af returnerede metadata.
Mapning til specialer konfigureres i følgende fil:

• sxapracticesettingcodes.xml

Denne indlæses fra WildFly modulet:

/pack/wildfly8/modules/nsi/ddsprojects/sxa/documentmetadataprovider/config/main/

I konfiguration specificeres specialer således:

<filter>
  <practiceSettingCodes>
    <mappedCodedValue>
      <code>408454008</code>
      <codeSystem>2.16.840.1.113883.6.96</codeSystem>
      <description>klinisk mikrobiologi</description>
      <mappedValue>Mikrobiologi</mappedValue>
    </mappedCodedValue>
    <mappedCodedValue>
      <code>394596001</code>
      <codeSystem>2.16.840.1.113883.6.96</codeSystem>
      <description>klinisk biokemi</description>
      <mappedValue>KliniskBiokemi</mappedValue>
    </mappedCodedValue>
    <mappedCodedValue>
      <code>394915009</code>
      <codeSystem>2.16.840.1.113883.6.96</codeSystem>
      <description>patologisk anatomi og cytologi</description>
      <mappedValue>Patologi</mappedValue>
    </mappedCodedValue>
  </practiceSettingCodes>
</filter>

Det er vigtigt, at den tilsvarende fil for documentprovider er konfigureret fuldstændigt identisk.

Udpegning af log4j-konfigurationfil

Følgende fil, der findes under roden i war-filen sxa-documentmetadataprovider.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-sxa-documentmetadataprovider-ws.xml

Denne indlæses fra WildFly modulet:

/pack/wildfly8/modules/nsi/ddsprojects/sxa/documentmetadataprovider/config/main/

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-sxa-documentmetadataprovider-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 sxa-documentmetadataprovider-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-sxa-documentmetadataprovider.properties

Denne indlæses fra WildFly modulet:

/pack/wildfly8/modules/nsi/ddsprojects/sxa/documentmetadataprovider/config/main/ 

Per default udpeges konfigurationsfilen beskrevet i næste afsnit.

Konfiguration af SLA-log

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

• log4j-nspslalog-sxa-documentmetadataprovider.properties

Denne indlæses fra WildFly modulet:

/pack/wildfly8/modules/nsi/ddsprojects/sxa/documentmetadataprovider/config/main/

Konfiguration af Svareksponeringsservice XDS Repository Adapter

Konfiguration af Svareksponeringsservice kalder

Opsætningen for kalderen af Svareksponeringsservice konfigureres i SXAConfig.properties.
Denne indlæses fra WildFly modulet:

/pack/wildfly8/modules/nsi/ddsprojects/sxa/documentprovider/config/main/

Et eksempel på sådan konfiguration er:

sxa.labservice.request.timeout.seconds = 120
sxa.labservice.request.username = username
sxa.labservice.request.password = password
sxa.labservice.endpoint = 
http://localhost:9090/sxa-labreportservicestub/SvarEksponering
sxa.document.unique.root.id = 1.2.3.4.55.66
sxa.labservice.request.samtykkekode = _ 
sxa.labservice.request.samtykketekst = _ 
sxa.labservice.request.slutbruger.identifikation = _ 
sxa.labservice.request.slutbruger.organisation = _ 
sxa.labservice.request.slutbruger.cpr = _ 
sxa.labservice.request.slutbruger.fornavn = _ 
sxa.labservice.request.slutbruger.efternavn = _ 
sxa.labservice.request.slutbruger.stilling = _ 
sxa.labservice.request.slutbruger.email = _ 
sxa.labservice.request.slutbruger.rolle = _ 
sxa.labservice.request.slutbruger.autorisationskode = _

sxa.labservice.servicecheck.failurethreshold = 5
sxa.labservice.servicecheck.duration = PT10M

sxa.labservice.headers = _

sxa.labservice.logrecord.inbound.header.name = _
sxa.labservice.logrecord.outbound.header.name = _

sxa.labservice.credential.header=X-Labsvar-Credential
sxa.labservice.credential=00000000-0000-0000-0000-000000000000

Properties beskrives ifølge tabel.

Konfiguration af dokumentdelings-id

Konfiguration af hvilket homeCommunityId og repositoryUniqueId, Svareksponeringsservice XDS Repository Adapter'en skal reagere på ved request for indhentning af dokument, er konfigureret i følgende fil:

• sxaproviderconfiguration.xml

Denne indlæses fra WildFly modulet:

/pack/wildfly8/modules/nsi/ddsprojects/sxa/documentprovider/config/main/

Et eksempel på sådan konfiguration er:

<ProviderConfiguration>
  <homeCommunityId>1.2.3.5.6</homeCommunityId>
  <repositoryUniqueId>1.2.3.4.55.66</repositoryUniqueId>
  <uniqueIdRoot>1.2.3.4.55.66</uniqueIdRoot>
</ProviderConfiguration>

Bemærk, at de konkrete værdier skal være afstemt med homeCommunityId og repositoryUniqueId i de dokumentmetadata, der er konfigureret som beskrevet i afsnit 4.1.1. Er der ikke overensstemmelse, vil kald til Svareksponeringsservice XDS Repository give anledning til svar, der påpeger uoverenstemmelsen.

Konfiguration af mapning til specialer

Ved opslag på en patient kan der anføres en række søge-parametre. Svareksponeringsservice XDS Registry Adapter har logik, der er afhængig af konkrete søge-parametre foretager encoding i dokumentid, der er del af returnerede metadata. Ved indhentning af dokument foretages decoding og mapning til speciale-parametre anvendt i kaldet til Svareksponeringsservicen.
Mapning til specialer konfigureres i følgende fil:

• sxapracticesettingcodes.xml

Denne indlæses fra WildFly modulet:

/pack/wildfly8/modules/nsi/ddsprojects/sxa/documentprovider/config/main/

I konfiguration specificeres specialer således:

<filter>
  <practiceSettingCodes>
    <mappedCodedValue>
      <code>408454008</code>
      <codeSystem>2.16.840.1.113883.6.96</codeSystem>
      <description>klinisk mikrobiologi</description>
      <mappedValue>Mikrobiologi</mappedValue>
    </mappedCodedValue>
    <mappedCodedValue>
      <code>394596001</code>
      <codeSystem>2.16.840.1.113883.6.96</codeSystem>
      <description>klinisk biokemi</description>
      <mappedValue>KliniskBiokemi</mappedValue>
    </mappedCodedValue>
    <mappedCodedValue>
      <code>394915009</code>
      <codeSystem>2.16.840.1.113883.6.96</codeSystem>
      <description>patologisk anatomi og cytologi</description>
      <mappedValue>Patologi</mappedValue>
    </mappedCodedValue>
  </practiceSettingCodes>
</filter>

Det er vigtigt, at den tilsvarende fil for documentmetadataprovider er konfigureret fuldstændigt identisk.

Udpegning af log4j-konfigurationfil

Følgende fil, der findes under roden i war-filen sxa-documentprovider.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-sxa-documentprovider-ws.xml

Denne indlæses fra WildFly modulet:

/pack/wildfly8/modules/nsi/ddsprojects/sxa/documentprovider/config/main/

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-sxa-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 sxa-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-sxa-documentprovider.properties

Denne indlæses fra WildFly modulet:

/pack/wildfly8/modules/nsi/ddsprojects/sxa/documentprovider/config/main/ 

Per default udpeges konfigurationsfilen beskrevet i næste afsnit.

Konfiguration af SLA-log

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

• log4j-nspslalog-sxa-documentprovider.properties

Denne indlæses fra WildFly modulet:

/pack/wildfly8/modules/nsi/ddsprojects/sxa/documentprovider/config/main/

SES Auditlogning

Ved kald til Svareksponeringsservicen medsendes der en header, som indeholder information til auditlogning. Headeren indeholder en LogRecord xml-struktur, hvis indhold beskrives nærmere i dette afsnit.

Indholdet af headeren er nærmere beskrevet i og det tilhørende analysedokument. Ved requests til XDS Repository Adapteren bliver der konstrueret en LogRecord-header SXA konstruerer LogRecord-strukturen ud fra følgende informationer i requestet:

• Hsuid-header. Påkrævet
• Medcom-header. Påkrævet
• LogRecord-header. Frivillig.
• Request body. Påkrævet.

Eksempel på header:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<LogRecord xmlns="healthcare.loginfo/2017-03-01">
  <TraceInfo>
    <RequestTime>2020-10-23T14:15:54.138+02:00</RequestTime>
    <SessionId>00000000-0000-0000-0000-000000000000</SessionId>
    <RequestId>11111111-1111-1111-1111-111111111111</RequestId>
    <Route>
      <ViaSystem id="1">Dokumentdelingsservice</ViaSystem>
    </Route>
  </TraceInfo>
  <RequestingClient>
    <ClientIdentification ClientIdentificationType="CPR nummer">098765-4321</ClientIdentification>
    <ClinicName/>
    <ClinicDepartment/>
    <UserCprNumber>098765-4321</UserCprNumber>
    <UserName/>
    <UserInitials/>
    <LookUpType>Borger</LookUpType>
    <TaskType>Opslag Dokumentdelingsservice</TaskType>
  </RequestingClient>
  <Patient>
    <CprNumber>121212-1212</CprNumber>
    <Name/>
  </Patient>
  <Consent>
    <Code>1</Code>
    <Text/>
    <PrivacyOverrideCode>0</PrivacyOverrideCode>
  </Consent>
  <ExtendedRequestInfo Format="Text">{HomeCommunityId: 1.2.3.5.6, RepositoryUniqueId: 1.2.3.4.55.66, DocumentUniqueId: 1.2.3.4.55.66.12172240491026.20201023121554.20201023121654.0}</ExtendedRequestInfo>
</LogRecord>

I nedenstående tabel beskrives mere præcist, hvordan headeren udfyldes.

LogRecord generated. MessageID: <messageID>, RequestId: <requestId>

LogRecord generated. MessageID: AAABeBX9pFBxz1Ul3Nwf/lNPU0k=, RequestId: 863faf0f-dc2a-4c48-b4ec-897ec90a9890

Overvågning

Placering af overvågnings endpoint

Under listen af komponenter først i dette dokument, er der henvisninger til overvågningendpointene - status og alarm.

Overvågnings endpoint

Servicene udstiller et status- og alarmendpoint.

Generelt vedr status endpointet:

• Returnerer status HTTP 200, hvis komponenten kan modtage forespørgsler, og 500 hvis den ikke er i stand til det.
• Returnerer servicens version i json format
• Versionsnummeret hentes fra Mavens pom.properties indlejret i jar-filen for fællesartefaktet sxa-provider-common

Generelt vedr Status omkring alarm endpoint:

• Returnerer HTTP 500, hvis der er aktive alarmer og ellers HTTP 200.
• Returnerer tekst i text/plain format. 
• Der returneres kun tekst, hvis der en alarm.

Svareksponeringsservice XDS Registry Adapter:

• status: returnerer altid HTTP 200, samt servicens version 
• alarm: returnerer 500 hvis antal fejlkald til den bagvedliggende service fejler mere end konfigureret antal
  (sættes op vha. properties sxa.labservice.servicecheck.failurethreshold og sxa.labservice.servicecheck.duration)

Svareksponeringsservice XDS Repository Adapter:

• status: returnerer altid HTTP 200, samt servicens version 
• alarm: returnerer altid HTTP 200

Eksempel på status kald.

200 ok

{ "Version":"2.7.4" }

Eksempel på alarm kald for XDS registry adaptor, når servicens bagvedliggende service har fejlet for mange gange

500 Internal Server Error

Servicen har fejlet 6 gange. Den må ikke fejle mere end 5 gange i en given periode.

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.

For alle webservices er der en tilhørende SLA-log, der sørger for at logge udvalgte elementer fra requests til webservicen.
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 m.m.

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