Patient Service

The PatientService is responsible for fetching existing demographics records of a user, as well as creating new demographics records. Before scheduling a visit or appointment, you must ensure that the patient record exists in the required EHR system (detailed below).

DexCare Patients only

The following document describes getting and creating patients on an EHR System through DexCare. If your system does not use DexCare for that, this document is not relevant. We support creating visits through MRN/EPI, but not loading or creating.

Finding or Creating Patients Overview

The DexCare SDK expects your app to tell us exactly where to lookup or create a patient record. The SDK will know where to lookup or create a patient record based on an EHR System name provided by your app.

For Retail, each clinic is associated with an EHR system. The patient record must already exist in the Clinic’s EHR system before scheduling an appointment at that clinic.

For Virtual, it’s slightly trickier. The EHR system name can either be hardcoded in your app (in the case where your health system has a single EHR system), or it can determined based upon the user’s address and visit state, using an SDK method PatientService.getCatchmentArea. See the catchment areas section for details.

Patient records will be created in EPIC only when a fuzzy lookup fails. If the patient record already exists in EPIC, the DexCare SDK will not update it if any specified demographic values differ.

The PatientService.findOrCreatePatient methods assume the patient being created is the app user, the person signed in to the app. When a PatientService.findOrCreatePatient method determines a new patient record needs to be created in EPIC, the new record is automatically linked to the current authenticated user (and therefore returned in all future getPatient calls for the user).

In the case where the person signed in to the app is not scheduling an appointment or visit for themselves, a findOrCreateDependentPatient method should be called instead. This new record will not be linked to the current authenticated user.

Gender

The DexCareSDK contains a Gender enum of the possible genders that are accepted by Epic. Please note: Your Epic setup, may NOT support all genders as defined in the SDK and it is up to you to only allow the Gender input that your Epic instance allows.

Catchment Areas

When the required EHR system is not already known to your application (for example, in Virtual), you can call PatientService.getCatchmentArea(visitState, residenceState, residenceZipCode, brand) to retrieve the associated EHR System of where the user is located.

visitState - Which for the state in which the visit will take place
residenceState - Which state the patient resides
residenceZipCode - Zip code of the patient
brand - Provided by your DexCare Contact

Returned will be a CatchmentArea object which will have:

ehrSystem - The EHR System name for the catchment area, used in subsequent calls.
departmentId - A Unique identifier of the virtual department in which the visit will take place.

iOS
Android

let dexcareSDK = DexcareSDK(configuration: ...)

dexcareSDK.patientService.getCatchmentArea(
    visitState: visitState,
    residenceState: address.state,
    residenceZipCode: address.postalCode,
    brand: brand,
    success: { catchmentArea in
       // save catchmentArea for later calls
   },
   failure: { error in
       // error getting catchment area. Most likely an invalid state, or zip code.
     }
)
// Swift Concurrency
do {
    let catchmentArea = try dexcareSDK.patientService.getCatchmentArea(
    visitState: visitState,
    residenceState: address.state,
    residenceZipCode: address.postalCode,
    brand: brand)
} catch { error in
    // error getting catchment area. Most likely an invalid state, or zip code.
}

DexCareSDK.patientService.getCatchmentArea(
        visitState = "WA",
        residenceState = "WA",
        residenceZipCode = "98101",
        brand = "brand"
    ).subscribe({ catchmentArea ->
        // save catchmentArea for later calls
    }, { error ->
        // handle the error, show an error dialog, log the error, etc.
    })

Calling the findOrCreatePatient APIs

First, a PatientDemographics object needs to be constructed. This can be created manually, by showing the app user a form with all required information, or by re-using an existing one as returned by PatientService.getPatient().

IMPORTANT NOTE

The DexCare platform has no control over what already exists in Epic, nor what is created in Epic outside DexCare. Other platforms that integrate with Epic may not have the same level of high standards for data curation that DexCare does. This means that existing `PatientDemographics` returned by `PatientService.getPatient()` may contain incomplete, missing or invalid data.

In this case, it is the responsibility of the app to obtain the missing information from the patient, and pass in the completed PatientDemographics object to the SDK. All non-nullable and non-optional parameters are required and must contain non-empty, valid data. If the results of PatientService.getPatient() return invalid data for optional parameters, you must also obtain new information from the patient for said optional parameters.

For data validation, the DexCare SDKs check the formatting of phone numbers, emails, and postal/zip codes. The SDK provides three helper classes: PhoneValidator, EmailValidator, and ZipCodeValidator. These classes are the same ones used internally by the SDK to validate demographics data. Your app can use these to confirm an input will be accepted by the SDK. Additional information about these classes can be found in the SDK API documentation.

Once you have the PatientDemographics object with completed information, simply pass it in to one of the findOrCreatePatient methods.

iOS
Android

let dexcareSDK = DexcareSDK(configuration: ...)

dexcareSDK.patientService.findOrCreatePatient(
    inEhrSystem: catchmentArea.ehrSystem, // ehrSystem set manually or loaded via the `PatientService.getCatchmentArea`
    patientDemographics: patientDemographics, // A created `PatientDemographics` object
    success: { dexcarePatient in
      // returned is a full `DexcarePatient` object
    },
    failure: { error in
       print("FAILED TO CREATE PATIENT - \(error.localizedDescription)")    
    }
)

// Swift Concurrency
do {
    let dexcarePatient = try dexcareSDK.patientService.findOrCreatePatient(
    inEhrSystem: catchmentArea.ehrSystem, // ehrSystem set manually or loaded via the `PatientService.getCatchmentArea`
    patientDemographics: patientDemographics)
} catch { error in 
    print("FAILED TO CREATE PATIENT - \(error.localizedDescription)")    
}

DexCareSDK.patientService.findOrCreatePatient(
        ehrSystem = "some.predetermined.ehr.system", // ehrSystem set manually or loaded via the `PatientService.getCatchmentArea`
        patientDemographics = patientDemographics // A created `PatientDemographics` object
    ).subscribe({ dexCarePatient ->
        // the most up-to-date copy of the DexCarePatient is always returned, so there's no need to do a getPatient() afterwards
    }, { error ->
        // handle the error, show an error dialog, log the error, etc.
    })

Creating Dependent Patients

A dependent patient should be created when the current signed-in app user is booking a visit for someone else. Creating a dependent patient means that the signed in app user will not be the one receiving care for this visit.

Similarly to the findOrCreatePatient call, you create a dependent patient by calling PatientService.findOrCreateDependentPatient

NOTE: The dependent patient’s demographics will never be linked to the current app user’s demographics, and so you should keep track of the DexcarePatient object that is returned in findOrCreateDependentPatient separately.

iOS
Android

let dexcareSDK = DexcareSDK(configuration: ...)

dexcareSDK.patientService.findOrCreateDependentPatient(
    inEhrSystem: catchmentArea.ehrSystem, // ehrSystem set manually or loaded via the `PatientService.getCatchmentArea`
    dependentPatientDemographics: dependentPatientDemographics, // A created `PatientDemographics` object associated with the dependent
    success: { dexcarePatient in
      // returned is a full `DexcarePatient` object for the dependent
    },
    failure: { error in
       print("FAILED TO CREATE DEPENDENT PATIENT - \(error.localizedDescription)")    
    }
)

// Swift Concurrency
do {
    let dexcarePatient = try dexcareSDK.patientService.findOrCreateDependentPatient(
    inEhrSystem: catchmentArea.ehrSystem, // ehrSystem set manually or loaded via the `PatientService.getCatchmentArea`
    dependentPatientDemographics: dependentPatientDemographics) // A created `PatientDemographics` object associated with the dependent
} catch { error in 
    print("FAILED TO CREATE DEPENDENT PATIENT - \(error.localizedDescription)")    
}

DexCareSDK.patientService.findOrCreateDependentPatient(
        ehrSystem = "some.predetermined.ehr.system", // ehrSystem set manually or loaded via the `PatientService.getCatchmentArea`
        patientDemographics = patientDemographics // A created `PatientDemographics` object
    ).subscribe({ dexCarePatient ->
        // the most up-to-date copy of the DexCarePatient is always returned, so there's no need to do a getPatient() afterwards
    }, { error ->
        // handle the error, show an error dialog, log the error, etc.
    })

Get Patient

PatientService.getPatient() can be used to fetch the current authenticated user’s demographics. It is recommended to call this method from your application immediately after signing in.

Returned is a DexCarePatient object, containing:

patientGuid - a unique guid assigned to each patient
demographicLinks - an array of PatientDemographics objects that will give all demographics for every EHR System.

In systems with only one EHR System, this will only be a single item in the array. With systems with multiple EHR Systems, the array of PatientDemographics will contain a separate item for each EHR system, if one exists. `PatientDemographics.ehrSystemName