Da Vinci - Documentation Templates and Rules
2.1.0 - STU 2.1 United States of America flag

Da Vinci - Documentation Templates and Rules, published by HL7 International / Clinical Decision Support. This guide is not an authorized publication; it is the continuous build for version 2.1.0 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/HL7/davinci-dtr/ and changes regularly. See the Directory of published versions

: DTR Questionnaire Package - XML Representation

Page standards status: Trial-use Maturity Level: 2

Raw xml | Download


<OperationDefinition xmlns="http://hl7.org/fhir">
  <id value="questionnaire-package"/>
  <text>
    <status value="generated"/>
    <div xmlns="http://www.w3.org/1999/xhtml"><p class="res-header-id"><b>Generated Narrative: OperationDefinition questionnaire-package</b></p><a name="questionnaire-package"> </a><a name="hcquestionnaire-package"> </a><a name="questionnaire-package-en-US"> </a><p>URL: [base]/Questionnaire/$questionnaire-package</p><p>Input parameters Profile:<a href="StructureDefinition-dtr-qpackage-input-parameters.html">DTR Questionnaire Package Input Parameters</a></p><p>Output parameters Profile:<a href="StructureDefinition-dtr-qpackage-output-parameters.html">DTR Questionnaire Package Output Parameters</a></p><h3>Parameters</h3><table class="grid"><tr><td><b>Use</b></td><td><b>Name</b></td><td><b>Scope</b></td><td><b>Cardinality</b></td><td><b>Type</b></td><td><b>Binding</b></td><td><b>Documentation</b></td></tr><tr><td>IN</td><td>coverage</td><td/><td>0..*</td><td><a href="http://hl7.org/fhir/R4/coverage.html">Coverage</a></td><td/><td><div><p>Coverage resource instances to establish the member and the coverage for which documentation is to be collected.</p>
</div></td></tr><tr><td>IN</td><td>order</td><td/><td>0..*</td><td><a href="http://hl7.org/fhir/R4/resource.html">Resource</a></td><td/><td><div><p>Order resource instances. e.g., DeviceRequest, ServiceRequest, MedicationRequest,... Encounter, Appointment, etc. to establish context for the information to be collected.</p>
</div></td></tr><tr><td>IN</td><td>referenced</td><td/><td>0..*</td><td><a href="http://hl7.org/fhir/R4/resource.html">Resource</a></td><td/><td><div><p>Order-related referenced resources which are necessary to support stand-alone launch – specifically the Patient, requester, performer and location-related resources. (SHALL NOT include resources from <code>supportingInformation</code>).</p>
</div></td></tr><tr><td>IN</td><td>questionnaire</td><td/><td>0..*</td><td><a href="http://hl7.org/fhir/R4/datatypes.html#canonical">canonical</a></td><td/><td><div><p>Canonical url for Questionnaire(s) (possibly version-specific) to return.</p>
</div></td></tr><tr><td>IN</td><td>context</td><td/><td>0..1</td><td><a href="http://hl7.org/fhir/R4/datatypes.html#string">string</a></td><td/><td><div><p>Context ID from CRD or CDex.  May be used to determine what Questionnaires to return and/or to support pre-population.</p>
</div></td></tr><tr><td>IN</td><td>changedsince</td><td/><td>0..1</td><td><a href="http://hl7.org/fhir/R4/datatypes.html#dateTime">dateTime</a></td><td/><td><div><p>If present, only Questionnaire bundles whose Questionnaire or associated artifacts have changed since the specified timestamp.  If there are no changed artifacts the operation will simply return a 200 Ok indicating that nothing has changed since the specified timestamp.</p>
</div></td></tr><tr><td>OUT</td><td>PackageBundle</td><td/><td>0..*</td><td><a href="http://hl7.org/fhir/R4/bundle.html">Bundle</a></td><td/><td><div><p>A Bundle with a single Questionnaire, and 0..* Libraries containing needed CQL and/or ValueSets containing needed codes.</p>
</div></td></tr><tr><td>OUT</td><td>outcome</td><td/><td>0..1</td><td><a href="http://hl7.org/fhir/R4/operationoutcome.html">OperationOutcome</a></td><td/><td><div><p>Warning or information messages related to the successful execution of the operation</p>
</div></td></tr></table></div>
  </text>
  <extension
             url="http://hl7.org/fhir/StructureDefinition/structuredefinition-wg">
    <valueCode value="cds"/>
  </extension>
  <extension
             url="http://hl7.org/fhir/StructureDefinition/structuredefinition-fmm">
    <valueInteger value="2">
      <extension
                 url="http://hl7.org/fhir/StructureDefinition/structuredefinition-conformance-derivedFrom">
        <valueCanonical
                        value="http://hl7.org/fhir/us/davinci-dtr/ImplementationGuide/hl7.fhir.us.davinci-dtr"/>
      </extension>
    </valueInteger>
  </extension>
  <extension
             url="http://hl7.org/fhir/StructureDefinition/structuredefinition-standards-status">
    <valueCode value="trial-use">
      <extension
                 url="http://hl7.org/fhir/StructureDefinition/structuredefinition-conformance-derivedFrom">
        <valueCanonical
                        value="http://hl7.org/fhir/us/davinci-dtr/ImplementationGuide/hl7.fhir.us.davinci-dtr"/>
      </extension>
    </valueCode>
  </extension>
  <url
       value="http://hl7.org/fhir/us/davinci-dtr/OperationDefinition/questionnaire-package"/>
  <version value="2.1.0"/>
  <name value="QuestionnairePackage"/>
  <title value="Get Questionnaire Packge for given order(s)"/>
  <status value="active"/>
  <kind value="operation"/>
  <date value="2024-11-21T21:34:16+00:00"/>
  <publisher value="HL7 International / Clinical Decision Support"/>
  <contact>
    <name value="HL7 International / Clinical Decision Support"/>
    <telecom>
      <system value="url"/>
      <value value="http://www.hl7.org/Special/committees/dss"/>
    </telecom>
  </contact>
  <description
               value="This operation returns one or more 'collection' Bundles each consisting of a single Questionnaire resource, one or more QuestionnaireResponse resources, as well as any dependency Library and ValueSet instances needed to allow a renderer to fully render and otherwise process the Questionnaire.

The operation **SHALL** take as input the Coverage resource(s) identifying the member and the type(s) of Coverage for which additional information is needed and at least one of:  
* Zero or more canonicals specifying the URL and, (optionally) the version of the Questionnaire(s) to retrieve;
* A CRD/PAS context ID, and/or
* One or more Request or Encounter resources

If specific Questionnaires are specified, the operation will return the specified versions of the respective Questionnaires (or current version if no version is indicated).  For the other parameters (context id or resources) the payer will determine, all Questionnaires relevant to determining coverage, prior authorization, claims acceptability, documentation requirements, etc. that are relevant to the specified context.  The list of questionnaires returned will be the union of those determined by evaluating each of the provided parameters, with each Questionnaire version only being returned once.  If multiple versions of a questionnaire are returned, each **SHALL** be associated with distinct orders or coverages in the associated QuestionnaireResponses (see below).

In most cases, only one order and one coverage will be provided.  However, the operation allows for circumstances where the decision support engine can handle multiple active coverages - either for the same payer or multiple payers handled by the same engine.  It also handles multiple orders with overlapping requirements where a payer might be able to minimize the answers to be gathered by processing the answers as a group.

If any of the explicitly requested questionnaires cannot be found, a warning **SHALL** be provided in the [`Outcome`](StructureDefinition-dtr-qpackage-output-parameters.html) element of the outer `Parameters` resource.  Similarly, if there is an issue understanding any of the orders or coverages and determining appropriate Questionnaires, a warning will be provided.

Each Questionnaire will be packaged into a distinct Bundle.  If there is only one Questionnaire and there are no warnings, then the QuestionnaireBundle can be returned as the sole payload of the operation response.  If there are multiple Questionnaires and/or there is a need to convey an OperationOutcome alongside Questionnaires, the response will be a `Parameters` resource.  If the operation fails, the response payload **SHOULD** be an OperationOutcome.

The Bundle **SHALL** include the Questionnaire as the first entry along with all external Libraries referenced by the Questionnaire using the [cqf-library](https://build.fhir.org/ig/HL7/fhir-extensions/StructureDefinition-cqf-library.html) extension, as well as a recursive retrieval of all `relatedArtifact` references of type 'depends-on'.  All Libraries **SHALL** include both CQL and EML representations.  The Bundle **SHALL** include all external ValueSet instances referenced by the Questionnaire.  All value sets with expansions under 40 entries **SHALL** be expanded as of the current date and using expansion parameters (such as SNOMED release) as deemed appropriate by the payer.

All references to Questionnaires, Libraries, and ValueSets within the Bundle **SHALL** be version specific, as breaking changes may occur between versions and would likely cause failures or inconsistent data. Note that the same Libraries and/or ValueSets may appear in more than one Questionnaire Bundle, possibly with a different version.

If any of the dependencies cannot be retrieved or value sets expanded, a warning will be included in the [`Outcome`](StructureDefinition-dtr-qpackage-output-parameters.html). Each Library and ValueSet will only appear once in the Bundle, even if it is referenced multiple places.  The only exception is if more than one version of a Library or ValueSet are referenced.  Multiple versions of a ValueSet will be returned.  Multiple versions of a Library **MAY** be treated as an error, or **MAY** be handled by returning the 'most recent' version of the referenced versions.

As well, the Questionnaire Bundle **SHALL** contain one or more initial draft QuestionnaireResponses that reference the Questionnaire for that Bundle and populate the subject as well as repetitions of the Context extension that identify the Coverage(s) and Request or Encounter resources the Questionnaire is to be completed for. The same QuestionnaireResponse might be associated with multiple Request resources or may need to be filled out separately for different Requests.

The payer **MAY** opt to pre-populate some answers in the provided QuestionnaireResponses based on information the payer has in its own records or has from context from CRD or from other prior auth or claims submissions.

Payers must be cautious about prepopulating Questionnaires with sensitive information, because there are rare situations where a malicious application could attempt to access information that was not authorized by the EHR.

When resuming a work in progress questionnaire response the DTR client **SHALL** invoke the operation with the timestamp to see if the questionnaire package has changed since it was last retrieved, presuming that the `QuestionnaireResponse.meta.lastUpdated` element corresponds to the last package retrieval time.

### Notes
* For adaptive questionnaires, there will be no question items to reference any ValueSets and no expressions to reference any Libraries.  However, the payer may still opt to include Libraries or ValueSets in the initial Bundle to avoid the overhead of needing to send contained content with each [`$next-question`](http://hl7.org/fhir/uv/sdc/STU3/OperationDefinition-Questionnaire-next-question.html) invocation.  Alternatively, any needed Libraries and ValueSets may manifest as ‘contained’ resources within the QuestionnaireResponse returned by [`$next-question`](http://hl7.org/fhir/uv/sdc/STU3/OperationDefinition-Questionnaire-next-question.html) based on which questions have been selected. (see [Adaptive Form Considerations](https://build.fhir.org/ig/HL7/davinci-dtr/specification.html#adaptive-form-considerations))

* The `outcome` parameter is only present if the operation completes successfully with a 200 HTTP response code.  In the event of an error, no Parameters response will be returned at all, though a bare `OperationOutcome` might be returned."/>
  <jurisdiction>
    <coding>
      <system value="urn:iso:std:iso:3166"/>
      <code value="US"/>
    </coding>
  </jurisdiction>
  <code value="questionnaire-package"/>
  <base
        value="http://hl7.org/fhir/us/davinci-dtr/OperationDefinition/questionnaire-package"/>
  <resource value="Questionnaire"/>
  <system value="false"/>
  <type value="true"/>
  <instance value="false"/>
  <inputProfile
                value="http://hl7.org/fhir/us/davinci-dtr/StructureDefinition/dtr-qpackage-input-parameters"/>
  <outputProfile
                 value="http://hl7.org/fhir/us/davinci-dtr/StructureDefinition/dtr-qpackage-output-parameters"/>
  <parameter>
    <name value="coverage"/>
    <use value="in"/>
    <min value="0"/>
    <max value="*"/>
    <documentation
                   value="Coverage resource instances to establish the member and the coverage for which documentation is to be collected."/>
    <type value="Coverage"/>
  </parameter>
  <parameter>
    <name value="order"/>
    <use value="in"/>
    <min value="0"/>
    <max value="*"/>
    <documentation
                   value="Order resource instances. e.g., DeviceRequest, ServiceRequest, MedicationRequest,... Encounter, Appointment, etc. to establish context for the information to be collected."/>
    <type value="Resource"/>
  </parameter>
  <parameter>
    <name value="referenced"/>
    <use value="in"/>
    <min value="0"/>
    <max value="*"/>
    <documentation
                   value="Order-related referenced resources which are necessary to support stand-alone launch – specifically the Patient, requester, performer and location-related resources. (SHALL NOT include resources from `supportingInformation`)."/>
    <type value="Resource"/>
  </parameter>
  <parameter>
    <name value="questionnaire"/>
    <use value="in"/>
    <min value="0"/>
    <max value="*"/>
    <documentation
                   value="Canonical url for Questionnaire(s) (possibly version-specific) to return."/>
    <type value="canonical"/>
  </parameter>
  <parameter>
    <name value="context"/>
    <use value="in"/>
    <min value="0"/>
    <max value="1"/>
    <documentation
                   value="Context ID from CRD or CDex.  May be used to determine what Questionnaires to return and/or to support pre-population."/>
    <type value="string"/>
  </parameter>
  <parameter>
    <name value="changedsince"/>
    <use value="in"/>
    <min value="0"/>
    <max value="1"/>
    <documentation
                   value="If present, only Questionnaire bundles whose Questionnaire or associated artifacts have changed since the specified timestamp.  If there are no changed artifacts the operation will simply return a 200 Ok indicating that nothing has changed since the specified timestamp."/>
    <type value="dateTime"/>
  </parameter>
  <parameter>
    <name value="PackageBundle"/>
    <use value="out"/>
    <min value="0"/>
    <max value="*"/>
    <documentation
                   value="A Bundle with a single Questionnaire, and 0..* Libraries containing needed CQL and/or ValueSets containing needed codes."/>
    <type value="Bundle"/>
  </parameter>
  <parameter>
    <name value="outcome"/>
    <use value="out"/>
    <min value="0"/>
    <max value="1"/>
    <documentation
                   value="Warning or information messages related to the successful execution of the operation"/>
    <type value="OperationOutcome"/>
  </parameter>
</OperationDefinition>