Medical Record Migration Wizard
The Medical Record Migration Wizard guides administrators through migrating existing form data into structured guest medical records. Use this wizard when your organization is transitioning intake form data into the Medical Record module, ensuring a controlled and verifiable process before committing records at scale.
Audience: Organization administrators responsible for clinical data configuration and guest record management.
On this page
Before you begin
Availability: The Medical Record Migration Wizard is available only when the guest medical record migration setting is enabled for your organization. This setting is nested under the guest medical records setting and is hidden while that parent setting is off β guest medical records must be enabled before migration can be enabled. The migration setting is configured by Zenoti staff only. Contact your Zenoti representative to have it activated.
- Your organization must have the Medical Record module active and guest medical records enabled.
- At least one form must exist in your organization's form library that contains fields eligible for migration.
- Verify that the target Medical Record categories you intend to populate β Allergies, Medications, Medical History, Health & Lifestyle, Vitals, and Critical Alerts β are configured for your organization before running a full migration. Family History is a sub-section nested within Medical History, not a separate top-level category.
- Review all source forms for data quality issues (blank required fields, inconsistent values) before beginning.
- Inform affected staff that background migration processing occurs during your organization's maintenance window, not immediately when you initiate the run.
Permission: Creating a migration requires the Add permission on medical record data. Reviewing mappings, running a test migration, and starting a full run require the Edit permission on medical record data.
Important: A form already mapped in a previous migration appears in the form list marked Already mapped and cannot be selected again for a new migration.
Steps
The wizard presents exactly five ordered steps. You must complete each step before advancing to the next. The wizard is accessible at Configuration > Clinical setup > Medical Record β you remain within the Configuration area throughout. The steps are:
- Select forms
- Review mapping
- Test migration
- Update form
- Run migration
You can save your work at any point using Save as draft and return to the same migration later from the Medical Record setup step. The wizard resumes from where you left off.
Step 1: Select forms
Select the Configuration icon in the left icon rail.
Navigate to Configuration > Clinical setup > Medical Record.
Select the Migrate existing data step in the Medical Record setup stepper. This step appears only when the migration capability is enabled for your organization.
On the Select forms to migrate to medical records (upto 25 forms) screen, review the list of forms eligible for migration.
Note: Forms already mapped in another migration are shown with an Already mapped badge and cannot be selected.
Select one or more forms to migrate. You can select a maximum of 25 forms per migration. If you attempt to select more than 25, the wizard rejects the selection.
Select Next to proceed to the Review mapping step.
Tip: If a form you expect to see does not appear in the list, it may not contain fields that map to any Medical Record category. Review the form's field definitions before returning to this step.
Step 2: Review mapping
The mapping step is titled Review mapping in the wizard.
The wizard proposes mappings automatically and marks each AI-suggested mapping in the list. Review every suggestion.
Important: You must review or discard every AI-suggested mapping before the step can be completed. The wizard prevents you from advancing while unreviewed suggestions remain. To discard all AI suggestions at once, select Discard AI Mappings.
The guidance on this step reads: "Please map only medically relevant fields." Fields with no medical meaning β for example, a field that captures a guest's preferred appointment time β should be left unmapped rather than assigned to an approximate target category.
For each form field, assign it to one of the following Medical Record entity types:
- Allergy
- Health & Lifestyle
- Medical History
- Medication
- Vital
- Notes (a matching notes target is available for each entity type listed above)
Mapping is supported at the individual field level or at the individual option level within a field.
Note: The entity types available for a field depend on the field's own type. Text and text-area fields can be mapped to any entity type. Radio, dropdown, and check-box fields cannot be mapped to Health & Lifestyle or Notes entity types.
When all relevant fields are mapped and all AI suggestions have been reviewed or discarded, select Next to proceed to the Test migration step.
Worked example
Suppose you are migrating an intake form with fields named "Known allergies" (text), "Current medications" (text), "Smoking habits" (radio: Yes / No), and "Blood pressure (last reading)" (text). You map "Known allergies" to Allergy, "Current medications" to Medication, and "Blood pressure" to Vital. For "Smoking habits," because it is a radio field, Health & Lifestyle is not available β you leave it unmapped, as it has no direct medical record equivalent in the available entity types. The wizard allows you to proceed.
Step 3: Test migration
The test migration lets you validate your field mappings against real guest data before committing to a full run.
On the Test migration step, the wizard displays the instruction: "Please select up to 10 guests to perform a test migration and verify the data mapping."
Select up to 10 guests. The wizard rejects a request for more than 10 guests.
Select Perform test migration to begin the test.
After the test completes, open the Medical Record tab on each test guest's profile and verify that the migrated values appear correctly and are assigned to the right categories.
Confirm you have verified the migrated data by selecting the verification checkbox on this step. The Continue button remains disabled until you do so.
Note: If the mappings are not correct after reviewing the test results, select Back to review mapping to return to the mapping step. Returning to the mapping step rolls back all data written by the test migration β no test data remains in the guest records. You can then correct the mappings and re-run the test as many times as needed.
Once you have confirmed the data looks correct, select Continue to proceed to the Update form step.
Step 4: Update form
- The wizard displays the notice: "All the forms here will stay in the draft state until you review and publish them by visiting the form."
- For each form listed, select View form to open it. Review the form in its migrated state.
- When you are satisfied with a form's content, publish it. The form remains in draft until you explicitly publish it.
- After reviewing and publishing all forms, return to the wizard and select Next to proceed to the Run migration step.
Note: You are not required to publish all forms before advancing. Unpublished forms remain in draft and will not affect the migration run itself. However, publishing ensures the updated form definitions are available for future use.
Step 5: Run migration
On the Run migration step, the wizard displays the following warning:
"Export all data from your selected forms to Medical Records for all patients. Once initiated, it can't be terminated in between. Please ensure that your mappings are correct."
Review this warning carefully. The full migration covers all guests for the selected forms and cannot be stopped once it has started.
When you are ready, start the migration.
Important: Starting the run locks the migration. Mappings cannot be edited after the run is started.
The migration is carried out by a scheduled background job that runs during your organization's maintenance window. The job does not begin the moment you start it β progress appears over time as the job processes records during the designated window.
Note: Guests who already have data in their Medical Record are skipped automatically. The migration does not overwrite or replace data already present in a guest's medical record.
You do not need to keep the page open. The job runs independently in the background. Return to the Migration > Migrate existing data step at any time to check progress.
Monitor the migration run
Once the migration is running, you can check its status from the migration step in the Medical Record setup stepper. The following statuses may appear:
| Status | Meaning |
|---|---|
| Queued | The job is waiting for the next maintenance window to begin. |
| In progress | The job is actively processing records during the current maintenance window. |
| Completed | All eligible records have been processed. |
| Failed | The job encountered an error that stopped processing. |
If the job reaches its execution time limit within a maintenance window, it pauses automatically and resumes from the last unprocessed record on the next scheduled run. This pause-and-resume behavior is automatic β there are no administrator controls to pause, resume, or skip the job manually.
Tips
- Run the test migration more than once if you make corrections to your mappings. Each test run reflects the current mapping state, and returning to the mapping step rolls back test data, so re-testing after corrections confirms the fix worked before committing the full run.
- Schedule large migrations with the maintenance window in mind. Because the job runs during your organization's maintenance window and not on demand, initiate the Run migration step so the job is queued ahead of the next window. Check the migration status the following morning.
- Map only medically relevant fields. The wizard guidance on the mapping step states this explicitly. Mapping non-clinical fields to approximate medical categories produces noise in guest Medical Records and complicates future clinical use.
- Verify target category configuration before migrating. If a Medical Record category β for example, Vitals β is not yet configured for your organization, fields mapped to that category will not migrate correctly. Confirm all six categories are active before you proceed past the test migration step.
- Check field types in the source form. Text and text-area fields support all entity type targets. Radio, dropdown, and check-box fields cannot map to Health & Lifestyle or Notes. If a field's type limits your mapping options, consider whether updating the field type in the Update form step is appropriate before running the full migration.
Troubleshooting
The Migrate existing data step does not appear in Configuration > Clinical setup > Medical Record.
The step appears only when the migration capability is enabled for your organization, and only when the parent guest medical records setting is also on. If the step is absent, one of these settings is off. The migration setting is configured by Zenoti staff only β contact your Zenoti representative to request enablement. If guest medical records themselves are not enabled, that must be addressed first.
A form I expected to see is not in the Select forms list.
Only forms with fields compatible with Medical Record categories appear in the list. Forms already mapped in a previous migration are shown as Already mapped and cannot be reselected. If a form is neither listed nor marked already mapped, its fields may not be recognized as compatible. Review the form's field definitions and ensure they align with the target entity types. If the form was recently updated, allow a few moments for changes to take effect and then refresh the wizard.
The wizard prevents me from advancing past Review mapping.
The wizard requires that every AI-suggested mapping be reviewed or discarded before you can proceed. Look for entries in the mapping list marked with the AI-suggested badge. Either confirm each suggestion or select Discard AI Mappings to remove all unreviewed suggestions at once. Once no unreviewed suggestions remain, the Next button becomes available.
The test migration completed but I need to change the mappings.
Select Back to review mapping on the Test migration step. This returns you to the mapping step and automatically rolls back all data written during the test run β no test data remains in guest records. Correct your mappings and run the test again. You can repeat this cycle as many times as needed before proceeding.
The background migration job status shows Failed.
A failed status means the job encountered an error it could not recover from automatically. Steps to investigate:
- Navigate to the migration wizard status screen and check the migration status.
- Review the Errors encountered column for details about which records failed and why.
- If the error affects specific records, correct the underlying data and contact your Zenoti representative about re-running the wizard for those records.
- If the error is systemic β affecting a large number of records with the same error message β contact your Zenoti representative with the error details from the migration status screen.
The migration job is taking longer than expected.
The migration job runs only during your organization's maintenance window and pauses automatically if it reaches its execution time limit. It resumes from the last unprocessed record on the next scheduled run. This is expected behavior for large data sets. Check the status screen again after the next maintenance window. If the status has not advanced over multiple windows, contact your Zenoti representative.