io.onfhir:onfhir-operations

onFHIR is an HL7 FHIR compliant secure, high-performance and scalable health data repository that can be used as the central data service for HL7 FHIR compliant healthcare applications.


Keywords
fhir, fhir-server, health-informatics, hl7, java, mhealth, scala
License
GPL-3.0

Documentation

Onfhir FHIR Repository

OnFhir.io is a FHIR compliant secure health data repository that you can use as a central data service for your FHIR compliant healthcare applications. You can use it as a standalone server, or you can extend it with your further custom FHIR Operations to build your own application layer in addition to having standart FHIR repository capabilities. Onfhir.io is using FHIR Infrastructure Resource definitions (CapabilityStatement, StructureDefinition, SearchParameter, etc) to tailor the FHIR server to your specific FHIR capabilities you required; resource profiles, search parameters, FHIR interactions you wanted to support.
It is implemented with Scala, based on Akka and MongoDB.

Basic Configuration

You can copy and update onfhir-core/src/main/resources/application.conf file, which is the entrypoint configuration to configure onFHIR repository based on your needs.

For logger configurations, check onfhir-core/src/main/resources/logback.xml

For configuration of the FHIR API to be provided, you need to provide the followings;

  • A file providing your Conformance statement (FHIR Capability Statement - See http://hl7.org/fhir/capabilitystatement.html) that describes the capabilities of the FHIR server you want to provide
  • A folder including all your Profile definitions (FHIR StructureDefinition - See http://hl7.org/fhir/structuredefinition.html) including resource, data type and extension definitions that will be used in the FHIR server you want to provide
  • A folder including all your Compartment definitions (FHIR CompartmentDefinition - See http://hl7.org/fhir/2016Sep/compartmentdefinition.html) for all compartments that you want to support for search
  • A folder including all your Search parameter definitions (FHIR SearchParameter - See http://hl7.org/fhir/searchparameter.html) for all extra search parameters (apart from what is available from the base FHIR standard) that you define and support for your resources
  • A folder including all your Value sets (FHIR ValueSet - See http://hl7.org/fhir/valueset.html) that you define and refer in your resource profiles
  • A folder including all your Operation definitions (FHIR OperationDefinition - http://hl7.org/fhir/operationdefinition.html) that you define and refer from capability statement in operations part (For your OperationDefinitions write the full class path of your implementation of operation in OperationDefinition.name)

You can also provide the zip file for FHIR base definitions (Validation package - 'validation-min.xml.zip') that you want to support specifically. Currently all versions are supported and we created a module for each version that have specific standard definitions and special configurators.

  • DSTU2 >> onfhir-server-dstu2
  • STU3 >> onfhir-server-stu3
  • R4 >> onfhir-server-r4

Build & Run

You need to run the below command to build fhir-repository. This will compile your code, execute unit tests and create a single standalone jar with all the dependencies:

$ mvn package

Unit tests may take some time, so you can add -DskipTests=true command line parameter to the above command to skip the test execution but it is not recommended:

$ mvn package -DskipTests=true

Executable standalone jars target/fhir-repository-standalone.jar will be created under each onfhir-server for different FHIR version. Executing the following command will run the onfhir server for that version with nearly whole FHIR capabilities.

$ java -jar target/fhir-repository-standalone.jar

You can override in-app configurations by supplying an external application.conf file or JAVA arguments using the following commands:

$ java -Dconfig.file={path-to-application.conf} -jar target/fhir-repository-standalone.jar
$ java -Dserver.port=9999 -Dserver.host=172.17.0.1 -jar target/fhir-repository-standalone.jar

Extensibility

You can develop your own FHIR compliant backend application based on onFhir.io. In order to do this you can import the corresponding server module as dependency to your project and write a scala App (Boot) that initiates onFhir with a custom configuration. Onfhir.scala is the main entrypoint to the project. The following is the default server Boot configuration for onfhir-server-r4. It initiates a FHIR R4 server with the given configurations.

object Boot extends App {
  //Initialize onfhir for R4
  var onfhir = Onfhir.apply(new R4Configurator())
  //Start it
  onfhir.start
}

You can extend the onFhir.io by implementing certain custom mechanisms;

  • Custom Authorizer (Implementing io.onfhir.authz.IAAuthorizer interface): In default(if you configure), onFhir.io supports the authorization mechanism defined in SmartOnFhir initiative which is based on OAuth2.0 Bearer Token based authorization. If you need a custom authorization mechanism with different set of scopes (permissions), you can implement a authorizer module and register it to OnFhir.
  • Custom Token Resolver (Implementing io.onfhir.authz.ITokenResolver interface): OnFhir.io supports two default token resolution methods; Signed JWT tokens and OAuth2.0 Token Introspection. You can use them by configurations or implement a new module.
  • Custom Audit Handler (Implementing io.onfhir.audit.ICustomAuditHandler): In default, you can configure OnFhir to store FHIR AuditEvent records to its own local repository, or a remote FHIR server running as a seperate audit repository. If you want to create audit events/logs in different format and send them to a custom audit repository (ElasticSearch+Kibana, etc), you can extend this interface with your module and register it.
  • Further FHIR Operations: You can implement custom FHIR Operations by extending io.onfhir.api.service.FHIROperationHandlerService and preparing an OperationDefinition file for onFhir configuration while setting
    the class path of your module to the OperationDefinition.name parameter.
  • External Akka Routes: You can also implement non-FHIR REST services for your server and register them to OnFhir.
object Boot extends App {
  //Initialize onfhir for R4
  var onfhir = 
     Onfhir.apply(
        fhirConfigurator = new R4Configurator(),
        customAuthorizer = new MyAuthorizer(),
        customAuditHandler = new MyAuditHandler(),
        externalRoutes = ...my non-fhir routes 
     )
  //Start it
  onfhir.start
}

Docker

fhir-repository project also utilizes Spotify's maven plugin to build Docker images from the source code. By executing the following command, you can create a Docker image with the name "srdc/fhir". One thing to notice here is that, by default, the plugin will try to connect to docker machine on localhost:2375. Set the DOCKER_HOST environment variable to connect elsewhere.

$ mvn clean package docker:build

After building the image you can execute the following command to run fhir-repository which is bound to fhir host (which is an alias for the local ip of your instance in the docker network). By using APP_CONF_FILE environment variable you can provide the path for your configuration file (application.conf described in configuration file). Of course, you need to mount a volume to enable docker container ( is mounted to /fhir/conf which is given as root path for application.conf and other configuration directories) to access this configuration file. Please be careful, when setting the paths in application.conf. You can overide some configurations by setting the FHIR_HOST, USE_SSL, KAFKA_HOST and KAFKA_PORT environment variables if you like.Note that these properties are all optional and if not set, the configurations in the application.conf will be applied.

$ docker run -d --name fhir -h fhir -p 8080:8080 -e FHIR_HOST=fhir -e APP_CONF_FILE=/fhir/conf/application.conf -v <host-path-to-conf>:/fhir/conf -v <host-path-for-db-files>:/data/db  srdc/fhir

Then you will be able to send requests to this running instance over your docker machine

$ curl http://<DOCKER_HOST_IP>:8080/fhir/Patient/some-id

Tests

fhir-repository uses specs2 for unit testing. To execute tests for each build with the following command:

$ mvn test