# Jira Virtuoso App

Jira logo with Virtuoso bot

The Jira Virtuoso App enables creating and assigning Jira issues to execution results in Virtuoso.

Jira is an issue and project tracking platform that "helps teams plan, assign, track, report, and manage work and brings teams together for everything from agile software development and customer support to start-ups and enterprises" [1].

For more information on Jira, visit the product page of Jira.

Information regarding custom fields

Currently, the Jira Virtuoso App does not support required custom fields on Jira issues.

# Setup requirements

For the Jira Virtuoso App setup, you will need either a Jira Cloud (recommended) or Data Center / Server instance.

Dedicated user in Virtuoso

We recommend that you create a dedicated app user in Virtuoso for the Jira Virtuoso App, and share with it the projects to be tracked with write access.

Dedicated user in Jira, ownership and webhooks

We recommend that you create a dedicated user in Jira with administrative privileges on the projects you want to see listed.

Administrative privileges are necessary to automatically set up webhooks, which are used in the Jira to Virtuoso communication. If webhooks are not correctly configured, you will not receive updates to the tickets in Virtuoso when changes are made in Jira.

The user account used for setting Jira Virtuoso App up will be associated with the operations executed, for instance, the app will only be able to list projects that are visible to that user.

Important note about moving an issue to a different project

Moving a Jira issue to a different project may break the updates in Virtuoso as the target project may not have the necessary webhooks set up. To keep the updates working, before moving the issue, make sure that a ticket of that project already exists in Virtuoso; if there is not, create or assign a ticket in Virtuoso that uses that Jira project to set up the required webhooks automatically.

Virtuoso requires the following information to be able to connect to your team's Jira instance:

# Cloud instance

  • Your Jira instance URL;
  • The email associated to the JIRA account;
  • An API token of the same Jira account;
  • Specifying that the Jira Instance is CLOUD.

To generate an API token for a Jira account, please use the following guide: Manage API tokens for your Atlassian account.

# Data Center / Server instance

  • Your Jira instance URL;
  • The email associated to the JIRA account;
  • A personal access token of the same Jira account;
  • Specifying that the Jira Instance is SERVER.

To generate a personal access token for a Jira account, please use the following guide: Using personal access tokens.

Supported Jira Data Center / Server versions

Currently, Virtuoso only supports Jira Data Center / Server version 8.20.15 and higher

# Application setup

To install the Jira Virtuoso App follow the steps described in Installing an app.

User permissions

Although it is not mandatory, it is strongly advised that you create a new Virtuoso user dedicated to this application: Virtuoso projects shared with this application user will have the application enabled.

Label

Administrative privileges are necessary to create a new label in Jira, which is used when creating a Jira issue from Virtuoso. If Virtuoso tries to create an issue with a non existing label, the creation will fail in Jira. You can leave the label configuration field empty in order to not include any label with issues created from Virtuoso. Jira does not allow labels to have spaces.

To configure the app, follow these steps:

  1. Fill in the Jira URL field with the URL to your team's Jira instance;
  2. Fill in the Jira user email field with the email of the account you want to link to the operations;
  3. Fill in the Jira API token field with an API token of the Jira account you want to link;
  4. Fill in the Jira Instance Type field with CLOUD;
  5. (Optional) Fill in the Label with the label you want to include in your issues created from Virtuoso.

Configuring the cloud instance

# Data Center / Server instance

  1. Fill in the Jira URL field with the URL to your team's Jira instance;
  2. Fill in the Jira user email field with the email of the account you want to link to the operations;
  3. Fill in the Jira API token field with a Personal Access Token of the Jira account you want to link;
  4. Fill in the Jira Instance Type field with SERVER;
  5. (Optional) Fill in the Label with the label you want to include in your issues created from Virtuoso.

Configuring the data center / server instance

# Creating a ticket

To create a Jira issue using the Jira Virtuoso App, you need to fill out a form with the following fields:

  • Jira project: this field lists all Jira projects available, filtered by user input;
  • Issue type: this field lists all the supported issue types;
  • Title: this field accepts the summary of the issue to be created;
  • Description: optional, this field accepts a description of the issue to be created and is prefilled with a default description with several details about the execution.

It also presents a label that is added automatically to the created issue ("Virtuoso" by default) and the screenshots that will be attached to the issue (if there are any).

Create Jira issue form

To learn more about creating tickets using Virtuoso, please read Creating a ticket in the Ticket Tracking feature guide.

# Assigning a ticket

To assign an existing Jira issue using the Jira Virtuoso App, you need to fill out a form with the following fields:

  • Jira project: this field lists all Jira projects available, filtered by user input;
  • Ticket: this field lists all Jira issues available to be assigned, filtered by user input.
Assign Jira issue form

To learn more about assigning tickets using Virtuoso, please read Assigning a ticket in the Ticket Tracking feature guide.

# Updates between Jira and Virtuoso

The Jira Virtuoso App enables bidirectional updates between Jira and Virtuoso when some actions are executed.

A Virtuoso ticket will update when its linked Jira issue is updated, i.e., the title of a ticket will be updated in Virtuoso if the Jira summary changes. The fields that are subject to updates are the summary, status, URL, issue key, and issue type.

Limitation in issue type updates

Due to limitations in the Jira Cloud API, the update of an issue's issue type may not be reflected immediately in Virtuoso. If you need the new issue type to show in Virtuoso, you can force an update by changing the issue's summary or status.

On the other direction, the Jira Virtuoso App adds a comment to Jira issues linked to affected tickets when one of the following events occurs in Virtuoso:

  • A ticket was linked to a Jira issue;
  • A ticket was unlinked;
  • A ticket was archived;
  • A journey/test step was executed;
  • A journey/test step was deleted.
Last Updated: 9/29/2023, 12:34:53 PM