Operation-encounter-everything.xml

Operation Definition

<OperationDefinition xmlns="http://hl7.org/fhir">
  <id value="Encounter-everything"/> 
  <text> 
    <status value="generated"/> 
    <div xmlns="http://www.w3.org/1999/xhtml">
      <h2> Fetch Encounter Record</h2> 
      <p> OPERATION: Fetch Encounter Record</p> 
      <p> The official URL for this operation definition is: </p> 
      <pre> http://hl7.org/fhir/OperationDefinition/Encounter-everything</pre> 
      <div> 
        <p> This operation is used to return all the information related to an encounter described
           in the resource on which this operation is invoked. The response is a bundle of type &quot;searchset
          &quot;. At a minimum, the encounter resource itself is returned, along with any other resources
           that the server has available for the given encounter for the user. The server also returns
           whatever resources are needed to support the records - e.g. linked practitioners, locations,
           organizations etc. The principle intended use for this operation is to provide a patient
           with access to their record, or to allow a client to retrieve everything for an encounter
           for efficient display).</p> 

        <p> The server SHOULD return all resources it has that:</p> 

        <ul> 

          <li> are included in the encounter compartment for the identified encounter (have a reference
             to the encounter)</li> 

          <li> are referenced by the standard extenstion for associating an encounter (where no reference
             element exists) http://hl7.org/fhir/StructureDefinition/encounter-associatedEncounter</li> 

          <li> the server believes are relevant to the context of the encounter for any other reason
             (internally defined/decided)</li> 

          <li> any resource referenced by the above, including binaries and attachments (to make a more
             complete package)</li> 

        </ul> 

        <p> In the US Realm, at a mimimum, the resources returned SHALL include all the data covered
           by the meaningful use common data elements (see 
          <a href="http://hl7.org/fhir/us/daf">DAF</a>  for further guidance). Other applicable implementation guides may make additional rules
           about the information that is returned.   Note that for many resources, the exact nature
           of the link to encounter can be ambiguous (e.g. for a DiagnosticReport, is it the encounter
           when it was initiated, or when it was reported?)
        </p> 

      </div> 
      <p> URL: [base]/Encounter/[id]/$everything</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> _since</td> 
          <td> 0..1</td> 
          <td> instant</td> 
          <td/>  
          <td> 
            <div> 
              <p> Resources updated after this period will be included in the response. The intent of this
                 parameter is to allow a client to request only records that have changed since the last
                 request, based on either the return header time, or or (for asynchronous use), the transaction
                 time</p> 

            </div> 
          </td> 
        </tr> 
        <tr> 
          <td> IN</td> 
          <td> _type</td> 
          <td> 0..*</td> 
          <td> code</td> 
          <td/>  
          <td> 
            <div> 
              <p> One or more parameters, each containing one or more comma-delimited FHIR resource types
                 to include in the return resources. In the absense of any specified types, the server
                 returns all resource types</p> 

            </div> 
          </td> 
        </tr> 
        <tr> 
          <td> IN</td> 
          <td> _count</td> 
          <td> 0..1</td> 
          <td> integer</td> 
          <td/>  
          <td> 
            <div> 
              <p> See discussion below on the utility of paging through the results of the $everything operation</p> 

            </div> 
          </td> 
        </tr> 
        <tr> 
          <td> OUT</td> 
          <td> return</td> 
          <td> 1..1</td> 
          <td> Bundle</td> 
          <td/>  
          <td> 
            <div> 
              <p> The bundle type is &quot;searchset&quot;</p> 

            </div> 
          </td> 
        </tr> 
      </table> 
      <div> 
        <p> The key differences between this operation and simply searching the encounter compartment
           are:</p> 

        <ul> 

          <li> unless the client requests otherwise, the server returns the entire result set in a single
             bundle (rather than using paging)</li> 

          <li> the server is responsible for determining what resources to return as included resources
             (rather than the client specifying which ones)</li> 

        </ul> 

        <p> This frees the client from needing to determine what it could or should ask for, particularly
           with regard to included resources.</p> 

        <p> It is assumed that the server has identified and secured the context appropriately, and
           can either associate the authorization context with a single encounter, or determine whether
           the context has the rights to the nominated encounter, if there is one, or can determine
           an appropriate list of encouners to provide data for from the context of the request.
            If there is no nominated encounter (GET /Encounter/$everything) and the context is not
           associated with a single encounter record, the actual list of encounters is all encounters
           that the user associated with the request has access to. In such cases, the server may
           choose to return an error rather than all the records. Specifying the relationship between
           the context, a user and encounter records is outside the scope of this specification (though
           see 
          <a href="http://hl7.org/fhir/smart-app-launch">The Smart App Launch Implementation Guide</a> .
        </p> 

        <p> When this operation is used to access multiple encounter records at once, the return bundle
           could be rather a lot of data; servers may choose to require that such requests are made
           
          <a href="async.html">asynchronously</a> , and associated with 
          <a href="formats.html#bulk">bulk data formats</a> . Alternatively, clients may choose to page through the result set (or servers may require
           this). Paging through the results is done the same as for 
          <a href="http.html#paging">Searching</a> , using the 
          <a href="search.html#count">_count</a>  parameter, and Bundle links. Implementers should note that paging will be slower than
           simply returning all the results at once (more network traffic, multiple latency delays)
           but may be required in order not to exhaust available memory reading or writing the whole
           response in a single package. Unlike searching, there is no inherent user-display order
           for the $everything operation. Servers might consider sorting the returned resources in
           descending order of last record update, but are not required to do so
        </p> 

      </div> 
    </div> 
  </text> 
  <extension url="http://hl7.org/fhir/StructureDefinition/structuredefinition-fmm">
    <valueInteger value="2"/> 
  </extension> 
  <extension url="http://hl7.org/fhir/StructureDefinition/structuredefinition-ballot-status">
    <valueString value="Trial Use"/> 
  </extension> 
  <url value="http://hl7.org/fhir/OperationDefinition/Encounter-everything"/> 
  <name value="Fetch Encounter Record"/> 
  <status value="draft"/> 
  <kind value="operation"/> 
  <date value="2018-04-03T12:05:46+10: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="This operation is used to return all the information related to an encounter described
   in the resource on which this operation is invoked. The response is a bundle of type &quot;searchset
  &quot;. At a minimum, the encounter resource itself is returned, along with any other resources
   that the server has available for the given encounter for the user. The server also returns
   whatever resources are needed to support the records - e.g. linked practitioners, locations,
   organizations etc. The principle intended use for this operation is to provide a patient
   with access to their record, or to allow a client to retrieve everything for an encounter
   for efficient display).

The server SHOULD return all resources it has that:

* are included in the encounter compartment for the identified encounter (have a reference
   to the encounter)
* are referenced by the standard extenstion for associating an encounter (where no reference
   element exists) http://hl7.org/fhir/StructureDefinition/encounter-associatedEncounter
* the server believes are relevant to the context of the encounter for any other reason
   (internally defined/decided)
* any resource referenced by the above, including binaries and attachments (to make a
   more complete package)

In the US Realm, at a mimimum, the resources returned SHALL include all the data covered
   by the meaningful use common data elements (see [DAF](http://hl7.org/fhir/us/daf) for
   further guidance). Other applicable implementation guides may make additional rules about
   the information that is returned.   Note that for many resources, the exact nature of
   the link to encounter can be ambiguous (e.g. for a DiagnosticReport, is it the encounter
   when it was initiated, or when it was reported?)"/> 
  <code value="everything"/> 
  <comment value="The key differences between this operation and simply searching the encounter compartment
   are:  

* unless the client requests otherwise, the server returns the entire result set in a
   single bundle (rather than using paging) 
* the server is responsible for determining what resources to return as included resources
   (rather than the client specifying which ones)

This frees the client from needing to determine what it could or should ask for, particularly
   with regard to included resources. 

It is assumed that the server has identified and secured the context appropriately, and
   can either associate the authorization context with a single encounter, or determine whether
   the context has the rights to the nominated encounter, if there is one, or can determine
   an appropriate list of encouners to provide data for from the context of the request.
    If there is no nominated encounter (GET /Encounter/$everything) and the context is not
   associated with a single encounter record, the actual list of encounters is all encounters
   that the user associated with the request has access to. In such cases, the server may
   choose to return an error rather than all the records. Specifying the relationship between
   the context, a user and encounter records is outside the scope of this specification (though
   see [The Smart App Launch Implementation Guide](http://hl7.org/fhir/smart-app-launch).
     

When this operation is used to access multiple encounter records at once, the return bundle
   could be rather a lot of data; servers may choose to require that such requests are made
   [asynchronously](async.html), and associated with [bulk data formats](formats.html#bulk).
   Alternatively, clients may choose to page through the result set (or servers may require
   this). Paging through the results is done the same as for [Searching](http.html#paging),
   using the [_count](search.html#count) parameter, and Bundle links. Implementers should
   note that paging will be slower than simply returning all the results at once (more network
   traffic, multiple latency delays) but may be required in order not to exhaust available
   memory reading or writing the whole response in a single package. Unlike searching, there
   is no inherent user-display order for the $everything operation. Servers might consider
   sorting the returned resources in descending order of last record update, but are not
   required to do so"/> 
  <resource value="Encounter"/> 
  <system value="false"/> 
  <type value="false"/> 
  <instance value="true"/> 
  <parameter> 
    <name value="_since"/> 
    <use value="in"/> 
    <min value="0"/> 
    <max value="1"/> 
    <documentation value="Resources updated after this period will be included in the response. The intent of this
     parameter is to allow a client to request only records that have changed since the last
     request, based on either the return header time, or or (for asynchronous use), the transaction
     time"/> 
    <type value="instant"/> 
  </parameter> 
  <parameter> 
    <name value="_type"/> 
    <use value="in"/> 
    <min value="0"/> 
    <max value="*"/> 
    <documentation value="One or more parameters, each containing one or more comma-delimited FHIR resource types
     to include in the return resources. In the absense of any specified types, the server
     returns all resource types"/> 
    <type value="code"/> 
  </parameter> 
  <parameter> 
    <name value="_count"/> 
    <use value="in"/> 
    <min value="0"/> 
    <max value="1"/> 
    <documentation value="See discussion below on the utility of paging through the results of the $everything operation"/> 
    <type value="integer"/> 
  </parameter> 
  <parameter> 
    <name value="return"/> 
    <use value="out"/> 
    <min value="1"/> 
    <max value="1"/> 
    <documentation value="The bundle type is &quot;searchset&quot;"/> 
    <type value="Bundle"/> 
  </parameter> 
</OperationDefinition>