Migration Center

Migration Center is used when an existing gym is moved into SquareOS from another system. It stores source-system profiles, uploaded archive files, import jobs, validation, preview, and execution status.

What this page is for

Who should use it

Owner, migration operator, platform admin

Where to find it

/admin/migration-center

Before you start

Advanced admin operations flow completion gate: migration, form, waiver, GST, GL, commission, and advanced settings are complete only when every field, action, and downstream finance or customer effect has been reviewed from the live staff-app source.
Migration Center fields are Kind, Name, Notes, Source profile, Entity type, Template key, import file, and Upload status.
Migration Center actions are Create profile, Create import job, Open, Validate, Preview, Execute, and open recent job detail.
Kind records the source platform such as FitnessForce, GymOwl, FitX, GymSales, Gymdesk, or Custom.
Name should identify the migration profile clearly, for example Northline Fitness old CRM export.
Entity type must match a supported import family: prospect/prospects, client/clients, staff, subscription/subscriptions, credit_balance/credit_balances, payment_history/payments, or retail_product_sku/product_skus.
Template key must match the adapter/template expected for the file columns. Do not guess a template when the file structure is unknown.
Supported template keys are prospects, clients, staff, subscriptions, credit_balances, payment_history, and product_skus.
Prospects required columns are full_name, email, and phone. Optional columns include alternate_phone, date_of_birth, gender, lead_source, lead_channel, client_rep_email, expected_value_minor, and note.
Clients required columns are full_name, email, phone, and home_gym_code. Optional columns include alternate_phone, date_of_birth, gender, client_rep_email, member_since, is_member, last_visit_at, and note.
Staff required columns are full_name, email, and role_code. Optional columns are phone, primary_gym_code, and access_scope.
Subscriptions required columns are client_email, plan_code, start_date, status, and home_gym_code. Optional columns include end_date, next_billing_date, billing_frequency, contract_term_months, amount_minor, autopay_enabled, and transferable.
Credit balance required columns are client_email, amount_minor, and reason. Optional columns are reference_type and reference_id.
Payment history required columns are client_email, invoice_number, payment_number, amount_minor, mode_category, and paid_at. Optional columns include payment_method_code, reference, invoice_total_minor, invoice_balance_minor, and status.
Product/SKU required columns are category_code, product_code, product_name, sku_code, sku_name, and unit_price_minor. Optional columns include product_scope, gym_code, category_name, brand_code, brand_name, product_description, barcode, cost_price_minor, opening_quantity, reorder_level, and publish_gym_codes.
Column names are normalized to lowercase snake_case during validation, but required values must still be present in each row.
Creating an import job clones the uploaded source file into the archive vault with migration_source_snapshot metadata. Keep this archive as evidence for future support and audit investigations.
Job detail shows total rows, valid, invalid, imported, failed, source file, archive snapshot, recent batches, and the first validation rows.
Validation can run asynchronously through the import worker. A job with invalid rows becomes Failed validation; a fully valid job becomes Ready.
Validate checks file structure and row eligibility before preview. Preview should be reviewed before Execute because execution writes data into the tenant.

Daily workflow

Create source profile, upload file, create import job, validate, review preview and row counts, then execute only after owner approval.
Open recent job detail after each run and check imported, failed, skipped, and warning rows before deleting old source exports.
Use migration only for bulk onboarding or correction work. Normal prospects and members should be created through People, Trials, or POS.
For the first migration from a legacy system, run a tiny sample file first and compare People, subscriptions, payments, staff, retail stock, and reports before executing a full import.
When validation fails, fix the spreadsheet values or choose the correct template instead of manually editing generated import rows.

Watch out

Never execute an import only because validation passed. Preview sample rows and confirm tenant, entity type, template, archive file, and duplicate policy.
Do not use migration to bypass normal permission, finance, or duplicate-review workflows. Migration is powerful enough to create live operational records.

Use the left menu to open related pages in Admin Settings.
Use Ask Docs for questions that are already covered in this public documentation.