JIRA Integration

AgenticAnts provides seamless integration with Atlassian JIRA for creating tickets and tracking issues from AI agent recommendations and automations. This integration enables teams to streamline their workflow by automatically creating and managing JIRA tickets based on AI-generated insights.

Overview

The JIRA integration allows you to:

• Create JIRA tickets directly from AI recommendations
• Auto-populate tickets with detailed recommendation information
• Track ticket status (created, in progress, done)
• Display assignee information
• Add tracking labels automatically
• Map AI agents to team names and JIRA projects
• Discover and list all available JIRA projects/boards

Features

Core Capabilities

• FR1.2: Project administrators can configure Atlassian JIRA integration
• FR1.4: System discovers and lists all JIRA projects/boards
• FR1.5: Administrators can map agents to team names and JIRA projects
• FR4.1: Create JIRA ticket button for new recommendations
• FR4.2: Auto-populate ticket with recommendation details
• FR4.3: Track JIRA ticket status (created, in progress, done)
• FR4.4: Display assignee information
• FR4.5: Add tracking labels to tickets

Security

• All sensitive data (API tokens) are encrypted using shared encryption utilities
• Integration details are stored per-project with proper access controls
• OAuth flow includes state validation for security
• API tokens are never exposed in the UI or logs

Setup

Prerequisites

• An active Atlassian JIRA account
• Project administrator access in AgenticAnts
• JIRA API token (instructions below)

Getting a JIRA API Token

1. Go to Atlassian Account Settings (opens in a new tab)
2. Click "Create API token"
3. Give it a meaningful label (e.g., "AgenticAnts Integration")
4. Copy the generated token immediately (you won't be able to see it again)

Environment Variables

Add the following environment variables to your .env file:

# JIRA OAuth Configuration (for future OAuth implementation)
JIRA_CLIENT_ID=your_jira_client_id
JIRA_CLIENT_SECRET=your_jira_client_secret
JIRA_STATE_SECRET=your_jira_state_secret

Database Schema

The integration uses the following database schema:

CREATE TABLE jira_integrations (
    id VARCHAR PRIMARY KEY DEFAULT cuid(),
    project_id VARCHAR UNIQUE NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
 
    -- JIRA connection details
    jira_host VARCHAR NOT NULL,
    jira_email VARCHAR NOT NULL,
    jira_api_token VARCHAR NOT NULL, -- encrypted
 
    -- Metadata
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW(),
 
    INDEX idx_jira_project (project_id)
);

Configuration

Connecting to JIRA

1. Navigate to your project settings in AgenticAnts
2. Go to the Integrations tab
3. Click Configure next to JIRA
4. Enter your JIRA instance details:
   • JIRA Host URL: Your JIRA instance URL (e.g., https://company.atlassian.net)
   • Email Address: Your JIRA account email
   • API Token: The token you generated earlier
5. Click Connect to establish the integration
6. The system will validate your credentials and fetch available projects

Project Mapping

After connecting, you can map AI agents to JIRA projects:

1. Select the JIRA project you want to use
2. Map specific AI agents to team names
3. Configure default issue types and priorities
4. Set up automatic label tagging

Usage

Creating JIRA Tickets from UI

When you receive AI recommendations in AgenticAnts:

1. Navigate to the recommendation you want to track
2. Click the Create JIRA Ticket button
3. Review the auto-populated fields:
   • Summary (recommendation title)
   • Description (detailed recommendation)
   • Labels (automatically added from context)
4. Optionally customize the ticket details
5. Click Create to submit to JIRA
6. The ticket link will appear in the recommendation view

Programmatic Ticket Creation

Use the CreateJiraTicketButton component in your custom UI:

import { CreateJiraTicketButton } from "@/src/features/jira/components/CreateJiraTicketButton";
 
<CreateJiraTicketButton
  projectId={projectId}
  summary="Fix recommendation issue"
  description="Detailed description of the issue..."
  labels={["agenticants", "recommendation", "bug"]}
  onSuccess={(issueKey, issueId) => {
    console.log(`Created ticket ${issueKey}`);
    // Handle success (e.g., update UI, show notification)
  }}
/>

Tracking Ticket Status

Once a ticket is created:

1. The ticket status is displayed in AgenticAnts
2. Click the JIRA link to view the full ticket
3. Status updates from JIRA are reflected in real-time
4. Assignee information is shown alongside the ticket

API Reference

API Endpoints

GET /api/public/jira/install

Handles JIRA installation flow and redirects to manual configuration.

Response:

{
  "success": true,
  "redirect_url": "/settings/integrations"
}

GET /api/public/jira/oauth

Handles JIRA OAuth callback and stores integration details.

Query Parameters:

• code: OAuth authorization code
• state: Security state token

Response:

{
  "success": true,
  "integration_id": "cuid_xxxx"
}

Components

JiraConnectionCard

Displays connection status and provides connect/disconnect actions.

<JiraConnectionCard projectId={projectId} />

JiraConnectButton

Opens a dialog for entering JIRA connection details.

<JiraConnectButton projectId={projectId} onConnect={handleConnect} />

JiraDisconnectButton

Confirms and executes disconnection of JIRA integration.

<JiraDisconnectButton projectId={projectId} onDisconnect={handleDisconnect} />

JiraProjectSelector

Allows selection and configuration of JIRA projects.

<JiraProjectSelector
  projectId={projectId}
  onProjectSelect={handleProjectSelect}
/>

JiraUserSelector

Allows selection of JIRA users for ticket assignment.

<JiraUserSelector
  projectId={projectId}
  jiraProjectKey="PROJ"
  onUserSelect={handleUserSelect}
/>

Server Services

JiraService

Main service for JIRA integration operations:

class JiraService {
  // Store JIRA connection details
  async storeIntegration(projectId: string, config: JiraConfig): Promise<void>
 
  // Retrieve integration details
  async getIntegration(projectId: string): Promise<JiraIntegration | null>
 
  // Remove integration
  async deleteIntegration(projectId: string): Promise<void>
 
  // Validate JIRA credentials
  async validateCredentials(config: JiraConfig): Promise<boolean>
 
  // Fetch available JIRA projects
  async getProjects(projectId: string): Promise<JiraProject[]>
 
  // Create a new JIRA issue
  async createIssue(projectId: string, issue: IssueConfig): Promise<JiraIssue>
 
  // Get issue details
  async getIssue(projectId: string, issueKey: string): Promise<JiraIssue>
 
  // Get available users for a project
  async getUsers(projectId: string, jiraProjectKey: string): Promise<JiraUser[]>
}

TRPC Routes

jira.getIntegrationStatus

Returns the current connection status for a project.

const status = await trpc.jira.getIntegrationStatus.query({ projectId })
// Returns: { connected: boolean, jiraHost?: string }

jira.getProjects

Fetches available JIRA projects for the connected instance.

const projects = await trpc.jira.getProjects.query({ projectId })
// Returns: JiraProject[]

jira.disconnect

Disconnects the JIRA integration for a project.

await trpc.jira.disconnect.mutate({ projectId })

jira.createIssue

Creates a new JIRA issue with specified details.

const issue = await trpc.jira.createIssue.mutate({
  projectId,
  summary: "Issue title",
  description: "Detailed description",
  projectKey: "PROJ",
  issueType: "Bug",
  labels: ["ai-generated", "urgent"]
})
// Returns: { issueKey: string, issueId: string, url: string }

jira.getUsers

Fetches available users for a specific JIRA project.

const users = await trpc.jira.getUsers.query({
  projectId,
  jiraProjectKey: "PROJ"
})
// Returns: JiraUser[]

Best Practices

Ticket Organization

• Use consistent label naming conventions (e.g., agenticants-, ai-, recommendation-)
• Map different agent types to different JIRA projects or issue types
• Set up JIRA automation rules to handle AgenticAnts tickets
• Create custom JIRA dashboards for AI-generated tickets

Security

• Rotate API tokens regularly (every 90 days recommended)
• Use dedicated service accounts for AgenticAnts integration
• Limit JIRA permissions to only what's needed (create/update issues)
• Monitor API usage in JIRA audit logs

Performance

• Batch create tickets when possible
• Use JIRA's bulk import for historical data
• Set up webhooks for real-time status updates (future feature)
• Cache JIRA project/user data to reduce API calls

Troubleshooting

Common Issues

"Invalid credentials" error

• Verify your JIRA host URL is correct (include https://)
• Ensure you're using an API token, not your password
• Check that your email matches the JIRA account
• Verify the token hasn't expired or been revoked

"No projects found"

• Ensure your JIRA account has access to at least one project
• Check that your API token has correct permissions
• Verify the JIRA instance is accessible from your network

"Failed to create ticket"

• Confirm the project key is correct
• Verify the issue type exists in the project
• Check that required fields are populated
• Ensure you have create permission in the project

Connection timeout

• Check your network connectivity
• Verify JIRA instance is not behind a firewall
• Test the JIRA API directly using curl
• Check for any proxy settings

Debug Mode

Enable debug logging to troubleshoot issues:

# In your .env file
DEBUG=agenticants:jira:*
LOG_LEVEL=debug

View logs in the browser console or server logs:

# Server logs
tail -f logs/jira-integration.log
 
# Filter for JIRA-specific entries
grep "JIRA" logs/server.log

Future Enhancements

The following features are planned for future releases:

• Full OAuth Flow: Complete OAuth implementation with Atlassian marketplace app registration
• Webhook Support: Real-time status updates from JIRA to AgenticAnts
• Bulk Operations: Create multiple tickets from a single recommendation batch
• Advanced Templates: Customizable ticket templates and workflows
• Automation Rules: Integration with JIRA automation for advanced workflows
• Custom Fields: Support for JIRA custom fields in ticket creation
• Bi-directional Sync: Update recommendations based on JIRA ticket changes
• Sprint Integration: Automatically add tickets to active sprints
• Time Tracking: Report time spent on AI-recommended tasks

Support

Need help with the JIRA integration?

• Documentation: This guide and inline help
• Community: Join our Discord (opens in a new tab)
• GitHub: Report issues (opens in a new tab)
• Email: support@agenticants.ai

For enterprise customers:

• Dedicated Support: Direct access to our integration specialists
• Custom Setup: We'll help configure your JIRA integration
• Training: Onboarding sessions for your team

Related Resources

• Slack Integration - Send notifications to Slack
• Webhook Integration - Custom integrations
• API Reference - Full API documentation
• Security Best Practices - Securing integrations

Ready to connect JIRA? Head to your project settings and get started!