Interfaces Adressering Server

Routing Info Interface

Feature informatie

Feature	getRoutingInfo
Type	Service
Versie	1.0.1
Groep	Adressering
Gepubliceerd	01 Nov 2023
Delta	Specificatie van te retourneren statuscode indien URA of appID van destination of client in getRoutingInfo niet wordt gevonden.

Feature	Versie	Dependency	Aanbieder	Afnemer
getRoutingInfo	1.0.1	AORTA Stelseltoken	*	*
getRoutingInfo	1.0.1	AORTA-ID HTTP Header	*	*
getRoutingInfo	1.0.1	Formaat AORTA interactietabel	*	-
getRoutingInfo	1.0.1	getTransformatieMetadata	*	-

Inhoud en formaat van een getRoutingInfoRequest

Een getRoutingInfoRequest wordt op de volgende wijze verzonden:

POST [base endpointadres]/getRoutingInfo/v1

Bij het verzenden van een getRoutingInfoRequest dienen de volgende HTTP headers te worden meegezonden:

Feature	AORTA-ID HTTP Header
Type	Subfeature
Versie	1.0.0
Groep	HTTP Headers
Gepubliceerd	19 Oct 2023
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.

Content-Type: application/json; charset=utf-8

Het technische formaat van de HTTP body van een getRoutingInfo request is:

JSON

{
    "destination": {
        "code": "",
        "codeSystem": ""
    },
    "interaction": [{
        "id": "",
        "type": "",
        "fhirProfile": "",
        "fhirProfileVersion": ""
    }],
    "client ": {
        "code": "",
        "codeSystem": ""
    }
}

Input parameters:

Name	Cardinality	Type	Toelichting
destination	0..1	Object met attributen	Beoogde bestemming van de interactie. Vereist wanneer één van de ingestuurde interactions géén url attribuut bevat met daarin een appID. Wordt genegeerd wanneer alle ingestuurde interactions een url attribuut bevatten met daarin een appID. Wanneer één ingestuurde interaction een url attribuut bevat met een appID en een andere ingestuurde interaction wordt uitgedrukt middels een id attribuut, dan wordt de destination slechts gebruikt voor de interaction met het id attribuut. Voor de interaction met het url attribuut wordt dan de appID uit het url attribuut gebruikt.
destination.code	1..1	String	Beoogde bestemming van de interactie. Mogelijke waarden: <appID> <URA>
interaction	1..n	Object met attributen	Structuur waaruit het interactie-id van ieder te adresseren bericht kan worden bepaald. Een interactie dient op één van de volgende methoden te worden doorgegeven: id (bijv. search:zib-LivingSituation:2) type + fhirProfile + fhirProfileVersion (bijv. read + http://nictiz.nl/fhir/StructureDefinition/zib-LivingSituation + 2.1.3) type + fhirProfile (bijv. search + http://nictiz.nl/fhir/StructureDefinition/zib-LivingSituation )
interaction.id	0..1	String	Interactie-id van het te adresseren bericht, of van de te adresseren berichten. Het versie-deel in het id attribuut wordt gespecificeerd a.d.h.v. aan major versienummer conform semver, dus bijvoorbeeld "1", "*" of "x". Hiermee is de compatibiliteit afdoende geborgd.
interaction.type	0.1	String met waarde create \| read \| update \| delete \| search \| batch \| transaction	Het (restful FHIR) interactie type.
interaction.fhirProfile	0..1	String	De canonical van het gehanteerde FHIR profiel, bijv. "http://nictiz.nl/fhir/StructureDefinition/zib-LivingSituation ".
interaction.fhirProfileVersion	0..1	String	De versie van het gehanteerde FHIR profiel. Het attribuut wordt gespecificeerd conform semver, dus bijvoorbeeld "1.0.0" of "2.x". De Adressering Server houdt bij het zoeken naar applicaties slechts rekening met het major nummer, omdat compatibiliteit hierdoor afdoende is geborgd.
client	0..1	Object met attributen	Beoogde client voor de interactie.
client.code	1..1	String	Beoogde client voor de interactie. Mogelijke waarden: <appID> <role-id>
client.codeSystem	1..1	String	Het gehanteerde codesysteem. Mogelijke waarden: "urn:oid:2.16.840.1.113883.2.4.6.6" (appID) "urn:oid:2.16.840.1.113883.2.4.3.111.8" (role-id)

Inhoud en formaat van een getRoutingInfoResponse

Bij het verzenden van een getRoutingInfoResponse dienen de volgende HTTP headers te worden meegezonden:

Content-Type: application/json; charset=utf-8

Het technische formaat van de HTTP body van een getRoutingInfoResponse is:

JSON

[{
    "interactionId": "",
    "destinationInfo": [{
        "destination": {
            "code": "",
            "codeSystem": ""
        },
        "fqdn": "",
        "transformationId": "",
        "aortaATversion": ""
    }]
}]

Output bestaat uit 0..n JSON objecten die, voor elk van de ontvangen interactions, de volgende inhoud bevatten. Deze objecten worden geretourneerd in de volgorde waarin de betreffende interactions werden ontvangen in het getRoutingInfo request.

Name	Cardinality	Type	Toelichting
interactionId	1..1	String	Interactie-id van het te adresseren bericht, of van de te adresseren berichten. Wordt gevuld met de interactie, indien mogelijk inclusief het exacte versienummer, waarmee de flow dient te worden vervolgd. Ook indien een transformatie is vereist.
destinationInfo	0..n	Object met attributen	Slechts aanwezig indien tenminste één geschikte GBx-applicatie is gevonden.
destinationInfo.destination	1..1	Object met attributen	Beoogde bestemming van de interactie.
destination.code	1..1	String	Beoogde bestemming van de interactie. Mogelijke waarden: <appID>
destination.codeSystem	1..1	String	Het gehanteerde codesysteem. Mogelijke waarden: "urn:oid:2.16.840.1.113883.2.4.6.6" (appID)
destinationInfo.fqdn	1..1	String	FQDN van de GBx-applicatie.
destinationInfo.transformationId	0..1	String	Het ID van het uit te voeren transformatie algoritme. Slechts aanwezig indien de applicatie die het request moet beantwoorden, vereist dat eerst een transformatie wordt uitgevoerd. Wordt nooit gevuld wanneer de interactie een FHIR-operation is.
destinationInfo.aortaATversion	0..1	String	De hoogste versie van het AORTA access_token die wordt ondersteund door de beoogde bestemming van de interactie. Afwezig indien de bestemming geen AORTA access_tokens kan verwerken.

HTTP statuscodes

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
		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.VAL.100.v1 Het systeem toetst of het verzoek voldoet aan de interface specificatie.	Ongeldig verzoek statuscode 400 Bad Request
2		Het systeem genereert de vereiste foutresponse en keert terug naar de exit stap van de main flow.
3	Het systeem stelt vast voor welke interactie-id('s) routing info wordt gevraagd.	Interactie-id kan niet worden bepaald (of is onjuist) statuscode 400 Bad Request
3		Het systeem genereert de vereiste foutresponse en keert terug naar de exit stap van de main flow.
4	Het systeem stelt, m.b.v. de transformatie server metadata, vast welk van de gevraagde interactie-id('s) eventueel m.b.t. transformatie kunnen worden uitgevoerd, en bepaalt naar welke interactie-id's dan zou worden getransformeerd.
5	Het systeem stelt voor iedere gevraagde interactie-id vast, naar welke actieve GBx-applicatie(s) (appID) binnen de aangegeven destination, de betreffende interactie, zo nodig na transformatie, kan worden verzonden. Instance-level interactie: het appID wordt verkregen uit het url attribuut in de interaction (formaat van de url is in deze situatie "<base endpointadres Resource Broker XXX-in>/<appID>/<type>/<id>"). Type- of whole system interactie: hierbij wordt gebruik gemaakt van de Applicatie Register Interface van RB APR (zie ook de Toelichting "systeemrollen en conformances" en de Toelichting "filtering interacties").	Destination niet gevonden statuscode 404 Not Found
		Het systeem genereert de vereiste foutresponse en keert terug naar de exit stap van de main flow.
		Client niet gevonden statuscode 404 Not Found
		Het systeem genereert de vereiste foutresponse en keert terug naar de exit stap van de main flow.
6	Het systeem stelt voor iedere gevonden GBZ-applicatie, op basis van de systeemrollen in het APR, vast of de betreffende applicatie AORTA access_tokens kan verwerken, en zo ja wat de hoogste versie is die wordt ondersteund.
7 <exit>	Het systeem retourneert een response naar de primaire actor.	Verwerking succesvol statuscode 200 OK

Voorbeelden van gebruik Routing Info Interface

Interactie vanuit MedMij

Het technische formaat van een getRoutingInfo request is:

CODE

POST [base endpointadres]/getRoutingInfo/v1

{
    "destination": {
        "code": "382",
        "codeSystem": "urn:oid:2.16.528.1.1007.3.3"
    },
    "interaction": [{
        "id": "create:zib-BloodPressure:3"
    }]
}

Het technische formaat van een getRoutingInfo response is:

CODE

200 OK

[{
    "interactionId": "create:zib-BloodPressure:3",
    "destinationInfo": [{
        "destination": {
            "code": "5476",
            "codeSystem": "urn:oid:2.16.840.1.113883.2.4.6.6"
        },
        "fqdn": "bron.zorgaanbieder.nl",
        "transformationId": "1"
    }]
}]

In bovenstaande situatie is transformatie #1 vereist om de gevraagde FHIR-interactie af te kunnen leveren bij GBZ-applicatie #5476.

Initiatie vanuit GBx-client

Het technische formaat van een getRoutingInfo request is:

CODE

POST [base endpointadres]/getRoutingInfo/v1

{
    "destination": {
        "code": "592",
        "codeSystem": "urn:oid:2.16.528.1.1007.3.3"
    },
    "interaction": [{
        "type": "read",
        "fhirProfile": "http://nictiz.nl/fhir/StructureDefinition/mp-MedicationAgreement",
        "fhirProfileVersion": "1.0"
    }, {
            "type": "read",
        "fhirProfile": "http://nictiz.nl/fhir/StructureDefinition/mp-MedicationAgreement",
        "fhirProfileVersion": "2.0"
    }, {
        "id": "search:eAfspraak-Appointment:2"
    }]
}

Het technische formaat van een getRoutingInfo response is:

CODE

200 OK

[{
    "interactionId": "read:mp-MedicationAgreement:1",
    "destinationInfo": [{
        "destination": {
            "code": "3287",
            "codeSystem": "urn:oid:2.16.840.1.113883.2.4.6.6"
        },
        "fqdn": "bron-1.zorgaanbieder.nl",
        "aortaATversion": "2.0"
    }]
}, {
    "interactionId": "read:mp-MedicationAgreement:2"
}, {
    "interactionId": "search:eAfspraak-Appointment:2",
    "destinationInfo": [{
        "destination": {
            "code": "3288",
            "codeSystem": "urn:oid:2.16.840.1.113883.2.4.6.6"
        },
        "fqdn": "bron-2.zorgaanbieder.nl",
        "transformationId": "3"
    }]
}]

In bovenstaande situatie is transformatie #3 vereist om de gevraagde Appointment interactie af te kunnen leveren bij GBZ-applicatie #3288. Er is géén transformatie vereist om de gevraagde MedicationRequest interactie af te kunnen leveren bij GBZ-applicatie #3287.

Aanroep vanuit Autorisatie Server ZA

Het technische formaat van een getRoutingInfo request is:

CODE

POST [base endpointadres]/getRoutingInfo/v1

{
    "destination": {
        "code": "3287",
        "codeSystem": "urn:oid:2.16.840.1.113883.2.4.6.6"
    },
    "interaction": [{
        "id": "search:mp-MedicationAgreement:1"
    }, {
        "id": "search:mp-MedicationAgreement:2"
    }],
    "client ": {
        "code": "205",
        "codeSystem": "urn:oid:2.16.840.1.113883.2.4.6.6"
    }
}

Stel dat de client in deze situatie versie 1.1 van de gevraagde interactie ondersteunt, dan wordt, omdat eenzelfde major nummer voldoende is, het technische formaat van de bijbehorende getRoutingInfo response:

CODE

200 OK

[{
    "interactionId": "search:mp-MedicationAgreement:1",
    "destinationInfo": [{
        "destination": {
            "code": "3287",
            "codeSystem": "urn:oid:2.16.840.1.113883.2.4.6.6"
        },
        "fqdn": "bron-1.zorgaanbieder.nl",
        "aortaATversion": "1.0"
    }]
}]

In bovenstaande situatie is géén transformatie vereist om de gevraagde MedicationRequest interactie af te kunnen leveren bij GBZ-applicatie #3287.