UiPath Documentation
activities
latest
false
Integration Service activities

Finding a patient

Choosing between Patient.$match and List Records for Epic FHIR, with Epic's minimum data set requirements and the rules for identifier systems.

Most Epic FHIR activities need a patient's FHIR ID before they can return anything. Two activities resolve a person to that ID, and they answer different questions: Patient.$match identifies one specific person, and List Records (selecting the Patient resource) retrieves everyone meeting a set of criteria.

Warning:

Choosing the right activity is a patient-safety matter. Epic states: "Improper use of Patient.Search could lead to patient safety concerns such as reading and writing data using the wrong patient record." Patient.$match identifies one specific person and List Records (selecting the Patient resource) retrieves a list, so taking the first result from a search and treating it as the patient is the mistake Epic warns against.

You haveUse
A FHIR IDGet Record. No matching is needed.
A medical record number (MRN) or other identifierPatient.$match with Identifier Value and Identifier System
Demographics for one specific personPatient.$match
Criteria describing a group of peopleList Records (selecting the Patient resource)

The minimum data set​

Epic requires a minimum data set before it will return a patient, and each Epic organization configures its own. By default, one of the following is required:

  • An identifier on its own, such as a FHIR ID, National ID or MRN
  • Given Name, Family Name and Date of Birth
  • Given Name, Family Name, Legal Sex and either Phone or Email

These are defaults rather than fixed rules, and your organization may accept less or require more. Neither Patient.$match nor List Records (selecting the Patient resource) enforces a combination.

A client-side check would reject requests that a less restrictive organization would answer, and would still pass requests that a stricter organization refuses. The connector forwards every field you supply and lets your Epic instance decide. Your Epic contact can confirm your organization's minimum data set, which is worth establishing before you design a workflow around it.

Supplying more detail measurably improves results. In testing against a live record, Given Name, Family Name, birth date and legal sex returned 59013. The same request with an email address added, or with a complete address added, returned a confident match. A partial address consisting of city and state alone was not sufficient.

Searching for patients​

See Epic's Patient.Search (Demographics) (R4) specification. Three behaviors are worth noting:

  • Name matching is not exact. Epic matches family and given against exact, phonetic and alias names, so a search for given=Jon may legitimately return a patient named Jonathan. This is Epic behavior and cannot be disabled.
  • Three parameters require a companion. own-prefix, partner-name and partner-prefix each require own-name. Used alone, they return no results rather than an error.
  • Merged patients affect stored IDs. When two patient records are merged, the source patient's FHIR ID becomes invalid and returns 404. A FHIR ID cached by your automation can therefore become stale.

Identifier systems​

The identifier search parameter takes the form {system|}code, and the system value is specific to your organization. Epic's ID Types for APIs documentation states that "this system value will differ in each customer environment." On Patient.$match, the system and the value are separate fields, Identifier System and Identifier Value.

A system object identifier (OID) copied from Epic's documentation, from a sandbox, or from another health system will not work in your environment. Your Epic technical contact can supply the OID that corresponds to your organization's MRN, which is a per-connection configuration value.

Note:

Of the identifiers on a patient record, MRN is normally the one to search on. EPI, EPIC, INTERNAL and WPRINTERNAL are Epic-internal keys.

  • The minimum data set​
  • Searching for patients​
  • Identifier systems​

Was this page helpful?

Connect

Need help? Support

Want to learn? UiPath Academy

Have questions? UiPath Forum

Stay updated