Add debug=true query param to populate-express and add README

push-populate-image.sh

@@ -19,8 +19,8 @@
 set -xe
 
 # Compile the Express app.
-cd services/assemble-express && npm run compile && cd -
+cd services/populate-express && npm run compile && cd -
 
 # Build the Docker image for multiple architectures, then push to Docker Hub.
-docker buildx build --file ./services/populate-express/Dockerfile --tag aehrc/smart-forms-populate:v2.2.5 \
+docker buildx build --file ./services/populate-express/Dockerfile --tag aehrc/smart-forms-populate:latest \
   --platform linux/amd64,linux/arm64/v8 --push --no-cache .

services/extract-express/README.md

@@ -1,6 +1,6 @@
-# SDC StructureMap-based $extract
+# SDC StructureMap-based $extract ExpressJS service
 
-A Typescript reference implementation of the [$extract](https://hl7.org/fhir/uv/sdc/OperationDefinition-QuestionnaireResponse-extract.html) operation from the [HL7 FHIR Structured Data Capture Specification](http://hl7.org/fhir/uv/sdc/ImplementationGuide/hl7.fhir.uv.sdc).
+A [ExpressJS](https://expressjs.com/) Typescript reference implementation of the [$extract](https://hl7.org/fhir/uv/sdc/OperationDefinition-QuestionnaireResponse-extract.html) operation from the [HL7 FHIR Structured Data Capture Specification](http://hl7.org/fhir/uv/sdc/ImplementationGuide/hl7.fhir.uv.sdc).
 It is an abstraction on top of an existing StructureMap [$transform](https://hl7.org/fhir/r4/structuremap-operation-transform.html) operation to perform the extraction. 
 
 A proof-of-concept StructureMap $transform is defined on https://proxy.smartforms.io/fhir/StructureMap/$transform, leveraging Brian's .NET mapping engine from https://github.com/brianpos/fhir-net-mappinglanguage/tree/main/demo-map-server.
@@ -18,14 +18,14 @@ FORMS_SERVER_AUTH_TOKEN =
 
 If you are planning to deploy this as a microservice on your EHR server, it is required for your EHR server to have a StructureMap $transform operation defined.
 
-If EHR_SERVER_URL is left empty, the service will use the request endpoint as the EHR server URL. i.e. Deploying this service on http://localhost:3003 will result in a call to http://localhost:3003/StructureMap/$transform during execution of the $extract operation.
+If EHR_SERVER_URL is left empty, the service will use the request endpoint as the EHR server URL. i.e. Deploying this service on http://localhost:3003/fhir will result in a call to http://localhost:3003/fhir/StructureMap/$transform during execution of the $extract operation.
 
 If your EHR server does not have a StructureMap $transform operation defined, you can set EHR_SERVER_URL to https://proxy.smartforms.io/fhir/StructureMap/$transform. 
 
-Note: The $transform service on https://proxy.smartforms.io/fhir only performs processing - it does not persist any data. The service might not be up indefinitely, given its a POC.
+Note: The $transform service on https://proxy.smartforms.io/fhir only performs processing - it does not persist any data.
 
 ## Docker Usage
-Run `docker run -p 3003:3003 aehrc/smart-forms-extract` for local usage.
+Run `docker run -p 3003:3003 aehrc/smart-forms-extract`.
 
 You can use `docker run -p 3003:3003 -e EHR_SERVER_URL=https://proxy.smartforms.io/fhir aehrc/smart-forms-extract` to use the POC $transform operation. 
 

services/populate-express/src/README.md

@@ -0,0 +1,39 @@
+# SDC $populate ExpressJS service
+
+An [ExpressJS](https://expressjs.com/) Typescript reference implementation of the [$populate](http://hl7.org/fhir/uv/sdc/OperationDefinition-Questionnaire-populate.html) operation from the [HL7 FHIR Structured Data Capture Specification](http://hl7.org/fhir/uv/sdc/ImplementationGuide/hl7.fhir.uv.sdc).
+It builds on [@aehrc/sdc-populate](https://www.npmjs.com/package/@aehrc/sdc-populate), nicely packaging it into an ExpressJS app that can be deployed as a microservice.
+
+## Configuration
+Create a .env file (or copy from example.env) in the root of the project with the following:
+```env
+EHR_SERVER_URL =
+EHR_SERVER_AUTH_TOKEN =
+
+TERMINOLOGY_SERVER_URL=
+TERMINOLOGY_SERVER_AUTH_TOKEN=
+```
+
+If EHR_SERVER_URL is left empty, the service will use the request endpoint as the EHR server URL (recommended).
+i.e. Deploying this service on http://localhost:3001/fhir will result in calls to fetch resources on the http://localhost:3001/fhir FHIR API during execution of the $populate operation.
+
+By default, sdc-populate uses https://r4.ontoserver.csiro.au/fhir as the terminology server under the hood. If you want to use a different terminology server, you can set the `TERMINOLOGY_SERVER_URL` and `TERMINOLOGY_SERVER_AUTH_TOKEN` environment variables.
+
+## Docker Usage
+
+Run `docker run -p 3001:3001 aehrc/smart-forms-populate`.
+
+You can supply your `docker run` command environment variables. i.e.
+
+```docker run -p 3001:3001 -e EHR_SERVER_URL=https://proxy.smartforms.io/fhir aehrc/smart-forms-populate```
+
+```docker run -p 3001:3001 -e TERMINOLOGY_SERVER_URL=https://tx.ontoserver.csiro.au/fhir aehrc/smart-forms-populate```
+
+Docker image: https://hub.docker.com/r/aehrc/smart-forms-populate
+
+## Sample implementation
+A sample implementation of this service is available at https://smartforms.csiro.au/fhir/Questionnaire/$populate.
+https://smartforms.csiro.au/fhir only stores Questionnaire definitions and does not contain any clinical data. Therefore when using this sample implementation, contextual information for pre-population should be provided as actual FHIR resources, not references.
+
+This service also allows you to specify a query parameter `debug=true` which returns a FHIRPath context object (useful for debugging!) as the `contextResult-custom` output parameter.
+
+Note: The $populate service on https://smartforms.csiro.au/fhir only performs processing - it does not persist any data.

services/populate-express/src/index.ts

@@ -17,7 +17,7 @@
 
 import express from 'express';
 import cors from 'cors';
-import type { IssuesParameter } from '@aehrc/sdc-populate';
+import type { IssuesParameter, ResponseParameter } from '@aehrc/sdc-populate';
 import { isInputParameters, populate } from '@aehrc/sdc-populate';
 import type { RequestConfig } from './callback';
 import { fetchResourceCallback } from './callback';
@@ -54,6 +54,7 @@ app.get('/fhir/Questionnaire/\\$populate', (_, res) => {
 });
 
 app.post('/fhir/Questionnaire/\\$populate', async (req, res) => {
+  const debugMode = req.query['debug'] === 'true';
   const ehrServerRequestConfig: RequestConfig = {
     url: req.protocol + '://' + req.get('host') + '/fhir'
   };
@@ -108,6 +109,14 @@ app.post('/fhir/Questionnaire/\\$populate', async (req, res) => {
       return;
     }
 
+    // Filter contextResult-custom based on debug=true query parameter
+    if (!debugMode) {
+      const filtered = outputParameters.parameter.filter(
+        (param) => param.name !== 'contextResult-custom'
+      ) as [ResponseParameter, IssuesParameter] | [ResponseParameter];
+      outputParameters.parameter = filtered;
+    }
+
     // Return valid output params
     const issuesParameter = outputParameters.parameter.find(
       (param): param is IssuesParameter => param.name === 'issues'