Bulk Data Access IG, published by HL7 International / FHIR Infrastructure. This guide is not an authorized publication; it is the continuous build for version 2.0.0 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
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.
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.
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.
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 as 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.
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. Examples would be a client that uses 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.
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 more efficiently export data on sets of patients from a source system. Post export, the client can use the FHIR resources returned for these cohorts for finer grained filtering to support use cases such as measure calculation or analytics that may necessitate more complex filter criteria.
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 Group Profile. The 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.
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, or Group resource that is a group of Patient resources or Practitioner resources. When members are provided, the expression in the memberFilter
extension for the Group SHALL only be applied to the compartments of the referenced resources, or those of the members of referenced Group resources. When members are not provided and the Group's type
element is set to person
, the expression in the memberFilter
extension SHALL be applied to all of the 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 memberFilter
extension SHALL be applied to all of the Practitioner compartments the client is authorized to access.
memberFilter
ModifierExtension (1..*)
A server SHALL support the inclusion of one or more memberFilter
modifier extensions containing a valueExpression
with a language of application/x-fhir-query
and an expression
populated with a FHIR REST API query for a resource type included in the Patient or Practitioner compartment. If multiple memberFilter
extensions are provided that contain criteria for different resource types, servers SHALL filter the group to only include Patients or Practitioners that have resources in their compartments that meet the conditions in all of the expressions. If multiple memberFilter
extensions are provided that contain criteria for a single resource type, the server SHALL include Patients or Practitioners who have resources in their compartments that meet the criteria for that resource type in any of those expressions (a logical "or"). A server MAY also support other expression languages such as text/cql
. When more than one lanugage is supported by a server a client SHALL use a single language type for all of the memberFilter expressions included in a single Group.
FHIR search result parameters (such as _sort, _include, and _elements) SHALL NOT be used as memberFilter
criteria. 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 memberFilter
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.
membersRefreshed
Extension (0..*)
If a groups membership is calculated periodically from the memberFilter
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 relevent 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 Patients, or practitioner
when creating a group of Practitioners.
name
(1..1)
A label assigned to the group for human identification and communication.
characteristic
(0..0)
Identifies traits whose presence r absence is shared by members of the group.
actual
(1..1)
If true, indicates that the resource refers to a specific group of real individuals. If false, the group defines a set of intended individuals.
{
//group with plan members (type 1 or 2 group)
//filtered to patients with T2 DM and an ambulatory encounter in January 2024
"resourceType": "Group",
"member": [{
"entity": {"reference": "Group/blue-cross-members"}
}],
"modifierExtension": [{
"url": "{...}/memberFilter",
"valueString": "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": "{...}/memberFilter",
"valueString": "Encounter?
class=http://terminology.hl7.org/CodeSystem/v3-ActCode|AMB&
date=ge2024-01-01&date=le2024-01-31"
}]
}
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 memberFilter
expressions.