@aehrc/smart-forms-renderer 0.3.0 → 0.5.0

package/src/utils/populate.ts

@@ -0,0 +1,117 @@
+/*
+ * Copyright 2023 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 {
+  Encounter,
+  Patient,
+  Practitioner,
+  Questionnaire,
+  QuestionnaireResponse
+} from 'fhir/r4';
+import {
+  getLaunchContexts,
+  getQuestionnaireLevelXFhirQueryVariables,
+  getSourceQueries
+} from './populateContexts';
+import type { IssuesParameter, ResponseParameter } from 'sdc-populate';
+import { isInputParameters } from 'sdc-populate';
+import type Client from 'fhirclient/lib/Client';
+import { createPopulateInputParameters } from './populateInputParams';
+import { requestPopulate } from '../api/populate';
+
+export interface PopulateFormParams {
+  populated: QuestionnaireResponse;
+  hasWarnings: boolean;
+}
+/**
+ * Pre-populate questionnaire from CMS patient data to form a populated questionnaireResponse
+ *
+ * @author Sean Fong
+ */
+export async function populateQuestionnaire(
+  questionnaire: Questionnaire,
+  fhirClient: Client,
+  patient: Patient,
+  user: Practitioner,
+  encounter: Encounter | null,
+  populateForm: {
+    (params: PopulateFormParams): void;
+  },
+  exitSpinner: { (): void }
+) {
+  // Get launch contexts, source queries and questionnaire-level variables
+  const launchContexts = getLaunchContexts(questionnaire);
+  const sourceQueries = getSourceQueries(questionnaire);
+  const questionnaireLevelVariables = getQuestionnaireLevelXFhirQueryVariables(questionnaire);
+
+  if (
+    launchContexts.length === 0 &&
+    sourceQueries.length === 0 &&
+    questionnaireLevelVariables.length === 0
+  ) {
+    exitSpinner();
+    return;
+  }
+
+  // Define population input parameters from launch contexts, source queries and questionnaire-level variables
+  const inputParameters = createPopulateInputParameters(
+    questionnaire,
+    patient,
+    user,
+    encounter,
+    launchContexts,
+    sourceQueries,
+    questionnaireLevelVariables
+  );
+
+  if (!inputParameters) {
+    exitSpinner();
+    return;
+  }
+
+  if (!isInputParameters(inputParameters)) {
+    exitSpinner();
+    return;
+  }
+
+  // Perform population if parameters satisfies input parameters
+  const outputParameters = await requestPopulate(fhirClient, inputParameters);
+
+  if (outputParameters.resourceType === 'OperationOutcome') {
+    exitSpinner();
+    return;
+  }
+
+  const responseParameter = outputParameters.parameter.find(
+    (param) => param.name === 'response'
+  ) as ResponseParameter;
+  const issuesParameter = outputParameters.parameter.find((param) => param.name === 'issues') as
+    | IssuesParameter
+    | undefined;
+
+  if (issuesParameter) {
+    for (const issue of issuesParameter.resource.issue) {
+      if (issue.details?.text) {
+        console.warn(issue.details.text);
+      }
+    }
+    populateForm({ populated: responseParameter.resource, hasWarnings: true });
+    return;
+  }
+
+  populateForm({ populated: responseParameter.resource, hasWarnings: false });
+}

package/src/utils/populateCallback.ts

@@ -0,0 +1,53 @@
+/*
+ * Copyright 2023 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 { FetchResourceCallback } from 'sdc-populate';
+import axios from 'axios';
+
+const ABSOLUTE_URL_REGEX = /^(https?|ftp):\/\/[^\s/$.?#].[^\s]*$/;
+
+export interface RequestConfig {
+  clientEndpoint: string;
+  authToken: string;
+}
+
+export const fetchResourceCallback: FetchResourceCallback = (
+  query: string,
+  requestConfig: RequestConfig
+) => {
+  let { clientEndpoint } = requestConfig;
+  const { authToken } = requestConfig;
+
+  const headers = {
+    Accept: 'application/json;charset=utf-8',
+    Authorization: `Bearer ${authToken}`
+  };
+
+  if (!clientEndpoint.endsWith('/')) {
+    clientEndpoint += '/';
+  }
+
+  if (ABSOLUTE_URL_REGEX.test(query)) {
+    return axios.get(query, {
+      headers: headers
+    });
+  } else {
+    return axios.get(clientEndpoint + query, {
+      headers: headers
+    });
+  }
+};

package/src/utils/populateContexts.ts

@@ -0,0 +1,112 @@
+/*
+ * Copyright 2023 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 { Extension, Questionnaire } from 'fhir/r4';
+import type {
+  LaunchContext,
+  QuestionnaireLevelXFhirQueryVariable,
+  SourceQuery
+} from '../interfaces/populate.interface';
+
+export function getLaunchContexts(questionnaire: Questionnaire): LaunchContext[] {
+  if (questionnaire.extension && questionnaire.extension.length > 0) {
+    return questionnaire.extension.filter((extension) =>
+      isLaunchContext(extension)
+    ) as LaunchContext[];
+  }
+
+  return [];
+}
+
+export function isLaunchContext(extension: Extension): extension is LaunchContext {
+  const hasLaunchContextName =
+    extension.url ===
+      'http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-launchContext' &&
+    !!extension.extension?.find(
+      (ext) =>
+        ext.url === 'name' &&
+        (ext.valueId ||
+          (ext.valueCoding &&
+            (ext.valueCoding.code === 'patient' ||
+              ext.valueCoding.code === 'encounter' ||
+              ext.valueCoding.code === 'location' ||
+              ext.valueCoding.code === 'user' ||
+              ext.valueCoding.code === 'study' ||
+              ext.valueCoding.code === 'sourceQueries')))
+    );
+
+  const hasLaunchContextType = !!extension.extension?.find(
+    (ext) =>
+      ext.url === 'type' &&
+      ext.valueCode &&
+      (ext.valueCode === 'Patient' ||
+        ext.valueCode === 'Practitioner' ||
+        ext.valueCode === 'Encounter')
+  );
+
+  return (
+    extension.url ===
+      'http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-launchContext' &&
+    hasLaunchContextName &&
+    hasLaunchContextType
+  );
+}
+
+// get source query references
+export function getSourceQueries(questionnaire: Questionnaire): SourceQuery[] {
+  if (questionnaire.extension && questionnaire.extension.length > 0) {
+    return questionnaire.extension.filter((extension) => isSourceQuery(extension)) as SourceQuery[];
+  }
+
+  return [];
+}
+
+export function isSourceQuery(extension: Extension): extension is SourceQuery {
+  return (
+    extension.url ===
+      'http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-sourceQueries' &&
+    !!extension.valueReference
+  );
+}
+
+/**
+ * Filter x-fhir-query variables from questionnaire's extensions needed for population
+ *
+ * @author Sean Fong
+ */
+export function getQuestionnaireLevelXFhirQueryVariables(
+  questionnaire: Questionnaire
+): QuestionnaireLevelXFhirQueryVariable[] {
+  if (questionnaire.extension && questionnaire.extension.length > 0) {
+    return questionnaire.extension.filter((extension) =>
+      isXFhirQueryVariable(extension)
+    ) as QuestionnaireLevelXFhirQueryVariable[];
+  }
+
+  return [];
+}
+
+export function isXFhirQueryVariable(
+  extension: Extension
+): extension is QuestionnaireLevelXFhirQueryVariable {
+  return (
+    extension.url === 'http://hl7.org/fhir/StructureDefinition/variable' &&
+    !!extension.valueExpression?.name &&
+    extension.valueExpression?.language === 'application/x-fhir-query' &&
+    !!extension.valueExpression?.expression
+  );
+}

package/src/utils/populateInputParams.ts

@@ -0,0 +1,242 @@
+/*
+ * Copyright 2023 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.
+ */
+
+// If none are specified, then the subject is unlimited.
+import type {
+  Encounter,
+  FhirResource,
+  Parameters,
+  ParametersParameter,
+  Patient,
+  Practitioner,
+  Questionnaire,
+  Reference
+} from 'fhir/r4';
+import type {
+  LaunchContext,
+  QuestionnaireLevelXFhirQueryVariable,
+  SourceQuery
+} from '../interfaces/populate.interface';
+
+function createPatientSubject(questionnaire: Questionnaire, patient: Patient): Reference | null {
+  const subjectTypes = questionnaire.subjectType;
+
+  // If subjectTypes array is not empty AND "Patient" is not in the array, we cannot create a Patient subject reference.
+  if (subjectTypes && subjectTypes.length > 0) {
+    const patientSubject = subjectTypes.find((subject) => subject === 'Patient');
+    if (!patientSubject) {
+      return null;
+    }
+  }
+
+  return {
+    type: 'Patient',
+    reference: 'Patient/' + patient.id
+  };
+}
+
+function createCanonicalParam(canonicalUrl: string): ParametersParameter {
+  return {
+    name: 'canonical',
+    valueString: canonicalUrl
+  };
+}
+
+// setting local parameter as false as we are calling $populate with an NPM package, not a server
+// package doesn't contain any fhir resources to "know" the context from
+function createLocalParam(): ParametersParameter {
+  return {
+    name: 'local',
+    valueBoolean: false
+  };
+}
+
+function createLaunchContextParam(
+  launchContext: LaunchContext,
+  patient: Patient,
+  user: Practitioner,
+  encounter: Encounter | null
+): ParametersParameter | null {
+  const name = launchContext.extension[0].valueId ?? launchContext.extension[0].valueCoding?.code;
+  if (!name) {
+    return null;
+  }
+
+  // let resource :string
+  const resourceType = launchContext.extension[1].valueCode;
+  let resource: FhirResource | null;
+  switch (resourceType) {
+    case 'Patient':
+      resource = patient;
+      break;
+    case 'Practitioner':
+      resource = user;
+      break;
+    case 'Encounter':
+      resource = encounter;
+      break;
+    default:
+      return null;
+  }
+
+  if (!resource) {
+    return null;
+  }
+
+  return {
+    name: 'context',
+    part: [
+      {
+        name: 'name',
+        valueString: name
+      },
+      {
+        name: 'content',
+        resource: resource
+      }
+    ]
+  };
+}
+
+function createSourceQueryParams(sourceQuery: SourceQuery, index: number): ParametersParameter {
+  const reference = sourceQuery.valueReference.reference;
+  if (reference && reference.startsWith('#')) {
+    const containedReference = reference.slice(1);
+    return {
+      name: 'context',
+      part: [
+        {
+          name: 'name',
+          valueString: containedReference
+        },
+        {
+          name: 'content',
+          valueReference: sourceQuery.valueReference
+        }
+      ]
+    };
+  }
+
+  // if sourceQuery cannot be referenced to a contained bundle, return itself as a context
+  // this most likely shouldn't happen
+  return {
+    name: 'context',
+    part: [
+      {
+        name: 'name',
+        valueString: `sourceQuery${index}`
+      },
+      {
+        name: 'content',
+        valueReference: sourceQuery.valueReference
+      }
+    ]
+  };
+}
+
+function createVariableParam(variable: QuestionnaireLevelXFhirQueryVariable): ParametersParameter {
+  const query = variable.valueExpression.expression;
+  const resourceType = query.split('?')[0];
+
+  return {
+    name: 'context',
+    part: [
+      {
+        name: 'name',
+        valueString: variable.valueExpression.name
+      },
+      {
+        name: 'content',
+        valueReference: { reference: query, type: resourceType }
+      }
+    ]
+  };
+}
+
+/**
+ * Define population input parameters without any batch response contexts
+ *
+ * @author Sean Fong
+ */
+export function createPopulateInputParameters(
+  questionnaire: Questionnaire,
+  patient: Patient,
+  user: Practitioner,
+  encounter: Encounter | null,
+  launchContexts: LaunchContext[],
+  sourceQueries: SourceQuery[],
+  questionnaireLevelVariables: QuestionnaireLevelXFhirQueryVariable[]
+): Parameters | null {
+  const patientSubject = createPatientSubject(questionnaire, patient);
+  if (!patientSubject) {
+    return null;
+  }
+
+  const inputParameters: Parameters = {
+    resourceType: 'Parameters',
+    parameter: [
+      {
+        name: 'questionnaire',
+        resource: questionnaire
+      },
+      {
+        name: 'subject',
+        valueReference: patientSubject
+      }
+    ]
+  };
+
+  // canonical
+  if (questionnaire.url) {
+    inputParameters.parameter?.push(createCanonicalParam(questionnaire.url));
+  }
+
+  // contexts
+  const contexts: ParametersParameter[] = [];
+  // add launch contexts
+  if (launchContexts.length > 0) {
+    for (const launchContext of launchContexts) {
+      const launchContextParam = createLaunchContextParam(launchContext, patient, user, encounter);
+      if (launchContextParam) {
+        contexts.push(launchContextParam);
+      }
+    }
+  }
+
+  // add source queries
+  if (sourceQueries.length > 0) {
+    for (const [index, sourceQuery] of sourceQueries.entries()) {
+      contexts.push(createSourceQueryParams(sourceQuery, index));
+    }
+  }
+
+  // add questionnaire-level variables
+  if (questionnaireLevelVariables.length > 0) {
+    for (const variable of questionnaireLevelVariables) {
+      contexts.push(createVariableParam(variable));
+    }
+  }
+
+  if (contexts.length > 0) {
+    inputParameters.parameter?.push(...contexts);
+  }
+
+  // local
+  inputParameters.parameter?.push(createLocalParam());
+
+  return inputParameters;
+}

package/src/utils/qItem.ts

@@ -0,0 +1,103 @@
+/*
+ * Copyright 2023 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 { Extension, Questionnaire, QuestionnaireItem } from 'fhir/r4';
+import { hasHiddenExtension } from './itemControl';
+import { getChoiceControlType } from './choice';
+import { QItemChoiceControl, QItemOpenChoiceControl } from '../interfaces/choice.enum';
+import { getOpenChoiceControlType } from './openChoice';
+import type { EnableWhenExpression, EnableWhenItems } from '../interfaces/enableWhen.interface';
+
+interface isHiddenParams {
+  questionnaireItem: QuestionnaireItem;
+  enableWhenIsActivated: boolean;
+  enableWhenItems: EnableWhenItems;
+  enableWhenExpressions: Record<string, EnableWhenExpression>;
+}
+
+/**
+ * Test the given QItem on a series of checks to verify if the item should be displayed
+ * Check if qItem has hidden attribute
+ * Check if qItem fufilled its enableWhen criteria
+ *
+ * @author Sean Fong
+ */
+export function isHidden(params: isHiddenParams): boolean {
+  const { questionnaireItem, enableWhenIsActivated, enableWhenItems, enableWhenExpressions } =
+    params;
+  if (hasHiddenExtension(questionnaireItem)) {
+    return true;
+  }
+
+  return isHiddenByEnableWhens({
+    linkId: questionnaireItem.linkId,
+    enableWhenIsActivated,
+    enableWhenItems,
+    enableWhenExpressions
+  });
+}
+
+interface isHiddenByEnableWhensParams {
+  linkId: string;
+  enableWhenIsActivated: boolean;
+  enableWhenItems: EnableWhenItems;
+  enableWhenExpressions: Record<string, EnableWhenExpression>;
+}
+
+export function isHiddenByEnableWhens(params: isHiddenByEnableWhensParams): boolean {
+  const { linkId, enableWhenIsActivated, enableWhenItems, enableWhenExpressions } = params;
+
+  if (enableWhenIsActivated) {
+    if (enableWhenItems[linkId]) {
+      return !enableWhenItems[linkId].isEnabled;
+    }
+
+    if (enableWhenExpressions[linkId]) {
+      return !enableWhenExpressions[linkId].isEnabled;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Check if qItem is a repeat item AND if it isn't a checkbox item
+ * Note: repeat checkbox items are rendered as multi-select checkbox instead of being rendered as a traditional repeat item
+ *
+ * @author Sean Fong
+ */
+export function isRepeatItemAndNotCheckbox(qItem: QuestionnaireItem): boolean {
+  const isCheckbox =
+    getChoiceControlType(qItem) === QItemChoiceControl.Checkbox ||
+    getOpenChoiceControlType(qItem) === QItemOpenChoiceControl.Checkbox;
+
+  return !!qItem['repeats'] && !isCheckbox;
+}
+
+export function getXHtmlStringFromQuestionnaire(questionnaire: Questionnaire): string | null {
+  const itemControl = questionnaire._title?.extension?.find(
+    (extension: Extension) =>
+      extension.url === 'http://hl7.org/fhir/StructureDefinition/rendering-xhtml'
+  );
+
+  if (itemControl) {
+    if (itemControl.valueString) {
+      return itemControl.valueString;
+    }
+  }
+  return null;
+}