Operation-questionnaire-populatelink.xml

Operation Definition

<OperationDefinition xmlns="http://hl7.org/fhir">
  <id value="Questionnaire-populatelink"/>
  <text>
    <status value="generated"/>
    <div xmlns="http://www.w3.org/1999/xhtml">
      <h2>Generate a link to a Questionnaire completion webpage</h2>
      <p>OPERATION: Generate a link to a Questionnaire completion webpage</p>
      <div>
        <p>Generates a link to a web page to be used to answer a specified 
          <a href="questionnaire.html">Questionnaire</a>.  The form at the specified location will be pre-filled with answers to questions where
           possible based on information provided as part of the operation or already known by the
           server about the subject of the 
          <a href="questionnaire.html">Questionnaire</a>.
        </p>

        <p>If the operation is not called at the instance level, one and only one of the identifier,
           questionnaire or questionnaireRef 'in' parameters must be provided. If called at the instance
           level, these parameters will be ignored.</p>

        <p>The response will contain a url for the web page to direct the user to.  The page will
           allow the user to complete/verify the questionnaire answers and to submit the form.</p>

        <p>The specified page will be populated with an unanswered set of questions following the
           group and question structure of the specified 
          <a href="questionnaire.html">Questionnaire</a>.  If  
          <em>content</em> parameters were specified or the 
          <em>local</em> parameter was set to true, some of the questions may have answers filled in as well.
            In the case of repeating questions or groups, typically only one repetition will be provided
           unless answer values exist that would support populating multiple repetitions.
        </p>

        <p>Population of the page with appropriate data is dependent on the questions and/or groups
           in the 
          <a href="questionnaire.html">Questionnaire</a> having metadata that allows the server to recognize the questions.  This might be through
           
          <em>Questionnaire.group.question.code</em>, through extensions such as the 
          <a href="extension-questionnaire-dereference.html">http://hl7.org/fhir/StructureDefinition/questionnaire-deReference</a> extension or through use of the 
          <a href="conceptmap.html">ConceptMap</a> resource.
        </p>

        <p>Regardless of the mechanism used to link the questions in a questionnaire to a &quot;known&quot;
           mappable concept, solutions using this operation should ensure that the details of the
           question and associated linkage element are sufficiently similar as to safely allow auto-population;
           i.e. the question text and context must be sufficiently the same, the value set for the
           question must fall within the value set for the mapped element, the data types must be
           the same or convertible, etc.</p>

      </div>
      <p>URL: [base]/Questionnaire/$populatelink</p>
      <p>URL: [base]/Questionnaire/[id]/$populatelink</p>
      <p>Parameters</p>
      <table class="grid">
        <tr>
          <td>
            <b>Use</b>
          </td>
          <td>
            <b>Name</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>identifier</td>
          <td>0..1</td>
          <td>uri</td>
          <td/>
          <td>
            <div>
              <p>A logical questionnaire identifier (i.e. ''Questionnaire.identifier''). The server must
                 know the questionnaire or be able to retrieve it from other known repositories.</p>

            </div>
          </td>
        </tr>
        <tr>
          <td>IN</td>
          <td>questionnaire</td>
          <td>0..1</td>
          <td>Questionnaire</td>
          <td/>
          <td>
            <div>
              <p>The 
                <a href="questionnaire.html">Questionnaire</a> is provided directly as part of the request. Servers may choose not to accept questionnaires
                 in this fashion
              </p>

            </div>
          </td>
        </tr>
        <tr>
          <td>IN</td>
          <td>questionnaireRef</td>
          <td>0..1</td>
          <td>Reference</td>
          <td/>
          <td>
            <div>
              <p>The 
                <a href="questionnaire.html">Questionnaire</a> is provided as a resource reference. Servers may choose not to accept questionnaires
                 in this fashion or may fail if they cannot resolve or access the referenced questionnaire.
              </p>

            </div>
          </td>
        </tr>
        <tr>
          <td>IN</td>
          <td>content</td>
          <td>0..*</td>
          <td>Reference</td>
          <td/>
          <td>
            <div>
              <p>Resources containing information to be used to help populate the generated HTML form.
                  These may be FHIR resources or may be binaries containing FHIR documents, CDA documents
                 or other source materials.  Servers may not support all possible source materials and
                 may ignore materials they do not recognize.  (They MAY provide warnings if ignoring submitted
                 resources.)</p>

            </div>
          </td>
        </tr>
        <tr>
          <td>IN</td>
          <td>local</td>
          <td>0..1</td>
          <td>boolean</td>
          <td/>
          <td>
            <div>
              <p>If specified and set to 'true' (and the server is capable), the server should use what
                 resources and other knowledge it has about the referenced subject when pre-populating
                 answers to questions.</p>

            </div>
          </td>
        </tr>
        <tr>
          <td>OUT</td>
          <td>link</td>
          <td>1..1</td>
          <td>uri</td>
          <td/>
          <td>
            <div>
              <p>The URL for the web form  that supports capturing the information defined by questionnaire,
                 possibly partially (or fully)-populated with a set of answers for the specified Questionnaire</p>

            </div>
          </td>
        </tr>
        <tr>
          <td>OUT</td>
          <td>issues</td>
          <td>0..1</td>
          <td>OperationOutcome</td>
          <td/>
          <td>
            <div>
              <p>A list of hints and warnings about problems encountered while populating the questionnaire.
                 These might be show to the user as an advisory note. Note: if the questionnaire cannot
                 be populated at all, then the operation should fail, and an OperationOutcome is returned
                 directly with the failure, rather than using this parameter</p>

            </div>
          </td>
        </tr>
      </table>
      <div>
        <p>While it is theoretically possible for the questionnaire response to be completely auto-populated
           and submitted without human review, the intention of this transaction is merely to reduce
           redundant data entry.  The web page 
          <strong>SHOULD</strong> ensure that a human submitter has an opportunity to review the auto-populated answers
           to confirm correctness as well as to complete or expand on information provided by the
           auto-population process.
        </p>

        <p>Complex form designs with conditional logic or tight constraints on cardinalities may
           be challenging to auto-populate.  A server MAY choose to traverse the questionnaire as
           if it were a human respondent, answering only those questions that are enabled based on
           previously answered questions.  However, doing so may result in minimal population.  Alternatively,
           systems may choose to populate all known answers, independent of dependencies and other
           constraints.  This may cause questions to be answered that should not be answered.  The
           web form is responsible for pruning the final populated questionnaire once human review
           has taken place.</p>

        <p>Invoking this operation with the ''content'' parameter may involve the disclosure of personally
           identifiable healthcare information to the system which is performing the population process.
            No such disclosures should be made unless the system on which the operation is being
           invoked is a &quot;trusted&quot; system and appropriate agreements are in place to protect
           the confidentiality of any information shared with that system.</p>

      </div>
    </div>
  </text>
  <url value="http://hl7.org/fhir/OperationDefinition/Questionnaire-populatelink"/>
  <name value="Generate a link to a Questionnaire completion webpage"/>
  <status value="draft"/>
  <kind value="operation"/>
  <date value="2016-12-06T12:22:34+11:00"/>
  <publisher value="HL7 (FHIR Project)"/>
  <contact>
    <telecom>
      <system value="url"/>
      <value value="http://hl7.org/fhir"/>
    </telecom>
    <telecom>
      <system value="email"/>
      <value value="fhir@lists.hl7.org"/>
    </telecom>
  </contact>
  <description value="Generates a link to a web page to be used to answer a specified [Questionnaire](questionnaire.html).
    The form at the specified location will be pre-filled with answers to questions where
   possible based on information provided as part of the operation or already known by the
   server about the subject of the [Questionnaire](questionnaire.html).  If the operation
   is not called at the instance level, one and only one of the identifier, questionnaire
   or questionnaireRef 'in' parameters must be provided. If called at the instance level,
   these parameters will be ignored.  The response will contain a url for the web page to
   direct the user to.  The page will allow the user to complete/verify the questionnaire
   answers and to submit the form.  The specified page will be populated with an unanswered
   set of questions following the group and question structure of the specified [Questionnaire](questio
  nnaire.html).  If  *content* parameters were specified or the *local* parameter was set
   to true, some of the questions may have answers filled in as well.  In the case of repeating
   questions or groups, typically only one repetition will be provided unless answer values
   exist that would support populating multiple repetitions.  Population of the page with
   appropriate data is dependent on the questions and/or groups in the [Questionnaire](questionnaire.ht
  ml) having metadata that allows the server to recognize the questions.  This might be through
   *Questionnaire.group.question.code*, through extensions such as the [http://hl7.org/fhir/StructureDe
  finition/questionnaire-deReference](extension-questionnaire-dereference.html) extension
   or through use of the [ConceptMap](conceptmap.html) resource.  Regardless of the mechanism
   used to link the questions in a questionnaire to a &quot;known&quot; mappable concept,
   solutions using this operation should ensure that the details of the question and associated
   linkage element are sufficiently similar as to safely allow auto-population; i.e. the
   question text and context must be sufficiently the same, the value set for the question
   must fall within the value set for the mapped element, the data types must be the same
   or convertible, etc."/>
  <code value="populatelink"/>
  <comment value="While it is theoretically possible for the questionnaire response to be completely auto-populated
   and submitted without human review, the intention of this transaction is merely to reduce
   redundant data entry.  The web page **SHOULD** ensure that a human submitter has an opportunity
   to review the auto-populated answers to confirm correctness as well as to complete or
   expand on information provided by the auto-population process.  Complex form designs with
   conditional logic or tight constraints on cardinalities may be challenging to auto-populate.
    A server MAY choose to traverse the questionnaire as if it were a human respondent, answering
   only those questions that are enabled based on previously answered questions.  However,
   doing so may result in minimal population.  Alternatively, systems may choose to populate
   all known answers, independent of dependencies and other constraints.  This may cause
   questions to be answered that should not be answered.  The web form is responsible for
   pruning the final populated questionnaire once human review has taken place.  Invoking
   this operation with the ''content'' parameter may involve the disclosure of personally
   identifiable healthcare information to the system which is performing the population process.
    No such disclosures should be made unless the system on which the operation is being
   invoked is a &quot;trusted&quot; system and appropriate agreements are in place to protect
   the confidentiality of any information shared with that system."/>
  <resource value="Questionnaire"/>
  <system value="false"/>
  <type value="true"/>
  <instance value="true"/>
  <parameter>
    <name value="identifier"/>
    <use value="in"/>
    <min value="0"/>
    <max value="1"/>
    <documentation value="A logical questionnaire identifier (i.e. ''Questionnaire.identifier''). The server must
     know the questionnaire or be able to retrieve it from other known repositories."/>
    <type value="uri"/>
  </parameter>
  <parameter>
    <name value="questionnaire"/>
    <use value="in"/>
    <min value="0"/>
    <max value="1"/>
    <documentation value="The [Questionnaire](questionnaire.html) is provided directly as part of the request. Servers
     may choose not to accept questionnaires in this fashion"/>
    <type value="Questionnaire"/>
  </parameter>
  <parameter>
    <name value="questionnaireRef"/>
    <use value="in"/>
    <min value="0"/>
    <max value="1"/>
    <documentation value="The [Questionnaire](questionnaire.html) is provided as a resource reference. Servers may
     choose not to accept questionnaires in this fashion or may fail if they cannot resolve
     or access the referenced questionnaire."/>
    <type value="Reference"/>
    <profile>
      <reference value="http://hl7.org/fhir/StructureDefinition/Questionnaire"/>
    </profile>
  </parameter>
  <parameter>
    <name value="content"/>
    <use value="in"/>
    <min value="0"/>
    <max value="*"/>
    <documentation value="Resources containing information to be used to help populate the generated HTML form.
      These may be FHIR resources or may be binaries containing FHIR documents, CDA documents
     or other source materials.  Servers may not support all possible source materials and
     may ignore materials they do not recognize.  (They MAY provide warnings if ignoring submitted
     resources.)"/>
    <type value="Reference"/>
  </parameter>
  <parameter>
    <name value="local"/>
    <use value="in"/>
    <min value="0"/>
    <max value="1"/>
    <documentation value="If specified and set to 'true' (and the server is capable), the server should use what
     resources and other knowledge it has about the referenced subject when pre-populating
     answers to questions."/>
    <type value="boolean"/>
  </parameter>
  <parameter>
    <name value="link"/>
    <use value="out"/>
    <min value="1"/>
    <max value="1"/>
    <documentation value="The URL for the web form  that supports capturing the information defined by questionnaire,
     possibly partially (or fully)-populated with a set of answers for the specified Questionnaire"/>
    <type value="uri"/>
  </parameter>
  <parameter>
    <name value="issues"/>
    <use value="out"/>
    <min value="0"/>
    <max value="1"/>
    <documentation value="A list of hints and warnings about problems encountered while populating the questionnaire.
     These might be show to the user as an advisory note. Note: if the questionnaire cannot
     be populated at all, then the operation should fail, and an OperationOutcome is returned
     directly with the failure, rather than using this parameter"/>
    <type value="OperationOutcome"/>
  </parameter>
</OperationDefinition>