# Migration Checklist

import { MigrationChecklist, ChecklistSection, ChecklistItem } from "../../../components/migration-checklist";

Use this checklist to plan and validate a v1-to-v2 integration migration. Your progress is saved in
this browser.

<MigrationChecklist>

<ChecklistSection title="Discovery">
  <ChecklistItem>Inventory v1 endpoints currently used by the integration.</ChecklistItem>
  <ChecklistItem>Identify which v2 resources and workflows replace each v1 call.</ChecklistItem>
  <ChecklistItem>Mark whether each call is read, create, replace, partial update, delete, or command-style.</ChecklistItem>
  <ChecklistItem>Identify batch jobs, webhooks, retries, export jobs, and support tooling that parse API responses or errors.</ChecklistItem>
</ChecklistSection>

<ChecklistSection title="Authentication">
  <ChecklistItem>Create or obtain v2 client credentials.</ChecklistItem>
  <ChecklistItem>Implement `/api/v2/auth/token`.</ChecklistItem>
  <ChecklistItem>Store `access_token`, `refresh_token`, `expires_in`, and `scope` according to your security requirements.</ChecklistItem>
  <ChecklistItem>Send `Authorization: Bearer ...` on protected requests.</ChecklistItem>
  <ChecklistItem>Handle `401` errors and token refresh paths.</ChecklistItem>
</ChecklistSection>

<ChecklistSection title="Requests">
  <ChecklistItem>Replace v1 URLs with `/api/v2` endpoints from the [API reference](/api).</ChecklistItem>
  <ChecklistItem>Re-map every request body from the v2 request schema.</ChecklistItem>
  <ChecklistItem>Rename scalar reference fields to the documented `...Id`, `...Ids`, `...Code`, or `...Codes` fields.</ChecklistItem>
  <ChecklistItem>For root element writes, review [Elements](/docs/migration-from-v1/elements) before mapping statuses, groups, nested task/publication links, and external-system bindings.</ChecklistItem>
  <ChecklistItem>For task writes, review [Element Tasks](/docs/migration-from-v1/tasks) before mapping assignment, status, format, confirmation status, Asset Link, text length, custom fields, and done-state payloads.</ChecklistItem>
  <ChecklistItem>For publication writes, review [Element Publications](/docs/migration-from-v1/publications) before mapping placement fields, task links, schedules, CMS metadata, publish flow, and delete response handling.</ChecklistItem>
  <ChecklistItem>For task-publication links, review [Task-Publication Link Migration](/docs/migration-from-v1/task-publication-linking) before translating v1 positional `assignments` arrays or standalone `assignedTasks`.</ChecklistItem>
  <ChecklistItem>For custom fields, review [Custom-Field Migration](/docs/migration-from-v1/custom-fields) before mapping definition lists, option paths, selection values, and scope assignment fields.</ChecklistItem>
  <ChecklistItem>For platform schedule configuration, review [Platform Schedule Configuration Migration](/docs/migration-from-v1/platform-schedule-configuration) before mapping weekly schedules, manual schedules, or time-slot IDs.</ChecklistItem>
  <ChecklistItem>For configuration resources, review [Configuration Resource Migration](/docs/migration-from-v1/configuration-resources) before mapping platform, group, category, type, status, or task-format calls.</ChecklistItem>
  <ChecklistItem>For users, absences, shifts, and shift day notes, review [People And Scheduling Migration](/docs/migration-from-v1/people-and-scheduling) before mapping people and schedule-administration calls.</ChecklistItem>
  <ChecklistItem>Check omission and `null` behavior for every write field.</ChecklistItem>
  <ChecklistItem>Use `POST`, `PUT`, `PATCH`, and `DELETE` according to [Write Semantics](/docs/guides/api-conventions/write-semantics).</ChecklistItem>
  <ChecklistItem>For nested element writes, validate task-publication link fields and publication schedule fields.</ChecklistItem>
</ChecklistSection>

<ChecklistSection title="Responses">
  <ChecklistItem>Re-map response parsing from the v2 response schema.</ChecklistItem>
  <ChecklistItem>Allow additive response fields.</ChecklistItem>
  <ChecklistItem>Do not send response bodies back as write payloads without mapping through the write schema.</ChecklistItem>
  <ChecklistItem>Update list parsing for `content`, `size`, `hasMore`, `page`, and `nextCursor`.</ChecklistItem>
  <ChecklistItem>Choose the pagination mode exposed by each endpoint; the element list is cursor-only.</ChecklistItem>
</ChecklistSection>

<ChecklistSection title="Errors">
  <ChecklistItem>Parse RFC 9457 Problem Details.</ChecklistItem>
  <ChecklistItem>Use `type` for error category handling.</ChecklistItem>
  <ChecklistItem>Parse validation `errors[]` when present.</ChecklistItem>
  <ChecklistItem>Log `traceId` for support.</ChecklistItem>
  <ChecklistItem>Update retry logic so validation, authentication, authorization, and business-conflict errors are not retried blindly.</ChecklistItem>
</ChecklistSection>

<ChecklistSection title="Resource Workflows">
  <ChecklistItem>Verify element aggregate create/read/update behavior using [Elements](/docs/migration-from-v1/elements).</ChecklistItem>
  <ChecklistItem>Verify task creation, assignment, status, format, content behavior, done-state action, and delete behavior using [Element Tasks](/docs/migration-from-v1/tasks).</ChecklistItem>
  <ChecklistItem>Verify publication creation, scheduling, publishing, delete behavior, and CMS metadata behavior using [Element Publications](/docs/migration-from-v1/publications).</ChecklistItem>
  <ChecklistItem>Verify task-publication linking behavior using [Task-Publication Link Migration](/docs/migration-from-v1/task-publication-linking).</ChecklistItem>
  <ChecklistItem>Verify custom-field definition, option, and value behavior using [Custom-Field Migration](/docs/migration-from-v1/custom-fields).</ChecklistItem>
  <ChecklistItem>Verify platform schedule configuration and time-slot behavior using [Platform Schedule Configuration Migration](/docs/migration-from-v1/platform-schedule-configuration).</ChecklistItem>
  <ChecklistItem>Verify platform, group, category, type, status, and task-format behavior using [Configuration Resource Migration](/docs/migration-from-v1/configuration-resources).</ChecklistItem>
  <ChecklistItem>Verify user, absence, shift, and shift-day-note behavior using [People And Scheduling Migration](/docs/migration-from-v1/people-and-scheduling).</ChecklistItem>
</ChecklistSection>

<ChecklistSection title="Release Readiness">
  <ChecklistItem>Run integration tests against a v2 test environment.</ChecklistItem>
  <ChecklistItem>Compare representative v1 and v2 workflows at the business-rule level.</ChecklistItem>
  <ChecklistItem>Confirm support staff can use `traceId` values from client logs.</ChecklistItem>
  <ChecklistItem>Confirm monitoring and alerting treat expected v2 validation/business errors differently from transient operational failures.</ChecklistItem>
  <ChecklistItem>Keep a rollback or dual-run plan until critical workflows have been verified in production-like data.</ChecklistItem>
</ChecklistSection>

</MigrationChecklist>