Public Repository

Last pushed: 5 months ago
Short Description
REST version of the HIP toolkit
Full Description


REST based version of HIP SDK The application is based on Spring Boot spring-boot-starter-web.

The following services are included:

  • Aggregated care listings


The current versions of this image are listed below. The version is described by [HIP rest version] ([HIP SDK version])

  • 1.1.2-SNAPSHOT (2.1.10-SNAPSHOT)
  • 1.1-SNAPSHOT (2.1.9-SNAPSHOT)
  • 1.0-SNAPSHOT (2.1.9-SNAPSHOT)

Each HIP REST version is avalable as a tag.

Quick start

Assuming you have a development license file named license.lic in ~/.hip (see the section license below if you don't have one), start the container by running docker run -e SPRING_PROFILES=development -v ~/.hip/:/root/.hip -p 8080:8080 hipab/hip-rest:1.1-SNAPSHOT. You can now access the documentation on http://localhost:8080/api/v1/.

Installation and configuration


  1. Download and install Docker Toolbox
  2. To create a virtual machine, run docker-machine create -d virtualbox --virtualbox-memory 2048 default
  3. Create a file named docker-compose.yml that contains the following lines:
 image: hipab/hip-rest:1.1-SNAPSHOT
   SPRING_PROFILES: development
   hipsdk_profile: sdk-development
   - ./license:/root/.hip
   - “8080:8080”
  1. Make sure the directory license containing the file license.lic exists in the same working directory from where you run docker-compose up from.\
    The path to license in docker-compose.yml can also be altered if needed.

  2. Run docker-compose up -d

  3. See usage below for instructions on how to test the container

docker-compose.yml can be adjusted once you have verified the application runs in development mode.
Here you can alter profile, add other environment properties, which are passed to the application, adjust ports and so on.

Notes about Windows:
  • To define an absolute path to volumes, use the format /c:/<path to license>/:/root/.hip (for a file on drive c).
  • Ensure that the drive you share containing the license is shared in the docker application. Click here to read more.

Configuration of HIP-REST

The environment variable SPRING_PROFILE controls the HIP-REST profile
Available Profiles for HIP-REST are

  • development for development environment
  • production for production environment (production is in progress, not currently functional)

By default all modules are enabled. To only allow specific modules, list these in the environmental property[x]. The x is an index in an array, starting with 0 and incrementing by one for each module added.

Available modules are:

  • getalllistings (Aggregated Care Listing)
  • alert (Alert Information)
  • carecontact (Care Contact)
  • caredocumentation (Care Documentation)
  • careplans (Care Plan)
  • careservices (Care Service)
  • diagnose (Diagnosis)
  • ecgoutcome (Ecg Outcome)
  • functional-status (Functional Status)
  • imaging-outcome (Imaging Outcome)
  • laboratory (Laboratory Order Outcome)
  • maternity (Maternity)
  • medication-history (Medication History)
  • consent (Pdl Consent)
  • referral-outcome (Referral Outcome)
  • requeststatus (Request Activity)
  • vaccination (Vaccination)

Note that when defining application properties in the environment section dots . should be replaced with underscores _ and equality = is replaced with colon :.\
E.g.[0] = alert is written as hip_rest_modules[0]: alert\
Each module should be specified as a separate property. Example enabling Alert information and PDL consent:\[0] = alert\[1] = consent

Configuration of HIP-SDK

The environment variable hipsdk_profile controls the HIP-SDK profile

Available profiles for HIP-SDK are

  • sdk-developmentfor local development
  • sdk-qa for development and verification running against a test-environment
  • sdk-production for production environment

Since HIP-REST is but a wrapper, HIP-SDK needs to be configured as well.\
The following properties are the most used and should be set in the environment section in docker-compose.yml when using qa or production profile. = # Where the service is hosted. Test or production environment
ntjp.port = 
ntjp.protocol = # http or https
ntjp.baseUrl = 

ntjp.cert.disableCNCheck = 

ntjp.cert.keystore.type = # Type of keystore, for example PKCS12 or JKS
ntjp.cert.keystore.file = # Path to keystore containing client certificate
ntjp.cert.keystore.password =
ntjp.cert.keystore.keyPassword =

ntjp.cert.truststore.type = # Type of keystore, for example PKCS12 or JKS
ntjp.cert.truststore.file = # Path to Certificate store containing 'SITHS Type 3 CA v1' or 'SITHS Type 3 CA v1 pp'(for test environments) certificates. 
ntjp.cert.truststore.password = 

Note that when defining application properties in the environment section dots . should be replaced with underscores _ and equality = is replaced with colon :.\
E.g. is written as ntjp_host:


API Documentation

The default base path for the service is [container]:8080/api/v1
API documentation is found in the root path [container]:8080/.


Breaking change in v1.1:

All calls require header information containing session to be set.\
If the principal type is citizen, use civic registration number as session id


See the api-documentation for further information about required header fields for each module.

Initial testing

Before connecting to the qa or production environment it is recommended that the application is tested with the development profile set for both HIP-REST and HIP-SDK which means the application is run in local mode.\
The patients available for local testing are:

  • 197705232382
  • 191212121212


Licence file for usage is not included, visit to find out how to obtain a licence if you do not have one.


For further configuration see Spring's documentation, Appendix A. Common application properties for an overview of possible properties and 24. Externalized Configuration for information on how to supply them to the application. Note that not all of the properties listed under Appendix A. are supported.

Notes on usage in QA / Production

HIP Rest uses the Swedish national infrastructure to fetch patient data. In order to connect to live data an agreement must be formed with Inera AB. Read more on Inera's website.


Some common issues and their resolutions are listed below:

CacheManager configuration: You've assigned more memory to the on-heap than the VM can sustain, please adjust your -Xmx setting accordingly
Make sure you docker daemon has at least 4GB of RAM available.

Docker Pull Command