EHRbase is an openEHR Clinical Data Repository, providing a standard-based backend for interoperable clinical applications. It implements the latest version of the openEHR Reference Model (RM 1.0.4) and version 1.4 of the Archetype Definition Language (ADL). Applications can use the capabilities of EHRbase through the latest version of the openEHR REST API and model-based queries using the Archetype Query Language.
(click to expand)
Please check the CHANGELOG and/or EHRbase Documentation for more details.
v?.?.? - (...)
Important: Please note that this release introduces Archie's new strict invariant checks. Depending on existing data and clients this might be a breaking change. Please carefully check the EHRbase output and update your input data if EHRbase rejects it. The strict validation can also be deactivated via configuration, but caution in advised!
v0.17.2 - beta release. Bug fixes, enhancements, automatic Docker Hub deployments via Github Actions.
v0.17.1 - beta release. Default handling for audit metadata, bug fixes and SDK version update.
v0.17.0 - fifth beta release. validation using an external terminology server, Attribute-based Access Control, AQL fixes and other enhancements
v0.16.0 - fourth beta release. New endpoints for versioned Compositions, ATNA Logging, AQL fixes and other enhancements.
v0.15.0 - third beta release. New admin API endpoints for EHRs, Compositions and Contributions. Fixes and other enhancements.
v0.14.0 - second beta release.
This release of EHRbase (v0.13.0) is the first beta release.
Please check the CHANGELOG and/or EHRbase Documentation for more details.
EHRbase Documentation is build with Sphinx and hosted on Read the Docs.
See our Run EHRbase + DB with Docker-Compose documentation page for a quick start.
These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. Please read these instructions carefully. See deployment for notes on how to deploy the project on a live system.
You will need Java JDK/JRE 11 (preferably openJDK: e.g. from https://adoptopenjdk.net/)
You will need a Postgres Database (at least Version 10.4, Version 13 recommended) (Docker image or local installation). We recommend the Docker image to get started quickly.
NOTE: Building EHRbase requires a properly set up and running DB for the following steps.
Run ./db-setup/createdb.sql as postgres User.
You can also use this Docker image which is a preconfigured Postgres database:
docker network create ehrbase-net
docker run --name ehrdb --network ehrbase-net -e POSTGRES_PASSWORD=postgres -d -p 5432:5432 ehrbase/ehrbase-postgres:latest(For a preconfigured EHRbase application Docker image and its usage see the documentation)
Edit the database properties in ./pom.xml if necessary
Run mvn package
Replace the * with the current version, e.g. application/target/application-0.9.0.jar
java -jar application/target/application-*.jar
EHRbase can use Basic Authentication for all resources. This means you have to send an 'Authorization' header
set with keyword Basic followed by the authentication information in Base64 encoded username and password. To
generate the Base64 encoded username and password combination create the string after the following schema:
username:password.
The Basic Auth mechanism is implemented as "opt-in" and can be activated either by providing an environment variable
SECURITY_AUTHTYPE=BASIC with the start command or by adding the value into the target application.yml file.
Currently we have support one user with password which can be set via environment variables SECURITY_AUTHUSER and
SECURITY_AUTHPASSWORD. By default these values are set with ehrbase-user and authPassword=SuperSecretPassword
and can be overridden by environment values. Alternatively you can set them inside the corresponding application.yml
file.
The same applies to the admin user, via SECURITY_AUTHADMINUSER, SECURITY_AUTHADMINPASSWORD
and their default values of ehrbase-admin and EvenMoreSecretPassword.
Environment variable SECURITY_AUTHTYPE=OAUTH is enabling OAuth2 authentication.
Additionally, setting the following variable to point to the existing OAuth2 server and realm is necessary:
SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_ISSUERURI=http://localhost:8081/auth/realms/ehrbase
Two roles are available: a user role, and admin role. By default, these roles are expected to be named USER and
ADMIN. The names of these roles can be customised through the SECURITY_OAUTH2USERROLE and SECURITY_OAUTH2ADMINROLE
environment variables. Users should have their roles assigned accordingly, either in the realm_access.roles or scope
claim of the JWT used for authentication.
EHRbase java sourcecode is using palantir-java-format codestyle.
The formatting is checked and applied using the spotless-maven-plugin.
To apply the codestyle run the com.diffplug.spotless:spotless-maven-plugin:apply maven goal in the root directory of the project.
To check if the code conforms to the codestyle run the com.diffplug.spotless:spotless-maven-plugin:check maven goal in the root directory of the project.
These maven goals can also be run for a single module by running them in the modules' subdirectory.
To make sure all code conforms to the codestyle, the "check-codestyle" check is run on all pull requests. Pull requests not passing this check shall not be merged.
If you wish to automatically apply the formatting on commit for *.java files, a simple pre-commit hook script "pre-commit.sh" is available in the root directory of this repository.
To enable the hook you can either copy the script to or create a symlink for it at .git/hooks/pre-commit.
The git hook will run the "apply" goal for the whole project, but formatting changes will only be staged for already staged files, to avoid including unrelated changes.
In case there is a section of code that you carefully formatted in a special way the formatting can be turned off for that section like this:
everything here will be reformatted..
// @formatter:off
This is not affected by spotless-plugin reformatting...
And will stay as is it is!
// @formatter:on
everything here will be reformatted..
Please be aware that @formatter:off/on should only be used on rare occasions to increase readability of complex code and shall be looked at critically when reviewing merge requests.
This command will run all tests from tests/robot folder.
DB and server application will be started/stopped by the tests accordingly. You must not start them by hand.
NOTE: Make sure you meet the PREREQUISITES mentioned in tests/README.md prior to test execution.
Please Check the README in
testsfolder for more details.
cd tests
./run_local_tests.shjava -jar application/target/application-*.jarYou can override the application properties (like database settings) using the normal spring boot mechanism: Command-Line Arguments in Spring Boot- Browse to Swagger UI --> http://localhost:8080/ehrbase/swagger-ui.html
Before updating to a new version of EHRBase check UPDATING.md for any backwards-incompatible changes and additional steps needed in EHRBase. New Releases may introduce DB changes. It is thus recommend to make a DB backup before updating.
- Maven - Dependency Management
EHRbase uses the Apache License, Version 2.0 (https://www.apache.org/licenses/LICENSE-2.0)
EHRbase contains code and derived code from EtherCIS (ethercis.org) which has been developed by Christian Chevalley (ADOC Software Development Co.,Ltd). Dr. Tony Shannon and Phil Berret of the Ripple Foundation CIC Ltd, UK and Dr. Ian McNicoll (FreshEHR Ltd.) greatly contributed to EtherCIS.
EHRbase heavily relies on the openEHR Reference Model implementation (Archie) made by Nedap. Many thanks to Pieter Bos and his team for their work!
EHRbase is jointly developed by Vitasystems GmbH and Peter L. Reichertz Institute for Medical Informatics of TU Braunschweig and Hannover Medical School
