From 6dc9d3cda2a652670c5c9fc988e84fde1e372b20 Mon Sep 17 00:00:00 2001 From: Sean Fong Date: Wed, 3 Jul 2024 12:50:09 +0930 Subject: [PATCH] Add debug=true query param to populate-express and add README --- push-populate-image.sh | 4 +-- services/extract-express/README.md | 10 +++---- services/populate-express/src/README.md | 39 +++++++++++++++++++++++++ services/populate-express/src/index.ts | 11 ++++++- 4 files changed, 56 insertions(+), 8 deletions(-) create mode 100644 services/populate-express/src/README.md diff --git a/push-populate-image.sh b/push-populate-image.sh index bc5c350a..dcdad19c 100644 --- a/push-populate-image.sh +++ b/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 . diff --git a/services/extract-express/README.md b/services/extract-express/README.md index 2ff47e40..1c6e7c58 100644 --- a/services/extract-express/README.md +++ b/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. diff --git a/services/populate-express/src/README.md b/services/populate-express/src/README.md new file mode 100644 index 00000000..9a70eb2c --- /dev/null +++ b/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. diff --git a/services/populate-express/src/index.ts b/services/populate-express/src/index.ts index 3fb2b56f..003368f0 100644 --- a/services/populate-express/src/index.ts +++ b/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'