type: resourceresource: Group

Group

Scope and Usage

Use Cases

The Group resource is used in one of two ways:

To define a group of specific people, animals, devices, etc. that is being tracked, examined, acting collectively or otherwise referenced as part of healthcare-related activities
To define a set of possible people, animals, devices, etc. that are of interest for some intended future healthcare-related activities

Examples of the former could include a family, a household, or group therapy or treatment sessions, exposed entities tracked as part of public health, etc. The latter might be used to define expected subjects for a clinical study.

Both use cases are handled by a single resource because the data elements captured tend to be similar.

NOTE: While Specimen does not quite fit with this definition, it is being retained as part of Group to avoid making a breaking change to the Observation resource.

Defining Group Inclusion and Exclusion Criteria

The Group definition, specifying the criteria for membership in the Group, may be expressed with one or more Group.characteristic elements. Here we describe how the Group StructureDefinition is used to express inclusion and exclusion criteria for group membership.

Group.membership

Group.membership requires one of three codes:

'enumerated': Use this code if the Group Resource lists the group members and/or specifies the number of entities in the group. Use of the 'enumerated' code will require use of the Group.type element.
'definitional': Use this code if the Group Resource provides structured data (i.e. the Group.characteristic values) that is necessary and sufficient to define the qualifications for group membership (the inclusion and exclusion criteria for defining what makes something a member of the group). Use of the 'definitional' code will require use of the Group.type element. If a group is both enumerated and definitional, then use the enumerated code.
'conceptual': Use this code if the Group Resource is an abstract representation of a group that is neither enumerated (listing or counting actual members) nor definitional (providing complete definition for membership qualifications). A different use of the 'conceptual' code is when the Group is otherwise 'definitional' but the Group.type cannot be used because the actual type value is not included in FHIR types.

Group.combinationMethod

Group.combinationMethod is used when there are two or more Group.characteristic instances to define how the characteristics are combined.

Use a code 'all-of' to indicate that each of the characteristics must be met. This is functionally equivalent to combining all characteristics with an AND operator.
Use a code 'any-of' to indicate that at least one of the characteristics must be met. This is functionally equivalent to combining all characteristics with an OR operator.
Use a code 'at-least' to indicate that at least n of the characteristics must be met. Use Group.combinationThreshold to specify the value of n.
Use a code 'at-most' to indicate that at most n of the characteristics must be met. Use Group.combinationThreshold to specify the value of n.
Use a code 'except-subset' to indicate that the characteristics expressed as exclusion criteria are used as exceptions to meeting the characteristics expressed as inclusion criteria. Explaining by example: “Cancer of any kind (except basal cell skin cancer or cancer in situ) unless documented to be disease-free for five years” (Example of Group for Cancer Except Subset).

Group.combinationThreshold

Provides the value of "n" when "at-least" or "at-most" codes are used for Group.combinationMethod (see above)

Group.characteristic.code

Each characteristic must have a code value (CodeableConcept datatype) to specify the attribute. For instance:

for a characteristic of "age > 18 years” the attribute is “age” and the attribute of age may be expressed as

"code": { "coding": [ { "system": "http://snomed.info/sct", "code": "397669002", "display": "Age" } ] }

for a characteristic of "Body mass index >= 30 kg/m2" the attribute is "Body mass index" and the attribute may be expressed as

"code": { "coding": [ { "system": "http://loinc.org", "code": "39156-5", "display": "Body mass index (BMI) [Ratio]" } ] }

Group.characteristic.value[x]

Each characteristic must have a value[x] value to specify the value of the attribute that holds for members of the group. There is no [x] in the JSON or XML expression as it is replaced with the data type (CodeableConcept, boolean, Quantity, Range, Reference, uri, or Expression)

For instance:

for a characteristic of "age > 18 years” the value is “> 18 years” and the value may be expressed with a Quantity datatype as

"valueQuantity": { "comparator": ">=", "value": 18, "unit": "years",

"system": "http://unitsofmeasure.org", "code": "a" }

for a characteristic of "Body mass index >= 30 kg/m2" the value is ">= 30 kg/m2" and the value may be expressed as

"valueQuantity": { "comparator": ">=", "value": 30, "unit": "kg/m2",

"system": "http://unitsofmeasure.org", "code": "kg/m2" }

Group.characteristic.exclude

Sometimes group membership is determined by characteristics not possessed. When this is the case, the Group.characteristic.exclude element has a value of true ("exclude": true). For characteristics that are not exclusion criteria, the Group.characteristic.exclude element has a value of false ("exclude": false). The exclude element is required.

For example, an exclusion criterion of HbA1c ≥ 14.0% is expressed as:

{ "description": "HbA1c ≥ 14.0%", "code": {; "coding": [ { "system": "http://loinc.org", "code": "59261-8", "display": "Hemoglobin A1c/Hemoglobin.total in Blood" } ] }, "valueQuantity": { "value": 14, "comparator": ">=", "unit": "%", "system": "http://unitsofmeasure.org", "code": "%" }, "exclude": true }

Group.characteristic.description

A short, natural language description of the characteristic (using the markdown datatype) that could be used to communicate the criteria to an end-user. The description element is for convenience so that end users can understand the characteristic and is neither a required part of the characteristic nor part of the structured representation of the characteristic.

Group.characteristic.method

The method modifies the Group.characteristic.code and indicates how the value is to be determined, using the CodeableConcept datatype. For example, HbA1C values can be determined by High-Performance Liquid Chromatography or by Capillary electrophoresis.

The method may be expressed as multiple concepts, eg. standing barefoot for Height measurements could be expressed as two separate concepts (standing, barefoot) that express the method.

Group.characteristic.formula

The formula modifies the Group.characteristic.code and indicates how the value is to be determined, using an Expression datatype.

Group.characteristic.determiner

The determiner modifies the Group.characteristic.code and indicates who or what determines the value, using a Reference datatype. The determiner value may reference a person (Practitioner or PractitionerRole Resource) or group (Organization Resource) or device. The reference to a device can be either to a specific device using the Device Resource, or the DeviceMetric Resource if a specific set of device parameters is needed, or a type of device using the DeviceDefinition Resource.

Group.characteristic.offset

Defines the reference point for comparison when other than 0. As an example, to express a characteristic of a calcium level greater than the normal limit or a hemoglobin level less than 1 g/dL below the reference range, the offset concept would represent "normal limit" or "reference range".

This is a modifier element because it modifies the meaning of the characteristic.value[x].

Group.characteristic.instances[x]

Number of occurrences meeting the characteristic.

There should be a constraint on the Quantity.value and Range.low.value and Range.high.value that it can only be non-negative whole numbers.

Group.characteristic.duration[x]

Length of time in which the characteristic is met.

Group.characteristic.period

The period over which the characteristic is tested; e.g. the patient had an operation during the month of June.

Group.characteristic.timing

The relative time in which the characteristic is tested, eg. within a month following patient discharge.

Note: RelativeTime is a recent addition to the Group Resource. RelativeTime is used to express a point in time or an interval of time relative to an event defined in data types other than dateTime.

Example: Example of Group for HbA1c at 12 months

Example includes timing and offset "At 12 months form inclusion in a clinical trial. Inclusion is defined as enrollment via the SNOMED code.

"timing": [ { "contextCode": { "coding": [ { "system": "http://snomed.info/sct", "code": "709491003", "display": "Enrollment in clinical trial" } ] }, "offsetDuration": { "value": 12, "unit": "months", "system": "http://unitsofmeasure.org", "code": "mo" }, "text": "at 12 months" }

Boundaries and Relationships

There are a number of mechanisms in FHIR for communicating collections of resources:

The List resource - enumerates a flat collection of resources and provides features for managing the collection. While a particular List instance may represent a "snapshot", from a business process perspective the notion of "List" is dynamic – items are added and removed over time. The List resource references other resources. Lists may be curated and have specific business meaning. For use cases where Group is suitable (e.g. for a list of Patients to be viewed on a dashboard), the Group resource should be preferred to the List resource. The underlying rationale is that a collection of patients, practitioners, etc. is likely to be of interest as the subject of a measure, observation, communication, etc., which Group is intended to support.
This Group resource - defines a group of specific people, animals, devices etc. by enumerating them, or by describing qualities that group members have. The group resource refers to other resources, possibly implicitly. Groups are intended to be acted upon or observed as a whole; e.g. performing therapy on a group, calculating risk for a group, etc. This resource will commonly be used for public health (e.g. describing an at-risk population), clinical trials (e.g. defining a test subject pool) and similar purposes. It may be used to define families or households, which in some circumstances may act collectively or have a degree of legal or formal recognition.
The Organization resource is used for collections of people that have come together to achieve an objective. In generally, the Group resource is used to identify a collection of people (or animals, devices, etc.) that are gathered for the purpose of analysis or acting upon, but are not expected to act themselves. Families or households are sometimes an exceptiont to this, in that they are primarily recipients of care, particularly in a public health context, but sometimes act collectively
CareTeam. Group is distinct from CareTeam. Group is patient-independent and identifies an undifferentiated set of individuals who are intended to be the target of one or more clinical activities (e.g. set of clinical trial participants, set of individuals impacted by or at risk of a public health event, a herd or flock, etc.) The CareTeam resource establishes a set of relationships and roles and is specific to a particular Patient. The actors are the individual members or organized group of individuals. CareTeam can be referenced by EpisodeOfCare, Encounter, or CarePlan to identify the set of individuals (and their respective roles) who are intended to be involved in providing the care defined by those resources. Groups containing practitioners are not allowed to perform actions for patient care.
The Bundle resource - is an infrastructure container for a group of resources. It does not have narrative and is used to group collections of resources for transmission, persistence or processing (e.g. messages, documents, transactions, query responses, etc.) The content of bundles is typically algorithmically determined for a particular exchange or persistence purpose.
The Composition resource - defines a set of healthcare-related information that is assembled together into a single logical document that provides a single coherent statement of meaning, establishes its own context and that has clinical attestation with regard to who is making the statement. The composition resource provides the basic structure of a FHIR document. The full content of the document is expressed using a bundle. Compositions will often reference Lists as the focus of particular sections.
The DomainResource.contained element - allows multiple resources to be nested inside any DomainResource. This is a special type of grouping where the grouped resources lose independent existence - they no longer have their own identifiers, can't easily be queried independently, etc. Use of this grouping is a technical mechanism for managing the independence of resources and has no impact on meaning.

Notes

Mixing Characteristics and Members

If both Group.characteristic and Group.member are present, then the members are the individuals who were found who met the characteristic. It's possible that there might be other candidate members who meet the characteristic and aren't (yet) in the list. All members SHALL have the listed characteristics.

Managing large Groups

For operations to assist in adding to, removing from, or filtering contents of large Groups, see Operations for Large Resources.

Groups as Families and Households

As discussed in the introduction, when a Group has a code of 'family' or 'household' it is permitted to take on responsibility - it can be a performer, author, witness, etc.

For example, it is possible for a Group with a code of 'family' to be a performer of an Observation or owner of a Task. However, this is not permitted for a Group made up of Practitioners, PractitionerRoles or Organizations. Groups with a code other than 'family' or 'household' SHALL NOT be targets of references for elements that take on responsibility, though they might still be targets of other element types (subject, focus, target, etc.) If a collective that is not a family or household needs to take collective action, use Organization or CareTeam would need to be used instead. A Group of Practitioners could, however, be a subject of an Observation.

Membership

Membership testing is used to test for active members of a Group. At a minimum, servers supporting membership testing on Group resources SHALL be able to correctly identify active enumerated entities. Active enumerated entities in a group are entities:

listed in Group.member.entity,
that do not have Group.member.inactive with a value of true, and
do not have an expired Group.member.period (e.g., either the element is not present or has a period covering 'now').

Membership testing MAY also be applied to characteristic-defined Groups. If supported, membership testing is based on the characteristic testing of the Group. Any entity meeting the required characteristics is considered to be active.

Servers SHOULD declare whether they support only the enumerated or characteristic group filters, via CapabilityStatement.rest.resource.documentation in markdown. Servers MAY impose additional membership constraints (e.g. based on modifier extensions).

Relationships inside the group

Some systems may track detailed family relationship codes (e.g. child, mother, grandfather) within a group rather than merely saying "family member". There are a few options to support conveying such information:

Instances of the PersonalRelationship resource can be used to indicate relationships between group members. Such relationships can be leveraged independent of the participants' involvement of the group
More detailed family relationship codes (e.g. from the [Personal Relationship RoleType Valueset](https://terminology.hl7.org/6.0.2/ValueSet-v3-PersonalRelationshipRoleType.html)) MAY be sent as additional Codings in the Group.member.involvement element. These SHOULD also be accompanied by the 'family-member' code to support systems that might not understand more detailed codes. If this is done, then the relationship codes are interpreted as being with respect to whichever group member is designated as "head of household"/"primary contact". If there is no such group member explicitly designated, then the nature of the more detailed personal relationship codes cannot reliably be interpreted.

StructureDefinition

Elements (Simplified)

Group [0..*]: - Group of multiple entities
Group.url [0..1]: uri Canonical identifier for this Group, represented as an absolute URI (globally unique)
Group.identifier [0..*]: Identifier Business Identifier for this Group
Group.version [0..1]: string Business version of the Group
Group.versionAlgorithm[x] [0..1]: string, Coding extensible:version-algorithm How to compare versions
Group.name [0..1]: string Label for Group
Group.title [0..1]: string Name for this Group (human friendly)
Group.status [0..1]: code required:publication-status draft | active | retired | unknown
Group.experimental [0..1]: boolean For testing only - never for real usage
Group.date [0..1]: dateTime Date last changed
Group.publisher [0..1]: string Name of the publisher/steward (organization or individual)
Group.contact [0..*]: ContactDetail Contact details for the publisher
Group.description [0..1]: markdown Natural language description of the group
Group.useContext [0..*]: UsageContext The context that the content is intended to support
Group.purpose [0..1]: markdown Why this Group is defined
Group.copyright [0..1]: markdown Notice about intellectual property ownership, can include restrictions on use
Group.copyrightLabel [0..1]: string Copyright holder and year(s)
Group.type [0..1]: code required:group-type person | animal | practitioner | device | careteam | healthcareservice | location | organization | relatedperson | specimen | medication | medicinalproductdefinition | substance | substancedefinition | biologicallyDerivedProduct | nutritionProduct
Group.membership [1..1]: code required:group-membership-basis definitional | conceptual | enumerated
Group.code [0..1]: CodeableConcept extensible:group-code Use of the Group (and by implication, kind of members)
Group.quantity [0..1]: unsignedInt Number of members
Group.managingEntity [0..1]: [Reference(Organization](/Reference(Organization), RelatedPerson, Practitioner, PractitionerRole)) Entity that is the custodian of the Group's definition
Group.combinationMethod [0..1]: code required:group-characteristic-combination all-of | any-of | at-least | at-most | except-subset
Group.combinationThreshold [0..1]: positiveInt Provides the value of "n" when "at-least" or "at-most" codes are used
Group.characteristic [0..*]: BackboneElement Include / Exclude group members by Trait
Group.characteristic.code [1..1]: CodeableConcept example:example-characteristic-codes Kind of characteristic
Group.characteristic.value[x] [1..1]: CodeableConcept, boolean, Quantity, Range, Reference, uri, Expression Value held by characteristic
Group.characteristic.exclude [1..1]: boolean Group includes or excludes
Group.characteristic.description [0..1]: markdown Natural language description of the characteristic
Group.characteristic.method [0..*]: CodeableConcept example:definition-method Method for how the characteristic value was determined
Group.characteristic.formula [0..1]: Expression Formal algorithm to derive the value
Group.characteristic.determiner [0..1]: [Reference(Practitioner](/Reference(Practitioner), PractitionerRole, Organization, Device, DeviceDefinition)) Who determines the value
Group.characteristic.offset [0..1]: CodeableConcept example:characteristic-offset Reference point for comparison
Group.characteristic.instances[x] [0..1]: unsignedInt, Range Number of occurrences meeting the characteristic
Group.characteristic.duration[x] [0..1]: Duration, Range Length of time in which the characteristic is met
Group.characteristic.period [0..1]: Period Period over which characteristic is tested
Group.characteristic.timing [0..*]: RelativeTime Timing in which the characteristic is determined
Group.member [0..*]: BackboneElement Who or what is in group
Group.member.entity [1..1]: [Reference(CareTeam](/Reference(CareTeam), Device, Group, HealthcareService, Location, Organization, Patient, Practitioner, PractitionerRole, RelatedPerson, Specimen, Medication, MedicinalProductDefinition, Substance, SubstanceDefinition, BiologicallyDerivedProduct, NutritionProduct)) Reference to the group member
Group.member.involvement [0..*]: CodeableConcept example:group-involvement-set Code that describes how user is part of the group
Group.member.period [0..1]: Period Period member belonged to the group
Group.member.inactive [0..1]: boolean If member is no longer in group

Mappings

Group Mappings — 29 mapping entries

Implementation Guide

implementationguide-Group-core.xml

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

<ImplementationGuide xmlns="http://hl7.org/fhir">
  <id value="Group-core"/>
  <identifier>
    <system value="urn:ietf:rfc:3986"/>
    <value value="urn:oid:2.16.840.1.113883.4.642.30.3"/>
  </identifier>
  <name value="StandardGroupExtensions"/>
  <title value="Standard Group Extensions"/>
  <status value="draft"/>
  <date value="2014-01-31T00:00:00.000"/>
  <publisher value="Health Level Seven, Inc. - [WG Name] WG"/>
  <description value="This profile describes common extensions that are used with Group"/>
</ImplementationGuide>

Operations

everything — Fetch a group of Patient Records — 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.
purge — Purge Group Record — This operation is used to request the removal of all current and historical versions for all resources in a Group of patient compartments.

Full Operations

Resource Packs

list-Group-packs.xml

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

<List xmlns="http://hl7.org/fhir">
  <id value="Group-packs"/>
  <status value="current"/>
  <mode value="working"/>
  <entry>
    <item>
      <reference value="ImplementationGuide/Group-core"/>
    </item>
  </entry>
</List>

Search Parameters

membership — token — Definitional or enumerated group — Group.membership
characteristic — token — Kind of characteristic — Group.characteristic.code
characteristic-value — composite — A composite of both characteristic and value — Group.characteristic
characteristic-quantity — composite — A composite of both characteristic and quantity values — Group.characteristic
characteristic-reference — composite — A composite of both characteristic and reference values — Group.characteristic
code — token — The kind of resources contained — Group.code
exclude — token — Group includes or excludes — Group.characteristic.exclude
identifier — token — Unique id — Group.identifier
managing-entity — reference — Entity that is the custodian of the Group's definition — Group.managingEntity
member — reference — Reference to the group member — Group.member.entity
type — token — The type of resources the group contains — Group.type
value — token — Value held by characteristic — (Group.characteristic.value.ofType(CodeableConcept)) | (Group.characteristic.value.ofType(boolean))
quantity — quantity — Quantity Value held by characteristic — (Group.characteristic.value.ofType(Quantity)) | (Group.characteristic.value.ofType(Range))
name — string — A portion of the Group's name — Group.name
url — uri — The uri that identifies the Group — Group.url
status — token — The current status of the Group — Group.status
experimental — token — Whether the Group is experimental — Group.experimental

Full Search Parameters

Examples

101 — group-example — General Group Example, Characteristic Based
102 — group-example-member — General Group Example, Member Based
example-conceptualcohortdefinition-cancer-except-subset — group-example-conceptualcohortdefinition-cancer-except-subset — ConceptualCohortDefinition: Cancer of any kind (except basal cell skin cancer or cancer in situ) unless documented to be disease-free for five years
example-eligibility-criteria-ada-rec-bariatric — group-example-eligibility-criteria-ada-rec-bariatric — Inclusion Criteria: [[1]] Adults. [[2]] Diagnosed with type 2 diabetes. [[3]] Body Mass Index (BMI) ≥ 40.0 kg/m2 (BMI ≥ 37.5 kg/m2 in Asian Americans), or BMI ≥ 35.0 kg/m2 and ≤ 39.9 kg/m2 (BMI 32.5-37.4 kg/m2 in Asian Americans) who do not achieve durable weight loss and improvement in comorbidities (including hyperglycemia) with nonsurgical methods. [[4]] Screened surgical candidates.
example-outcomedefinition-hba1c-at-12-months — group-example-outcomedefinition-hba1c-at-12-months — OutcomeDefinition: HbA1c at 12 months
example-patientlist — group-example-patientlist — Patients primarily attributed to Practitioner 123
example-Stroke-Thrombolysis-Trialists-2014-2016-IPD-MA-Cohort — group-example-Stroke-Thrombolysis-Trialists-2014-2016-IPD-MA-Cohort — Stroke Thrombolysis Trialists’ Collaborators Group collection used for individual patient data meta-analysis
Family — group-example-family — Example of a Family
group-example — group-example
group-example-conceptualcohortdefinition-cancer-except-subset — group-example-conceptualcohortdefinition-cancer-except-subset
group-example-eligibility-criteria-ada-rec-bariatric — group-example-eligibility-criteria-ada-rec-bariatric
group-example-family — group-example-family
group-example-herd1 — group-example-herd1
group-example-household — group-example-household
group-example-member — group-example-member
group-example-outcomedefinition-hba1c-at-12-months — group-example-outcomedefinition-hba1c-at-12-months
group-example-patientlist — group-example-patientlist
group-example-Stroke-Thrombolysis-Trialists-2014-2016-IPD-MA-Cohort — group-example-Stroke-Thrombolysis-Trialists-2014-2016-IPD-MA-Cohort
group-examples-header — group-examples-header
herd1 — group-example-herd1 — Herd of 2500 breeding sows
Household — group-example-household — Example of a Household

Full Examples

FiveWs.author — Not relevant for this resource
FiveWs.actor — Not relevant for this resource
FiveWs.cause — Not relevant for this resource
FiveWs.where — Not relevant for this resource
FiveWs.context — Not relevant for this resource
FiveWs.init — Not relevant for this resource
FiveWs.source — Not relevant for this resource
FiveWs.who — Not relevant for this resource
FiveWs.grade — Not relevant for this resource
FiveWs.planned — Not relevant for this resource
FiveWs.done — Not relevant for this resource

group-participant-mapping-exceptions.xml

Divergent Elements

Participant.identifier → Group.identifier
- shortUnmatched | reason=Unknown | pattern=Business Identifier for group | resource=Business Identifier for this Group
- definitionUnmatched | reason=Unknown | pattern=Business identifiers assigned to this group by one of the applications involved. These identifiers remain constant as the resource is updated and propagates from server to server. | resource=Business identifiers assigned to this participant by one of the applications involved. These identifiers remain constant as the resource is updated and propagates from server to server.
- commentsUnmatched | reason=Removed information not relevant to this resource | pattern=Note: This is a business identifier, not a resource identifier (see discussion). It is best practice for the identifier to only appear on a single resource instance, however business practices may occasionally dictate that multiple resource instances with the same identifier can exist - possibly even with different resource types. For example, multiple Patient and a Person resource instance might share the same social insurance number. | resource=Note: This is a business identifier, not a resource identifier (see discussion). It is best practice for the identifier to only appear on a single resource instance, however business practices may occasionally dictate that multiple resource instances with the same identifier can exist - possibly even with different resource types.
Participant.name → Group.name
- shortUnmatched | reason=Unknown | pattern=A name for the group | resource=Label for Group
- definitionUnmatched | reason=Unknown | pattern=Description of the group as presented to a consumer while searching. | resource=A label assigned to the group for human identification and communication.

Unmapped Elements

Participant.active — Unknown