Instructions

Instructions

Authorization

The PHR platform utilizes the OAuth 2.0 protocol for authorization.

The authorization profiles and models used on the platform are described in the PHR authorization guide (pdf). The guide contains references to the appropriate OAuth 2.0 specifications.

HL7 FHIR

Kanta PHR and the data it contains are based on the HL7 FHIR standard. Use of the HL7 FHIR standard in Kanta PHR is described in the document titled Implementation Guide. This guide is designed for specifiers and developers who need information about the FHIR resources, elements and extensions used in Kanta PHR.

The Kanta PHR platform only supports the JSON format, which means that all resources must be stored on the platform in the JSON format.

Declaring reference to and conformance with a profile confirmed as part of the Kanta PHR national data content is mandatory. The server validates the content of the resource being stored against the specified profile, and rejects any resource whose content does not conform to the profile.

Reference to the profile is declared by including the URL for the profile in the resource metadata:

{
    "resourceType": "Patient",
    …
    "meta": {
       "profile": [
          “http://phr.kanta.fi/StructureDefinition/fiphr-patient-stu3”
     ]
},
…
 

Development community PH SIG

New content added to Kanta PHR is presented and approved at monthly online commentary meetings of the Kanta PHR support project (PH SIG). Also suggestions for new content can be made at the meetings. The meetings are a forum for providing guidance on the use of the FHIR standard and national data content. Agendas for the meetings and instructions for joining are posted on the PH SIG website.

Use cases

Descriptions of the most common use cases from the viewpoint of the application to be integrated (descriptions are in Finnish only).

Laws and statutes

Wellbeing applications integrated with Kanta PHR must conform to prevailing laws, decrees and statutes. It is recommended to review these provisions  as part of the application development process.

Log files

With server-based wellbeing applications, it is recommended that transaction histories should be recorded in log files. However, sensitive health or wellbeing data should not be stored in log files.

Programming interfaces

The Capability Statement for Kanta PHR can be read in the Simplifier profile registry. It describes the supported REST interactions and lists the available search parameters. Actions allowed by wellbeing applications must be included in the Kanta PHR Capability Statement.

Please note that non-citizen resources cannot be retrieved from the PHR production environment or client test environment. Such resources include

  • profiles
  • ValueSet
  • CodeSystem
  • Questionnaire 
  • CapabilityStatement.

However, these resources can be retrieved from Simplifier, which provides an interface for this purpose.

Lifetime of the refresh token

The refresh token for server-based applications expires after one year if integration has not been used, in which case users must renew the application’s permissions.

The application must check that the user’s access token is valid. The access token is updated as needed for example when data on wellbeing are recorded.

Applications may not extend the validity of the refresh token without the user’s permission.

Glossary of terms

The glossary of terms  describes briefly the terminology and concepts related to Kanta PHR. The descriptions have been formulated specifically to fit the context of Kanta PHR and wellbeing applications.

Concepts and terms associated with Kanta PHR are also defined in the list of Kanta terminology compiled by the Finnish Institute for Health and Welfare (in Finnish).

Accessibility of the application

It is requested that attention should be paid to the accessibility of wellbeing applications to ensure that they are accessible also by persons with physical or cognitive impairments. Accessibility-related design principles may be consulted for example in the W3C Accessibility Standards Overview published by the World Wide Web Consortium (W3C).

Update frequency of end user visible data

The type of data recorded in the wellbeing application and the frequency of measurements factor into how often the data should be made available to the user in Kanta PHR. In the case of isolated measurements that occur two or three times a day or less frequently (e.g. blood pressure), the results should be made available in Kanta PHR as quickly as possible.

When it comes to a series of measurements or a set of measurements made over a longer period of time (such as the number of steps taken per day), the results are not imported into Kanta PHR until the final result is known.

Information security

An information security risk assessment must be carried out during the development of the application. Any threats or risks to information security discovered in the assessment must be managed effectively. The information security requirements for Class A systems, for instance, can be applied here.

Server applications, installations and environments must be protected and the protections documented.

User authentication

Strong authentication is required when a user wishes to authorise an application to access the Kanta PHR. The user is forwarded to the Suomi.fi service to perform the authentication. Single sign-on (SSO) is used if the user has already performed authentication during the same session.

Sign-on to the wellbeing application is permitted also without strong authentication. However, the application must check that the user is the person who acquired the permissions.

Sign-on is not required in native applications, but users must be informed of the data protections.

Importing legacy data

Data recorded in a wellbeing application prior to its integration with Kanta PHR can be imported into Kanta PHR. Legacy data can be imported as a background operation that stores the data as a gradual process.

In case of a large volume of data, it is advisable to contact Kela to agree on the method of data transfer on a case-by-case basis

Last updated 22.12.2023