Migration Center API

New in version 0.9.84+

The Migration Center replaces the older card-first content migration page with a wizard-driven assistant that supports import into BRM, export from BRM, site transfer, and manual advanced tools. This document explains the internal service boundaries, runtime contracts, draft persistence, hosted-package behavior, and the AJAX entry points used by the admin UI.

Scope and Positioning

The Migration Center handles three different classes of work:

• Direct current-site migration between BRM and installed WordPress-native/plugin-native content models
• Guided rebuild packages for hosted platforms such as Kajabi, Thinkific, Teachable, and Podia
• Generic CSV bundle import/export for unsupported or custom systems

Hosted packages are intentionally not modeled as guaranteed one-click native imports. The implementation and UI now describe them as guided rebuild packages because that is the truth on those platforms.

Admin Entry Point

The admin page lives at:

• src/Admin/Pages/ContentMigrationPage.php

It keeps the page slug brm_content_migration and renders the top-level tabs:

• Import Into BRM
• Export From BRM
• Site Transfer
• Advanced Tools

The page reuses existing legacy migration cards for Site Transfer and Advanced Tools, while the new assistant is driven by the Migration Center services below.

Core Service Layer

The main service cluster lives under src/Services/Migration/.

MigrationPresetRegistryService

Owns the available source/target presets, including:

• installed WordPress plugin targets
• hosted export presets
• the generic CSV bundle preset

Each preset carries a TargetCapabilityProfile plus extra metadata used by the question graph, dry-run preview, and artifact writer. Hosted presets also define:

• workflow summary
• limitations
• scope options
• bundle file lists
• platform checklist steps
• target-specific asset guidance

MigrationScanService

Builds the scan snapshot used by the wizard. It inspects:

• active plugins
• public post types and BRM structures
• taxonomies and hierarchy depth
• post_parent usage
• relationship candidates
• field availability and media usage patterns

This is what allows the wizard to skip many questions and prefer high-confidence defaults.

MigrationQuestionGraphService

Builds the actual assistant flow. The graph is answer-aware and branch-aware, which means it can:

• skip nodes that are already resolved by scan confidence or preset data
• preserve answers while the user goes back
• invalidate downstream answers when an earlier answer changes the branch
• generate hosted-package versus current-site export flows from the same top-level mode

Important runtime behavior:

• hosted export copy is intentionally framed as guided rebuild package wording
• CSV bundle flows are kept distinct from hosted package flows even though both use entry.export_target = download-package
• level-fit steps expose user-controlled omitted/mapped levels rather than forcing a hidden planner decision

MigrationTransformationPlannerService

Builds the final normalized plan after answers are complete. It is responsible for:

• source/target level shape comparison
• level omission and shift decisions
• collapse planning
• field mapping rules
• synthetic level planning where needed

The planner does not mutate content during the question flow. It only prepares the execution model.

MigrationDryRunService

Builds the review payload shown before execution. For hosted exports it returns an artifact_summary that includes:

• the package heading
• the workflow label
• the generated file list for the selected scope
• platform limitations

That summary is intentionally user-facing and should stay aligned with the actual preset metadata.

MigrationExecutionService

Owns the execution phase. Depending on the mode, it either:

• creates/updates BRM structures and items
• writes into same-site competitor/native targets
• builds a hosted/package export artifact
• produces a CSV bundle export

Hosted/package exports intentionally return a completion status that points the admin toward downloading the package and following the checklist, rather than implying remote execution inside the hosted platform.

MigrationArtifactService

Builds package outputs under uploads/brm-migrations/<run-id>/. It writes:

• hosted worksheets and manifests
• media-reference CSVs
• people CSV companions where supported
• generated HTML content files
• checklists
• manifest.json

Security/robustness details:

• artifact filenames are normalized
• directory preparation throws on failure
• writes throw explicit runtime exceptions instead of silently failing
• ZIP staging and upload analysis now guard against path traversal

MigrationUploadService

Handles uploaded ZIP/CSV/JSON files for import-side analysis. It rejects hosted manual rebuild packages as BRM import sources, because those packages are export-only and are not valid BRM restore inputs.

This distinction is important and intentional:

• Generic CSV bundles can round-trip into BRM
• Hosted guided rebuild packages cannot be imported into BRM

MigrationRunService

Owns persistence for draft and completed runs via:

• wp_brm_migration_runs
• wp_brm_migration_run_items

Draft persistence is server-side and begins as soon as the user answers the first question. That allows restore-after-close behavior without relying only on browser storage.

AJAX Surface

The admin-facing AJAX controller is:

• src/Admin/MigrationCenterService.php

It registers endpoints such as:

• brm_mc_scan
• brm_mc_get_graph
• brm_mc_validate_answers
• brm_mc_build_plan
• brm_mc_preview_plan
• brm_mc_execute_stage
• brm_mc_resume_run
• brm_mc_verify_run
• brm_mc_rollback_run
• brm_mc_download_artifact

All write-oriented actions are gated by capability checks and BRM nonce verification. The controller is intentionally thin and delegates almost everything to the service layer.

Draft Restore and Restart Contract

The assistant stores drafts as status = draft runs before execution starts. A draft includes:

• answers payload
• current node
• resolved path
• scan snapshot/hash
• selected tab/preset

On restore, the scan is refreshed. If the environment changed, only affected downstream answers are invalidated. The UI always exposes a visible restart action that clears the current draft without touching unrelated completed runs.

UI Contracts

The current UI implementation uses the shared BRM admin shell, shared checkbox markup, localized JS strings, and the new migration script:

• src/Admin/AdminAssetsSupport.php
• assets/admin/js/migration-center.js

Important front-end contracts:

• no new hardcoded English UI strings in JS
• single current-step presentation instead of a clickable step list
• single-choice steps auto-advance
• inline validation text instead of duplicated global notice spam for missing answers
• one success message, not duplicated top/bottom success rendering

Legacy Tool Boundary

The Migration Center does not replace every legacy migration implementation internally. Existing lower-level tools still live under:

• StructureMigration
• FieldMigration
• RelationshipMigration
• ExportImportMigration

Those remain available through the Advanced Tools and Site Transfer tabs. The new assistant coordinates higher-level flows without re-implementing every legacy operator.

Testing and Release Notes

The migration-center slice has targeted unit coverage across graph building, dry-run generation, artifact generation, uploads, execution, rollback, and preset metadata. Hosted export messaging was also validated against real platform constraints for Thinkific, Teachable, Podia, and Kajabi as far as those dashboards and plans allow.

Release messaging should continue to preserve one important distinction:

• same-site WordPress targets can be direct migration flows
• hosted targets should be positioned as guided rebuild package flows unless the platform actually exposes a native import path for that content type