Populating FHIR resources¶

In a FHIR facade implementation, populating FHIR resources is a critical step that involves mapping and transforming data from existing healthcare systems into standardized FHIR resources. This process ensures that the data is consistent, accurate, and accessible in a FHIR-compliant format, allowing for seamless interoperability between different healthcare applications.

Note

WSO2 Healthcare Solution offers two distinct solutions (Ballerina and Micro Integrator) each tailored to different architectural preferences. For systems that favor the Enterprise Service Bus (ESB) pattern, the Micro Integrator, enhanced with FHIR accelerators, can be utilized.
On the other hand, Ballerina, a programming language specifically designed for integrations, is ideal for implementing FHIR integrations structured as microservices.

BallerinaMicro Integrator

Populating a FHIR resource in Ballerina is as straightforward as creating a simple record object. Developers need only import the appropriate FHIR package from Ballerina Central and then create a FHIR resource record as demonstrated below.

Step 1: Set Up Ballerina¶

Before you begin, ensure you have Ballerina installed on your system. Follow the instructions in the Installation Steps to install Ballerina and set up the development environment.

Step 2: Implement the flow to populate a FHIR resource¶

Create ballerina project using the following command. It will create the ballerina project and the main.bal file can be used to implement the logic.
```
$ bal new fhir_resource_populate_sample
```
Import the required modules to the Ballerina program. In this sample we are using FHIR Patient resource from international base FHIR IG . Therefore, we need to import ballerinax/health.fhir.r4.internationa401 package. If you are using a different IG of FHIR, you can import the relevant package from the central or generated from the bal health tool.
```
import ballerinax/health.fhir.r4.internationa401;
import ballerina/io;
```
Create a custom patient record type to represent the patient data. In this sample, the patient record contains the patient's first name, last name, address, and phone number.
```
// A custom patient record.
type Patient record {
    string firstName;
    string lastName;
    string address;
    string phoneNumber;
};
```

Define a data mapping function to convert the patient record to a FHIR Patient resource. The function takes the custom patient record as input and returns an FHIR Patient resource. You can use the visual data mapper in ballerina to map the patient record fields to the FHIR Patient resource fields. You can follow the documentation on Visual Data Mapping to learn more about visual data mapping in Ballerina.

// Data mapping function to convert a patient record to an FHIR Patient resource.
function patientToFHIR(Patient patient) returns international401:Patient => {
    meta: {
        lastUpdated: time:utcToString(time:utcNow()),
        profile: [international401:PROFILE_BASE_PATIENT]
    },
    active: true,
    name: [
        {
            family: patient.lastName,
            given: [patient.firstName],
            use: international401:CODE_MODE_OFFICIAL,
            prefix: ["Mr"]
        }
    ],
    address: [
        {
            line: [patient.address],
            city: "New York",
            country: "United States",
            postalCode: "10022"
        }
    ],
    telecom: [
        {
            value: patient.phoneNumber,
            use: "mobile"
        }
    ]
};

Serialize the FHIR resource to a string using the toString() function.

The complete code sample will look as follows:

import ballerina/io;
import ballerina/time;
import ballerinax/health.fhir.r4.international401;

// A custom patient record.
type Patient record {
    string firstName;
    string lastName;
    string address;
    string phoneNumber;
};

public function main() returns error? {
    // Sample patient data
    Patient patient = {firstName: "John", lastName: "Doe", address: "123 Main St", phoneNumber: "555-555-5555"};
    international401:Patient patientResource = patientToFHIR(patient);
    io:println(patientResource.toString());
}

// Data mapping function to convert a patient record to an FHIR Patient resource.
function patientToFHIR(Patient patient) returns international401:Patient => {
    meta: {
        lastUpdated: time:utcToString(time:utcNow()),
        profile: [international401:PROFILE_BASE_PATIENT]
    },
    active: true,
    name: [
        {
            family: patient.lastName,
            given: [patient.firstName],
            use: international401:CODE_MODE_OFFICIAL,
            prefix: ["Mr"]
        }
    ],
    address: [
        {
            line: [patient.address],
            city: "New York",
            country: "United States",
            postalCode: "10022"
        }
    ],
    telecom: [
        {
            value: patient.phoneNumber,
            use: "mobile"
        }
    ]
};

Step 3: Run the Ballerina Program¶

Run the Ballerina program using the following command:

```bash
$ bal run
```

In Ballerina, you can access built-in records [link to central] that support FHIR. These predefined records allow you to easily populate FHIR resources. With cardinality constraints and data validation rules embedded in the record definitions, the IDE provides guidance to ensure the complete and accurate population of FHIR resources. Additionally, records are available for commonly used implementation guides, incorporating specific extensions and constraints relevant to those areas.

For integrations running on WSO2 Micro Integrator (MI), FHIR resources can be created using the DataMapper feature available in the VSCode Micro Integrator extension. This feature allows you to map fields from the source schema to the target FHIR schema effortlessly. Schemas can be loaded into the extension by referencing sample JSON files provided here that correspond to each schema of FHIR resources.

The following example demonstrates how to populate HL7 FHIR resources using the WSO2 Micro Integrator.

Step 1: Set Up WSO2 Micro Integrator¶

Before you begin, download the WSO2 Micro Integrator and install by following the Installation Steps.

Step 2: Implement the flow to populate a FHIR resource¶

Create a MI project using the MI VSCode plugin by following the guide on Creating a New Integration Project.

Create a REST API to receive a custom patient data and populate a FHIR Patient resource.

<?xml version="1.0" encoding="UTF-8"?>
<api context="/patient" name="PatientAPI" xmlns="http://ws.apache.org/ns/synapse">
    <resource methods="POST" uri-template="/v1">
        <inSequence>
            <property name="OriginalPayload" scope="default" type="STRING"
                expression="json-eval($.)" />
            <log category="INFO" level="full">
                <property name="originalPayload" expression="$ctx:OriginalPayload" />
            </log>
        </inSequence>
        <faultSequence>
        </faultSequence>
    </resource>
</api>

Use DataMapper mediator to map the custom patient data to a FHIR Patient resource. Use the JSON schemas provided here to load the FHIR Patient schema as the output into the DataMapper.

Log the output of the DataMapper to view the populated FHIR Patient resource and use respond mediator to send the response to the client. Following is the complete API configuration:

Completed flow

<?xml version="1.0" encoding="UTF-8"?>
<api context="/patient" name="PatientAPI" xmlns="http://ws.apache.org/ns/synapse">
    <resource methods="POST" uri-template="/v1">
        <inSequence>
            <property name="OriginalPayload" scope="default" type="STRING"
                expression="json-eval($.)" />
            <datamapper config="gov:/datamapper/PatientMapper/PatientMapper.dmc"
                inputSchema="gov:/datamapper/PatientMapper/PatientMapper_inputSchema.json"
                inputType="JSON"
                outputSchema="gov:/datamapper/PatientMapper/PatientMapper_outputSchema.json"
                outputType="JSON" />
            <log category="INFO" level="full">
                <property name="originalPayload" expression="$ctx:OriginalPayload" />
            </log>    
            <respond/>
        </inSequence>
        <faultSequence>
        </faultSequence>
    </resource>
</api>

Step 3: Deploy and Test the Integration Project¶

Deploy the integration project to the MI runtime by following the guide on Deploying the Integration Project and test the API using a REST client.

Note

The populated FHIR resource can be accessed and modified within the message flow, and further FHIR-related actions, such as adding the resource to a FHIR bundle or serializing it into FHIR-specified wire formats like fhir+json or fhir+xml, can be accomplished using the FHIR Base module available in the WSO2 Connector Store.