openFHIR Quick Start Guide

This quick start guide helps you get started with openFHIR, an engine that implements FHIR Connect specification and facilitates bidirectional mappings between openEHR and FHIR.

Prerequisites

• Docker and Docker Compose
• Postman (optional, for API testing)

Running openFHIR with Docker

1. Clone the Repository

git clone https://github.com/medblocks/openFHIR.git
cd openfhir

2. Configure Bootstrap Directory

Modify src/main/resources/application.properties to add:

bootstrap.dir=[folder path]

Replace [folder path] with the path to the directory containing your context, and model files. Bootstrap will load all files in this directory. For example, if your files are in src/test/resources/blood_pressure/, will load all the context YAML files and model YAML files in that directory.

bootstrap.recursively-open-directories=true

This will ensure all model and context files in the specified directory are loaded during startup.

3. Build and Run with Docker Compose

docker-compose build
docker-compose up

This will:

• Build the openFHIR application from source
• Start a PostgreSQL database container
• Start the openFHIR engine connected to the database
• Expose the service on port 8080

Testing with Blood Pressure Example and Using Postman

We’ll use the blood pressure example files located in src/test/resources/blood_pressure/ to test the openFHIR engine. A Postman collection is available in the repository at etc/openFHIR_oss.postman_collection.json.

Setting Up Postman

1. Import the collection from etc/openFHIR_oss.postman_collection.json into Postman
2. Set up an environment with the variable baseurl pointing to your openFHIR instance (e.g., http://localhost:8080)

Running the Blood Pressure Example

Follow these steps in Postman:

1. Upload OPT Template

Create a new POST request:

• URL: {{baseurl}}/opt
• Headers:
  • Content-Type: application/xml
• Body: Binary file
  • Select the file: src/test/resources/blood_pressure/Blood Pressure.opt

2. Upload Context Definition

Create a new POST request:

• URL: {{baseurl}}/fc/context
• Headers:
  • Content-Type: text/plain
• Body: Binary file
  • Select the file: src/test/resources/blood_pressure/simple-blood-pressure.context.yml

Note: This step is not needed if these files are already in the bootstrap directory.

3. Upload Model Definition

Create a new POST request:

• URL: {{baseurl}}/fc/model
• Headers:
  • Content-Type: text/plain
• Body: Binary file
  • Select the file: src/test/resources/blood_pressure/blood-pressure.model.yml

Note: This step is not needed if these files are already in the bootstrap directory.

4. Test the Mapping

Convert openEHR to FHIR

Create a new POST request:

• URL: {{baseurl}}/openfhir/tofhir?templateId=Blood Pressure
• Headers:
  • Content-Type: application/json
• Body: raw (JSON)

{
	"blood_pressure/blood_pressure/any_event:0/systolic|magnitude": 120.0,
	"blood_pressure/blood_pressure/any_event:0/systolic|unit": "mm[Hg]",
	"blood_pressure/blood_pressure/any_event:0/diastolic|magnitude": 80.0,
	"blood_pressure/blood_pressure/any_event:0/diastolic|unit": "mm[Hg]",
	"blood_pressure/blood_pressure/any_event:0/clinical_interpretation": "Normal blood pressure"
}

Convert FHIR to openEHR

Create a new POST request:

• URL: {{baseurl}}/openfhir/toopenehr
• Headers:
  • Content-Type: application/json
  • templateId: Blood Pressure
• Body: raw (JSON)

{
	"resourceType": "Bundle",
	"entry": [
		{
			"resource": {
				"resourceType": "Observation",
				"status": "final",
				"code": {
					"coding": [
						{
							"system": "http://loinc.org",
							"code": "85354-9",
							"display": "Blood pressure panel"
						}
					]
				},
				"component": [
					{
						"code": {
							"coding": [
								{
									"system": "http://loinc.org",
									"code": "8480-6",
									"display": "Systolic blood pressure"
								}
							]
						},
						"valueQuantity": {
							"value": 120,
							"unit": "mm[Hg]",
							"system": "http://unitsofmeasure.org",
							"code": "mm[Hg]"
						}
					},
					{
						"code": {
							"coding": [
								{
									"system": "http://loinc.org",
									"code": "8462-4",
									"display": "Diastolic blood pressure"
								}
							]
						},
						"valueQuantity": {
							"value": 80,
							"unit": "mm[Hg]",
							"system": "http://unitsofmeasure.org",
							"code": "mm[Hg]"
						}
					}
				]
			}
		}
	]
}

For more FHIR examples, refer to the bundle files in the repository at GitHub.

Next Steps

• Check the full documentation for more detailed information
• Try the online sandbox to explore more examples
• Explore the different endpoints and mapping capabilities

License

This project is licensed under the Apache License 2.0 - see the official repository for details.