Use Cases Resource Broker VnC

Overzicht Resource Broker VnC

Onderstaande figuur toont een overzicht van de interfaces, services en functies van de Resource Broker VnC component. Resource Broker VnC is verantwoordelijk voor initiatie van interacties bij AORTA Resource Servers. Resource Broker VnC handelt altijd op verzoek van een Resource Broker *-in component (bijv. RB ZA-in of RB MedMij-in).

De services zijn toegankelijk via een geboden interface en worden beschreven in de vorm van use cases. Een service wordt altijd vervult middels één of meerdere applicatiefuncties, bijvoorbeeld Verzending & Consolidatie. De RB VnC component maakt zelf ook gebruik van een aantal interfaces, bijvoorbeeld van de AORTA FHIR Resource Interface.

Opvragen AORTA CapabilityStatement

Primaire actor	AORTA-beheerder
Systeem	Verzending & Consolidatie (beheertool)
Secundaire actor	Resource Server, Resource Broker GTK
Code	AOF.UC.VNC.100.v1

Pre-condities

De secundaire actor is aangesloten op het systeem.

Triggers

De primaire actor wil de operationele status van een secundaire actor toetsen.

Main flow

Stap

Omschrijving

Uitzondering(en)

1

De primaire actor kiest de optie om de operationele status van een secundaire actor te toetsen.

2

Het systeem initieert, voor alle door secundaire actor ondersteunde FHIR-versions, een FHIR capabilities operation bij de secundaire actor.

3

<exit>

Het systeem ontvangt en verwerkt een response.

Postcondities

Het systeem heeft het verzoek op de juiste wijze verwerkt en heeft een daarbij passende response geretourneerd.

Verzenden & Consolideren benodigde interacties

Primaire actor	Resource Broker MedMij-in, Resource Broker ZA-in, Resource Broker v3-in, Resource Broker GTK
Systeem	Verzending & Consolidatie
Secundaire actor	Transformatie Server, Resource Server, Resource Broker GTK
Code	AOF.UC.VNC.200.v8
Realiseert Feature	Initiëren reguliere FHIR-interactie, Uitvoeren get-aorta-data, Uitvoeren push-aorta-data

Pre-condities

De secundaire actor is aangesloten op het systeem.

Triggers

De primaire actor heeft een FHIR-interactie ontvangen, die moet worden uitgezet naar één of meerdere secundaire actoren.

Main flow

AOF.UCe.VAL.100.v1 - Toetsing type content		Uitkomst
Stap	Omschrijving	Uitkomst
i	Het systeem ontvangt een verzoek en start de verwerking. Het systeem toetst of het gevraagde type content (Accept header) en het gehanteerde type content (Content-Type header) worden ondersteund. NB. wanneer het verzoek wordt ontvangen van een component van VZVZ, dan hoeft geen toets op type content te worden uitgevoerd.	Gevraagd type content niet ondersteund statuscode 406 Not Acceptable
		Gehanteerd type content niet ondersteund statuscode 415 Unsupported Media Type
		Het systeem genereert de vereiste response en gaat verder met de exit stap van de main flow.

AOF.UCe.VAL.250.v1 - Toetsing van een intern RB-request		Uitkomst
Stap	Omschrijving	Uitkomst
i	Het systeem controleert of alle vereiste tokens zijn toegevoegd aan het request	Ontbrekend token statuscode 401 Unauthorized In deze situatie wordt geen nadere informatie over de opgetreden fout geretourneerd. In deze situatie wordt, conform RFC 6750, ook een WWW-Authenticate HTTP response header met als auth-scheme "Bearer", maar zonder foutcode of nadere informatie omtrent de fout geretourneerd. Indien de `WWW-Authenticate` HTTP response header wordt geproduceerd door de resource broker, dan wordt een `realm` attribuut met waarde "`aorta`" toegevoegd.
i		Het systeem genereert de vereiste response en gaat verder met de exit stap van de main flow.
ii	Het systeem controleert de geldigheid van de meegezonden, van toepassing zijnde, tokens AORTA access_token, zoals omschreven in de sectie "Toetsing AORTA access_token". DigiD Authenticatietoken, zoals omschreven in de sectie “Toetsing DigiD Authenticatietoken”. NB. wanneer het verzoek via een intern netwerk wordt ontvangen, en van een component van VZVZ, dan hoeft deze toets niet te worden uitgevoerd. Welke tokens van toepassing zijn is beschreven in de interface specificaties die horen bij deze use case.	Ongeldig token statuscode 401 Unauthorized In deze situatie wordt, conform RFC 6750, ook een `WWW-Authenticate` HTTP response header met als auth-scheme "`Bearer`" en een `error` attribuut met waarde "`invalid_token`" geretourneerd. Indien de `WWW-Authenticate` HTTP response header wordt geproduceerd door de resource broker, dan wordt een `realm` attribuut met waarde "`aorta`" toegevoegd. In deze situatie mag daarnaast ook een OperationOutcome met issue.code "`security`" worden geretourneerd.
ii		Het systeem genereert de vereiste response en gaat verder met de exit stap van de main flow.
iii	Indien van toepassing: Het systeem controleert de samenhang tussen het AORTA access_token en het DigiD authenticatietoken, zoals omschreven in de de sectie "Toetsing van samenhang tussen tokens". NB. wanneer het verzoek via een intern netwerk wordt ontvangen, en van een component van VZVZ, dan hoeft deze toets niet te worden uitgevoerd. Welke tokens van toepassing zijn is beschreven in de interface specificaties die horen bij deze use case.	Ongeldig token statuscode 401 Unauthorized In deze situatie wordt, conform RFC 6750, ook een `WWW-Authenticate` HTTP response header met als auth-scheme "`Bearer`" en een `error` attribuut met waarde "`invalid_token`" geretourneerd. Indien de `WWW-Authenticate` HTTP response header wordt geproduceerd door de resource broker, dan wordt een `realm` attribuut met waarde "`aorta`" toegevoegd. In deze situatie mag daarnaast ook een OperationOutcome met issue.code "`security`" worden geretourneerd.
iii		Het systeem genereert de vereiste response en gaat verder met de exit stap van de main flow.

Stap	Omschrijving	Uitkomst
1	Indien een get-aorta-data request OF een FHIR-search interactie wordt ontvangen die is gericht aan een zorgaanbieder (URA): Het systeem achterhaald, m.b.v. de AORTA Token Interface (middels een AORTA Token Request), welke interactie(s) moet(en) worden geïnitieerd, en bij welke GBx-applicatie(s).	Interactie(s) en/of GBx-applicaties kunnen niet worden vastgesteld statuscode 500 Internal Server Error
		Het systeem genereert de vereiste response en gaat verder met de exit stap van de main flow.
		Géén GBx-applicatie gevonden Het systeem gaat direct naar stap 5 (samenstellen van response) van de main flow.
2	Voor elke GBx-applicatie, waar één of meerdere interacties moeten worden geïnitieerd, worden voor iedere te initieren interactie de volgende stappen doorlopen: Het systeem stelt, o.b.v. het, door de primaire actor, gevraagde protocol van de response en het al dan niet aanwezig zijn van een transformationId in de _vrb_ter_scope claim van het AORTA access_token, vast of een HL7-v3, of een HL7-FHIR interactie moet worden uitgestuurd, en of een transformatie moet worden uitgevoerd (zie ook de toelichtingen “Opbouwen van queries“ en “Vaststellen van het te hanteren protocol”). Het systeem stelt vast naar welke endpoint de interactie dient te worden doorgestuurd, zoals omschreven in de toelichting "Bepalen van de ontvangende resource servers". Het systeem initieert de vereiste interactie. Indien een transformatie is vereist, en de te initieren interactie is géén v3-query, een FHIR-read of een FHIR-search, dan initieert het systeem hiervoor eerst de use case Transformeer content middels de Transformatie Interface	Ongeldige adressering Er is bijvoorbeeld een probleem met het FQDN dat is opgenomen in de audience van het AORTA access_token. Het systeem voegt een OperationOutcome toe (issue.severity=”warning”, issue.code "processing") met daarin informatie over de reden. statuscode 500 Internal Server Error
		Het systeem gaat verder met de volgende interactie of GBx-applicatie.
		Transformatie niet geslaagd statuscode 500 Internal Server Error
		Het systeem genereert de vereiste foutresponse en gaat verder met de volgende interactie of GBx-applicatie.
		Interactie kon niet worden geïnitieerd Er is bijvoorbeeld een probleem met de scope van het AORTA access_token, waardoor het systeem een interactie niet kan opbouwen. Het systeem voegt een OperationOutcome toe (issue.severity=”warning”, issue.code "processing") met daarin informatie over de reden. statuscode 500 Internal Server Error
		Het systeem gaat verder met de volgende interactie of GBx-applicatie.
3	Voor elke ontvangen response worden de volgende stappen doorlopen: Het systeem toetst of de response géén attachment met daarin malafide inhoud bevat (zie FHIR security, attachments). Indien een response wordt ontvangen en een transformatie moet worden uitgevoerd, dan initieert het systeem de use case Transformeer content middels de Transformatie Interface. In de toelichting “Transformatie van FHIR results naar v3-responses” is omschreven hoe moet worden omgegaan met ontvangen HTTP statuscodes, headers en OperationOutcomes van een FHIR Resource Server. Indien (eventueel na transformatie) een FHIR searchset Bundle is verkregen dan voegt het systeem er een Provenance resource aan toe, zodat voor iedere opgeleverde resource instance in de Bundle duidelijk is, van welk bronsysteem deze werd verkregen. Indien geen (tijdige) response wordt ontvangen, dan worden bovenstaand stappen niet doorlopen en genereert het systeem zelfstandig de vereiste foutresponse.	Malafide inhoud Het systeem logt de gebeurtenis, negeert de betreffende response en gaat verder met de volgende interactie of GBx-applicatie.
		Geen (tijdig) antwoord van GBx-applicatie statuscode 504 Gateway Timeout
		Transformatie niet geslaagd statuscode 500 Internal Server Error
		Het systeem genereert de vereiste foutresponse en gaat verder met de volgende interactie of GBx-applicatie.
4	Het systeem consolideert alle ontvangen responses, zoals omschreven in de toelichting "Consolideren van de responses naar één FHIR-result" of, wanneer één v3-response moet worden opgeleverd, in AORTA documentatie voor v3-uitwisseling.
5	Bij opleveren van een FHIR-result: het systeem overschrijft eventuele URL's in het opgeleverde resultaat Absolute URL's in Bundle entries (fullUrl's, references en link elementen van het type “self”, “first”, “next”, “previous” en “last”) dienen te worden aangepast conform het volgende formaat: `<base endpointadres Resource Broker XXX-in>/<appID>/<type>/<id>`. DocumentReference.content.attachment.url dient, zowel voor absolute URL’s als voor relatieve URL’s, te worden aangepast conform het volgende formaat: `<base endpointadres Resource Broker XXX-in>/<appID>/<type>/<id>`. URL in Location header dient te worden aangepast conform het volgende formaat: `<base endpointadres Resource Broker XXX-in>/<appID>/<type>/<id>/_history/[vid]` waarbij `<appID>` het applicatie-id (zonder root OID) bevat van het bronsysteem. Het in te vullen `appID` kan worden bepaald door het opgeleverde base endpointadres in de Bundle, te vergelijken met het FQDN van iedere GBZ-applicatie, die eerder in de flow werd betrokken bij de verwerking van het resource request. De juiste Resource Broker XXX-in wordt bepaald o.b.v. de inhoud van de vrb_client_id claim in het AORTA access_token. De base URL die hierbij hoort wordt verkregen uit het AORTA Stelseltoken.
6 <exit>	Het systeem retourneert een response naar de primaire actor.	Zie de toelichting "Consolideren van de responses naar één FHIR-result".
		Verwerking succesvol statuscode 200 OK Wanneer een geldige FHIR zoekparameter wordt ontvangen die niet wordt ondersteund, dan wordt een OperationOutcome met issue.code "`not supported`" opgenomen in het resultaat. Wanneer een ongeldige FHIR zoekparameter wordt ontvangen, dan wordt een OperationOutcome met issue.code "`invalid`" en de van toepassing zijnde issue.details geretourneerd opgenomen in het resultaat. Wanneer een FHIR zoekparameter een geldige waarde bevat die niet wordt ondersteund, dan wordt een OperationOutcome met issue.code "`not supported`" en de van toepassing zijnde issue.details geretourneerd. Wanneer een optionele FHIR zoekparameter een ongeldige waarde heeft, dan wordt een OperationOutcome met issue.code "`value`" en de van toepassing zijnde issue.details geretourneerd. Voor bovenstaande criteria geldt dat ze voor FHIR-interacties die worden vertaald van naar HL7v3: worden getoetst in de resource broker; voor FHIR-interacties die niet worden vertaald: worden getoetst in de resource server. Wanneer een feitelijk, door Resource Server, geretourneerde statuscode moet worden toegevoegd aan een response, dan wordt dit gedaan in een OperationOutcome met: voor statuscode 2xx: issue.severity=information, issue.code=processing. en issue.diagnostics="<appID van resource server>:<statuscode van resource server>", OF anders: issue.severity=warning, issue.code=processing. en issue.diagnostics="<appID van resource server>:<statuscode van resource server>".
		Verwerking succesvol - resource instance gecreëerd statuscode 201 Created

Post-condities

Het systeem heeft het verzoek op de juiste wijze verwerkt en heeft een daarbij passende response geretourneerd.

Het systeem heeft ontvangen request en de geretourneerde response gelogd, zoals beschreven in de Toelichting Logging.

Het systeem heeft van het ontvangen request, de volgende attributen gelogd:

datum en tijd van ontvangst
request-id
initial-request-id
sender-id
- role-id wanneer de sender van het request een VZVZ component is, en de aanroep niet via TLS geschiedt
- common name wanneer de aanroep via TLS geschiedt

==

Het systeem heeft voor ieder uitgaand request, dat bij het doorlopen van de use case werd verzonden, de volgende attributen gelogd:

datum en tijd van verzending
request-id
initial-request-id
receiver-id
- role-id wanneer de receiver van het request een VZVZ component is, en de aanroep niet via HTTP geschiedt
- FQDN wanneer de aanroep via HTTP geschiedt

Aanvullend daarop heeft het systeem van het ontvangen request de volgende attributen gelogd:

jti van het ontvangen AORTA access_token

Het systeem heeft van de geretourneerde response, de volgende attributen gelogd:

datum en tijd van response
request-id van het bijbehorende request
initial-request-id van het bijbehorende request
receiver-id
- role-id wanneer de receiver van de response een VZVZ component is, en de aanroep niet via TLS geschiedt
- common name wanneer de aanroep via TLS geschiedt
HTTP statuscode en eventueel geretourneerde foutinformatie

==

Het systeem heeft voor iedere response, die bij het doorlopen van de use case werd ontvangen, de volgende attributen gelogd:

datum en tijd van response
request-id van het bijbehorende request
initial-request-id van het bijbehorende request
sender-id
- role-id wanneer de sender van de response een VZVZ component is, en de aanroep niet via TLS geschiedt
- common name wanneer de aanroep via TLS geschiedt
HTTP statuscode en eventueel geretourneerde foutinformatie

Toelichtingen

Bepalen van de ontvangende resource servers

Het appID en de FQDN van de ontvangende GBZ-applicatie (resource server) zijn opgenomen in de aud claim van het AORTA access_token.

Wanneer het systeem een versie 1 AORTA access_token ontvangt, dan is het FQDN niet opgenomen in de aud claim, maar dient het juiste FQDN m.b.v. Feature getApplication(s) te worden bepaald.

Opbouwen van queries

Het systeem bepaalt, m.b.v. de interactietabel, welk van de ontvangen interactie-id’s in de _vrb_ter_scope van het AORTA access_token van toepassing is op het uit te sturen request, en stelt vast dat het gaat om een “pull” interactie.

Indien voor de betreffende interactie in de _vrb_ter_scope van het access_token een transformation-id is opgenomen, dan

kiest het systeem, o.b.v. de combinatie van het interactie-id en het transformation-id de juiste interactie-template
stelt het systeem, m.b.v. de gekozen interactie-template, de ontvangen scope in het access_token, en de eventueel van client ontvangen aanvullende zoekparameters, de uit te sturen v3-query op

Let op: de mapping van FHIR parameternamen naar v3 parameternamen ligt besloten in de interactie-template. Deze mapping kan niet worden gehaald uit de interactietabel, omdat de interactietabel niet alle mogelijke zoekparameters voor iedere interactie bevat. De mapping kan ook niet worden gehaald uit de SDS, omdat eventueel door client toegevoegde aanvullende zoekparameters, niet zijn opgenomen in de scope van het access_token (het vullen van de scope met v3 parameternamen lukt daardoor niet). M.b.t. v3-bouwsteen-queries bestaat er een generieke template, die kan worden gebruikt voor alle bouwstenen, maar bestaan ook templates die bouwsteen-specifiek zijn.

Indien voor de betreffende interactie in de _vrb_ter_scope van het access_token géén transformation-id is opgenomen, dan

stelt het systeem, m.b.v. de ontvangen scope in het access_token, en de eventueel van client ontvangen aanvullende zoekparameters, de uit te sturen FHIR-search interactie op

Vaststellen van het te hanteren protocol

Het systeem bepaalt, m.b.v. de interactietabel, welk van de ontvangen interactie-id’s in de _vrb_ter_scope van het AORTA access_token van toepassing is op het uit te sturen request.

Indien voor de betreffende interactie in de _vrb_ter_scope van het access_token een transformation-id is opgenomen, dan

bepaalt het systeem, m.b.v. de Transformatie Server Metadata en het transformatie-id, het protocol van de uit te sturen interactie

Indien voor de betreffende interactie in de _vrb_ter_scope van het access_token géén transformation-id is opgenomen, dan

bepaalt het systeem, m.b.v. de interactietabel, het protocol van de uit te sturen interactie.

Toevoegen Provenance resource

Het systeem voegt in een aantal situaties een Provenance resource toe aan een bericht om aan te geven van welk systeem, en van welke organisatie de gegevens in het bericht afkomstig zijn:

Bij opleveren van een searchset Bundle met resultaten van een opvraag.
Bij doorsturen van een batch/transaction Bundle met gegevens die worden gestuurd.

Het FHIR-profiel van de Provenance resource instance die wordt toegevoegd aan een Bundle is hieronder beschreven. Deze Provenance resource wijst naar alle resource instances in de Bundle, dus ook naar eventuele OperationOutcome resource instances. Per bronsysteem (appID) is er dus sprake van één Provenance instance.

Bij de verwijzing van de Provenance resource naar de resource instances in de Bundle kunnen zich een aantal situaties voordoen:

De resource instance is voorzien van een fullUrl - in deze situatie wordt de verwijzing gemaakt m.b.v. de beschikbare fullUrl.
De resource instance is niet voorzien van een fullUrl - in deze situatie wordt een UUID-type fullUrl toegevoegd aan de resource instance, en wordt de verwijzing gemaakt m.b.v. deze fullUrl.

De URA en het appID van het bronsysteem zijn opgenomen in het AORTA access_token:

Bij opvragingen zijn deze attributen opgenomen in de audience claim van het access_token. De URA die hoort bij het appID wordt, indien deze niet is opgenomen in het AORTA access_token, via de APR API verkregen uit het APR.
Bij pushberichten zijn deze attributen opgenomen in de _vrb. _vrb_ion en in de vrb_client_id van het access_token.

Feature	aorta-provenance
Type	Subfeature
Versie	1.0.0
Groep	FHIR-profielen
Gepubliceerd	19 Oct 2023
Delta	Initiële versie van feature.

Voorbeelden:

Consolideren van de responses naar één FHIR-result

Resource Broker VnC kan een interactie, eventueel na transformatie, uit moeten zetten bij één GBZ-applicatie of bij meerdere GBZ-applicaties. De volgende interacties worden altijd uitgezet bij slechts één GBZ-applicatie:

applicatie-search (gericht aan appID),
create,
update, $is-allowed.

Een organisatie-search (gericht aan URA) en get-aorta-data (gericht aan appID, URA of gespreid) kunnen leiden tot een bevraging van meerdere GBZ-applicaties.

Een FHIR client, zoals een DVP Server of een Initiërende GBx-applicatie, wordt d.m.v. HTTP statuscodes en FHIR OperationOutcomes voorzien van informatie omtrent de afhandeling van verzonden requests. Een FHIR client is hierbij vooral geïnteresseerd informatie over de uiteindelijke afhandeling van haar requests, d.w.z. het daadwerkelijke resultaat. Bijv. een standaard FHIR resource client verwacht als antwoord op een FHIR-create een HTTP 201 statuscode die aangeeft dat de resource succesvol is gecreëerd in een resource server. De door RB VnC geretourneerde statuscode dient derhalve informatie te verschaffen die zo dicht als mogelijk ligt bij het daadwerkelijke resultaat.

Wanneer een interactie wordt uitgezet bij één GBZ-applicatie, dan wordt de statuscode die RB VnC retourneert volledig gebaseerd op de response van de betreffende GBZ-applicatie.
Wanneer een interactie wordt uitgezet bij meerdere GBZ-applicaties, dan wordt statuscode van RB VnC gebaseerd op alle ontvangen responses.

Onderstaande regels gelden zowel voor ontvangen statuscodes in de HTTP-response van individuele interacties, als voor geïncludeerde statuscodes in batch-response of transaction-response Bundles bij sets van interacties.

Algemeen geldende regels voor alle interacties:

Eventueel ontvangen, en na transformatie verkregen, OperationOutcomes worden altijd geïncludeerd in de geconsolideerde response. Voor een interactie die is uitgezet bij meerdere GBZ-applicaties wordt hier ook het appID aan toegevoegd.
Wanneer (eventueel na transformatie) een FHIR searchset Bundle wordt verkregen, met een absolute URL in een fullUrl, reference of link element van het type “self”, “first”, “next”, “previous” of “last”, dan dient de FQDN van deze absolute URL overeen te komen met de FQDN van de Resource Server (GBZ-applicatie) die werd bevraagd. Indien dit niet het geval is, dan dient als statuscode van deze response 500 te worden gehanteerd en wordt een OperationOutcome met issue.code "business-rule” en issue.diagnostics “resultaat bevat URL’s die afwijken van FQDN van Resource Server”. Indien de interactie was uitgezet bij meerdere GBZ-applicaties, dan wordt hier ook het appID aan toegevoegd.

Algemeen geldende regels voor alle interacties, uitgezonderd $get-aorta-data:

Wanneer de statuscode die wordt ontvangen van een GBZ-applicatie, afwijkt van de uiteindelijk door RB VnC te retourneren statuscode, dan voegt RB VnC aan de response, een OperationOutcome toe met daarin het appID van de betreffende GBZ-applicatie en de statuscode die daadwerkelijk werd ontvangen van deze GBZ-applicatie.

Vertaling van v3-response naar FHIR-response:

Bij ontvangst van een statuscodes anders dan 200 en/of bij ontvangst van een SOAP-fault, wijzigt RB VnC (d.w.z. de XSG namens RB VnC) de statuscode naar 500 en genereert hierbij een v3-foutcode RTEDEST. De Transformatie Server zet de v3-foutcode vervolgens om in een FHIR OperationOutcome.
RB VnC includeert alle, na transformatie verkregen OperationOutcomes, in de geconsolideerde response. Vervolgens wordt de te hanteren statuscode voor deze response als volgt vastgesteld:
1. wanneer het resultaat na transformatie een OperationOutcome bevat met issue.code "suppressed", dan dient als statuscode van deze response 403 te worden gehanteerd..
2. wanneer het resultaat na transformatie tenminste één OperationOutcome oplevert, en geen OperationOutcome met issue.code "suppressed" bevat, en géén reguliere resource-instanties bevat, dan dient als statuscode van deze response 500 te worden gehanteerd.
3. in alle overige gevallen wordt een 2xx gehanteerd, d.w.z.
  1. wanneer de response een antwoord is op een FHIR-create interactie, dan wordt de statuscode 201
  2. wanneer de response een antwoord is op een ander type FHIR interactie, dan wordt de statuscode 200

Afhandeling van (na transformatie verkregen) FHIR-response bij een FHIR-interactie die is uitgezet naar één GBZ-applicatie:

RB VnC retourneert de statuscode die het ontvangt, inclusief ontvangen OperationOutcomes en inclusief ontvangen AORTA-Version , WWW-Authenticate en voor FHIR relevante HTTP response headers (bijv. Location). Uitzonderingen:
1. wanneer een 4xx statuscode wordt ontvangen, waarvan zeker is dat ze wordt veroorzaakt door RB VnC zelf, dan dient als statuscode van deze response 500 te worden gehanteerd. Dit geldt voor statuscodes 400 en 401.
2. wanneer een 5xx statuscode wordt ontvangen, dan krijgt de te retourneren statuscode altijd de waarde 500.
Wanneer de response een OperationOutcome bevat met issue.code "suppressed", en een statuscode 403 wordt geretourneerd, dan dient ook een WWW-Authenticate HTTP response header, met als auth-scheme "Bearer" en een error attribuut met waarde "access_denied", te worden geretourneerd.

Afhandeling van (na transformatie verkregen) FHIR-responses bij ontvangen FHIR-search die is doorgezet naar meerdere GBZ-applicaties (organisatie-search):

Indien gegevens zijn opgeleverd: 200 gaat boven 4xx (zodat gegevens die wel werden verkregen kunnen worden geretourneerd)
Indien geen gegevens zijn opgeleverd: 4xx gaat boven 200 (nu melden aan client dat zij een fout heeft gemaakt)
2xx gaat boven 5xx (zodat eventueel verkregen gegevens kunnen worden geretourneerd)
4xx gaat boven 5xx (zodat de client weet dat zij een fout heeft gemaakt)
Wanneer verschillende 4xx codes worden ontvangen, dan wordt dit beschouwd als een fout, en wordt de statuscode 500 geretourneerd
Wanneer alle GBZ-applicaties een statuscode 5xx retourneren, dan wordt als statuscode 500 geretourneerd, ongeacht of de ontvangen statuscodes allemaal gelijk zijn aan elkaar of niet
Wanneer de geconsolideerde response een OperationOutcome bevat met issue.code "suppressed", en een statuscode 403 wordt geretourneerd, dan dient ook een WWW-Authenticate HTTP response header, met als auth-scheme "Bearer" en een error attribuut met waarde "access_denied", te worden geretourneerd.

Afhandeling van (na transformatie verkregen) FHIR-responses bij ontvangen $get-aorta-data die is vertaald naar één of meerdere FHIR-search interacties gericht aan één of meerdere GBZ-applicaties:

De statuscode die wordt ontvangen van een GBZ-applicatie wordt door RB VnC, middels een OperationOutcome met daarin het appID van de betreffende GBZ-applicatie en de statuscode die werd ontvangen, toegevoegd aan de response.
Ontvangst van een 4xx wordt beschouwd als een succesvol uitgevoerde search bij de betreffende GBZ-applicatie.
Ontvangst van een 5xx wordt beschouwd als een succesvol uitgevoerde search bij de betreffende GBZ-applicatie.
Een timeout of verbindingsfout wordt beschouwd als een succesvol uitgevoerde search bij de betreffende GBZ-applicatie.
Indien tenminste één search als succesvol kon worden beschouwd, dan wordt een 200 geretourneerd.
Indien geen enkele search als succesvol kon worden beschouwd dan wordt een 500 geretourneerd.

Wanneer een feitelijk, door resource server, geretourneerde statuscode moet worden toegevoegd aan een response, dan wordt dit gedaan in een OperationOutcome met:

voor statuscode 2xx: issue.severity=information, issue.code=processing. en issue.diagnostics="<appID van resource server>:<statuscode van resource server>", OF
anders: issue.severity=warning, issue.code=processing. en issue.diagnostics="<appID van resource server>:<statuscode van resource server>".

Search-results die worden ontvangen dienen als volgt te worden geconsolideerd tot één search-result:

Het systeem stopt het alle Entries die zijn ontvangen, in één nieuwe Bundle en retourneert deze ene Bundle. Naast de ontvangen Entries bevat de te retourneren Bundle de volgende attributen:
1. type = "searchset"
2. total (het totaal aantal Entries dat conform de FHIR specificaties moet worden meegeteld)

Voorbeelden voor consolidatie van statuscodes bij opvragen van gegevens zijn opgenomen in onderstaande tabel.

#	RB VnC ontvangt				RB VnC retourneert (bij FHIR-search)		RB VnC retourneert (bij get-aorta-data)
#	GBZ-applicatie 1 (v3)	GBZ-applicatie 2 (v3)	GBZ-applicatie 3 (FHIR)	GBZ-applicatie 4 (FHIR)	statuscode	extra gegevens	statuscode	extra gegevens
1	200 (leeg)	n.v.t.	n.v.t.	n.v.t.	200	-	200	Outcome (1:200)
2	200 + PATLFT (=403)	n.v.t.	n.v.t.	n.v.t.	403	Outcome (suppressed) + WWW-Authenticate	200	Outcome (1:403)
3	n.v.t.	n.v.t.	406	n.v.t.	406	-	200	Outcome (3:406)
4	n.v.t.	n.v.t.	504	n.v.t.	500	Outcome (3:504)	200	Outcome (3:504)
5	200	200	200	200	200 (=organisatie-search: wordt nog niet ondersteund)	-	200	Outcome (1:200) + Outcome (2:200) + Outcome (3:200) + Outcome (4:200)
6	200	200 + PATLFT (=403)	200	200	200 (=organisatie-search: wordt nog niet ondersteund)	Outcome (2:403)	200	Outcome (1:200) + Outcome (2:403) + Outcome (3:200) + Outcome (4:200)
7	200 (leeg)	200 + PATLFT (=403)	200 (leeg)	n.v.t.	403 (=organisatie-search: wordt nog niet ondersteund)	Outcome (1:200) + Outcome (3:200)	200	Outcome (1:200) + Outcome (2:403) + Outcome (3:200)
8	200 (leeg)	n.v.t.	200 (leeg) + Outcome (not supported)	n.v.t.	200 (=organisatie-search: wordt nog niet ondersteund)	Outcome (not supported)	200	Outcome (1:200) + Outcome (3:200) + Outcome (3:not supported)
9	200 (leeg)	n.v.t.	406	n.v.t.	406 (=organisatie-search: wordt nog niet ondersteund)	Outcome( 1:200)	200	Outcome (1:200) + Outcome (3:406)
10	200	n.v.t.	406	n.v.t.	200 (=organisatie-search: wordt nog niet ondersteund)	Outcome (3:406)	200	Outcome (1:200) + Outcome (3:406)
11	401	n.v.t.	401	n.v.t.	500 (=organisatie-search: wordt nog niet ondersteund)	Outcome (1:401) + Outcome (3:401)	200	Outcome (1:401) + Outcome (3:401)
12	403 + Outcome (suppressed)	n.v.t.	403	n.v.t.	403 (=organisatie-search: wordt nog niet ondersteund)	Outcome (suppressed) + WWW-Authenticate	200	Outcome (1:403) + Outcome (3:403)
13	401	n.v.t.	403	n.v.t.	500 (=organisatie-search: wordt nog niet ondersteund)	Outcome (1:401) + Outcome (3:403)	200	Outcome (1:401) + Outcome (3:403)
14	500	n.v.t.	511	n.v.t.	500 (=organisatie-search: wordt nog niet ondersteund)	Outcome (3:511)	200	Outcome (1:500) + Outcome (3:511)
15	200	n.v.t.	500	n.v.t.	200 (=organisatie-search: wordt nog niet ondersteund)	Outcome (3:500)	200	Outcome (1:200) + Outcome (3:500)
16	200 (leeg)	n.v.t.	500	n.v.t.	200 (=organisatie-search: wordt nog niet ondersteund)	Outcome (3:500)	200	Outcome (1:200) + Outcome (3:500)

Logging

Het systeem logt alle (FHIR) interacties die het verwerkt in een berichtenlog. Deze logging dient een aantal doelen en doelgroepen:

Zodat de toezichthouder kan toetsen of de gegevensverwerking in de resource broker voldoet aan wet- en regelgeving;
Zodat patiënten via Volgjezorg ook kunnen inzien welke gegevens van hen vanuit een PGO of vanuit een xIS zijn opgevraagd;
Zodat GBZ-beheerders de benodigde informatie kunnen verkrijgen over mogelijk opgetreden verstoringen/fouten;
Zodat ketenregie
1. bij problemen in de uitwisseling, de betrokken partijen bij elkaar kan brengen en kan voorzien van nadere informatie;
2. inzicht heeft in (aantallen en typen) uitwisselingen binnen AORTA.

De berichtenlog bestaat uit een messageLog (A+D: ontvangen requests en geretourneerde responses) en een GBZ-log (B+C: verzonden requests en ontvangen responses).

Het systeem logt in de berichtenlog ondermeer de volgende attributen:

Request (push of pull, inkomend en uitgaand)
- Het message-id, deze wordt wordt gevuld met "<initialRequestID>; <requestID>".
- Het interactie-id, hierin wordt
  - Voor FHIR-interacties opgenomen de string "<basis interactietype>:<FHIR-profiel>:<major FHIR profiel versie>", bijv. "search:mp-MedicationAgreement:1", OF
    "operation:<operation name>:<major operation versie>", bijv. "operation:$get-aorta-data:1"
- Tijdelijk wordt de SOAP-action
  - Voor FHIR-interacties gevuld met "<de ontvangen URL, inclusief de ontvangen zoekparameters>".
  - Voor Task notificaties gevuld met "<de ontvangen URL>".
- Indien van toepassing: het BSN van de patiënt van wie gegevens worden opgevraagd;
- Indien van toepassing: het type gegevens (data category) waarop de interactie betrekking heeft, hierin wordt opgenomen
  - voor interacties waarmee een entry in VWI/ACT wordt geregistreerd of gewijzigd: het bouwsteentype of de gegevenssoort van het request (deze is opgenomen in de URL));
  - voor overige interacties: de gegevensdienst-ID of de contextcode ("medmij.gegevensdienst.<id>" of "aorta.contextcode.<code>" uit de scope van het AORTA access_token);
- Het ID van de agerende organisatie
  - Voor requests die worden ontvangen vanuit het MedMij netwerk is dit het organisatieID van de Resource Broker MedMij-in component;
  - Voor requests die worden ontvangen vanuit het Twiin netwerk is dit het organisatieID van het initiërende (externe) GTK;
  - Voor requests die worden ontvangen vanuit AORTA zelf is dit het organisatieID van de initiërende GBx-applicatie;
- Het ID van het agerende systeem
  - Voor requests die worden ontvangen vanuit het MedMij netwerk is dit het appID van de Resource Broker MedMij-in component;
  - Voor requests die worden ontvangen vanuit het Twiin netwerk is dit het appID van de Resource Broker GTK component;
  - Voor requests die worden ontvangen vanuit AORTA zelf is dit het appID van het initiërende GBx;
- Het ID van de reagerende organisatie
  - Voor requests die worden verzonden naar een GBZ is dit het organisatieID van de initiërende GBx-applicatie;
  - Voor requests die worden verzonden naar het Twiin netwerk is dit het organisatieID van (of achter) het reagerende (externe) GTK;
- Het ID van het reagerende systeem
  - Voor requests die worden verzonden naar een GBZ is dit het organisatieID van de reagerende GBZ-applicatie;
  - Voor requests die worden verzonden naar het Twiin netwerk is dit het appID van de Resource Broker GTK component;
- Het ID van de reagerende XSG;
- Het ID van de agerende XSG;
- Indien van toepassing: De gebruiker en eventueel de verantwoordelijke.
Response (ontvangen en geretourneerd)
- Het message-id, deze wordt wordt gevuld met de requestID uit het bijbehorende request.
- Het resultaat (result, result category, xml error detail), hierin worden opgenomen de HTTP statuscode en eventueel zelf gegenereerde foutcodes, zoals RTEDEST. Bij FHIR-interacties wordt hier aan toegevoegd
  - de inhoud van een eventueel ontvangen of verzonden WWW-Authenticate HTTP header, en/of
  - de inhoud (severity, code en details) van eventueel ontvangen OperationOutcome instanties waarvan de severity gelijk is aan error of fatal.
- Het interactie-id, hierin wordt
  - Voor FHIR-interacties opgenomen de string "<basis interactietype>:<FHIR-profiel>:<major FHIR profiel versie>", bijv. "search:mp-MedicationAgreement:1", OF
    "operation:<operation name>:<major operation versie>", bijv. "operation:$get-aorta-data:1"

In de exportLog t.b.v. CCDA wordt een nieuw veld toegevoegd:

QueryString, deze wordt voor FHIR-interacties gevuld met de inhoud van het SOAP-action veld uit de messageLog.

Transformatie van FHIR-results naar v3-responses

FHIR-result		v3-response		Wie
HTTP statuscode	Aanvullende informatie	acknowledgement typeCode	acknowledgementDetail typeCode	Wie
200	-	AA	-	Transformatie Server (in v3 response ook het transformatie-id opnemen)
	Wanneer een geldige FHIR zoekparameter wordt ontvangen die niet wordt ondersteund, dan wordt een OperationOutcome met issue.code "`not supported`" opgenomen in het resultaat.
	Wanneer een ongeldige FHIR zoekparameter wordt ontvangen, dan wordt een OperationOutcome met issue.code "`invalid`" en de van toepassing zijnde issue.details geretourneerd opgenomen in het resultaat.
	Wanneer een FHIR zoekparameter een geldige waarde bevat die niet wordt ondersteund, dan wordt een OperationOutcome met issue.code "`not supported`" en de van toepassing zijnde issue.details geretourneerd.
	Wanneer een optionele FHIR zoekparameter een ongeldige waarde heeft, dan wordt een OperationOutcome met issue.code "`value`" en de van toepassing zijnde issue.details geretourneerd.
400	-	AE	SYN	Resource Broker VnC (in v3 response ook het transformatie-id opnemen)
	Wanneer een verplichte FHIR zoekparameter ontbreekt, dan wordt een OperationOutcome met issue.code "`required`" en de van toepassing zijnde issue.details geretourneerd.		SYN105 + OperationOutcome issue.code en issue.details attributen in fout tekst veld opnemen
	Wanneer een verplichte FHIR zoekparameter een ongeldige waarde heeft, d.w.z. een waarde die niet is gespecificeerd binnen de gegevensdienst, dan wordt een OperationOutcome met issue.code "`value`" en de van toepassing zijnde issue.details geretourneerd.		SYN103 + OperationOutcome issue.code en issue.details attributen in fout tekst veld opnemen
	Wanneer een ontvangen FHIR resource instance ongeldig is, dan wordt een OperationOutcome met issue.code "`invalid`" en de van toepassing zijnde issue.details geretourneerd.		SYN113 + OperationOutcome issue.code en issue.details attributen in fout tekst veld opnemen
401	-	CE	SYNGBX + WWW-Authenticate error attribuut in fout tekst veld opnemen (in huidige situatie wordt een 4xx door de ZIM vertaald naar een SYNGBX)
401	In deze situatie wordt, conform RFC 6750, ook een `WWW-Authenticate` HTTP response header met als auth-scheme "`Bearer`" en een `error` attribuut met waarde "`invalid_token`" geretourneerd. In deze situatie mag daarnaast ook een OperationOutcome met issue.code "`security`" worden geretourneerd.	CE
403	-	AE	SYNGBX + WWW-Authenticate error attribuut in fout tekst veld opnemen (in huidige situatie wordt een 4xx door de ZIM vertaald naar een SYNGBX)
	Indien een `Authorization` header werd gebruikt in het request, dan wordt in deze situatie, conform RFC 6750, een `WWW-Authenticate` HTTP response header met als auth-scheme "`Bearer`" en een `error` attribuut met waarde "`access_denied`" geretourneerd. Indien het een FHIR-request betreft, dan wordt in deze situatie (ook) een OperationOutcome met issue.code "`forbidden`" geretourneerd.
	In deze situatie wordt, conform RFC 6750, een `WWW-Authenticate` HTTP response header met als auth-scheme "`Bearer`" en een `error` attribuut met waarde "`access_denied`" geretourneerd. In deze situatie wordt een OperationOutcome met issue.code "`suppressed`" geretourneerd.
	In deze situatie wordt, conform RFC 6750, ook een `WWW-Authenticate` HTTP response header met als auth-scheme "`Bearer`" en een `error` attribuut met waarde "`insufficient_scope`" geretourneerd. In deze situatie mag daarnaast ook een OperationOutcome met issue.code "`forbidden`" of "`security`" worden geretourneerd.
404	In deze situatie wordt een OperationOutcome met issue.code "`not-supported`" en de van toepassing zijnde issue.details geretourneerd.	AE	NS200 + OperationOutcome issue.code en issue.details attributen in fout tekst veld opnemen
404	In deze situatie wordt een OperationOutcome met issue.code "`not-found`" en de van toepassing zijnde issue.details geretourneerd.	AE	NF + OperationOutcome issue.code en issue.details attributen in fout tekst veld opnemen
500	-	AE	INTERR
503	-	CR	RTEDEST
504	-	AR	QTITI