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).

Finding or Creating Patients Overview

As of SDK 4.x, 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.

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.
  • 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.
         }
    )
    
  • DexCareSDK.patientService.getCatchmentArea(
            "WA",
            "WA",
            "98101",
            "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.

  • 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)")    
        }
    )
    
  • DexCareSDK.patientService.findOrCreatePatient(
            "some.predetermined.ehr.system",
            patientDemographics
        ).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.

  • 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)")    
        }
    )
    
  • DexCareSDK.patientService.findOrCreateDependentPatient(
            "some.predetermined.ehr.system",
            patientDemographics
        ).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.ehr​System​Name shows which EHR System the demographic is in.

Logging in with MyChart

Currently supported is the ability to log in with your MyChart credentials. When that happens, the DexCare system will link a PatientDemographics record for the corresponding MyChart information for an EHR System. An existing DexCarePatient must already exist and be logged in. ie you must call DexcareSDK.signIn(accessToken)

If a DexCarePatient is already linked, the SDK will return the existing DexCarePatient object. An EHR System is also required. This should be set to the EHR System of the current MyChart Epic EHR System.

  • let dexcareSDK = DexcareSDK(configuration: ...)
    dexcareSDK.patientService.createPatientWithMyChart(
      myChartUserName: "mychartEmailOrUserName",
      myChartPassword: "mychartPassword",
      ehrSystem: "predetermined.ehr.system.name",
      success: { patient in
          print("SUCCESSFULLY linked Patient through MyChart")
      }, failure: { error in
          print("FAILED linking patient through mychart - \(error.localizedDescription)")    
      })
    
  • DexCareSDK.patientService.createPatientWithMyChart(
            "mychartEmailOrUserName",
            "mychartPassword",
            "predetermined.ehr.system.name"
        ).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.
        })