Skip to main content
Skip table of contents

Interfaces Toegangslog

Toegangslog Interface

Algemeen

Base endpoint en FHIR-versions

De waarde van de base-URL van de FHIR endpoints die de Toegangslog biedt t.b.v. de Toegangslog 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 Toegangslog interface worden de volgende FHIR-versions ondersteund:

  • R4

Let op! De Toegangslog wordt door Resource Clients aangeroepen via Resource Broker ZA-in. Een Resource Client dient de base-URL van Resource Broker ZA-in te gebruiken. Resource Broker ZA-in hanteert de base-URL van de Toegangslog.

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 log entry 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:

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

aorta-AuditEvent

Type

Subfeature

Versie

1.0.0

Groep

FHIR-profielen

Gepubliceerd

Delta

Initiële versie van feature.

Voorbeelden:

Interacties

Zoeken naar LOG-entries

Feature

searchAuditEvent

Type

Service

Versie

1.0.1

Groep

Logging

Gepubliceerd

Delta

Verhelderd dat toets op geldigheid van access_token en toets op content_type in sommige situaties achterwege mag worden gelaten.

Use case

AOF.UC.LOG.100.v2

Feature

Versie

Dependency

Aanbieder

Afnemer

searchAuditEvent

1.0.1

core-FHIR-interactie-broker

*

*

searchAuditEvent

1.0.1

aorta-AuditEvent

1.0

1.0

De interactie om te zoeken naar LOG-entries is gebaseerd op een FHIR-search:

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

Ondersteunde parameters zijn:

  • period

Voorbeeld: "zoek alle log entries vanaf 1 januari 2023" wordt

GET [base]/AuditEvent?period.start=ge2023-01-01

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.

HTTP statuscodes die kunnen worden geretourneerd zijn opgenomen in onderstaande tabel.

Omdat bepaalde Confluence macro’s nog niet worden ondersteund in de publicatie omgeving, bevat de tabel, in de publicatieomgeving, ook informatie over de wijze waarop de betreffende interface wordt geïmplementeerd in de server component. De statuscodes die kunnen worden geretourneerd zijn opgenomen in de kolom “Uitkomst”. De overige informatie mag worden genegeerd.

AOF.UCe.VAL.100.v1 - Toetsing type content

Uitkomst

Stap

Omschrijving

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

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.

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

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.

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.

Het systeem genereert de vereiste response en gaat verder met de exit stap van de main flow.

Stap

Omschrijving

Uitkomst

1

<exit>

Het systeem retourneert een response naar de primaire actor.

Verwerking succesvol

statuscode 200 OK

Functionele datamodel van een LOG-entry

Het functionele datamodel van een LOG-entry, en de mapping ervan naar FHIR is beschreven in onderstaande tabel.

Attribuut

Cardinaliteit

Toelichting

Functioneel

FHIR

ID van rapporterende applicatie

source.observer

1..1

Referentie naar Device.

Device.identifier bevat het app-id van de rapporterende Resource Broker component.

ID van initiërende organisatie en applicatie (source)

agent.type

1..1

Vaste waarde 110153.

XML
<agent>
    <type>
        <coding>
            <system value="http://dicom.nema.org/resources/ontology/DCM"/>
            <code value="110153"/>
            <display value="Source Role ID"/>
        </coding>
    </type>
    <!-- ... -->
</agent>

agent.who

1..1

Referentie naar Device.

Wanneer een entry betrekking heeft op een A+D log event, dan betreft dit een initiërend GBx-applicatie, en wordt ook een Organization instance meegegeven.

Wanneer een entry betrekking heeft op een B+C log event, dan betreft dit de Resource Broker, en wordt geen Organization instance meegegeven.

Device.identifier bevat het app-id van de verzendende applicatie. Device.owner bevat een referentie naar de hiervoor verantwoordelijke Organization.

Organization.identifier bevat het organisatie-id van de verzendende organisatie, bijvoorbeeld de URA van de verzendende zorgaanbieder.

agent.requestor

1..1

"true"

CODE
<requestor value="true"/>

agent.purposeOfUse

0..1

Mogelijk later gaan gebruiken voor noodsituaties.

ID van reagerende organisatie en applicatie (destination)

agent.type

1..1

Vaste waarde 110152.

XML
<agent>
    <type>
        <coding>
            <system value="http://dicom.nema.org/resources/ontology/DCM"/>
            <code value="110152"/>
            <display value="Destination Role ID"/>
        </coding>
    </type>
    <!-- ... -->
</agent>

agent.who

1..1

Referentie naar Device.

Wanneer een entry betrekking heeft op een A+D log event, dan betreft dit de Resource Broker, en wordt geen Organization instance meegegeven.

Wanneer een entry betrekking heeft op een B+C log event, dan betreft dit een reagerende GBx-applicatie, en wordt ook een Organization instance meegegeven.

Device.identifier bevat het app-id van de ontvangende applicatie. Device.owner bevat een referentie naar de hiervoor verantwoordelijke Organization.

Organization.identifier bevat het organisatie-id van de ontvangende organisatie, bijvoorbeeld de URA van de ontvangende zorgaanbieder.

agent.requestor

1..1

"false"

CODE
<requestor value="false"/>

interactie-id

type

1..1

"rest" voor RESTful FHIR interacties.

“hl7-v3” voor HL7v3 interacties.

NB. in beide gevallen moet de versie erbij om het juiste CodeSystem te kiezen.

voorbeeld FHIR

JSON
"type": {
  "coding": {
    "system": "http://terminology.hl7.org/CodeSystem/audit-event-type",
    "version": "0.5.0",
    "code": "rest"
  }
}

voorbeeld V3

JSON
"type": {
  "coding": {
    "system": "http://terminology.hl7.org/CodeSystem/audit-event-type",
    "version": "0.5.0",
    "code": "hl7-v3"
  }
}

subtype

0..*

"read", "create", "update", "search-type" etc.

Voor V3 fixed value “hl7-v3”.

voorbeeld FHIR

JSON
"subtype": {
  "coding": {
    "system": "http://hl7.org/fhir/restful-interaction",
    "version": "0.5.0",
    "code": "read"
  }
}

voorbeeld V3

JSON
"subtype": {
  "coding": {
    "system": "http://terminology.hl7.org/CodeSystem/audit-event-type",
    "version": "0.5.0",
    "code": "hl7-v3"
  }
}

entity.type

0..1

Indien het om een FHIR-object gaat, dan wordt de ValueSet AuditEventEntityType gebruikt: https://simplifier.net/packages/hl7.fhir.r4.core/4.0.1/files/81466

Indien het om een v3-object gaat, dan wordt het element leeg gelaten

entity.name

1..1

Dit element wordt niet gebruikt, ook al omdat het in R5 verdwijnt.

entity.detail.type

1..1

Bevat het CodeSystem uri van de interactieIDs

Vaste waarde 2.16.840.1.113883.1.6

entity.detail.valueString

1..1

Bevat het interactieID van de v3 of FHIR interactie.

gegevensdienst-id / contextcode

purposeOfEvent

0..1

Het type gegevens (data category) dat wordt uitgewisseld.

Wordt gevuld met de contextCode (AORTA) of met een gegevensdienst-id (MedMij).

system = "2.16.840.1.113883.2.4.3.111.15.1" of "http://vzvz.nl/fhir/NamingSystem/medmij-gegevensdienst"

code = "<contextCode>" of "<gegevensdienst-id>"

Voorbeeld AORTA:

CODE
"purposeOfEvent": {
  "coding": {
    "system": "urn:oid:2.16.840.1.113883.2.4.3.111.15.1",
    "code": "MEDGEG",
    "display": "Medicatieproces medicatiegegevens"
  }
}

Voorbeeld MedMij:

JSON
"purposeOfEvent": {
  "coding": {
    "system": "http://vzvz.nl/fhir/NamingSystem/medmij-gegevensdienst",
    "code": "50"
  }
}

patiënt

agent.type

1..1

Vaste waarde PAT.

XML
<agent>
    <type>
        <coding>
            <system value="http://terminology.hl7.org/CodeSystem/v3-RoleClass"/>
            <code value="PAT"/>
        </coding>
    </type>
    <!-- ... -->
</agent>

agent.who

1..1

Referentie naar Patient. Patient.identifier bevat het BSN van de persoon die onderwerp is van de persoonsgegevens in kwestie.

agent.requestor

1..1

"false" wanneer de AuditEvent betrekking heeft op een interactie waarbij de patiënt zelf niet de opvrager was.

"true" wanneer de AuditEvent betrekking heeft op een interactie waarbij de patiënt zelf wel de opvrager was.

datum en tijd van de activiteit

recorded

1..1

Datum/tijd zoals vastgelegd in de log.

-

period

1..1

Periode tussen ontvangst request en retour response:

  • start = verzendtijd van request

  • eind = ontvangsttijd van response

resultaat

outcome

1..1

Toegestane waarden zijn:

  • 0 - Success

  • 4 - Minor failure (statuscode 4xx geretourneerd)

  • 8 - Serious failure (statuscode 5xx geretourneerd)

  • 12 - Major failure (systeem is niet bereikbaar)

Mapping v3-transactie op codes:

  • succes: 0

  • AE: 8 

  • CE: 12

outcomeDesc

1..1

Wordt gevuld met het volledige result veld uit de messageLog. Bevat dan de geretourneerde HTTP statuscode en eventuele gegenereerde foutcodes.

-

requestID (extension)

1..1

extension.url "http://vzvz.nl/fhir/StructureDefinition/aorta-request-id"

extension.valueString
bevat het requestID dat wordt toegekend aan de betreffende A+D of B+C event (v3: gehele messageID van A of B log, fhir: deel van messageID van A of B log).

-

initialRequestID (extension)

1..1

extension.url "http://vzvz.nl/fhir/StructureDefinition/aorta-trace-id"

extension.valueString
bevat het initialRequestID dat wordt toegekend aan de betreffende A+D en B+C event (v3: messageID van A log, fhir: deel van messageID van A log).

Hiermee kunnen de instances aan elkaar worden gerelateerd.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.