Revised Comprehensive Migration Plan¶
Date: 2026-02-26 Status: Phase 1 + Phase 2 COMPLETE, Phase 3 revised
What Changed From Original Plan¶
The original plan was missing migration tool verification work and jumped straight to Razor views + Bootstrap 5 + NuGet RCL. The correct sequence is:
- Fix migration tool issues FIRST — ensure grid is migrated correctly
- Run fresh migration — verify all 14 datatypes + 76 content nodes
- Build Razor views to match verified migration output
- Bootstrap 5 + NuGet RCL only after project is 100% correct
Completed (Phase 1 + 2)¶
| Task | Status |
|---|---|
| Rename 4 data protection files (P0 1A) | DONE |
| Verify 3 gridElement alias alignment (P0 1C) | DONE (no renames needed) |
| Create grid_element_socialfooter.cshtml (Path B) | DONE |
| DT 1055: Create uSync DataType config | DONE |
| DT 1055: Fix articlecontrols GUID | DONE |
| Fix 5 DescendantsOrSelf build errors (loanbox files) | DONE |
| Remove duplicate headerNews.cshtml | DONE |
| MkDocs .gitignore + RESUME_PROMPT nav | DONE |
| MkDocs build verification | DONE |
| Build verification (0 errors) | DONE |
Phase 3: Migration Tool Verification (PRIORITY)¶
3A: Run Fresh Migration + Verify Grid Allowances¶
Goal: Confirm the migration tool output is 100% correct before building any more views.
Steps:
1. Run run-migrations.ps1 to execute full migration cycle
2. After migration, query the v17 DB for all BlockGrid configs
3. For each of the 14 datatypes, verify:
- All layouts created with correct area column widths
- All area wrappers have correct specifiedAllowance entries
- AllowAtRoot=true ONLY for Row Configs, false for everything else
- All content element types properly referenced
4. Check migration logs for any "Could not find element type" warnings
5. Verify DT 1055 now has a complete BlockGrid config
Verification Script:
-- Check all BlockGrid datatype configs exist
SELECT nodeId, [text] FROM umbracoDataType WHERE propertyEditorAlias = 'Umbraco.BlockGrid'
-- Verify DT 1055 has config
SELECT * FROM umbracoDataType WHERE nodeId = 1055
3B: Verify Content Migration (76 nodes with BlockGrid data)¶
- Query all content nodes that have BlockGrid property data
- Verify the JSON structure follows the 4-level hierarchy: RowConfig → Layout → AreaWrapper → Content
- Check that block element type keys in content match registered element types
- Verify settings (row settings, cell settings) are properly attached
3C: Migration Tool Improvements (double-migration-tool)¶
| Task | Priority | Description |
|---|---|---|
| Add pre-migration allowance validation | HIGH | Before building specifiedAllowance, verify all v8 editor aliases have registered element types. Fail with clear error instead of warning. |
| Add post-migration report | MEDIUM | Generate a report showing v8 allowed editors → v17 specifiedAllowance mapping per area per layout per datatype |
| Fix Nested Content warnings | LOW | 52 "missing ContentTypes array" warnings — investigate if these cause data loss |
| Verify DT 1055 content migration | HIGH | 12 content nodes need to be verified after the uSync/GUID fix |
Phase 4: Missing Razor Views (prioritized by content usage)¶
Classification of 186 Content Element Types¶
Of the 186 content element types: - 76 have matching views (exact filename match) — DONE - ~59 are nested/child types (rendered by parent, no standalone view needed) - 6 are settings types (no view needed) - ~48 need views created — this is the actual work
4A: Views for Element Types WITH Content (highest priority)¶
These element types have actual content in the DB — missing views means broken pages:
| Element Type Alias | Content Count | Has View? | Action |
|---|---|---|---|
| headingItem | 147 | YES | Done |
| grid_builtin_rte | 144 | YES | Done |
| grid_builtin_media | 47 | YES | Done |
| grid_builtin_quote | 6 | YES | Done |
| grid_builtin_embed | 2 | NO | Create or rename embedElement.cshtml |
| cTAItem | varies | NO | Create (or rename ctaElement.cshtml) |
| grid_element_cardcontrol | varies | NO | Create |
| header/headerNew/headerFull/headerNews/headerContact | varies | NO | Create (5 files) |
| blockListCallToAction | varies | NO | Create |
| mainCalculatorControls | varies | NO | Create |
| calculatorControls | varies | NO | Create |
| googleMap | varies | NO | Create |
| grid_element_largegooglemap | varies | NO (Path B has no view) | Copy gridElementLargegooglemap.cshtml |
4B: Rename "Element" Suffix Files to Serve Missing Types¶
13 orphaned *Element.cshtml files may serve as views for missing element types:
| Existing File | Possible Target Alias | Action |
|---|---|---|
| embedElement.cshtml | grid_builtin_embed | Rename/copy |
| ctaElement.cshtml | cTAItem | Rename/copy |
| heroElement.cshtml | heroItem | Already has view — verify |
| counterElement.cshtml | counter | Already has view — verify |
| headingElement.cshtml | headingItem | Already has view — verify |
| rteElement.cshtml | grid_builtin_rte | Already has view — verify |
| mediaElement.cshtml | grid_builtin_media | Already has view — verify |
| faqElement.cshtml | faqControls | Already has view — verify |
| linkListElement.cshtml | linkListControl | Already has view — verify |
| accordionButtonElement.cshtml | accordionButtonItem | May need rename |
| accordionControlsElement.cshtml | accordionControls | Already has view |
| buttonModalElement.cshtml | buttonModal | Already has view |
| imageWithLinkElement.cshtml | imageWithLink | Already has view |
4C: Missing Page Templates (12 files)¶
HIGH (4): - CustomerOnlyPage1.cshtml - MasterThirdParty.cshtml + StandardPageThirdParty.cshtml - SPALoader.cshtml
MEDIUM (4): - homeFullWidthSection.cshtml - StandardPageNewNoHeaderNoFooter.cshtml + masterNoHeaderNof.cshtml - LatestArticlesPaging.cshtml
LOW (4): - ArticleContentType2.cshtml - loanInputCTA.cshtml (page template version) - releaseNotesWidget.cshtml (page template version — partial already exists) - TokenAuthentication.cshtml
4D: Calculator Localization¶
Replace hardcoded English labels with IDictionaryService in: - 6 calculator partials - 7 JS files (use data attributes or API for translations)
4E: Other P1/P2 Fixes¶
| Task | Priority |
|---|---|
| Move API keys to appsettings.json | P2 |
| Calculator slider UI (jQuery UI range) | P2 |
| Calculator form validation | P2 |
| Orphaned element type cross-DB validation (SQL script) | P2 |
Phase 4 Progress (Current)¶
Completed in This Session¶
| Task | Status |
|---|---|
| ISiteSettingsService: Add LoanBoxesConfiguration + GoogleMapConfiguration | DONE |
| Fix 13 views using DescendantsOrSelf anti-pattern | DONE |
| 8 new component views (grid_builtin_embed, grid_element_largegooglemap, cTAItem, header, headerFull, grid_element_cardcontrol, blockListCallToAction, googleMap) | DONE |
| 9 page templates (ArticleContentType2, loanInputCTA, releaseNotesWidget, TokenAuthentication, homeFullWidthSection, SPALoader, MasterThirdParty, StandardPageThirdParty, StandardPageNewNoHeaderNoFooter) | DONE |
| masterNoHeaderNoFooter expanded from stub to full layout | DONE |
| Build verification (0 errors, 114 warnings all pre-existing) | DONE |
Remaining Phase 4¶
| Task | Priority | Status |
|---|---|---|
| CustomerOnlyPage1.cshtml page template | HIGH | IN PROGRESS (agent) |
| LatestArticlesPaging.cshtml page template | HIGH | IN PROGRESS (agent) |
| Calculator views (mainCalculatorControls, calculatorControls) | HIGH | TODO |
| Calculator localization (IDictionaryService) | MEDIUM | TODO |
| Remaining missing component views (~20-30) | MEDIUM | IN PROGRESS (agent) |
| 13 orphaned *Element.cshtml cleanup | LOW | TODO |
| Move API keys to appsettings.json | LOW | TODO |
Phase 5: Bootstrap 5 Upgrade¶
ONLY after Phases 3-4 are 100% complete and verified.
(Same as original plan Phase 4)
Phase 6: BlockPreview + ModelsBuilder¶
ONLY after Phase 5 is complete.
See PLAN-BLOCKPREVIEW-MODELSBUILDER.md for full details.
Summary: 1. Fix DataType 1816 (corrupt MediaPicker3 config) 2. Configure ModelsBuilder: SourceCodeManual → Progress.Baseline.Core/Models/ 3. Generate 455+ strongly-typed model classes 4. Install Umbraco.Community.BlockPreview v5.2.1 5. Register in Program.cs with AddBlockPreview() 6. Test all block type previews in backoffice
Effort: ~3-4.5 days
Phase 7: NuGet RCL Architecture¶
ONLY after Phase 6 is complete and regression-tested.
(Same as original plan Phase 6)
Phase 8: Final Documentation¶
(Same as original plan Phase 7)
Side Projects (Parallel)¶
A: Migration Orchestrator App¶
See PLAN-MIGRATION-ORCHESTRATOR.md for full details.
Blazor app (desktop → web) for configuring and running multiple migrations simultaneously with progress monitoring. Each project stores source/target DB connections, forms paths, and migration options.
Effort: ~5 days (Phase 1 desktop/local), +3 days (Phase 2 web publish)
B: Migration Performance Optimization¶
Current: ~30 minutes per migration. Target: <10 minutes.
See PLAN-MIGRATION-PERFORMANCE.md for analysis and optimization plan (pending performance research).
Dependency Graph (Revised)¶
Phase 3 (Migration Verify) → Phase 4 (Razor Views) → Phase 5 (BS5) → Phase 6 (BlockPreview) → Phase 7 (RCL) → Phase 8 (Docs)
↑
Side Projects (parallel): Migration Orchestrator App, Performance Optimization
Key change: Migration tool verification MUST come before building more views. We need to know the migration output is correct before we build views to match it.