Versions Compared

Old Version 22

changes.mady.by.user Unknown User (tbr@kvalitetsit.dk)

Saved on

compared with

New Version 23

changes.mady.by.user Unknown User (tbr@kvalitetsit.dk)

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Request

...

rootNational Adviseringsservice 2 (NAS2) - Leverancebeskrivelse
includeroottrue

Indhold

Table of Contents

Introduktion

Formål

Dette dokument er en vejledning til anvendelse af den Nationale Adviseringsservice (NAS). På baggrund af dokumentet er det muligt at udvikle adviseringskildesystemer og adviseringsmodtagersystemer.

Formålet med dette dokument er at vejlede udviklere, der skal udvikle eller vedligeholde systemer, som anvender snitflader på National Adviseringsservice.

Læsevejledning

Dette dokument er rettet mod udviklere, der skal udvikle eller teste services, der har grænseflader mod National Adviseringsservice.

Læseren forudsættes at være bekendt med de involverede teknologier, som f.eks. SOAP og DGWS.

Dokument historik

...

Definitioner og referencer

...

Den snitflade som et afsender system kalder for at afsende adviseringer.

...

Introduktion til National Adviseringsservice

National Adviseringsservice er en service på NSP'en, der hjælper med at distribuere adviseringer fra et afsendersystem til et eller flere modtagersystemer via en standardiseret snitflade. 

Et afsendersystem sender adviseringer på et givent topic. En advisering består af et topic, et eller flere ID'er, der kan filteres på og så selve adviseringen. Afsendelse af adviseringer sker via NotificationBroker-snitfladen. Før et system kan afsende adviseringer skal topic være oprettet i systemet. 

Ønsker man hente adviseringer, sker det ved at modtagersystemet først opretter en evt. IDliste, et pullpoint og til sidst et abonnement på et emne og en evt. IDListe. Herefter er anvendersystemet klar til at hente adviseringer via det pullpoint der blev oprettet. 

I snitfladebeskrivelsen er der, udover beskrivelse af selve snitfladen, en beskrivelse af et konkret brugsscenarie samt tilhørende eksempler på request og response. 

Snitfladebeskrivelse

Generelt

Overordnet set er det WS-notication standarden, der implementeres og der henvises til disse snitflader. Ved hver af nedenstående operationer henvises der til, hvilken operation der er tale om i WS-notification standarden. De steder hvor der er specielle forhold til WS-notification standarden er disse også dokumenteret. Det er typisk hvilke krav der er til "any" elementerne.

Endpoints

Nedenstående er en tabel over endpoints for de forskellige services. 

...

Topics

Inden der kan leveres adviseringer til et Topic skal dette eksplicit oprettes. Dette sker gennem en supporthenvendelse oprettet på nspop.dk.

Bemærk: Der skal indgås 'Tilslutningsaftale: - Specifikke vilkår for oprettelse af NAS 2.0 Topics, med opfyldelse navnestandard m.v. Venligst kontakt af NSP-Operatør på nsp.op@nsi.dk

Navnet på alle Topics der ønskes oprettet skal følge denne skabelon:

Code Block
http://ejer.dk/projekt/år/måned/dag:hændelse
  • Ejer er et registreret domæne for den organisation der ejer projektet. F.eks. sundhedsdatastyrelsen.dk
  • Forretningsområde er et kort navn der tydeligt identificere det forretningsområde, der er ansvarlig for adviseringerne [a-z0-9]*. F.eks. graviditet, medicinering, laboratoriesvar
  • År/måned/dag er datoen for hvornår standarden for adviseringens payload er fastsat [0-9]{4}/[0-9]{2}/[0-9]{2}. F.eks. 2020/01/01
  • Hændelse skal tydeligt forklare hvad der er adviseringen omhandler. F.eks MaternityCardUpdated

Der er mulighed for whitelisting på et Topic, så kun godkendte klienter har adgang til at oprette abonnement og hente beskeder for et Topic. Adgangsstyringen vil i så fald ske på baggrund af CVR eller CVR-Xid i certifikatet ved et kald til servicen. 

Afsendersnitflade

Afsender snitfladen er ikke beskyttet af DGWS og sikkerhed sker udelukkende på baggrund af IP whitelisting og det faktum at topic skal være oprettet i systemet for at det er muligt at afsende adviseringer.

Scenarie for afsender

Det Fælles Medicin kort udsender en advisering på emnet TESTNAS-TOPIC1, omhandlende et specifikt cpr-nummer.

Scenariet omfatter:

  1. FMK sender advisering på CPR-nummer

Afsender sender advisering med CPR-nummer   

...

NAS-NB-1: Aflevering af advisering

...

Følgende er et eksempel på advisering med id-filtrerbart indhold.  

Snitflade

Dette er operationen Notify på NotificationBroker der kaldes. I WS-notification hedder operationen Notify. 

Request består af nedenstående. 

...

Code Block
languagexml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:Envelope xmlns:ns6="http://docs.oasis-open.org/wsrf/bf-2" xmlns:ns5="http://docs.oasis-open.org/wsn/b-2" xmlns:ns8="http://docs.oasis-open.org/wsn/t-1" xmlns:ns7="http://docs.oasis-open.org/wsrf/rp-2" xmlns:ns9="http://nsi.dk/advis/v10" xmlns:ns2="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns4="http://www.w3.org/2005/08/addressing" xmlns:ns3="http://www.medcom.dk/dgws/2006/04/dgws-1.0.xsd">
  <ns2:Header/>
  <ns2:Body>
    <ns5:Notify>
      <ns5:NotificationMessage>
        <ns5:Topic Dialect="http://docs.oasis-open.org/wsn/t-1/TopicExpression/Simple">TESTNAS-TOPIC1</ns5:Topic>
        <ns5:Message>
          <ns9:NotifyContent id="2512484916" idType="http://nsi.dk/advis/v10/CPR" isSystemNotification="false">
            <ns9:NotifyContent id="12345" idType="mintype-abc">
              <test>&lt;noget&gt;xml&lt;/noget&gt;</test>
            </ns9:NotifyContent>
          </ns9:NotifyContent>
        </ns5:Message>
      </ns5:NotificationMessage>
    </ns5:Notify>
  </ns2:Body>
</ns2:Envelope>

Response

Code Block
languagexml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:Envelope xmlns:ns2="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns3="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" xmlns:ns4="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:ns5="http://www.w3.org/2000/09/xmldsig#" xmlns:ns6="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:ns7="http://www.medcom.dk/dgws/2006/04/dgws-1.0.xsd" xmlns:ns8="http://www.w3.org/2005/08/addressing" xmlns:ns9="http://docs.oasis-open.org/wsn/b-2" xmlns:ns10="http://docs.oasis-open.org/wsrf/bf-2" xmlns:ns11="http://docs.oasis-open.org/wsrf/rp-2" xmlns:ns12="http://docs.oasis-open.org/wsn/t-1" xmlns:ns13="http://nsi.dk/advis/v10">
  <ns2:Header/>
  <ns2:Body>
    <ns9:NotifyResponse/>
  </ns2:Body>
</ns2:Envelope>
Navitabs
rootNational Adviseringsservice 2 (NAS2) - Leverancebeskrivelse
includeroottrue


Indhold

Table of Contents

Introduktion

Formål

Dette dokument er en vejledning til anvendelse af den Nationale Adviseringsservice (NAS). På baggrund af dokumentet er det muligt at udvikle adviseringskildesystemer og adviseringsmodtagersystemer.

Formålet med dette dokument er at vejlede udviklere, der skal udvikle eller vedligeholde systemer, som anvender snitflader på National Adviseringsservice.

Læsevejledning

Dette dokument er rettet mod udviklere, der skal udvikle eller teste services, der har grænseflader mod National Adviseringsservice.

Læseren forudsættes at være bekendt med de involverede teknologier, som f.eks. SOAP og DGWS.

Dokument historik

DatoAnsvarligBeskrivelse


Initiel version

Definitioner og referencer

RerenceBeskrivelse
DGWSDen Gode WebService
NotifikationBroker

Den snitflade som et afsender system kalder for at afsende adviseringer.

PullPointDen snitflade som et modtager system kalder for at hente adviseringer og nedlægge et pull point.
PullPointFactoryDen snitflade som et modtager system kalder for at oprette et pull point
IDListDen snitflade som et modtager system kalder for at vedligeholde id lister. 
SubscriptonManagerDen snitflade som et modtager system kalder for at oprette og nedlægge abonnementer. 
WS-NotificationDen standard som der implementeres i NAS. For standard snitflader etc. se https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wsn

Introduktion til National Adviseringsservice

National Adviseringsservice er en service på NSP'en, der hjælper med at distribuere adviseringer fra et afsendersystem til et eller flere modtagersystemer via en standardiseret snitflade. 

Et afsendersystem sender adviseringer på et givent topic. En advisering består af et topic, et eller flere ID'er, der kan filteres på og så selve adviseringen. Afsendelse af adviseringer sker via NotificationBroker-snitfladen. Før et system kan afsende adviseringer skal topic være oprettet i systemet. 

Ønsker man hente adviseringer, sker det ved at modtagersystemet først opretter en evt. IDliste, et pullpoint og til sidst et abonnement på et emne og en evt. IDListe. Herefter er anvendersystemet klar til at hente adviseringer via det pullpoint der blev oprettet. 

I snitfladebeskrivelsen er der, udover beskrivelse af selve snitfladen, en beskrivelse af et konkret brugsscenarie samt tilhørende eksempler på request og response. 

Snitfladebeskrivelse

Generelt

Overordnet set er det WS-notication standarden, der implementeres og der henvises til disse snitflader. Ved hver af nedenstående operationer henvises der til, hvilken operation der er tale om i WS-notification standarden. De steder hvor der er specielle forhold til WS-notification standarden er disse også dokumenteret. Det er typisk hvilke krav der er til "any" elementerne.

Endpoints

Nedenstående er en tabel over endpoints for de forskellige services. 

ServiceEndpoint
Pull point factory/nas2/pullpointfactory
ID list/nas2/idlist
Subscription manager/nas2/subscriptionmanager
Notification broker/nas2/notificationbroker
Pull point factory/nas2/pullpointfactory

Topics

Inden der kan leveres adviseringer til et Topic skal dette eksplicit oprettes. Dette sker gennem en supporthenvendelse oprettet på nspop.dk.

Bemærk: Der skal indgås 'Tilslutningsaftale: - Specifikke vilkår for oprettelse af NAS 2.0 Topics, med opfyldelse navnestandard m.v. Venligst kontakt af NSP-Operatør på nsp.op@nsi.dk

Navnet på alle Topics der ønskes oprettet skal følge denne skabelon:

Code Block
http://ejer.dk/projekt/år/måned/dag:hændelse
  • Ejer er et registreret domæne for den organisation der ejer projektet. F.eks. sundhedsdatastyrelsen.dk
  • Forretningsområde er et kort navn der tydeligt identificere det forretningsområde, der er ansvarlig for adviseringerne [a-z0-9]*. F.eks. graviditet, medicinering, laboratoriesvar
  • År/måned/dag er datoen for hvornår standarden for adviseringens payload er fastsat [0-9]{4}/[0-9]{2}/[0-9]{2}. F.eks. 2020/01/01
  • Hændelse skal tydeligt forklare hvad der er adviseringen omhandler. F.eks MaternityCardUpdated

Der er mulighed for whitelisting på et Topic, så kun godkendte klienter har adgang til at oprette abonnement og hente beskeder for et Topic. Adgangsstyringen vil i så fald ske på baggrund af CVR eller CVR-Xid i certifikatet ved et kald til servicen. 

Afsendersnitflade

For afsendersnitfladen er det ikke for nuværende et krav at requests er DGWS-beskyttede, og dermed sker sikkerhed på baggrund af IP whitelisting og det faktum at topic skal være oprettet i systemet for at det er muligt at afsende adviseringer.
Det vil dog overgå til at DGWS bliver påkrævet, og afsendere bør opdatere deres systemer til at håndtere dette. 
Hvis der er DGWS headers på kaldet vil disse blive verificeret. Hvis de ikke er inkluderet, vil requests gå igennem uden tjek, så længe det endnu ikke er påkrævet. 

Scenarie for afsender

Det Fælles Medicin kort udsender en advisering på emnet TESTNAS-TOPIC1, omhandlende et specifikt cpr-nummer.

Scenariet omfatter:

  1. FMK sender advisering på CPR-nummer

Afsender sender advisering med CPR-nummer   

NAS-NB-1: Aflevering af advisering

Som et eksternt system ønsker jeg at aflevere en advisering til NAS2, så denne kan distribueres videre til abonnenter på det angivne topic


Følgende er et eksempel på advisering med id-filtrerbart indhold.  

Snitflade

Dette er operationen Notify på NotificationBroker der kaldes. I WS-notification hedder operationen Notify. 

Request består af nedenstående. 

Notify
ElementKrævetAnvendtBeskrivelse
NotificationMessageJaJaEt eller flere NotificationMessage elementer.
anyNejNejAnvendes ikke
NotificationMessage
ElementKrævetAnvendtBeskrivelse
SubscriptionReferenceNejNejAnvendes ikke.
TopicJaJaElement af typen TopicExpressionType
ProducerReferenceNejNejAnvendes ikke.
Message

Selve adviseringen der skal bestå af et NotifyContent element
TopicExpressionType
ElementKrævetAnvendtBeskrivelse
Dialect (attribute)JaJaSkal have værdien http://docs.oasis-open.org/wsn/t-1/TopicExpression/Simple. Bemærk at dette er en attribute.
ContentJaJaTopic der sendes adviseringer til.
NotifyContent
ElementKrævetAnvendtBeskrivelse
Id (attribute)JaJaID adviseringen vedrører. 
idType (attribute)JaJa

ID type adviseringen vedrører.

anyJaJaIndhold af adviseringen.


Response består af nedenstående. Er et tomt element.

NotifyResponse
ElementKrævetAnvendtBeskrivelse


Request med DGWS headers

Code Block
languagexml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:Envelope xmlns:ns6="http://docs.oasis-open.org/wsrf/bf-2" xmlns:ns5="http://docs.oasis-open.org/wsn/b-2" xmlns:ns8="http://docs.oasis-open.org/wsn/t-1" xmlns:ns7="http://docs.oasis-open.org/wsrf/rp-2" xmlns:ns9="http://nsi.dk/advis/v10" xmlns:ns2="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns4="http://www.w3.org/2005/08/addressing" xmlns:ns3="http://www.medcom.dk/dgws/2006/04/dgws-1.0.xsd">
  <ns2:Header>
    <!-- DGWS headers -->
  </ns2:Header>
  <ns2:Body>
    <ns5:Notify>
      <ns5:NotificationMessage>
        <ns5:Topic Dialect="http://docs.oasis-open.org/wsn/t-1/TopicExpression/Simple">TESTNAS-TOPIC1</ns5:Topic>
        <ns5:Message>
          <ns9:NotifyContent id="2512484916" idType="http://nsi.dk/advis/v10/CPR" isSystemNotification="false">
            <ns9:NotifyContent id="12345" idType="mintype-abc">
              <test>&lt;noget&gt;xml&lt;/noget&gt;</test>
            </ns9:NotifyContent>
          </ns9:NotifyContent>
        </ns5:Message>
      </ns5:NotificationMessage>
    </ns5:Notify>
  </ns2:Body>
</ns2:Envelope>

Request uden DGWS headers (UDFASES) 

Code Block
languagexml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:Envelope xmlns:ns6="http://docs.oasis-open.org/wsrf/bf-2" xmlns:ns5="http://docs.oasis-open.org/wsn/b-2" xmlns:ns8="http://docs.oasis-open.org/wsn/t-1" xmlns:ns7="http://docs.oasis-open.org/wsrf/rp-2" xmlns:ns9="http://nsi.dk/advis/v10" xmlns:ns2="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns4="http://www.w3.org/2005/08/addressing" xmlns:ns3="http://www.medcom.dk/dgws/2006/04/dgws-1.0.xsd">
  <ns2:Header/>
  <ns2:Body>
    <ns5:Notify>
      <ns5:NotificationMessage>
        <ns5:Topic Dialect="http://docs.oasis-open.org/wsn/t-1/TopicExpression/Simple">TESTNAS-TOPIC1</ns5:Topic>
        <ns5:Message>
          <ns9:NotifyContent id="2512484916" idType="http://nsi.dk/advis/v10/CPR" isSystemNotification="false">
            <ns9:NotifyContent id="12345" idType="mintype-abc">
              <test>&lt;noget&gt;xml&lt;/noget&gt;</test>
            </ns9:NotifyContent>
          </ns9:NotifyContent>
        </ns5:Message>
      </ns5:NotificationMessage>
    </ns5:Notify>
  </ns2:Body>
</ns2:Envelope>

Response med DGWS headers

...

ID type adviseringen vedrører.

...

Response består af nedenstående. Er et tome element.

...

Request

Code Block
languagexml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:Envelope xmlns:ns6ns2="http://docsschemas.oasis-openxmlsoap.org/soap/wsrfenvelope/bf-2" xmlns:ns5ns3="http://docs.oasis-open.org/wsn/b-2" xmlns:ns8="http://docs.oasis-open.org/wsn/t-1wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" xmlns:ns7ns4="httpurn://docs.oasis-open.org/wsrf/rp-2" xmlns:ns9="http://nsi.dk/advis/v10oasis:names:tc:SAML:2.0:assertion" xmlns:ns2ns5="http://schemaswww.xmlsoapw3.org/soap2000/envelope09/xmldsig#" xmlns:ns4ns6="http://wwwdocs.w3oasis-open.org/wss/20052004/08/addressing01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:ns3ns7="http://www.medcom.dk/dgws/2006/04/dgws-1.0.xsd">
  <ns2:Header/>
  <ns2:Body>
    <ns5:Notify>
      <ns5:NotificationMessage>
        <ns5:Topic Dialect xmlns:ns8="http://www.w3.org/2005/08/addressing" xmlns:ns9="http://docs.oasis-open.org/wsn/b-2" xmlns:ns10="http://docs.oasis-open.org/wsnwsrf/t-1/TopicExpression/Simple">TESTNAS-TOPIC1</ns5:Topic>
        <ns5:Message>
          <ns9:NotifyContent id="2512484916" idType="bf-2" xmlns:ns11="http://nsi.dk/advis/v10/CPR" isSystemNotification="false">
            <ns9:NotifyContent id="12345" idType="mintype-abc">
              <test>&lt;noget&gt;xml&lt;/noget&gt;</test>
            </ns9:NotifyContent>
          </ns9:NotifyContent>
        </ns5:Message>
      </ns5:NotificationMessage>
    </ns5:Notify>docs.oasis-open.org/wsrf/rp-2" xmlns:ns12="http://docs.oasis-open.org/wsn/t-1" xmlns:ns13="http://nsi.dk/advis/v10">
  <ns2:Header>
    <!-- DGWS headers -->
  </ns2:Header>
  <ns2:Body>
    <ns9:NotifyResponse/>
  </ns2:Body>
</ns2:Envelope>

Response uden DGWS headers (UDFASES)

Code Block
languagexml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:Envelope xmlns:ns2="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns3="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" xmlns:ns4="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:ns5="http://www.w3.org/2000/09/xmldsig#" xmlns:ns6="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:ns7="http://www.medcom.dk/dgws/2006/04/dgws-1.0.xsd" xmlns:ns8="http://www.w3.org/2005/08/addressing" xmlns:ns9="http://docs.oasis-open.org/wsn/b-2" xmlns:ns10="http://docs.oasis-open.org/wsrf/bf-2" xmlns:ns11="http://docs.oasis-open.org/wsrf/rp-2" xmlns:ns12="http://docs.oasis-open.org/wsn/t-1" xmlns:ns13="http://nsi.dk/advis/v10">
  <ns2:Header/>
  <ns2:Body>
    <ns9:NotifyResponse/>
  </ns2:Body>
</ns2:Envelope>


Abonnementsnitflade

Abonnementsnitfladen er beskyttet af DGWS og det er derfor krævet at man har optaget et token i STS'en inden man kalder nedenstående snitflader. 

...