Interfaces Resource Broker LOG

RB-Logging Interface

Algemeen

Base endpoint en FHIR-versions

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

R4

HTTP-request headers

AOF.RB-I.RBL.100.v1

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	19 Oct 2023
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	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.

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

AOF.RB-I.RBL.200.v1

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

AOF.RB-I.RBL.350.v1

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:

AOF.FP.LOG.100.v1

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

Voorbeelden:

https://simplifier.net/vzvz/~resources?category=Example&exampletype=AuditEvent

Interacties

Zoeken naar LOG-entries

Feature	searchAuditEvent
Type	Service
Versie	1.0.0
Groep	Logging
Gepubliceerd	19 Oct 2023
Delta	Initiële versie van feature.
Use case	AOF.UC.LOG.100.v1

Feature	Versie	Dependency	Aanbieder	Afnemer
searchAuditEvent	1.0.0	core-FHIR-interactie-broker	*	*
searchAuditEvent	1.0.0	aorta-AuditEvent	1.0	1.0

AOF.RB-I.RBL.300.v1

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

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.

Functionele datamodel van een LOG-entry

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

AOF.RB-I.RBL.500.v2

Functioneel	FHIR	Cardinaliteit	Toelichting
Attribuut		Cardinaliteit	Toelichting
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
resultaat	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.