Desk365 to Jira Service Management Migration Guide

Desk365 to Jira Service Management Migration Guide

Migrating from Desk365 to Jira Service Management (JSM) means moving tickets, conversation history, attachments, contacts, knowledge base articles, and operational workflows between two systems with fundamentally different data models. Desk365 is a Microsoft 365-native helpdesk with a flat ticket structure. JSM sits on top of Jira's issue-tracking engine, where every ticket is an "issue" tied to a project, issue type, and workflow.

This guide covers the data objects you can extract, API mechanics on both sides, field mapping decisions, import method tradeoffs, knowledge base migration, and the failure modes you need to plan for. It assumes Jira Service Management Cloud.

Why Teams Move from Desk365 to JSM

Desk365 works well as a lightweight, Teams-integrated helpdesk. Teams outgrow it when they need deeper ITSM workflows — change management, problem management, asset CMDB, or tight coupling between service requests and engineering work in Jira Software.

JSM provides native integration with Confluence for knowledge bases, Jira Software for dev escalation, and a full ITIL-aligned workflow engine. The tradeoff: JSM is significantly more complex to configure, and its pricing model charges per agent.

The migration itself is not symmetrical. Desk365 makes it relatively easy to get data out. Getting data into JSM — with correct field types, statuses, user mappings, and comment visibility — is where most teams hit friction.

What You Can Extract from Desk365

Desk365 offers two extraction methods: CSV export and REST API v3.

The CSV export is accessible from the agent portal and supports filtered exports by date range, status, or assigned agent. It covers tickets, time entries, contacts, and companies. The API provides richer, threaded data including conversation history and knowledge base content. (help.desk365.io)

Desk365 API v3 Basics

• Authentication: API key, found at Settings > Integrations > API
• Base URL: https://yoursubdomain.desk365.io
• Rate limits: Plan-specific — Standard: 100 calls/hour; Plus and Premium: 50 calls/minute (help.desk365.io)
• Pagination: Controlled via ticket_count parameter

Desk365 tickets ship with these default fields: Priority, Status, Subject, Type, Group, Category, Subcategory, Source, and Contact. The Type field defaults to four values: Question, Incident, Problem, and Request. Custom fields support Dropdown, Text Input, Checkbox, Date, Number, Paragraph Input, and multi-level (cascading) field types.

CSAT and Survey Data

Desk365 exposes survey data via /v3/surveys and /v3/surveys/ratings. Extract this before migration — it is the only way to preserve historical satisfaction scores.

JSM does not have a native CSAT engine in the same model as Desk365. Your options for preserving this data:

• Store survey scores as read-only custom fields on each migrated issue (e.g., desk365_csat_rating, desk365_csat_comment)
• Export the full survey dataset as a CSV and store it in Confluence as a historical record linked from the migrated project
• If ongoing CSAT measurement is required in JSM, configure a third-party integration such as Nicereply, Surveypal, or Atlassian's built-in customer satisfaction feature (available on Premium and Enterprise plans)

Do not attempt to map Desk365 survey ratings into JSM's native satisfaction fields — the data models are not compatible and the write path for those fields is restricted.

How Jira Service Management Accepts Data

JSM has multiple import paths, and picking the wrong one causes problems that are hard to fix after the fact.

Relevant APIs

1. Jira Cloud REST API (/rest/api/3/issue) — creates standard Jira issues with direct control over all fields including assignee, reporter, and custom fields
2. JSM Service Desk API (/rest/servicedeskapi/request) — creates customer requests with service desk context, including serviceDeskId, requestTypeId, and request participants
3. Jira Bulk Issue API (POST /rest/api/3/issue/bulk) — creates up to 50 issues per call; unlike single-issue creation, this endpoint supports overriding system-managed fields when used through the Jira CSV/JSON import pipeline
4. Jira CSV/JSON importers — wizard-based bulk import, but with significant service-desk-specific limitations

For migrations requiring comment visibility control, the JSM Service Desk API is the right choice — it accepts a public flag on comments. The Jira Cloud REST API gives broader field control. CSV and JSON importers are simpler but make all imported comments public in JSM, which is a deal-breaker if Desk365 private notes must remain internal. (support.atlassian.com)

JSM Project Type Matters

JSM has two project types: Classic (company-managed) and Team-managed (formerly Next-gen). Most migration tooling — including Atlassian's own importers — works reliably only with Classic projects. If your target project is Team-managed, either convert it or create a new Classic project for the import.

Authentication and Rate Limits

JSM Cloud requires an API token generated at id.atlassian.com/manage-profile/security/api-tokens, paired with the admin user's email for Basic Auth.

Rate limiting is the single biggest operational constraint for migration scripts. Jira Cloud enforces three independent rate-limiting systems simultaneously:

• Points-based quota (per-hour): Each API call consumes points based on complexity and data volume.
• Burst rate limits (per-second): Restricts requests per second per endpoint, enforced per-tenant. Uses a token bucket algorithm.
• Per-issue write limits: Restricts how frequently a single issue can be modified.

When you hit a limit, JSM returns a 429 Too Many Requests response with a Retry-After header. Your migration script must implement exponential backoff and read the X-RateLimit-Remaining and Retry-After headers on every response.

Field Mapping: Desk365 to Jira Service Management

This is where migrations succeed or fail. Desk365 and JSM have different field semantics, and a naive 1:1 mapping loses data or creates garbage.

Core Field Mapping

The Description Format Problem

The Jira Cloud v3 REST API requires description and multi-line text fields in Atlassian Document Format (ADF), a JSON-based document structure. Desk365 exports descriptions as plain text or HTML.

You need a conversion layer. A minimal ADF wrapper for plain text:

{
  "type": "doc",
  "version": 1,
  "content": [
    {
      "type": "paragraph",
      "content": [
        {
          "type": "text",
          "text": "Your ticket description here"
        }
      ]
    }
  ]
}

For HTML content with formatting, you need to parse the HTML and build corresponding ADF nodes (headings, lists, code blocks, etc.). Two maintained options:

• @atlaskit/adf-utils — Atlassian-maintained npm package for building and validating ADF documents. Install via npm install @atlaskit/adf-utils. Provides builders, validators, and traversal utilities.
• adf-builder — community-maintained npm package (search npm registry for current version and maintenance status before using in production).

Do not skip ADF conversion — raw HTML dumped into an ADF field renders as literal markup text in the portal. Test your converter against real ticket data, not synthetic examples, before running at scale.

Department-to-JSM Mapping: Decision Table

Desk365 departments are nested inside companies and control ticket-form, knowledge base, and announcement visibility. JSM has no direct equivalent. The right mapping depends on what the department field actually does in your Desk365 environment:

Desk365 Companies → JSM Organizations

Desk365 companies carry domains, contacts, assets, and department structure. JSM organizations are groups of customers shared across service projects. Create JSM organizations via:

curl -u admin@example.com:API_TOKEN \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Corp"}' \
  https://your-domain.atlassian.net/rest/servicedeskapi/organization

Then add customers to the organization:

curl -u admin@example.com:API_TOKEN \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"usernames": ["user@acme.com"]}' \
  https://your-domain.atlassian.net/rest/servicedeskapi/organization/{organizationId}/user

The company→organization mapping works for customer grouping but breaks when the Desk365 company record also drives routing, department logic, or asset ownership. Audit your company records before assuming a direct copy.

CSV vs API: Choosing Your Import Method

Atlassian recommends CSV as the default import format for most tools. That guidance is too broad for JSM migrations from Desk365, because imported CSV/JSON comments become public, request-type behavior matters, and Teams/portal workflows add constraints that basic import docs do not address. (support.atlassian.com)

Use CSV import when the migration is simple

• You are loading ticket shells or history where all comments are safe to expose publicly
• You can prebuild the target project, workflow, statuses, and request types before import
• Attachment files are accessible via HTTP/HTTPS URLs that Jira Cloud can reach
• You do not need to control public vs internal comment visibility

Use API or scripted migration when fidelity matters

• You must control public vs internal comment visibility
• You need request-specific semantics such as serviceDeskId, requestTypeId, or request participants
• You need to migrate knowledge base, assets, customer details, or organization structures alongside tickets
• You need phased backfill plus a short delta sync so the source system can keep running until cutover
• You need to rebuild Teams intake, portal forms, or access rules

Preserving Historical Timestamps

When creating issues via POST /rest/api/3/issue, JSM sets the Created date to the moment of the API call. To preserve historical creation dates, you have two options:

Option 1: Jira CSV/JSON bulk import pipeline — The Jira importer (accessed via Project Settings > Import) can override Created and Updated system fields when the import file includes them in the correct column format. This is the most reliable method for timestamp preservation at scale.

Option 2: Description prepend fallback — For API-driven migrations where bulk import is not used, prepend the original creation date to the issue description:

[Originally created: 2022-11-14 09:32 UTC by jane.smith@acme.com]

<original ticket body>

This preserves timestamp visibility without requiring bulk import infrastructure, at the cost of polluting the description field.

The Jira bulk create endpoint (POST /rest/api/3/issue/bulk) accepts up to 50 issues per request and shares the same field constraints as single-issue creation — it does not bypass timestamp restrictions. Timestamp override requires the importer pipeline specifically.

Step-by-Step Migration Runbook

Step 1: Audit Your Desk365 Data

Before writing any code, inventory everything:

• Total ticket count (active and archived) and date range
• All custom fields in use and their types
• Knowledge base article count, category/folder structure
• Contact and company count, department structure and department manager assignments
• Attachment volume — this drives timeline more than ticket count
• Inbound channels (Teams, email, web forms)
• Custom statuses, groups, categories, subcategories
• SLA configurations and automations
• Survey/CSAT data volume and whether historical scores are needed for compliance

Export a sample CSV and pull a batch via the API to surface unexpected nulls and bad field values before touching production.

Step 2: Model the JSM Target First

Build the target service project before you move history. This is not optional.

• Create a Classic project type
• Define all issue types matching your Desk365 ticket types
• Build the workflow with all needed statuses (JSM will not create missing statuses during import)
• Create custom fields matching Desk365 custom fields (customfield_XXXXX identifiers)
• Set up the priority scheme
• Configure Request Types — map Desk365 types to JSM Request Types, and make sure the Customer Request Type field is populated for portal visibility

For identity management: if your agents authenticate via Microsoft 365, deploy Atlassian Guard (formerly Atlassian Access) and configure user provisioning from Microsoft Entra ID. Force a sync before migrating tickets.

For external customers, create JSM customer accounts via the API before migrating tickets — customer accounts must exist before issues that reference them can be created:

curl -u admin@example.com:API_TOKEN \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "email": "customer@example.com",
    "displayName": "Jane Customer",
    "notify": false
  }' \
  https://your-domain.atlassian.net/rest/servicedeskapi/customer

Set "notify": false during bulk customer creation to suppress welcome emails to thousands of users simultaneously.

Step 3: Extract and Normalize Source Data

Use the Desk365 API v3 for extraction:

curl -X GET "https://yoursubdomain.desk365.io/v3/tickets?include_description=1&ticket_count=100&page=1" \
  -H "Authorization: Bearer YOUR_API_KEY"

Paginate through all tickets. For each ticket, also pull:

• Replies and notes (public and private)
• Attachments — download and store locally, since Desk365 URLs may be behind auth or short-lived
• Contact details for reporter mapping

Desk365 API filters use arrays of string values, and -- represents an unassigned value. Use UTF-8 URL encoding for filter parameters. (help.desk365.io)

Delta sync method: For the cutover delta sync (Step 7), use the Desk365 API updated_since filter parameter to pull only tickets modified after your initial extraction timestamp. The parameter accepts an ISO 8601 date string. Record the exact UTC timestamp when your initial extraction completes — this becomes the updated_since value for the delta run. If you miss the sync window or the delta takes longer than expected, run a second delta using the timestamp from when the first delta started.

Desk365 also supports webhooks for real-time ticket event notifications. For migrations where the cutover window is under 4 hours, polling with updated_since is simpler. For longer parallel-run periods (days to weeks), configure Desk365 webhooks to write ticket update events to a queue, then replay that queue during cutover. Webhook events are not a substitute for a full extraction — use them only for the delta.

Step 4: Transform and Map Data

This is the bulk of the engineering work:

• Convert descriptions from HTML/text to ADF
• Map Desk365 statuses to JSM workflow statuses
• Map Desk365 agents to JSM user accountId values (build a lookup table by email)
• Map Desk365 contacts to JSM customers
• Map custom fields by type (dropdowns need option IDs, not display values)
• Distinguish private notes from public comments
• Preserve original Desk365 ticket numbers in a custom field for cross-reference

desk365:
  company_name: Acme
  group: IT
  category: Access
  sub_category: VPN
  cf_department: Finance
  ticket_number: 48219
 
jsm:
  organization: Acme
  request_type: Access Request
  component: VPN
  labels:
    - desk365-import
  custom_fields:
    source_ticket_number: 48219
    source_department: Finance

That pattern keeps the original Desk365 identity visible inside JSM even when you have to remodel the operational meaning of the data.

Step 5: Load Data in Dependency Order

A reliable load sequence: customers/organizations → tickets → comments → attachments → request participants → knowledge base → assets.

For each ticket:

1. Create the issue with core fields, including the Customer Request Type field
2. Add comments with correct public/private visibility via the request comment API
3. Upload attachments via the attachment endpoint with X-Atlassian-Token: no-check header
4. Transition the issue to the correct status via the transition API

curl -D- -u admin@example.com:API_TOKEN \
  -X POST \
  -H "X-Atlassian-Token: no-check" \
  -F "file=@/path/to/local/file.pdf" \
  https://your-domain.atlassian.net/rest/api/3/issue/ITSM-142/attachments

For comments, use the JSM request comment endpoint to control visibility:

curl -u admin@example.com:API_TOKEN \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "body": "This is an internal note.",
    "public": false
  }' \
  https://your-domain.atlassian.net/rest/servicedeskapi/request/{issueIdOrKey}/comment

For status transitions: JSM enforces workflow transition rules. You cannot set a ticket directly to "Resolved" if the workflow does not allow a transition from the initial status. Either use the transition API to walk issues through valid paths, or temporarily simplify the workflow during import. The bulk import pipeline can bypass transition rules; the standard REST API cannot.

Step 6: Migrate Knowledge Base Articles

Desk365 knowledge base articles follow a Category → Folder → Article hierarchy. JSM uses Confluence, which has a Space → Page hierarchy. This is a separate migration phase — do not combine it with ticket migration.

Hierarchy mapping:

Step-by-step:

1. Extract all categories, folders, and articles via the Desk365 API (/v3/kb/categories, /v3/kb/folders, /v3/kb/articles)
2. Create the Confluence Space (or identify the target Space if using an existing one)
3. Create parent pages for each Desk365 category, then child pages for each folder
4. For each article, convert the HTML body content to Confluence storage format — an XHTML-based XML format that Confluence uses internally
5. Create pages via POST /wiki/rest/api/content with the converted content

Confluence storage format is distinct from both ADF and standard HTML. A minimal page creation payload:

{
  "type": "page",
  "title": "Article Title",
  "space": { "key": "SUPPORT" },
  "ancestors": [{ "id": "123456" }],
  "body": {
    "storage": {
      "value": "<p>Article body in Confluence storage format XHTML.</p>",
      "representation": "storage"
    }
  }
}

For articles with complex HTML (tables, code blocks, images, embedded videos), you need an HTML-to-storage-format conversion step. The Confluence REST API provides a conversion endpoint: POST /wiki/rest/api/contentbody/convert/storage with the body {"value": "<your HTML>", "representation": "wiki"} — this converts wiki markup to storage format, but HTML requires preprocessing first.

For images and file attachments within articles: download them from Desk365, upload to Confluence as page attachments via POST /wiki/rest/api/content/{pageId}/child/attachment, then rewrite the image src URLs in the article body to point to the Confluence attachment URLs before creating the page.

After creation, link the Confluence Space to your JSM service project under Project Settings > Knowledge Base. This makes articles searchable from the JSM customer portal.

Step 7: Validate

Do not stop at record counts. Run these checks:

• Total ticket count matches (source vs. target, split by active and archived)
• Random sample of 50+ tickets checked for field accuracy
• All comments present, in correct order, with correct public/private visibility
• Attachments downloadable
• Status distribution matches source
• Custom field values spot-checked
• Knowledge base articles render correctly in Confluence and are surfaced in the JSM portal
• CSAT custom fields populated on surveyed tickets

project = SUPPORT AND labels = desk365-import
project = SUPPORT AND statusCategory != Done

Also compare volumes by status, month, and company/organization to catch bad status mapping and incomplete batches.

Recreating Microsoft Teams Workflows

Desk365's primary selling point is deep Teams integration. To replicate this in JSM, configure Atlassian Assist (formerly Halp, now natively integrated into JSM):

1. Install the Jira Service Management app in your Microsoft Teams tenant
2. Configure Request Channels — map specific Teams channels to specific JSM Request Types
3. Train users on the new behavior: Assist requires an emoji reaction (🎫) or direct bot interaction to create tickets

Key constraints:

• A Jira site can connect to only one Microsoft Teams tenant at a time (support.atlassian.com)
• Request types with unsupported required fields will block chat intake — design your request types with this in mind
• Each service project gets one agent channel in Teams

Common Failure Modes

Missing descriptions: Forgetting include_description=1 on the Desk365 API. Tickets arrive in JSM with empty bodies.

Missing archived tickets: Exporting only the standard ticket view and forgetting that archived tickets require a separate export. (help.desk365.io)

Private notes exposed: Importing Desk365 history through Jira CSV or JSON importers makes all comments public. Use the JSM request comment API with "public": false when private note visibility matters. (support.atlassian.com)

ADF conversion errors: Raw HTML in JSM description fields renders as unreadable markup. Test your converter against real ticket data using @atlaskit/adf-utils validation before running at scale.

User mismatches: Desk365 agents identified by name/email will not match JSM's accountId system. Build a lookup table first. If an agent does not have a JSM license, their tickets land as unassigned.

Status transition failures: JSM enforces workflow transitions and will not create missing statuses during CSV or JSON import. Statuses must already exist in the workflow before any import begins.

Request Type omission: Tickets imported without a Customer Request Type value will not appear in the customer portal, and end-users will not receive email notifications.

Rate limit cascades: Hitting Jira's burst limits mid-migration and not handling 429 responses correctly. The script retries immediately, gets throttled harder, and the migration grinds to a halt. Always read Retry-After before retrying.

Attachment URL failures: Desk365 attachment URLs may be behind auth or short-lived. Stage attachments locally before import — do not assume Jira Cloud can reach Desk365 attachment URLs directly.

Delta sync window missed: If the delta sync takes longer than expected and new tickets are created during the delta run, you need a second pass. Record the UTC timestamp when each extraction starts, not when it ends, to ensure complete coverage.

KB article image links broken: Desk365 KB article images are hosted on Desk365 infrastructure. After migrating article HTML to Confluence without re-hosting the images, they will break when Desk365 is decommissioned. Download, re-upload to Confluence, and rewrite URLs before cutover.

SLA data loss: Historical SLA data cannot be cleanly migrated into JSM's native SLA engine, which calculates SLAs dynamically based on JQL calendars and issue events. Extract Desk365 SLA metrics and map them to read-only custom fields in JSM for compliance reference.

Customer creation order violation: Creating issues before customer accounts exist causes reporter/requester fields to fail silently or default to the API user. Always create customers first.

Welcome email flood: Creating JSM customer accounts via API with "notify": true sends a welcome email to every imported customer. Set "notify": false for bulk customer creation.

Cutover Strategy

A helpdesk migration is not a one-shot event. IT teams cannot stop supporting users during the transition.

1. Initial sync: Migrate historical data (closed tickets, old attachments, inactive users) over several days.
2. Validation: Verify data integrity, ADF formatting, comment visibility, and attachment accessibility.
3. Cutover window: Choose a low-traffic period.
4. Delta sync: Pull only tickets created or updated since the initial sync using the updated_since filter on the Desk365 API. Record the start timestamp of the initial sync as your delta boundary.
5. Channel cutover: Update email forwarding rules to point to JSM's email handler. Remove the Desk365 bot from Teams and deploy Atlassian Assist to all relevant channels.
6. Make Desk365 read-only: Only after validation passes on the delta sync.

A pragmatic approach to historical data volume:

• Migrate open and pending tickets in full — all comments, attachments, custom fields
• Migrate closed tickets from the last 12–24 months with reduced detail — subject, description, status, dates
• Archive older closed tickets as CSV/PDF exports stored in a shared drive or Confluence space

This cuts migration volume significantly while keeping actionable history accessible.

When to Use a Tool vs Custom Scripts

Third-party tools like Help Desk Migration (Relokia) offer wizard-based field mapping and basic transformations. Good for straightforward migrations with standard fields and no private note sensitivity.

Custom scripts are necessary when:

• You must control public/private comment visibility
• You have deeply nested custom fields or multi-level Desk365 fields
• You need precise control over timestamps and internal note handling
• Your ticket volume exceeds 50,000+ and you need optimized batching
• You need to maintain original ticket IDs as references
• You are migrating KB articles with embedded images that need URL rewriting
• You have department-based access rules that require project-level restructuring in JSM

The tradeoff is engineering time. A tool gets you 80% there in a day. Custom scripts get you to 100% but take one to two weeks of development and testing.

The Hard Parts Are Not the Records

The mistake teams make is assuming this migration is just a record export. The actual hard parts are comment visibility, access-model redesign, Teams channel behavior, ADF conversion, Confluence storage format conversion for KB articles, delta sync timing, and cutover control.

The extraction side from Desk365 is straightforward. The JSM side — particularly the interaction between request types, customer portal visibility, comment privacy, and organizational structure — is where careful engineering matters. Plan for the access model before writing a single migration script. Every other problem is solvable mid-flight; a misdesigned permission model requires rebuilding the target project.