FHIR Cohort
Category: Healthcare Standards
Node id: fhir-cohort
Maturity: beta
Risk tier: B
Standards: GDPR, ISO 13485, IEC 62304
Runs a versioned, reviewed cohort definition file against the FHIR server and writes the sorted patient-id list to a hashed members file. Fails instead of emitting a partial or truncated cohort; never outputs demographics.
What it does
- network
- phi
Use cases
- Define the HGUGM cardiology pilot cohort (Cardiología episodes in the study window) reproducibly.
- Produce the cohort member list that P7/P8 batching iterates over.
Input ports
| Name | Type | Required | Description |
|---|---|---|---|
trigger | any | No | Optional upstream signal; ignored. The definition file is the only input that shapes the cohort. |
Output ports
| Name | Type | Required | Description |
|---|---|---|---|
result | json | No | Run record: definition id, version and SHA-256, executed_at, complete, patient_count and per-criterion counts. No patient ids or demographics. |
members_path | text | No | Absolute path of the members file (<cohort_dir>/<definition_id>@<version>/<executed_at>.members.json). |
members_sha256 | text | No | Hex SHA-256 of the members file bytes, for the run record. |
success | boolean | No | True when the cohort ran complete and the members file was written. |
Settings
Basic
| Setting | Name | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|---|
| Definition file | definition_path | string | Yes | Path to a tietai.cohort-definition/v1 JSON file, e.g. deployments/tenants/hgugm/cohorts/hgugm-cardiology-pilot-v1.json. | ||
| Cohort directory | cohort_dir | string | Yes | Absolute directory for members files on the hospital volume (pilot: /srv/hgugm/cohorts). Created with mode 0700. |
Advanced
| Setting | Name | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|---|
| FHIR version | fhir_version | enum | No | R4 | R4, R4B, R5 | FHIR version negotiated with the server (default R4). |
Errors
| Code | Description |
|---|---|
DEFINITION_INVALID | The definition file is missing, not closed-schema valid, or lacks reviewed_by. |
COHORT_INCOMPLETE | A criterion failed (UMLS/FHIR error, concept with no codes) or hit the scan limit; no cohort is emitted. |
COHORT_TOO_LARGE | More than 2000 patients matched; the node fails rather than truncate. |
COHORT_EXECUTION_FAILED | The FHIR endpoint or credentials are not configured, or the query was refused. |
COHORT_MEMBERS_WRITE_FAILED | cohort_dir is missing, relative, or the members file could not be written (an existing record is never overwritten). |
Runtime notes
- The FHIR endpoint comes from FHIR_BASE_URL and the platform credentials, exactly as for the fhir_cohort_query tool; there is no per-node URL.
- Runs the definition through ToolSet.RunCohort with include_summaries=false, max_patients=2000 and max_pages=100.
- Patient ids are written only to the members file; the result output carries counts and hashes, never ids or demographics.
- A definition whose reviewed_by is a <placeholder> runs, with a 'review pending' warning in result.warnings.
See Build any workflow for how to put nodes together and Ports, types and data flow for how port types connect.
Something unclear? Send documentation feedback by email.