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.