ballerinax/health.fhir.cds Ballerina library

Overview

CDS Hooks (2.0) package for building Clinical Decision Support integrations in Ballerina. It defines request, context, response, card, and action models used in CDS workflows defined in the CDS Hooks implementation guide(https://cds-hooks.hl7.org/2.0/).

Trademark Notice: FHIR® and the FHIR® logo are the registered trademarks of Health Level Seven International and their use does not constitute endorsement by HL7®.

Key Features

• Typed request and response models for CDS Hooks interactions
• Predefined context records for common hook types
• Structured card, suggestion, action, and link representations
• Simplifies implementation of CDS services and clients

CDS package

Package Overview

Capabilities and features

CDS resource types

Sample Usage

This section focuses on samples depicting how to use this package to implement CDS related integrations

Prerequisites

1. Install Ballerina 2201.8.2 or later

1. Validate the context data of CDS request

Sample below is using the CDS request resource in health.fhir.r4.cds package.

import ballerina/log;
import ballerinax/health.fhir.cds;

public function main() returns error? {
    json cdsRequestPayload = {
        "hookInstance": "d1577c69-dfbe-44ad-ba6d-3e05e953b2ea",
        "fhirServer": "http://hapi.fhir.org/baseR4",
        "hook": "patient-view",
        "fhirAuthorization": {
            "access_token": "some-opaque-fhir-access-token",
            "token_type": "Bearer",
            "expires_in": 300,
            "scope": "user/Patient.read user/Observation.read",
            "subject": "cds-service4"
        },
        "context": {
            "userId": "Practitioner/example",
            "patientId": "593380",
            "encounterId": "89284"
        },
        "prefetch": {
            "patientToGreet": {
                "resourceType": "Patient",
                "gender": "male",
                "birthDate": "1925-12-23",
                "id": "1288992",
                "active": true
            }
        }
    };

    json cdsServiceJson = {
        "description": "An example of a CDS Service that returns a static set of cards",
        "hook": "patient-view",
        "id": "static-patient-greeter",
        "title": "Static CDS Service Example",
        "prefetch": {
            "patientToGreet": "Patient/{{context.patientId}}"
        }
    };

    cds:CdsService cdsService = check cdsServiceJson.cloneWithType();
    cds:CdsRequest cdsRequest = check cdsRequestPayload.cloneWithType();
    cds:CdsError? validationResult = cds:validateContext(cdsRequest, cdsService);
    if validationResult is cds:CdsError {
        log:printError(string `Error message: ${validationResult.message()}`);
        log:printError(string `Error description: ${validationResult.detail().description ?: ""}`);
        log:printError(string `Status code: ${validationResult.detail().code}`);
    } else {
        log:printInfo("Context validation is successful!");
    }
}

2. Prefetch validation

import ballerina/log;
import ballerinax/health.fhir.cds;

public function main() returns error? {
    json payload = {
        "hookInstance": "d1577c69-dfbe-44ad-ba6d-3e05e953b2ea",
        "fhirServer": "http://hapi.fhir.org/baseR4",
        "hook": "patient-view",
        "fhirAuthorization": {
            "access_token": "some-opaque-fhir-access-token",
            "token_type": "Bearer",
            "expires_in": 300,
            "scope": "user/Patient.read user/Observation.read",
            "subject": "cds-service4"
        },
        "context": {
            "userId": "Practitioner/example",
            "patientId": "593380",
            "encounterId": "89284"
        },
        "prefetch": {
            "patientToGreet": {
                "resourceType": "Patient",
                "gender": "male",
                "birthDate": "1925-12-23",
                "id": "1288992",
                "active": true
            }
        }
    };

    json cdsServiceJson = {
        "description": "An example of a CDS Service that returns a static set of cards",
        "hook": "patient-view",
        "id": "static-patient-greeter",
        "title": "Static CDS Service Example",
        "prefetch": {
            "patientToGreet": "Patient/{{context.patientId}}"
        }
    };

    cds:CdsService cdsService = check cdsServiceJson.cloneWithType();
    cds:CdsRequest cdsRequest = check payload.cloneWithType();
    cds:CdsRequest|cds:CdsError result = cds:validateAndProcessPrefetch(cdsRequest, cdsService);

    if (result is cds:CdsError) {
        log:printError(string `Error message: ${result.message()}`);
        log:printError(string `Error description: ${result.detail().description ?: ""}`);
        log:printError(string `Status code: ${result.detail().code}`);
    } else {
        log:printInfo(string `Validated CDS request: ${result.toJsonString()}`);
    }
}