Skip to main content

Group

Overview​

The Group resource "represents a defined collection of entities that may be discussed or acted upon collectively but which are not expected to act collectively, and are not formally or legally recognized; i.e. a collection of entities that isn't an Organization."

In the context of bulk data export, Group resources define collections of patients whose data can be exported together.

Key Use Cases:

  • Define patient populations for bulk export
  • Organize patients by care programs or conditions
  • Support population health analytics
  • Enable cohort-based data analysis

Resource Schema​

Key fields in Group resources:

{
  "resourceType": "Group",
  "id": "example-group",
  "active": true,
  "type": "person",
  "actual": true,
  "name": "Diabetes Care Program Patients",
  "quantity": 150,
  "member": [
    {
      "entity": {
        "reference": "Patient/123"
      }
    }
  ]
}

Operations​

Note: Always verify supported operations by checking the CapabilityStatement before implementation.

Read​

Retrieves a specific Group resource by ID.

Endpoint: GET /Group/{id}

Examples​

Read Group Resource
curl -X GET https://fhir.netsmartcloud.com/uscore/v1/bulk-data/Group/example-group \
    -H "Authorization: Bearer {access_token}" \
    -H "Accept: application/fhir+json"

Export Operation ($export)​

Initiates bulk data export for all patients in the specified Group.

Endpoint: GET /Group/{id}/$export

Parameters​

Note: Available parameters are defined in the CapabilityStatement. Always verify current parameters before implementation.

NameTypeRequiredDescription
_outputFormatstringNoFormat for exported data (default: application/fhir+ndjson)
_sinceinstantNoOnly include resources modified after this date
_typestringNoComma-separated list of resource types to export

Examples​

Initiate Group Export
curl -X GET "https://fhir.netsmartcloud.com/uscore/v1/bulk-data/Group/example-group/\$export" \
    -H "Authorization: Bearer {access_token}" \
    -H "Accept: application/fhir+json" \
    -H "Prefer: respond-async"
Export with Parameters
curl -X GET "https://fhir.netsmartcloud.com/uscore/v1/bulk-data/Group/example-group/\$export?_type=Patient,Observation&_since=2024-01-01T00:00:00Z" \
    -H "Authorization: Bearer {access_token}" \
    -H "Accept: application/fhir+json" \
    -H "Prefer: respond-async"

Response​

Export Initiated
HTTP/2 202 Accepted
Content-Location: https://fhir.netsmartcloud.com/uscore/v1/bulk-data/$export-poll-status/abc123

{
  "transactionTime": "2024-01-15T10:30:00Z",
  "request": "https://fhir.netsmartcloud.com/uscore/v1/bulk-data/Group/example-group/$export",
  "requiresAccessToken": true
}

Integration Patterns​

Bulk Export Workflow​

# Step 1: Retrieve CapabilityStatement
GET /metadata

# Step 2: Identify available Groups
GET /Group/{id}

# Step 3: Initiate export
GET /Group/{id}/$export

# Step 4: Poll for completion
GET /$export-poll-status/{job-id}

# Step 5: Download files
GET /Binary/{file-id}/$binary-access-read

Common Export Patterns​

Population Health Export:

# Export all data for a patient population
GET /Group/diabetes-patients/$export

Filtered Export:

# Export specific resource types since a date
GET /Group/care-program/$export?_type=Patient,Observation&_since=2024-01-01T00:00:00Z

Supported Profiles​

Note: Supported profiles are extracted from the CapabilityStatement. Always verify current profiles by checking the supportedProfile arrays.

Error Handling​

For common error scenarios and troubleshooting guidance, see Common Errors.

Relationships to Other Resources​

  • Patient: Group members reference Patient resources
  • Binary: Export operation generates Binary resources for file downloads
  • CapabilityStatement: Documents supported Group operations and parameters