Approach Logging v3.0
Inleiding
Het loggingmechanisme is het AS v2.2.x is ten tijde van dit schrijven ongeveer 8 maanden in productie, waarbij significante voortgang is geboekt ten aanzien van het zowel technisch als functioneel correct loggen van de verschillende events. Hierdoor is MedMij Beheer beter in staat analyses uit te voeren op het verkeer en daar waar nodig te assisteren bij het verhelpen en/of identificeren van knelpunten in de keten.
Hoewel het logverkeer significant is verbeterd, blijven er hiaten in het logverkeer welke moeilijk op te lossen zijn, zonder hiervoor het afsprakenstelsel als geheel aan te passen. Deze hiaten zijn onder te verdelen in de volgende zaken:
Missende events, zowel in het huidige verzamelproces alsmede in het Delen en Verzamel/Notificeren proces.
Missende events in verschillende subprocessen, zoals de beschikbaarheids toets en het beheer van toestemmingen.
Onduidelijkheid over de inhoud van verschillende attributen, zoals client_id, provider_id, session_id, trace_id, de inhoud van de result_gathering_information.
Onduidelijkheid over de verschillende foutcodes, de sterke alignment met oAuth 2.0, en de inhoud van de omschrijvingen.
Om deze uitdagingen te adresseren is een herziend log model bedacht, welke belangrijkste wijzigingen op deze pagina worden uitgelegd.
Onderscheid in hoofdprocessen en subprocessen
Ten einde fouten te reduceren in de documentatie, zijn de processen uit het afsprakenstelsel verder gecategoriseerd in hoofdprocessen en subprocessen, waardoor de verschillende log events slechts eenmalig en generiek over de processen heen worden beschreven.
Het afsprakenstelsel in de huidige vorm kent drie hoofdprocessen:
Verzamelen
Delen
Abonneren / Notificeren
HIerbij dient aangetekend te worden dat Abonneren / NOtificeren op het moment niet door deelnemers wordt gebruikt/ondersteund en dat deze in de toekomst zeer waarschijnlijk een andere invulling gaat krijgen. Om die reden is deze voor dit moment buiten beschouwing gelaten.
Daarnaast kent het huidige afsprakenstelsel enkele subprocessen, welke ondersteunend en/of onderdeel zijn van de hoofdprocessen:
Authenticeren
Autoriseren
Beheer Toestemmingen
Beschikbaarheids- en Ontvankelijkheidstoets
Token Refresh
Gegevens Ophalen
Gegevens Delen
Objectenmodel v3.0
De uitdagingen welke zijn genoemd in de inleiding vormen de basis voor de definitie van een herziend objectenmodel, waarbij de structuur en samenhang eenduidiger is gemaakt. Het model is in onderstaand diagram weergegeven:
In hoofdlijnen is het model hervormt tot de volgende uitgangspunten:
De basis vormt nog steeds een Event, waarin de overkoepelende attributen zijn opgenomen.
Een event kan tevens een Request of Response object bevatten, welke de attributen herbergt welke specifiek zijn tot de request, danwel response.
Een Request kent vier mogelijke uitkomsten:
Op een request volgt geen antwoord (no response)
Request is incorrect beoordeeld door ontvanger
Request is correct, maar resulteert in een fout bij de ontvanger
Request is correct en resulteert in een correct antwoord
Een Response reflecteert tevens deze vier situaties, waardoor deze altijd als een paar worden gezien
Met specifieke subobjecten worden request en response objecten uitgebreid met informatie over het event.
Belangrijkste verschillen ten opzichte van het Logging mechanisme in v2.2.x
Het logging mechanisme voor v3.0 kent enkele significante wijzigingen, welke pogen de knelpunten gevonden in v2.2.x op te lossen. In onderstaande paragrafen zijn de belangrijkste verschillen opgenomen ten opzichte van de versie welke in v2.2.x actief zijn.
Basis gevormd door Request, Response en Event
Zoals hierboven opgemerkt, vormen Event, Request en Response de basis van het logmechanisme. Hierdoor worden de volgende drie situaties afgedekt:
Het event is een verzoek aan een derde partij
Het event is een ontvangen verzoek van een derde partij
Het event is een op zichzelf staand event binnen een subproces
In onderstaand voorbeelden zijn deze weergegeven:
Event | Voorbeeld |
|---|---|
send_authentication_request |
JSON
|
receive_authentication_response |
JSON
|
show_consent_page |
JSON
|
Proces en Subproces zijn onderdeel van een event
Het is mogelijk dat subprocessen worden hergebruikt binnen bepaalde hoofdprocessen, waardoor een overkoepelende identifier nodig is voor het verschaffen van de context waarbinnen het event zich manifesteert. Om dit te realiseren is het event object uitgebreid met de volgende 2 attributen:
Proces: Het overkoepelende hoofdproces binnen het afsprakenstelsel. Dit betreft op dit moment Verzamelen en Delen.
Subproces: Het subproces binnen het hoofdproces, danwel het hoofdproces indien het event zich niet binnen een van de subprocessen afspeelt. De subprocessen zijn in bovenstaand paragraaf aangaande hoofdprocessen en subprocessen beschreven.
In onderstaand voorbeeld is dit weergegeven:
show_consent_page |
JSON
|
Fouten zijn geen op zichzelf staande events, maar onderdeel van een Request, Response of op zichzelf staand event
Fouten ontstaan binnen een bepaalde context, als antwoord op een verzoek of ontstaan binnen de verwerking van een verzoek, of bij het versturen van de response. Tevens is het mogelijk dat er fouten optreden waar in beginsel niet in is voorzien tijdens de specificatie van de logging.
Om die redenen worden fouten gelogd als onderdeel van de request, danwel response en onderverdeeld in type (soort), specifieke fout en verduidelijkende omschrijving.
Door de fouten minder specifiek te maken en onder te verdelen in meer generieke categorien, kan worden voldaan aan de wens om fouten in de keten te kunnen duiden en meer gericht te ondersteunen bij oplossingen. Tevens worden deelnemers de ruimte geboden onverwachte fouten te kunnen loggen binnen dit model. Het type fout wordt hierbij gebruikt de fouten te groeperen, zodat bij name en description de deelnemer de specifieke fout welke is ontstaan kan invullen.
In onderstaand voorbeeld is dit weergegeven:
Fout | HTTP response | Foutbericht |
|---|---|---|
Deelnemer verleent actief geen toestemming | 400 |
JSON
|
Overbodige attributen zijn verwijderd
Attributen binnen het logging framework dienen een eenduige inhoud te kennen naar welke gerefereerd kan worden binnen de analyse en rapportage. Voor elk attribuut wordt de inhoud en herkomst gespecifeerd, welke door deelnemers in openbare informatie kan worden verkregen, danwel gespecificeerd.
Attributen welke niet bijdragen aan het volgen van het verkeer door de keten, danwel additionele waarde bieden in de vorm van analyse, zijn uit het objectenmodel verwijderd.
De volgende attributen zijn uit het model verwijderd:
Attribuut | Rationale |
|---|---|
session_id | Deze was alleen relevant voor de DVP en heeft geen significante meerwaarde ten opzichte van de combinatie request_id en correlation_id |
client_id | Op dit moment is de meerwaarde van het identificeren van de versturende partij beperkt. Deze is herleidbaar en op basis van request_id en participant_id |
server_id | Op dit moment is de meerwaarde van het identificeren van de ontvangende partij beperkt. Deze is herleidbaar en op basis van request_id en participant_id |
location | De inhoud van dit attribuut is onderdeel geweest van uitvoerige discussies met deelnemers, waarbij een verschil is tussen het originele doel en de wijze waarop deze wordt gebruikt. Deze is vervangen door een uniek medmij participant id. |
request_type | De inhoud van dit attribuut is statisch en zeer specifiek binnen de context. Het heeft derhalve geen additionele waarde. |
response_type | De inhoud van dit attribuut is statisch en zeer specifiek binnen de context. Het heeft derhalve geen additionele waarde. |
state | Hoewel de inhoud hiervan van waarde kan zijn voor deelnemers, heeft de inhoud geen herleidbare waarde voor MedMij. Derhalve is deze verwijderd. |
trace_id | Deze is in het nieuwe model hernoemd naar x_correlation_id, om de relatie met x-correlation-id te verstevigen. |
Logberichten kunnen eenduidig aan deelnemers worden gekoppeld, onafhankelijk van het gebruikte certificaat
Om logberichten te kunnen koppelen aan deelnemers, zal het location attribuut worden vervangen door een unieke medmij_participant_id welke door de R&A zal worden uitgegeven bij de registratie van een deelnemer. Deze is alleen beschikbaar/bekend voor/bij de deelnemer.
Resultaat van het ophalen danwel delen van een resource wordt gelogd bij de actie
In het huidige model, dient de DVA een overzicht (samenvatting) te loggen van de succesvol, niet succesvol en lege resources in het result_gathering_information event (in het information object). Deze is in het nieuwe model komen te vervallen.
Wanneer bij elke resource uitvraag het resultaat daarvan wordt gelogd, is hieruit een samenvatting te construeren binnen het Datawarehouse, danwel reporting. Het is daarom niet nodig deelnemer hiermee te belasten.
In plaats daarvan wordt bij het resource response bericht het resultaat van de betreffende ophaaldactie, danwel deelactie gelogd:
send_resource_response |
JSON
|
In bovenstaand voorbeeld bevat een Response object op een resource uitvraag een send_resource_responseobject, waarin de zorgaanbieder en betreffende gegevensdienst zijn opgenomen. Vervolgens is een verzamelobject Results opgenomen welke afzonderlijke Resource objecten bevat, waarbij per resource de naam en het resultaat van de ophaalactie worden gelogd.
Het model is zo opgezet dat zowel individuele resource uitvragen, alsmede een uitvraag op basis van gegevensdienst (wat kan resulteren in meerdere resource uitvragen) kan worden afgedekt.
In overleg met Nictiz/MedMij moet nog worden bepaald wat in het attribuut name moet worden genomen.
Het doel van dit attribuut is om specifieker binnen een gegevensdienst te kunnen zien wat succesvol, danwel onsuccesvol kan worden opgehaald. Op basis van de huidige insteek neigt men naar de combinatie tussen HCIM EN en FHIR Resource. In onderstaand voorbeeld is de combinatie genomen voor de gegevensdienst Basis Gegevens Langdurige Zorg (BgLz).
[{
"event": {
"type": "send_resource_response",
"medmij_participant_id": "c6a27d45-4316-464e-81e0-48d5dbccaccc",
"datetime": "2023-09-28T22:14:44.618+01:00",
"correlation_id": "79dc6181-6239-4fdd-ad98-594312aeac71",
"process": "verzamelen",
"sub_process": "gegevens_verzamelen",
"response": {
"request_id": "11bad6a2-4768-45cc-a2c6-affc370d9aa9",
"status": 200,
"resources": {
"provider_id": "een.huisarts@medmij",
"service_id": 49,
"results": [{
"resource": {
"hcim": "TreatmentDirective",
"name": "Consent",
"result": "successful"
}
}]
}
}
}
}]