JXL Documentation

# Troubleshooting

The JXL app experience is built on the shoulders of various Atlassian platforms. Sometimes the underlying Jira or Atlassian Marketplace (opens new window) systems and services can cause unexpected outcomes. Here's a list of things that can (rarely) happen and how to respond to them.

# Installation fails in Jira Cloud

If the installation is taking a long time and ends in Jira showing an indefinite error message, this can have a number of reasons that Atlassian refuses to indicate better in their error message. The most common ones are the following.

You might have an open quote with Atlassian. If you're paying Atlassian annually via quotes and your account is in arrears, Atlassian might not allow you to install some/any apps.

Atlassian might not have a valid payment method from you. Either you have no payment method provided or it's expired. Even though the JXL trial is (and even your Jira trial or plan might be) free, Atlassian might require a valid payment method to be on file in order to start trials of third-party apps.

  • Open the Jira settings menu in the navigation header bar and choose Billing.
  • On the Billing preview page, locate the relevant Jira product and click its Manage link.
  • On the Manage subscriptions page, if you see a warning message about your payment details, click the Add payment details link and follow the steps there.
  • Try to install JXL again.

You might have an existing, suspended subscription of JXL. Did you already have a trial of JXL, then uninstalled and reinstalled the app?

  • Open the Jira settings menu in the navigation header bar and choose Billing.
  • On the Billing preview page, locate the relevant Jira product and click its Manage link.
  • On the Manage subscriptions page, scroll down and look for an Inactive subscriptions section. If JXL is listed there, you need to contact Atlassian Support (opens new window) about this, using the link provided there.

Something has actually gone wrong during the installation of the app. This is very unlikely.

  • Visit the JXL Status (opens new window) site and check if Atlassian Jira app installation is operational.
  • If not, wait for Atlassian to fix their systems and try to install JXL again.

You can help

If you also think this indefinite error message is confusing and poor user experience, please help us by upvoting and commenting on the Atlassian issue that causes this. Visit UPM-6047 (opens new window), sign in with your usual Atlassian account, and click the Vote for this issue button at the top right of the page.

# Can't buy JXL for Jira Data Center

If you are trying to purchase JXL from My Atlassian (e.g. by clicking the Buy now button in the Universal Plugin Manager (opens new window)) and see an error message (along the lines of "We are unable to add the plugin to your cart. The plugin key is invalid.") this is caused by an Atlassian bug.

Please try purchasing through the Atlassian.com order form (opens new window) instead.

# Can't find JXL for Jira Server licence

Licence and maintenance period of JXL for Jira Server are not listed in Universal Plugin Manager (opens new window) and My Atlassian (opens new window), as it is our own proprietary licensing system independent of Atlassian’s.

# Sheets not in Jira navigation after installation

The Sheets item in the navigation is only visible if you have been granted the JXL: View sheets Permission, which should happen for all Users by default. However, sometimes something goes wrong on the Jira side when registering the Global permissions during the installation of the JXL app. This is caused by a known bug that Atlassian seems to refuse to track publicly or properly fix.

To resolve this, make sure you and all other relevant Users in your Jira site have this Permission, and ideally also the other JXL Permissions JXL: Edit sheets and JXL: Make bulk changes in sheets.

# Can't find Sheets in Jira Work Management Cloud

For some reason, Atlassian decided to design the Jira Work Management navigation conceptually entirely differently from all other navigation experiences, which is a common source of confusion. Instead of in the sidebar, you will find the Sheets item in the Apps menu of the horizontal tab navigation there.

# Can't find Sheets in Jira Product Discovery Cloud

For some reason, Atlassian has not (yet?) allowed any third-party app vendors to add items to the Jira Product Discovery sidebar, which is a common source of confusion. As a workaround, you can create Sheets in other Project types and define a Sheet scope that captures your Jira Product Discovery Issues.

# Error 'Couldn't create/save sheet' in Jira Data Center or Server

This can happen when your system is not currently connected to the internet.

Assuming the connection is stable, if you just installed JXL, it might also be a very rare case of a known Jira API bug related to the format of project keys. If your Jira system uses project keys that start with a number, which is a format not fully supported by Atlassian, some Jira APIs might fail to work as expected.

To compensate this Jira bug and prevent these errors in JXL, we have developed an alternative mode of exchanging data with the affected Jira APIs. You can switch to it by adding and enabling the Dark feature app.jxl.load-sheets-with-project-key in your Jira site (How to manage dark features (opens new window)).

Only do this if you are affected by this bug and it's not an option for you to adjust your project key format back to the standard pattern in Jira (Changing the project key format (opens new window)). Additionally, please contact us (opens new window) to let us know if you are using the Dark feature permanently.

You can help

If you also think this is poor user experience, please help us by upvoting and commenting on the Atlassian bug that causes this. Visit JSWSERVER-21574 (opens new window), sign in, and click the This affects my team link at the top right of the page.

# Sheet loads slowly

JXL offers consistent speed and overall performance at any scale. Even with a scope of 10,000 Issues, your Sheets should load within a few seconds or faster. Usually, when a Sheet loads slowly (more than 10 s), it's caused by a third-party app's Function in the JQL statement of its Sheet scope (a common example is issuesInEpics() from ScriptRunner (opens new window)).

There is no perfect solution to this, as we have no influence on the performance of Jira or other apps. Check if you really need to use Functions that cause slowness. As an example, the results of above-mentioned issuesInEpics() can often also be achieved using Structures, Level-specific search and filtering and Level filtering in JXL.

# Can't find some issue in sheet

If you are expecting a specific Issue to be listed in your Sheet but you can't find it, there are a few aspects that could cause this.

To start with, make sure that the Issue is indeed captured by the Sheet scope you have defined. If you need help writing or understanding a query, check Atlassian's JQL reference (Jira Query Language (opens new window)).

Once confirmed that the Issue is included in your Sheet's scope, make sure that there is no Column filtering enabled that could prevent the relevant Issue from being visible. Keep in mind that you could have filtering applied to multiple columns and any of them could be responsible for hiding the Issue. To check and clear all column filtering at once, click the highlighted icon in the status bar below the table and choose Reset column filtering. If the icon isn't highlighted, no column filtering is enabled.

Also check any Level filtering preferences you might have set that could prevent the relevant Issue from being visible. To reset this to its default state, click the icon above the row handles and click Reset, or click the highlighted icon in the status bar below the table and choose Reset level filtering. If the icon isn't highlighted, no level filtering preference is set.

Also check if you have typed anything in the Table search field that could prevent the relevant Issue from being visible. To clear the table search, empty the search field or click the highlighted icon in the status bar below the table and choose Clear table search. If the icon isn't highlighted, no table search is active.

# Can't update some field in sheets

While you can add any column to any Sheet in JXL, many table cells will only be available and editable for individual Issue types if you have configured Jira accordingly.

You need to have the appropriate Field added to the Issue type’s Screen in your Jira settings, specifically to the Edit operation Screen, or in absence of that to the Default Screen (Manage issue screens (opens new window)). The Field must also not be hidden in Field configurations. In Team-managed projects in Jira Cloud, the Field has to be added to the Issue type in Project settings (Customize an issue type's fields (opens new window)).

Generally, in order to be permitted to edit Fields of an Issue while it’s on a particular Status, its Workflow properties need to allow for it (Use workflow properties (opens new window)).

# Can't update time tracking fields in sheets

Jira only permits external apps like JXL to edit Fields if they are added to the relevant Screen. You need to have Time tracking added to the Issue type’s Screen in your Jira settings, specifically to the Edit operation Screen, or in absence of that to the Default Screen (Manage issue screens (opens new window)).

Adding this to the Screen/s can be an unexpected experience, as the necessary item to add is not named after the affected Fields (i.e. Original estimate, Time spent, Remaining estimate) but it's named Time tracking.

# Can't add some field's column to sheets

JXL supports a wide variety of Fields as table columns, including all Jira Standard fields, all your Custom field types, as well as many third-party apps' Fields (Supported fields).

If you come across a Field that's missing or that you think should work differently, feel free to let us know (opens new window) and we'll look into it.

# Columns with Builds information incorrectly empty in Jira Cloud

If some or all of the Builds status or Number of builds columns' cells are erroneously empty, this is caused by a known Jira bug.

You can help

If you also think this is poor user experience, please help us by upvoting and commenting on the Atlassian bug that causes this. Visit JSWCLOUD-23831 (opens new window), sign in with your usual Atlassian account, and click the This affects my team link at the top right of the page.

# Embedded sheet using iframe macro in Confluence Cloud doesn't load

If you are trying to embed a Sheet into a Confluence page by using the iframe Macro (Insert the iframe macro (opens new window)), the referenced Jira page may load but the JXL Sheet's data does not. This is caused by a known Jira bug.

You can help

If you also think this is poor user experience, please help us by upvoting and commenting on the Atlassian bug that causes this. Visit ECO-6 (opens new window), sign in with your usual Atlassian account, and click the This affects my team link at the top right of the page.

# More

If the hints above didn't help, contact us (opens new window).

Updated: 29 Sept 2023

← Frequently asked questions →

© 2020-3000 Fine Software Pty Ltd