Jira
Integrating Jira as a data source for Kapa enables you to ingest issues, comments, and associated metadata from your issue tracking system.
This integration is primarily useful for internal deployments, where employees use Kapa to assist customer support or sales teams in responding to user inquiries more efficiently. For example, if a customer reports an issue, your support team can use Kapa to check whether the issue has already been reported and what the current status of it is (i.e., if a resolution is being worked on).
If you maintain a public Jira instance, you may also consider using Jira as a data source for external deployments of Kapa to provide broader access to issue data.
Prerequisites
- A Jira Cloud instance (this integration does not support Jira Server or Jira Data Center)
- An Atlassian API token
- User credentials with appropriate permissions
Data ingested
When you connect Kapa to Jira, the following issue data is ingested:
- Issue URLs
- Issue keys, summaries, descriptions, types, statuses, and priorities
- Assignees and reporter names
- Creation dates, update dates, resolution dates, and due dates
- Resolution statuses
- Labels, components, and fix versions
- Environment information, when available
- Full comment history including authors, contents, and timestamps
This data allows Kapa to provide detailed responses about your Jira issues, including their history and associated discussions. Like all other Kapa data sources, Jira issues are automatically re-ingested on a weekly basis.
To anonymize personal information, such as names and email addresses, enable PII detection and data masking.
Permissions required
The API token inherits the permissions of the user who generated it. The following permissions are required:
| Permission | Purpose | Security considerations |
|---|---|---|
| Browse Projects | Allows Kapa to view and access issues | This is the minimum permission required by Kapa to read data from your Jira instance |
For security best practices, create a service account with only the required permissions and generate an API key for that account.
Setup
Step 1: Generate an Atlassian API token
- Go to Atlassian API tokens page
- Click Create API token
- Provide a label for your token (e.g., "Kapa Integration")
- Copy and securely store the generated token
Step 2: Configure the Kapa platform
- Go to the Kapa platform
- Open the Sources tab
- Click Add new source
- Enter a name for the integration
- Select Jira, and then click Continue
- Configure your Jira connection:
- Base URL: Your Jira Cloud instance URL (e.g.,
https://example.atlassian.com) - Username: Your Jira username or email address
- API token: The Atlassian API token you generated
- Base URL: Your Jira Cloud instance URL (e.g.,
- Once your credentials are validated, configure the filters for issue selection
- Click Save to create the source and begin the initial data ingestion
Configuration options
The following configuration options are available for the Jira integration:
| Option | Description | Default | Required |
|---|---|---|---|
| Base URL | Your Jira Cloud instance URL | None | Yes |
| Username | Your Jira username or email address | None | Yes |
| API token | The Atlassian API token | None | Yes |
| Minimum date created | Only fetch issues created after this date | All time | No |
| Projects to include | Select specific projects to ingest | All projects | No |
| Statuses to include | Filter issues by status (e.g., Open, In Progress) | All statuses | No |
| Resolutions to include | Filter issues by resolution type (e.g., Fixed) | All resolutions | No |
| Issue types to include | Filter issues by issue type (e.g., Bug) | All issue types | No |
Best practices
- Use focused project selection: Rather than ingesting all projects, focus on those most relevant to your support needs
- Consider status filtering: For many use cases, only certain statuses (like "Fixed" or "Won't Fix") provide useful information
- Set appropriate date ranges: Including old issues may add noise to your knowledge base
- Create a dedicated service account: For better security and tracking, create a specific Jira account for Kapa integration
- Enable PII masking: If privacy is a concern, enable PII detection to anonymize personal information
Troubleshooting
- Authentication errors: Verify your API token is valid and hasn't expired
- Permission denied: Ensure the user account has the necessary permissions for the projects you're trying to access
- No issues appearing: Check that your projects contain issues matching your filter criteria