From 6eb151c3bcd40cd7b287ab7a6140bd9868a89cb8 Mon Sep 17 00:00:00 2001 From: Sean Fong Date: Sun, 19 May 2024 09:39:08 +0930 Subject: [PATCH] Add first cut of pre-population docs --- .../docs/sdc/advanced/fundamental.mdx | 2 - documentation/docs/sdc/calculations.mdx | 8 ++ documentation/docs/sdc/population.mdx | 130 +++++++++++++++++- .../assets/questionnaires/QFormPopulation.ts | 16 --- 4 files changed, 132 insertions(+), 24 deletions(-) diff --git a/documentation/docs/sdc/advanced/fundamental.mdx b/documentation/docs/sdc/advanced/fundamental.mdx index e8355422f..d65aa8739 100644 --- 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 index bb6bb536f..1f2dfa87a 100644 --- 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 index b9d5e21ef..82b052fca 100644 --- a/documentation/docs/sdc/population.mdx +++ b/documentation/docs/sdc/population.mdx @@ -2,15 +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. + +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: -- [initial](http://hl7.org/fhir/uv/sdc/behavior.html#initial) -- [variable](http://hl7.org/fhir/uv/sdc/expressions.html#variable) -- [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) +- [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) + +### 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 + + +