Jira Connector

Connect to Atlassian Jira to index issues, comments, worklogs, and project data for AI-powered search across your issue tracker.

Overview

The Jira connector supports:

• Jira Cloud (v3 API) and Jira Server/Data Center (v2 API)
• Full issue content including summary, description, and custom fields
• Comments, worklogs, and attachments
• JQL-based filtering for precise control over which issues are indexed
• Project and issue type filtering
• Incremental sync based on issue update timestamps

Prerequisites

• Jira Cloud or Server/Data Center instance
• A user account with Browse Projects permission for the target projects
• API token (Jira Cloud) or username/password (Jira Server)

Authentication

Jira Cloud

1. Generate an API token at Atlassian Account → API Tokens
2. Use your Atlassian email address as the username
3. Use the generated API token as the credential

Jira Server / Data Center

Use standard username and password authentication. Ensure the account has browse access to the projects you want to index.

Configuration Reference

Setting	Type	Required	Description
Instance URL	string	Yes	Jira instance URL (e.g., https://yourcompany.atlassian.net)
Username	string	Yes	Atlassian email (Cloud) or username (Server)
API Token	string	Yes	API token (Cloud) or password (Server)
Use Cloud	boolean	No	Use Jira Cloud v3 API (default: true). Set to false for Server/Data Center.
Project Keys	array	No	Specific project keys to include (e.g., ["ENG", "PROD"])
Include All Projects	boolean	No	Sync all accessible projects (default: true)
JQL Filter	string	No	Custom JQL query to filter issues
Issue Types	array	No	Filter by issue type (e.g., ["Bug", "Story", "Task"])
Statuses	array	No	Filter by issue status (e.g., ["Open", "In Progress"])
Include Comments	boolean	No	Include issue comments (default: true)
Include Attachments	boolean	No	Include issue attachments
Include Worklogs	boolean	No	Include work log entries
Max Issues	integer	No	Maximum number of issues to collect

Setup Steps

1. Add Connector: Navigate to Knowledge → Add Data Source → Jira
2. Enter Instance URL: Your Jira Cloud or Server URL
3. Provide Credentials: Email and API token (Cloud) or username and password (Server)
4. Configure Filters: Set project keys, JQL filter, issue types, or statuses
5. Select Content: Choose whether to include comments, attachments, and worklogs
6. Test & Create: Verify the connection and save

JQL Filtering

JQL (Jira Query Language) gives precise control over which issues are indexed. Some useful patterns:

# Issues from specific projects
project in (ENG, PROD, INFRA)

# Open issues from the last 90 days
status != Closed AND created >= -90d

# Bugs with high priority
issuetype = Bug AND priority in (High, Highest)

# Issues with specific labels
labels = documentation

# Issues assigned to a team
assignee in membersOf("Engineering")

# Combine multiple conditions
project = ENG AND status != Closed AND updated >= -30d

Tip: Test your JQL filter in Jira's issue search before using it in ZenSearch to ensure it returns the expected results.

Content Indexed

Content	Default	Description
Summary	Always	Issue title
Description	Always	Full issue description (rich text)
Custom Fields	Always	All accessible custom fields
Comments	Configurable	Discussion threads on issues
Attachments	Configurable	Files attached to issues (parsed for content)
Worklogs	Configurable	Time tracking entries with descriptions
Labels	Always	Issue labels and tags
Components	Always	Issue components
Fix Versions	Always	Release versions

Best Practices

1. Use JQL to filter relevant issues — Index only active, recent, or documentation-relevant issues to keep your search corpus focused
2. Exclude closed/archived issues — Add status != Closed to your JQL filter to avoid cluttering search results with resolved issues
3. Include comments — Comments often contain the most useful troubleshooting information and decisions
4. Use project keys for team-specific collections — Create separate ZenSearch collections for different teams using project_keys
5. Set a max issues limit — For initial evaluation, use max_issues to limit the sync volume
6. Filter by issue type — If you only need bugs and stories, exclude sub-tasks and epics to reduce noise
7. Combine with Confluence — Many teams use Jira for tracking and Confluence for documentation; connecting both provides comprehensive coverage

Troubleshooting

Authentication failed

• Jira Cloud: Verify your email address and API token are correct. API tokens are account-specific, not instance-specific.
• Jira Server: Verify username and password. Check that the account is not locked.
• Ensure the user has at least Browse Projects permission.

No issues found

• Check your JQL filter syntax — test it in Jira's search first
• Verify the user has access to the specified projects
• If using project_keys, confirm the project keys are correct (case-sensitive)

Missing fields or content

• Verify the user has field-level permissions for custom fields
• Some custom fields may require specific Jira permissions to read
• Attachments require the Browse Projects and View Read-Only Workflow permissions

Slow sync performance

• Narrow the JQL filter to reduce the number of issues
• Disable include_attachments if attachment content is not needed (attachments require separate API calls and parsing)
• Set max_issues to limit the total sync volume

Rate limiting

• Jira Cloud enforces rate limits per API token
• ZenSearch uses concurrent connections (up to 10) — reduce concurrency if you experience rate limiting
• Schedule syncs during off-peak hours

Related

• Confluence
• GitHub