SDC-Populate

A Typescript reference implementation of the $populate operation from the HL7 FHIR Structured Data Capture Specification designed for Form Population.

Check out the API Reference for technical specifications.

Usage

There are two ways to use this package:

1. Using it in a web app
2. Using it in a backend service e.g. ExpressJS

Using it in a web app

It is recommended to use populateQuestionnaire(), which performs an in-app population. This means that the app is not sending data to an external server, but rather using the library to populate the questionnaire in the app itself.

const { populateSuccess, populateResult } = await populateQuestionnaire({
  questionnaire: yourQuestionnaireResource,
  fetchResourceCallback: yourFetchResourceCallbackFunction,
  fetchResourceRequestConfig: yourFetchResourceRequestConfig,
  patient: yourPatient,
});

// Pre-population is successful
if (populateSuccess && populateResult !== null) {
  const questionnaireResponse = populateResult.populatedResponse;
  
  // Do things with the pre-populated questionnaireResponse...
}

You will also need to define your own fetchResourceCallback function and fetchResourceRequestConfig. This function is responsible for fetching resources from your FHIR server. It should return a promise that resolves to the resource you want to fetch.

import { FetchResourceRequestConfig, FetchResourceCallback } from '@aehrc/sdc-populate';

const ABSOLUTE_URL_REGEX = /^(https?|ftp):\/\/[^\s/$.?#].[^\s]*$/;

export const yourFetchResourceRequestConfig: FetchResourceRequestConfig = {
  sourceServerUrl: 'https://proxy.smartforms.io/fhir',
  authToken: string | null
};

export const yourFetchResourceCallbackFunction: FetchResourceCallback = async (
  query: string,
  requestConfig: FetchResourceRequestConfig
) => {
  let { sourceServerUrl } = requestConfig;
  const { authToken } = requestConfig;

  const headers: Record<string, string> = {
    Accept: 'application/json;charset=utf-8'
  };

  if (authToken) {
    headers['Authorization'] = `Bearer ${authToken}`;
  }

  if (!sourceServerUrl.endsWith('/')) {
    sourceServerUrl += '/';
  }

  const requestUrl = ABSOLUTE_URL_REGEX.test(query) ? query : `${sourceServerUrl}${query}`;
  const response = await fetch(requestUrl, { headers });

  if (!response.ok) {
    throw new Error(`HTTP error when performing ${requestUrl}. Status: ${response.status}`);
  }

  return response.json();
};

Available parameters for populateQuestionnaire():

| Parameter | Description | |-------------------------------|--------------------------------------------------------------------------------------------------| | questionnaire | Questionnaire to populate | | fetchResourceCallback | A callback function to fetch resources from your FHIR server | | fetchResourceRequestConfig | Any request configuration to be passed to the fetchResourceCallback (e.g., headers, auth, etc.) | | patient | Patient resource as patient in context | | user | Practitioner resource as user in context (optional) | | encounter | Encounter resource as encounter in context (optional) | | fetchTerminologyCallback | A callback function to fetch terminology resources (optional) | | fetchTerminologyRequestConfig | Any request configuration to be passed to the fetchTerminologyCallback (e.g., headers, auth, etc.) (optional) |

Using it in a backend service

Using this library in a backend service requires more pre-configuration. Due to how the $populate works, you will need to provide a bunch of input parameters to the populate() function.

There is a sample implementation of how to use the populate() function in https://github.com/aehrc/smart-forms/blob/main/services/populate-express/src/index.ts.

Local development notes

It's recommended to run this library within a web app or a service if you're doing local development. This library compiles to both CommonJS and ES Modules, so there is no problems in using it across web frameworks and Node-based backends.

To compile the code, use npm run compile. To watch for changes, use npm run watch.

Note: Do not use tsc or tsc -w as it will only compile to ES Modules, which means it will not work with CommonJS-based implementations.