Sandbox environments

Sandbox environments

Two sandbox environments have been established and are available for developers. Developers are encouraged to use the sandbox environments, while developing and testing new PHR applications.

Both of the sandboxes contain same data that can be accessed with or without authorization features by choosing sandbox or sandbox2 interfaces.

Sandboxes are not production servers. Storing personal health data or other confidential information about real people is strictly forbidden. Kela does not take responsibility over any data stored by sandbox users. Kela cannot commit to making the environments accessible at all times, but will take efforts to do so.

The implementations of the sandbox servers are based on HAPI-FHIR library and the RESTful Server provided along with it. A RESTful Client with a graphical user interface and essential tools for developers are also provided with the sandbox environment. Read more information about HAPI-FHIR (github.com).

Data will be deleted from the sandbox environments regularly on the 1st of March, June, September and December, or the first following working day. The data that will be deleted includes all Patient related resources (e.g. Observation, CarePlan, MedicationAdministration resources) that have been stored in the sandbox more than three months ago.

Sandbox without authorization functionality

A publicly accessible FHIR sandbox environment is available at https://fhirsandbox.kanta.fi. Application suppliers are invited to start exploring the FHIR standard and developing first applications using this sandbox environment.

No registration is needed at the moment, and security-related protocols such as OAuth 2.0 are not supported in this sandbox. This also means that any data stored at the server can be removed at any time by anyone.

In order to store a patient’s resources in this sandbox environment, you first need to create a Patient resource yourself (see instructions) to be able to store resources for a patient.

Sandbox with authorization

Authorization service in sandbox is located at https://fhirsandbox-ui.kanta.fi/.

Resource server is located at https://fhirsandbox2.kanta.fi/phr-resourceserver/baseStu3.

Self-registration is required in order to use authorization functionalities. In order to register a new user (software developer), go to Kanta PHR Sandbox Management Service (kanta.fi) and provide your details. NB! Please ensure you keep the password you choose in mind. Unfortunately, resetting your password is not currently possible. If you forget your password, you will have to register as a new user and register a new client (see instructions below) as well.

After registration, log in and choose "Self-service Client Registration". Register a new client by entering its details. The service will generate a client ID, a client secret, a client configuration URL, and a registration token. Please remember to save this information, as it will be required in authorization requests (see The PHR authorization guide for the sandbox environment) and for any modification of the client properties in the future.

In this sandbox environment, the Patient resource will be created by the PHR platform during the authorization code flow, so there’s no need to create the Patient resource yourself. Note however, that the social security numbers you use in the authorization code flow should follow the format of the Finnish social security number (the server will validate it) and should be of the 900-series social security numbers meant to be used for testing. Please note that all data stored in the sandbox is public. Also, it is possible to find out all the social security numbers used in the environment. 

Adding new profiles and resources to the sandbox environment

Declaring conformance to a profile in a resource is mandatory in the sandbox environment, either to a profile that has already been accepted in the national Finnish PHR data content or a completely new profile. You can add your own profile to the sandbox environment for testing by yourself. NB! New resource types are not supported automatically by the Kanta PHR platform. Only resource types listed under "Resources" in Sandbox HAPI (or in capability statement of Sandbox server) are supported. New resource types that aren’t yet supported should be brought to the development process of the national data content as a development proposal.

When a resource declaring conformance to a certain profile is submitted to the resource server, the server will validate the resource against it, and will reject the resource if it does not comply with the profile.

The profile must be registered in the sandbox environment by storing its StructureDefinition. NB! If you want to update a profile you have already stored in the sandbox environment: Update the existing profile, don’t create another version of it with the same url. Resource validation won’t work correctly, if there exists multiple instances of the same profile with the same url.

  • The structure definitions are accepted only in JSON format.
  • They should be marked as experimental drafts. 
  • All the profiles have to have url starting with “http://phr.kanta.fi”, and the url and the id have to follow the rules described in the Finnish PHR profiling guidelines. Especially note that the profile shouldn’t have “fiphr” in the beginning of the id, instead you should replace it with something indicating the profile is for testing purposes. For example:
{
    "resourceType":"StructureDefinition",
    "id":"test1-patient-stu3",
    …
    "url":"http://phr.kanta.fi/StructureDefinition/test1-patient-stu3",
    …
}
  • In order for validation to work, the profile must include the snapshot of the base resource.
  • Additionally, the profile must include the meta and text fields of the base resource.
Last updated 7.6.2023