Implementing an AI-assisted content migration

Define initial mapping rules

The migration of content starts with the mapping between the old and new schema. Follow the steps below to define the initial mapping between the old and new models.

1. Export both old and the new models as JSON files. Check out the syncing schemas guide on how to export a full schema to your preferred repository.

2. Using the schema JSON files and the old content items as context, ask the AI to define a schema mapping like the example snippet below.

   [
     {
       "oldName": "Person",
       "oldModelId": "c71ca99d-a9f8-4ab9-9d55-8422b7b24139",
       "oldTitleField": "name",
       "newName": "Person",
       "newModelId": "b09b4e0b-35f4-46d2-a9ee-c183f9f47ef0",
       "newTitleField": "name"
     },
     {
       "oldName": "Page",
       "oldModelId": "30eb21e3-88e6-45a6-89ca-2916a2a997d1",
       "oldTitleField": "internal_title",
       "newName": "Page",
       "newModelId": "b621dc19-d1db-40ef-a7e2-301a7bfc8cae",
       "newTitleField": "internal_title",
       "newSlug": true
     },
     {
       "oldName": "Article",
       "oldModelId": "8588d2ad-f529-4bc8-a3ce-c498a3d91260",
       "oldTitleField": "title",
       "newName": "Post",
       "newModelId": "fae3ce54-0003-487a-99d5-e9785bd9cc1e",
       "newTitleField": "title",
       "newSlug": true
     },
     {
       "oldName": "InlineCTA",
       "oldModelId": "c14b4592-6f90-4555-b692-d59ffbc66361",
       "oldTitleField": "headline",
       "newName": "CTA",
       "newModelId": "9c8d0009-e93b-4ff4-99d9-91f8d70c0af7",
       "newTitleField": "internal_title"
     },
     {
       "oldName": "SectionCtaImage",
       "oldModelId": "bf48dbcc-c70c-4843-887b-1f94f32e89f6",
       "oldTitleField": "title",
       "newName": "CTA",
       "newModelId": "9c8d0009-e93b-4ff4-99d9-91f8d70c0af7",
       "newTitleField": "internal_title"
     },
     {
       "oldName": "SectionFAQ",
       "oldModelId": "769f3a42-add3-432f-98a9-539e8cb70fa6",
       "oldTitleField": "internal_title",
       "newName": "FAQList",
       "newModelId": "5975c250-de41-4c26-82f4-cb4f456a77ec",
       "newTitleField": "internal_title"
     }
   ]

3. Review the mapping file and refine your prompt or the file directly to adjust the mapping.

Create migration scripts

To make sure that the migration can be run in manageable slices, build the scripts you need for the execution flow below.

CLI script: Create assets

It exposes the --dry-run (-d) flag for test mode that simulates the run without creating assets.

This script performs the following tasks:

1. Loop through each old asset used in a content item.
2. For each asset retrieved, create a single asset (unless in --dry-run mode),
3. Store the new and old asset IDs with the linked content ID of the source content in an asset mapping file. You need the ID mapping to link it to the correct content at a later stage.
4. Output the result and keep track of any unsaved IDs. Report includes the total count of created assets, failed assets and recorded ID mappings.

CLI script: Create empty content items

It exposes two optional flags:

• --dry-run (-d): Test mode that simulates the run without creating or modifying content.
• --model <name> (-m): Filter mode to migrate a single, specific model type rather than all models.

It performs the following tasks:

1. Loop through each entry in the schema mapping file.
2. For each model, fetch all the old content items.
3. For each old item retrieved, create a single content item (unless in --dry-run mode) to generate a new empty item with just a title and slug value.
4. Store the old and newly created ID mapping. You need the ID mapping to create the matching reference content at a later stage.
5. Output the result and keep track of any unsaved IDs. Report includes the total count of created items, failed items and recorded ID mappings.

CLI script: Fill content items

This CLI script exposes the following parameters:

• --dry-run (-d): Simulates updates without updating any new content items.

• --model <name> (-m): Restricts updates to items belonging to a specific model.

• --slug <name> (-s): Fills only a single content item matched by its slug.

• --id <id> (-i): Fills only a single content item matched by its ID.

• --limit <n> (-l): Caps the maximum number of items processed per model.

This script performs the following tasks:

• Using the API, fetch the nested fields, for example sections in the dynamic content field or stack field.
• Construct the payload for a PATCH or PUT as follows:
  • Look up the corresponding new content item ID using the ID mapping stored when new content items were created.
  • Set all new content items to Review stage. Useful for content editors to identify the migrated content items they need to review.
  • Call model and section-specific functions to fill nested content.
• Update the target content items, unless in --dry-run mode. If it’s a dry run, then output the generated payload without sending an API request.
• Generate a JSON report for any unmapped content items.

Helper scripts per model

This migration strategy splits the mapping into manageable slices by having separate scripts per new model. While the CLI script, Fill content items is model-agnostic and manages mapping between models, it calls helper scripts per new model to map the fields in a model.

These helper scripts perform the following tasks:

• Map model-specific fields. For example, for pages they map nested structures in the Stack field and for articles, they map to elements in a Dynamic content field.
• Using the asset mapping file and the content ID mapping, link the assets to the new content items.
• Add the transformed content to the payload for the request.

Helper scripts per nested element

For models like pages and articles that include nested elements, the mapping is split into a separate script per element. These helper scripts help you pinpoint very specific mapping issues.

Test and run the migration

Use the same test-and-run cycle for both migration phases: first create the empty content items and their ID mappings, then fill those items with content. Complete the first phase before starting the second so that references can resolve to the new item IDs.

Define the success criteria

Measure success against the content that is in scope.

• Creating empty content items: Make sure every eligible source item has a corresponding empty target item and a saved ID mapping.
• Filling content items: Check that every required field and reference is mapped to the target schema.

For these two phases, the report contains no unexplained failures. Any intentional exclusions or items that require manual migration are documented with an owner or next action.

These criteria let you distinguish accepted exceptions from migration defects. You can move to a full dry run when the remaining report entries have a clear resolution, even if some will be handled manually.

Follow the test-and-run cycle

For both the create and fill phases, follow the steps below.

1. Start with a partial dry run:
   • When running the CLI script to create empty content items, use --dry-run with --model.
   • For the fill phase, use --dry-run with --id or --slug, then expand the test to each --model.
2. Read the JSON report as a structured to-do list. Each entry should identify an unmapped component, failed reference, skipped field, or other specific issue.
3. Give the relevant report entries to your AI coding assistant and use them to fix the mapping file, extend the script, or add a missing helper. For example: Which model mapping is missing for each singular name in this report?
4. Repeat the partial dry run until the phase meets the success criteria.
5. Run a full dry run without the item or model filters and review the report for issues that the partial runs did not expose.
6. If the full dry run meets the success criteria, run that phase without --dry-run:
   • Run the create phase for all items before starting the fill phase.
   • Run the fill phase for one model first, verify the result, and then run it for all remaining items.

Verify the completed migration

After both phases are complete:

• Compare the source totals, created items, and saved ID mappings.
• Spot-check representative content items and nested structures in the Prepr UI and the new web app.
• Confirm that all remaining report entries are documented for manual resolution.