[Java] Introduction to EHRbase 1-Overview and Environment

5 minute read


This article is the content of the lecture introduced at the 2nd 2020 openEHR workshop. EHRbase is an open source software implementation of the openEHR specification. In this article, I will introduce the architecture of EHRbase and even how to build a development environment.

The contents below are constructed with reference to the following materials and the memo of Professor Eisen Kimura, Ehime University.

  • EHRbase (GitHub repository)
    • https://github.com/ehrbase/
  • EHRbase project
    • https://ehrbase.org/
  • Presentation of Christian Chevalley at EHRbase, The 3rd openEHR Asia summit
    • https://www.slideshare.net/openEHR-Japan/ehrbase-open-source-openehr-cdr

EHRbase development environment

The major software components used by EHRbase as a development environment are listed below. The environment is built with docker, but install it if necessary.

  • docker
  • Java JDK/JRE 11 (OpenJDK recommended)
  • Maven
  • Springboot
  • PostgreSQL 10.4-
    • jsquery plugin
    • temporal template
  • Postman
  • Ocean archetype editor, template designer

EHRbase overview

  • EHRbase is one of the open source software implementation of EHR server according to openEHR specifications.
  • Development started in 2019, following the flow of MEDScape and EtherCIS.
  • Currently a development team of 16 people working on GitHub.
  • Springboot is used to build an EHR server with a Modern platform architecture.
    • REST API, JSON/XML message
  • Saves and manages EHR data, but does not handle information such as personal name and address
    • OpenEPMI
    • in Japan?
  • Client including UI is not included. (SDK provided)

What EHRbase aims for

  • Implementation of EHR with open source software that conforms to the openEHR specification
  • Lower barriers for vendors, hospitals, and governments to deploy open standards and platforms with established interoperability.
  • It will be the foundation to support data-driven medicine and realize interoperability in medicine in the 21st century.
  • It can be used for electronic prescriptions and intensive care management with complicated work procedures.
  • Make it easy to develop next-generation medical software.

EHRbase organizational governance

EHRbase architecture


Christian Chevaley, EHRbase, the 3rd openEHR Asia summit, online, July 24, 2020.

EHRbase and its surroundings


Christian Chevaley, EHRbase, the 3rd openEHR Asia summit, online, July 24, 2020.

EHRbase server

  • Secure REST API (Supports various authentication procedures including OAuth2)
  • Perform openEHR compliant CRUD transaction and validation
  • Query (AQL) processing for openEHR objects
  • Maintain local knwoledge model
  • Data centric architecture
  • Compatible with the latest openEHR architecture


  • Can handle Template(Knowledge base)
  • Templates can be converted to POJO classes
  • Provide the EHRbase client endpoint as a Java method
    • EHR
    • Template
    • Composition
    • Querying (AQL)
    • Directory
  • Supports serialization and validation of openEHR objects
  • Generate REST API payload

Development environment construction

Before installing EHRbase

This time we will build the environment with Docker, so we will prepare the environment so that docker can operate. docker-engine and docker-compose work with a relatively new version, but they did not work with the old version around ver 1.7.

  • Linux
    • Please install docker and docker-compose corresponding to each distribution.
  • Windows
    • Please do WSL2 environment before preparing Docker environment. *I am trying it on Ubuntu 20.04LTS, but I think that other distros will also work.
  • Mac
    • I haven’t tried it, but docker seems to work.

Install EHRbase

Important: Please note that the official procedure may stop working.

  • Java is not used this time, but you need to install JDK 11 equivalent for development, so please install it according to your environment.
  • The order is as follows.

    1.Create docker-network

    1. Setting up a container with PostgreSQL and related plugins
    2. Create the EHRbase application container

Creating docker-network

Create a docker network for EHRbase with the following command

$ docker network create ehrbase-net

Confirm with docker network ls and it is OK if the following is displayed.

$ docker network ls
2c6a5b55365a bridge bridge local
4b82d2167e35 ehrbase-net bridge local
5ee3d71c037f host host local
31ab9819a783 none null local

If you are already using PostgreSQL, you can use it as it is, but you need to install the plugin.

  • Use docker
$ docker run --name ehrdb --network ehrbase-net -e POSTGRES_PASSWORD=postgres -d -p 5432:5432 ehrbaseorg/ehrbase-postgres:latest
  • If you do not use docker, install PostgreSQL (ver 10.4 or later) and then install the following plugin. For Ubuntu, install the required packages as shown below.
$ sudo apt install gcc bison flex postgresql libpq-dev postgresql-server-dev-all openjdk-11-jdk maven


$ git clone https://github.com/arkhipov/temporal_tables.git
$ cd temporal_tables
$ make
$ sudo make install
$ make installcheck
  • If you get an error with make install check, create a ROLE with the same name as your Linux user name in PostgreSQL and grant database creation privileges.

  • Install jsquery

shell:jsquery$ git clone https://github.com/postgrespro/jsquery.git

$ cd jsquery
$ make USE_PGXS=1
$ sudo make USE_PGXS=1 install
$ make USE_PGXS=1 installcheck
  • If you get an error with make install check, create a ROLE with the same name as your Linux user name in PostgreSQL and grant database creation privileges.

Build EHRbase server

  • It is convenient to use docker.
$ docker run --name ehrbase --network ehrbase-net -d -p 8080:8080 -e DB_URL=jdbc:postgresql://ehrdb:5432/ehrbase -e DB_USER=ehrbase -e DB_PASS=ehrbase -e SYSTEM_NAME=local .ehrbase.org ehrbaseorg/ehrbase:latest
  • Confirm the execution as follows.
$ docker exec -i -t ehrbase /bin/bash
  • If you want to build the development environment without using docker, do the following.
    • Initialize database table
$ git clone https://github.com/ehrbase/ehrbase.git
$ cd ehrbase
$ sudo -u postgres psql -e <./base/db-setup/createdb.sql
  • maven environment settings
    • Edit pom.xml if needed.
  • Build the package
$ mvn package
  • Run EHRbase.
    • If it is the current version, execute the following command.
$ java -jar application/target/application-0.13.0.jar

API confirmation

If it seems to work well, the API list built with Swagger-ui will appear. The Basic authentication user is ehrbase-user and the password is SuperSecretPassword.


EHR registration

Let’s register EHR using Postman. Use the following JSON sample from the official tutorial.

  "_type": "EHR_STATUS",
  "subject": {
    "external_ref": {
      "id": {
        "_type": "GENERIC_ID",
        "value": "ins01",
        "scheme": "id_scheme"
      "namespace": "ehr_craft",
      "type": "PERSON"
  "other_details": {
    "_type": "ITEM_TREE",
    "items": []
  "is_modifiable": "true",
  "is_queryable": "true"

Template registration

Create a template using Template editing software such as Ocean Template Designer. Once created, output in operational template format.

After confirming the contents of the XML file, register it with Postman according to the API.

The registered file can also be viewed using Postman.

Next time, we will register, read, update and delete (CRUD) data based on this template.