Bridging the Gap: Connecting to EHR Systems with Ballerina FHIR Client and Ballerina FHIR Service

An EHR (Electronic Health Record) System is a digital platform used by healthcare providers to store and manage patient information. It stores patient data such as medical history, diagnoses, medications, treatment plans, immunization records, lab results, and more, providing a comprehensive view of the patient’s health.

Epic and Cerner are two of the largest EHR systems in the world of healthcare interoperability, offering third-party developers access to their APIs to interact with patient data. However, these systems use different client authentication mechanisms, specifically when securing their OAuth 2.0-based API interactions. Epic uses the Private Key JWT (PKJWT) method for client authentication, while Cerner uses the Client Credentials method, a standard OAuth 2.0 mechanism.

The Ballerina FHIR client supports both mechanisms and connecting with Epic or Cerner requires just a few lines of code.

Using Ballerina FHIR Client

The Ballerina **FHIR Client** which is a Ballerina library, offers a specialized, out-of-the-box solution for handling healthcare data in FHIR format, designed to simplify the integration and interaction with healthcare APIs. If you’re developing a client application that consumes FHIR APIs, Ballerina FHIR client is the ideal choice to use for all the FHIR interactions with the source FHIR server.

1. FHIR-specific functionality: The FHIR Client abstracts away the complexity of constructing and parsing FHIR messages. It understands FHIR resources natively, allowing you to work with high-level operations like creating, retrieving, or updating resources without needing to build HTTP requests manually.
2. Simplified Data Handling: When using a generic HTTP client, you need to manually handle JSON or XML serialization and deserialization for FHIR resources, which can be error-prone and time-consuming. The FHIR Client handles the FHIR resource formats directly, saving you from manually managing these transformations.
3. Better Error Handling: The FHIR Client has built-in error handling tailored for healthcare data exchange. It can recognize specific FHIR-related errors and help you handle exceptions more gracefully.

Using Ballerina FHIR Service

However, implementing FHIR APIs is not always straightforward. It involves several things, such as validating client request headers, processing search parameters and validating their formats and considering validations at resource creation levels, such as resource type checks, payload format validations, and handling error responses.

All the complexities are handled in FHIR Service which is a Ballerina library that can be used to create a FHIR listener and a service.

If you are a FHIR backend developer who integrates various healthcare systems with a FHIR server, Ballerina FHIR service simplifies your effort with features like, in-built parameter resolution, FHIR resource type validations supporting business-to-business connectivity.

Using FHIR Client and FHIR R4 Service to Connect to Cerner: A Practical Implementation

Environment setup:

1. Create a Developer Account in Cerner
2. Register your application with desired scopes and obtain Client ID and Client Secret.
3. Install Ballerina

Set up the Ballerina Project

1. Create a new Ballerina project by executing the below.

bal new cerner-connect

2. In the project root, create a Config.toml file as below and your obtained CLIENT_ID and CLIENT_SECRET values.

base = "https://fhir-ehr-code.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d"
tokenUrl = "https://authorization.cerner.com/tenants/ec2458f2-1e24-41c8-b71b-0e701af7583d/protocols/oauth2/profiles/smart-v1/token"
clientId = "<CLIENT_ID>"
clientSecret = "<CLIENT_SECRET>"
scopes = ["system/Practitioner.read"]

3. Since we are fetching the Practitioner resource, we need to create an api_config.bal file that includes the search parameters.

[embed]

You can refer to all the api_config files for the FHIR international spec from here. Also we can generate Practitioner API template from Bal Health Tool by providing the specific FHIR Structure definition file. You can refer to this article on how to use the Bal Health Tool.

4. In the main.bal file have the following code.

[embed]

5. Run the Ballerina service.

bal run -- -Cballerina.http.traceLogConsole=true

6. Invoke the API as below.

curl --location 'http://localhost:7070/fhir/r4/Practitioner/593923

You can refer the code from here.