FAQs
Troubleshooting, Security & Common Questions
Security & Permissions
Is this add-on secure?
Yes, it is completely secure. We use Atlassian's official OAuth 2.0 method, which is the industry standard for security. When you connect, you are simply giving permission to the add-on through Atlassian's own secure system to read your Jira data.
Why does the add-on need permission to access my Google Sheets?
When you install the add-on, Google will ask you to authorize several permissions. Here is exactly why we need them:
"View and manage spreadsheets that this application has been installed in": This is the most important permission. It allows the add-on to create the "Latest Issue Data" and "Issue Data Logs" sheets and write your Jira data into them.
"Connect to an external service": This allows the add-on to talk to the Jira API to fetch your data
"Allow this application to run when you are not present": This is required only if you want to use Automated Triggers. It allows the script to run in the background (e.g., at 3:00 AM) to sync your data while you sleep.
"Display and run third-party web content in prompts and sidebars": This allows us to show you the configuration sidebar where you select your projects and fields.
"See your primary Google Account username email address": We use this to securely link your Jira connection to your Google account. This ensures that your personal "Jira Connection" stays tied to you and isn't shared with other people using the same spreadsheet.
Please provide access to all the scopes, without these - the add-on features won't function properly.
What permissions does it ask for in Jira (Atlassian)?
The add-on only requests read-only permissions. This means it can fetch your issue data, but it absolutely cannot modify, create, or delete any of your issues or projects in Jira.
"Read Jira service data": This allows us to fetch your issues, project names, status lists, and field configurations. This is the core of the add-on.
"View user profiles": We use this to translate internal Jira IDs into readable names for your spreadsheet (for example, showing "John Doe" instead of a random string of numbers in the Assignee column).
"View your profile": This allows us to show you which Jira account you are currently connected with in the sidebar.
Does the add-on store my Jira data on its own servers?
No. Your Jira issue data (summaries, descriptions, custom field values, etc.) travels directly from Atlassian's servers to your Google Sheet via an encrypted connection. It is never stored anywhere else.
Certain "metadata" is necessary to make the add-on function, which includes:
Your Sync Configurations: The JQL queries, field mappings, and metrics you’ve set up are stored within the Google Sheet itself.
Usage Logs (Non-Sensitive): We track the number of API calls and AI requests made (e.g., "10 Search calls") to manage service limits and improve performance. This does not include the content of the data being synced.
AI Context: When using the AI Configuration feature, we only send the names of your fields and statuses to the AI model to build your configuration. Your actual Jira issue data is never sent to an AI model.
How do I disconnect my Jira account or reset the add-on?
If you want to stop using the add-on or simply start fresh, you have three levels of "Reset" available:
Disconnect (Logout): Click "Disconnect" at the top of the sidebar. This removes your "Jira Connection" from the add-on. You will no longer be able to sync data, but your saved settings (mappings/metrics) will remain in the sheet in case you want to reconnect later.
Reset All Settings: Found on the "Reset" page in the sidebar menu. This is the "Nuclear Option." It will:
Disconnect your Jira account.
Delete all saved field mappings, JQL, and metrics for the current sheet.
Clear your local API usage statistics.
Remove any automated triggers you have set up.
Revoke Access via Atlassian: If you want to completely remove the add-on's permission from your Atlassian account, you can do so at any time through your Atlassian account settings:
Go to id.atlassian.com/manage-profile/apps (https://id.atlassian.com/manage-profile/apps).
Find "Jira Data Fetcher for Google Sheets" and click "Remove Access."
What happens to the data already in my sheet if I disconnect?
Nothing! The data already synced into your Google Sheet belongs to the sheet. Disconnecting or resetting the add-on only stops future syncs; it does not delete the information you have already successfully imported.
Getting Started
The authorization window didn't open or is blocked. What should I do?
This is usually caused by a browser pop-up blocker.
Step 1: Look for a "pop-up blocked" icon in your browser's address bar and click it to allow pop-ups from script.google.com.
Step 2: The sidebar provides a direct link to the authorization page. You can click this link to open it manually.
I connected to the wrong Jira site. How do I switch?
Once you are connected, a "Jira Site" dropdown will appear at the top of the Configuration page. You can simply select a different site from this list, and the add-on will automatically switch to it for all future syncs and project searches.
Syncing Data & Features
My sync is taking a very long time. How can I speed it up?
Sync speed is mainly affected by three things:
Large Date Range: If the "Created Since" filter is empty, the add-on might be trying to fetch years of data. Try setting a filter like -90d (for the last 90 days) to limit the scope.
Changelog Tracking: The "Track Changelog" feature is very powerful but requires fetching detailed history for every issue, which can be slow. Consider enabling it only for the most critical fields.
Append-Only Mode: In this mode, the add-on runs extra queries to check for"stale" issues. While efficient, it is inherently slower than the simple overwrite mode.
I'm getting an error that a Project, Status, or Field was not found, but I know it exists.
This usually happens if the configuration was set up based on one Jira project, and you then switched to another project that doesn't have the same fields or statuses. The best solution is to click the "Fetch & Refresh Statuses" and "Fetch Fields" buttons to get the latest lists for your currently selected project. Fields are based on the latest issue in the project. If you still don't find the needed field - you can add a custom field by clicking "Add Custom Field" below the fields section.
Can I sync my company's custom Jira fields?
Absolutely! After selecting your project, click the "Fetch Fields" button. The add-on will scan your project and list all available fields, including system fields and any custom fields your organization has created (e.g., "Story Points","Epic Link," "Sprint").
What is the difference between "Time in Status" and "Time in Transitions"?
Time in Status: Measures the total accumulated time an issue spent in a specific state. For example, if a ticket was "In Review" for 2 hours on Monday and 3 hours on Wednesday, the total "Time in In Review" would be 5 hours.
Time in Transitions: Measures the duration between two different points in the workflow. For example, it calculates the total time from [Issue Creation] to "Done." This is often used for metrics like Cycle Time or Lead Time.
How do I get the most value out of the JSON changelog data in my sheet?
The changelog JSON is sorted with the newest change first. For quick analysis, you can simply look at the beginning of the text to see the most recent update. For more advanced reporting, you can use Regex formulas or Google Apps Script to parse this JSON data. For example, you could write a formula to automatically extract the ChangedBy value from the first log entry to see who last touched the field.
Collaboration & Team Use
My teammate set up a sheet, but when I open it, it says I'm not connected. Why?
This is a key security feature. Your connection to Jira is your personal "passport" and is never shared. Even when using the same spreadsheet, every user must connect with their own Jira account. This ensures that data is always fetched based on the current user's permissions.
My colleague can sync the data, but I get a "Permission Denied" error.
This means the sheet is configured to sync a Jira project that your specific Jira account does not have permission to view. You can either ask your Jira administrator for access to that project or change the sync configuration to a project you do have access to.
Someone else set up an automated trigger. Can I change or delete it?
For security, automated triggers are tied to the creator's account. You can see that a trigger is active and who created it. If you need to take over the automation, you can use the "Force Reset Configuration" button on the "Automated Triggers" page. This disconnects the sheet from the old trigger and allows you to create a new one linked to your account.
If I share the sheet with someone, can they get access to my Jira account?
No! They will only get access to the data you have already synced to the sheet. They cannot access your Jira account or fetch any new data from there without connecting their own Atlassian account with the add-on. After which they can only sync what they can access via Jira UI.
Errors & Troubleshooting
I'm getting a "Sync Failed" error. What should I check first?
JQL Errors: If you are using Custom JQL, double-check that the syntax is valid in Jira.
Permissions: Ensure you have permission to view the project specified in the settings.
Temporary Glitch: Sometimes Jira's API or Google's services have temporary issues. Wait a minute and try clicking "Sync Now" again.
The add-on is not responding or seems stuck on "Loading..."
This can occasionally happen. The best first step is to simply close and reopen the sidebar by going to Extensions > Jira Data Fetcher > Open Configuration. If that doesn't work, refreshing the entire Google Sheet page will resolve most issues.