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

1. The client requests and receives a system token from HelseID, which includes the organization number.

2. 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.

3. The client then requests and receives a user token from HelseID. Typically they are authenticated using Buypass or Commfides.

4. 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

5. 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:

Output in case of successful request:

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

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

{
  "eksistererBlokkertHelsepersonell": false,
  "harLasteResepter": true,
  "harLegemidler": true,
  "returTekst": "OBS: Kritisk informasjon i kjernejournal",
  "sistEndretKritiskInfo": [
    {
      "kategori": "OVER_REAK",
      "sistEndret": "2017-11-29T16:35:19.003Z"
    }
  ],
  "sistEndretKritiskInfoDato": "2017-11-29T16:35:19.003Z",
  "sperringDetaljer": [
    {
      "erSperret": false,
      "modul": "KRITISKINFO"
    }
  ],
  "status": 4,
  "ticket": "ca2gveFcW%2BdZqO2Fx7EG773Lh0TUvO2gtz45gQCbbUrKpXBJf8yS3ROacFn%2Bq"
}

Error response example

HTTP/1.1 403 FORBIDDEN
Cache-Control: no-cache, must-revalidate, private, s-maxage=0
Pragma: no-cache
Content-Type: application/json; charset=utf-8

{
    "status" : 403,
    "utviklermelding" : "Her kan det stå en mer spesifikk tekst som hjelper utvikler av API-klient litt mer enn feilmeldingen som kan vises til bruker",
    "brukermelding" : "Virksomheten har ikke tilgang til kjernejournal",
    "feilkode" : "KJF-000227"
}

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/api

• Use 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:

Output in case of successful request:

Request example

GET /v1/ping/ HTTP/1.1
Host: api.kjernejournal.no:8000
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IkE4...u_UjgeTxzxI2g
X-EPJ-System: ACME EHR system versjon 42.01

Response example

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Pragma: no-cache
X-EVENT-ID: Id-93f2826025992c6dc91b8cfd
Content-Type: application/json

{
  "pong" : "2021-04-23T16:15:15.973Z",
  "imperdieteleifendcommodo" : "Ukjent felt skal støttes av konsument"
}

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

Related error codes

See Error codes and messages