Skip to main content

Jira Integration User Guide

Testworthy provides comprehensive bidirectional integration with Jira, enabling seamless workflow between your test management and issue tracking systems. This guide covers both outbound connections (Testworthy → Jira) and inbound connections (Jira → Testworthy).

Overview​

Testworthy's Jira integration consists of two main components:

  • Connect to Jira: Configure how Testworthy connects to your Jira instance to create issues, link test cases, and sync statuses
  • Jira Plugin Access: Manage API access for Jira marketplace plugins to access Testworthy data

Integration Features​

From Testworthy to Jira:

  • Create Jira issues directly from test cases
  • Link test cases to existing Jira issues
  • Auto-create defects when tests fail
  • Sync test case status with Jira issue status
  • Attach test results to Jira issues
  • Real-time status updates

From Jira to Testworthy:

  • View linked test cases in Jira issues
  • Access test case details from Jira
  • Create new test cases from Jira
  • Track testing progress in Jira dashboards

Prerequisites​

Before setting up the integration, ensure you have:

  1. Jira Instance Access

    • Administrative access to your Jira instance (Cloud or Server)
    • Ability to create API tokens
    • Project permissions in target Jira projects

  2. Testworthy Permissions

    • Platform Admin, Tenant Owner, or Project Manager role (for global configuration)
    • Project access for the projects you want to integrate

  3. API Tokens

Connect to Jira (Testworthy → Jira)​

This configuration allows Testworthy to connect to your Jira instance and perform actions like creating issues and linking test cases.

Step 1: Access Integration Settings​

  1. Navigate to the Jira Integration module in Testworthy
  2. Select the Connect to Jira tab
  3. Choose your target project from the dropdown

Integration Settings

Step 2: Configure Connection Settings​

Project-Wide Configuration (Admins Only)​

  1. In the Configuration tab, locate the Connection Settings card
  2. Fill in the required fields:
    • Jira Base URL: Your Jira instance URL (e.g., https://your-domain.atlassian.net)
    • Email Address: The email associated with your Jira account
    • API Token: Your Atlassian API token

Connection Settings

  1. Click Test Connection to verify the configuration
  2. Click Save Configuration to apply the settings

Personal Override Configuration​

Individual users can override project settings with their personal credentials:

  1. Click Use Personal Login in the Personal Login card
  2. Enter your personal email and API token
  3. Save the personal credentials

Personal Configurations

Personal Configurations Settings

Step 3: Understanding the Integration Workflow​

The integration follows a three-step process:

  1. Link Issues: Attach existing Jira tickets to test cases during or after execution
  2. Auto Defects: Create Jira bugs automatically when a test case fails
  3. Sync: View real-time Jira statuses and updates without leaving Testworthy

Step 4: Working with Linked Issues​

Viewing Linked Issues​

  1. Go to the Linked Issues tab
  2. View all test cases currently linked to Jira issues
  3. Use filters to search by:
    • Test case name or Jira key
    • Issue status (All, Done, In Progress, etc.)
    • Date ranges (Today, Last 7 days, Last 30 days)

Linked Issues

Linking Test Cases to Jira Issues​

During test execution:

  1. Run your test cases in Testworthy
  2. For failed tests, use the Jira integration option
  3. Choose to link to an existing issue or create a new defect
  4. The linkage will appear in the Linked Issues view with real-time status

Link Issue

Existing Jira Reference

Existing Issue

Create new Jira Issue

New Issue

New Issue Setup

Managing Linked Issues​

  • View in Jira: Click the "View in Jira" button to open the issue in your Jira instance
  • Status Sync: Statuses are automatically synchronized every 30 seconds
  • Real-time Updates: Changes in Jira are reflected in Testworthy within seconds

Linked Issues

Jira Plugin Access (Jira → Testworthy)​

This configuration enables Jira marketplace plugins to access Testworthy data through secure API keys.

Step 1: Access Jira Plugin Access​

  1. Select the Jira Plugin Access tab in the Jira Integration module
  2. This opens the Jira Plugin Access Dashboard

Jira Plugin Access

Step 2: Understanding the Setup Process​

The Jira plugin access requires two main steps:

  1. API Keys: Generate and manage API keys for secure authentication
  2. Plugin Integration: Install and configure the Testworthy plugin in Jira

Step 3: API Key Management​

Generating Organization API Keys​

  1. Navigate to the API Keys tab
  2. Generate an Organization API key for tenant-level authentication
  3. This key provides access to all projects within your organization

Organization API Key

Generating Project-Specific API Keys​

  1. Generate individual API keys for specific projects
  2. These keys provide granular access control
  3. Each project can have its own unique API key

Project API Key

Key Management Best Practices​

  • Secure Storage: Copy and store keys securely immediately after generation
  • Key Rotation: Regularly regenerate keys for enhanced security
  • Access Control: Use project-specific keys when possible for better security
  • Monitoring: Keep track of which keys are being used by which plugins

Step 4: Adding Jira Reference to a Test Case​

After configuring the plugin, you can add a Jira Reference to a test case in Testworthy:

  1. Open the test case you want to link in Testworthy
  2. Click on the ... button and select Edit
  3. Enter the Jira issue key (e.g., PROJ-123) you want to reference
  4. Save the changes

New Reference

New Jira Reference

Note: Jira Reference can also be added when manually creating a new test case.

Step 5: Installing the Jira Plugin​

  1. Visit the Atlassian Marketplace
  2. Install the Testworthy plugin in your Jira instance
  3. Configure the plugin with the API keys generated in Step 3
  4. Set up the connection to your Testworthy instance

Step 6: Plugin Configuration​

Once installed, configure the plugin with:

  • Jira Project Key: Exact Jira Project/Space key
  • Testworthy URL: https://app.testworthy.us/
  • User Email: Exact user email copied from Testworthy
  • API Key: The organization-specific API key
  • TW Project Key: The project-specific API key generated from Testworthy

TW App Configuration Dashboard

TW App Configuration

Once configured, all linked test cases to a specific Jira Ticket will appear in the Testworthy tab.

TW tab on Jira

Personal vs Project Configuration​

Project Configuration (Default)​

  • Scope: Applies to all team members in the project
  • Managed By: Platform Admins, Tenant Owners, or Project Managers
  • Use Case: Centralized management, consistent attribution
  • Attribution: Issues created using the configured project account

Personal Override​

  • Scope: Applies only to the individual user
  • Managed By: Individual users
  • Use Case: Personal attribution, custom credentials
  • Attribution: Issues created using the user's personal account

When to Use Each Approach​

Use Project Configuration When:

  • You want centralized management
  • All team members should use the same Jira account
  • You need consistent issue attribution
  • You want simplified setup for team members

Use Personal Override When:

  • You need personal attribution for Jira issues
  • Team members have different Jira accounts
  • You want individual accountability
  • Different team members need access to different Jira projects

Troubleshooting​

Common Connection Issues​

"Connection Failed" Error​

  • Cause: Invalid credentials or network issues
  • Solution:
    1. Verify your Jira URL format (include https://)
    2. Ensure your email and API token are correct
    3. Check if your Jira instance is accessible
    4. Verify API token permissions

"Authentication Failed" Error​

  • Cause: Incorrect email or API token
  • Solution:
    1. Regenerate your API token from Atlassian
    2. Ensure you're using the correct email address
    3. Check if the API token has expired

"Permission Denied" Error​

  • Cause: Insufficient permissions in Jira
  • Solution:
    1. Ensure you have project permissions in Jira
    2. Verify your account has issue creation rights
    3. Check if the project exists and is accessible

API Key Issues​

"API Key Invalid" Error​

  • Cause: Expired or incorrect API key
  • Solution:
    1. Regenerate the API key in Testworthy
    2. Update the key in your Jira plugin configuration
    3. Ensure you're using the correct key type (organization vs project)

"Access Denied" Error​

  • Cause: Insufficient permissions for API key generation
  • Solution:
    1. Ensure you have the correct role (Platform Admin, Tenant Owner, or Project Manager)
    2. Contact your administrator for permission elevation

Status Sync Issues​

"Statuses Not Updating" Error​

  • Cause: Network connectivity or configuration issues
  • Solution:
    1. Check your internet connection
    2. Verify the Jira instance is accessible
    3. Re-save your connection configuration
    4. Use the manual refresh button in Linked Issues

Security Considerations​

API Token Security​

  • Encryption: All API tokens are encrypted with AES-256 before storage
  • Visibility: Tokens are never displayed in plain text in the interface
  • Rotation: Regularly rotate your API tokens
  • Scope: Use project-specific keys when possible for limited scope

Access Control​

  • Role-Based: Only users with appropriate roles can configure integrations
  • Audit Trail: All configuration changes are logged
  • Personal Overrides: Users can only configure personal overrides, not project settings

Network Security​

  • HTTPS Only: All connections use encrypted HTTPS
  • Token Transmission: API tokens are never transmitted in URLs
  • Secure Headers: All requests include appropriate security headers

Best Practices​

  1. Regular Key Rotation: Rotate API keys every 90 days
  2. Least Privilege: Use project-specific keys when possible
  3. Monitor Usage: Regular review API key usage patterns
  4. Secure Storage: Store backup keys in secure password managers
  5. Team Training: Ensure team members understand security practices

Support and Resources​

Getting Help​

  • Check the Troubleshooting section above
  • Contact your system administrator
  • Review Jira and Testworthy logs for detailed error messages
  • Ensure all prerequisites are met before configuration

Common Support Scenarios​

  • Setting up first-time integration
  • Migrating from manual to automated linking
  • Configuring team-wide vs personal authentication
  • Troubleshooting connectivity issues
  • Managing API key lifecycle

This guide covers the comprehensive setup and usage of Testworthy's Jira integration. For the latest updates and additional features, please refer to the in-application help or contact your administrator.