# Bulk Groups
The [Group Level Bulk Export Operation](export.html#endpoint---group-of-patients) 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.
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 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](https://hl7.org/fhir/us/davinci-atr/) or a Group created with using member FHIR ids located using the FHIR [patient match operation](https://hl7.org/fhir/patient-operation-match.html).
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. 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.
## 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 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.
### REST Interactions
When the Bulk Cohort API is supported, the server SHALL accept FHIR Group create requests that use the [FHIR Asynchronous Interaction Request](https://hl7.org/fhir/async-bundle.html) pattern and provide a valid FHIR Group resource that complies with the [Bulk Cohort Group Profile](#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](https://hl7.org/fhir/async-bundle.html) pattern.
### Group Profile
#### Key Elements
`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.
`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.
`modifierExtension.memberFilter` (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").
FHIR [search result parameters](https://www.hl7.org/fhir/search.html#modifyingresults) (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 (see [server capability documentation](#server-capability-documentation)). 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.
`Extension.membersRefreshed` (0..1) -
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.
`name` (1..1) -
A client SHALL include a name for the group and the server SHALL retain that name in the group that is created or return an error.
`characteristic` (0..0) -
This element is not used in a group complying with the Bulk Cohort profile.
`code` (0..1), `description` (R5 only) 0..1 and other metadata elements -
Clients and servers are encouraged to use these elements to provide information on the group.
`actual` (1..1) -
Fixed value of `true`.
#### Example
```js
{
//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"
}]
}
```
### 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 `memberFilter` expressions.
Sign in with Wallet
Connect another wallet