> ## Documentation Index > Fetch the complete documentation index at: https://docs.gradial.com/llms.txt > Use this file to discover all available pages before exploring further. # Batch Migration > Migrate large volumes of content into your new CMS environment using Gradial's batch processing capabilities. ## Why This Is Slow Today Migrations are where content teams lose quarters. A redesign, a platform move, or a template consolidation means a list of URLs — often hundreds — that each need their content read, mapped onto new components, and rebuilt. The work is identical every time and completely manual, which makes it both expensive and error-prone: page 40 gets built to a slightly different standard than page 4, and nobody notices until an audit. The usual response is to scope the migration down: move the top 50 pages, leave the rest, and accept a split estate. That decision then costs you for years. Gradial runs the same page-build process across the whole list at once, using your templates and design system patterns, so the volume stops being the reason to cut scope. *** ## Overview Batch Migration allows you to create multiple new pages from a set of source URLs and transition them into your new design system. This is ideal for onboarding legacy content, platform migrations, or transitioning pages to updated templates at scale. Think of batch migration as running many [New Page](/docs/creating-new-experiences/new-page) tasks simultaneously—Gradial reads content from your source pages and recreates them using your CMS templates and Design System patterns. *** ## Prerequisites Before starting a migration, ensure you have: 1. **Golden Pages** created for each target template type — see [Golden Pages Guide](/docs/creating-new-experiences/golden-pages) 2. **Design System patterns** ingested from those Golden Pages — see [Design Pattern Ingestion](/docs/creating-new-experiences/design-pattern-ingestion) 3. **Target pages created in your CMS** — the destination pages should already exist in your content structure 4. **Source URLs accessible** — Gradial needs to read from your source pages *** ## Migration Workflow Overview ``` ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ 1. Prepare │ │ 2. Create │ │ 3. Run │ │ Spreadsheet │ ──▶ │ Batch Task │ ──▶ │ Batch │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ ┌─────────────────┐ ┌─────────────────┐ │ │ 5. Promote │ │ 4. Review │ │ │ Launches │ ◀── │ Results │ ◀──────────┘ └─────────────────┘ └─────────────────┘ ``` *** ## Step 1: Prepare Your Migration Spreadsheet The migration spreadsheet is the most important part of the process. A well-prepared spreadsheet with detailed instructions produces much more accurate results. ### Required Columns | Column | Description | Example | | :- | :- | :- | | **Instructions** | Detailed prompt telling Gradial how to handle this page | See below | | **Live Link** | Source URL to migrate content from | `https://www.example.com/old-page` | | **Migrated Page Path** | Content path for the destination in your CMS | `/content/mysite/en/new-page` | | **Author URL** | Full authoring URL for the destination | `https://author.example.com/editor.html/content/mysite/en/new-page.html` | | **Preview URL** | Author URL with preview parameter | `https://author.example.com/content/mysite/en/new-page.html?wcmmode=disabled` | ### Optional Columns Depending on your migration needs, you may include additional columns: * **Pattern Recommendations** — Specify which Design System patterns to use for each page * **Site Group** — For sites with dynamic content segmentation * **Template Reference** — Explicitly specify which template to use * **Custom metadata** — Any page-specific information the agent should know ### Writing Effective Instructions The Instructions column is where you tell Gradial exactly how to handle each page. More detail produces better results. **Example instruction:** ``` Migrate the content from the Live Link URL to the Migrated Page Path. Use the Article Page Design Patterns for component selection. Map content as follows: - Page hero: Use "Article Hero" pattern with the main headline and featured image - Body content: Use "Rich Text Block" pattern for article text - Related articles: Use "Card Grid 3-Column" pattern for any linked articles - CTA section: Use "Promo Banner" pattern for any call-to-action blocks Preserve all existing images and upload to DAM at /content/dam/mysite/articles/ Do not run the QA agent after completion. ``` ### Pattern Recommendations For each page, specifying which patterns to use and where improves accuracy significantly: ``` Patterns to use: - "Article Hero" for the top banner section - "Rich Text Block" for main body content - "Pull Quote" for any highlighted quotes - "Image Gallery" for photo collections - "Related Content Cards" for the bottom section ``` *** ## Step 2: Create the Batch Task ### Navigate to Batch Tasks From the left navigation, select **Batch Tasks**, then click **New Batch** in the top-right corner. ### Configure the Batch 1. Enter a descriptive **name** for the batch (e.g., "Blog Migration - January 2025") 2. Add an optional **description** 3. Verify the correct **Workspace** and **Environment** are selected > **Tip:** For initial testing, name your batch clearly (e.g., "Blog Migration - TEST RUN") so you can easily identify and clean up test batches later. ### Import Your Spreadsheet 1. Click **Bulk Add** to open the import screen 2. Select **New Page** as the task type 3. Upload your Excel file containing the migration data 4. The first row will be used as headers; each subsequent row becomes a task ### Configure Task Properties Before creating tasks, you can set properties that apply to all tasks: * **Assignee** — Who owns these tasks * **Approver** — Who reviews completed tasks * **Template** — The CMS template to apply Setting these during import saves time versus updating each task individually. ### Create Tasks Click **Create Tasks** (or "Create xx threads"). Each row in your spreadsheet becomes an individual task within the batch. > **Important:** Creating tasks does not run them. Review the imported tasks before executing the batch. *** ## Step 3: Run a Test Batch First Before running a large migration, always test with 1-2 pages to validate your setup. ### Why Test First? * Verify your instructions produce the expected results * Check that patterns render correctly * Identify any adjustments needed to your spreadsheet * Avoid having to fix issues across hundreds of pages ### Running Selected Tasks 1. From the batch task table, select specific tasks using the checkboxes 2. Click **Run Batch** — only selected tasks will execute 3. Review results before running the full batch ### Evaluating Test Results After test tasks complete: 1. Click into each task to see the instructions and results 2. Open the authoring agent report to see what actions were taken 3. Preview the migrated page in your CMS to verify content and layout 4. Note any adjustments needed for your instructions or pattern recommendations *** ## Step 4: Run the Full Batch Once satisfied with test results, run the complete migration. ### Execute the Batch 1. Click **Run Batch** from the batch task view 2. The button shows the total number of tasks to process 3. Confirm to start processing ### Monitor Progress During execution, you'll see: * **Progress bar** showing overall batch completion percentage * **Task list** with status indicators for each task: * 🔵 **Running** — Task is being processed * 🟢 **Done** — Task completed successfully * 🔴 **Error** — Task encountered an issue ### Processing Time Migration tasks take longer than simple content updates because Gradial must: 1. Read and analyze the source page 2. Map content to appropriate patterns 3. Create or update the destination page in your CMS 4. Upload any assets to the DAM 5. Optionally run QA checks Plan accordingly for large batches. *** ## Step 5: Review and Promote ### Review Completed Tasks After the batch completes: 1. Navigate back to the task list 2. Click into individual tasks to review: * The original instructions * The agent's action report * Any summary messages or QA findings ### Promote Launches Migrated pages are created in your CMS's staging layer (an AEM Launch, a workflow state, a draft environment), not published directly. To make them live: 1. Select tasks ready for promotion (individually or use the header checkbox to select all visible) 2. Click **Promote Launches** 3. For batches with multiple pages of tasks, navigate to each page and repeat > **Note:** Promoting a staged page does NOT publish it. Publication still follows your organization's standard CMS workflow and governance processes. ### Handle Issues If QA reveals issues with migrated pages: * Create follow-up tasks in Gradial to make corrections * Use [Content Updates](/docs/updating-existing-experiences-i-e-content-updates/content-updates) for copy changes, component adjustments, or styling fixes * Iterate until pages meet quality standards *** ## Best Practices ### Spreadsheet Preparation * **Be detailed in instructions** — More context produces better results * **Specify patterns explicitly** — Don't rely on the agent to guess which patterns to use * **Include all URLs** — Provide both author and preview URLs for easy verification * **Test your spreadsheet** — Run a small batch first to validate your setup ### Batch Organization * **Use clear naming conventions** — Makes tracking and cleanup easier * **Group similar pages** — Batch pages that use the same template and patterns together * **Keep batches manageable** — Consider splitting very large migrations into multiple batches ### Quality Assurance * **Review before promoting** — Check migrated pages in your CMS preview * **Use the QA agent** — Let Gradial flag potential issues automatically * **Plan for iteration** — Expect some pages will need follow-up adjustments ### Execution * **Test first, always** — Run 1-2 pages before the full batch * **Monitor progress** — Watch for errors during batch execution * **Promote in batches** — Review and promote pages in manageable groups *** ## Troubleshooting | Issue | Likely Cause | Solution | | :- | :- | :- | | Tasks fail to run | Source URL inaccessible | Verify source pages are accessible to Gradial | | Wrong patterns used | Instructions not specific enough | Add explicit pattern recommendations | | Content missing | Source page structure unexpected | Review source page and update instructions | | Images not migrated | DAM path not specified | Add DAM upload path to instructions | | Tasks stuck in "Running" | Processing complex page | Allow more time; check for errors | *** ## Related Resources * [Golden Pages Guide](/docs/creating-new-experiences/golden-pages) — Creating reference pages for pattern ingestion * [Design Pattern Ingestion](/docs/creating-new-experiences/design-pattern-ingestion) — Setting up your Design System * [New Page Workflow](/docs/creating-new-experiences/new-page) — Creating individual new pages * [Content Updates](/docs/updating-existing-experiences-i-e-content-updates/content-updates) — Making changes to existing pages * [Batch Updates](/docs/updating-existing-experiences-i-e-content-updates/medium-content-updates-in-gradial) — Updating multiple pages at once *** ## Who this is for | Role | What Gradial handles | | :- | :- | | **Migration / Program Lead** | Full-estate scope instead of a top-50 subset, with consistent output across the whole list | | **Web Producer** | Not running the same CMS operation four hundred times | | **Content Strategist** | Legacy content mapped onto the new design system, with gaps surfaced rather than silently dropped | | **IT / Platform Owner** | A platform move that doesn't leave a split estate behind | | **Brand Manager** | Every migrated page built to current standards, not the standard in force when it was first written | ### How this maps to your function Migrations get scoped down because the per-page cost is high and fixed. Change that cost and the scoping conversation changes with it — you can move the long tail, retire the old platform on schedule, and stop carrying two estates. Bulk migration is also the best opportunity you will get to raise the floor: every page passes through a process that applies current templates, current patterns and current brand standards. Handled page by page over two years, that consistency never arrives. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.