Jira Extractor Setup — Customer Guide¶
Configure analytiQa to automatically extract issues from your Jira instance.
Prerequisites¶
- Jira Cloud or Server instance (any plan)
- A Jira account (ideally a dedicated service account) that can browse every project you want to report on
- A Jira API token for that account
- A secure credential intake link from your Qualtiva technical contact
Step 1: Your Jira URL¶
Examples:
- Atlassian Cloud:
https://your-company.atlassian.net - Server/Data Center:
https://jira.your-domain.com
If you're unsure, log into Jira — the URL is in your browser address bar.
Step 2: Your Credentials¶
You need:
- Email address — the Jira account analytiQa should use
- API Token — generated for that account
Enter both in the Jira section of your secure credential intake link. Never send them by email or chat.
Don't have a token? See Atlassian's guide: Manage API tokens for your Atlassian account.
Step 3: Choose What to Extract (Filters)¶
You choose which Jira issues analytiQa extracts with one or more filters. Each filter has:
- A name, e.g. the team, board or workstream. It's stored on every issue the filter matches, so you can break dashboards down by it.
- Either a JQL query or an existing saved Jira filter, referenced by its name or ID.
You can list as many filters as you need. An issue that matches more than one filter is extracted once and tagged with each filter's name.
Examples¶
| Filter name | Defined as | Extracts |
|---|---|---|
Platform |
JQL: project = PLAT |
Everything in one project |
Falcon |
JQL: project = WEB AND "Squad" = Falcon |
One squad's issues in a shared project |
Payments stories |
JQL: project IN (PAY, CHK) AND issuetype = Story |
Stories across two projects |
Mobile |
Saved filter: Mobile squad - qTest sync |
Whatever that saved Jira filter returns |
Rules of thumb¶
- Copy JQL straight from Jira. A trailing
ORDER BY …is fine; it's ignored. - Don't exclude completed work. Leave out conditions like
status != DoneorstatusCategory != Done. analytiQa picks up changes as they happen, so if an issue drops out of your filter when it's closed, we never see it close, and it stays "open" in your dashboards. Filter by status in the dashboard instead. - Date limits are fine. A condition like
updated >= "2026-01-01"is a good way to limit how much history is included. - Saved filters must be shared with the Jira account analytiQa uses. Otherwise that account can't run them.
- Tell us how far back to go. After the first run, analytiQa only picks up issues created or updated in the last few days. For the first extraction we can go further back (for example "everything since 1 January 2026"); just say so in your request.
Custom fields¶
By default analytiQa also extracts these custom fields, when they exist in your Jira:
- Team
- Sprint (all sprints the issue has been in, plus the current one)
- Fix Version
Name any other fields you want, for example Story Points, Squad or Components. A field that doesn't exist in your Jira is skipped; it doesn't cause an error.
Setting this up
You can enter filters and custom fields yourself in the Extractor config (advanced) box of the Jira section in your secure link. The box is pre-filled with your current configuration. Or send the list to your technical contact and they'll set it up with you. The Configuration Checklist shows the information to gather.
Step 4: Polling Interval¶
analytiQa checks Jira for new and updated issues every 15 minutes by default. The extraction is lightweight and read-only, and most teams leave the default as-is. If you need a different frequency, tell your technical contact.
Step 5: Review Your Configuration¶
Before submitting, check:
- ✓ Jira URL is correct
- ✓ Email and API token are valid, and the account can see every project in your filters
- ✓ Each filter returns what you expect when you run its JQL in Jira's issue search
- ✓ No filter excludes Done / closed issues
- ✓ Saved filters are shared with the analytiQa Jira account
What Happens Next¶
- First extraction: analytiQa fetches the issues matching your filters, as far back as agreed.
- Ongoing updates: every 15 minutes, issues created or updated recently are picked up.
- Dashboard ready: log in to the analytiQa dashboard → Jira Issues.
What Gets Extracted¶
From each Jira issue, analytiQa captures:
- Basic fields: issue key, summary, description, status, priority, type, assignee, reporter, labels
- Dates: created and updated
- Relations: linked issues and their relationship type
- Activity: comments, worklogs, watchers and status history, including when an issue was closed or reopened
- Filters: the name of every filter that matched the issue
- Custom fields: Team, Sprint, Fix Version, plus any others you ask for
Example Dashboards¶
Once data is ingested, see Common Queries & Reports for pre-built examples:
- Issues by status (To Do, In Progress, Done)
- Average resolution time by priority
- Issue volume trends over time
- Bugs vs. features breakdown
Troubleshooting¶
| Issue | Solution |
|---|---|
| "Invalid credentials" | Check the email and API token. Generate a new token if needed and send it through a new secure link. |
| "Connection timeout" | Your Jira URL may be incorrect. Verify it in your browser. |
| "No data extracted" | Run each filter's JQL in Jira's issue search, logged in as the analytiQa account. If it returns nothing there, adjust the filter. |
| "Only some issues extracted" | The Jira account may lack permission to see some projects, or a saved filter isn't shared with it. Check your Jira permissions. |
| Issues stuck as "open" | A filter probably excludes Done issues. Remove the status condition. |
More help? See Support & Troubleshooting.
Next Steps¶
- Configure another data source: qTest Setup or Tosca Setup
- Explore your data: Using Dashboards
- Build custom reports: Common Queries & Reports