Integration description

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).
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
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
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.
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.
X-EVENT-ID	Header	The ID of the request in kjernejournal. Can be used for debugging and correlation between the systems.

Output in case of failed request:

Field	Location	Description
status	Body	The HTTP status of the response.
utviklermelding	Body	A developer friendly description of the error.
brukermelding	Body	A user friendly description of the error. Is to be used in the tooltip of the error icon.
feilkode	Body	An error code which is associated with the error condition. See list at the bottom.
X-EVENT-ID	Header	The ID of the request in kjernejournal. Can be used for debugging and correlation between the systems.

The response status decides which kjernejournal icon is to be displayed, as described in the “Kjernejournal icon” section. If the patient has status 0 or 1, or the request failed, the icon should not be clickable, as it is not possible to open kjernejournal on the patient.

The ticket in the response represents the organization, the patient, and optionally the consent given to access the patient’s kjernejournal, and is used to tie the health indicator request to the portal request. So this must be stored by the EHR system, and used when the user opens the kjernejournal portal.

The consent parameter in the health indicator request MUST NOT be specified if the EHR system only have portal integration with kjernejournal, as the user will be asked to specify consent when the patient’s kjernejournal is opened in the portal. The consent parameter is only to be used if the EHR system has both API and portal integration, and is used to reuse the consent from an API request in the portal.

The API lookup MUST NOT block the opening of the patient in the EHR. In the case of a timeout or slow response from KJ, the user MUST be able to use the EHR system normally.

Request example:

Request Example

Successful response example:

Successful Response Example

Failed response example:

Failed Response Example

Security

The Health indicator service requires a bearer token, which must be a client access token from HelseID (that authenticates the organization, not the user), so the EHR must retrieve a token from HelseID before calling kjernejournal.

Kjernejournal will not accept tokens with more than one audience, or which was authenticated with a client secret, so when the EHR system requests an access token from HelseID, it must:

• Ask specifically for the scope nhn:kjernejournal/api

• Use a signed JWT as client assertion (urn:ietf:params:oauth:client-assertion-type:jwt-bearer), signed with either an enterprise certificate or RSA key

As the volume of requests against the health indicator service quickly becomes quite high, the EHR system SHOULD re-use a token throughout its validity period, to reduce the amount of requests against HelseID. But it is vital that the token always represents the correct organization of the user, so if the EHR system supports multiple organizations, the token MUST NOT be shared between users of different organizations.

See helseid.no and dokumentasjon.helseid.no for more information about integrating with HelseID.

The portal

Get patient

If the Health indicator service returns a status with value 2 or higher, the user can open kjernejournal for the patient by clicking on the kjernejournal icon. This is done by the EHR system opening the “get patient url” in the embedded browser.

In order to connect the opening of the portal with the earlier health indicator request, the ticket from the health indicator response must be supplied as a parameter. This will ensure that the request is tied to the correct organization, and the correct patient is opened.

The service is available at /hpp-webapp/hentpasient and it takes the following parameters:

Example with ticket only 

https://KJERNEJOURNAL_URL/hpp-webapp/hentpasient?ticket=PmDvQLzdcnbkiYSmk8bym5iDRWPuUlkpsvMyxEXAiVkvjHzwItVizUXFeq7bQDgD

Hold session

The kjernejournal session should be “synchronized” with the usage of the EHR system, and this is done through the hold session mechanism. The kjernejournal session will last up to 12 hours, but the user will be logged out after 19 minutes of inactivity, so the EHR system must keep the kjernejournal session alive as long as the user is active in the EHR system. Active in the EHR system means general activity of the user in the EHR system, not limited to kjernejournal.

There are several reasons this is important for the user experience. Correct implementation of hold session will:

• avoid the need for repeated logons (not applicable with SSO)

• avoid the need for the user to repeatedly enter consent to open a patient’s kjernejournal, or unlock blocked tabs, when returning to a earlier patient

• avoid loss of information, if the user has entered information without saving it in the kjernejournal portal

Keeping the session alive is done by opening a special web page in the integrated browser, in the background, at a fixed interval (as long as the user is active). This should be hidden from the user, but the same browser context/environment must be used (so that it shares the same session cookies). The interval should be configurable, but default to 15 minutes.

The hold session service is available at /hpp-webapp/holdsesjon, and expects nothing more than a simple GET.

Session timer start 

The EHR must start the timer:

• When the kjernejournal icon is pressed for the first time in the EHR

OR

• When the browser is redirected from the login application to the original URL that was opened after a click on the kjernejournal icon. This provides a more accurate calculation of when the user's session started with the kjernejournal, but may be somewhat more complicated to implement.

Session timer stop

If the session is no longer valid, e.g. after 12 hours, or a manual logoff, the hold session request will end in a redirect. If that is to happen, then the hold session timer should stop. This can be implemented by checking the final page of the browser - if it is not the same as the one originally opened (/hpp-webapp/holdsesjon), then the session is no longer valid.

If the EHR system calls the Logout service (see below), the timer must also be terminated.

Session timer reset

If the timer has previously been terminated and the user opens kjernejournal again (see conditions under “Session timer start”), the EHR system should start the timer again.

Logout

The EHR system should terminate the kjernejournal session when the user logs off the EHR system, switches to another user, or shuts down the EHR system. This is done by opening the URL /hpp-webapp/logout in the embedded browser in the background. This will terminate the session on the kjernejournal side.

Additionally the EHR system MUST destroy all session cookies in the embedded browser, regardless of their domain.

Patient context

It is vital that there is no room for confusion about which patient is opened in the kjernejournal portal at any time, so the EHR system must take great care to ensure that the patient opened in kjernejournal is always the same as the one opened in the EHR. This means that if the user changes patients in the EHR, the kjernejournal browser must be closed or hidden.

If the EHR system reuses the browser instance between patients, it is important to clear the screen between patients, e.g. by loading about:blank, so that slow loading or network problems don’t show the old patient. Preferably a new browser instance/window is used for every patient (but it must share the same context/environment, so that session cookies are shared between them).

To summarize: The embedded browser MUST NOT, under any circumstances, show the the wrong/old patient in kjernejournal.

Browser requirements

Kjernejournal supports, and are testet in, Chromium based browsers. Therefore the browser component must be based on Chromium.

There is functionality for downloading PDFs in the kjernejournal portal, and the embedded browser must therefore support showing, printing and saving these. But if a user opens a PDF, it should not be saved to disk permanently by default. Either it should be opened in memory, or the temporary location should be cleared out when the EHR system shuts down.

Additionally, there are some requirements to make kjernejournal more closely integrated. When using the kjernejournal portal:

• there must not be an address field visible

• there must not be any navigation buttons visible

• there must not be any right click functionality

• Ctrl + A, Ctrl + C, Ctrl + V must work as expected

And it is important to remember that browsers are security critical software, and should be kept up to date.

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

Request sample

 

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.

Response sample

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

Errors that can be returned from the API (not all are applicable for the health indicator API):