Formål

Denne guide har som formål at give et overblik over, hvordan behandlingsrelationsservicen (BRS) kaldes, samt hvorledes der hentes notifikationer fra opfølgninger ed notifikationsservicen.
Guiden indeholder referencer til kodeeksempler og snitfladebeskrivelser for kald til behandlingsrelationsservicen og notifikationsservicen.

Baggrund

Behandlingsrelationsservicen (BRS) er en service, der returnerer den bedst kendte behandlingsrelation imellem en borger og en sundhedsfaglig person på et givet tidspunkt.
I sundhedssektoren findes der ikke et register over behandlingsrelationer, og BRS gør derfor brug af afledt viden fra en række nationale registre for at bestemme den aktuelle behandlingsrelation. De konkrete registre og algoritmer, der anvendes i BRS til at bestemme den aktuelle behandlingsrelation er beskrevet i BRS - Design- og Arkitekturbeskrivelse.

Da den gængse registreringspraksis tillader opdateringer af registrene i et relativt stort tidsrum efter en handling, kan gentagne kald til BRS med samme input give forskelligt resultat over tid, idet datagrundlaget med stor sikkerhed vil ændre sig i dagene og ugerne efter en sundhedsfaglig hændelse, f.eks. en lægekonsultation eller et indlæggelsesforløb på et sygehus.

Man kan i kaldet til BRS vælge at lade servicen håndtere denne kompleksitet, idet man gennem en række parametre kan konfigurere BRS-håndteringen og styre hvordan – og hvornår – der skal leveres et endeligt svar til kaldet.

Målgruppe og forudsætninger

Slutbrugerne er i denne sammenhæng f.eks. udviklere og arkitekter hos leverandører, som ønsker at integrere til BRS. Se Behandlingsrelationsservice (BRS) - Leverancebeskrivelse for en forretningsmæssig beskrivelse af BRS.

Det forudsættes at læseren kender til Den Gode Webservice (DGWS) og den nationale serviceplatform (NSP).

Snitfladebeskrivelse

Behandlingsrelationsservicen giver mulighed for at bestille opfølgninger gennem brug af notifikationsservicen. Da det forventes at denne option vil blive brugt af de fleste anvendere, er begge snitflader dokumenteret nedenfor.

Bemærk at der refereres til teknisk dokumentation af snitfladeelementerne i afsnittene nedenfor med referencer sat i anførselstegn. Disse referencer peger på BRS-projektet på nspop, og det følgende præfiks er underforstået i referencerne: https://svn.nspop.dk/svn/components/brs/

Behandlingsrelationsservice

Endpoint

Behandlingsrelationsservicen kan tilgås i de decentrale NSP-miljøer (dNSP) under adressen

*\[miljøurl\]/brs-nsp/service/brs*

hvor den stiller operationen "treatmentRelation" til rådighed. Denne operation tager en soap besked som input, indeholdende en header og en body. Headeren indeholder en WSSE header samt en Medcom header som specificeret i Den Gode Webservice (DGWS) version 1.0.1. SOSI idkortet i headeren skal være på niveau 3 og udstedt af SOSI-STS.

WSDL findes ved at tilføje "?wsdl"-postfix til adressen.

Eksempel på endpoint i testmiljøerne (cNSP i TEST2-miljøet):
http://test2-cnsp.ekstern-test.nspop.dk:8080/brs-nsp/service/brs

Forespørgsel til BRS

Body er defineret som et element af typen treatmentRelationRequestBody, der er en complexType indeholdende en række felter. Betydningen og anvendelsen af felterne er opsummeret i tabellen nedenfor.

Hvis der i kaldet til behandlingsrelationsservicen er angivet at der skal bestilles opfølgninger i opfølgningsservicen, vil der komme alarm-notifikationer, hvis de angivne kriterier ikke er opfyldt indenfor det i kaldet angivne tidsrum.

Disse notifikationer kan hentes med notifikationsservicen i det decentrale NSP-miljø.

Hvis der derimod indenfor det angivne tidsrum opnås tilstrækkelig evidens, så de angivne kriterier er opfyldt, bliver der ikke genereret notifikationer.

Eksempel

Følgende er et eksempel på et request til BRS:

<treatmentRelationRequestBody xmlns="http://nsi.dk/fmki20110601/brs">
  <OrganisationIdentifier>
    <DoctorOrganisationIdentifier>132435</DoctorOrganisationIdentifier>
  </OrganisationIdentifier>
  <PatientCpr>0101601951</PatientCpr>
  <HealthProfessionalCpr>0101601803</HealthProfessionalCpr>
  <RelationLookupTimeInterval>
    <start>2013-09-30T00:00:00+02:00</start>
    <end>2013-10-25T23:59:00+02:00</end>
  </RelationLookupTimeInterval>
  <TimeLimit>2013-09-30T11:04:37+02:00</TimeLimit>
  <QueryableCvr>31908574</QueryableCvr>
  <AcceptableRelations>
    <Relation>A</Relation>
    <Relation>B</Relation>
  </AcceptableRelations>
  <FollowupRelations>
    <All>All</All>
  </FollowupRelations>
  <AuthorisationIdentifier>DM712</AuthorisationIdentifier>
  <ServiceProvider>
    <Name>SJ</Name>
    <Version>0.1</Version>
    <Vendor>Sundhed.dk</Vendor>
  </ServiceProvider>
</treatmentRelationRequestBody>

Svar fra BRS

Operationen "treatmentRelation" returnerer et treatmentRelationResponse, der opfylder DGWS. Det vil sige, at det har en wsse og en medcom header. Selve svaret er defineret som et treatmentRelationResponseBody.  Betydningen af felterne er opsummeret i tabellen nedenfor:

Eksempel

Følgende er et eksempel på et response fra BRS:

<?xml version='1.0' encoding='UTF-8'?>
<ns6:treatmentRelationResponseBody xmlns="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" xmlns:ns2="http://www.w3.org/2000/09/xmldsig#" xmlns:ns3="http://www.medcom.dk/dgws/2006/04/dgws-1.0.xsd" xmlns:ns4="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:ns5="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:ns6="http://nsi.dk/fmki20110601/brs" xmlns:ns7="http://rep.oio.dk/cvr.dk/xml/schemas/2005/03/22/" xmlns:ns8="http://rep.oio.dk/cpr.dk/xml/schemas/core/2005/03/18/">
  <ns6:SufficientRelation>false</ns6:SufficientRelation>
  <ns6:ActualRelations>
    <ns6:Relation>C</ns6:Relation>
  </ns6:ActualRelations>
  <ns6:FollowupOrdered>true</ns6:FollowupOrdered>
  <ns6:UniqueReferenceId>0044ba5a-8378-4d33-b128-03522ed26e85</ns6:UniqueReferenceId>
  <ns6:ExternalReferenceId>e4a4ab3f-3f7f-4e5d-a311-5942c14856b8</ns6:ExternalReferenceId>
</ns6:treatmentRelationResponseBody>

Notifikationsservice

Endpoint

Notifikationsservicen udstilles på NSP'erne under adressen

*\[miljøurl\]gos/service/notification*

hvor den sætter operationen "notificationQuery" til rådighed.

Eksempel på endpoint i testmiljøerne (cNSP i TEST2-miljøet):
http://test2-cnsp.ekstern-test.nspop.dk:8080/gos/service/notification

Bemærk: NSP miljøernes loadbalancer router trafikken fra ovennævnte endpoint til brs-nsp/service/notification, idet dette er adressen i BRS2.

Forespørgsel til Notifikationsservice

Body er defineret som et element af typen notificationQueryRequestBody, der er en complexType indeholdende en række felter.  Betydningen af felterne er opsummeret i tabellen nedenfor:

Man kan hente notifikationer der er "udstedt" til ens eget CVR nummer – altså notifikationer, hvis QueryableCvr matcher CVR nummeret i headeren ved kaldet til Notifikationsservicen.

Bemærk at CVR nummeret ikke indgår som en eksplicit parameter, da det er indeholdt i SOSI idkortet, der optræder i SOAP headeren.

Denne operation tager en SOAP besked som input, indeholdende en header og en body. Headeren indeholder en WSSE header samt en Medcom header, som specificeret i Den Gode Webservice (DGWS) version 1.0.1. SOSI idkortet i headeren skal være på niveau 3.

Eksempel

Følgende er et eksempel på et request til Notifikationsservice:

<NotificationQueryRequestBody xmlns="http://nsi.dk/fmki20110601/notification">
  <Type>BRS</Type>
  <SerialNumber>1027</SerialNumber>
</NotificationQueryRequestBody>

Svar fra Notifikationsservice

Operationen "notificationQuery" returnerer et notificationQueryResponse der opfylder DGWS. Det vil bl.a. sige, at det har en wsse og en medcom header.  Svaret indeholder de første 100 notifikationer med serienummer højere end eller lig det der er angivet i forespørgslen.

Notifikationerne returneres i sorteret rækkefølge. Hver notifikation indeholder følgende informationer:

Notifikationers "payload" er af typen TreatmentRelationAlarm. Dette indeholder følgende elementer:

TreatmentRelationFollowup-elementet indeholder felterne:

Elementet TreatmentRelationRelayerData indeholder følgende data, der er nok til at identificere de kendte relationer mellem en behandler og en patient:

Eksempel

<?xml version='1.0' encoding='UTF-8'?>
<ns5:NotificationQueryResponseBody xmlns="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:ns2="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" xmlns:ns3="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:ns4="http://www.w3.org/2000/09/xmldsig#" xmlns:ns5="http://nsi.dk/fmki20110601/notification" xmlns:ns6="http://www.medcom.dk/dgws/2006/04/dgws-1.0.xsd">
  <ns5:Notifications>
    <ns5:Type>BRS</ns5:Type>
    <ns5:SerialNumber>1027</ns5:SerialNumber>
    <ns5:ExternalReferenceId>e4a4ab3f-3f7f-4e5d-a311-5942c14856b8</ns5:ExternalReferenceId>
    <ns5:QueryableCvr>31908574</ns5:QueryableCvr>
    <TreatmentRelationAlarmType:TreatmentRelationAlarmType xmlns:TreatmentRelationAlarmType="http://nsi.dk/fmki20110601/brs" xmlns="http://nsi.dk/fmki20110601/brs">
      <TreatmentRelationFollowup>
        <TreatmentRelationRelayerData>
          <OrganisationIdentifier>
            <DoctorOrganisationIdentifier>132435</DoctorOrganisationIdentifier>
          </OrganisationIdentifier>
          <PatientCpr>0101601951</PatientCpr>
          <HealthProfessionalCpr>0101601803</HealthProfessionalCpr>
          <RelationLookupTimeInterval>
            <start>2013-09-30T00:00:00+02:00</start>
            <end>2013-10-25T23:59:00+02:00</end>
          </RelationLookupTimeInterval>
        </TreatmentRelationRelayerData>
        <TimeLimit>2013-09-30T11:04:37+02:00</TimeLimit>
        <ExternalReferenceId>e4a4ab3f-3f7f-4e5d-a311-5942c14856b8</ExternalReferenceId>
        <QueryableCvr>31908574</QueryableCvr>
        <AcceptableRelations>
          <Relation>A</Relation>
          <Relation>B</Relation>
        </AcceptableRelations>
        <RequestSource>
          <TreatmentRelationRequestBody>
            <OrganisationIdentifier>
              <DoctorOrganisationIdentifier>132435</DoctorOrganisationIdentifier>
            </OrganisationIdentifier>
            <PatientCpr>0101601951</PatientCpr>
            <HealthProfessionalCpr>0101601803</HealthProfessionalCpr>
            <RelationLookupTimeInterval>
              <start>2013-09-30T00:00:00+02:00</start>
              <end>2013-10-25T23:59:00+02:00</end>
            </RelationLookupTimeInterval>
            <TimeLimit>2013-09-30T11:04:37+02:00</TimeLimit>
            <QueryableCvr>31908574</QueryableCvr>
            <AcceptableRelations>
              <Relation>A</Relation>
              <Relation>B</Relation>
            </AcceptableRelations>
            <FollowupRelations>
              <All>All</All>
            </FollowupRelations>
            <AuthorisationIdentifier>DM712</AuthorisationIdentifier>
            <ServiceProvider>
              <Name>SJ</Name>
              <Version>0.1</Version>
              <Vendor>Sundhed.dk</Vendor>
            </ServiceProvider>
          </TreatmentRelationRequestBody>
        </RequestSource>
        <TreatmentRelationFollowupSerialNumber>1123</TreatmentRelationFollowupSerialNumber>
        <UniqueId>0044ba5a-8378-4d33-b128-03522ed26e85</UniqueId>
      </TreatmentRelationFollowup>
      <ActualRelations>
        <Relation>C</Relation>
      </ActualRelations>
    </TreatmentRelationAlarmType:TreatmentRelationAlarmType>
  </ns5:Notifications>
</ns5:NotificationQueryResponseBody>

Format for tidsstempler

Bemærk at formatet på alle tidsstempler (f.eks. TimeLimit og RelationLookupTimeInterval) er som følger: YYYY-MM-DD'T'HH:MM:SS'+'forskydning fra GMT', f.eks. "2013-01-31T22:59:40+02:00"

Fejlkoder

Nedenfor ses en liste af typiske fejl der kan forekomme når en service kaldes. Fejl der returneres indeholder en fejlkode samt en fejltekst med yderligere detaljer. Teksten er ikke medtaget i tabellen nedenfor da den kan variere afhængig af hvad der gav anledning til fejlen.

Procedure for udskiftning af certifikat

I dette afsnit beskrives hvad der skal ske, når en anvender skal udskifte sit certifikat, og det nye certifikat er udstedt til et andet CVR-nummer end det gamle certifikat. Hvis CVR-nummeret ikke er ændret, aftales blot at NSP-operatøren whitelister det nye certifikat, og fjerner det gamle fra whitelisten når der er meldt OK fra anvenderen.

Nogle anvendere er i stand til at benytte to certifikater i en overgangsperiode, andre er ikke, og derfor beskrives disse to tilfælde særskilt. Overgangsperioden er på 90 dage.

Udskiftning med overgangsperiode

Hvis det gamle og nye certifikat kan anvendes samtidigt i en periode, er proceduren for udskiftning som følger:

1. Det aftales med NSP-operatøren, hvornår det nye certifikat tages i brug. NSP-operatøren whitelister certifikatets CVR-nummer på dette tidspunkt.
2. Anvenderen sørger for, inden for overgangsperioden, at ophøre med at bruge det gamle certifikat. Hvis andre anvendere genererer alarmer til det gamle CVR-nummer, orienteres de om at de fremefter skal generere alarmer på det nye CVR-nummer.
3. Ved overgangsperiodens udløb fjerner NSP-operatøren det gamle CVR-nummer fra whitelisten.

Udskiftning uden overgangsperiode

Hvis det ikke er muligt for anvenderen at anvende to certifikater i en periode, er proceduren for udskiftning som følger:

1. Anvenderen aftaler med NSP-operatøren, hvornår der udskiftes certifikat. NSP-operatøren whitelister det nye certifikat.
2. Eventuelle andre anvendere, der genererer alarmer eller notifikationer til CVR-nummeret på det gamle certifikat, orienteres om det forestående skift, og at de skal anvende det nye CVR-nummer.
3. På det aftale tidspunkt ophører anvenderen med at kalde BRS.
4. NSP-operatøren duplikerer alle alarmer og notifikationer hørende til det gamle CVR-nummer, således at kopien hører til det nye CVR-nummer (beskrevet i driftsvejledningen, afsnit 4.2.
5. NSP-operatøren melder klar til anvenderen.
6. Anvenderen begynder at anvende BRS igen med det nye certifikat.

Eksempler på at kalde services

Java frameworks

JAVA SEAL er et open source bibliotek, der kan håndtere SOSI IDKort, DGWS og integration til SOSI-STS. Biblioteket er dokumenteret på digitaliser.dk:
http://digitaliser.dk/group/374971

Eksempelkode i Java

Der er udviklet testkode, der gør brug af JAVA SEAL biblioteket, sammen med JAXWS webservicestakken til at kalde de to services. Eksemplet kan bruges til at teste de forskellige service-håndtag fra ydersiden. Man kan med fordel tage udgangspunkt i eksemplet, når der implementeres en javabaseret webserviceklient, der gør brug af BRS og opfølgningsservicen.
Test-koden kan hentes fra projektet på nspop:

https://svn.nspop.dk/svn/components/brs

Hvor følgende klasse er indgangspunktet for at kalde behandlingsrelationsservicen production/src/main/java/dk/nsi/behandlingsrelationservice/BRSQueries.java

.NET frameworks

Seal.NET er et open source framework, der kan håndtere SOSI IDKort, DGWS og integration til SOSI-STS. Seal.NET er dokumenteret på digitaliser.dk:
http://digitaliser.dk/group/375117
Der er pt. ikke skrevet eksempelkode på at kalde de to services fra et .NET projekt, men der er WSDL'er til rådighed, som man kan anvende i Visual Studio's webservice wizard, kombineret med Seal.NET.

Ændringslog