Patient Upload Wizard Documentation
The Patient Upload Wizard helps practices import patient demographic data in a guided, step-by-step process. It is designed to reduce manual entry, improve consistency, and give users visibility into data issues before records are created or updated. The wizard follows the same structured flow as the Charge Upload Wizard, making it easier for teams already familiar with that experience to adopt and use.
Key Changes
- Structured 5-Step Wizard Workflow: Replaces the legacy import in Patient Master with a standardized 5-step flow (Upload → Map Fields → Validation Summary → Data Grid Review → Completion), matching the UI and UX of the Charge Upload Wizard.
-
Standardized Columnar Template & Flexible Uploads: Replaces the legacy row-wise structure with an industry-standard columnar format – allowing multiple insurance levels (Primary, Secondary, Tertiary) and guarantor details to exist in dedicated columns on a single patient row rather than requiring repeated rows per patient—alongside downloadable PMS-aligned templates and CSV/Excel (.xlsx) drag-and-drop support.
- Automated & Guided Field Mapping: Automatically maps columns when headers match PMS fields, enforces mandatory fields (first name, last name, dob, gender), and provides a toggle to view and remap unmapped fields.
- Pre-Import Validation & Issue Breakdown: Evaluates records before import and groups them into color-coded categories (Success, Alerts, Warnings, and Errors/Excluded), with an exportable Excel report detailing row-by-row issues.
- Pre-Approval Data Grid & Record Handling: Provides an interactive preview grid to filter and review patient data prior to import, automatically routing valid records to create new profiles or update existing ones (including multi-row grouping for insurances and guarantors).
What this feature is for
Use the Patient Upload Wizard when you need to create new patient records or update existing ones in bulk from a CSV or Excel file. The wizard supports field mapping, validation review, approval, and final processing.
How the Patient Upload Wizard works
The wizard uses a 5-step process so users can upload a file, map fields, review validation results, confirm the data, and complete the import with confidence.
| Step | Purpose | What the user does |
| 1 | Upload file and access resources | Select a CSV or Excel file and review template/help resources before continuing. |
| 2 | Map file columns to system fields | Confirm or adjust field mapping between the uploaded file and PracticeSuite patient fields. |
| 3 | Review validation summary | See which records are ready, which have warnings or alerts, and which are excluded due to errors. |
| 4 | Review validated data and approve | Inspect the processed rows in a grid view and approve the upload. |
| 5 | Complete the upload | Review the final outcome, including created, updated, and failed counts. |
Step 1: Upload file and resources
Users start by uploading a patient demographic file in CSV or Excel (.xlsx) format. The upload area supports click-to-browse behavior, and the wizard also provides downloadable sample templates to help users prepare the file correctly.
- Supported file types: CSV and Excel (.xlsx)
- Templates are available for download from the wizard
- The file must contain data rows; empty or corrupted files will not proceed
- The upload opens in a separate window from Patient Master for a focused workflow
Best practice: Use the provided template whenever possible. The template headers are aligned to the system field names so that auto-mapping works more reliably in the next step.
Step 2: Field mapping
After upload, the wizard displays the available patient fields and maps uploaded columns to the corresponding PracticeSuite fields. If a file column name matches a system field name, the wizard attempts to auto-map it. Users can review the mapping, update it if needed, and continue only after all mandatory fields are mapped.
Mandatory fields: The following fields are required for processing: first_name, last_name, dob & gender. These fields are required because they are essential for identifying the patient and determining whether the row should create a new patient or update an existing one.
Mandatory Fields for Insurance Patients: Clarifying that insurance name, and subscriber id are required for proper insurance linkage. Please note if any of the required insurance information is missing, the system will drop the patient from insurance to cash.
Common fields that may be mapped: The wizard supports a broad set of patient demographic and related fields, including patient identifiers, contact information, guarantor details, insurance details, provider references, and demographic classifications such as race, ethnicity, language, and marital status.
Step 3: Validation summary
Once mapping is complete, the system runs pre-validations and groups the uploaded rows into categories so users can understand what will happen before approving the import.
| Category | Meaning | Will the row import? |
| Success | The row is valid and ready to be processed as a new patient or an update to an existing patient. | Yes |
| Warning | The row has a non-blocking issue, usually related to format, reasonableness, or lookup value quality. | Yes |
| Alert | The row has a linked-data issue, such as a missing related record, but the patient can still be created or updated. | Yes, with limitation |
| Error | The row has a blocking issue and is excluded from processing until corrected. | No |
Success: Success means the record is acceptable for import. A successful row may represent either a new patient that will be created, or an existing patient that will be updated. If a file is uploaded again with records that already exist, the wizard treats those rows as updates rather than creating duplicate profiles.
Warnings: Warnings indicate that the row can still be imported, but some values may be incorrectly formatted, unusual, or not aligned with expected lookup values. Typical warning scenarios include invalid state abbreviations, ZIP code formats, email formats, phone number formats, SSN formats, or other values (Race, Ethnicity, Language, Marital Status) that do not match Practice Options.
Alerts: Alerts indicate that the patient row can still be processed, but a related reference could not be fully linked during the upload. Typical alert scenarios include insurance names not found or inactive in Insurance Master, or Provider NPIs not found or inactive in Provider Master.
Errors: Errors are blocking validations. Rows with errors are excluded from the upload and must be corrected before they can be processed. Typical error scenarios include missing headers, invalid gender codes, or potential duplicates detected where first name + last name + DOB matches an existing patient and no MR Number is provided.
Validation message logic: Each validation includes both a message and a suggestion. Suggestion guidance appears through the information icon in the wizard so users can understand the issue without leaving the screen.
| Validation type | What it tells the user | Typical next action |
| Error | This row cannot be processed. | Fix the file and re-upload. |
| Warning | This row can be processed, but the value may be incorrect or nonstandard. | Review the source data or lookup setup. |
| Alert | This row can be processed, but some linked data could not be fully assigned. | Complete the missing association after import. |
Step 4: Review data and approve
Before final processing, the wizard presents the validated rows in a review grid. This gives users a final opportunity to inspect the data and understand how each row will be treated. Users can review records by category, and warning/alert indicators help highlight rows that need attention.
Step 5: Complete the upload
After approval, the wizard processes the batch and shows the final result. The completion summary identifies how many records were processed, created, updated, or failed.
How duplicate handling works
The wizard does not blindly create a new patient for every row. It uses key patient details to identify possible duplicates and determine whether a row should create or update. If the row matches an existing patient by first name, last name, and DOB but no MR Number is provided, the system raises an error to avoid creating a duplicate patient.
How to prepare a clean upload file
- Use the downloadable template whenever possible.
- Make sure first_name, last_name, dob and Gender are populated.
- Use standard formats for state, ZIP, phone, email, and SSN values.
- Verify Race, Ethnicity, Language, Marital Status values against Practice Options.
- Include the MR Number when updating existing patients to avoid duplicate-related errors.
Summary
The Patient Upload Wizard is more than a file import tool. It is a controlled patient onboarding and update process with built-in validation logic. Its purpose is to help users import patient data faster while preserving data quality, preventing duplicates, and clearly showing which issues must be corrected versus which can be reviewed after import.