| Table of Contents |
|---|
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.
...
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.
...
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
...
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 encrypted base64 string.
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 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. More information can be found at https://helseid.readthedocs.io/no/latest/
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.
...
| Table excerpt | ||
|---|---|---|
| ||
Successful response example |
| Table excerpt | ||
|---|---|---|
| ||
Error response example |
Security
The Health indicator service requires a system access token (JWT) from HelseID.
...
Ask specifically for the scope
https://ehelse.no/kjernejournal/kj_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.
...
| Info |
|---|
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
...