EMPI Identity & Act Resolution
Category: Healthcare Standards
Node id: empi
Maturity: production
Risk tier: C
Standards: FHIR R4, HIPAA, GDPR
Enterprise Master Patient Index — deterministic rules plus probabilistic (Fellegi-Sunter) scoring for patient identity and clinical act reconciliation via tietai-empi-service, with pairs the thresholds cannot settle queued for human review. Choose the action with 'operation'.
What it does
- Deterministic rules plus Fellegi-Sunter scoring, with configurable thresholds
- Doubtful pairs queued for human review instead of resolved blind
- Clinical act reconciliation on the same engine as patient identity
- Batch deduplication, merge, clusters and single best record
- External identifier lookup (MRN, SSN, DNI)
- FHIR R4 Patient $match returning a scored Bundle
Use cases
- Patient identity resolution across source systems
- Reconciling episodes, consultations, tests and procedures duplicated across systems
- Working the human-review queue of pairs the thresholds could not settle
- Cross-system deduplication and golden-record generation
Runtime
- Performance tier:
variable
Input ports
| Name | Type | Required | Description |
|---|---|---|---|
patient_data | json | No | Demographics of the patient to match/create (match). Ignored when record_id is set. |
record_id | text | No | UUID of an existing EMPI record to match (match). |
identifiers | json | No | External identifiers attached when creating a record for matching. |
survivor_id | text | No | UUID of the surviving record (merge). Falls back to the survivor_id config. |
retired_id | text | No | UUID of the record merged into the survivor (merge). Falls back to the retired_id config. |
patient | json | No | FHIR R4 Patient resource to match (fhir_match). A FHIR Parameters resource may be supplied as 'parameters' instead. |
records | json | No | Records to create for matching (ingest). Each item is either the attribute map itself or {data, source_system, source_id, identifiers}. |
entity_name | text | No | Stable entity definition name to resolve instead of hardcoding entity_def_id: patient or clinical_act. |
entity_def_id | text | No | UUID of the entity definition, when it is already known. |
link_id | text | No | UUID of the queued POSSIBLE link a human decided on (review_link). |
decision | text | No | The human decision to record: MATCH or NOT_MATCH (review_link). |
external_reviewer_id | text | No | Id of the person who made the decision (review_link, required; "system" is refused). EMPI records it as the reviewer of record. |
external_review_id | text | No | Id of the review in which the decision was made (review_link, required). |
comment | text | No | Optional reviewer comment recorded with the decision (review_link). |
global_id | text | No | Cluster global id to read (cluster, sbr). |
input | any | No | Ordering only. The operation reads the inputs and config it needs; a value wired here is ignored. Use it to make a step run after another that it takes no data from. |
Output ports
| Name | Type | Required | Description |
|---|---|---|---|
result | json | No | Full EMPI response for the operation (match candidates, merge survivor, dedup summary, lookup records, or FHIR bundle). |
bundle | json | No | FHIR R4 Bundle of scored matches (fhir_match only). |
record_id | text | No | The record that was matched (match). |
global_id | text | No | Cluster the matched record now belongs to (match). Absent when it matched nothing and is a cluster of one. |
patient_key | text | No | The identity to scope downstream work by (match): the cluster global id, or the record id when the record matched nothing. |
record_ids | json | No | UUIDs of the records created by ingest, in input order; failures are omitted and reported in result.failed. |
links | json | No | Queued POSSIBLE links awaiting a human decision (list_possible), each carrying both records when include_records is on. |
count | number | No | Number of links on this page (list_possible). |
total | number | No | Total number of queued links matching the filter (list_possible). |
entity_def_id | text | No | Resolved entity definition UUID (entity_def). |
data | json | No | Golden record attributes for a cluster (sbr). |
Settings
Basic
| Setting | Name | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|---|
| Operation | operation | enum | Yes | match | match, ingest, deduplicate, merge, lookup, fhir_match, list_possible, review_link, cluster, sbr, entity_def | EMPI action to perform. |
| Entity | entity_name | enum | No | patient | patient, clinical_act | Stable entity definition name, resolved to its UUID at run time. Prefer this over entity_def_id: the UUID is generated per deployment when the definition is seeded, so a pipeline carrying one is portable to exactly one environment. |
| Identifier Type | identifier_type | string | No | Identifier type for lookup (e.g. MRN, SSN, DNI). Input identifier_type overrides this. | ||
| Identifier Value | identifier_value | string | No | Identifier value for lookup. Input identifier_value overrides this. |
Advanced
| Setting | Name | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|---|
| Entity Definition ID | entity_def_id | string | No | UUID of the EMPI entity definition. Overrides entity_name when both are set. | ||
| Source System | source_system | string | No | hydra-pipeline | Recorded as the source system when a record is created for matching. | |
| Survivor Record ID | survivor_id | string | No | Fallback survivor record UUID for merge when no survivor_id input is wired. | ||
| Retired Record ID | retired_id | string | No | Fallback retired record UUID for merge when no retired_id input is wired. | ||
| Link ID | link_id | string | No | Fallback queued-link UUID for review_link when no link_id input is wired. | ||
| Review Decision | decision | enum | No | MATCH, NOT_MATCH | Fallback decision for review_link when no decision input is wired. | |
| Cluster Global ID | global_id | string | No | Fallback cluster global id for cluster and sbr when no global_id input is wired. | ||
| Page | page | string | No | Queue page to read (list_possible). Defaults to the first page. | ||
| Page Size | page_size | string | No | Queue page size (list_possible), 1-100. Defaults to the service page size of 20. | ||
| Include Records | include_records | boolean | No | true | Embed both records in each queued link (list_possible), so a reviewer sees what they are deciding about without one request per record. | |
| EMPI Base URL | empi_base_url | string | No | Override the EMPI service base URL (default from EMPI_SERVICE_URL or http://empi-service:8090). |
Errors
| Code | Description |
|---|---|
EMPI_CONFIG | Required input/config for the selected operation is missing |
EMPI_REQUEST | The EMPI service returned a non-2xx status or was unreachable |
Runtime notes
- Production replacement for the in-process 'patient-matching' stub node.
- Requires a signing secret — EMPI_JWT_SECRET, or the platform JWT_SECRET_KEY / JWT_SECRET — and a pipeline org context; the node mints a short-lived service JWT scoped to the active org.
- match: pass record_id to match an existing record, or patient_data with entity_name (or entity_def_id) to create-then-match.
- match emits patient_key — the cluster global id, or the record id when the record matched nothing. Wire that into clinical-act-extract; an act must be scoped by a resolved identity, not by a source-system MRN.
- merge: survivor_id/retired_id may come from inputs or config; inputs win.
- ingest: creates records one at a time so each matches against those already ingested in the same run; a failed record is reported in result.failed and the run continues.
- list_possible: returns only pairs the thresholds could not settle. Scope it with entity_name, or the queue mixes identity pairs with clinical act pairs.
- review_link with MATCH recomputes the cluster global ids for that entity, so a timeline built afterwards reflects the decision.
- review_link requires external_reviewer_id and external_review_id: the node calls EMPI as the pipeline service, and EMPI refuses a service-applied decision that does not name the person who decided (HG-37). Prefer identity-review-queue apply, which sends both from the human review.
See Build any workflow for how to put nodes together and Ports, types and data flow for how port types connect.
Etwas unklar? Senden Sie Feedback zur Dokumentation per E-Mail..