YouTrack integration for issues

Issues of Meliora Testlab’s projects can be integrated with JetBrains YouTrack issue tracker which allows for realtime one-way integration. In this scenario, YouTrack acts as a master repository for your project’s issues.

• How it works

  When integrated with YouTrack, the YouTrack is a master repository for issues. All issues are added to YouTrack and the changes of the issues are replicated back to Testlab with a polling protocol. As the data for issues is replicated back to Testlab, it allows you to do real-time analysis and reporting against your project’s issues in Testlab. The links between Testlab’s and YouTrack’s issues are maintained in Testlab’s database.

  When configured for this issue tracking integration, the behavior of Testlab’s user interface is changed as follows:

  • For fields pushed from YouTrack, Testlab’s editing views become read-only. Fields not mapped from YouTrack are still editable in Testlab.
  • When adding a new issue, the user is automatically transferred to YouTrack to add the new issue. When returning, the user is asked for the YouTrack bug identifier and when entered, the issue is fetched from YouTrack and added to Testlab’s database.
  • An existing bug in YouTrack can also be linked to Testlab. When done so, the user is asked for the issue ID and the corresponding bug is then fetched from YouTrack and added to Testlab’s database.
  • When viewing an issue, the view contains a button that can be pressed to easily open up the issue in YouTrack.
  • When commenting on an issue, the user is automatically transferred to YouTrack to add the comment.

  As a background job, YouTrack is polled periodically for any changes in the bugs. By default, this happens once every 5 minutes.

  • When polled, the data for all bugs already linked in Testlab are fetched and their data is refreshed in Testlab’s database.
  • If the integration is configured to delete the removed issues from Testlab, all bugs which seem to be deleted from YouTrack are also deleted from Testlab.

  For details on what data is synced exactly, please see below.

• Prerequisites

  1. You are using YouTrack and the YouTrack is accessible over the network. This means, that your YouTrack must be accessible from the server(s) Testlab is running on.
  2. You have a YouTrack authentication token associated with a user that has required privileges (read issue, read issue comments, read issue attachments).

   

• How to get started

  To get started with integration follow the steps described below. If you have questions about these instructions or any problems with the set up please feel free to open up a support ticket in Testlab. We are happy to help you with your setup!

   

  1. Preliminary configuration for YouTrack

  Integration needs access to YouTrack API. This requires an authentication token associated with a YouTrack user. Access to YouTrack via API is restricted to by the same privileges as the authenticated user has.

  The YouTrack user should have privileges at least to view issues, comments. Default roles Issue Viewer and Developer should work.

  You can add an authentication token for a user on the user’s authentication tab. Click Add Token and make sure the token has at least scope YouTrack. Copy the token when prompted.

  See also YouTrack documentation on authentication tokens: https://www.jetbrains.com/help/youtrack/standalone/Manage-Permanent-Token.html#

  Also, note that TestLab – YouTrack integration doesn’t currently support OAuth2.

• Integrate Testlab project with YouTrack

  For all Testlab projects which you prefer to integrate with your YouTrack, some configuration steps need to be taken.

  • Log on to your Testlab (preferably as an administrator to make sure you have the needed permissions for the configuration) and select Testlab > Manage projects…
  • Select the project you want to integrate with your YouTrack.
  • Choose the Integrations tab, Click Edit and as an Issue tracker, choose “YouTrack” and enter the following:
    • YouTrack URL: https://example.myjetbrains.com/youtrack
      Absolute URL of the YouTrack you are integrating the project with. This is typically the address you access your YouTrack with your browser.
    • API token: your YouTrack API token
      The API token in your YouTrack you set up earlier. Make sure to copy and paste the API token exactly as it is set up in your YouTrack.
    • Field mappings
      Defines how YouTrack customizable fields are mapped to TestLab fields. A YouTrack field can be mapped to multiple TestLab fields. Not all TestLab fields are supported, and the integration attempts to map unrecognized fields as TestLab custom fields.
    • Statuses: status mappings
      Defines how the issue statuses you have in your YouTrack are mapped to Testlab’s issue workflow statuses. The mappings can be used to map the statuses between the systems if the workflow statuses in your Testlab does not match the statuses in your YouTrack. The default values are provided to match default values from YouTrack to Testlab’s default issue workflow.
      The mappings are optional: If a status in your YouTrack is not mapped, by default, the integration tries to match the status to identical status in your Testlab’s workflow. The comparison is made in a case-insensitive manner by comparing the labels of the statuses.
    • Priorities: priority mappings
      Similarly to the statuses, this option defines how the issue priorities in your YouTrack are mapped to Testlab’s priorities. The default values are provided to match default values from YouTrack to Testlab’s defaults.
    • Resolutions: resolution mappings
      Similarly to the statuses, this option defines how the issue resolutions in your YouTrack are mapped to Testlab’s priorities. The default values are provided to match default values from YouTrack to Testlab’s defaults.
    • Severities: severity mappings
      Similar to the other mappings, the setting defines how issue values are mapped to Testlab’s issue severities. Note that the severity-field isn’t mapped by default.
    • Delete linked issues removed from YouTrack?: yes or no
      If checked, the issues replicated to Testlab which are removed from YouTrack are also removed from Testlab’s database.
  • Click the “Verify Configuration” button to check that your YouTrack settings are valid. We will try to contact your YouTrack from the address provided with the API token credentials by calling the REST API.
  • Click Save and you are done.
  • To verify that the integration works as expected
    • In Testlab, change your project to the one you integrated with if you are not already logged on to it, go to Issues view and click Add issue…
    • Choose to Add a new issue in your YouTrack and a new browser window should open up which points to your YouTrack. Log in if needed, and enter some issue details for testing. Add and save a new issue to your YouTrack.
    • Change view back to Testlab and enter the ID of the bug just added. Testlab should now fetch the issue from YouTrack and it should be visible in the Issues view in Testlab.

• Default mappings of data between YouTrack and Testlab

  When configured, the integration will map the YouTrack fields to Testlab’s issues as (fields in cursive are customizable field mappings):

  YouTrack field(s)	Testlab field (or assets)
  Summary	Title
  Description	Description
  Created at	Created
  Reporter	Created by
  Updater	Updated by
  Resolved (date)	Resolved
  Comments	Comments
  Attachments	Attachments
  Type	Type
  Assignee	Assigned to
  Affected versions	Detected in version
  Fix versions	Resolved in version
  State	Resolution
  State	Status
  Priority	Priority

  When mapping the data, the following logic is respected:

  • When mapping users (such as Reporter to Testlab’s assignee), the mapping is done primarily by the e-mail address provided by YouTrack and if this fails, by the user name. For the field to be mapped correctly, a matching user should be found in Testlab by going through the project’s users.
  • All public comments from YouTrack are replicated to Testlab as comments.
  • All attached files from YouTrack are replicated as attachments to Testlab.
  • Customizable field mappings use the field names as written on YouTrack. TestLab currently recognizes the following fields for YouTrack integration: priority, status, resolution, assigned to, resolved in, detected in version, severity, environment. Any unrecognized fields are mapped to TestLab custom fields if the project contains a field with that name.
  • YouTrack fields that can have multiple values that are mapped to a TestLab field with a single value will only pick a single value to display, e.g. latest version. When mapped to a TestLab custom field all values will be included.

• Frequently asked questions

  In short – what exactly does this do?

  You can integrate your YouTrack issue tracker in a way, in which issues are created and updated in YouTrack and pushed to your Testlab project as issues. Issue fields that are pushed from YouTrack cannot be edited directly in Testlab but fields, which are not pushed (such as targeted milestone, related test case, etc) can still be edited in Testlab.

   

  From where exactly do I set this up with?

  Log in to your Testlab project, select Testlab > Manage project(s)… and choose the Integrations tab. All integrations which can be taken in use by yourself are configured per project from this view. Check the pre-requisites and follow the instructions above in this document to set up the integration.

   

  I’m using custom workflows, how exactly can I set them up?

  It is a good idea to have the same workflow statuses for assets in both Testlab and YouTrack. This way the statuses map to each other (with no need to map them by hand) and for users, this is most likely the most intuitive way to work with issues anyway.