The Definitive Guide to Migrating to Jira

Jira is a software product developed by Atlassian for bug tracking, issue tracking and agile project management ¹. Atlassian is headquartered in Sydney and San Francisco, with Jira available in three product lines on a single underlying engine: Jira Software (engineering and agile), Jira Service Management (ITSM and service desk) and Jira Work Management (business teams).

The typical Jira customer is a software-led organisation — anywhere from a 20-person startup to a 20,000-engineer enterprise — that wants configurable workflows, JQL-based reporting and a deep Marketplace ecosystem rather than the simpler, more opinionated trackers further down the category. Compared with monday.com or Asana, Jira positions on workflow depth and developer-tool integrations; compared with Azure DevOps it positions on platform neutrality and the strength of its app ecosystem.

The shapes of migration that actually land on Jira tend to fall into four patterns. First, PM consolidation: a company replacing Trello, Asana or ClickUp with Jira to standardise engineering and cross-functional work on one tracker. Second, DC-to-Cloud moves, where existing Jira Data Center customers migrate to Atlassian Cloud ahead of Data Center end-of-life on 28 March 2029 ³⁷.

Third, legacy issue-tracker replacements — Redmine, Trac, Bugzilla, MantisBT, or homegrown databases — where the source schema is loose and the project is really a re-architecture. Fourth, M&A integration, where an acquired business runs on a different tracker and the parent standardises on Jira. An Asana-to-Jira move usually has clean Project-to-Project parity but maps poorly across custom workflows; a Server-to-Cloud move retains schema but reshapes user identifiers and audit history.

What makes migrating *to* Jira easier than the category average is the official tooling — the Jira Cloud Migration Assistant (JCMA) for Data Center sources and a native CSV importer for everything else ²³². JCMA also generates a Post-Migration Reconciliation (PTR) Excel report that counts projects, issues, comments, attachments and boards source-vs-destination ¹²².

What makes it harder than the average is the scheme model — Workflow Schemes, Field Configuration Schemes, Screen Schemes, Issue Type Schemes, Permission Schemes and Notification Schemes all map per-project per-issue-type ²⁵. Imports silently land issues against the wrong scheme set if the destination project's schemes are not pre-configured. Add the system-property override block — created, updated and creator cannot be overwritten on Cloud during standard CSV import — and the migration rewards careful pre-creation.

Workflows do not import via CSV — they are built in Settings → Issues → Workflows and applied through a Workflow Scheme before the first issue lands. Custom fields do not exist until created with the right type and context. Teams that scope for that work up front finish on time; teams that assume parity do not.

Workflows do not import. Custom fields do not exist until they are created. Teams that assume parity discover this on day two.

Jira's data model is hierarchical: a Site contains Projects, each Project has Issue Types, each Issue Type is governed by a Workflow Scheme that defines its Statuses and Transitions. Issues belong to a Project, carry an Issue Key (PROJ-123), and are linked to other issues via Issue Links. Above the issue level, Epics group Stories/Tasks/Bugs, and Sub-tasks live one level below their parent.

Before you map a single field on the source side, you need to know which Project, which Issue Type, and which Workflow Scheme each row will land against. The table below summarises the objects you will touch in a Jira Software / Service Management / Work Management migration.

Issues use the Issue Key (e.g. PROJ-123) as their canonical identifier, but Jira also exposes a numeric Issue ID internally. For CSV updates of existing issues, the External System Import tool requires you to include the Issue Key in a column mapped to Issue Key so the importer upserts rather than creates ¹²¹.

For first-time imports the upsert key you control is the legacy source ID — stamp it on each issue as a custom External ID or Legacy ID single-line text field. Build it on day one, populate from the source export, and use it for every subsequent delta.

Custom field types in Jira are based on a small set of primitive data types — string, number, user, group, datetime, option, option-with-children — each with documented JQL behaviour ⁴³. The catalogue below summarises the field-type estate you will model.

Relationships in Jira are expressed three ways. First, issue hierarchy: Sub-task → parent issue → Epic → higher-level (Premium) — these are *first-class* parent/child relationships scoped to a Project. Second, Issue Links — configurable link types like blocks, is blocked by, relates to, duplicates, clones, used for cross-project dependencies and for non-hierarchical relationships ⁵⁴.

Third, Components, Fix Versions and Labels act as project-scoped tag dimensions, queryable via JQL. There is no native master-detail cascade-delete between Epics and Stories: deleting an Epic does not delete its Stories, which is a behaviour you may need to reproduce with an Automation rule if your source platform relied on it.

Custom Field contexts are the single most-misunderstood part of the Jira schema. A custom field with one name can have *multiple* contexts, each scoped to a different (Project, Issue Type) combination, each with its own option list and default value ⁴⁸. A row imported into the wrong project context will appear to drop its value even though the field name matches.

The single best predictor of a clean Jira migration is how much work you do on the source side before the first import button is pressed. Atlassian's own JCMA documentation pre-flights your data for over a dozen error classes and still warns that scheduled background jobs, large attachment estates and inactive users derail otherwise-healthy migrations ⁷⁷⁷⁹.

The single best predictor of a clean Jira migration is how much work you do before you press *Begin migration* in JCMA.

Treat the source export as raw material that needs to be shaped to Jira's expected formats — dates rewritten to the chosen ISO format, users resolved to Atlassian Account IDs (Cloud) or usernames (Data Center), Issue Type and Status values mapped to the destination's existing names, and option-list values pre-created on the right Field Context.

Source-side prep

• Audit and clean the source database before export. Atlassian's *Clean up your instance before migration* guide recommends deleting unused projects, schemes, custom fields and workflows so you migrate less rather than more ⁷⁹⁸⁰.
• Convert dates to the format you intend to declare on the importer's Date time format options step — Jira rejects rows with fields.validation.date.format when the file format does not match the declared format ⁸³.
• Convert option lists so every value in single-select and multi-select columns exists as an option on the destination field's context — Jira returns *custom field require options that do exist* on any mismatch ⁸⁴.
• Stamp a stable external ID on every record in the source export — the source platform's primary key — so re-runs and reconciliation are deterministic.
• Decide what is in scope for historical comments, attachments and change history. CSV import preserves comments via the 01/01/2012 10:10;Admin; This comment works pattern and attachments via HTTP/HTTPS URLs in an Attachment column ³⁸.
• Save the file as UTF-8 with BOM if you have non-ASCII characters — Jira warns when the file contains non-ASCII and the wrong encoding silently mojibakes German umlauts, French accents, CJK characters ⁸²⁹¹.

Destination-side prep

• Create a sandbox on Jira Cloud Premium/Enterprise (or a development DC instance) and run the full migration end-to-end before touching production. Atlassian explicitly recommends a sandbox dry-run before any JCMA cutover¹²⁴.
• Provision users first through Okta, Microsoft Entra ID or another identity provider, *then* run the import — owner/reporter/assignee assignment fails silently if the referenced user does not exist or has no Jira product access ¹¹³.
• Pre-create every Custom Field with its Context on the right Project + Issue Type pair. Once a field is created, its type cannot be changed — you create a new field with the right type and migrate values across.
• Build Workflows, Workflow Schemes, Issue Type Schemes, Field Configuration Schemes, Screen Schemes, Permission Schemes and Notification Schemes before importing any issues — issues land against the wrong scheme set if the destination project is not pre-configured.
• Define Components and Fix Versions per Project before importing issues that reference them; the CSV importer accepts multiple column headers with the same name to import multi-value Component and Fix Version assignments ³⁸.

People prep

Cutover only works if humans cooperate. Lock down a source-system freeze window — typically 24 to 72 hours — and communicate it widely. Stop all non-crucial scheduled jobs on the source Jira (re-indexing, archive, Tempo accruals); Atlassian flags scheduled jobs as a leading cause of degraded migration performance ⁷⁷. A small Jira-to-Jira move runs one to two business days; a Server-to-Cloud migration with 2,000+ users and ScriptRunner-heavy customisations runs four to twelve weeks even when JCMA completes overnight ¹⁴.

Jira exposes several load paths and the right one depends on the source platform, dataset size, and whether the migration is Jira-to-Jira or third-party-to-Jira. The Jira Cloud Migration Assistant (JCMA) is the official path for Data Center → Cloud. The CSV importer covers most one-shot loads from third-party trackers. Marketplace and ETL tools sit on top of all of these.

Jira Cloud Migration Assistant (JCMA)

JCMA is the Atlassian-built, free app installed on Jira Data Center that migrates Projects, Issues, Workflows, Schemes, Users, Boards and Filters to Jira Cloud ³⁶. It runs as a wizard: pre-migration checks → choose projects → select users and apps → assess → run. Atlassian's published best practice is to move groups of projects in business-impact-ordered waves rather than one big-bang cutover ¹²⁴.

JCMA generates a Post-migration Reconciliation (PTR) report as an Excel file that compares source-vs-destination entity counts for projects, issues, comments, attachments, boards, filters and configurations, so you can validate before users get access ¹²². JCMA requires JCMA 1.12.45 or later for the PTR report.

CSV importer (External System Import)

Jira ships a native CSV importer at Settings (gear) → System → External System Import → CSV in both Cloud and Data Center ³²³³. A newer Jira import experience moves data from Asana, Notion and other business-tool sources directly into Jira business and software spaces. The recommended number of work items per file is 1,500, with estimated time around an hour ³².

The importer accepts CSV (and XLS/XLSX in the new experience). Each file needs a heading row with at minimum a Summary column; multi-value fields like *Components*, *Fix Version* and *Labels* are imported by repeating the column header ³⁸. Comments are loaded with the pattern MM/dd/yyyy HH:mm;username;comment-body; attachments via HTTP/HTTPS URLs in an Attachment column ³⁸¹⁵⁷.

Marketplace and third-party staging tools

Exalate, Getint, OpsHub and Configuration Manager sit between the source and Jira. They handle two scenarios: (a) third-party-to-Jira where the source is ClickUp, Asana, Azure DevOps or Trello, and the tool handles field mapping plus attachments and comments, and (b) Jira-to-Jira with selective JQL-based migration and bidirectional sync during a transition window.

Mapping is where every Jira migration earns its scars. The schema decisions you make in your mapping spreadsheet determine whether boards work on day two, whether automations fire on day five, and whether your engineering team trusts the data on day thirty.

Work object by object, top to bottom of the import order: Projects + Schemes first (so issues have somewhere to land), then Users and Groups, then Components and Versions, then Epics, then Stories/Tasks/Bugs, then Sub-tasks, then Issue Links, then attachments and comments by CSV pattern.

Project hierarchy — Project → Epic → Story/Task/Bug → Sub-task

Jira's first-class hierarchy is Project → Epic → Story/Task/Bug → Sub-task, and Premium adds higher levels (Initiative, Theme) configurable in Settings → Issues → Issue type hierarchy. Sub-task and Epic are *system* Issue Types — their parent-child semantics are baked into the platform.

When importing, set the Parent column on a Sub-task row to the parent's external ID; set the Epic Link (legacy) or Parent column on a Story row to the Epic's external ID. The newer Jira import experience also lets you assign specific Issue Types — Epic, Task, Story, Bug, Subtask — during import, rather than defaulting everything to Task. Use this — defaulting to Task and changing types post-import breaks reporting until reconciled.

Task dependencies — Issue Links, not hierarchy

Task dependencies in Jira are modelled through Issue Links with configurable Issue Link Types — defaults include blocks / is blocked by, relates to, duplicates, clones. Administrators can add custom link types via Settings → Issues → Issue linking ⁵⁴.

Issue Links can be populated via the CSV importer by adding columns named after each link type. Cross-project dependencies are supported natively — Issue Links span projects without restriction. The pragmatic approach for a source platform with a single dependency field is to import every dependency as a blocks link, then refine link types post-cutover.

Custom workflow status — Statuses and Workflow Schemes

Workflows are state machines built from Statuses and Transitions, applied to Issue Types via a Workflow Scheme on each Project. Every destination Status must be pre-created in Settings → Issues → Statuses before the workflow is built ¹⁰⁶.

When importing, the *Status* column value must exactly match the destination Status name, and that Status must be present on the workflow assigned to the Issue Type. Issues whose imported Status does not match the workflow's allowed states land on the workflow's *initial* status with the imported value dropped. Build the source-status → destination-Status mapping before the first dry run.

Time tracking — Original / Remaining / Logged

Jira has native time tracking with three fields: Original Estimate, Remaining Estimate and Logged Time (worklogs). Original and Remaining import via CSV columns in Jira's time-format (2w 1d 4h 30m). Worklogs import via repeated Log Work columns with the pattern time-spent;timestamp;author;comment.

For third-party trackers (Tempo, Harvest, Toggl), worklog migration is more involved. Atlassian's App Migration Platform coordinates with Tempo for Server-to-Cloud Tempo Timesheet migrations, but the support is partner-driven; projects without a Tempo migration path land worklogs as plain Jira worklogs, losing Tempo billing categories and account associations ¹⁰².

Comments and attachments — threading and timestamps

Comments import with original timestamps via the CSV pattern 01/01/2012 10:10;Admin;This is a comment body in a Comment column — repeat the column header for multiple comments ³⁸. The author segment must match an Atlassian Account ID (Cloud) or username (DC); unresolved authors default to the importer user. Comments do not thread on Jira — they are flat and chronological on the Activity tab.

Attachments via CSV require HTTP/HTTPS URLs in an Attachment column, with optional timestamp and author: 01/01/2012 13:10;[email protected];image.png;file://image-name.png ³⁸. Attachment size on Cloud defaults to 1 GB per file (up to 2 GB configurable); Data Center caps at 10 MB per file ¹⁵³¹⁵⁹. Plan storage caps: 2 GB per app on Free, 250 GB on Standard, unlimited on Premium ¹⁵³.

For migrations with hundreds of GB of attachments, keep originals in S3 or Google Drive, store a deep link in a custom URL field on the issue, and only inline-attach the most recent or most-referenced subset. This avoids both the per-file cap and the cumulative storage tier consumption.

Recurring tasks — Automation rules, not a property

Jira has no native *recurring issue* property. Recurrence is implemented via Automation rules in Project settings → Automation with a scheduled trigger (e.g. *Every Monday at 9 AM, clone issue PROJ-123*) or via Marketplace apps like Schedule for Jira. Source platforms (Asana, ClickUp, monday.com) that store a recurrence_rule on each task lose the rule structure on import; re-create as one Automation rule per distinct schedule.

For a migration with hundreds of distinct recurring rules, consolidate into 5-to-15 canonical Automations (daily standup, weekly review, monthly close, quarterly planning) and let team leads opt their issues in post-migration rather than mapping legacy recurrences one-to-one.

Custom-field mapping strategy

Resist the urge to map every source custom field one-to-one. Migrate only fields used by an active workflow, board, JQL filter or dashboard in the last 12 months. Atlassian's guidance is explicit: limit the number of custom fields in your import, avoid duplicating names of existing standard fields, and use generic names that can be reused ⁴⁸. Excess custom fields slow JQL and fragment context configurations.

For Select List fields whose source values do not match the destination, either (1) extend the destination field's context to include the missing options, (2) collapse adjacent values during transform, or (3) introduce a parallel custom field that holds the legacy value verbatim. Calculation / scripted fields do not import — they are rebuilt with ScriptRunner, Adaptavist Power Scripts or native Automation conditions post-load.

Audit trail, ownership and original timestamps

System fields created, updated, creator, reporter and the issue change history are partially preserved on import. The CSV importer accepts *Date Created* and *Reporter* columns; whether they round-trip correctly depends on the importer permission set ¹¹³¹¹⁴. On Cloud, *Modified Date* cannot be set during a CSV import even by admins — Jira stamps the import time with no override ¹¹⁴.

If you need to preserve the audit trail, create two custom datetime properties per issue type — *Legacy Created Date* and *Legacy Modified Date* — and populate them from the source export. Inactive source users are typically not recreated as Jira users (which would consume licences); instead, store name and email in a custom text field ⁹⁵.

Account-level audit logging is captured in Settings → System → Audit Log; Data Center exports up to 100,000 events as CSV and rotates daily logs at 100 MB each ¹¹². The Cloud audit log is admin-visible but limited to configuration-impact events — Jira's audit log is explicitly *not intended to record all activity*; it is a configuration-changes-only log ¹¹⁸.

Validation is the bridge between the import finishing and users being allowed in. Atlassian's JCMA Post-Migration Reconciliation (PTR) report is the canonical starting point for Data Center → Cloud — an Excel file generated automatically that counts projects, issues, comments, attachments, boards, filters and configurations source-vs-destination ¹²². For third-party migrations the equivalent is a hand-built reconciliation spreadsheet, plus a manual spot-check protocol on real records.

Build a reconciliation queries spreadsheet that compares source and destination on each of these counts. Anything outside a 0.5 percent variance gets investigated before users get login access.

• Total issues per project per Issue Type imported vs source — minus deliberately excluded rows (archived, deleted, out-of-scope).
• Total issues per Status vs source — a non-trivial drift usually signals a status-mapping miss against the destination Workflow Scheme.
• Total comments per project vs source, and a date-bucketed comparison to confirm comment timestamps round-tripped through the CSV MM/dd/yyyy HH:mm;author;body pattern.
• Total attachments and total bytes per project — verify against tier storage cap (2 GB Free / 250 GB Standard / unlimited Premium) ¹⁵³.
• Issue Links per link type — count blocks, is blocked by, relates to, duplicates and compare against source-derived expected counts ⁵⁴.
• Worklogs per user and total time logged — SUM(timeSpentSeconds) GROUP BY author and compare to source-system totals.
• Assignee and Reporter coverage — GROUP BY assignee and confirm no issue landed unassigned that had a source assignee (the silent Account ID resolution failure).
• Sprint and Version assignments — count issues per Sprint, per Fix Version, and verify against source-platform release/sprint structure.

On top of reconciliation, run a manual spot-check protocol: pick 30 random issues across projects and verify each field against the source UI. Pick five high-value Epics and trace the full hierarchy — child Stories, Sub-tasks, Issue Links, attachments, comments, worklogs. If a non-trivial discrepancy shows up in three or more of the 30, halt the migration, fix the root cause, and re-import the affected rows by Issue Key.

Jira has no native bulk-undo. The closest mechanism is Bulk Change at Issues → Search → Tools → Bulk Change, which lets admins select issues by JQL and delete them in batches — deleting all imported issues is the only practical rollback path once a bad import lands ¹²². Stamp every imported row with an *Import Batch ID* custom field so a single JQL query selects the entire batch for clean deletion.

The real rollback strategy remains: export everything to S3 before the import starts, snapshot the Jira database (DC) or rely on Cloud's daily backup, and if catastrophe strikes, bulk-delete by Import Batch ID and re-import. For JCMA DC-to-Cloud cutovers, keep DC live in read-only mode for 30 to 90 days post-Cloud-go-live as a fallback reference.

Cutover sequencing: (1) source goes read-only and teams are notified; (2) all non-crucial scheduled jobs are paused ⁷⁷; (3) final delta export captures everything that changed during the test-import window; (4) delta is imported; (5) PTR report or hand-built reconciliation runs; (6) users get login access and a 48-hour hyper-care window with the migration lead on call; (7) source decommission is scheduled for 30 to 90 days out, never the same day.

The Atlassian Partner Directory lists Platinum, Gold and Silver Solution Partners by certifications, customer count and product focus ¹⁴¹. For Jira migrations, partners with explicit Server-to-Cloud, ClickUp-to-Jira or Asana-to-Jira practices ship cleaner than generalist shops; partners with Atlassian *Cloud Specialization* are the standard pick for JCMA-driven Data Center cutovers.

Common picks include Adaptavist, Isos Technology, Appfire, Modus Create, Praecipio Consulting and Eficode — each offers fixed-scope migration packages alongside ongoing managed services. Atlassian also offers cloud migration trial extensions: paid annual cloud subscriptions for 1,000+ user organisations qualify for up to one year free of overlapping DC subscription ¹⁴⁴.

Standard Marketplace picks include Exalate (bidirectional sync during cutover), Getint (Asana/ClickUp/Trello-to-Jira with attachments and comments) and OpsHub Migration Manager (enterprise Jira-to-Jira). For warehouse-resident sources, Fivetran, Airbyte, Stitch and Workato all ship Jira connectors used as the staging layer in ETL-fed migrations.

Managed-migration cost ranges vary widely. A clean Asana-to-Jira or Trello-to-Jira move of under 25,000 issues with standard Issue Types often lands in the $3,000–$10,000 range with a setup fee plus per-project pricing. A Jira Data Center to Cloud project with 2,000+ users, ScriptRunner customisations and 50+ Marketplace apps typically runs $40,000–$150,000+, with the upper end driven by user count, custom-field complexity and plugin migration paths rather than raw issue count ¹⁴².

For teams that want to outsource the migration end-to-end, FlitStack specialises in Jira migrations and handles the Workflow Scheme construction, Custom Field Context configuration, Account ID resolution, historical-data preservation and reconciliation work described in Sections 5 and 7. Pricing is fixed-fee, based on issue count and source platform, with separate line items for Issue Link migration, worklog preservation and attachment volume.

This is one of several legitimate paths — the right choice for any given team depends on whether they want an Atlassian Solution Partner, a Marketplace-app-led migration, an ETL-staged approach, or a specialist migration vendor. Explore FlitStack →