Skip to main content

Zephyr Test Management (Cloud)

This guide provides the necessary details to quickly and securely connect your Zephyr instance (Zephyr Squad or Zephyr Scale/Essential) within Jira Cloud to SQAI Suite, enabling the generation and linkage of test cases.

Updated over 2 months ago

⚠️ Warning: This integration setup is for Zephyr setups (Squad,Scale,Essential) within the Atlassian Cloud only. If your set-up is not Cloud (Server or Data Center), please consult our Atlassian Application Tunnel Documentation

1. How does SQAI Suite Leverage This Integration?

Connecting to Zephyr allows SQAI to integrate directly into your Jira-based testing management workflow:

  • Centralized Test Creation: Allows SQAI to generate new, high-quality test cases directly within your designated Zephyr Project and Folder.

  • Streamlined Workflow: Eliminates the manual effort of transferring generated test assets into your Test Management Tool (TMT).

  • Traceability: Ensures test cases are created with the necessary IDs and links to maintain end-to-end traceability.

2. Information Required from Your Zephyr Account

To establish a secure, plug-and-play connection, we require four specific pieces of information.

Required Detail

Explanation

How to Find It

Test Case URL

The base URL required for SQAI to link back to the created test cases.

See Section 2.1 (Found in the URL).

Project Key

The short identifier for your Project (e.g., SQAI).

See Section 2.1 (Found in the URL).

Folder ID

The numerical ID of the specific folder where test cases will be placed.

See Section 2.2 (Requires Dev Tools Inspection).

Access Token

A unique, private token used for API authentication.

See Section 3.

2.1 Retrieving the Project Key and Test Case URL

  1. Log into Jira and navigate to your specific project, then open Zephyr Scale/Squad.

  2. The Project Key (e.g., SQAI) is visible in the URL path

  3. The Test Case URL is the long, complex part of the URL, required for generating direct links in SQAI Data Tables.

2.2 Retrieving the Folder ID (Advanced Step)

https://app.tm4j.smartbear.com/backend/rest/tests/2.0/project/10001/foldertree/testcase

The Folder ID is not directly visible in the URL and must be retrieved using the browser's developer tools:

  1. Navigate to the Test Cases section in Zephyr and open your browser's Developer Tools (F12 or Ctrl+Shift+I).

  2. Go to the Network tab and clear the log.

  3. Click on the specific folder (e.g., SQAI Dev) you want the ID for. This will trigger an API request.

  4. Look for a request containing /foldertree/testcase or similar path in the Network log.

  5. Inspect the Response of that API request. The response will contain a JSON object where the id field corresponds to the Folder ID.

3. Setting up the Access Token

The Access Token is required to authorize SQAI Suite to communicate with the Zephyr API.

Step 1: Access Token Settings

  1. In the Jira interface, click your Avatar Icon (usually in the top right corner).

  2. Scroll down to the bottom of the user menu and select Zephyr Scale API Access Tokens or Zephyr Squad API Access Tokens.

Step 2: Generate and Secure the Token

  1. On the API Access Tokens page, click Create access token

  2. Provide a clear name (e.g., "SQAI Integration").

  3. Click Copy to secure the generated key. This token is only displayed once; store it securely.

4. Entering Details in SQAI Suite

Once you have secured your Access Token and gathered the necessary IDs, you can complete the setup in the SQAI Suite platform.

Step 1: Navigate to Integrations Go to your SQAI Suite settings and select the Integrations page. Find and select the Zephyr Test Management configuration.

Step 2: Enter Details Insert the following details into the corresponding fields shown on the configuration page:

Configuration Field Name

Value to Enter

Notes

API key

The Access Token generated in Section 3.

Expiration Date

Optional. Date the token expires.

Used by SQAI for reminder alerts.

Base URL

https://api.zephyrscale.smartbear.com/v2/

Default Value. Keep this URL unless you have a specific custom API endpoint.

Project Key

The project identifier (e.g., SQAI).

Found in your Jira URL.

Folder ID

The numerical ID retrieved via Dev Tools (Section 2.2).

Jira URL

The URL of your Jira instance (e.g., https://<MY_DOMAIN>.atlassian.net).

Used for linking back to your environment.

Step 3: Save and Confirm Click "Save Configuration." If the set-up is successful, you will receive a success message and see a green indicator next to your integration.

5. Troubleshooting Zephyr Integration

If SQAI reports an error or fails to connect, use this checklist to quickly identify and resolve the most common issues related to access.

Problem

Cause

Solution

Connection Failed: "Unauthorized" or "Forbidden"

A. Invalid Token: The Access Token was copied incorrectly or has been revoked.

Generate New Token: Generate a new Access Token from the user profile settings (Section 3) and update the configuration in SQAI Suite.

Invalid Resource: Cannot Find Folder

B. Incorrect Folder ID: The numerical Folder ID was incorrect or not retrieved using the API response (Dev Tools).

Re-Verify ID: Repeat the process in Section 2.2 using the Network tab in Dev Tools to ensure you have the current id value.

Invalid Resource: Cannot Find Project

C. Incorrect Project Key: The Project Key entered contains a typo.

Double-Check URL: Verify the Project Key matches the key visible in the Jira URL.

Token Expired

D. Token Visibility: The token was not copied immediately.

Generate New Key: Since the key is only displayed once, you must generate a new key and update the configuration in SQAI Suite.

Related Articles
TestMonitor Test Management (Cloud)
Xray Test Management (Cloud)
TestRail Test Management (Cloud)
Atlassian Jira (Cloud)
Testmo Test Management (Cloud)
Did this answer your question?