Operation-group-everything.xml

Operation Definition

<?xml version="1.0" encoding="UTF-8"?>

<OperationDefinition xmlns="http://hl7.org/fhir">
  <id value="Group-everything"/> 
  <text> 
    <status value="generated"/> 
    <div xmlns="http://www.w3.org/1999/xhtml">
      <h2> Fetch a group of Patient Records</h2> 
      <p> OPERATION: Fetch a group of Patient Records</p> 
      <p> The official URL for this operation definition is: </p> 
      <pre> http://hl7.org/fhir/OperationDefinition/Group-everything</pre> 
      <div> 
        <p> This operation is used to return all the information related to one or more patients that
           are part of the group on which this operation is invoked. The response is a bundle of
           type &quot;searchset&quot;. At a minimum, the patient resource(s) itself is returned,
           along with any other resources that the server has that are related to the patient(s),
           and that are available for the given user. The server also returns whatever resources
           are needed to support the records - e.g. linked practitioners, medications, locations,
           organizations etc.   The intended use for this operation is for a provider or other user
           to perform a bulk data download.  The server SHOULD return at least all resources that
           it has that are in the patient compartment for the identified patient(s), and any resource
           referenced from those, including binaries and attachments. In the US Realm, at a mimimum,
           the resources returned SHALL include all the data covered by the meaningful use common
           data elements as defined in 
          <a href="http://hl7.org/fhir/us/coref">US-Core</a> . Other applicable implementation guides may make additional rules about how much information
           that is returned.
        </p> 

      </div> 
      <p> URL: [base]/Group/[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> start</td> 
          <td> 0..1</td> 
          <td> 
            <a href="datatypes.html#date">date</a> 
          </td> 
          <td/>  
          <td> 
            <div> 
              <p> The date range relates to care dates, not record currency dates - e.g. all records relating
                 to care provided in a certain date range. If no start date is provided, all records prior
                 to the end date are in scope.</p> 

            </div> 
          </td> 
        </tr> 
        <tr> 
          <td> IN</td> 
          <td> end</td> 
          <td> 0..1</td> 
          <td> 
            <a href="datatypes.html#date">date</a> 
          </td> 
          <td/>  
          <td> 
            <div> 
              <p> The date range relates to care dates, not record currency dates - e.g. all records relating
                 to care provided in a certain date range. If no end date is provided, all records subsequent
                 to the start date are in scope.</p> 

            </div> 
          </td> 
        </tr> 
        <tr> 
          <td> IN</td> 
          <td> _since</td> 
          <td> 0..1</td> 
          <td> 
            <a href="datatypes.html#instant">instant</a> 
          </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> 
            <a href="datatypes.html#code">code</a> 
          </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> 
            <a href="datatypes.html#integer">integer</a> 
          </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> 
            <a href="bundle.html">Bundle</a> 
          </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 group's patients 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 particular group, or determine whether
           the context has the rights to the nominated group, if there is one, or can determine an
           appropriate list of groups to provide data for from the context of the request.   If there
           is no nominated group (GET /Group/$everything) and the context is not associated with
           a single group record, the actual list of groups is all groups 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 (and is likely to do so, but not required to).  Specifying
           the relationship between the context, a user and groups 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> The return bundle from this operation is usually rather a lot of data; servers typically
           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> 

        <p> The _since parameter is provided to support periodic queries to get additional information
           that has changed about the group since the last query. This means that the _since parameter
           is based on record time. The value of the _since parameter should be set to the time from
           the server. If using direct response, this is the timestamp in the response header. If
           using the async interface, this is the transaction timestamp in the json response. Servers
           should ensure that the timestamps a managed such that the client does not miss any changes.
           Clients should be able to handle getting the same response more than once in the case
           that the transaction falls on a time boundary. Clients should ensure that the other query
           parameters are constant to ensure a coherent set of records when doing periodic queries.</p> 

      </div> 
    </div> 
  </text> 
  <extension url="http://hl7.org/fhir/StructureDefinition/structuredefinition-fmm">
    <valueInteger value="1"/> 
  </extension> 
  <extension url="http://hl7.org/fhir/StructureDefinition/structuredefinition-standards-status">
    <valueCode value="trial-use"/> 
  </extension> 
  <url value="http://hl7.org/fhir/OperationDefinition/Group-everything"/> 
  <version value="4.0.1"/> 
  <name value="Fetch a group of Patient Records"/> 
  <status value="draft"/> 
  <kind value="operation"/> 
  <date value="2021-01-21T15:34:20+00: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 one or more patients that
   are part of the group on which this operation is invoked. The response is a bundle of
   type &quot;searchset&quot;. At a minimum, the patient resource(s) itself is returned,
   along with any other resources that the server has that are related to the patient(s),
   and that are available for the given user. The server also returns whatever resources
   are needed to support the records - e.g. linked practitioners, medications, locations,
   organizations etc.   The intended use for this operation is for a provider or other user
   to perform a bulk data download.  The server SHOULD return at least all resources that
   it has that are in the patient compartment for the identified patient(s), and any resource
   referenced from those, including binaries and attachments. In the US Realm, at a mimimum,
   the resources returned SHALL include all the data covered by the meaningful use common
   data elements as defined in [US-Core](http://hl7.org/fhir/us/coref). Other applicable
   implementation guides may make additional rules about how much information that is returned."/> 
  <code value="everything"/> 
  <comment value="The key differences between this operation and simply searching the group's patients 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 particular group, or determine whether
   the context has the rights to the nominated group, if there is one, or can determine an
   appropriate list of groups to provide data for from the context of the request.   If there
   is no nominated group (GET /Group/$everything) and the context is not associated with
   a single group record, the actual list of groups is all groups 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 (and is likely to do so, but not required to).  Specifying
   the relationship between the context, a user and groups is outside the scope of this specification
   (though see [The Smart App Launch Implementation Guide](http://hl7.org/fhir/smart-app-launch).
   

The return bundle from this operation is usually rather a lot of data; servers typically
   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.

The _since parameter is provided to support periodic queries to get additional information
   that has changed about the group since the last query. This means that the _since parameter
   is based on record time. The value of the _since parameter should be set to the time from
   the server. If using direct response, this is the timestamp in the response header. If
   using the async interface, this is the transaction timestamp in the json response. Servers
   should ensure that the timestamps a managed such that the client does not miss any changes.
   Clients should be able to handle getting the same response more than once in the case
   that the transaction falls on a time boundary. Clients should ensure that the other query
   parameters are constant to ensure a coherent set of records when doing periodic queries."/> 
  <resource value="Group"/> 
  <system value="false"/> 
  <type value="false"/> 
  <instance value="true"/> 
  <parameter> 
    <name value="start"/> 
    <use value="in"/> 
    <min value="0"/> 
    <max value="1"/> 
    <documentation value="The date range relates to care dates, not record currency dates - e.g. all records relating
     to care provided in a certain date range. If no start date is provided, all records prior
     to the end date are in scope."/> 
    <type value="date"/> 
  </parameter> 
  <parameter> 
    <name value="end"/> 
    <use value="in"/> 
    <min value="0"/> 
    <max value="1"/> 
    <documentation value="The date range relates to care dates, not record currency dates - e.g. all records relating
     to care provided in a certain date range. If no end date is provided, all records subsequent
     to the start date are in scope."/> 
    <type value="date"/> 
  </parameter> 
  <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>