Preconditions

Before configuring limited group enrollment, verify that the following conditions are met.

• Delivery configuration is complete and the endpoint has been validated.
• Patients to be enrolled have valid Patient resources in Health Gorilla.
• Your system supports authenticated FHIR GET and POST requests.
• Your organization has an operational owner responsible for enrollment maintenance, such as a care operations team, an interface team, or an automated roster process.

Missing prerequisites are a common cause of enrollment delays or unexpected behavior.

Enrollment Configuration

After prerequisites are met, configure limited group enrollment by performing the following actions:

• Create the enrollment group once for the tenant.
• Add or remove patients over time using group membership operations.
• Validate effective group membership before confirming alert behavior.
• Group creation is performed once. Membership updates and validation occur as patient eligibility changes.

Create the Enrollment Group

Creating the enrollment group creates an empty FHIR Group. Patients are enrolled only when they are added to the group.

1. Create a FHIR Group with the following attributes:

• resourceType: Group
• type: person
• actual: true
• The name Clinical Alerts Roster is recommended, but is not required.

2. Submit the group using an authenticated FHIR POST request.

POST /fhir/R4/Group
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/fhir+json
Accept: application/fhir+json

Sample Payload

{
  "resourceType": "Group",
  "type": "person",
  "actual": true,
  "name": "Clinical Alerts Roster"
}

3. Record the group ID returned in the response. You will need the group ID to add and remove patients and validate enrollment.

Manage Group Membership

Limited group membership is not updated automatically. Your organization is responsible for maintaining membership over time using group membership operations.

Enrollment updates are incremental, meaning additive and removal-based. Full roster replacement is not supported.

Use the group ID to perform one of the following actions.

• Enroll a patient: POST /fhir/R4/Group/{group_id}/$add-to-group?patient={patient_reference}
• Unenroll a patient: POST /fhir/R4/Group/{group_id}/$remove-from-group?patient={patient_reference}

Allow several minutes for enrollment changes to propagate.

Confirm Enrollment

Validate the enrollment state before confirming alert behavior.

1. Retrieve group membership using a FHIR GET request.

GET /fhir/R4/Group/{group_id}/$members
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/fhir+json

2. Review the returned list to confirm accuracy.

Enrollment Behavior and Constraints

The following behaviors apply when using limited group enrollment:

• Enrollment is evaluated at the time qualifying document activity is processed.
• Enrollment changes apply prospectively and do not affect previously processed activity.
• Removing a patient from the group stops alert generation for that patient after propagation completes.
• Alert payloads and delivery behavior are unchanged once a patient is enrolled.
• Groups used for limited group enrollment must not include characteristic filters. Groups with characteristics are treated as system-managed enrollment and do not support explicit membership operations.
• You may use multiple limited groups when different alerting workflows require distinct patient populations.

Transitioning to All-Tenant Group Enrollment

Some organizations transition from limited group enrollment to all-tenant group enrollment in order to apply alert eligibility broadly across the tenant.

To avoid gaps in alert coverage, all-tenant group enrollment must be enabled and validated before the limited enrollment group is deleted.

To transition safely:

• Request that Health Gorilla enable all-tenant group enrollment for the tenant.
• Validate that alerts are generated and delivered for a known patient under all-tenant enrollment.
• Delete the limited enrollment group only after all-tenant enrollment is active and validated.

Enrollment evaluation remains prospective throughout the transition. Alerts are not generated retroactively.

Delete the Enrollment Group

Deleting the enrollment group removes all enrolled patients and stops alert generation under the limited group enrollment model after propagation completes.

Important: Delete the group only after all-tenant group enrollment has been enabled and validated, or when enrollment is intentionally being disabled.

1. Retrieve the group and confirm the group ID.
2. Submit a FHIR DELETE request for the group.
3. Confirm the group is no longer retrievable.

Allow several minutes for deletion to propagate before validating alert behavior.