Setup & Authentication
Configure the TestKase Jira Plugin with a Personal Access Token and understand its configuration states.
Overview
After installing the plugin, each user must configure it with their own Personal Access Token (PAT) from TestKase.
Configuration States
The plugin moves through a small state machine. Three states occur during first-time setup -- NO_CONFIG, PAT_SAVED and READY -- and two more appear later if something breaks: PAT_EXPIRED (your token was revoked or expired) and MAPPING_LOST (the Jira project is no longer connected to a TestKase project). See Troubleshooting for both.
Stage 1: NO_CONFIG
What you see: A warning screen with instructions to configure the plugin.
This is the initial state before any PAT has been entered. The panel displays a message explaining that configuration is required and provides a link to the global configuration page.
How to proceed: Click the configuration link or navigate to the TestKase global page in Jira to enter your PAT.
Stage 2: PAT_SAVED
What you see: The plugin validates your PAT and checks the project mapping.
After you save your PAT, the plugin verifies the token is valid and looks for a TestKase project mapped to the current Jira project. If the mapping exists, the plugin transitions to the READY state automatically.
If the mapping is not found: The panel shows a message explaining that the Jira project is not connected to a TestKase project. A TestKase project admin must connect it using the Jira Plugin card, as described under Project Mapping below.
Stage 3: READY
What you see: The full test management interface with Test Cases and Test Cycles tabs.
The plugin is fully configured and ready to use. You can now create test cases, manage cycles, execute tests, and use all plugin features.
Later state: PAT_EXPIRED
What you see: A token-invalid screen instead of the panel.
Your saved PAT has been revoked or has expired. Enter a new PAT on the TestKase global page to recover.
Later state: MAPPING_LOST
What you see: A "project not mapped" screen instead of the panel.
The Jira project is no longer connected to a TestKase project through the Jira Plugin card. When this happens the plugin also clears its own cached mapping record for that project, so it will re-resolve the mapping from TestKase once an admin reconnects it.
Generating a Personal Access Token
- Log in to your TestKase account.
- Navigate to Settings → API Keys.
- Click Generate New Key.
- Give the key a descriptive label (e.g., "Jira Plugin").
- Copy the generated token immediately -- it will not be shown again.
For detailed instructions, see API Keys.
Each user should generate their own PAT. This ensures actions in the plugin are attributed to the correct user and access is scoped to the projects that user has permission to view.
Entering Your PAT in Jira
- In Jira, navigate to the TestKase global page (accessible from the apps menu or from the configuration link in the plugin panel).
- Paste your TestKase PAT into the token field.
- Click Save.
- The plugin validates your token and checks for a project mapping.
Once saved, the PAT is stored securely on Atlassian's Forge infrastructure and is used for all subsequent API calls from the plugin.
Project Mapping
The plugin automatically detects which TestKase project is mapped to the current Jira project. This mapping is established in TestKase using the Jira Plugin card.
Prerequisite: Before the plugin can function on a Jira project, a TestKase project admin must:
- In TestKase, open the Requirement Integration page for the project.
- Under Plugin Integrations, click Connect on the Jira Plugin card.
- Enter the Server URL of your Jira site (
https://your-org.atlassian.net), the Email address of an Atlassian account, and that account's API Token, then click Next. These are the same credentials the API Integration asks for; the card also shows a "What type of Jira do you use?" Cloud/Enterprise choice that has no effect -- leave it on Cloud. - Select the Jira project and click Save. The Jira Plugin card does not ask you to pick issue types -- that step exists only for the API Integration.
The plugin reads this mapping automatically -- you do not need to configure the project connection in the plugin itself.
If You Belong to More Than One TestKase Organization
The plugin looks the mapping up inside one organization: the first TestKase organization your account joined. If the Jira project is connected from a TestKase project in a different organization you belong to, the plugin reports MAPPING_LOST ("not mapped") even though the connection exists and looks correct in the dashboard.
There is no organization picker in the plugin. Connect the Jira project from a TestKase project in your original organization, or use a Personal Access Token belonging to a user whose first organization is the right one.
This only affects people who are members of several TestKase organizations. If you belong to one organization -- which is the normal case -- it never applies.
Use the Jira Plugin card, not the Jira API Integration card. The plugin looks up mappings created by the Jira Plugin card only. If the project was connected through Jira under API Integrations, the plugin will report "project not mapped" permanently -- reconnecting through the Jira Plugin card is the fix.
Connecting the Jira Plugin card covers both requirements and defects, and it replaces whatever the project had configured before. If either type was Built-in, that type's data is permanently deleted -- the project's requirements and requirement folders, its built-in defects, or both. Nothing is migrated and nothing can be recovered. The deletion happens when you confirm the Data Loss dialog, before the connection is saved, so cancelling afterwards does not undo it. See Built-in before you connect.
Re-Configuration
Updating Your PAT
If your PAT expires or you need to use a different token:
- Navigate to the TestKase global page in Jira.
- Enter your new PAT and click Save.
- The plugin validates the new token and resumes normal operation.
Deleting Configuration
To clear your plugin configuration:
- Navigate to the TestKase global page in Jira.
- Delete the saved PAT.
- The plugin returns to the NO_CONFIG state.
Security
- Per-user tokens -- Each user authenticates with their own PAT. There is no shared credential.
- Encrypted storage -- PATs are stored on Atlassian's Forge infrastructure using their built-in encrypted storage.
- HTTPS only -- All communication between the Forge app and TestKase API uses HTTPS encryption.
- No Jira modifications -- The plugin reads Jira issue context but does not modify your Jira issues.
Timezone Handling
The plugin uses your Jira profile timezone when displaying dates related to test execution (e.g., last run date, execution timestamps). Ensure your Jira profile timezone is set correctly for accurate date display.
FAQ
▶What if my PAT expires?
Navigate to the TestKase global page in Jira, enter a new PAT, and click Save. The plugin will validate the new token and resume working. You can generate a new PAT from TestKase Settings → API Keys at any time.
▶Can I use the same PAT for multiple Jira projects?
Yes. A single PAT works across all Jira projects, as long as the TestKase user behind the PAT has access to the mapped TestKase projects. The plugin detects the correct project mapping per Jira project automatically.
▶What if the project mapping is lost?
If the Jira Plugin connection is reset or reconfigured in TestKase, the plugin panel shows a mapping error. A TestKase project admin must reconnect it from the Requirement Integration page, under Plugin Integrations, using the Jira Plugin card.