Skip to content

Jira On-Premises Integration Guide

This document explains how to configure and use InspectRAG's integration with Jira On-Premises installations.

Overview

The Jira On-Premises integration allows InspectRAG to index and keep synchronized your Jira issues, comments, and attachments. This integration uses Jira's webhook system to receive real-time notifications when content changes and processes them via asynchronous tasks.

Prerequisites

Before configuring the Jira On-Premises integration, ensure you have:

  • Administrative access to your Jira On-Premises installation
  • A Personal Access Token (PAT) with appropriate permissions
  • Redis server for temporary data storage
  • Network connectivity between InspectRAG and your Jira server

Configuration

Environment Variables

The following environment variables must be configured:

ONPREM_JIRA_HOST=https://jira.your-company.com
ONPREM_JIRA_PAT=your_personal_access_token
RAG_REDIS_URL=redis://localhost:6379/0
ONPREM_WEBHOOK_SECRET=YOUR_WEBHOOK_SECRET

Required Permissions

The Jira PAT needs the following permissions:

  • READ permissions on all projects you want to index
  • BROWSE permissions for issues
  • Access to view attachments

Setting Up Webhooks in Jira

  1. Log in to your Jira On-Premises instance as an administrator Jira On-Premises Integration Architecture
  2. Navigate to System > WebHooks
  3. Click Create WebHook Jira Webhook Configuration
  4. Configure the webhook:
  5. Name: InspectRAG Integration
  6. URL: https://your-inspectrag-instance.com/onprem-jira-webhook
  7. Status: Enabled
  8. Secret: Set the secret to anything you want (this will later be used in ONPREM_WEBHOOK_SECRET in .env)
  9. Events: Select the following events:
    • Issue: created
    • Issue: updated
    • Issue: deleted
    • Comment: created
    • Comment: updated
    • Comment: deleted
    • Worklog: created
    • Worklog: updated
    • Worklog: deleted
    • Project: created
    • Project: updated
    • Project: deleted
  10. Un-check the Exclude Body box.
  11. Click Create to save the webhook configuration

Data Processing

Event Types

The integration handles the following Jira event types:

Event Type Description Processing Logic
comment_created A new comment is added Indexes the comment immediately
comment_updated A comment is edited Updates the indexed comment
comment_deleted A comment is removed Removes the comment from the index
jira:issue_deleted An issue is deleted Removes all related documents from the index
jira:issue_updated An issue is modified Performs partial updates based on what changed

Content Processing

InspectRAG processes and indexes several components of Jira issues:

  1. Issue Description: The summary and description fields are combined into a single document.
  2. Comments: Each comment is stored as a separate document with metadata about the author.
  3. Attachments: Files attached to issues are downloaded, processed based on their file type, and indexed.

Metadata Capture

Metadata Key Description Example
file_id Unique document ID combining issue key and specific identifier PROJECT-123-description
issue_key Jira issue key PROJECT-123
source_type Document type: description, comment, or attachment comment
platform Fixed value indicating the source platform jira
issue_updated (description) Timestamp when the issue was last updated 2023-05-10T15:30:00.000Z
comment_id (comments) Unique ID of the comment 456789
comment_author (comments) Display name of the comment author Jane Doe
comment_updated (comments) Timestamp of comment creation or update 2023-05-11T12:00:00.000Z
attachment_id (attachments) Unique ID of the attachment 987654
attachment_filename (attachments) Original file name of the attachment screenshot.png
creator (attachments) Display name of the attachment creator John Smith
attachment_created (attachments) Timestamp when the attachment was added 2023-05-09T08:45:00.000Z

Delta Processing

The integration uses an efficient delta processing approach:

  1. Each received webhook triggers a Celery task
  2. The system uses a 2-second debounce mechanism to prevent duplicate processing
  3. For issue updates, it compares the new state with the previous state stored in Redis
  4. Only changed components (description, attachments) are re-indexed

Troubleshooting

Common Issues

Issue Possible Causes Solution
Webhook events not received Network connectivity, incorrect URL Verify network settings, check Jira webhook logs
Authentication failures Invalid or expired PAT Generate a new PAT in Jira
Missing content Permission issues Ensure PAT has access to all relevant projects
Attachment processing failures Unsupported file types Check logs for file format errors

Logging

The integration logs detailed information about each step of the process. To increase logging verbosity:

  1. Adjust the logging level in your settings
  2. Monitor the Celery task logs for webhook processing information

Testing Connection

You can test the connection to your Jira instance with:

curl -H "Authorization: Bearer YOUR_PAT" https://jira.your-company.com/rest/api/2/myself

This should return your user information if the connection and authentication are working correctly.

Performance Considerations

  • The integration uses asynchronous processing to handle high volumes of updates
  • Attachments are processed in a streaming manner to minimize memory usage
  • Redis is used as temporary storage to track issue state between updates
  • File downloads are performed in a dedicated temporary directory

Security Considerations

  • All credentials are stored as environment variables, not in code
  • PATs should be configured with the minimum required permissions
  • Network traffic between InspectRAG and Jira should be encrypted
  • Redis data is temporary and doesn't contain sensitive information
  • Temporary files are removed after processing

Limitations

  • The integration doesn't process custom fields by default
  • Very large attachments may take longer to process
  • Rate limiting may apply based on your Jira instance configuration