Indholdsfortegnelse


Snitflader

Applikationen opstiller forskellige snitflader, som er beskrevet nedenfor.

DKS

Snitfladen for at udstille DKS konfigurationen kan findes under:

https://localhost/sor-opslag/dks

DKS snitfladen har support for brugen af HTTP header If-Modified-Since.

Status

Applikationen udstiller to forskellige status snitflader; en human readable i XML format, og en simpel som kan bruges til hyppige check af applikationens health.

Snitfladen for at få XML output findes her:

https://localhost/sor-opslag/status

Snitfladen returnerer et simpelt XML format, som indeholder følgende information:

TagBeskrivelse
VersionApplikationens version, tages fra pom.xml filen under build
SealVersionVersionen af SEAL modulet, tages fra pom.xml filen under build
CurrentDateDato for hvornår at status snitfladen blev kaldt
StartedDateDato for hvornår at applikationen blev startet
LatestRequestDateDato for hvornår sidste forespørgelse blev sendt til applikationen
LatestSuccessDateDato for hvornår sidste succefulde forespørgelse blev sendt til applikationen
RequestsTotalDet totale antal forespørgelser til applikationen siden den blev startet
Requests24hAntallet af forespørgelser til applikationen i løbet af de sidste 24 timer
RequestErrorsTotalDet totale antal forespørgelser til applikationen der fejlede siden den blev startet
RequestErrors24hAntallet af forespørgelser til applikationen der fejlede i løbet af de sidste 24 timer
RequestDurationAverageTotalDen gennemsnitlige svartid for en forespørgelse til applikationen målt siden den blev startet
RequestDurationAverage24hDen gennemsnitlige svartid for en forespørgelse til applikationen målt over de sidste 24 timer
RequestDurationMaxTotalSummen af svartiden for alle forespørgelser til applikationen målt siden den blev startet
RequestDurationMax24hSummen af svartiden for alle forespørgelser til applikationen målt over de sidste 24 timer
UpDownScoreDen interne score applikationen bruger til at bedømme, om applikationen kan betragtes som værende oppe eller ej (styres af applikationens konfigurationsfil)
ServiceUpOm servicen betragter sig selv som oppe eller ej


Web Service Definition Language (WSDL) 

Opslag service WSDL kan hentes med følgende url:

https://localhost/sor-opslag/SORLookupService?wsdl

Her er det vigtigt at det er HTTP GET metoden bliver brugt, og den forventeded WSDL ser som følgende ud:


<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions name="SORLS" targetNamespace="http://sundhedsdatastyrelsen.dk/SORLookupService/2018/09/06/"
                  xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
                  xmlns:tns="http://sundhedsdatastyrelsen.dk/SORLookupService/2018/09/06/"
                  xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
                  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                  xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
                  xmlns:medcom="http://www.medcom.dk/dgws/2006/04/dgws-1.0.xsd">

    <wsdl:types>
        <!-- Headers -->
        <xsd:schema targetNamespace="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
            <xsd:include schemaLocation="schema/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"/>
        </xsd:schema>
        <xsd:schema targetNamespace="http://www.medcom.dk/dgws/2006/04/dgws-1.0.xsd">
            <xsd:include schemaLocation="schema/2006_01/medcom.xsd"/>
        </xsd:schema>

        <xsd:schema targetNamespace="http://sundhedsdatastyrelsen.dk/SORLookupService/2018/09/06/">
            <xsd:include schemaLocation="schema/2018/09/06/sorls.xsd"/>
        </xsd:schema>
    </wsdl:types>

    <!-- Headers -->
    <wsdl:message name="SecurityHeader">
        <wsdl:part name="SecurityHeader" element="wsse:Security"/>
    </wsdl:message>
    <wsdl:message name="MedComHeader">
        <wsdl:part name="MedcomHeader" element="medcom:Header"/>
    </wsdl:message>

    <!-- GetSorEntity Requests/Responses -->
    <wsdl:message name="GetSorEntityRequest_2018_09_06">
        <wsdl:part element="tns:GetSorEntityRequest" name="GetSorEntityRequest"/>
    </wsdl:message>
    <wsdl:message name="GetSorEntityResponse_2018_09_06">
        <wsdl:part element="tns:GetSorEntityResponse" name="GetSorEntityResponse"/>
    </wsdl:message>

    <!-- ShakSorMap Requests/Responses -->
    <wsdl:message name="ShakSorMapRequest_2018_09_06">
        <wsdl:part element="tns:ShakSorMapRequest" name="ShakSorMapRequest"/>
    </wsdl:message>
    <wsdl:message name="ShakSorMapResponse_2018_09_06">
        <wsdl:part element="tns:ShakSorMapResponse" name="ShakSorMapResponse"/>
    </wsdl:message>

    <!-- SorShakMap Requests/Responses -->
    <wsdl:message name="SorShakMapRequest_2018_09_06">
        <wsdl:part element="tns:SorShakMapRequest" name="SorShakMapRequest"/>
    </wsdl:message>
    <wsdl:message name="SorShakMapResponse_2018_09_06">
        <wsdl:part element="tns:SorShakMapResponse" name="SorShakMapResponse"/>
    </wsdl:message>

    <!-- Port Types -->
    <wsdl:portType name="SORLookupServicePortType">
        <wsdl:operation name="GetSorEntity_2018_09_06">
            <wsdl:input message="tns:GetSorEntityRequest_2018_09_06" name="GetSorEntityRequest_2018_09_06"/>
            <wsdl:output message="tns:GetSorEntityResponse_2018_09_06" name="GetSorEntityResponse_2018_09_06"/>
        </wsdl:operation>

        <wsdl:operation name="ShakSorMap_2018_09_06">
            <wsdl:input message="tns:ShakSorMapRequest_2018_09_06" name="ShakSorMapRequest_2018_09_06"/>
            <wsdl:output message="tns:ShakSorMapResponse_2018_09_06" name="ShakSorMapResponse_2018_09_06"/>
        </wsdl:operation>

        <wsdl:operation name="SorShakMap_2018_09_06">
            <wsdl:input message="tns:SorShakMapRequest_2018_09_06" name="SorShakMapRequest_2018_09_06"/>
            <wsdl:output message="tns:SorShakMapResponse_2018_09_06" name="SorShakMapResponse_2018_09_06"/>
        </wsdl:operation>
    </wsdl:portType>

    <!-- Bindings -->
    <wsdl:binding name="SORLookupServiceBinding" type="tns:SORLookupServicePortType">
        <soap:binding transport="http://schemas.xmlsoap.org/soap/http"/>

        <wsdl:operation name="GetSorEntity_2018_09_06">
            <soap:operation soapAction="http://sundhedsdatastyrelsen.dk/SORLookupService/2018/09/06#GetSorEntity" style="document"/>

            <wsdl:input name="GetSorEntityRequest_2018_09_06">
                <soap:header message="tns:SecurityHeader" part="SecurityHeader" use="literal"/>
                <soap:header message="tns:MedComHeader" part="MedcomHeader" use="literal"/>
                <soap:body use="literal"/>
            </wsdl:input>

            <wsdl:output name="GetSorEntityResponse_2018_09_06">
                <soap:body use="literal"/>
            </wsdl:output>
        </wsdl:operation>

        <wsdl:operation name="ShakSorMap_2018_09_06">
            <soap:operation soapAction="http://sundhedsdatastyrelsen.dk/SORLookupService/2018/09/06#ShakSorMap" style="document"/>

            <wsdl:input name="ShakSorMapRequest_2018_09_06">
                <soap:header message="tns:SecurityHeader" part="SecurityHeader" use="literal"/>
                <soap:header message="tns:MedComHeader" part="MedcomHeader" use="literal"/>
                <soap:body use="literal"/>
            </wsdl:input>

            <wsdl:output name="ShakSorMapResponse_2018_09_06">
                <soap:body use="literal"/>
            </wsdl:output>
        </wsdl:operation>

        <wsdl:operation name="SorShakMap_2018_09_06">
            <soap:operation soapAction="http://sundhedsdatastyrelsen.dk/SORLookupService/2018/09/06#SorShakMap" style="document"/>

            <wsdl:input name="SorShakMapRequest_2018_09_06">
                <soap:header message="tns:SecurityHeader" part="SecurityHeader" use="literal"/>
                <soap:header message="tns:MedComHeader" part="MedcomHeader" use="literal"/>
                <soap:body use="literal"/>
            </wsdl:input>

            <wsdl:output name="SorShakMapResponse_2018_09_06">
                <soap:body use="literal"/>
            </wsdl:output>
        </wsdl:operation>
    </wsdl:binding>

    <!-- Services -->
    <wsdl:service name="SORLookupServiceService">
        <wsdl:port name="SORLookupServicePort" binding="tns:SORLookupServiceBinding">
            <soap:address location="http://localhost:8080/sor-opslag/SORLookupService" />
        </wsdl:port>
    </wsdl:service>
</wsdl:definitions>


Modus operandi

Applikationen prøver så vidt muligt altid at give et fornuftigt svar. Kun i de tilfælde, hvor at applikationen ikke kan skrive et pænt svar til klienten, vil den give op og bare kaste en exception. Ved et kald til en snitflade der ikke eksisterer, vil den svare med HTTP kode 404.

Applikationens hovedfunktionalitet ligger under HTTP POST på adressen:

http://localhost/SORLookupService

Dette er SOAP snitfladen, og kan håndtere en af følgende SOAP operationer:

Operationen bliver valgt med HTTP header SOAPAction. Hvis en anden operation end de listede er valgt, vil servicen returnere HTTP kode 405 (Method not allowed).

Alle operationer vil returnere et Status objekt som en del af svaret. Dette object indeholder altid to felter, ErrorCode og Message. Hvis ErrorCode er 0, så var kaldet en succes, ellers skete der en fejl i løbet af kaldet. Positive værdier er validerings fejl, imens at negative er operationelle fejl. De nedenstående er hvilke denne applikation definerer:

KodeBeskrivelse
-1Autentifikations fejl, invalid signatur
-2Autentifikations fejl, kan ikke læse forespørgelsen
-3Autorisations fejl, kun certifikat niveau 3 eller 4 er tilladt
-4Autorisations fejl, uden for gyldighedsperioden for sikkerheds headeren
-5Autorisations fejl, ugyldig type af certifikat brugt, kun FOCES og MOCES er tilladt
-6Autorisations fejl, CVR er ikke whitelisted
-7Fejl under forespørgelse mod SDM databasen
-8Whitelisting fejl under forespørgelse mod SOR databasen
-9Fejl under parsering af SOAP forespørgsel indhold
-10Fejl under marshalling af en object
-11Fejl når SOAP besked bliver skrevet ud
-12Fejl når responsen bliver overført til SOAP besked
-13SOAP besked er ugyldig


Ved fejlkode -2 kunne SEAL komponenten ikke arbejde med body af forespørgelsen. Enten har klienten sendt noget der ikke kunne transformeres af komponenten (mest sandsynligt), eller også ligger der en fejl i komponenten, og bør rapporteres til de ansvarlige.

Ved fejlkode -6 kunne applikationen ikke finde whitelisting af det CVR nummer fundet i klientens certifikat. Enten er de ikke whitelisted overhovedet (mest sandsynligt), eller også er der en fejl i koden. Databasen kan checkes for at opklare dette. Hvis det viser sig at der er fejl i applikationen, så er Subject feltet af klientens certifikat nødvendigt for at løse problemet.

Ved fejlkode -7 er den nødvendige database service nede, og applikationen kan reelt ikke fungere før SDM databasen er oppe. Applikationen er dog i stand til at recover fra databasen når servicen går ned, uden at nogen indgriben er nødvendig. Applikationen kræver dog, at databasen er tilgængelig ved opstart, ellers vil det give en fejl, og applikationen bliver ikke deployeret. Kun en ny deployering kan få servicen op at køre igen.

Ved fejlkode -8 er der tale om fejl under forespørgsel mod SOR databasen enten fordi databasen er nede eller data er ikke tilstede.

Ved fejlkode -9 er der tale om fejl under transformation af XML til objekt, og det tyder på forkert konstrueret SOAP body. Fejlen ligger højest sandsynligt hos klienten, men bør undersøges nærmere.

Ved fejlkode -10, -11, -12 og -13 er fejl hvor at transformation af objekter til XML har fejlet. De bør ikke kunne forekomme.


Ved alle resterende fejl ligger ansvaret udelukkende hos klienten.

Logning

Applikationen bruger tre forskellige logs.

Audit log

Audit logning benytter audit API biblioteket, og skriver til audit.log i logs/ mappen. Følgende oplysninger bliver trukket ud af forespørgelsen og skrevet i audit loggen:

  • Message ID
  • SOAP operation
  • Klient certifikatets common name
  • Klient certifikatets organization
  • Klient certifikatets CVR
  • Klient certifikatets ID
  • Klient certifikatets type

SLA log

SLA logning benytter nsp-util biblioteket, og skriver til nsputil-sla.log i logs/ mappen. Der bliver startet et nyt SLA log objekt på to forskellige tidspunkter; når en forespørgelse kommer ind til applikationen, og når applikationen skal lave en forespørgelse mod backend.

Ved forespørgelser til applikationen er der følgende ID'er:

IDOperation
210GetSorEntity
235ShakSorMap
240SorShakMap


Applikation log

Applikation loggen styres af log4j-sorls.properties, og denne afhænger af hvad der er blevet sat op. Det er muligt slet ikke at få en applikation log på disken, hvis dette ønskes (ikke anbefalet).

Typisk kun ved fejl, vil der blive skrevet i applikation loggen. Der kommer en kort fejl beskrivelse, og så stacktrace fra hvor fejlen skete.

  • No labels