1 Introduction
- 1.1 Purpose
- 1.2 Target audience
- 1.3 Limitations
2 Solution description
- 2.1 Workflow using HelseID and API's from kjernejournal
  - 2.1.1 Main functional steps
- 2.2 Authentication of health personell
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

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 HelseID - NHN Utviklerportal for more information about integrating with HelseID. NB! KJ APIs require access tokens with the API Resource as the only audience, see doc at 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

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: `HPMOTTATTSAMTYKKE` `HPAKUTT` `HPUNNTAK` 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

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: `0`: The patient identifier is not a valid Norwegian national identity number `1`: The patient do not have kjernejournal `2`: Kjernejournal is available `3`: Patient has filled in health information (illness history, communication issues) `4`: Attention: The patient has critical information registered in kjernejournal 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.
sistEndretKritiskInfoDato	Body	Timestamp for last change on critical information.
returTekst	Body	Description of the response status. Is to be used in the tooltip of the icon.
ticket	Body	An opaque string which represents: the user's organization the patient the consent given for opening the patient's kjernejournal (if present in the request) 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/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:

Field	Location	Required	Description

Field

Location

Required

Description

Authorization

HTTP Header

Yes

A token from HelseID sent as a bearer token.

X-EPJ-System