How to integrate with Aidbox (FHIR Server) as EMR provider

Noel Del Castillo

Noel Del Castillo

CEO of SeeYouDoc

Integrate your EMR to Aidbox (HL7 FHIR Server) for referral scenarios
- Noel Del Castillo

Introduction

SeeYouDoc has committed to the UPSilab Community during the Digital Health Interoperability Bootcamp to develop a proof-of-concept for implementing a Referral Tracking System (RTS) using HL7 FHIR.

This guide is intended for developers who want to set up and implement the RTS system on their development machines. We will be using Aidbox as our FHIR server and Metabase as our analytics server.

Architecture

Architecture

Scope of This Guide

  • Help developers set up the necessary tools.
  • Push referrals to the RTS.
  • Explain the data structure and workflow.

Exclusions

This post does not cover:

  • Webhook configuration.
  • Handling Bundle resources in the EMR system.
  • Queries of view tables and Metabase integration.

Future posts will cover these topics based on feedback from the UPSilab Community.

Developer Setup

Prerequisites

To get started, you need to install the following:

  1. Docker & Postman
  2. Clone the GitHub repository: 
    git clone https://github.com/SeeYouDoc/rts_sandbox
  3. Copy sql dump file inside the directory
  4. Run the command: 
    docker-compose up

In case you run the command before and want to reset the setup, do this to remove the volume and setup a new container:

docker-compose down -v
docker-compose up

Components Installed

This will start the following applications:

  • Aidbox (FHIR Server) - http://localhost:8080/
  • Metabase (Analytics Server) - http://localhost:3000/

Setting Up Aidbox

Aidbox serves as the FHIR server to store and process FHIR resources.

Login Credentials

  • Username: admin
  • Password: yFpCTYWU9Y

Configuring OAuth 2.0 Client

  1. Go to http://localhost:8080/ui/console#/iam/sandbox/client
  2. Set your client_id and client_secret. oauth2_a
  3. Ensure JWT is checked.
  4. Click Run to create the client. oauth2_b
  5. Click Run again to create the policy. oauth2_b
  6. Provide the audience and generate an access token. oauth2_b
  7. Copy the access token for later use in Postman.

Setting Up Metabase

Metabase is used for querying and visualizing data.

Steps

  1. Visit http://localhost:3000/ to set up an admin account.
  2. Configure the database connection:
    • Database Type: PostgreSQL
    • Host: aidbox_db
    • Port: 5432
    • Username: aidbox
    • Password: qjqbfVXa94
  3. Sync the database whenever you create a new view table in Aidbox.

Pushing Data to RTS

EMR providers need to push referral data to the RTS to initiate a referral.

ServiceRequest Resource

  • ServiceRequest is used for referrals in HL7 FHIR.
  • It represents an order or proposal for a diagnostic or consultation service.
  • More details can be found in the HL7 FHIR documentation.

Using Bundle Resource

We use FHIR Bundle to send multiple resources as a single atomic transaction:

  • Ensures data integrity.
  • Avoids referential integrity issues.

Steps to Push Data

  1. Open Postman
  2. Create a POST request:
    • Authorization: OAuth 2.0
    • Token: Paste your access token. push1
    • Method: POST
    • URL: http://localhost:8080/fhir
    • Body: Set as raw JSON and paste the data from the sample JSON file. push2
  3. Send the request.
  4. If successful, you should receive a 200 OK response. push3
  5. Verify data in Aidbox: http://localhost:8080/ui/console#/resources-v2/ServiceRequest. push4

Data Structure

Once you successfully push ServiceRequest data into Aidbox, you need to ensure it follows the correct HL7 FHIR standards.

Referral Scenario

scenario This diagram demonstrate how SeeYouDoc & WAH two EMR systems integrates through the RTS system powered by Aidbox.

  1. Dr. Reo (using SeeYouDoc as an EMR) consults with Vina Castro.
  2. Dr. Reo determines that Vina needs to see a gastroenterologist.
  3. He finds a specialist at Ospital ng Maynila.
  4. He refers Vina via SeeYouDoc.
  5. SeeYouDoc creates a Bundle request and sends it to RTS.
  6. RTS processes and stores the ServiceRequest resource.
  7. RTS sends the bundle request to WAH (based on webhook configuration).
  8. WAH processes the request and stores the data.
  9. Vina visits Ospital ng Maynila and the hospital retrieves the referral data.

JSON Structure of ServiceRequest

    {
      "fullUrl": "urn:uuid:4m67o3pk-l789-6n64-k667-kp15lil9l9p2",
      "resource": {
        "resourceType": "ServiceRequest",
        "id": "4m67o3pk-l789-6n64-k667-kp15lil9l9p2",
        "identifier": [
          {
            "type": {
              "coding": [
                {
                  "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
                  "code": "SNO",
                  "display": "Serial Number"
                }
              ],
              "text": "Source System Identifier"
            },
            "system": "https://www.seeyoudoc.com/fhir/ServiceRequest",
            "value": "4m67o3pk-l789-6n64-k667-kp15lil9l9p2"
          }
        ],
        "extension": [
          {
            "url": "https://www.seeyoudoc.com/fhir/StructureDefinition/system-source",
            "valueString": "SeeYouDoc"
          }
        ],
        "status": "active",
        "intent": "order",
        "category": [
          {
            "coding": [
              {
                "system": "http://snomed.info/sct",
                "code": "103693007",
                "display": "Diagnostic procedure"
              }
            ]
          }
        ],
        "code": {
          "coding": [
            {
              "system": "http://snomed.info/sct",
              "code": "11429006",
              "display": "Consultation with gastroenterologist"
            }
          ]
        },
        "subject": {
          "reference": "Patient/8g01i7je-f123-0h08-e001-ej59fcf3f3j6"
        },
        "encounter": {
          "reference": "Encounter/0i23k9lg-h345-2j20-g223-gl71heh5h5l8"
        },
        "performer": [{
          "reference": "Organization/3b56d2e9-a678-5c53-9556-9e04a8a8a8e0"
        }],
        "authoredOn": "2025-02-15T08:25:00+08:00",
        "requester": {
          "reference": "Practitioner/5d78f4gb-c890-7e75-b778-bg26cac0c0g2"
        }
      },
      "request": {
        "method": "PUT",
        "url": "ServiceRequest/4m67o3pk-l789-6n64-k667-kp15lil9l9p2"
      }
    }

Key Fields Explained

  • id: Unique identifier for the referral.
  • identifier: used to set the reference from the source system in order to validate the data.
  • extension: used to set the name of the source system
  • status: active indicates an active referral.
  • intent: order means a service is being requested.
  • code: SNOMED code for gastroenterology consultation.
  • subject: Reference to Patient.
  • encounter: Reference to Encounter.
  • performer: Reference to referred Organization who will perform the service.
  • requester: Reference to Practitioner (doctor making the referral).

Next Steps & Challenges

While this guide covers the initial implementation, there are still challenges that need to be addressed:

  • Webhook configuration for EMR providers.
  • Government ID validation to prevent fake users.
  • Adoption by EMR providers.
  • Security enhancements for RTS.
  • View table queries for Metabase analytics.

Conclusion

This guide demonstrates how to implement an RTS using Aidbox as the HL7 FHIR Server. This is just the first step toward achieving full interoperability in medical referrals.

With further development, we can enhance security, efficiency, and adoption of this system to improve patient care and streamline referrals across healthcare providers.

This will require a community effort to push healthcare innovation in the Philippines. Good thing SeeYouDoc is part of the UPSilab Community. #parasabayan

footer-banner