Repository files navigation

This project providesHL7 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 theFHIR Server developed by the MITRE Corporation. It is not a complete implementation of FHIR, as features are driven by theIntervention Engine,eCQM Engine,Patient Matching Test Harness,Synthetic Mass andPatient Assistance Tool projects.

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

• JSON representations of all resources
• XML representations of all resources viaFHIR.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)
• X-Provenance header (transactions only)
• 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 andIf-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 theMongoDB Go Driver is still in its alpha stage.

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 likeObservation.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.

MongoDB is used as the underlying database and has recently acquired multi-document transaction features in version 4.0. Note that transactions are only supported when MongoDB is run as a replica set.

This project also implements a partial workaround. Clients can send aX-Mutex-Name header and two requests with the same value of this header will execute serially (provided there is only one active instance of this server). Please note that this won't give you the all-or-nothing behaviour of real transactions.

A single server can store multiple datasets with the--enableMultiDB switch. This allows requests to specificy the name of a MongoDB database to use. This is done in the base URL, e.g.http://fhir-server/db/test4_fhir/Patient?name=alex

The database should already exist and indexes will not be created automatically. MongoDB transactions also require that collections are pre-created and this server will attempt to do that the first time the database is used. An existing database can also be copied with MongoDB'scopyDatabase command, or you can run this server with theinitdb --databaseName db-name flags.

To mitigate the effects of the database being compromised clients can request thatsome Patient data be encrypted when stored by setting an HTTP headerX-GoFHIR-Encrypt-Patient-Details: 1.However this currently prevents searches by these fields from working.

Encryption is done using AES-GCM with a random nonce. The 32-byte key is specified in an environment variableGOFHIR_ENCRYPTION_KEY_BASE64. A name should be given to the key viaGOFHIR_ENCRYPTION_KEY_ID and this is checked for consistency prior to decryption.

Calls to MongoDB have been instrumented using OpenCensus.There is currently support for Google StackDriver (--enableStackdriverTracing) and Jaeger (--enableJaegerTracing and setJAEGER_AGENT_ENDPOINT_URI andJAEGER_COLLECTOR_ENDPOINT_URI).

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/

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

2. Install and start MongoDB

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

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

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

6. Build and run thefhir-server executable

    $ cd fhir-server $ go build $ ./fhir-server --help Usage of ./fhir-server: -databaseName string MongoDB database name to use by default (default "fhir") -enableXML Enable support for the FHIR XML encoding -databaseSuffix string Request-specific MongoDB database name has to end with this (optional, e.g. '_fhir') -enableMultiDB Allow request to specify a specific Mongo database instead of the default, e.g. http://fhir-server/db/test4_fhir/Patient?name=alex -enableHistory Keep previous versions of every resource -disableSearchTotals Don't query for all results of a search to return Bundle.total, only do paging -tokenParametersCaseSensitive Whether token-type search parameters should be case sensitive (faster and R4 leans towards case-sensitive, whereas STU3 text suggests case-insensitive) -mongodbURI string MongoDB connection URI - a replica set is required for transactions support (default "mongodb://mongo:27017/?replicaSet=rs0") -port int Port to listen on (default 3001) -reqlog Enables request logging -- use with caution in production -failedRequestsDir string Directory where to dump failed requests (e.g. with malformed json) -enableJaegerTracing Enable OpenCensus tracing to Jaeger -enableStackdriverTracing Enable OpenCensus tracing to StackDriver -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. Runrs.initiate() from the MongoDB shell (mongo)

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

Dockerfiles as well as a Google Cloud Container BuildercloudBuild.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 viahttps://console.cloud.google.com/gcr/triggers

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 thefhir-server directory:

$ cd fhir-server$ go run server.go

You can invoke the golang test suite by running:

$ go test ./...

More tests have been written in F#:

$ cd fhir-server$ go build$ cd ..$ cd fsharp-fhir-tools/HttpTests/$ dotnet run start-gofhir

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

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.