Integration Guide: Kjernejournal REST API using HelseID as authenticator
- 1 Introduction
- 1.1 Purpose
- 1.2 Target audience
- 1.3 Limitations
- 2 Solution description
- 3 Integration description
- 3.1 Health indicator service
- 3.1.1 Advcanced request and response
- 3.1.2 Error response example
- 3.1.3 Security
- 3.2 Patient context
- 3.3 Ping service
- 3.4 Activation
- 3.5 Endpoints
- 3.6 Related error codes
- 3.1 Health indicator service
Introduction
This is a specification for the technical integration with the different REST APIs that are available from kjernejournal.
Purpose
The purpose is to clarify the premises for the technical organization of the EHR vendor for integration with the API's available from kjernejournal, using HelseID as authenticator. It does not include details on input and output to the various API's, see the page Kjernejournal API-integrasjon for links to the pages with detailed information about the APIs and Swagger documentation.
Target audience
The target audience for this document are technical resources and project management with a responsibility for implementing an integration with kjernejournal.
Limitations
This document is limited to the services and needs that support integration.
This document do not include
establishment of operating routines
establishment of monitoring routines
integration with HelseID to obtain the necessary security tokens for communicating with kjernejournal.
Solution description
The vendor can choose to integrate with several of the kjernejournal APIs. , Norsk helsenett can assist the vendor in assessing which APIs that are relevant for their EHR system and their end-users.
An API-integration with kjernejournal requires:
Integration with Health indicator Rest service that indicates whether the patient has kjernejournal or not.
Development of dialogs where the information requested from kjernejournal is presented to the end user.
Development of dialogs where end user registers the information that is uploaded to kjernejournal (Alert information).
When the user opens a new patient, the EHR system should make an API call to kjernejournal’s health indicator API, which indicates if the patient is registered in kjernejournal, and if any critical information is registered. The EHR system changes the appearance of the kjernejournal icon according to the response from the health indicator API, to signify to the user the level of information that exists in kjernejournal for the patient.
For the different APIs the workflow will vary in the EHR system. The vendor has great freedom to choose the appearance of dialogs that are needed for the integration. Norsk helsenetts requirements are focusing on that the data shall be presented correctly and user-friendly.
Workflow using HelseID and API's from kjernejournal
Main functional steps
The client requests and receives a system token from HelseID, which includes the organization number.
The client then sends the signed system token and a patient nin to kjernejournal, which authorizes the organization and creates a ticket that represents both the organization number and the patient.
The client then requests and receives a user token from HelseID. Typically they are authenticated using Buypass or Commfides.
The client then sends both the ticket from kjernejournal, as well as the signed user token to the actual API, which then authorizes the user and responds
The client receives the data from kjernejournal
Note that this is not a required order. The client is free to do step 3 before step 2, or to do step 3 as the user logs onto the client and just store the user token until it is needed.
In these steps, tokens are issued by HelseID, while the ticket is issued by kjernejournal in step 2. Tokens are in jwt format and signed by HelseID, while the ticket is an opaque string only useful for kjernejournal.
Authentication of health personell
All API's in kjernejournal require both the ticket described above, but also a user access token (JWT) from HelseId. The EHR must implement HelseID authentication, and must contact HelseID for information. Typically this is done through a web browser, but the EHR is free to do this is any way that is acceptable to HelseID.
The user access token must have the scope nhn:kjernejournal/api. The token must also have the claims https://nhn.no/claims/identity/pid and https://nhn.no/claims/identity/security_level. Only tokens with security level 4 will the accepted.
The token must be attached as a Bearer token i requests to Kjernejournal API's. Typically EHR will use an Authorization code grant with HelseId to get a token. This flow is not described in detail here as it is a Oauth2/OIDC standard.
See helseid.no and https://utviklerportal.nhn.no/informasjonstjenester/helseid/ for more information about integrating with HelseID. NB! KJ APIs require access tokens with the API Resource as the only audience, see doc at https://helseid.atlassian.net/wiki/spaces/HELSEID/pages/481755152/Requesting+multiple+access+tokens+with+single+audiences
Integration description
All requests to kjernejournals API's are done in two steps.
First a client token is sent to authenticate the organization, and a ticket is returned.
Secondly a user token is sent together with the ticket, which together authenticates both the user and the organization, and gives access to the API. Note that a ticket is valid for one hour, and can be reused for that time. As the ticket contains the patients nin, it will only be valid for the specific patient used in the first step.
Health indicator service
The Health indicator REST service returns the patients status in kjernejournal.
It’s a POST to /v1/helseindikator, with a JSON body (Content-type: application/json) with the following input:
Input:
Field | Location | Required | Description |
|---|---|---|---|
fnr | Body | Yes | Patient identifier (Norwegian national identity number). |
legemiddelFraDato | Body | No | Optional parameter for information about prescriptions. Example: 2021-06-11 |
samtykke | Body | No | Consent for opening the patient’s kjernejournal (used if the ticket from the response is later used to access the patient’s kjernejournal). Can be one of the following values:
This parameter should be sent for API integrations. |
Authorization | HTTP Header | Yes | A token from HelseID sent as a bearer token. |
X-EPJ-System | HTTP Header | Yes | Which EHR system, and which version, the request originated from.
|
Output in case of successful request:
Field | Location | Description |
|---|---|---|
eksistererBlokkertHelsepersonell | Body | Boolean. Because Kjernejournal does not control the information once it is shared, no clinical information will be shared if the patient has blocked at least one person. Only useful for API integration. |
harLasteResepter | Body | Boolean. Indicates if the patient has locked prescriptions. |
harLegemidler | Body | Boolean. Indicates if the patient has any prescriptions or multidose drug prescriptions. |
status | Body | One of the following values:
Is to be used to determine what icon should be shown to the user. |
sistEndretKritiskInfo | Body | Shows a timestamp for last change for each category of critical information for patients with status 4. Only present if the status is 4. |
sistEndretKritiskInfoDato | Body | Timestamp for last change in information for patients with status 4. Only present if the status is 4. |
returTekst | Body | Description of the response status. Is to be used in the tooltip of the icon. |
ticket | Body | An opaque string which represents:
Is to be used in the subsequent opening of the portal. Only present if the status is 2 or higher. |
eksistererBlokkertHelsepersonell | Body | Boolean. Because Kjernejournal does not control the information once it is shared, no clinical information will be shared if the patient has blocked at least one person. Only useful for API integration. |
harLasteResepter | Body | Boolean. Indicates if the patient has locked prescriptions. |
sperringDetaljer | Body | Indicates which modules of kjernejournal that the patient has locked. |
X-EVENT-ID | Header | The ID of the request in kjernejournal. Can be used for debugging and correlation between the systems. |
All API responses from kjernejournal may have an arbitrary gibberish extra field. This is to ensure that consumers can handle new fields in the response.
See swagger documentation: https://api.st2.kjernejournal-test.no:8000/v1/helseindikator/swagger-ui.html
Request example
POST /v1/helseindikator/ HTTP/1.1
Host: api.kjernejournal.no:8000
Content-Type: application/json;charset=UTF-8
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IkE4...u_UjgeTxzxI2g
X-EPJ-System: ACME EHR system versjon 42.01
{"fnr":"13116900216"}
Successful response example
HTTP/1.1 200 OK
Cache-Control: no-cache, must-revalidate, private, s-maxage=0
Pragma: no-cache
Content-Type: application/json; charset=utf-8
{
"returTekst": "OBS: Kritisk informasjon i kjernejournal",
"sistEndretKritiskInfoDato": "2017-11-29T16:35:19.003Z",
"status": 4,
"ticket": "ca2gveFcW%2BdZqO2Fx7EG773Lh0TUvO2gtz45gQCbbUrKpXBJf8yS3ROacFn%2Bq"
}
Advcanced request and response
Typically used for API integration
POST /v1/helseindikator/ HTTP/1.1
Host: api.kjernejournal.no:8000
Content-Type: application/json;charset=UTF-8
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IkE4...u_UjgeTxzxI2g
X-EPJ-System: ACME EHR system versjon 42.01
{
"fnr": "13116900216",
"legemiddelFraDato": "2021-06-11",
"samtykke": "HPMOTTATTSAMTYKKE"
}Note. The request should include the HTTP header "X-EPJ-System" that describes which EHR the request originated from and which version of the system was used.
Successful response example
Error response example
Security
The Health indicator service requires a system access token (JWT) from HelseID.
The EHR must implement HelseID authorization of the client based on the Client Credentials Grant flow. HelseID must be contacted for information on how to do this.
Information about the flow can be found here Welcome to HelseID’s technical documentation! — HelseID documentation.
When the EHR system requests an access token from HelseID, it must:
Ask specifically for the scope
nhn:kjernejournal/apiUse either an enterprise certificate or RSA key (not client secret)
Patient context
The EHR shall ensure that health personnel can not mix different patients together in the EHR and kjernejournal. This is an essential requirement for both the EHR and kjernejournal. This must be assured through comprehensive testing.
The patient must be registered in the local EHR system's patient register with birth or D-number in order to open the patient's kjernejournal. Norsk helsenett wants the EHR provider to deliver a detailed solution design around this topic.
Ping service
Kjernejournal also exposes a simple ping service, which can be used to test system authentication without opening a patient. It is not required to make use of this service, but it can be useful to use it as a method to verify connectivity and that the organization has been granted access to kjernejournal. This is usually implemented as a “test connection” button in the settings, and the error message here should be as detailed as possible (including stack trace or similar), as it is used by technical personnel.
It is a simple GET to /v1/ping. The authentication and error responses are identical to the health indicator service.
Input:
Field | Location | Required | Description |
|---|---|---|---|
Authorization | HTTP Header | Yes | A token from HelseID sent as a bearer token. |
X-EPJ-System | HTTP Header | Yes | Which EHR system, and which version, the request originated from.
|
Output in case of successful request:
Field | Location | Description |
|---|---|---|
Pong | Body | Timestamp |
X-EVENT-ID | Header | The ID of the request in kjernejournal. Can be used for debugging and correlation between the systems. |
Request example
Response example
All API responses from kjernejournal may have an arbitrary gibberish extra field. This is to ensure that consumers can handle new fields in the response.
Activation
The kjernejournal Integration must be placed behind a toggle function, so that it can be (de)activated on an installation basis. It should also be possible to choose which user group or users that have access to the kjernejournal integration.
Endpoints
Service | Environment | URL |
|---|---|---|
API | Test | |
API | Prod |
Related error codes
See https://kjernejournal.atlassian.net/wiki/spaces/KJERNEJOURDOK1/pages/664635127
© Norsk helsenett - kjernejournal