Interfaces Abonnementenregister
Abonnement Interface
Algemeen
Base endpoint en FHIR-versions
De waarde van de base-URL van de FHIR endpoints die het Abonnementenregister biedt t.b.v. de Abonnement Interface ( [base] dus ), dient voor alle FHIR-interacties gelijk te zijn aan "https://<FQDN>[/<path-extension>]/fhir/<fhir-version>". De waarde van <fhir-version>
is dan bijvoorbeeld "R4" of "R5".
T.b.v. de Abonnement Interface worden de volgende FHIR-versions ondersteund:
R4
HTTP-request headers
Bij iedere interactie, worden in ieder HTTP-request, de volgende HTTP headers meegezonden:
Feature | Authorization HTTP Header |
---|---|
Type | Subfeature |
Versie | 1.0.0 |
Groep | HTTP Headers |
Gepubliceerd |
|
Delta | Initiële versie van feature. |
Authorization: Bearer <AORTA access_token>
Een AORTA access_token is altijd een JSON Web Token (JWT).
Een JWT bestaat uit een aantal base64 strings, die aan elkaar zijn gekoppeld met punten. Indien een token een SAML Assertion zou zijn, dan dient het altijd base64url te worden gecodeerd conform RFC 4648. Omdat een base64url geëncodeerde SAMLv2 Assertion geen punten kan bevatten, is de ontvanger altijd in staat om het type token bepalen.
In het token, dat wordt ontvangen in een Authorization header, is informatie opgenomen over welke type inhoudelijk token het betreft en welke versie, dus bijvoorbeeld dat het gaat om een AORTA access_token.
Het BSN van de patient waarop een abonnement betrekking heeft wordt bij alle interacties meegegeven in het AORTA access_token. Alle interacties hebben dus betrekking op een en dezelfde patiënt. Dit geldt ook voor interacties die worden verstuurd in een batch of transaction Bundle.
Feature | AORTA-ID HTTP Header |
---|---|
Type | Subfeature |
Versie | 1.0.0 |
Groep | HTTP Headers |
Gepubliceerd |
|
Delta | Initiële versie van feature. |
AORTA-ID: initialRequestID=<UUID conform RFC4122>; requestID=<UUID conform RFC4122>
Het initialRequestID attribuut bevat het ID van het allereerste request in de hele keten en dient te worden opgenomen in de logbestanden van alle partijen in de keten, zodat bij foutopsporing de verschillende logbestanden aan elkaar kunnen worden gerelateerd.
Het requestID is voor iedere request message uniek. In requests wordt deze gegenereerd door de client. Ook het requestID dient te worden opgenomen in de verschillende logbestanden, zodat altijd duidelijk is op welk bericht een log entry van toepassing is.
Feature | AORTA-Version HTTP Header |
---|---|
Type | Subfeature |
Versie | 1.0.0 |
Groep | HTTP Headers |
Gepubliceerd |
|
Delta | Initiële versie van feature. |
AORTA-Version: contentVersion=<versienummer>; acceptVersion=<versienummer>
Wanneer een Resource Server een FHIR interactie ontvangt, dan kan het a.d.h.v. de syntax van het ontvangen request afleiden om welke interactie het gaat, bijvoorbeeld "een FHIR-search naar Obervations", of "een FHIR-read van een Binary". Daarnaast is iedere interactie voorzien van een versienummer. Voor versienummering wordt gebruik gemaakt van semantic versioning.
De acceptVersion
geeft aan conform welke versie(s) de interactie mag worden verwerkt en beantwoord. Het versienummer in de acceptVersion
wordt gespecificeerd conform semver, dus bijvoorbeeld "2.x" of "~1.2.3 || ^2.1.0". In het algemeen geldt dat een resource server een interactie dient te verwerken conform de hoogst aangegeven acceptVersion die het zelf op dat moment kan toepassen.
De contentVersion
geeft aan welke versie van de interactie daadwerkelijk is gehanteerd. In de contentVersion
dient het versienummer de exacte versie van de interactie te bevatten die is gehanteerd, dus zonder wildcards of ranges, bijvoorbeeld “1”, of "2.2". De versie van een FHIR-interactie is opgenomen in het interactie-id.
HTTP-response headers
Bij iedere interactie, worden in iedere HTTP-response, de volgende HTTP headers meegezonden:
Subfeature | AORTA-Version HTTP Header |
---|---|
Versie | 1.0.0 |
AORTA-Version: contentVersion=<versienummer>
De contentVersion
geeft aan welke versie van de interactie daadwerkelijk is gehanteerd. In de contentVersion
dient het versienummer de exacte versie van de interactie te bevatten die is gehanteerd, dus zonder wildcards of ranges, bijvoorbeeld “1”, of "2.2". De versie van een FHIR-interactie is opgenomen in het interactie-id.
Generieke parameters
Het gewenste formaat (JSON of XML) kan op de gebruikelijke manier via de Accept Header opgegeven worden, maar kunnen ook via de FHIR _format
parameter doorgegeven worden.
Ondersteunde waarden voor de _format
parameter zijn voor alle interacties, waar van toepassing:
de mogelijke opties die duiden op het FHIR JSON formaat of op het FHIR XML formaat.
Indien beide (Accept header en _format
parameter) in een request voorkomen, geldt de waarde van de _format
parameter. Indien geen enkele voorkomt, dan geldt het formaat van het Content-Type.
FHIR-profielen
Informatie over de gehanteerde FHIR-profielen op deze interface:
Feature | |
---|---|
Type | Subfeature |
Versie | 1.0.0 |
Groep | FHIR-profielen |
Gepubliceerd |
|
Delta | Initiële versie van feature. |
Voorbeelden:
Interacties
Registreren Abonnement
Feature | |
---|---|
Type | Service |
Versie | 1.0.0 |
Groep | Notificatie |
Gepubliceerd |
|
Delta | Initiële versie van feature. |
Feature | Versie | Dependency | Aanbieder | Afnemer |
---|---|---|---|---|
1.0.0 | Verplicht >=* | Verplicht >=1 | ||
1.0.0 | Verplicht >=1.* | Verplicht >=1 |
Deze interactie is gebaseerd op de FHIR conditional create interactie:
POST [base]/Subscription
If-None-Exist: [parameters]
Voorbeeld:
POST [base]/Subscription
If-None-Exist: identifier=<system>|<value>
{
"resourceType": "Subscription",
...
}
HTTP statuscodes die kunnen worden geretourneerd zijn:
Stap | Omschrijving | Uitkomst |
---|---|---|
1 | Het systeem ontvangt een verzoek en start de verwerking. | Gevraagde versie niet ondersteund statuscode 406 Not Acceptable |
Het systeem genereert de vereiste foutresponse en keert terug naar de exit stap van de main flow. | ||
Gehanteerde versie niet ondersteund statuscode 415 Unsupported Media Type | ||
Het systeem genereert de vereiste foutresponse en keert terug naar de exit stap van de main flow. | ||
2 | AOF.UC-COM.AUT.100.v1 Het systeem controleert of er een access_token is toegevoegd aan het request. | Ontbrekend token statuscode 401 Unauthorized
|
Het systeem genereert de vereiste foutresponse en keert terug naar de exit stap van de main flow. | ||
3 | AOF.UC-COM.AUT.200.v1 Het systeem toetst of het ontvangen token een geldig AORTA access_token is op de wijze zoals beschreven in Toetsing AORTA access_token. | Ongeldig token statuscode 401 Unauthorized
|
Het systeem genereert de vereiste foutresponse en keert terug naar de exit stap van de main flow. | ||
4 | AOF.UC-COM.VAL.100.v1 Het systeem toetst of het verzoek voldoet aan de interface specificatie. | Ongeldig FHIR-verzoek statuscode 400 Bad Request
|
Het systeem genereert de vereiste foutresponse en keert terug naar de exit stap van de main flow. | ||
5 | Het systeem toetst of het BSN in de patient claim van het AORTA access_token overeenkomt met het BSN in het criterium van het beoogde abonnement. | BSN in criterium komt niet overeen met token statuscode 403 Forbidden
|
Het systeem genereert de vereiste foutresponse en keert terug naar de exit stap van de main flow. | ||
6 | Het systeem toetst of de registratie van het abonnement is toegestaan:
| Registratie niet toegestaan statuscode 403 Forbidden
|
Het systeem genereert de vereiste foutresponse en keert terug naar de exit stap van de main flow. | ||
7 | Indien nog geen equivalent abonnement bestaat, zoals aangeduid door het equivalentie criterium ( | Meer dan één equivalent abonnement gevonden statuscode 412
|
Het systeem genereert de vereiste foutresponse en keert terug naar de exit stap van de main flow. | ||
8 <exit> | Het systeem retourneert een response naar de primaire actor. | Verwerking succesvol statuscode 200 OK |
Opvragen Abonnementen
Feature | |
---|---|
Type | Service |
Versie | 1.0.0 |
Groep | Notificatie |
Gepubliceerd |
|
Delta | Initiële versie van feature. |
Feature | Versie | Dependency | Aanbieder | Afnemer |
---|---|---|---|---|
1.0.0 | * | * | ||
1.0.0 | 1.0 |
Deze interactie is gebaseerd op de FHIR-search interactie.
GET [base]/Subscription{?[parameters]{&_format=[mime-type]}}
Ondersteunde parameters
zijn:
-
Voorbeeld:
GET [base]/Subscription
HTTP statuscodes die kunnen worden geretourneerd zijn:
Stap | Omschrijving | Uitkomst |
---|---|---|
1 | Het systeem ontvangt een verzoek en start de verwerking. | Gevraagde versie niet ondersteund statuscode 406 Not Acceptable |
Het systeem genereert de vereiste foutresponse en keert terug naar de exit stap van de main flow. | ||
2 | AOF.UC-COM.AUT.100.v1 Het systeem controleert of er een access_token is toegevoegd aan het request. | Ontbrekend token statuscode 401 Unauthorized
|
Het systeem genereert de vereiste foutresponse en keert terug naar de exit stap van de main flow. | ||
3 | AOF.UC-COM.AUT.200.v1 Het systeem toetst of het ontvangen token een geldig AORTA access_token is op de wijze zoals beschreven in Toetsing AORTA access_token. | Ongeldig token statuscode 401 Unauthorized
|
Het systeem genereert de vereiste foutresponse en keert terug naar de exit stap van de main flow. | ||
4 | AOF.UC-COM.VAL.100.v1 Het systeem toetst of het verzoek voldoet aan de interface specificatie. | Ongeldig FHIR-verzoek statuscode 400 Bad Request
|
Het systeem genereert de vereiste foutresponse en keert terug naar de exit stap van de main flow. | ||
5 | Het systeem voert de zoekopdracht uit:
| |
6 <exit> | Het systeem retourneert een response naar de primaire actor. | Verwerking succesvol statuscode 200 OK |
Wijzigen Abonnement
Feature | |
---|---|
Type | Service |
Versie | 1.0.0 |
Groep | Notificatie |
Gepubliceerd |
|
Delta | Initiële versie van feature. |
Feature | Versie | Dependency | Aanbieder | Afnemer |
---|---|---|---|---|
1.0.0 | * | * | ||
1.0.0 | 1.0 |
Deze interactie is gebaseerd op de FHIR conditional update interactie:
PUT [base]/Subscription?[parameters]
Ondersteunde parameters
zijn:
identifier (de waarde van extension http://vzvz.nl/fhir/StructureDefinition/aorta-subscription-identifier van de Subscription, ofwel het abonnement-id)
Voorbeeld:
PUT [base]/Subscription?identifier=<system>|<value>
{
"resourceType": "Subscription",
...
}
HTTP statuscodes die kunnen worden geretourneerd zijn:
Stap | Omschrijving | Uitkomst |
---|---|---|
1 | Het systeem ontvangt een verzoek en start de verwerking. | Gevraagde versie niet ondersteund statuscode 406 Not Acceptable |
Het systeem genereert de vereiste foutresponse en keert terug naar de exit stap van de main flow. | ||
Gehanteerde versie niet ondersteund statuscode 415 Unsupported Media Type | ||
Het systeem genereert de vereiste foutresponse en keert terug naar de exit stap van de main flow. | ||
2 | AOF.UC-COM.AUT.100.v1 Het systeem controleert of er een access_token is toegevoegd aan het request. | Ontbrekend token statuscode 401 Unauthorized
|
Het systeem genereert de vereiste foutresponse en keert terug naar de exit stap van de main flow. | ||
3 | AOF.UC-COM.AUT.200.v1 Het systeem toetst of het ontvangen token een geldig AORTA access_token is op de wijze zoals beschreven in Toetsing AORTA access_token. | Ongeldig token statuscode 401 Unauthorized
|
Het systeem genereert de vereiste foutresponse en keert terug naar de exit stap van de main flow. | ||
4 | AOF.UC-COM.VAL.100.v1 Het systeem toetst of het verzoek voldoet aan de interface specificatie. | Ongeldig FHIR-verzoek statuscode 400 Bad Request
|
Het systeem genereert de vereiste foutresponse en keert terug naar de exit stap van de main flow. | ||
5 | Het systeem toets of er inderdaad een abonnement bestaat met de identifier, zoals doorgegeven in het request. | Abonnement bestaat niet statuscode 422 Unprocessable Entity
Het systeem kan niet eenduidig vaststellen welke entry wordt bedoeld statuscode 412
|
Het systeem genereert de vereiste foutresponse en keert terug naar de exit stap van de main flow. | ||
6 | Het systeem toetst of het BSN in de patient claim van het AORTA access_token overeenkomt met het BSN in het criterium van het bestaande abonnement. | BSN in criterium komt niet overeen met token statuscode 403 Forbidden
|
Het systeem genereert de vereiste foutresponse en keert terug naar de exit stap van de main flow. | ||
7 | Het systeem toetst of de wijziging van het abonnement is toegestaan:
| Wijziging niet toegestaan statuscode 403 Forbidden
|
Het systeem genereert de vereiste foutresponse en keert terug naar de exit stap van de main flow. | ||
8 | Het systeem verwerkt de wijziging. | |
9 <exit> | Het systeem retourneert een response naar de primaire actor. | Verwerking succesvol statuscode 200 OK |
Beëindigen Abonnement
Feature | |
---|---|
Type | Service |
Versie | 1.0.0 |
Groep | Notificatie |
Gepubliceerd |
|
Delta | Initiële versie van feature. |
Feature | Versie | Dependency | Aanbieder | Afnemer |
---|---|---|---|---|
1.0.0 | * | * | ||
1.0.0 | 1.0 |
Deze interactie is gebaseerd op de FHIR conditional delete interactie:
DELETE [base]/Subscription?[parameters]
Voorbeeld:
DELETE [base]/Subscription?identifier=<system>|<value>
HTTP statuscodes die kunnen worden geretourneerd zijn:
Stap | Omschrijving | Uitkomst |
---|---|---|
1 | Het systeem ontvangt een verzoek en start de verwerking. | Gevraagde versie niet ondersteund statuscode 406 Not Acceptable |
Het systeem genereert de vereiste foutresponse en keert terug naar de exit stap van de main flow. | ||
2 | AOF.UC-COM.AUT.100.v1 Het systeem controleert of er een access_token is toegevoegd aan het request. | Ontbrekend token statuscode 401 Unauthorized
|
Het systeem genereert de vereiste foutresponse en keert terug naar de exit stap van de main flow. | ||
3 | AOF.UC-COM.AUT.200.v1 Het systeem toetst of het ontvangen token een geldig AORTA access_token is op de wijze zoals beschreven in Toetsing AORTA access_token. | Ongeldig token statuscode 401 Unauthorized
|
Het systeem genereert de vereiste foutresponse en keert terug naar de exit stap van de main flow. | ||
4 | AOF.UC-COM.VAL.100.v1 Het systeem toetst of het verzoek voldoet aan de interface specificatie. | Ongeldig FHIR-verzoek statuscode 400 Bad Request
|
Het systeem genereert de vereiste foutresponse en keert terug naar de exit stap van de main flow. | ||
5 | Het systeem toetst of er inderdaad een abonnement bestaat met de identifier, zoals doorgegeven in het request. | Abonnement bestaat niet statuscode 422 Unprocessable Entity
Het systeem kan niet eenduidig vaststellen welke entry wordt bedoeld statuscode 412
|
Het systeem genereert de vereiste foutresponse en keert terug naar de exit stap van de main flow. | ||
6 | Het systeem toetst of de beëindiging van het abonnement is toegestaan:
| Registratie niet toegestaan statuscode 403 Forbidden
|
Het systeem genereert de vereiste foutresponse en keert terug naar de exit stap van de main flow. | ||
7 | Het systeem beëindigt het abonnement. | |
8 <exit> | Het systeem retourneert een response naar de primaire actor. | Verwerking succesvol statuscode 200 OK |
Functionele datamodel van een Abonnement
Het functionele datamodel van een Abonnement, en de mapping ervan naar FHIR is beschreven in onderstaande tabel.
Element/attribuut | Cardinaliteit | Toelichting | |
---|---|---|---|
Functioneel | FHIR | ||
abonnement-id | extension: aorta-subscription-identifier | 1..1 | Uniek ID van het abonnement |
- | id | 1..1 | Logical ID van de FHIR Subscription |
- | reason | 1..1 | Reden van creatie Abonnement. |
abonnee-organisatie-id | extension: aorta-subscription-managingEntity:Organisation.XXX | 1..1 | URA of organisatie-id van abonnee |
abonnee-applicatie-id | ?? | 1..1 | appID van GBx-applicatie van de abonnee |
aanvrager-id | ?? | 0..1 | Slechts aanwezig wanneer de aanvrager een patiënt is. BSN van patiënt (abonnee) |
aanvrager-functie | ?? | 1..1 | rolcode abonnee (UZI-rolcode of “P”) Deze rolcode bepaalt welke signalen het systeem ontvangt als gevolg van een abonnement. Dit moet namelijk passen binnen de autorisaties van de aanvrager-functie. |
gebeurtenis-type | criteria (hoe exact?) | 1..1 | Mogelijke typen:
|
gebeurtenis-subtype | criteria (hoe exact?) | 0..1 | Verplicht bij abonnement op wijzigingen in VWI/ACT:
Verplicht bij abonnement op wijzigingen in de LOG als gevolg van opvragen/sturen patiëntgegevens:
De combinatie van contextcode en rolcode is in de SDS gekoppeld aan een set van bouwsteentypen/gegevenssoorten. |
gebeurtenis-subject | criteria | 1..1 | BSN van patiënt
|
einddatum | end | 1..1 | Moet vallen binnen een vastgestelde maximum duur van een abonnement. |
TODO
Gebeurtenis Afhandeling Interface
Vooralsnog geen aanpassingen t.o.v. bestaande situatie.