Zum Hauptinhalt springen

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​

NameTypeRequiredDescription
patient_datajsonNoDemographics of the patient to match/create (match). Ignored when record_id is set.
record_idtextNoUUID of an existing EMPI record to match (match).
identifiersjsonNoExternal identifiers attached when creating a record for matching.
survivor_idtextNoUUID of the surviving record (merge). Falls back to the survivor_id config.
retired_idtextNoUUID of the record merged into the survivor (merge). Falls back to the retired_id config.
patientjsonNoFHIR R4 Patient resource to match (fhir_match). A FHIR Parameters resource may be supplied as 'parameters' instead.
recordsjsonNoRecords to create for matching (ingest). Each item is either the attribute map itself or {data, source_system, source_id, identifiers}.
entity_nametextNoStable entity definition name to resolve instead of hardcoding entity_def_id: patient or clinical_act.
entity_def_idtextNoUUID of the entity definition, when it is already known.
link_idtextNoUUID of the queued POSSIBLE link a human decided on (review_link).
decisiontextNoThe human decision to record: MATCH or NOT_MATCH (review_link).
external_reviewer_idtextNoId of the person who made the decision (review_link, required; "system" is refused). EMPI records it as the reviewer of record.
external_review_idtextNoId of the review in which the decision was made (review_link, required).
commenttextNoOptional reviewer comment recorded with the decision (review_link).
global_idtextNoCluster global id to read (cluster, sbr).
inputanyNoOrdering 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​

NameTypeRequiredDescription
resultjsonNoFull EMPI response for the operation (match candidates, merge survivor, dedup summary, lookup records, or FHIR bundle).
bundlejsonNoFHIR R4 Bundle of scored matches (fhir_match only).
record_idtextNoThe record that was matched (match).
global_idtextNoCluster the matched record now belongs to (match). Absent when it matched nothing and is a cluster of one.
patient_keytextNoThe identity to scope downstream work by (match): the cluster global id, or the record id when the record matched nothing.
record_idsjsonNoUUIDs of the records created by ingest, in input order; failures are omitted and reported in result.failed.
linksjsonNoQueued POSSIBLE links awaiting a human decision (list_possible), each carrying both records when include_records is on.
countnumberNoNumber of links on this page (list_possible).
totalnumberNoTotal number of queued links matching the filter (list_possible).
entity_def_idtextNoResolved entity definition UUID (entity_def).
datajsonNoGolden record attributes for a cluster (sbr).

Settings​

Basic​

SettingNameTypeRequiredDefaultAllowed valuesDescription
OperationoperationenumYesmatchmatch, ingest, deduplicate, merge, lookup, fhir_match, list_possible, review_link, cluster, sbr, entity_defEMPI action to perform.
Entityentity_nameenumNopatientpatient, clinical_actStable 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 Typeidentifier_typestringNoIdentifier type for lookup (e.g. MRN, SSN, DNI). Input identifier_type overrides this.
Identifier Valueidentifier_valuestringNoIdentifier value for lookup. Input identifier_value overrides this.

Advanced​

SettingNameTypeRequiredDefaultAllowed valuesDescription
Entity Definition IDentity_def_idstringNoUUID of the EMPI entity definition. Overrides entity_name when both are set.
Source Systemsource_systemstringNohydra-pipelineRecorded as the source system when a record is created for matching.
Survivor Record IDsurvivor_idstringNoFallback survivor record UUID for merge when no survivor_id input is wired.
Retired Record IDretired_idstringNoFallback retired record UUID for merge when no retired_id input is wired.
Link IDlink_idstringNoFallback queued-link UUID for review_link when no link_id input is wired.
Review DecisiondecisionenumNoMATCH, NOT_MATCHFallback decision for review_link when no decision input is wired.
Cluster Global IDglobal_idstringNoFallback cluster global id for cluster and sbr when no global_id input is wired.
PagepagestringNoQueue page to read (list_possible). Defaults to the first page.
Page Sizepage_sizestringNoQueue page size (list_possible), 1-100. Defaults to the service page size of 20.
Include Recordsinclude_recordsbooleanNotrueEmbed both records in each queued link (list_possible), so a reviewer sees what they are deciding about without one request per record.
EMPI Base URLempi_base_urlstringNoOverride the EMPI service base URL (default from EMPI_SERVICE_URL or http://empi-service:8090).

Errors​

CodeDescription
EMPI_CONFIGRequired input/config for the selected operation is missing
EMPI_REQUESTThe 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..