R6 Ballot (2nd Draft)

Publish-box (todo)

8.3.10.1 Operation $everything on Group

FHIR Infrastructure icon Work Group Maturity Level: 0Trial Use Compartments: N/A

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 "searchset". 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 icon. Other applicable implementation guides may make additional rules about how much information that is returned.

The canonical URL for this operation definition is

 http://hl7.org/fhir/OperationDefinition/Group-everything

Formal Definition (as a OperationDefinition).

URL: [base]/Group/[id]/$everything

This is an idempotent operation

In Parameters:
Name Scope Cardinality Type Binding Profile Documentation
start 0..1 date

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.

end 0..1 date

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.

_since 0..1 instant

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 0..* code

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

_count 0..1 integer

See discussion below on the utility of paging through the results of the $everything operation

Out Parameters:
Name Scope Cardinality Type Binding Profile Documentation
return 1..1 Bundle

The bundle type is "searchset"

Note: as this is the only out parameter, it is a resource, and it has the name 'return', the result of this operation is returned directly as a resource

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 /[base]/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 icon).

The return bundle from this operation is usually rather a lot of data; servers typically choose to require that such requests are made asynchronously, and associated with bulk data formats. 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, using the _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.

8.3.10.1.1 Examples

Request: Get all resources linked to a single patient


GET /open/Group/example/$everything
[some headers]

Response: Everything linked to the nominated patient (in this case, built automatically by the publication tooling)


HTTP/1.1 200 OK
[other headers]

<Bundle xml="http://hl7.org/fhir">
  <id value="07741a83-d087-4d29-923d-5b83b73b17aa"/>
  <type value="searchset"/>
  <entry>
    <fullUrl value="http://hl7.org/fhir/Patient/f001"/>
    <resource>
     <?xml version="1.0" encoding="UTF-8"?>
     
     <Patient xmlns="http://hl7.org/fhir">
       <id value="f001"/>
       <identifier>
         <use value="usual"/>
         <system value="urn:oid:2.16.840.1.113883.2.4.6.3"/>
         <!--   BSN identification system   -->
         <value value="738472983"/>
       </identifier>
       <!--   BSN identification system   -->
       <identifier>
         <use value="usual"/>
         <system value="urn:oid:2.16.840.1.113883.2.4.6.3"/>
       </identifier>
       <active value="true"/>
       <name>
         <use value="usual"/>
         <family value="van de Heuvel"/>
         <given value="Pieter"/>
         <suffix value="MSc"/>
       </name>
       <telecom>
         <system value="phone"/>
         <value value="0648352638"/>
         <use value="mobile"/>
       </telecom>
       <telecom>
         <system value="email"/>
         <value value="p.heuvel@gmail.com"/>
         <use value="home"/>
       </telecom>
       <gender value="male"/>
       <birthDate value="1944-11-17"/>
       <deceasedBoolean value="false"/>
       <!--   ISO 3166 Codes (Countries)   -->
       <address>
         <use value="home"/>
         <line value="Van Egmondkade 23"/>
         <city value="Amsterdam"/>
         <postalCode value="1024 RJ"/>
         <country value="NLD"/>
       </address>
       <maritalStatus>
         <coding>
           <system value="http://terminology.hl7.org/CodeSystem/v3-MaritalStatus"/>
           <code value="M"/>
           <display value="Married"/>
         </coding>
         <text value="Getrouwd"/>
       </maritalStatus>
       <multipleBirthBoolean value="true"/>
       <contact>
         <relationship>
           <coding>
             <system value="http://terminology.hl7.org/CodeSystem/v2-0131"/>
             <code value="C"/>
           </coding>
         </relationship>
         <name>
           <use value="usual"/>
           <family value="Abels"/>
           <given value="Sarah"/>
         </name>
         <telecom>
           <system value="phone"/>
           <value value="0690383372"/>
           <use value="mobile"/>
         </telecom>
       </contact>
       <communication>
         <language>
           <coding>
             <system value="urn:ietf:bcp:47"/>
             <!--   IETF language tag   -->
             <code value="nl"/>
             <display value="Dutch"/>
           </coding>
           <text value="Nederlands"/>
         </language>
         <preferred value="true"/>
       </communication>
       <managingOrganization>
         <reference value="Organization/f001"/>
         <display value="Burgers University Medical Centre"/>
       </managingOrganization>
     </Patient>
    </resource>
  </entry>
</Bundle>

 

For more information about operations, including how they are invoked, see Operations.