Resource Broker Interfaces - 0.7.x

Resource Broker LOG

RB-Logging Interface

AOF.RB-I.RBL.100.v1

Bij iedere interactie worden in het HTTP-request, de volgende additionele custom HTTP headers meegezonden:

• Authorization: Bearer <AORTA access_token>
• AORTA-ID: initialRequestID=<UUID conform RFC4122>; requestID=<UUID conform RFC4122>
• AORTA-Version: contentVersion=<versienummer>; acceptVersion=<versienummer>

Een token dat wordt meegezonden is in sommige gevallen een XML SAMLv2 Assertion, en in andere situaties een JSON Web Token (JWT). Een JWT bestaat uit een aantal base64 strings, die aan elkaar zijn gekoppeld met punten. Omdat een base64url geëncodeerde SAMLv2 Assertion geen punten kan bevatten, is de ontvanger altijd in staat om het type token bepalen. Een SAML Assertion dient altijd base64url te worden gecodeerd conform RFC 4648. 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 attribuut contentVersion bevat de versie van de betreffende interactie die wordt gehanteerd in het request. Het attribuut acceptVersion bevat de versie of versies die door de resource broker mogen worden gehanteerd bij de verwerking van de interactie.

AOF.RB-I.RBL.200.v1

Bij iedere interactie worden in het HTTP-response, de volgende additionele custom HTTP headers meegezonden:

• AORTA-Version: contentVersion=<versienummer>

Het attribuut contentVersion bevat de daadwerkelijk gehanteerde versie.

AOF.RB-I.RBL.300.v1

Resource broker biedt een FHIR-search interactie op AuditEvent aan. Een resource client kan op de volgende wijze zoeken naar audit events:

GET [base]/AuditEvent{?[parameters]{&_format=[mime-type]}}

De waarde van de base-URL is gelijk aan:

• https://<FQDN>{</path extension>}/fhir/<fhir-version>

De waarde van <fhir-version> die wordt ondersteund is "R4".

Ondersteunde waarden voor _format zijn:

• de mogelijke opties die duiden op het FHIR JSON formaat of op het FHIR XML formaat.

Ondersteunde parameters zijn:

• period

Let op! Het BSN van de patient waarnaar wordt gezocht, wordt meegegeven in het AORTA access_token, en dus niet in een query-parameter.

AOF.RB-I.RBL.400.v1

Resource broker levert AuditEvent instanties op die betrekking hebben op:

• inkomende berichten (A log) en de daarop geretourneerde responses (D log);
• uitgaand berichten (B log) en de daarop geretourneerde responses (C log);

A+D log entries zijn gecombineerd in één AuditEvent instance. Hetzelfde geldt voor B+C log entries.

AOF.RB-I.RBL.500.v1

FHIR profiel van AuditEvent:

De FHIR-profielen van Device en die van Organization zijn beschreven op de pagina AORTA FHIR-profielen.

Resource Broker MedMij-in

AS FHIR Resource Broker Interface

AOF.RB-I.ASF.100.v2

De AS FHIR Resource Broker Interface is nagenoeg gelijk aan de AORTA FHIR Resource Interface, inclusief de gehanteerde HTTP-headers. Dit geldt zowel voor het generieke deel van de interface als voor de AORTA FHIR * interacties. In deze sectie worden daarom slechts de afwijkingen hierop beschreven.

M.b.t. de HTTP-headers die worden gebruikt geldt voor alle interacties de volgende uitzondering:

• In de Authorization header wordt een MedMij access_token meegestuurd
  Authorization: Bearer <medmij_access_token>
• Tevens zal het, van DigiD ontvangen, authenticatietoken (Assertion), base64url gecodeerd conform RFC 4648) als volgt worden toegevoegd aan ieder request:
  DigiD-Authenticatie: Bearer <DigiD SAML Assertion>

Een token dat wordt meegezonden is in sommige gevallen een XML SAMLv2 Assertion, en in andere situaties een JSON Web Token (JWT). Een JWT bestaat uit een aantal base64 strings, die aan elkaar zijn gekoppeld met punten. Omdat een base64url geëncodeerde SAMLv2 Assertion geen punten kan bevatten, is de ontvanger altijd in staat om het type token bepalen.

MedMij CapabilityStatement Interface

AOF.RB-I.MMC.100.v1

Resource broker biedt op zijn endpoint een CapabilityStatement aan. Een resource client kan het statement als volgt bij de resource broker opvragen:

GET [base]/metadata {?_format=[mime-type]}

De waarde van [base] is gelijk aan de in de MedMij ZAL geregistreerde ResourceEndpointUri.

Het gaat hier om een CapabilityStatement van het type "Instance", oftewel het bevat informatie over de daadwerkelijke installatie die benaderbaar is. Bovenstaande capabilities interactie is binnen FHIR verplicht voor FHIR servers.

Deze interface maakt deel uit van de resource interface, zoals gespecificeerd in het MedMij afsprakenstelsel. Op deze interface worden de additionele HTTP headers, zoals de Authorization header en de MedMij-Request-ID header, echter NIET toegepast.

MedMij FHIR Resource Broker Interface

Generiek

AOF.RB-I.MMF.100.v1

Resource broker biedt de resource interface, zoals gespecificeerd in het MedMij afsprakenstelsel. De resource broker biedt gedurende sommige perioden meerdere endpoints, d.w.z. één per actieve release van het MedMij afsprakenstelsel. 

Verschil in resource interface tussen MedMij 1.2.0 en 1.3.0

Het MedMij afsprakenstelsel introduceert de HTTP header MedMij-Request-ID. Dit heeft tot gevolg dat deze header moet worden gecontroleerd (uitzondering indien afwezig) en ook moet worden gebruikt in de AORTA-ID header en in de logging van LSP+.

Ondersteunde MedMij gegevensdiensten

AOF.RB-I.OMG.100.v2

Resource broker ondersteunt de volgende MedMij gegevensdiensten:

De kolommen voor de aantallen interacties bevatten het maximum aantal interacties dat per persoon zal worden geïniteerd om de gehele use case één maal te doorlopen.

RS-Logging Interface

AOF.RB-I.RSL.100.v2

Logbestanden die nodig zijn voor de managementrapportages kunnen, conform gemaakte afspraken in het DAP, middels een API, via HTTPS (TLS) door VZVZ-beheer worden opgehaald. Technisch formaat van de logbestanden is JSON.

De logging kan desgewenst worden opgesplitst in meerdere JSON-bestanden. Ieder JSON-bestand heeft wel altijd betrekking op interacties die plaats hebben gevonden conform één specifieke MedMij-release. Op deze manier kan in de rapportages een beeld worden gecreëerd van het gebruik van een bepaalde MedMij-release in de tijd.

AOF.RB-I.RSL.200.v1

De volgende loggegevens moeten beschikbaar worden gesteld:

Resource Broker ZA-in

AORTA FHIR Resource Broker Interface

AOF.RB-I.AFR.100.v3

De AORTA FHIR Resource Broker Interface is deels gelijk aan de AORTA FHIR Resource Interface, inclusief de gehanteerde HTTP-headers. Dit geldt zowel voor het generieke deel van de interface als voor de AORTA FHIR * interacties. In deze sectie worden daarom slechts de afwijkingen hierop beschreven.

De waarde van de base-URL van de FHIR endpoints die de Resource Broker biedt t.b.v. de AORTA FHIR Resource Broker 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 "STU3", "R4" of "R5".

Resource Broker VnC

AOF.RB-I.VCI.50.v1

De waarde van de base-URL ( [base] ) van de FHIR endpoints die de Resource Broker VnC biedt , 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".

Verzending & Consolidatie Interface

Generiek

AOF.RB-I.VCI.100.v3

De Verzending & Consolidatie Interface is nagenoeg gelijk aan de AORTA FHIR Resource Interface. Dit geldt zowel voor het generieke deel van de interface als voor de AORTA FHIR * interacties. In deze sectie worden daarom slechts de afwijkingen hierop beschreven.

M.b.t. de HTTP headers die worden gebruikt gelden voor alle interacties de volgende extra headers:

• Conditionele request header: DigiD-Authenticatie: Bearer <authenticatietoken>

Een request die is gestuurd door een patiënt (via MedMij of een GBP) dient altijd een DigiD-Authenticatie header te bevatten.

Vooralsnog hoeven slechts JWT-based access_tokens, en SAML-based authenticatietokens te worden ondersteund.

Een token dat wordt meegezonden is in sommige gevallen een XML SAMLv2 Assertion, en in andere situaties een JSON Web Token (JWT). Een JWT bestaat uit een aantal base64 strings, die aan elkaar zijn gekoppeld met punten. Omdat een base64url geëncodeerde SAMLv2 Assertion geen punten kan bevatten, is de ontvanger altijd in staat om het type token bepalen.

Een SAML Assertion dient altijd base64url te worden gecodeerd conform RFC 4648.

Resource Broker APR

Applicatie Register Interface

Generiek

AOF.RB-I.ARI.100.v2

Bij alle interacties die worden geboden door de applicatie register interface worden de volgende HTTP headers toegepast:

• Bij iedere interactie wordt in ieder HTTP-request, op de volgende wijze, een custom HTTP header meegezonden:
  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.

TKID-activatie

AOF.RB-I.ARI.200.v2

Resource broker biedt een interactie aan, waarmee één of meerdere TKID's voor een xIS-instantie, op een aangegeven base endpointadres,  kunnen worden geactiveerd.

Het technische formaat van een activate request is:

POST [base endpointadres]/activate/v1
Content-Type: application/json; charset=utf-8
AORTA-ID: initialRequestID=<UUID conform RFC4122>; requestID=<UUID conform RFC4122>
AORTA-Version: contentVersion=<versienummer>; acceptVersion=<versienummer>

{

"applicationId": "<app-id>",
"tkid": ["string", "string"]

}

Het technische formaat van een activate response is:

200 OK
AORTA-Version: contentVersion=<versienummer>

Toelichting TKID

Middels een activatie van een TKID geeft de GBZ-beheerder aan dat het voor de xIS-instantie, die wordt aangeduid met het applicatieID, een bepaalde set van reeds verkregen acceptaties (nader aangeduid door een set van xIS-type kwalificaties ID's - TKID's) wil activeren. Als gevolg hiervan worden de AORTA systeemrollen, waarvoor het xIS-type blijkens de TKID's is geaccepteerd, in het APR gekoppeld aan de xIS-instantie (de Applicatie). Nadat deze actie is voltooid, kunnen de FHIR capabilities die deel uitmaken van deze AORTA systeemrollen, via de resource broker, bij het xIS worden aangesproken. Bij een activatie wordt een eventueel eerder geregistreerde set van TKID's vervangen door de nieuwe set van TKID's. Indien er een probleem is met één van de TKID's in een set, dan wordt de gehele transactie afgewezen en verandert er dus niets. Het is ook mogelijk om geen enkele tkid te activeren (door geen tkid attribuut op te nemen in de body van het request).

Bevragen Register

AOF.RB-I.ARI.300.v2

Het technische formaat van een getApplication request is:

POST [base endpointadres]/getApplication/v1
Content-Type: application/json; charset=utf-8
AORTA-ID: initialRequestID=<UUID conform RFC4122>; requestID=<UUID conform RFC4122>
{

"applicationId": ""

}

Input parameters:

Het technische formaat van een getApplication  response is:

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

{
    "applicationId": "",
    "active": "",
    "address": "",
    "systemRoles": [{
        "role": "",
        "conformances": [{
            "interactionId": "",
            "send": "",
            "receive": ""
        }]
    }]
}

AOF.RB-I.ARI.400.v2

Het technische formaat van een getApplications request is:

POST [base endpointadres]/getApplications/v1
Content-Type: application/json; charset=utf-8
AORTA-ID: initialRequestID=<UUID conform RFC4122>; requestID=<UUID conform RFC4122>
{

"ura": ""

}

Input parameters:

Het technische formaat van een getApplications  response is:

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

[{
    "applicationId": "",
    "active": "",
    "address": "",
    "systemRoles": [{
        "role": "",
        "conformances": [{
            "interactionId": "",
            "send": "",
            "receive": ""
        }]
    }]
}]

Inhoud van een application object:

Toetsen conformances

AOF.RB-I.ARI.500.v1

Resource broker biedt een interactie aan, waarmee kan worden bepaald of een bepaalde GBx-applicatie, gegevens conformances bevat.

Het technische formaat van een hasConformance request is:

POST [base endpointadres]/hasConformance
Content-Type: application/json; charset=utf-8
AORTA-ID: initialRequestID=<UUID conform RFC4122>; requestID=<UUID conform RFC4122>
{
    "applicationId": "",
    "interactionId": ["", ""]
}

Input parameters:

Het technisch formaat van een hasConformance response is:

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

{
    "applicationId": "",
    "fqdn": "",
    "conformanceStatus": [{
        "interactionId": "",
        "status": ""
    }]
}

Output parameters:

Toetsen Mitz-status

AOF.RB-I.ARI.600.v1

Resource broker biedt een interactie aan, waarmee kan worden bepaald of een bepaalde GBx-applicatie gebruik maak van Mitz voor registratie en toetsing van patiënttoestemming.

Het technische formaat van een isMitzClient request is:

POST [base endpointadres]/isMitzClient
Content-Type: application/json; charset=utf-8
AORTA-ID: initialRequestID=<UUID conform RFC4122>; requestID=<UUID conform RFC4122>
{
    "applicationId": ""
}

Input parameters:

Het technische formaat van een isMitzClient response is:

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

{
    "status": ""
}

Output parameters:

{}