Jira Service Management Migration Checklist

Migrating to Jira Service Management (JSM) brings the benefit of powerful workflows, automation, and flexible service desk features. But the gap between "planning a migration" and "executing one without data loss" is where most teams get stuck. This checklist covers the technical specifics — API constraints, field mapping gotchas, source-specific complexity, and the failure modes we see repeatedly.

Scope the Migration

Before diving into the migration, define the scope with enough precision that your execution plan doesn't change mid-flight.

• Historical Data Range: Decide how far back your ticket history should go. Migrating too much data increases execution time and can hit JSM's attachment storage limits. Migrations under 50k tickets typically complete in hours; migrations over 100k tickets can take days depending on attachment volume and API rate limits.

• Identify Users and Agents: Determine which active users and archived agents need to be included. JSM agent licensing is per-seat — every agent you migrate needs a paid license slot. Confirm your license count before migration, not after.

• Choose Objects to Migrate: Define the objects you want to bring over, such as:

  • Tickets (and related threads)
  • Customers and companies (profiles and contact info)
  • Custom fields, tags, and metadata
  • Attachments
  • Saved replies, workflows, and automation rules

• Decide What to Skip: Consider leaving behind old spam, irrelevant tickets, test cases, and outdated records. Removing noise before migration reduces execution time and keeps your JSM instance clean from day one.

• Map Legacy Data: Carefully map legacy ticket statuses, priorities, workflows, and team assignments to JSM's model. This mapping will guide the actual data migration. See the field mapping reference below for specifics.

Complexity by Migration Source

Not all migrations to JSM are equal. The source platform determines which data maps cleanly and where you'll spend engineering time.

If you're migrating from a platform not listed here, the complexity generally scales with the number of custom fields, the depth of threading/conversation history, and whether the source API supports bulk export.

Field Mapping Reference

Field mapping is where most migration errors originate. Here are the mappings that cause the most problems:

What Can Be Migrated Via API

JSM's REST API (v2 and v3) supports importing most essential data, but with specific constraints you need to plan around.

• Customers & Organizations: Import via the /rest/servicedeskapi/customer and Jira user management endpoints. Customer metadata like support plan tiers typically requires custom fields since JSM has no native "customer tier" concept.

• Tickets & Conversations: Each legacy ticket becomes a JSM issue. The migration should include:

  • Original tickets (as issues via /rest/api/3/issue)
  • Messages, replies, internal comments (via /rest/api/3/issue/{issueIdOrKey}/comment)
  • Attachments (via /rest/api/3/issue/{issueIdOrKey}/attachments — note the default 10MB per-file limit on Cloud)
  • Metadata (priority, status, custom fields)

• Custom Fields & Tags: Custom fields must be created in JSM before import. Tags map to Labels, with the spacing constraint noted in the field mapping table above.

• Attachments: Supported, but subject to per-file size limits (10MB default on Cloud, configurable on Data Center). Inline images in ticket bodies require separate handling — they must be uploaded as attachments and re-linked.

What the API Does Not Support

These require UI configuration or workarounds:

• SLA policies and SLA clock history — SLA configurations are project-level settings, not importable via API. Historical SLA compliance data from your source platform cannot be migrated.
• Automation rules — Must be rebuilt manually in JSM's automation engine or via Scriptrunner.
• Queue definitions and routing rules — UI-only configuration.
• Assets (formerly Insight) objects — Assets has its own API (/rest/assets/1.0/), separate from the core Jira API. Asset imports require a separate migration process.
• Knowledge base articles — If you're also migrating a knowledge base, Confluence is the target, not JSM directly. This is a separate migration track.

API Rate Limits

JSM Cloud enforces rate limits that directly affect migration speed:

• Standard rate limit: varies by endpoint, but expect throttling (HTTP 429 responses) if you exceed roughly 100 requests per minute per user for write operations.
• Attachment uploads are the most common bottleneck. Large attachment volumes can extend migration timelines significantly.
• Use exponential backoff on 429 responses. Aggressive retry without backoff can result in temporary API blocks.

What Still Needs to Be Configured in the JSM UI

While JSM provides a robust API, there are still several configurations that require manual intervention.

• Service Desk Setup: Configure your Service Desks, including email channels, queues, and team-specific workflows.
• User Roles & Permissions: Assign roles and permissions to your users (Admins, Agents, and Customers). Configure these through the JSM UI. Note that JSM's permission model (project roles + permission schemes) is different from most help desk platforms — plan for this mapping.
• Workflows: Set up your workflows manually in JSM, including SLAs, issue status transitions, and approval processes.
• Custom Fields & Ticket Types: If your system has custom ticket types or fields, ensure they are configured ahead of the migration. Every custom field used in the import must already exist in JSM, with the correct data type.
• Queues and SLAs: Configure your service queues, SLA policies, and routing rules manually in the UI.
• Email and Notification Settings: Set up email notifications, including autoresponders and customer notifications, to ensure proper communication flow.
• Automation Rules (including Scriptrunner): If you relied on macros, triggers, or automation in your source platform, you'll need to rebuild these. JSM's native automation engine handles common cases. For complex logic (e.g., cross-project updates, conditional field population), Scriptrunner is the standard tool.

Pre-Migration Setup

This phase ensures that JSM is ready to accept migrated data and minimizes issues during the cutover.

1. Create Projects & Service Desks: Set up your JSM projects and ensure they align with your organizational structure (e.g., support, HR, IT).
2. Invite Users and Set Permissions: Add all active users and assign proper roles and permissions. Ensure agent IDs are correctly mapped to avoid orphaned tickets. Confirm your JSM agent license count covers all agents who need assignment.
3. Map Custom Fields: If your legacy system had custom fields, replicate them in JSM. Match data types exactly — a mismatch between text and number types will cause silent data drops.
4. Test Data Import: Run a small-scale import (e.g., 100 tickets covering different ticket types, statuses, and attachment sizes) to ensure mapping and formatting are correct. Verify that issues, comments, and attachments appear as expected.
5. Configure Email and Integration Settings: Set up email forwarding, email notifications, and any third-party integrations.

Migration Execution

At this stage, you'll actually move the data into JSM.

• Import Customers and Organizations: Start by importing customer and company profiles to ensure that ticket history links correctly.
• Migrate Tickets and Conversations: Each legacy ticket becomes an issue in JSM. Migrate all messages, replies, attachments, and statuses.
• Map Agent Assignments & Ownership: Ensure that each migrated ticket is assigned to the correct agent and team. If an agent no longer exists, decide in advance whether to reassign to a default agent or leave unassigned.
• Import Tags, Custom Fields & Metadata: Preserve any essential metadata like priority, ticket type, and custom fields.
• Run Delta Import: After the main migration, run a delta import for tickets created between your final export and the go-live date.

Post-Migration Verification

Once data is loaded and agents begin working in JSM, verify everything for accuracy. "Spot-checking" isn't enough — use a structured verification approach.

• Record count validation: Compare source ticket count against JSM issue count per project. If the numbers don't match, investigate before proceeding.
• Attachment verification: Check that attachments are accessible (not just present). Corrupt or zero-byte attachments are a common failure mode.
• Timestamp integrity: Verify that created/updated timestamps on migrated issues match the source. Incorrect timestamps break SLA reporting.
• Agent assignment audit: Run a JQL query for assignee is EMPTY to find orphaned tickets that lost their agent mapping.
• Thread integrity: Open a sample of tickets with long conversation histories and confirm all replies and internal comments appear in the correct order.
• Test inbound channels (email, chat, etc.) to ensure tickets are routed correctly and that agents can respond.
• Test workflows, SLAs, and routing rules to confirm that automation behaves as expected.
• Ensure agents are comfortable with JSM's interface, workflows, and features like internal comments and issue transitions.
• After one week, schedule a review to collect agent feedback and address any issues that arise during day-to-day operations.

Rollback and Recovery

No checklist is complete without a plan for when things go wrong.

• Before migration: Take a full export of your source platform data. This is your recovery baseline if the migration needs to be re-run or reversed.
• Partial failure during import: If a subset of tickets fails to import (common with attachments exceeding size limits or malformed custom field data), isolate the failed records, fix the data, and re-import only the failed subset.
• Complete rollback: If the migration is fundamentally broken (e.g., wrong field mappings applied to all records), delete the JSM project and re-create it from scratch rather than trying to patch in place. Patching partial data creates harder-to-find inconsistencies.
• Post-go-live issues: If problems surface after agents are already working in JSM, freeze new work in the old system but keep it read-accessible for reference while you resolve the issues.

Common Pitfalls & Pro Tips

Ignoring Custom Fields & Tags: Ensure that all custom fields and tags are properly mapped before migrating. Missing fields can result in data loss — and because JSM often fails silently on these, you won't know until an agent reports it.

Testing with uniform data: Always test with varied data, including different ticket types, sources, statuses, and edge cases (e.g., tickets with 50+ replies, large attachments, special characters in custom fields) to ensure full migration integrity.

Underestimating the learning curve: Even experienced agents will need time to adjust to JSM's system. JSM's terminology (issues vs. tickets, request types vs. forms) and navigation are different from most help desk platforms. Provide training to avoid post-migration confusion.

Overcomplicating workflows at launch: Keep workflows simple initially. Overcomplicating workflows can cause confusion and slow down the cutover process. Add complexity incrementally after go-live.

Skipping the delta import: Don't forget to run a delta import after the initial migration to capture any new tickets created before go-live. The gap between final export and cutover always has new tickets.

Not accounting for Assets (Insight): If your source platform has a CMDB or asset management component, this is a separate migration track with its own API and data model. Don't treat it as part of the ticket migration.