Health tool (FHIR/HL7)

The health tool generates Ballerina library packages and Ballerina templates for FHIR APIs for developing healthcare integrations.

These artifacts generated by the tool are primarily focused on the Fast Healthcare Interoperability Resources (FHIR) standard and are developed using Ballerina.

Info: It is supported from Ballerina Swan Lake version 2201.8.1 onwards.

Prerequisites

Download a directory containing all FHIR specification definition files. You can download a preferred standard implementation guide from the FHIR Implementation Guide registry.

Note: It is recommended to use a Standard for Trial Use (STU) or higher release level of the implementation guides. Make sure that the downloaded specification archive has the StructureDefinition, ValueSet, and CodeSystem files for the Implementation Guide (IG) resources when extracted.

Install the tool

Execute the command below to pull the Health tool from Ballerina Central.


$ bal tool pull health
health:2.0.0 pulled successfully.
health:2.0.0 successfully set as the active version.

Usage

The Ballerina Health tool supports two main usages as follows.

Package generation: generate a Ballerina package from a given FHIR implementation guide.
Template generation: generate Ballerina templates for FHIR APIs from a given FHIR implementation guide.

The general usage of the tool is as follows.

Note: Make sure to give the directory path of the downloaded FHIR definitions as the last argument.


$ bal health fhir [-m | --mode] <mode-type>
            [-o | --output] <output-location>
            [--package-name] <ballerina-package-name>
            [--dependent-package] <dependent-ballerina-package-name> 
            [--org-name] <package-or-template-organization-name>
            [--included-profile] <profile(s)-to-include-in-generation>
            [--excluded-profile] <profile(s)-to-exclude-in-generation>
            <fhir-specification-directory-path>

Command options

The parameters that are available with the tool are listed below.

Command option	Description	Usage
`-m, --mode`	Mode type can be `package` or `template`. The Ballerina package and API templates are generated according to the mode.	package generation template generation
`-o, --output`	The Ballerina artifacts are generated at the same location from which the `bal health fhir` command is executed. You can point to another directory location by using the `(-o\|--output)` flag.	package generation template generation
`--package-name`	Name of the Ballerina package to be generated.	package generation
`--dependent-package`	Ballerina package name, which contains the IG resources.	template generation
`--org-name`	Organization name of the Ballerina package or API templates to be generated.	package generation template generation
`--included-profile`	Generate one or more specific FHIR profiles as Ballerina templates for FHIR APIs.	template generation
`--excluded-profile`	Skip one or more specific FHIR profiles when generating Ballerina templates for FHIR APIs.	template generation

Package generation

The FHIR resources in the implementation guide will be represented as Ballerina records including the correct cardinality constraints and metadata. FHIR integration developers can leverage the generated package when transforming custom health data into FHIR format without referring to the specification.

Package generation usage

The tool supports the package generation usage as follows.


$ bal health fhir [-m | --mode] package
            [--package-name] <ballerina-package-name>
            [-o | --output] <output-location>
            [--org-name] <package-organization-name>
            <fhir-specification-directory-path>

Package generation command options

Command option	Description	Mandatory/Optional
`-m, --mode`	If `mode` is set to `package`, a Ballerina package will be generated including all the records and types.	Mandatory
`--package-name`	Name of the Ballerina package to be generated. The package name can be explicitly set using this argument. Unless specified, the default name of the implementation guide will be taken to construct the name of the package. For more information, see the the `name` field.	Mandatory
`-o, --output`	Location of the generated Ballerina artifacts. If this path is not specified, the output will be written to the same directory from which the command is run.	Optional
`--org-name`	Organization name of the Ballerina package to be generated. For more information, see the `org` field.	Optional

Package generation example

Follow the steps below to try out an example package generation use case of the Health tool.

Clone the example project

Clone the artifacts of the example and extract them to a preferred location.

The cloned directory includes the artifacts below that will be required to try out this example (Ballerina project and the FHIR specification files).

The ig-carinbb/definitions directory: includes the definition files of the FHIR specification.
The carinbb-patient-service directory: includes the Ballerina project containing the artifacts (i.e., the Ballerina.toml, Dependencies.toml, and service.bal files) to be executed.

Generate the package

Follow the steps below to run the Health tool and create the Ballerina package.

Navigate to the cloned working-with-health-tool/package-generation directory.

Run the tool with the required command options to generate the package.

Note: This example uses the definitions files downloaded from the JSON Definitions ZIP archive of the Carin BB implementation guide to generate the package.


$ bal health fhir -m package -o ig-carinbb/gen --org-name healthcare_samples --package-name carinbb_package ig-carinbb/definitions/
[INFO] Ballerina FHIR package generation completed successfully. Generated package can be found at: /tmp/healthcare-samples/working-with-health-tool/package-generation/ig-carinbb/gen

The generated folder (i.e., working-with-health-tool/package-generation/ig-carinbb/gen) will contain the following directory structure.


└── carinbb_package
    ├── Ballerina.toml
    ├── Package.md
    ├── initializer.bal
    ├── resource_c4bbcoverage.bal
    ├── resource_c4bbexplanation_of_benefit.bal
    ├── resource_c4bbexplanation_of_benefit_inpatient_institutional.bal
    ├── resource_c4bbexplanation_of_benefit_oral.bal
    ├── resource_c4bbexplanation_of_benefit_outpatient_institutional.bal
    ├── resource_c4bbexplanation_of_benefit_pharmacy.bal
    ├── resource_c4bbexplanation_of_benefit_professional_non_clinician.bal
    ├── resource_c4bborganization.bal
    ├── resource_c4bbpatient.bal
    ├── resource_c4bbpractitioner.bal
    ├── resource_c4bbrelated_person.bal
    ├── resources
    ├── tests
    └── variables.bal

Build the generated package.


$ cd ig-carinbb/gen/carinbb_package
$ bal pack
Compiling source
        healthcare_samples/carinbb_package:0.0.1

Creating bala
        target/bala/healthcare_samples-carinbb_package-any-0.0.1.bala

Push it to a repository.

Tip: You can push either to the local repository or to Ballerina Central, which is a remote repository.


$ bal push --repository local
Successfully pushed target/bala/healthcare_samples-carinbb_package-any-0.0.1.bala to 'local' repository.

Use the generated package

Follow the steps below to use the generated package by running the cloned Ballerina project.

Navigate to the cloned working-with-health-tool/package-generation/carinbb-patient-service directory.

Info: You can change the dependency (name and version) of the generated package in the carinbb-patient-service/Ballerina.toml file of this cloned Ballerina project directory as preferred.

Run the cloned Ballerina project and validate the output.


$ bal run
Compiling source
        healthcare_samples/carinbb_ballerina:1.0.0

Running executable

Invoke the API to try it out.


$ curl http://localhost:9090/Patient/2121

You can view the response shown below.


{
    "resourceType": "Patient",
    "gender": "male",
    "id": "2121",
    "identifier": [
        {
            "system": "http://hl7.org/fhir/sid/us-ssn",
            "value": "2121"
        }
    ],
    "meta": {
        "profile": [
            "http://hl7.org/fhir/us/carin-bb/StructureDefinition/C4BB-Patient"
        ]
    },
    "name": [
        {
            "family": "Doe",
            "given": [
                "John",
                "Hemish"
            ]
        }
    ]
}

Template generation

The tool can also be used to generate Ballerina templates for FHIR APIs for the FHIR resources in an implementation guide. FHIR integration developers can utilize these API templates by customizing them to align with their specific business logic and subsequently exposing them as standard FHIR APIs.

Template generation usage

The tool supports the template generation usage as follows.


$ bal health fhir [-m | --mode] template
            [--dependent-package] <dependent-ballerina-package-name> 
            [-o | --output] <output-location>
            [--org-name] <template-organization-name>
            [--included-profile] <profile(s)-to-include-in-generation>
            [--excluded-profile] <profile(s)-to-exclude-in-generation>
            <fhir-specification-directory-path>

Template generation command options

Command option	Description	Mandatory/Optional
`-m, --mode`	If `mode` is set to `template`, Ballerina templates for FHIR APIs can be generated.	Mandatory
`--dependent-package`	Fully qualified name of the published Ballerina package containing the IG resources (e.g., `<org>/<package>`). This option can be used to generate Ballerina templates for FHIR APIs specifically for the resources in the given IG. The package name part of this value will be added as a prefix to the template name.	Mandatory
`-o, --output`	Location of the generated Ballerina artifacts. If this path is not specified, the output will be written to the same directory from which the command is run.	Optional
`--org-name`	Organization name of the Ballerina templates for FHIR APIs to be generated. For more information, see the `org` field.	Optional
`--included-profile`	If one or more specific FHIR profiles need to be generated as Ballerina templates, specify the profile URL(s) as the value of this parameter. This argument can be used more than once.	Optional
`--excluded-profile`	If one or more specific FHIR profiles need to be skipped when generating Ballerina templates, specify the profile URL(s) as the value of this parameter. This argument can be used more than once.	Optional

Template generation example

Follow the steps below to try out an example template generation use case of the Health tool.

Clone the example project

Clone the artifacts of the example and extract them to a preferred location.

The cloned directory includes the ig-uscore/definitions directory, which includes the definition files of the FHIR specification.

Generate the templates

Follow the steps below to run the Health tool and generate the Ballerina templates for FHIR APIs for the selected package.

Note: You need to have a Ballerina package containing IG-specific FHIR resource data models to generate FHIR IG templates. You can use the package mode of the Health tool for easy generation of this package. This example uses the health.fhir.r4.uscore501 package in Ballerina Central.

Navigate to the cloned working-with-health-tool/template-generation directory.

Run the tool with the required command options to generate the Ballerina templates for FHIR APIs.

Note: This example uses the definitions files downloaded from the JSON Definitions ZIP archive of the US Core implementation guide to generate the templates.


$ bal health fhir -m template -o ig-uscore/gen --org-name healthcare_samples --dependent-package ballerinax/health.fhir.r4.uscore501 ig-uscore/definitions
[INFO] Generating templates for all FHIR profiles...
[INFO] Ballerina FHIR API templates generation completed successfully. Generated templates can be found at: /tmp/healthcare-samples/working-with-health-tool/template-generation/ig-uscore/gen

The generated folder (i.e., working-with-health-tool/template-generation/ig-uscore/gen) will contain the following directory structure.


.
|____device
| 	|____api_config.bal
| 	|____service.bal
|	|____.gitignore
|	|____Package.md
| 	|____Ballerina.toml
|____observation
|	|____api_config.bal
| 	|____service.bal
| 	|____.gitignore
| 	|____Package.md
| 	|____Ballerina.toml
|____patient
| 	|____api_config.bal
| 	|____service.bal
| 	|____Dependencies.toml
| 	|____.gitignore
| 	|____Package.md
| 	|____Ballerina.toml
|____practitioner
| 	|____api_config.bal
| 	|____service.bal
| 	|____Dependencies.toml
| 	|____.gitignore
| 	|____Package.md
| 	|____Ballerina.toml
|____practitionerrole
|	|____api_config.bal
|	|____service.bal
| 	|____.gitignore
| 	|____Package.md
| 	|____Ballerina.toml
|____procedure
| 	|____api_config.bal
| 	|____service.bal
| 	|____.gitignore
| 	|____Package.md
| 	|____Ballerina.toml
|____relatedperson
| 	|____api_config.bal
| 	|____service.bal
| 	|____.gitignore
| 	|____Package.md
| 	|____Ballerina.toml

Use the generated templates

Follow the steps below to use the generated API templates by running the cloned Ballerina project.

Navigate to the generated working-with-health-tool/template-generation/ig-uscore/gen/practitioner/ directory.

Update the get fhir/r4/Practitioner/[string id] method in the corresponding working-with-health-tool/template-generation/ig-uscore/gen/practitioner/service.bal file with the code below to implement the business logic.

Info: You can use VS Code to open the generated Ballerina templates for FHIR APIs and implement the business logic in it. It has Ballerina language support via an extension, which assists on both syntactic and semantic aspects.


isolated resource function get fhir/r4/Practitioner/[string id] (r4:FHIRContext fhirContext) returns Practitioner|r4:OperationOutcome|r4:FHIRError {
    Practitioner practitioner = {
        resourceType: "Practitioner",
        id: "1",
        meta: {
            lastUpdated: "2021-08-24T10:10:10Z",
            profile: [
                "http://hl7.org/fhir/us/core/StructureDefinition/us-core-practitioner"
            ]
        },
        identifier: [
            {
                use: "official",
                system: "http://hl7.org/fhir/sid/us-npi",
                value: "1234567890"
            }
        ],
        name: [
            {
                use: "official",
                family: "Smith",
                given: [
                    "John",
                    "Jacob"
                ],
                prefix: [
                    "Dr."
                ]
            }
        ]
    };
    return practitioner;
}

Run the service and verify the output response.


$ bal run
Compiling source
        healthcare_samples/health.fhir.r4.uscore501.practitioner:1.0.0

Running executable

Invoke the API to try it out.


$ curl http://localhost:9090/fhir/r4/Practitioner/1

You can view the response shown below.


{
"resourceType":"Practitioner",
"identifier":[
    {
        "system":"http://hl7.org/fhir/sid/us-npi",
        "use":"official",
        "value":"1234567890"
    }
],
"meta":{
    "lastUpdated":"2021-08-24T10:10:10Z",
    "profile":[
        "http://hl7.org/fhir/us/core/StructureDefinition/us-core-practitioner"
    ]
},
"name":[
    {
        "given":[
            "John",
            "Jacob"
        ],
        "prefix":[
            "Dr."
        ],
        "use":"official",
        "family":"Smith"
    }
],
"id":"1"
}

Why Ballerina

Get started with integration

Integration tools

References

Development tutorials

Build and run

Source code & dependencies

Style guide

Test, debug & document the code

Test Ballerina code

Bal persist

Run in the cloud

Configurability

Observability

Java interoperability

Build a GraalVM executable

Reuse code with Ballerina Central

Troubleshoot the runtime

Resources

Featured scenarios

Learn the language

Health tool (FHIR/HL7)

Prerequisites

Install the tool

Usage

Command options

Package generation

Package generation usage

Package generation command options

Package generation example

Clone the example project

Generate the package

Use the generated package

Template generation

Template generation usage

Template generation command options

Template generation example

Clone the example project

Generate the templates

Use the generated templates