fhir

README

GoFHIR - Intervention Engine FHIR Server

This project provides HL7 FHIR STU3 models and server components implemented in Go and using MongoDB for storage. It aims to work well when multiple instances are run in containers - starting quickly, having modest resource utilisation and giving good performance.

This is a continuation of the FHIR Server developed by the MITRE Corporation. It is not a complete implementation of FHIR, as features are driven by the Intervention Engine, eCQM Engine, Patient Matching Test Harness, Synthetic Mass and Patient Assistance Tool projects.

Currently this server should be considered experimental, with preliminary support for:

• JSON representations of all resources
• XML representations of all resources via FHIR.js (except for primitive extensions)
• Transaction bundles (requires a MongoDB 4.0 replica set)
• Create/Read/Update/Delete (CRUD) operations with versioning
• Conditional update and delete
• Resource-level history (basic support - lacks paging and filtering)
• Batch bundles (POST, PUT and DELETE entries)
• Arbitrary-precision storage for decimals
• Some search features
  • All defined resource-specific search parameters except composite types and contact (email/phone) searches
  • Chained searches
  • Reverse chained searches using _has
  • _include and _revinclude searches (without _recurse)

Currently this server does not support the following features:

• Validation
• Terminology
• Resource summaries
• Whole-system and whole-resource history
• Advanced search
  • Custom search parameters
  • Full-text search
  • Filter expressions
  • Whole-system search
• GraphQL

The following relatively basic items are next in line for development:

• Conditional reads (If-Modified-Since and If-None-Match)
• History support for paging, _since, _at and _count
• Batch interdependency validation
• Validation (probably by proxying the request to a reference FHIR server)
• Search for quantities with the system unspecified (i.e. by both unit and code)

Users are strongly encouraged to test thoroughly and contributions (including more tests) would be most welcome. Please note that MongoDB 4.0 is quite new and the MongoDB Go Driver is still in its alpha stage.

Future work

In addition to the unimplemented parts of the FHIR spec above major topics to consider are:

1. Improvements to indexing. Currently MongoDB searches & indexes "look inside" the resources for each path which is inefficient for parameters like Observation.combo-code-value-quantity since several paths/indexes need to be checked. Solutions to investigate would be to create compound indexes or extract search parameters into a sub-document and index that.
2. PostgreSQL support - see here for some ideas.

Getting started using Docker

1. Install Docker

2. Run an image of this FHIR server that includes MongoDB (--rm means all data will be deleted after the container exits):

    docker run --rm -it -p 3001:3001 gcr.io/eug48-fhir/fhir-server-with-mongo
   

3. You can also run MongoDB and this FHIR server in separate containers:

    docker run --name fhir-mongo -v /my/own/datadir:/data/db -d mongo --replSet rs0
    docker run --rm --link fhir-mongo:mongo mongo mongo --host mongo --eval "rs.initiate()"
    docker run --rm -it --link fhir-mongo:mongo -e GIN_MODE=release -e "MONGODB_URI=mongodb://fhir-mongo:27017/?replicaSet=rs0" -p 3001:3001 gcr.io/eug48-fhir/fhir-server
   

See MongoDB's Docker image documentation for more information, including how to persist data: https://hub.docker.com/_/mongo/

Building and running from source

1. Install the Go programming language (at least version 1.10)

2. Install and start MongoDB

3. Install the Dep package-management tool for Go: https://golang.github.io/dep/docs/installation.html

4. Clone or download this repository under GOPATH/src (run go env to see your current GOPATH)

5. Run dep ensure -vendor-only -v to download dependencies into a vendor sub-directory (can take a long time)

6. Build and run the fhir-server executable

    $ cd fhir-server
    $ go build
    $ ./fhir-server --help
    Usage of ./fhir-server:
    -databaseName string
    		MongoDB database name to use (default "fhir")
    -enableXML
    		Enable support for the FHIR XML encoding
    -mongodbHostPort string
    		MongoDB host:port (default "localhost:27017")
    -port int
    		Port to listen on (default 3001)
    -reqlog
    		Enables request logging -- use with caution in production
    -startMongod
    		Run mongod (for 'getting started' docker images - development only)
   

MongoDB 4.0 only supports transactions when run as a replica set. To create a single-node replica set:

1. Add the --replSet option to the MongoDB daemon: e.g. mongod --replSet rs0
2. Run rs.initiate() from the MongoDB shell (mongo)

If you wish to test the server with synthetic patient data, please reference Generate and Upload Synthetic Patient Data.

Building docker images

Dockerfiles as well as a Google Cloud Container Builder cloudBuild.json spec are in the root of the repository.

To build from the Dockerfiles:

$ docker build -t my-fhir-server:2018-07-12a .
$ docker build -f Dockerfile-with-mongo -t my-fhir-server-with-mongo:2018-07-12a .

To build using Google Container Builder (after setting up the gcloud tool):

# The main Dockerfile
$ gcloud builds submit -t gcr.io/your-project-id/fhir-server:2018-07-12a

# Both Dockerfiles
$ gcloud builds submit --config=cloudBuild.json  --substitutions=COMMIT_SHA=yyyy-mm-dd

You can also set up a trigger via https://console.cloud.google.com/gcr/triggers

Development

This project uses Go 1.10. To test the library first install dependencies by running dep ensure -vendor-only -v. You can also try using the older go get -t ./... (this requires the project to be at the right place in your GOPATH).

Once the dependecies have been installed, you can invoke the test suite by running:

$ go test ./...

To run the server whilst it is under development it is often easier to combine the build and run steps into a single command from the fhir-server directory:

$ go run server.go

As a library

This package can also be used as a library. Examples of usage can be found in the server set up of the eCQM Engine, the server set up of Intervention Engine, or the GoFHIR server used by SyntheticMass.

License

Copyright 2017 The MITRE Corporation

Copyright 2018 PAT Pty Ltd

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.