YouTrack Cloud
 
2025.1
  1. Administration
  2. Integrations
  3. Imports
  4. Import from Jira Service Management

Import from Jira Service Management

Last modified: 26 March 2025

An import from Jira Service Management (JSM) lets you migrate your service desk projects, requests, comments, users, and other data from Jira Service Management to YouTrack directly as help desk projects.

A setup wizard navigates you through the import configuration process. It prompts you to enter the connection settings. You can map projects in Jira Service Management to exiting projects in YouTrack or create new projects.

warning

License Limitations

References to users in Jira Service Management requests are mapped to existing accounts in YouTrack. If a match is not found, a new user account is created.

Imported users are allocated a license according to your subscription plan. For standard users and agents that exceed your per-user license limit, the imported users/agents are flagged as banned.

For more information, see Ban User Accounts and Manage User Accounts for Agents.

Prerequisites

Before you import projects from Jira Service Management to YouTrack, check the following requirements:

  • If you're importing from Jira Cloud, you've exported a copy of the user data for your Jira Service Management instance as a CSV file.

  • Your Jira Service Management instance allows remote API calls.

  • Your user account in Jira Service Management has administrative permissions. If you connect to the Jira Service Management instance with an account that is not assigned an administrator role, you can't import groups and related data.

  • You have direct access to log in to the source application using a password or token.

    YouTrack's import engine doesn't support authentication through external authentication modules.

Import Details

If the Jira Service Management database contains references to entities that don't exist in YouTrack yet, they're created. The YouTrack user account you use to run the import should have enough permissions to create all imported entities. We recommend using an account with a System Admin role or the Low-level Admin Write permission to run the import.

Imported Entities

Here is the list of entities that are imported from Jira Service Management and their mapping to YouTrack entities:

Entity in Jira Service Management

Entity in YouTrack

Jira Service Management Projects

Helpdesk Projects

Users

Users

Groups and memberships

Groups and memberships

Requests

Tickets

Issue links

Links

Attachments

Attachments

Request types, statuses, resolutions, priorities

Custom fields and their values

Custom fields

Custom fields

Labels

Tags

Note that YouTrack imports only those labels that mark at least one request in Jira.

Logged work

Work items

Comments

Comments

Request history

Ticket history

Watchers

Watchers

Voters

Voters

note

The following entities aren't imported from Jira to YouTrack:

  • Boards

  • Dashboards

  • Roadmaps

  • Reports

  • Labels that don't mark any requests in Jira

  • Mentioned users

Importing User Data

This integration also imports user accounts that are stored in the Jira Service Management instance. The same values for users who created, updated, added comments to, and are assigned requests in Jira Service Management are set to the corresponding user accounts in YouTrack.

  • Jira Cloud limits the amount of user data that is accessible through a programmatic interface. To successfully map user activity in Jira Service Management to imported tickets in YouTrack, you need to upload a copy of the dataset for Jira Service Management users to YouTrack before you start importing request data.

    During setup, you're asked to upload a CSV file that contains information about the user accounts that are currently stored in your Jira Service Management database. If you don't have access to download this information, you will not be able to import requests from your Jira Service Management instance.

  • Self-hosted Jira Server installations aren't subject to this limitation. This means that you don't have to manually export and upload user data before you can import your requests into YouTrack.

To export user data for your Jira Service Management instance:

  1. Navigate to the Directory section in Atlassian Administration and open the Users page.

  2. From the More menu in the upper-right corner of the header, click the Export users button.

    The option to export users in Atlassian Administration.

    • The Export users to CSV page opens.

    Select users to export page in Atlassian Administration.

  3. Use the following guidelines to configure the user selection for export:

    Setting

    Description

    Users

    Select whether you want to export all users on the site or only from selected groups. Your selection should include all users who're associated with any request-related events in the imported projects.

    User status

    Select whether you only want to export active users or all users. For best results, we suggest exporting all users.

    Additional data

    Select whether to export group membership and product access data. The data included in the user export file when these options are enabled aren't required for importing requests into YouTrack.

  4. Click the Export users button.

    • Atlassian generates a CSV file that contains user data from your Jira Service Management instance and sends it to your email.

  5. Open your mailbox and download the CSV file with the user data.

Imported User Type

Jira Service Management and YouTrack both have a specific user type designated as Agent. The agent role identifies that the user has permission to work with the service desk project.

For more information, see Manage User Accounts for Agents.

Jira Service Management to YouTrack user types:

Jira Service Management User Type

YouTrack User Type

User (agent)

Agent

All other Jira Service Management user types

Standard user

When a user with the type User (agent) is imported from Jira Service Management, and YouTrack finds an existing matching account, the YouTrack user's type is set to Agent.

If the number of Agent type users exceeds your YouTrack license limit, those users, which would be set as Agent, are set as Standard user. If the number of Standard user type users exceeds your YouTrack license limit, those imported users are set as Banned and can't access the YouTrack platform until the ban is lifted.

For more information, see User Type Overview and Ban User Accounts.

Jira Service Management Account Authentication

When you import data from a Jira Server installation, YouTrack automatically creates and enables a Jira authentication module. The authentication module uses the same credentials that are used to authenticate the connection to the server and import requests.

This means that imported users can use their Jira Service Management account credentials to log in to YouTrack. To learn more about this authentication module, see Atlassian Jira Auth Module.

note

Availability

The Jira authentication module is only supported for connections to Jira Server installations. Connections to Jira Cloud aren't allowed.

User Data Synchronization

YouTrack only supports continuous import from Jira Server installations. Automatic synchronization of user data between YouTrack and Jira Cloud is not supported.

If you activate continuous import from a Jira Cloud instance, you risk importing changes that were made by users who weren't included in the original dataset that you used to import your first batch of issues. If a user account that wasn't included in the original user dataset reports activity in an imported issue, this activity is assigned to an undefined user account in YouTrack.

Continuous issue import from Jira Cloud is only recommended when the user base in the Jira Service Management instance is relatively static. If you want to import issues from a Jira Cloud instance continuously, we recommend that you leave the Continuous import setting switched off and follow this procedure instead:

  1. Whenever you're ready to synchronize the Jira Cloud instance with YouTrack, export a fresh copy of the user dataset from the Atlassian Administration site.

  2. Upload the dataset to the integration settings in YouTrack.

  3. Use the Resume option to synchronize the data.

Inconsistent synchronization of user data can quickly cause enormous problems. Before you import your issues from Jira Cloud, we strongly suggest that you wait until you're ready to switch completely from Jira Service Management, transfer your user data, and migrate all of your issue-tracking activity to YouTrack. As much as we would like to support continuous import, the current limitations of the API for Jira Cloud make it difficult to set up a seamless integration.

Set up an Import from Jira Service Management

Before you add a new import configuration, prepare the credentials that will grant access to your Jira Service Management instance. You will need these credentials for authorization when setting up the import in YouTrack.

warning

Two-factor authentication

Import from Jira Server requires basic authentication with a username and password. If you attempt to import issues using an account that requires two-factor authentication, the import will fail.

To overcome this limitation, you can either disable 2FA for the Jira account used for authentication or authenticate with an account that doesn't require second-factor authentication.

Depending on the deployment type of your Jira, you will need different credential combinations:

Jira Type

User Identifier

Authentication Method

Jira Server

Username

Password

Jira Cloud

Username or email

API token.

For details on creating an API token, see Create an API Token for Jira Cloud.

If you're using Jira Cloud, export user data before configuring an import. For details on processing user data, see Importing User Data.

Create an API Token for Jira Cloud

To set up an import of articles from Jira Cloud, first, you need to create an API token for your Atlassian account.

To create an API token for the Atlassian account:

  1. Log in to the Atlassian account settings with an account that is granted administrative permissions.

  2. Click the Create API token button and provide a label for the token.

  3. Click Create.

    • The new API token is added to the list.

    The list of API tokens.

For more details on creating API keys for Atlassian products, refer to the Atlassian documentation.

Configure an Import from Jira Service Management in YouTrack

The setup wizard guides you through the process of connecting to your Jira Service Management account, mapping your Jira Service Management projects to YouTrack, and importing the selected data.

To set up an import from a Jira Service Management instance:

tip

Requires permissions: Low-level Admin Write

  1. From the Administration menu, select Integrations > Imports.

  2. Click the New import button.

    • The New Import dialog opens.

    New Import dialog.

  3. Select Jira Service Management.

    • Settings for a New Import from Jira Service Management are displayed.

    New Import from Jira dialog.

  4. Enter values for the following settings:

    Setting

    Description

    URL

    Enter the base URL of the Jira Service Management instance.

    Username or email

    Enter the username of the account that is used to log in to the Jira Service Management instance. This account must have administrative privileges in Jira to import projects, users, groups, and related data.

    • For Jira installations, enter the username. Don't enter an email address.

    • For Jira Cloud, you can use an email address as the username.

    Password or API token

    For Jira Server, enter the password for the account that is used to log in to the Jira instance.

    For Jira Cloud, create an API token for your Atlassian account and paste it into the input field. For details, see Create an API Token for Jira Cloud.

    SSL key

    If your Jira instance requires client SSL authentication, activate the Use SSL key for client authentication switch. You can then select the SSL key that identifies your YouTrack server from the list.

    The list only displays SSL keys that have already been imported into YouTrack. To learn how to generate and upload SSL keys, see SSL Keys.

  5. Click the Next button.

    • The second set of import settings is displayed.

    New Import from Jira step two.

  6. Enter values for the following settings:

    Setting

    Description

    User data

    (Jira Cloud only) Click the Upload user data button and select the CSV file that contains a copy of the user data from your Jira Service Management instance.

    To learn more about exporting user data from Jira Service Management, see To export user data for your Jira Service Management instance:.

    Continuous import

    If you want to synchronize changes applied to requests in the Jira Service Management instance with tickets that have been imported into YouTrack regularly, activate this switch.

    When this option is enabled, YouTrack checks the Jira Service Management instance for changes in the selected projects every two minutes. (YouTrack checks every 10 minutes for Free YouTrack Cloud accounts). Issues that are added or updated since the previous import are processed and updated in YouTrack.

    Continuous import from Jira Cloud can lead to inconsistent synchronization of user data. If the collection of users in your Jira instance is updated regularly, we strongly suggest that you leave this setting switched off and import changes manually. To learn more, see User Data Synchronization.

    Project mapping

    Select source and target projects for import. For details, see Project Mapping.

  7. Expand the Manage import for optional datasets section. Here you can configure the import engine to ignore certain parts of the source database during import.

    Setting

    Description

    Issue history

    Disable this toggle to ignore historical changes of issues during import.

    Issue links

    Disable this toggle to ignore links between issues during import.

    By default, these toggles are enabled. This means that YouTrack will pull historical changes and issue links from the import source if the import script supports it.

    note

    If the import script doesn't handle issue history or issue links, enabling any of these toggles will not result in importing these datasets. To import issue history or issue links, update the import script.

  8. Click the Start import button.

    • YouTrack creates new helpdesk projects and imports data to the existing ones according to the configured project mapping.

    • YouTrack imports requests, comments, users, groups, and related data from the selected Jira projects to the target YouTrack projects.

    • If the Continuous import option is enabled, YouTrack will periodically check target Jira Service Management projects for updated and new issues.

When you've set up an import, it appears in the Imports list. To view the configuration and import details, select the import configuration from the list.

Import results

In the details sidebar, YouTrack shows import status, the date and time of the last import, and details on the data that was imported. If there are any problems encountered during import, the error messages are displayed here.

Click the Resume button in the toolbar to explicitly start polling for changes and importing updates from the source Jira project.

You can also download the import log file to study and investigate when needed.

Project Mapping

On the final step of the import setup, you can select those Jira Service Management projects that you want to import to YouTrack. You can also decide whether to create a new project for the import or import data into an existing project in YouTrack.

YouTrack recognizes when a web address has already mapped a source project by a previous import. Imported source projects that have already been mapped in YouTrack aren't selectable. You can create multiple import jobs from the same source without importing duplicate data.

Project Mapping

To configure project mapping:

  1. Locate those Jira Service Management projects that you want to import.

    Use the filter bar on the right to filter projects by name.

  2. Select the projects that you want to import. Select the option at the top of the list to import all available Jira projects.

  3. Select a target YouTrack project for each Jira Service Management project.

    • When loading the list of Jira Service Management projects for mapping, YouTrack checks for existing YouTrack projects with corresponding names. If it finds a YouTrack project with the same name as the Jira Service Management one, YouTrack suggests it as the target project.

    • If there is no existing YouTrack project with the corresponding name, YouTrack suggests creating a new one.

  4. If you want to change a target project, select another option from the corresponding dropdown on the list.

  5. Click Start import to finalize import setup and start the import.

Import Options

After the initial import, the following controls are available in the sidebar:

Import results

Control

Description

Disable/Enable

Disable or enable the import. This lets you keep the settings for an import even if you aren't using it.

Resume

Immediately imports any changes made in the selected Jira Service Management projects after the previous import.

Edit

Opens the integration settings page in edit mode. Use this option to connect to a different Jira Service Management instance, update the login credentials, update project mapping, or upload a fresh copy of the CSV file that contains user data from your Jira instance.

Delete

Deletes the current import settings. Jira entity IDs that are attached to imported issues are also removed. Projects, requests, users, and groups that were imported from the connected Jira Service Management instance aren't affected. If you delete the import settings and connect to the same Jira Service Management instance, the issues are re-imported into existing projects with new issue IDs.

Continuous import

YouTrack periodically checks the target Jira Service Management instances and imports updated and new items created since the last sync.

The continuous import feature is only recommended for Jira Server. Continuous import from Jira Cloud can lead to inconsistent synchronization of user data. If the collection of users in your Jira instance is updated regularly, we strongly suggest that you leave this setting switched off and import changes manually. To learn more, see User Data Synchronization.

Download import log

Downloads the import log. Use this option to view and investigate errors that occurred during import.