Update the Katalon app for Jira to the Atlassian Forge version
The Katalon app for Jira Cloud runs on Atlassian Forge. A Jira admin must approve the update separately for each Jira site. Before you update, review the JQL changes below: queries that use the old Katalon names need to be edited. After you update, your team may also need to add the Katalon panels to work items. Release results are available through a link to Katalon instead of a panel in Jira.
This guide is for Jira admins. It uses the term work item for what Jira previously called an issue.
What you need to do​
- Find the saved filters, board filters, and dashboard gadget queries that use
"Katalon Status"or"Katalon AI Status". Where other people own them, agree with the owners on who edits them. - Before you approve the update, replace the old names in these queries with the
issue.propertyqueries, and check that each query returns the same results as before. See JQL names. - On the Manage apps page of each Jira site, approve the update of the Katalon app. See How the update reaches your site.
- Add the Katalon panels that your team uses to work items. See Work item panels.
- Check that the app works as expected: open one of the edited filters, a board or dashboard that uses one, a work item with linked tests, and a Jira version that is linked to a release in Katalon.
How the update reaches your site​
The Forge version is a major update, so Jira does not install it automatically.
- Find the Katalon app update on the Manage apps page of your Jira site.
- A Jira admin must approve the update. Until then, your site stays on the current version of the app.
- If you have more than one Jira site, approve the update on each site.
Existing connections and data​
The update replaces the app in place. You do not need to uninstall the app or connect your projects again.
- Project connections: The connection between a Jira project and Katalon, including its credentials, is kept.
- BDD settings: The BDD settings of a project are kept. They are on the BDD tab of Katalon Settings.
- Linked test results: The tests and results that are linked to work items are kept, and the Katalon status values that you search for in JQL do not change.
- Release links: The links between Jira versions and releases in Katalon are kept. After the update, each linked version gets a Katalon test results item. See Release results.
What changes​
| Area | Before the update | After the update |
|---|---|---|
| JQL names | "Katalon Status", "Katalon AI Status" | KatalonStatus, KatalonAIStatus |
| Project settings | Katalon tabs in the project settings | Project (space) settings > Apps > Katalon Settings |
| BDD settings | Separate Katalon BDD tab | BDD tab in Katalon Settings |
| Admin page | Katalon page for the Jira site | Jira settings > Apps > Katalon - Test Automation for Jira |
| Work item panels | Katalon panels shown on the work item | Added to a work item from View app actions |
| Release results | Katalon panel on the Jira version | Katalon test results item under Related work |
JQL names​
In the Forge version, the names that you use in JQL to search by Katalon status change as follows. The property queries in the last column work both before and after the update.
| Before the update | After the update | Before and after the update |
|---|---|---|
"Katalon Status" | KatalonStatus | issue.property[katalonTestResult].status |
"Katalon AI Status" | KatalonAIStatus | issue.property[katalonAiRun].status |
Only the name changes. Keep the status values in your queries as they are.
For example, a filter that finds the work items with a passed Katalon test result:
"Katalon Status" = PASSED
changes to one of the following:
issue.property[katalonTestResult].status = PASSED
KatalonStatus = PASSED
A filter that finds the work items with a passed Katalon AI run:
"Katalon AI Status" = PASSED
changes to one of the following:
issue.property[katalonAiRun].status = PASSED
KatalonAIStatus = PASSED
Use the issue.property queries to edit your filters before you approve the update, so that they keep working during and after the update. KatalonStatus and KatalonAIStatus are shorter alternatives that work only after the update.
Jira does not update or flag the saved filters, boards, and gadget queries that use the old names. After the update, a query that uses "Katalon Status" or "Katalon AI Status" no longer finds the field. Edit each of these queries by hand.
Project settings and the admin page​
- Project settings: The Katalon settings of a project are under the project (space) settings > Apps > Katalon Settings. The page has a Connection tab and a BDD tab.
- BDD settings: The separate Katalon BDD tab is removed. The BDD settings are on the BDD tab of Katalon Settings.
- Admin page: The Katalon admin page is under Jira settings > Apps > Katalon - Test Automation for Jira. Only Jira admins can open it.
Work item panels​
After the update, the Katalon Test Results and Katalon BDD Fields panels are not shown on a work item until someone adds them.
- To add a panel to a work item, open the work item, click View app actions under the summary, and select the panel.
- To avoid adding a panel to each work item, a Jira admin opens the More actions menu of the panel and selects Show for all work items. Only Jira admins see this option.
Release results​
The Katalon panel on the Jira version (release) page is removed. Instead, a Jira version that is linked to a release in Katalon shows a Katalon test results item under Related work.
- The item links to the release in Katalon, where you view the results.
- The item does not show pass counts.
- Katalon checks for linked versions about once an hour, so the item can take an hour or more to appear after the update or after you link a version.
Why the app moved to Forge​
Atlassian ends support for its Connect app platform on 31 January 2027. See Connect End of Support extended to January 31, 2027 on the Atlassian Developer Community. The Katalon app runs on Forge, Atlassian's current app platform.
If something does not work​
- A check fails after the update: For example, a project is no longer connected, or a panel or the Katalon test results item does not appear. Contact us through the Katalon Support Portal and include the URL of your Jira site.
For how to connect a project and view test results in Jira, see Use Katalon app for Jira.