@quicore/task-queue-fhir-tools

A specialized library for generating MongoDB update queries from FHIR resources. It extends the standard FHIR-to-Mongo mapping with support for deterministic IDs, multi-tenant data segregation (Customer IDs), and Task ID association.

Features

• Deterministic ID Generation: Creates consistent MongoDB _id values based on resource content and integration context.
• Multi-Tenancy: Support for tagging resources with customerId and optionally segregating data into customer-specific records.
• Task Association: Automatically links FHIR resources to specific Task IDs for workflow tracking.
• Bulk Processing: Efficiently process entire FHIR Bundles into categorized MongoDB bulkWrite operations.
• Chainable API: Fluid interface for setting metadata and configuration.

Installation

npm install @quicore/task-queue-fhir-tools

Usage

1. Processing a Single Resource

Use TaskFHIRQuery to generate an update query for an individual FHIR resource.

import { TaskFHIRQuery } from '@quicore/task-queue-fhir-tools';

const patientResource = {
    resourceType: "Patient",
    id: "123",
    name: [{ family: "Doe", given: ["John"] }]
};

const queryGenerator = new TaskFHIRQuery(patientResource)
    .setIntegrationId("my-integration-01")
    .setCustomerId("cust_99")
    .setTaskId("task_abc_123");

const mongoQueries = queryGenerator.query();
// Returns an array of updateOne operations

2. Processing a FHIR Bundle

Use TaskFHIRBundleProcessor to process a bundle and group queries by resourceType for efficient database writes.

import { TaskFHIRBundleProcessor } from '@quicore/task-queue-fhir-tools';

const bundle = {
    resourceType: "Bundle",
    entry: [ /* ... FHIR resources ... */ ]
};

const processor = new TaskFHIRBundleProcessor(bundle)
    .setCustomerId(["cust_A", "cust_B"])
    .setTaskId("workflow_456")
    .customerSpecificDataStore(true); // Generates separate records for each customer

const queriesByType = processor.query();

/* Output format:
{
  "Patient": [ { updateOne: { ... } }, ... ],
  "Observation": [ { updateOne: { ... } }, ... ]
}
*/

Key Concepts

Customer Specific Data Storage

By default, the processor adds customer IDs to an array (_sourceCustomerId) within a single shared record. If you call .customerSpecificDataStore(true), the library will:

1. Generate a unique record for each customer ID provided.
2. Append the customer ID to the canonical string used for hashing the _id.
3. Set a flag _customerSpecificStore: true in the document.

Canonical String Construction

The deterministic _id is derived from a canonical string. If customer segregation is enabled, the format is: {integrationId}::{resourceType}::{resourceId}::{customerId}

API Reference

TaskFHIRQuery

| Method | Description | | --- | --- | | setTaskId(string) | Associates the resource with a specific Task ID. | | setCustomerId(string \| string[]) | Adds one or more customer identifiers. | | customerSpecificDataStore(boolean) | If true, creates unique records per customer. | | query(upsert = true) | Finalizes and returns the MongoDB update array. |

TaskFHIRBundleProcessor

| Method | Description | | --- | --- | | setCustomerId(string \| string[]) | Sets the source customer(s) for all resources in the bundle. | | setTaskId(string) | Sets the task ID for all resources in the bundle. | | query() | Returns an object containing arrays of queries keyed by resource type. |

License

MIT © quicore