jira-connector 1.0.2

A flexible and powerful Python connector for interacting with Jira API

Generic Jira Connector

A flexible and powerful Python connector for interacting with Jira API. This connector allows you to connect to any Jira instance and dynamically read specified properties from issues.

Features

• Generic Design: Works with any Jira instance (Atlassian Cloud, Jira Server, Jira Data Center)
• Flexible Authentication: Supports both Bearer token and basic authentication
• Dynamic Property Reading: Extract any Jira issue properties using dot notation
• Configuration Management: Built-in support for multiple Jira service configurations
• Error Handling: Comprehensive error handling with retry logic
• Logging: Detailed logging for debugging and monitoring
• Environment Variables: Support for environment-based configuration

Installation

Install from PyPI (Recommended)

pip install jira-connector

This will automatically install all required dependencies:

• requests>=2.31.0
• urllib3>=1.26.0

Install from Source

git clone https://github.com/yourusername/jira-connector.git
cd jira-connector
pip install .

Development Installation

git clone https://github.com/yourusername/jira-connector.git
cd jira-connector
pip install -e .[dev]

Install with Optional Dependencies

# For development
pip install jira-connector[dev]

# For documentation
pip install jira-connector[docs]

# For testing
pip install jira-connector[test]

Quick Start

Basic Usage

from jira_connector import JiraConnector

# Initialize connector
connector = JiraConnector(
    jira_url="https://yourcompany.atlassian.net",
    token="your_api_token_here",
    service="my_service"
)

# Test connection
if connector.test_connection():
    print("Connection successful!")
    
    # Get specific issue with custom properties
    properties = [
        'key',
        'fields.summary',
        'fields.status.name',
        'fields.assignee.displayName'
    ]
    
    issue = connector.get_issue("PROJ-123", properties)
    print(issue)

# Close connection
connector.close()

Using Environment Variables

export JIRA_URL="https://yourcompany.atlassian.net"
export JIRA_TOKEN="your_api_token_here"
export JIRA_USERNAME="your_username"  # Optional

import os
from jira_connector import JiraConnector

connector = JiraConnector(
    jira_url=os.getenv('JIRA_URL'),
    token=os.getenv('JIRA_TOKEN'),
    service="my_service",
    username=os.getenv('JIRA_USERNAME')  # Optional
)

API Reference

JiraConnector Class

Initialization Parameters

• jira_url (str): Base URL of Jira instance
• token (str): API token for authentication
• service (str): Service name for logging (default: "jira")
• username (str, optional): Username for basic auth
• timeout (int): Request timeout in seconds (default: 30)
• verify_ssl (bool): Verify SSL certificates (default: True)
• max_retries (int): Maximum retry attempts (default: 3)

Main Methods

Connection Methods

• test_connection(): Test connection to Jira
• close(): Close the session

Issue Methods

• get_issue(issue_key, properties=None): Get issue details
• search_issues(jql, properties=None, max_results=50, start_at=0): Search issues using JQL
• get_project_issues(project_key, properties=None, max_results=50, start_at=0): Get issues from project
• create_issue(project_key, issue_type, summary, description=None, **fields): Create new issue
• update_issue(issue_key, **fields): Update existing issue

Comment Methods

• add_comment(issue_key, comment): Add comment to issue

Transition Methods

• get_issue_transitions(issue_key): Get available transitions
• transition_issue(issue_key, transition_id): Transition issue to new status

Utility Methods

• get_projects(): Get all accessible projects
• get_custom_fields(): Get all custom fields

Property Extraction

Use dot notation to extract nested properties:

properties = [
    'key',                                    # Issue key
    'fields.summary',                         # Issue summary
    'fields.status.name',                     # Status name
    'fields.status.statusCategory.name',     # Status category
    'fields.assignee.displayName',           # Assignee name
    'fields.customfield_10010',               # Custom field
    'fields.customfield_10020.value',         # Nested custom field
]

Examples

Search Issues with JQL

# Find all open bugs in a project
jql = "project = PROJ AND issuetype = Bug AND status != Closed"
issues = connector.search_issues(jql, properties, max_results=100)

# Find issues assigned to me
jql = "assignee = currentUser() AND status = 'In Progress'"
my_issues = connector.search_issues(jql, properties)

Work with Custom Fields

# Get all custom fields
custom_fields = connector.get_custom_fields()

# Use custom field in property extraction
properties = [
    'key',
    'fields.summary',
    'fields.customfield_10010',  # Text field
    'fields.customfield_10020.value',  # Select field
]

issues = connector.search_issues("project = PROJ", properties)

Create and Update Issues

# Create new issue
new_issue = connector.create_issue(
    project_key="PROJ",
    issue_type="Task",
    summary="New task from connector",
    description="Task description",
    priority={"name": "High"},
    labels=["urgent", "backend"]
)

# Update issue
connector.update_issue(
    issue_key="PROJ-123",
    summary="Updated summary",
    priority={"name": "Medium"}
)

Add Comments and Transitions

# Add comment
connector.add_comment("PROJ-123", "Working on this issue")

# Get available transitions
transitions = connector.get_issue_transitions("PROJ-123")

# Transition issue
if transitions:
    transition_id = transitions[0]['id']
    connector.transition_issue("PROJ-123", transition_id)

Environment Variables

Required

• JIRA_URL: Your Jira instance URL
• JIRA_TOKEN: Your API token

Optional

• JIRA_USERNAME: Username for basic auth
• JIRA_TIMEOUT: Request timeout (default: 30)
• JIRA_VERIFY_SSL: Verify SSL certificates (default: true)
• JIRA_MAX_RETRIES: Maximum retry attempts (default: 3)

Error Handling

The connector includes comprehensive error handling:

• Retry Logic: Automatic retries for failed requests
• Logging: Detailed error messages and debug information
• Graceful Degradation: Continues operation even if some requests fail

try:
    issues = connector.search_issues(jql, properties)
except Exception as e:
    print(f"Search failed: {e}")
    # Handle error appropriately

Security Considerations

1. API Tokens: Store API tokens securely, don't commit them to version control
2. Environment Variables: Use environment variables for sensitive data
3. SSL Verification: Keep SSL verification enabled in production
4. Access Control: Use tokens with minimal required permissions

Troubleshooting

Common Issues

1. Authentication Failed

   • Check API token is valid and not expired
   • Verify correct authentication method (token vs basic auth)

2. SSL Certificate Error

   • Set verify_ssl=False for self-signed certificates (not recommended for production)
   • Check if Jira URL is correct

3. Permission Denied

   • Ensure token has required permissions
   • Check user has access to the project/issue

4. Rate Limiting

   • Implement delays between requests
   • Use appropriate timeout values

Debug Logging

Enable debug logging:

import logging
logging.getLogger("JiraConnector").setLevel(logging.DEBUG)

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

This project is licensed under the MIT License.

Support

For issues and questions:

• Check the troubleshooting section
• Review the example usage in example_usage.py
• Create an issue in the repository