YouTrack Cloud 2023.3 Help

Import from Jira

YouTrack lets you connect to a Jira instance. This integration lets you perform the following tasks:

  • Import existing projects, users, groups, and group memberships from Jira.

  • Update previously imported projects to apply changes to issues that were made in Jira. New issues and changes that are applied to issues in the Jira project since the last import are added to YouTrack.

The visibility setting for issues that are imported from Jira with a configured Security Level is set to the Project Admins group.

Prerequisites

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

  • If you are importing from Jira Cloud, you have exported a copy of the user data for your Jira instance as a CSV file.

  • The projects that you want to import were created in Jira version 5 or later.

  • Your Jira instance allows remote API calls.

  • Your user account in Jira has administrative permissions. If you connect to the Jira instance with an account that is not assigned an administrator role, you cannot 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 database contains references to entities that do not exist in YouTrack yet, they are 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 and their mapping to YouTrack entities:

Entity in Jira

Entity in YouTrack

Projects

Projects

Users

Users

Groups and memberships

Groups and memberships

Issues

Issues

Issue links

Issue links

Attachments

Attachments

Issue 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 issue in Jira.

Logged work

Work items

Comments

Comments

Issue history

Issue history

Watchers

Watchers

Voters

Voters

Importing User Data

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

  • Jira Cloud limits the amount of user data that is accessible through a programmatic interface. In order to successfully map user activity in Jira to imported issues in YouTrack, you need to upload a copy of the dataset for Jira users to YouTrack before you start importing issue data.

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

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

To export user data for your Jira 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

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

    User Status

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

    Additional Data

    Choose whether to export group membership and product access data. The data that is included in the user export file when these options are enabled are not required for importing issues into YouTrack.

  4. Click the Export users button.

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

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

Jira 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 issues.

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

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 were not included in the original dataset that you used to import your first batch of issues. If a user account that was not 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 instance is relatively static. If you want to import issues from a Jira Cloud instance on a continuous basis, 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 are ready to switch completely from Jira, 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

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

Depending on the deployment type of your Jira, you'll 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 in YouTrack

The setup wizard guides you through the setup process.

To set up an import from a Jira instance:

  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.

    • Settings for a New Import from Jira are displayed.

    New Import from Jira dialog.
  4. Enter values for the following settings:

    Setting

    Description

    URL

    Enter the base URL of the Jira instance.

    Username or email

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

    • For Jira installations, enter the username. Do not 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 instance.

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

    Continuous import

    If you want to synchronize changes applied to issues in Jira instance with issues that have been imported into YouTrack on a regular basis, activate this switch.

    When this option is enabled, YouTrack checks the Jira 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 on a regular basis, 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.

  8. Click theĀ Start import button.

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

    • YouTrack imports issues, 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 projects for updated and new issues.

When you have 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 have an option to select those Jira projects that you want to import to YouTrack. You can also choose whether to create a new project for the import or import data into an existing project in YouTrack.

Project Mapping

To configure project mapping:

  1. Locate those Jira 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 project.

    • When loading the list of Jira 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 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:

Control

Description

Resume

Immediately imports any changes that were made in the selected Jira projects after the previous import.

Edit

Opens the integration settings page in edit mode. Use this option to connect to a different Jira 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, issues, users, and groups that were imported from the connected Jira instance are not affected. If you delete the import settings and connect to the same Jira instance, the issues are re-imported into existing projects with new issue IDs.

Download import log

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

Last modified: 29 February 2024