Migration centre: preview, import and reconciliation

Source version and installed-release boundary

This manual covers the reviewed newer product source workflow. It requires its matching released core, additive database structure and signed modules where applicable. The separately approved licensed 1.3.8 archive can have an earlier workflow. Do not assume these screens or commands exist merely from a numeric version label, and do not copy newer source files over a signed installation. Documentation publication does not upgrade the product or enable any external account.

Business → Migration centre provides preview and append-only import for billing exports. WHMCS, ClientExec, Blesta, HostBill, WISECP, FOSSBilling, BoxBilling and Upmind have source-specific export readers; the page states exactly which collections each native reader can establish. Mapped CSV and JSON cover customers, products, services, domains, invoices, invoice items, payments/refunds and initial ticket history for these and other platforms. See source formats and field mappings.

This is an export-based migration tool. It does not copy a source database blindly, request production API credentials, execute SQL, fetch arbitrary export URLs, move funds or run hosting/registrar commands. Existing WHMCS archived imports remain accessible through WHMCS archive. The older SQL cutover scripts have a separate installation-specific preflight; this workspace never invokes their sample-removal workflow.

Prepare and preview

1. Make an export from the source installation and retain a verified backup. Keep its source IDs intact. Remove credentials, payment-card data, API tokens and password hashes; these fields are refused by the readers.
2. Download the generic JSON template or use the documented native API export wrapper. Specify a stable source_instance, such as legacy-billing-01, and retain that name for later batches. Monetary values must be exact decimal strings, not locale-formatted values or inferred currency symbols. Currency IDs need an explicit ISO code mapping when the native API omits the code.
3. Select the source format, exact destination storefront and export file. The optional CSV map uses canonical field names as keys and literal header names as values. An explicit map allows a source's custom reports to migrate collections not covered by its native reader.
4. Preview the counts, immutable saved destination, conflicts, normalized samples and reconciliation notes. Uploads are at most 10 MiB / 10,000 records, stored encrypted in private storage and readable only by their uploading administrator for 24 hours.
5. Apply the reviewed preview using the existing sensitive-admin password confirmation. No records are imported merely by opening this page or uploading a file.

CSV can contain one collection per file. Import customers and products first, then related services/domains, invoices, lines and payments, using the same platform, source instance and destination. Referenced parents may also be included in one complete JSON bundle. Prior source mappings resolve across batches only after the importer rechecks the native owner, currency, record and destination.

The optional customer mapping is {"source-customer-id":123}, where 123 is the existing native numeric customer ID. It authorizes linking to that primary customer in the selected storefront; it never updates the customer's profile, access state or password. An email collision without an explicit mapping blocks the import. Changed source records, changed destination, changed mappings and conflicting domains require review instead of overwriting existing records.

Imported state

New customer sign-in starts disabled with a new random password. Original passwords and provider credentials are not migrated; review access and use the normal password-reset process before enabling customers. New native client, service and ticket references are allocated independently, while source IDs remain in encrypted provenance.

Products remain inactive with manual fulfilment and no guessed prices or provider connection. Source service status and billing dates are retained, but automatic renewals, registrar actions and hosting mappings are disabled. The source username remains in encrypted history for deliberate server mapping. Domain ownership, dates and nameservers are retained with renewal off and no registrar selected.

Historical invoices preserve original amounts, numbers and source status in provenance, receive an independent native number and stay in legacy_review. They cannot request payment until staff reconcile the seller, lines, taxes, credits and payment allocations through the existing invoice review workflow. Historical payments are recorded as historical allocations; no charge or refund is submitted. Mismatched source totals produce reconciliation notes rather than invented balancing amounts. Negative credit-note/line amounts cannot be represented by the current unsigned native invoice-line schema and are refused, not silently discarded.

Initial ticket text, source status and creation timestamps are retained without replaying notifications. Additional messages, attachments, orders, credit ledgers, stored mandates and platform-specific configuration are outside the canonical import contract; export and reconcile those separately. Unsupported or incomplete native collections must use an explicit mapping, not a guessed schema.

Every applied run records counts and stable source-to-native mappings. Exact repeated exports are idempotent. New records are committed transactionally; conflict failures roll back the batch. A database-backed immutable source binding and row locks protect destination ownership even if the cache lock expires. Import history shows encrypted normalized source fields alongside destination IDs.

CLI

php artisan emaila:migration mapped /private/export.json --site=123
php artisan emaila:migration mapped /private/export.json --site=123 --apply --actor=456 --preview-sha=SHA_FROM_REVIEWED_PREVIEW

The first command only previews. The second requires the exact reviewed digest, an existing storefront if selected, and an active administrator. CLI imports use the same validation, source binding, transaction and automation holds as the admin page. Never commit exports, previews, database backups or credentials to the product repository.

Validation

tests/migration-source-adapters.php, tests/migration-import-invariants.php and tests/billing-migration-workspace.php use synthetic exports and isolated databases. They cover exact monetary parsing, native export limits, pagination and duplicate refusal, field mapping, source identity, cross-batch references, destination ownership, concurrency invariants, encrypted previews/history, native record state, replay safety, source HTML escaping and administrator permissions. No live migration or provider request is part of deployment.