Jira integration

Last updated: September 2026

This document shows you how to set up an integration for Jira within Katalon True Platform.

If your Jira or Git instance is hosted on‑premise or behind a corporate firewall, use this guide together with the Private Jira/Git integration (Network configuration guide) to ensure all required firewall rules and tunnels are in place.

Connect a Jira account to Katalon True Platform

Before configuring Jira integration at the Project level (selecting board, mapping fields...), you must first set up the connection at the Account level.

Requirements

You must have the Account Admin or System Admin role to perform this action.

To set up the connection:

1. Go to Account > Integrations.

2. Click + Create Integration. In the Available Integration list, choose Jira.

3. Fill in the required fields to establish the connection. Katalon True Platform supports two types of Jira instances:

   Jira Cloud or Atlassian.com (SaaS)

   

   • Integration Name: A custom name for the integration (max 50 characters).
   • Organization URL: The Jira Organization URL.
     • Example: https://katalon-product-demo.atlassian.net
     • Must start with https://
   • Personal Access Token (PAT): Enter your Jira API token. To generate a PAT, refer to this documentation. Please make sure the PAT has required permissions.
     ✅ Jira Permissions Required for integration

     Integration Feature	Required Permission(s)	Notes
     Manual Sync	Browse Projects	Allows Katalon True Platform to retrieve project data from Jira.
     Link Defects	Browse Projects	Enables linking Jira issues to Katalon True Platform test cases.
     Create Defects	Browse Projects, Create Issues	Additional permissions may be required depending on Jira field configurations (see below).
     	Optional: Assign Issues, Modify Reporter, Link Issues, Resolve Issues, Schedule Issues	These become required if the corresponding fields (Assignee, Reporter, Issue Links, Fix Versions, Due Date) are marked as required in Jira.
     Handle Webhook Events	Browse Projects	Needed to associate Jira events with Katalon True Platform updates.
     Webhook Setup	Administer Jira (global permission)	Required only when configuring webhooks from Jira to Katalon True Platform.

   • Description (Optional): Brief description of the integration (max 255 characters).

   🔁 Service Hooks will be automatically created at the project level for real-time syncing and automation.

   Jira Datacenter Server or Self-Managed (On-Premise)

   

   note

   • Supported Version: Jira Datacenter Server 10.6.1 and above. Older versions may not be compatible and could cause connection issues.
   • Use HTTPS for Jira Data Center: Configure your Jira Data Center instance to use HTTPS and update its base URL accordingly. Browsers may block or upgrade HTTP requests, which can prevent embedded resources such as images, icons, and videos from loading correctly in Katalon True Platform.

   • Integration Name: Enter a custom name for the integration (max 50 characters).
   • Organization URL: Enter the Jira Organization URL.
     • Example: https://your-jira-instance.example.com
     • Must start with https://.
   • Personal Access Token (PAT): Enter the PAT of an ALM admin account. This is required for webhooks to work and to keep changes in sync with Katalon True Platform. To generate a PAT, refer to this documentation.
   • Description (Optional): Enter a brief description of the integration (max 255 characters).
   • TestCloud Tunnel (Optional): Select an active tunnel from the list. If you cannot find an active tunnel, set up a new TestCloud Tunnel.
   • For private, firewall-restricted environments, make sure the network paths between Jira and Katalon True Platform are configured as described in this Private Jira/Git integration – network configuration guide document.

4. Click Test Connection to validate the integration.

5. Once validated, click Save, or click Cancel to exit without saving any changes.

Result

To verify if the connection is active, navigate to Admin > System > Integrations. Your Jira integration will be listed under the Integration list.

• If the status initially shows as Inactive, reload the page to update the status to Active.
• If the status shows Error, verify all required configuration fields, especially the Personal Access Token (PAT), and confirm it is valid and configured correctly in the account-level integration.

Configure Jira integration at Project level

Requirements

• You must have the Project Admin role to perform this action.
• You have connected a Jira account at the Account-level

Once the connection is established, you can now configure the integration and perform these actions:

• Select Projects and Boards
• Pull requirements
• Map fields

1. Navigate to your project > Settings > Integrations.
2. Click the right edge of your linked connection and select the Settings (⚙️) icon.

3. Select the Project and Board:

• Project: Select the Jira Project to link from the dropdown list. This defines which work items will be synced to Katalon True Platform.
• Board (Optional): Select a board to link to enhance collaboration.
• Description (Optional): Brief description of the linked project (max 255 characters).

After selecting a Jira project and optional board, Katalon True Platform retrieves the fields and values available for that project. The configuration sections shown below depend on the options selected under Integration Options with Jira.

Step 2: Integration Options

Select Pull Requirements to enable:

• Requirement synchronization and configure release and sprint mapping
• Common field mapping
• Requirement fields, work item types, release dates, and requirement statuses

Select Bug Mapping to enable Bug Fields and Values Mapping, where you can map Jira bug severity and status or resolution to Katalon True Platform values.

Select both options to configure both requirement and bug synchronization.

If a board is selected, sprint-related data is also retrieved from Jira. Review the available fields and mappings, adjust them to match your Jira workflow, and click Proceed to save the configuration and begin synchronization.

Step 3: Release and Sprint Mapping

Define how Release and Sprint data will be mapped from your Jira project.

Step 4: Common Fields and Values Mapping

This section allows you to map priority for effective issue prioritization and resource allocation, ensuring clear prioritization based on urgency (e.g., High, Medium, Low). Consistent mapping helps maintain workflow efficiency and prevents misalignment that could lead to inefficiencies.

Map Jira Priority levels your chosen Katalon True Platform Priority levels based on your workflow.

Step 5: Requirement Fields and Value Mapping

Use this section to define how Jira requirement data appears in Katalon True Platform.

• Release Date for Requirement (Optional): Select up to three Jira date fields. The fields are evaluated from left to right, and the first available value is used as the requirement’s release date.
• Status mapping: Map Jira Status or Resolution to the corresponding Katalon True Platform State.
• Work Item Types: Select the Jira work item types that should be synchronized as requirements.
• Requirement fields mapping (Optional): Select additional Jira fields to display in the True Platform requirement details. By default, only the Jira issue description is synchronized.

For each mapped field, you can customize the True Platform label, change the display order, or remove the field.
Mapped fields appear as follows:

• Rich-text fields appear in the General tab below the description.
• Other field types appear in the collapsible Additional Information panel.
• Empty Jira fields are displayed with a - placeholder.

Fields provided by Jira Marketplace apps that are stored outside the standard Jira issue payload are not supported.

For an existing Jira configuration, select Edit, configure the requirement fields, and click Proceed to re-sync. Then go to Plans and click Sync to refresh the requirements.

Step 6: Bug Fields and Values Mapping

This section allows you to map the fields and values of bugs to the corresponding fields and values in Katalon True Platform.

• Map Jira Severity levels to your chosen Katalon True Platform Severity levels based on your workflow.
• Map Jira Status levels to your chosen Katalon True Platform Status.
• Select either Jira Resolution or Jira Status to your chosen Katalon True Platform Status.

4. Click Proceed to sync data and finalize the connection.
   • If the status initially shows as Inactive, reload the page to update the status to Active.
   • If you modify the connection details and click Save, your changes will be saved, but the status may remain Inactive. To sync data and finalize the connection, click Proceed.

To edit an existing linked Jira integration, click the Edit (pen) icon, make the necessary changes, and click Proceed. After editing, reload the page to ensure data is refreshed.

Result

Your Jira integration is now active within your project.

View release plans synced from linked Jira Integration

To view release plans synced from linked Jira integration:

1. Navigate to your specific project's UI > Plans.
2. In the left-right dropdown menu, select the linked Jira integration.
3. Click the Sync button to fetch the latest data.

---

Manage Jira integration

Katalon True Platform provides multiple ways to manage Jira integrations without losing historical data. This section covers how to disconnect, archive, and restore an integration when needed.

• Use Disconnect to disable Jira integration across all projects (Account-level).
• Use Archive to disable Jira connection for a single project (Project-level).

Katalon does not support permanently deleting integrations. This ensures audit history is preserved and enhances security and traceability.

Disconnect a Jira Connection

Required role: Account Admin or System Admin to perform this action.

Disconnecting makes the integration inactive across all projects. Katalon True Platform does not support fully deleting integrations, in order to preserve audit history.

1. Go to Account > Integrations.

2. Click the Disconnect icon next to the connection.

3. Confirm by clicking Disconnect in the dialog.

   => The status changes to Inactive. All projects using this integration lose the ability to sync with Jira.

4. To reconnect, click the Reconnect icon next to the integration and confirm. All projects will resume syncing once reconnected.

Archive a Linked Jira integration

Required role: Account Admin or System Admin to perform this action

Archiving disables the connection for that project only — other projects using the same Jira integration are unaffected. Archived configurations no longer appear in Project Settings, and any scheduled test runs will be canceled at runtime.

1. Go to your project > Settings > Integrations.
2. Click the right edge of your linked connection and select Archive.
3. Confirm by clicking Archive in the dialog.

Result: The integration no longer appears in the Plans module.

Restore a Linked Jira integration

1. Go to your project > Settings > Integrations.
2. Click New configuration (settings icon) on the Jira connection.
3. Enter the same repository URL as the archived configuration and click Proceed.

Katalon True Platform will restore the archived configuration rather than creating a duplicate.