Tilgangslogg - Implementasjonsguide
- Helge M. Karlsen
Beskrivelse
Denne dokumentasjonen inneholder implementasjonsguide for innsyn i tilgangslogg for Pasientjournal. Beskrivelsene i dette dokumentet baserer seg på Direktoratet for e-helses anbefalinger for REST-tjenester per juni 2018 og API dokumentasjon v2.2.3.0/1.8.3.0 for DIPS Service Broker Health Record Access Log. Dokumentasjonen tar høyde for at det er opprettet et endepunkt som igjen gjør spørringer mot en eller flere Dips-installasjoner.
Sikkerhet
Tjenestene sikres med TLS 1.2 og et JWT token. Det er også mulig å legge til rette for 2-veis TLS. Ettersom det er transportkryptering mellom klient og tjeneste bør det gjøres en sikkerhetsvurdering på endepunkter hvor spørringer og responser skal brukes til og fra en intern tjeneste. Alle spørringer som går fra klienten skal inkludere et JWT-token. Tokenet er "self-contained" og inneholder informasjon om innlogget- og evnt. representert innbygger samt en signatur som bekrefter om tokenet er gyldig.
Ved mottak av tokenet må blandt annet følgende valideres:
Token-signatur
Scope (scp)
Forventet verdi er “innsynpasientjournal“
Audience (aud)
Forventet verdi avhenger av mottaker. For eksempel kan Helse Vest validere at verdien “hv” er i listen
nationalId i request-parameter er lik subject (sub) verdien i tokenet.
Se også dokumentasjon for JWT for ytterligere informasjon om validering med mer: Innlogget Innbygger
Ressurser
Felles for alle Ressurser
HTTP Request Headers
Request headere vil være de samme for alle ressurser
Navn | Verdi |
|---|---|
Accept | application/xml |
Content-Type | application/json |
HTTP Response Status codes
Statuskoder som gjelder for alle HTTP responser. Disse statuskodene er de eneste som er forventet men Helsenorge har støtte for mottak av alle standard HTTP statuskoder.
Navn | Kode | Beskrivelse |
OK | 200 | Spørringen ble forstått og gjennomført. |
Internal Server Error | 500 | En feil oppstod ved behandling av spørringen |
Unauthorized | 401 | Tokenvalidering feilet |
Respons formatering
Helsenorge sender application/xml i accept-headeren og forventer derfor XML i responsen. DIPS returnerer i utgangspunktet JSON i sine responser, men av historiske årsaker har vi videreført XML. DIPS har støtte for å returnere XML også, men da må accept-headeren mot DIPS også være application/xml. Formateringen av XMLen Helsenorge forventer er den samme som DIPS returnerer ved kall til sine tjenester.
HealthRecordAccessLog
HTTP Request
Spørringen er et POST-kall med parametere i bodyen i JSON-format. Dette gjør at Content-Type i headeren alltid er satt til application/json. I responsen vil alltid være XML, derfor vil Accept i headeren ha verdien application/xml.
Parametere
Navn | Type | Påkrevd |
nationalId | String | Ja |
from | Dato | Nei |
to | Dato | Nei |
pageno 1 | Integer | Nei |
pagesize 1 | Integer | Nei |
1 Ved spørringer mot et endepunkt som har flere datakilder vil parameterne pageno og pagesize kunne gi inkonsekvente data i brukergrensesnittet. Hvis datakilde 1 har data fra 2012 og datakilde 2 har data fra 2018 på side 1 så vil sorteringen på dato bli helt feil om det samme er tilfellet når side 2 hentes. Disse vil dermed alltid ha en fast verdi på henholdsvis 1 og 10000.
HTTP Respons
Responsen er XML og er basert på Dips' egen respons, men med noen mulige tilpasninger for å kunne tilfredsstille de behovene som kommer om det er flere interne kilder på endepunktet HealthRecordAccessLog-spørringen går mot. Disse endringene skal ikke være nødvendig om det er en intern datakilde.
Tilpasninger ved feilsituasjoner og flere interne datakilder
Det er gjort en enkel utvidelse av responsen til HealthRecordAccessLog for å kunne tilrettelegge for at RHFet skal kunne gi Helsenorge en feilkode ved spesifikke feilsituasjoner. Om RHFet ikke har tilrettelagt for innsyn på vegne av barn 12-16 år kan RHFet returnere en respons med HTTP Status Code 200 (OK) og feilkoden RepresentationBelowMinimumAgeError. På denne måten kan Helsenorge informere innbyggerne om hvorfor de ikke kan se innsyn gjort mot et spesifikt RHF.
For å legge til denne utvidelsen må det legges til et XML-namespace i HealthRecordAccessLog og en ErrorList-node under denne. ErrorList-noden kan inneholde en eller flere Error-noder med properties codeContext, errorCode og location.
Properties i Error-noden
Property | Verdi | Beskrivelse |
|---|---|---|
codeContext | Det er ikke tilrettelagt for innsyn for barn 12-16 | Tekstlig beskrivelse av feilårsaken |
errorCode | RepresentationBelowMinimumAgeError | Feilkode - Se eksempler under |
location | 2.16.578.1.12.4.3.1.4.20.1 | OID som representerer RHFet, HFet/DIPS-installasjonen feilen stammer fra |
Eksempel på utvildelse
<HealthRecordAccessLog xmlns:i="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://DIPS.no/ServiceBroker/HealthRecordAccessLog"
xmlns:hralext="urn:no:ehelse:tilgangslogg:ext">
<TotalItemCount>0</TotalItemCount>
<hralext:ErrorList>
<hralext:Error codeContext="An error occurred while sending the request."
errorCode="UnavailableCommunity"
location="2.16.578.1.12.4.3.1.4.20.1"/>
</hralext:ErrorList>
<LogItems/>
</HealthRecordAccessLog>Feilkoder
Følgende feilkoder kan returneres av endepunktene for å kunne gi en forbedret feilmelding til innbyggeren. Se eksempelrespons for HealthRecordAccessLog for hvordan feilkodene kan brukes i en respons.
ErrorCode | Location | Beskrivelse |
UnavailableCommunity | OID som representerer HR | Brukes i de tilfeller hvor RHFet har flere enn ett endepunkt, slik at det er mulig å identifisere hvilket HF som ikke returnerer data |
RepresentationBelowMinimumAgeError | OID som representerer RHF | Brukes i de tilfeller hvor RHF ikke tillater innsyn ved representasjon av en barns aldergsgruppe |
RateLimitExceeded | OID som representerer RHF eller HF | Brukes i de tilfeller hvor RHF eller HF må stoppe trafikk på grunn av stor pågang. |
DocumentAccessLog
HTTP Request
Spørringen er et POST-kall med parametere i bodyen i JSON-format. Dette gjør at Content-Type i headeren alltid er satt til application/json. Responsen er XML-formatert og Accept i headeren vil verdien application/xml.
Parametere
Navn | Type | Påkrevd |
nationalId | String | Ja |
staffid | String | Ja |
staffIdType | string | Ja |
from | Dato | Nei |
to | Dato | Nei |
pageno | Integer | Nei |
pagesize | Integer | Nei |
simplify | Boolean | Nei |
showFirstAccessTime | Boolean | Nei |
repositoryId 2 | String | Ja 2 |
2 repositoryId er kun påkrevd og en nødvendig tilpasning når endepunktet inneholder flere interne DIPS-instanser
Tilpasninger ved flere interne datakilder
Det er lagt til en repositoryId-parameter på spørringen. Verdien for denne parameteren kommer fra RepositoryUniqueId i ListItem fra HealthRecordAccessLog-responsen og er kun påkrevd om endepunktet har flere interne datakilder/DIPS-installasjoner og har behov for å kunne identifisere hvilken datakilde DocumentAccessLog-spørringen skal gå mot. Om endepunktet kun har en datakilde har feltet verdien null eller så er ikke feltet med i spørringen.
HTTP Respons
Det har ikke vært nødvendig med tilpasninger på tjenestens respons og er dermed i henhold til Dips' egne spesifikasjoner. Om det er flere interne datakilder som skal svare på denne spørringen er det mulig å utvide responsen med en liste med feil. Se “Tilpasninger ved feilsituasjoner og flere interne datakilder“ under HealthRecordAccessLog.
DocumentAccessLog/accessReasonId
HTTP Request
Spørringen er et POST-kall med parametere i bodyen i JSON-format. Dette gjør at Content-Type i headeren alltid er satt til application/json. Responsen er XML-formatert og Accept i headeren vil verdien application/xml.
Parametere
Navn | Type | Påkrevd |
nationalId | String | Ja |
accessReasonId | Guid | Ja |
hfInternalId | integer | Ja |
from | Dato | Nei |
to | Dato | Nei |
pageno | Integer | Nei |
pagesize | Integer | Nei |
simplify | Boolean | Nei |
showFirstAccessTime | Boolean | Nei |
repositoryId 2 | String | Ja 2 |
2 repositoryId er kun påkrevd og en nødvendig tilpasning når endepunktet inneholder flere interne DIPS-instanser
Tilpasninger ved flere interne datakilder
Det er lagt til en repositoryId-parameter på spørringen. Verdien for denne parameteren kommer fra RepositoryUniqueId i ListItem fra HealthRecordAccessLog-responsen og er kun påkrevd om endepunktet har flere interne datakilder/DIPS-installasjoner og har behov for å kunne identifisere hvilken datakilde DocumentAccessLog-spørringen skal gå mot. Om endepunktet kun har en datakilde har feltet verdien null eller så er ikke feltet med i spørringen.
HTTP Respons
Det har ikke vært nødvendig med tilpasninger på tjenestens respons og er dermed i henhold til Dips' egne spesifikasjoner. Om det er flere interne datakilder som skal svare på denne spørringen er det mulig å utvide responsen med en liste med feil. Se “Tilpasninger ved feilsituasjoner og flere interne datakilder“ under HealthRecordAccessLog.
DocumentAccessLog/SubjectIdentifier
HTTP Request
Spørringen er et POST-kall med parametere i bodyen i JSON-format. Dette gjør at Content-Type i headeren alltid er satt til application/json. Responsen er XML-formatert og Accept i headeren vil verdien application/xml.
Parametere
Navn | Type | Påkrevd |
nationalId | String | Ja |
subjectIdentifierId | String | Ja |
subjectIdentifierSystem | String | Ja |
subjectIdentifierAssigner | String | Ja |
from | Dato | Nei |
to | Dato | Nei |
pageno | Integer | Nei |
pagesize | Integer | Nei |
simplify | Boolean | Nei |
showFirstAccessTime | Boolean | Nei |
repositoryId 2 | String | Ja 2 |
2 repositoryId er kun påkrevd og en nødvendig tilpasning når endepunktet inneholder flere interne DIPS-instanser
Tilpasninger ved flere interne datakilder
Det er lagt til en repositoryId-parameter på spørringen. Verdien for denne parameteren kommer fra RepositoryUniqueId i ListItem fra HealthRecordAccessLog-responsen og er kun påkrevd om endepunktet har flere interne datakilder/DIPS-installasjoner og har behov for å kunne identifisere hvilken datakilde DocumentAccessLog-spørringen skal gå mot. Om endepunktet kun har en datakilde har feltet verdien null eller så er ikke feltet med i spørringen.
HTTP Respons
Det har ikke vært nødvendig med tilpasninger på tjenestens respons og er dermed i henhold til Dips' egne spesifikasjoner. Om det er flere interne datakilder som skal svare på denne spørringen er det mulig å utvide responsen med en liste med feil. Se “Tilpasninger ved feilsituasjoner og flere interne datakilder“ under HealthRecordAccessLog.
DocumentAccessLog/SubjectQualificationIdentifier
HTTP Request
Spørringen er et POST-kall med parametere i bodyen i JSON-format. Dette gjør at Content-Type i headeren alltid er satt til application/json. Responsen er XML-formatert og Accept i headeren vil verdien application/xml.
Parametere
Navn | Type | Påkrevd |
|---|---|---|
nationalId | String | Ja |
subctQualifIdentifierId | String | Ja |
subctQualifIdentifierIdSystem | String | Ja |
subctQualifIdentifierIdAssigner | String | Ja |
from | Dato | Nei |
to | Dato | Nei |
pageno | Integer | Nei |
pagesize | Integer | Nei |
simplify | Boolean | Nei |
showFirstAccessTime | Boolean | Nei |
repositoryId 2 | String | Ja 2 |
2 repositoryId er kun påkrevd og en nødvendig tilpasning når endepunktet inneholder flere interne DIPS-instanser
Simplify-parameter
Fra DIPS Service Broker Health Record Access Log dokumentasjon v4.0
By default, each operation a "healthcareparty" does on a document becomes one row in the documentaccesslog. "Simplify" merges all rows with same "healthcareparty" and document to one row. Following rules applies to values that are merged.
Value | Merge rule |
AccessType | Allways set to value 2, enum value "Innsyn" |
TimeOfAccess | Last time accessing the document |
Notes | Last notes recorded with value |
Tilpasninger ved flere interne datakilder
Det er lagt til en repositoryId-parameter på spørringen. Verdien for denne parameteren kommer fra RepositoryUniqueId i ListItem fra HealthRecordAccessLog-responsen og er kun påkrevd om endepunktet har flere interne datakilder/DIPS-installasjoner og har behov for å kunne identifisere hvilken datakilde DocumentAccessLog-spørringen skal gå mot. Om endepunktet kun har en datakilde har feltet verdien null eller så er ikke feltet med i spørringen.
HTTP Respons
Det har ikke vært nødvendig med tilpasninger på tjenestens respons og er dermed i henhold til Dips' egne spesifikasjoner. Om det er flere interne datakilder som skal svare på denne spørringen er det mulig å utvide responsen med en liste med feil. Se “Tilpasninger ved feilsituasjoner og flere interne datakilder“ under HealthRecordAccessLog.
Eksempler
HealthRecordAccessLog
Spørring
{
"nationalId": "12345678900",
"from": "2018-05-22T00:00:01",
"to": "2018-05-22T23:59:59",
"pageno": null,
"pagesize": null
}
Respons
<HealthRecordAccessLog xmlns:i="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://DIPS.no/ServiceBroker/HealthRecordAccessLog"
xmlns:hralext="urn:no:ehelse:tilgangslogg:ext">
<TotalItemCount>2</TotalItemCount>
<hralext:ErrorList>
<hralext:Error codeContext="An error occurred while sending the request."
errorCode="UnavailableCommunity"
location="2.16.578.1.12.4.3.1.4.20.1"/>
</hralext:ErrorList>
<LogItems>
<LogItem>
<AccessReason>
<Comment i:nil="true"/>
<Type>DecisionBased</Type>
<Value>Åpen konsultasjonsserie</Value>
</AccessReason>
<AccessingPerson>
<Department>
<Name>Sykehuspartner</Name>
<ReshId i:nil="true"/>
<ShortName>SP</ShortName>
</Department>
<FirstName>Elsa Louise</FirstName>
<Identifier>
<Type>InternalId</Type>
<Value>60969496</Value>
</Identifier>
<LastName>Popov</LastName>
<Position>IT DIPS Forvalter</Position>
</AccessingPerson>
<EndTime>2018-05-22T21:49:13</EndTime>
<HFInternalId>1</HFInternalId>
<HFname>Oslo universitetssykehus HF</HFname>
<OrganisationNumber>993467049</OrganisationNumber>
<Organization>Oslo universitetssykehus HF</Organization>
<RegionalLogAccessItem> </RegionalLogAccessItem>
<RepositoryUniqueId>2.16.578.1.12.4.3.1.1.20.22</RepositoryUniqueId>
<StartTime>2018-05-22T15:49:13</StartTime>
<hralext:RepositoryId>2.16.578.1.12.4.3.1.1.20.2</hralext:RepositoryId>
</LogItem>
<LogItem>
<AccessReason>
<Comment i:nil="true"/>
<Type>None</Type>
<Value>Clinical care provision to an individual subject of care</Value>
</AccessReason>
<AccessingPerson>
<Department>
<Name i:nil="true"/>
<ReshId i:nil="true"/>
<ShortName i:nil="true"/>
</Department>
<FirstName>LISBETH PSA</FirstName>
<Identifier>
<Type>InternalId</Type>
<Value/>
</Identifier>
<LastName>HEGGEDAL</LastName>
<Position>Sykepleier</Position>
</AccessingPerson>
<EndTime>2021-03-11T13:27:19</EndTime>
<HFInternalId>1</HFInternalId>
<HFname>Oslo universitetssykehus HF</HFname>
<OrganisationNumber>993467049</OrganisationNumber>
<Organization>Andeby sykehus</Organization>
<RegionalLogAccessItem>
<AccessReasonId>a15e9229-8d5b-4044-b25c-52ca8249edae</AccessReasonId>
<Accesstype>h</Accesstype>
<Purposeassigner>ISO 14265 Classification of Purposes for processing personal health information</Purposeassigner>
<Purposedescription>Clinical care provision to an individual subject of care</Purposedescription>
<Purposeid>1</Purposeid>
<Purposesystem>1.0.14265.1</Purposesystem>
<Subjectassigner>Skatteetaten</Subjectassigner>
<Subjectchildorgassigner i:nil="true"/>
<Subjectchildorgid i:nil="true"/>
<Subjectchildorgname i:nil="true"/>
<Subjectchildorgsystem i:nil="true"/>
<Subjectid>10086400478</Subjectid>
<Subjectname>LISBETH PSA HEGGEDAL</Subjectname>
<Subjectorgassigner>Brønnøysundregistrene</Subjectorgassigner>
<Subjectorgid>999977774</Subjectorgid>
<Subjectorgname>Andeby sykehus</Subjectorgname>
<Subjectorgsystem>2.16.578.1.12.4.1.4.101</Subjectorgsystem>
<Subjectqualificationassigner>Helsedirektoratet</Subjectqualificationassigner>
<Subjectqualificationid>222200052</Subjectqualificationid>
<Subjectqualificationname i:nil="true"/>
<Subjectqualificationsystem>2.16.578.1.12.4.1.4.4</Subjectqualificationsystem>
<Subjectroleassigner>ISO</Subjectroleassigner>
<Subjectroleid>SP</Subjectroleid>
<Subjectrolename>Sykepleier</Subjectrolename>
<Subjectrolesystem>2.16.578.1.12.4.1.1.9060</Subjectrolesystem>
<Subjectsystem>2.16.578.1.12.4.1.4.1</Subjectsystem>
</RegionalLogAccessItem>
<RepositoryUniqueId>2.16.578.1.12.4.3.1.1.20.22</RepositoryUniqueId>
<StartTime>2020-03-11T13:27:19</StartTime>
</LogItem>
</LogItems>
</HealthRecordAccessLog>
Felter under namespace urn:no:ehelse:tilgangslogg:ext er kun nødvendig om det er flere interne DIPS-instanser som skal returnere data
DocumentAccessLog
Spørring
repositoryId verdi er kun nødvendig om det er flere interne DIPS-instanser som har returnert data
Respons
DocumentAccessLog/accessReasonId
Spørring
repositoryId er kun nødvendig om det er flere interne DIPS-instanser
Respons
Se respons for DocumentAccessLog
DocumentAccessLog/SubjectIdentifier
Spørring
repositoryId er kun nødvendig om det er flere interne DIPS-instanser som har returnert data.
Respons
Se respons for DocumentAccessLog
DocumentAccessLog/SubjectQualificationIdentifier
Spørring
repositoryId er kun nødvendig om det er flere interne DIPS-instanser som har returnert data.
Respons
Se respons for DocumentAccessLog