Merge pull request #794 from aehrc/issue/692

Issue/692
aehrc · May 19, 2024 · 676fafe · 676fafe
2 parents e884d2c + 4365a73
commit 676fafe
Show file tree

Hide file tree

Showing 63 changed files with 4,294 additions and 92 deletions.
diff --git a/apps/demo-renderer-app/package-lock.json b/apps/demo-renderer-app/package-lock.json
diff --git a/apps/demo-renderer-app/package.json b/apps/demo-renderer-app/package.json
@@ -11,7 +11,7 @@
     "preview": "vite preview"
   },
   "dependencies": {
-    "@aehrc/sdc-populate": "^1.5.0",
+    "@aehrc/sdc-populate": "^1.8.0",
     "@aehrc/smart-forms-renderer": "file:../../packages/smart-forms-renderer",
     "@tanstack/react-query": "^4.36.1",
     "react": "^18.2.0",

diff --git a/apps/smart-forms-app/package.json b/apps/smart-forms-app/package.json
@@ -26,7 +26,7 @@
   "homepage": "https://github.com/aehrc/smart-forms#readme",
   "dependencies": {
     "@aehrc/sdc-assemble": "^1.2.0",
-    "@aehrc/sdc-populate": "^1.8.0",
+    "@aehrc/sdc-populate": "^1.9.0",
     "@aehrc/smart-forms-renderer": "^0.28.0",
     "@emotion/react": "^11.11.4",
     "@emotion/styled": "^11.11.5",

diff --git a/documentation/docs/sdc/advanced/fundamental.mdx b/documentation/docs/sdc/advanced/fundamental.mdx
@@ -129,8 +129,6 @@ Allows one or more values to be pre-filled in the answer when initially renderin
 
 Questions using answerOption can use `answerOption.initialSelected` as an alternative.
 
-[//]: # 'FIXME add support for initialSelected'
-
 :::note
 
 Multiple initial values can be used in repeating items. There can only be one initial value for non-repeating items.

diff --git a/documentation/docs/sdc/calculations.mdx b/documentation/docs/sdc/calculations.mdx
@@ -22,6 +22,14 @@ The only way to use calculations is via **calculatedExpressions** currently.
 
 :::
 
+### Variable
+
+Used to define a variable that is available for use in [expressions](http://hl7.org/fhir/uv/sdc/expressions.html) within the same item and any descendant items. This allows it to be consumed by calculatedExpressions when the renderer executes a calculation.
+
+For more information, refer to http://hl7.org/fhir/uv/sdc/expressions.html#variable.
+
+For usages, refer to the [CalculatedExpression](#calculatedexpression) section on this page.
+
 ### CalculatedExpression
 
 The basis of calculations in SDC. Allows an item value to update continuously as the answers to dependent questions change.

diff --git a/documentation/docs/sdc/population.mdx b/documentation/docs/sdc/population.mdx
@@ -2,14 +2,133 @@
 sidebar_position: 2
 ---
 
+import IframeContainer from '../../src/react/IframeContainer';
+
 # Pre-population
 
-Pre-population Placeholder
+Pre-population is a mechanism to pre-fill form questions with information already present in the clinical system. It is a way to reduce the burden on the user to fill in information that is already known.
 
-- [initial](http://hl7.org/fhir/uv/sdc/behavior.html#initial)
+For a detailed explanation, see the [Form Population](https://hl7.org/fhir/uv/sdc/populate.html) section in the SDC spec.
+
+The elements/extensions that fall under this category are:
+
+#### Extensions containing pre-population queries:
+
+- [launchContext](http://hl7.org/fhir/uv/sdc/expressions.html#launchContext)
 - [variable](http://hl7.org/fhir/uv/sdc/expressions.html#variable)
+- [x-fhir-query](http://hl7.org/fhir/uv/sdc/expressions.html#x-fhir-query-enhancements)
+- [sourceQueries](https://build.fhir.org/ig/HL7/sdc/populate.html#structuremap-based-population)
+- [itemPopulationContext](http://hl7.org/fhir/uv/sdc/expressions.html#itemPopulationContext)
+
+#### Elements/expressions defined at the question to be pre-populated:
+
+- [initial](http://hl7.org/fhir/uv/sdc/behavior.html#initial)
 - [initialExpression](http://hl7.org/fhir/uv/sdc/expressions.html#initialExpression)
 - [calculatedExpression](http://hl7.org/fhir/uv/sdc/expressions.html#calculatedExpression)
-- [itemPopulationContext](http://hl7.org/fhir/uv/sdc/expressions.html#itemPopulationContext)
-- [launchContext](http://hl7.org/fhir/uv/sdc/expressions.html#launchContext)
-- [x-fhir-query](http://hl7.org/fhir/uv/sdc/expressions.html#x-fhir-query-enhancements)
+
+### LaunchContext
+
+Allows information to be passed into the execution environment based on the context in which the Questionnaire is being pre-populated i.e patient, user, encounter, etc.
+
+The passed information is known as "in context" within the launching system, and is subsequently applied in pre-population queries.
+
+#### Example
+
+Below is an example of how a launchContext extension is defined in the questionnaire.
+It specifies that the patient in context is to be used to pre-populate the form.
+
+```json
+{
+  "url": "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-launchContext",
+  "extension": [
+    {
+      "url": "name",
+      "valueCoding": {
+        "system": "http://hl7.org/fhir/uv/sdc/CodeSystem/launchContext",
+        "code": "patient"
+      }
+    },
+    {
+      "url": "type",
+      "valueCode": "Patient"
+    },
+    {
+      "url": "description",
+      "valueString": "The patient that is to be used to pre-populate the form"
+    }
+  ]
+}
+```
+
+In the below x-fhir-query variable, `{{%patient.id}}` is a reference to the launchContext extension defined above. During pre-population, the value of `{{%patient.id}}` will be replaced with the actual patient id before the query is executed.
+
+```json
+{
+  "url": "http://hl7.org/fhir/StructureDefinition/variable",
+  "valueExpression": {
+    "name": "Condition",
+    "language": "application/x-fhir-query",
+    "expression": "Condition?patient={{%patient.id}}"
+  }
+}
+```
+
+For usages, refer to initial, initialExpression, and calculatedExpression sections on this page.
+
+### X-FHIR-Query Variable
+
+The variable extension is used to define a variable that is available for use in expressions within the same item and any descendant items.
+
+When the variable is defined using the `application/x-fhir-query` language, it can be used to contain a query that is executed against the FHIR server during pre-population to retrieve the value to be used in the expression.
+
+For more information, refer to http://hl7.org/fhir/uv/sdc/expressions.html#x-fhir-query-enhancements.
+
+#### Example
+
+Below is an example of how a variable extension using the `application/x-fhir-query` language is defined in the questionnaire.
+
+It specifies a variable called "Condition" and it's value is to be retrieved by executing the query `Condition?patient={{%patient.id}}` on the launching system.
+`{{%patient.id}}` is a reference to a defined launchContext, which will be replaced with the actual patient ID before the query is executed.
+
+After the query is executed, the expression can be consumed by pre-population expressions during the pre-population process.
+
+```json
+{
+  "url": "http://hl7.org/fhir/StructureDefinition/variable",
+  "valueExpression": {
+    "name": "Condition",
+    "language": "application/x-fhir-query",
+    "expression": "Condition?patient={{%patient.id}}"
+  }
+}
+```
+
+For usages, refer to initial, initialExpression, and calculatedExpression sections on this page.
+
+### SourceQueries
+
+[//]: # 'TODO'
+
+### Initial
+
+Allows one or more values to be pre-filled in the answer when initially rendering the questionnaire for user input. Initial values can't be specified for groups or display items.
+
+This uses answers defined in the questionnaire itself, instead of relying on a FHIR server to provide the initial values.
+
+Questions using answerOption can use `answerOption.initialSelected` as an alternative.
+
+:::note
+
+Multiple initial values can be used in repeating items. There can only be one initial value for non-repeating items.
+
+:::
+
+#### Basic Usage
+
+<IframeContainer storyUrl="https://smartforms.csiro.au/storybook/index.html?path=/story/component-sdc-8-1-4-advanced-other--read-only">
+  <iframe
+    src="https://smartforms.csiro.au/storybook/iframe.html?args=&id=component-sdc-8-1-4-advanced-other--read-only"
+    width="100%"
+    height="100"
+  />
+</IframeContainer>
diff --git a/package-lock.json b/package-lock.json
diff --git a/packages/sdc-populate/package.json b/packages/sdc-populate/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@aehrc/sdc-populate",
-  "version": "1.8.0",
+  "version": "2.0.0",
   "description": "Performs the $populate operation from the HL7 FHIR SDC (Structured Data Capture) specification: http://hl7.org/fhir/uv/sdc",
   "main": "lib/index.js",
   "scripts": {

diff --git a/...es/sdc-populate/src/api/expandValueset.ts → ...stionnaireOperation/api/expandValueset.ts b/...es/sdc-populate/src/api/expandValueset.ts → ...stionnaireOperation/api/expandValueset.ts
diff --git a/...dc-populate/src/api/fetchQuestionnaire.ts → ...nnaireOperation/api/fetchQuestionnaire.ts b/...dc-populate/src/api/fetchQuestionnaire.ts → ...nnaireOperation/api/fetchQuestionnaire.ts
diff --git a/.../sdc-populate/src/api/lookupCodeSystem.ts → ...ionnaireOperation/api/lookupCodeSystem.ts b/.../sdc-populate/src/api/lookupCodeSystem.ts → ...ionnaireOperation/api/lookupCodeSystem.ts
diff --git a/packages/sdc-populate/src/SDCPopulateQuestionnaireOperation/index.ts b/packages/sdc-populate/src/SDCPopulateQuestionnaireOperation/index.ts
@@ -0,0 +1,22 @@
+/*
+ * Copyright 2024 Commonwealth Scientific and Industrial Research
+ * Organisation (CSIRO) ABN 41 687 119 230.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// Export interfaces
+export * from './interfaces';
+
+// Export utils
+export * from './utils';
diff --git a/...late/src/interfaces/callback.interface.ts → ...peration/interfaces/callback.interface.ts b/...late/src/interfaces/callback.interface.ts → ...peration/interfaces/callback.interface.ts
diff --git a/...e/src/interfaces/expressions.interface.ts → ...ation/interfaces/expressions.interface.ts b/...e/src/interfaces/expressions.interface.ts → ...ation/interfaces/expressions.interface.ts
diff --git a/...ages/sdc-populate/src/interfaces/index.ts → ...uestionnaireOperation/interfaces/index.ts b/...ages/sdc-populate/src/interfaces/index.ts → ...uestionnaireOperation/interfaces/index.ts
diff --git a/...c/interfaces/inputParameters.interface.ts → ...n/interfaces/inputParameters.interface.ts b/...c/interfaces/inputParameters.interface.ts → ...n/interfaces/inputParameters.interface.ts
diff --git a/.../interfaces/outputParameters.interface.ts → .../interfaces/outputParameters.interface.ts b/.../interfaces/outputParameters.interface.ts → .../interfaces/outputParameters.interface.ts
@@ -50,6 +50,7 @@ export interface IssuesParameter extends ParametersParameter {
 }
 
 // This is used for debugging purposes, it does not exist in the FHIR spec
+// It is used to return the context result to the renderer
 export interface CustomContextResultParameter extends ParametersParameter {
   name: 'contextResult-custom';
   valueAttachment: Attachment;

diff --git a/...populate/src/utils/addDisplayToCodings.ts → ...ireOperation/utils/addDisplayToCodings.ts b/...populate/src/utils/addDisplayToCodings.ts → ...ireOperation/utils/addDisplayToCodings.ts
diff --git a/...es/sdc-populate/src/utils/answerOption.ts → ...stionnaireOperation/utils/answerOption.ts b/...es/sdc-populate/src/utils/answerOption.ts → ...stionnaireOperation/utils/answerOption.ts
diff --git a/...c-populate/src/utils/constructResponse.ts → ...naireOperation/utils/constructResponse.ts b/...c-populate/src/utils/constructResponse.ts → ...naireOperation/utils/constructResponse.ts