Bulk Data Access IG, published by HL7 International / FHIR Infrastructure. This guide is not an authorized publication; it is the continuous build for version 3.0.0-ballot built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/HL7/bulk-data/ and changes regularly. See the Directory of published versions

Groups

Bulk Exporting Data for a Group

The Group Level Bulk Export Operation scopes the data returned in an export to the population defined by a FHIR Group resource on the server. Depending on the capabilities exposed by the server, a client may be able to retrieve a list of the Group resources it has access to, search for Group resource based on their attributes, read the contents of individual Group resources, and perform other FHIR operations such as creating new Groups, adding and removing members from a Group, or deleting previously created Group resources.

Group Types

When considering Bulk Export use cases, the community has identified three common patterns of group related server capabilities. A server may support one or more of these patterns.

1. Read-only groups: Cohorts of patients are managed entirely by the server and are exposed to the client as a set of Group FHIR ids for use in a Bulk Export operation. The server may also provide an API to view, list, and/or search for Group resources on the server, but does not offer clients the ability to create, update or delete Group resources. Examples include a roster provided by a payer organization to a provider organization using negotiated data from another system and a list of patients configured using a registry tool in an EHR system.

2. Member-based groups: Cohorts are managed by the client by specifying individual members using a FHIR API with the ability to add and remove members in Group resources, and/or create and delete Group resources themselves. Depending on the server capabilities exposed, a client may add members based on their FHIR ids or using characteristics such as a subscriber number. Adding Group resources or adding patients to a group may trigger automated or manual approval workflows on the server. Examples include a patient roster managed using the DaVinci ATR API or a Group created with using member FHIR ids located using the FHIR patient match operation.

3. Criteria-based groups: Cohorts of patients on the server are managed by the client with a FHIR API that includes the ability to define Group resources based on a set of patient characteristics. These characteristics are then used by the server to associate members with the group. The server may also populate other elements of the group, such as the date membership was last computed. Examples include a client using a FHIR API to create a cohort of patients who are assigned to a specific practitioner, or a cohort of patients with a problem list condition of diabetes and a visit in the past month. A group may represent a subset of another "read-only group" or "member-based group", and could be point-in-time snapshot based on membership at the time of creation or dynamically update as new patients meet the specified criteria. The Bulk Cohort API described below represents one approach to defining criteria based groups.

Bulk Cohort API

Servers supporting the Bulk Data Access IG MAY support the Bulk Cohort API, which consists of an asynchronous Group creation REST interaction and a profile on the Group resource. The intent is to support the creation of characteristic-based cohorts using coarse-grained filters to efficiently export data on sets of patients from a source system. Post export, the client can use more complex filter criteria to support use cases such as measure calculation or other analytics. Groups complying with the Bulk Cohort profile must contain a member-filter modifier extension to define the members included in the group. Servers may concurrently support other group profiles that contain lists of members or use other methods to define group inclusion.

REST Interactions

When the Bulk Cohort API is supported, the server SHALL accept FHIR Group create requests that use the FHIR Asynchronous Interaction Request pattern and provide a valid FHIR Group resource that complies with the Bulk Cohort Profile. Servers MAY also accept synchronous FHIR Group create requests, but since not all servers can create groups in this way (for example, some systems require a manual group approval step), clients should not expect this to be universally available. After group creation, a server MAY subsequently make the new Group resource available to authorized clients or MAY reject resource creation request and returning a relevant error. Servers SHOULD support read, search, delete, and Bulk Export operations on created Group resources, and SHOULD support the name search parameter in search requests for these resources. Servers MAY support other FHIR REST API operations and other search parameters.

Servers MAY support Group update requests. When update requests are supported, servers SHALL accept update requests that use the FHIR Asynchronous Interaction Request pattern and MAY accept synchronous update requests.

When a client and server are using SMART on FHIR authorization, scopes relevant to a group related API transaction SHALL be requested by the client and granted by the server prior to the client making the request. For example, when using SMART on FHIR v2, creating and managing Groups can be represented with system/Group.cud and retrieving the groups accessible to the client can be represented with system/Group.rs.

Group Profile

Full Bulk Cohort Profile

Key Elements

member (0..*)
A server MAY support the inclusion of one or more member elements that contain an entity element with a reference to a Patient resource, Practitioner resource, Device resource, or a Group resource that is a group of one of these resource types. When members are provided, the expression in the member-filter extension for the Group SHALL only be applied to the referenced resources and the compartments of the referenced resources, and the resources and compartments of the members of any referenced Groups. When members are not provided and the Group's type element is set to person, the expression in the member-filter extension SHALL be applied to all of the Patient resources and Patient compartments the client is authorized to access. When members are not provided and the Group's type element is set to practitioner, the expression in the member-filter extension SHALL be applied to all of the Practitioner resources and Practitioner compartments the client is authorized to access. When members are not provided and the Group's type element is set to device, the expression in the member-filter extension SHALL be applied to all of the Device resources and Device compartments the client is authorized to access.

member-filter ModifierExtension (1..*)
A server SHALL support the inclusion of one or more member-filter modifier extensions containing a valueExpression with a language of application/x-fhir-query and an expression populated with a FHIR REST API query, and SHALL support REST queries for one or more of the Patient, Practitioner, or Device resource types. For supported resource types, the server SHALL also support querying the resources in that resource type's compartment. If multiple member-filter extensions are provided, servers SHALL filter the group to only include resources that meet the conditions in all of the expressions or resources that have resources in their compartments that meet the conditions in all of the expressions. A server MAY also support other expression languages such as text/cql. When more than one language is supported by a server a client SHALL use a single language type for all of the member-filter expressions included in a single Group.

FHIR search result parameters (such as _sort, _include, and _elements) SHALL NOT be used as member-filter criteria. Additionally, a query in the member-filter parameter SHALL have the search context of a single FHIR Resource Type. The contexts "all resource types" and "a specified compartment" are not allowed. Clients should consult the server's capability statement to identify supported search parameters. Servers SHALL reject Group creation requests that include unsupported search parameters in a member-filter expression. Implementation guides that reference the Bulk Cohort API, should specify required search parameters must be supported for their use case. Other implementations guides that incorporate the Bulk Export operation MAY provide a set of core search parameters that servers implementing the guide need to support.

members-refreshed Extension (0..*)
If a group's membership is calculated periodically from the member-filter criteria, a server SHALL populate a valueDateTime with the date the group's membership was last updated. When a date element is populated for the Group, the valueDateTime element SHALL NOT be later than the date in that element, but may be the same datetime or an earlier datetime. If members are calculated dynamically for the group (for example, when a Bulk Export operation is kicked off) this value SHALL be omitted. The server's refresh cycle capabilities and relevant configuration options SHOULD be described in the server's documentation.

type (1..1)
A client SHALL populate this element with person when creating a group of Patient resources, practitioner when creating a group of Practitioner resources, or device when creating a group of Device resources.

name (1..1)
A label assigned to the group for human identification and communication.

characteristic (0..0)
This element is not used in groups complying with this profile

actual (1..1)
True if the member element is populated, otherwise false.

Example

Group with plan members filtered to patients with diabetes on their problem list and an ambulatory encounter in January 2024.

{
  "resourceType" : "Group",
  ...
  "language" : "en",
  ...
  "extension" : [
    {
      "url" : "http://hl7.org/fhir/uv/bulkdata/StructureDefinition/members-refreshed",
      "valueDateTime" : "2024-08-22T10:00:00Z"
    }
  ],
  "modifierExtension" : [
    {
      "url" : "http://hl7.org/fhir/uv/bulkdata/StructureDefinition/member-filter",
      "valueExpression" : {
        "language" : "application/x-fhir-query",
        "expression" : "Condition?category=http://terminology.hl7.org/CodeSystem/condition-category|problem-list-item&clinical-status=http://terminology.hl7.org/CodeSystem/condition-clinical|active&code=http://hl7.org/fhir/sid/icd-10-cm|E11.9"
      }
    },
    {
      "url" : "http://hl7.org/fhir/uv/bulkdata/StructureDefinition/member-filter",
      "valueExpression" : {
        "language" : "application/x-fhir-query",
        "expression" : "Encounter?class=http://terminology.hl7.org/CodeSystem/v3-ActCode|AMB&date=ge2024-01-01&date=le2024-01-31"
      }
    }
  ],
  "type" : "person",
  "actual" : true,
  "name" : "DM Dx and Jan. 2024 Ambulatory Encounter",
  "member" : [
    {
      "entity" : {
        "reference" : "http://example.org/fhir/Group/blue-cross-members"
      }
    }
  ]
}

View Example

Server Capability Documentation

To provide clarity to developers on which capabilities are implemented in a particular server, server providers SHALL ensure that their Capability Statement accurately reflects the Bulk Cohort profile as a rest.resource.supportedProfile of Group. Server providers SHOULD also ensure that their documentation addresses when and how often are Bulk Cohort group membership is updated and which search parameters are supported in member-filter expressions.