Merge pull request #1033 from aehrc/issue/997

Add support for preferred terminology servers
aehrc · Oct 8, 2024 · fd52504 · fd52504
2 parents dab2652 + a3d9c67
commit fd52504
Show file tree

Hide file tree

Showing 24 changed files with 253 additions and 19 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,10 @@ This log documents significant changes for the [@aehrc/smart-forms-renderer](htt
 Changelog only includes changes from version 0.36.0 onwards.
 
 
+## [0.44.0] - 2024-10-09
+### Added
+- Added support for the [preferredTerminologyServer](https://hl7.org/fhir/uv/sdc/STU3/StructureDefinition-sdc-questionnaire-preferredTerminologyServer.html) SDC extension.
+
 ## [0.43.1] - 2024-10-04
 ### Changed
 - Completely removed persisting "iframe-resizer" dependencies as a follow-up to v0.43.0.

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
@@ -12,7 +12,7 @@
   },
   "dependencies": {
     "@aehrc/sdc-populate": "^2.3.1",
-    "@aehrc/smart-forms-renderer": "^0.43.1",
+    "@aehrc/smart-forms-renderer": "^0.44.0",
     "@radix-ui/react-collapsible": "^1.1.0",
     "@radix-ui/react-slot": "^1.1.0",
     "@radix-ui/react-switch": "^1.1.0",

diff --git a/apps/smart-forms-app/package.json b/apps/smart-forms-app/package.json
@@ -28,7 +28,7 @@
   "dependencies": {
     "@aehrc/sdc-assemble": "^1.3.1",
     "@aehrc/sdc-populate": "^2.3.1",
-    "@aehrc/smart-forms-renderer": "^0.43.1",
+    "@aehrc/smart-forms-renderer": "^0.44.0",
     "@emotion/react": "^11.13.0",
     "@emotion/styled": "^11.13.0",
     "@fontsource/material-icons": "^5.0.18",

diff --git a/...rms-app/src/features/playground/components/StoreStateViewers/QuestionnaireStoreViewer.tsx b/...rms-app/src/features/playground/components/StoreStateViewers/QuestionnaireStoreViewer.tsx
@@ -6,6 +6,7 @@ import GenericStatePropertyPicker from './GenericStatePropertyPicker.tsx';
 const questionnaireStoreStatePropertyNames: string[] = [
   'sourceQuestionnaire',
   'itemTypes',
+  'itemPreferredTerminologyServers',
   'tabs',
   'currentTabIndex',
   'variables',

diff --git a/apps/smart-forms-app/src/features/playground/hooks/useShowQuestionnaireStoreProperty.ts b/apps/smart-forms-app/src/features/playground/hooks/useShowQuestionnaireStoreProperty.ts
@@ -20,6 +20,8 @@ import { useQuestionnaireStore } from '@aehrc/smart-forms-renderer';
 function useShowQuestionnaireStoreProperty(selectedProperty: string) {
   const sourceQuestionnaire = useQuestionnaireStore.use.sourceQuestionnaire();
   const itemTypes = useQuestionnaireStore.use.itemTypes();
+  const itemPreferredTerminologyServers =
+    useQuestionnaireStore.use.itemPreferredTerminologyServers();
   const tabs = useQuestionnaireStore.use.tabs();
   const currentTabIndex = useQuestionnaireStore.use.currentTabIndex();
   const variables = useQuestionnaireStore.use.variables();
@@ -42,6 +44,7 @@ function useShowQuestionnaireStoreProperty(selectedProperty: string) {
     {
       sourceQuestionnaire,
       itemTypes,
+      itemPreferredTerminologyServers,
       tabs,
       currentTabIndex,
       variables,

diff --git a/documentation/docs/api/smart-forms-renderer/interfaces/QuestionnaireStoreType.md b/documentation/docs/api/smart-forms-renderer/interfaces/QuestionnaireStoreType.md
@@ -153,6 +153,14 @@ LinkId of the currently focused item
 
 ***
 
+### itemPreferredTerminologyServers
+
+> **itemPreferredTerminologyServers**: `Record`\<`string`, `string`\>
+
+Key-value pair of item types `Record<linkId, preferred terminology servers>`
+
+***
+
 ### itemTypes
 
 > **itemTypes**: `Record`\<`string`, `string`\>

diff --git a/documentation/docs/api/smart-forms-renderer/variables/useQuestionnaireStore.md b/documentation/docs/api/smart-forms-renderer/variables/useQuestionnaireStore.md
@@ -165,6 +165,14 @@ This is the React version of the store which can be used as React hooks in React
 
 `Record`\<`string`, `InitialExpression`\>
 
+### use.itemPreferredTerminologyServers()
+
+> **itemPreferredTerminologyServers**: () => `Record`\<`string`, `string`\>
+
+#### Returns
+
+`Record`\<`string`, `string`\>
+
 ### use.itemTypes()
 
 > **itemTypes**: () => `Record`\<`string`, `string`\>

diff --git a/documentation/docs/sdc/terminology.mdx b/documentation/docs/sdc/terminology.mdx
@@ -14,9 +14,10 @@ The elements/extensions that fall under this category are:
 - [answerValueSet](http://hl7.org/fhir/uv/sdc/behavior.html#answerValueSet)
 - [answerExpression](http://hl7.org/fhir/uv/sdc/expressions.html#answerExpression)
 
-There is also another extension that can be used to define the unit of a quantity item:
+Other related extensions:
 
-- [unitOption](https://hl7.org/fhir/uv/sdc/behavior.html#unitOption)
+- [unitOption](https://hl7.org/fhir/uv/sdc/behavior.html#unitOption) - Provide selection choices for the unit of a quantity item
+- [preferredTerminologyServer](https://build.fhir.org/ig/HL7/sdc/StructureDefinition-sdc-questionnaire-preferredTerminologyServer.html) - Specify the preferred terminology server to use for terminology requests
 
 :::note
 
@@ -169,3 +170,14 @@ This can be used when the unit is not fixed, and allows the user to choose from
   storyId="component-itemtype-quantity--quantity-unit-option-response"
   initialHeight={280}
 />
+
+### PreferredTerminologyServer
+
+PreferredTerminologyServer is used to specify the preferred terminology server to use for terminology requests associated with the whole questionnaire or a particular group or question within the questionnaire (depending on where the extension appears).
+
+#### Basic usage
+
+<IframeContainer
+  storyId="component-sdc-other-extensions--preferred-terminology-server"
+  initialHeight={280}
+/>
diff --git a/documentation/package-lock.json b/documentation/package-lock.json
diff --git a/documentation/package.json b/documentation/package.json
@@ -15,7 +15,7 @@
     "typecheck": "tsc"
   },
   "dependencies": {
-    "@aehrc/smart-forms-renderer": "^0.43.1",
+    "@aehrc/smart-forms-renderer": "^0.44.0",
     "@docusaurus/core": "^3.4.0",
     "@docusaurus/preset-classic": "^3.4.0",
     "@docusaurus/theme-live-codeblock": "^3.4.0",

diff --git a/package-lock.json b/package-lock.json
diff --git a/packages/smart-forms-renderer/package.json b/packages/smart-forms-renderer/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@aehrc/smart-forms-renderer",
-  "version": "0.43.1",
+  "version": "0.44.0",
   "description": "FHIR Structured Data Captured (SDC) rendering engine for Smart Forms",
   "main": "lib/index.js",
   "scripts": {

diff --git a/packages/smart-forms-renderer/src/hooks/useTerminologyServerQuery.ts b/packages/smart-forms-renderer/src/hooks/useTerminologyServerQuery.ts
@@ -29,6 +29,8 @@ function useTerminologyServerQuery(
   searchTerm: string
 ): { options: Coding[]; loading: boolean; feedback?: { message: string; color: AlertColor } } {
   const processedValueSetUrls = useQuestionnaireStore.use.processedValueSetUrls();
+  const itemPreferredTerminologyServers =
+    useQuestionnaireStore.use.itemPreferredTerminologyServers();
   const defaultTerminologyServerUrl = useTerminologyServerStore.use.url();
 
   let fullUrl = '';
@@ -61,7 +63,9 @@ function useTerminologyServerQuery(
   }
 
   // Perform query
-  const terminologyServerUrl = getTerminologyServerUrl(qItem) ?? defaultTerminologyServerUrl;
+  const preferredTerminologyServerUrl = itemPreferredTerminologyServers[qItem.linkId];
+  const terminologyServerUrl =
+    getTerminologyServerUrl(qItem) ?? preferredTerminologyServerUrl ?? defaultTerminologyServerUrl;
   const { isFetching, error, data } = useQuery<ValueSet>(
     ['expandValueSet', fullUrl],
     () => getValueSetPromise(fullUrl, terminologyServerUrl),

diff --git a/packages/smart-forms-renderer/src/hooks/useValueSetCodings.ts b/packages/smart-forms-renderer/src/hooks/useValueSetCodings.ts
@@ -47,6 +47,8 @@ function useValueSetCodings(qItem: QuestionnaireItem): {
   const cachedValueSetCodings = useQuestionnaireStore.use.cachedValueSetCodings();
   const addCodingToCache = useQuestionnaireStore.use.addCodingToCache();
   const { xFhirQueryVariables } = useQuestionnaireStore.use.variables();
+  const itemPreferredTerminologyServers =
+    useQuestionnaireStore.use.itemPreferredTerminologyServers();
 
   const defaultTerminologyServerUrl = useTerminologyServerStore.use.url();
 
@@ -138,7 +140,11 @@ function useValueSetCodings(qItem: QuestionnaireItem): {
     const valueSetUrl = qItem.answerValueSet;
     if (!valueSetUrl || codings.length > 0) return;
 
-    const terminologyServerUrl = getTerminologyServerUrl(qItem) ?? defaultTerminologyServerUrl;
+    const preferredTerminologyServerUrl = itemPreferredTerminologyServers[qItem.linkId];
+    const terminologyServerUrl =
+      getTerminologyServerUrl(qItem) ??
+      preferredTerminologyServerUrl ??
+      defaultTerminologyServerUrl;
     const promise = getValueSetPromise(valueSetUrl, terminologyServerUrl);
     if (promise) {
       promise

diff --git a/packages/smart-forms-renderer/src/interfaces/questionnaireStore.interface.ts b/packages/smart-forms-renderer/src/interfaces/questionnaireStore.interface.ts
@@ -27,6 +27,7 @@ import type { InitialExpression } from './initialExpression.interface';
 
 export interface QuestionnaireModel {
   itemTypes: Record<string, string>;
+  itemPreferredTerminologyServers: Record<string, string>;
   tabs: Tabs;
   pages: Pages;
   variables: Variables;

diff --git a/packages/smart-forms-renderer/src/stores/questionnaireStore.ts b/packages/smart-forms-renderer/src/stores/questionnaireStore.ts
@@ -56,6 +56,7 @@ import type { InitialExpression } from '../interfaces/initialExpression.interfac
  *
  * @property sourceQuestionnaire - FHIR R4 Questionnaire to render
  * @property itemTypes - Key-value pair of item types `Record<linkId, item.type>`
+ * @property itemPreferredTerminologyServers - Key-value pair of item types `Record<linkId, preferred terminology servers>`
  * @property tabs - Key-value pair of tabs `Record<linkId, Tab>`
  * @property currentTabIndex - Index of the current tab
  * @property pages - Key-value pair of pages `Record<linkId, Page>`
@@ -96,6 +97,7 @@ import type { InitialExpression } from '../interfaces/initialExpression.interfac
 export interface QuestionnaireStoreType {
   sourceQuestionnaire: Questionnaire;
   itemTypes: Record<string, string>;
+  itemPreferredTerminologyServers: Record<string, string>;
   tabs: Tabs;
   currentTabIndex: number;
   pages: Pages;
@@ -161,6 +163,7 @@ export interface QuestionnaireStoreType {
 export const questionnaireStore = createStore<QuestionnaireStoreType>()((set, get) => ({
   sourceQuestionnaire: structuredClone(emptyQuestionnaire),
   itemTypes: {},
+  itemPreferredTerminologyServers: {},
   tabs: {},
   currentTabIndex: 0,
   pages: {},
@@ -223,6 +226,7 @@ export const questionnaireStore = createStore<QuestionnaireStoreType>()((set, ge
     set({
       sourceQuestionnaire: questionnaire,
       itemTypes: questionnaireModel.itemTypes,
+      itemPreferredTerminologyServers: questionnaireModel.itemPreferredTerminologyServers,
       tabs: questionnaireModel.tabs,
       currentTabIndex: firstVisibleTab,
       pages: questionnaireModel.pages,
@@ -245,6 +249,7 @@ export const questionnaireStore = createStore<QuestionnaireStoreType>()((set, ge
     set({
       sourceQuestionnaire: structuredClone(emptyQuestionnaire),
       itemTypes: {},
+      itemPreferredTerminologyServers: {},
       tabs: {},
       currentTabIndex: 0,
       pages: {},

diff --git a/packages/smart-forms-renderer/src/stories/assets/questionnaires/QTerminologyControl.ts b/packages/smart-forms-renderer/src/stories/assets/questionnaires/QTerminologyControl.ts
@@ -0,0 +1,59 @@
+/*
+ * 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.
+ */
+
+import type { Questionnaire } from 'fhir/r4';
+
+export const qPreferredTerminologyServer: Questionnaire = {
+  resourceType: 'Questionnaire',
+  id: 'PreferredTerminologyServer',
+  name: 'PreferredTerminologyServer',
+  title: 'Preferred Terminology Server',
+  version: '0.1.0',
+  status: 'draft',
+  publisher: 'AEHRC CSIRO',
+  date: '2024-10-08',
+  url: 'https://smartforms.csiro.au/docs/terminology/preferred-terminology-server',
+  extension: [
+    {
+      url: 'http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-preferredTerminologyServer',
+      valueUrl: 'https://sqlonfhir-r4.azurewebsites.net/fhir'
+    }
+  ],
+  item: [
+    {
+      linkId: 'notes',
+      _text: {
+        extension: [
+          {
+            url: 'http://hl7.org/fhir/StructureDefinition/rendering-xhtml',
+            valueString:
+              '<div xmlns="http://www.w3.org/1999/xhtml">\r\n    <p style="font-size:0.875em"> PreferredTerminologyServer is set as <strong>https://sqlonfhir-r4.azurewebsites.net/fhir</strong> for the entire questionnaire.</p><p style="font-size:0.875em">Developer note: Use <strong>Inspect > Network</strong> to see the request.</p></div>'
+          }
+        ]
+      },
+      text: 'PreferredTerminologyServer is set as https://sqlonfhir-r4.azurewebsites.net/fhir for the entire questionnaire. Use Inspect > Network to see the request.',
+      type: 'display',
+      repeats: false
+    },
+    {
+      linkId: 'languages',
+      text: 'Languages',
+      type: 'choice',
+      answerValueSet: 'http://hl7.org/fhir/ValueSet/languages'
+    }
+  ]
+};
diff --git a/packages/smart-forms-renderer/src/stories/assets/questionnaires/index.ts b/packages/smart-forms-renderer/src/stories/assets/questionnaires/index.ts
@@ -40,3 +40,4 @@ export * from './QBehaviorValueConstraints';
 export * from './QItemControlDisplay';
 export * from './QItemControlGroup';
 export * from './QItemControlQuestion';
+export * from './QTerminologyControl';
diff --git a/packages/smart-forms-renderer/src/stories/sdc/OtherExtensions.stories.tsx b/packages/smart-forms-renderer/src/stories/sdc/OtherExtensions.stories.tsx
@@ -0,0 +1,39 @@
+/*
+ * 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.
+ */
+
+import type { Meta, StoryObj } from '@storybook/react';
+import BuildFormWrapperForStorybook from '../storybookWrappers/BuildFormWrapperForStorybook';
+import { qPreferredTerminologyServer } from '../assets/questionnaires';
+
+// More on how to set up stories at: https://storybook.js.org/docs/react/writing-stories/introduction#default-export
+const meta = {
+  title: 'Component/SDC/Other Extensions',
+  component: BuildFormWrapperForStorybook,
+  // This component will have an automatically generated Autodocs entry: https://storybook.js.org/docs/react/writing-docs/autodocs
+  tags: []
+} satisfies Meta<typeof BuildFormWrapperForStorybook>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// More on writing stories with args: https://storybook.js.org/docs/react/writing-stories/args
+
+export const PreferredTerminologyServer: Story = {
+  args: {
+    questionnaire: qPreferredTerminologyServer
+  }
+};