Migrate Content Eval

Migration Evaluation

Gathers data from three sources, evaluates migration results across 12 categories, generates an HTML report, and routes the user to next steps:

1. Log analysis — what the tool attempted and reported (parse script → YAML)
2. Database verification — actual state in KX13 and XbyK (SQL queries)
3. Plan cross-reference — expected vs actual (migration plan detail)
4. HTML report — self-contained report with remediation guidance
5. Console summary — prioritized action items and next-step routing

Does NOT validate configuration — that is handled upstream by migrate-content-appsettings and migrate-content-run skills before migration runs.

Prerequisites

1. At least one migration run completed
2. Protocol log (protocol*.txt) and console log (migration-run*.log) in the directory from Settings.MigrationProtocolPath
3. Migration plan detail markdown file
4. sqlcmd CLI available with network access to both databases
5. appsettings.json with connection strings

Workflow

Phase 0: Resolve Inputs

1. Migration plan detail: Use the first argument. If not provided, prompt the user for the path.
2. appsettings.json: Use the optional second argument. If not provided, default to xperience-by-kentico-kentico-migration-tool-master/Migration.Tool.CLI/appsettings.json.
3. Log directory: Read Settings.MigrationProtocolPath from appsettings.json. Use its parent directory as the log directory for all inputs and outputs. If not set, prompt the user for the path.

Verify required files exist before proceeding.

Phase 1: Gather Data

1a. Parse Logs

Run the log parsing script, passing the log directory. The script discovers all protocol*.txt and migration-run*.log files, processes them chronologically, and merges results across runs (later runs override earlier failures per entity):

& skills/migrate-content-eval/scripts/parse-migration-logs.ps1 -LogDir <log-dir>

Read output at <log-dir>/parsed-log-summary.yaml.

If script fails, mark all log-based checks as N/A — do not attempt manual regex parsing.

1b. Establish Database Connections

Read appsettings.json. Extract connection strings:

• KX13: Settings.KxConnectionString
• XbyK: Settings.XbyKApiSettings.ConnectionStrings.CMSConnectionString

Parse server (-S) and database (-d). Handle both Data Source/Server and Initial Catalog/Database variants.

Validate: sqlcmd -S <server> -d <database> -Q "SELECT 1" -h -1

If a connection fails, note which categories will have partial data. Do NOT stop — other sources can still proceed.

1c. Parse Migration Plan

Read the migration plan detail. Split by ## (H2) and ### (H3) headings. Parse markdown tables (split by |, trim cells). Extract expected entities:

If a section is not found, mark that evaluation category as N/A.

1d. Run All SQL Queries

Read references/eval-sql-queries.md. Execute all queries for the 12 categories. Log all sqlcmd output to <log-dir>/eval-queries.log.

Use parseable output: sqlcmd -S <server> -d <database> -Q "<query>" -W -s "|" -h -1

Phase 2: Evaluate 12 Categories

Read references/evaluation-categories.md for the full per-category evaluation logic. For each category, compare gathered data against plan expectations and assign status:

Status values: PASS (matches), FAIL (critical mismatch), WARN (non-critical), N/A (data unavailable).

Phase 3: Generate HTML Report

Read these references:

• references/report-generation.md for template filling instructions and per-category HTML fragment structure
• references/actionable-suggestions.md for issue → remediation mapping with fix types and skill routing
• assets/LOG_ANALYSIS_REPORT_TEMPLATE.html for the HTML template

For each of the 12 categories, build an HTML fragment replacing the corresponding {{CAT_N_BODY}} token. Build prioritized action items ({{ACTION_ITEMS_BODY}}): FAIL items first with remediation type badge, then WARN items. Deduplicate across categories.

Save to <log-dir>/migrate-content-eval-report.html.

Phase 4: Console Summary & Routing

Display:

1. Summary table — all 12 categories with status
2. FAIL items — with remediation type and specific fix
3. WARN items — with recommended action

Then route next steps based on results:

Be specific when routing. Examples:

• "Re-run migrate-content-classes skill for MedioClinic.DoctorProfile to fix taxonomy JSON casing"
• "Re-run migrate-content-appsettings skill — EntityConfigurations keys use dots instead of underscores"
• "Manually delete orphaned content type MedioClinic.DayOfWeek in XbyK Administration > Content types"

Rules

• Read-only only — all SQL is SELECT. Never modify logs, plan, config, or source code.
• Always save query output to <log-dir>/eval-queries.log.
• Graceful degradation — missing logs → log checks N/A. Failed DB → DB checks N/A. Always produce partial results.
• Deduplicate cascading errors — count unique issues, not total log lines.
• Filter noise — system resource skips, root node skips, admin user skips, terminal InvalidOperationException are informational. Do not count them as errors.
• Self-contained HTML — inline CSS, no external deps, no JavaScript.
• Every FAIL / WARN must have a remediation classified as: Config, Code, or Manual.
• Every remediation must route to a specific skill or manual action — never say "verify manually" without specifying what and where.

Gotchas

• Protocol log entries are multi-line — the parse script handles this. Do not parse manually.
• Console log may have ANSI escape codes (\[\d+m) — strip before parsing.
• Both protocol log and console log live in the same directory — the parent of Settings.MigrationProtocolPath. Protocol files are protocol*.txt, console logs are migration-run*.log.
• EntityConfigurations keys must use underscores (CMS_Class), not dots. Misspelling makes ExcludeCodeNames silently fail.
• --page-types creates DataClassInfo for ALL source classes regardless of ExcludeCodeNames. Excluded classes replaced by taxonomy → orphaned content type (WARN).
• Taxonomy tag JSON: "identifier" (lowercase) produces no log error but tags don't render. DB query is the only detection method.
• Table names use underscores: MedioClinic.Doctor → MedioClinic_Doctor in SQL.
• Exclude linked pages from KX13 source counts: WHERE NodeLinkedNodeID IS NULL.
• Content Hub items use ClassContentTypeType = 'Content', not 'Website'.
• Connection string format varies — handle Data Source/Server and Initial Catalog/Database.
• Reusable schema fields are on CMS_ContentItemCommonData, NOT per-content-type data tables.