Jira Connector

Manage issues, projects, sprints, and epics in Atlassian Jira

Jira Connector

Automate your issue tracking and project management with Jira. Create bugs, manage sprints, transition issues through your workflow, and keep your team synchronized—all from DeepChain.

Overview

The Jira connector provides 12 powerful operations for managing your software development lifecycle. Whether you're automating bug reports, managing releases, or coordinating across teams, this connector makes it seamless.

Authentication

Jira supports two authentication methods:

Option 1: OAuth 2.0 (Recommended)

Secure, user-authorized access:

auth_type: oauth2
client_id: "your-app-id"
client_secret: "your-app-secret"
cloud_id: "your-cloud-id"

How to set it up:

  1. Go to atlassian.com > API tokens and create an OAuth app
  2. Set redirect URI: https://yourapp.deepchain.dev/oauth/callback
  3. Copy your Client ID and Client Secret

Option 2: API Token

Simple API key authentication:

auth_type: api_token
email: "user@company.com"
token: "your-api-token"
domain: "your-domain.atlassian.net"

Create an API token at atlassian.com > Profile > Personal API tokens.

Available Operations

Operation What It Does
getIssue Fetch an issue by key (e.g., PROJ-123)
createIssue Create a new issue (bug, story, task, etc.)
updateIssue Update issue fields (status, priority, assignee, etc.)
deleteIssue Delete an issue
addComment Add a comment to an issue
transitionIssue Move issue to a different status
assignIssue Assign an issue to a team member
listProjects List all projects
getProject Get project details
searchIssues Search with JQL (Jira Query Language)
getSprint Get sprint details
getBoard Get board details

Practical Workflow Examples

Example 1: Auto-Create Bug from Error Log

Convert error logs into tracked bugs:

- id: create_bug
  type: jira_connector
  config:
    operation: createIssue
    fields:
      project:
        key: "PROJ"
      issuetype:
        name: "Bug"
      summary: "Error: {{ input.error_message }}"
      description: |
        *Error Details*
        • Message: {{ input.error_message }}
        • Stack Trace: {code}{{ input.stack_trace }}{code}
        • Timestamp: {{ input.timestamp }}
        • Environment: {{ input.environment }}
      priority:
        name: "{{ if(input.error_count > 10, 'High', 'Medium') }}"
      labels:
        - "auto-created"
        - "{{ input.service }}"

Example 2: Create Issue and Assign to Team

Create a task and immediately assign it:

- id: create_task
  type: jira_connector
  config:
    operation: createIssue
    fields:
      project:
        key: "PROJ"
      issuetype:
        name: "Task"
      summary: "{{ input.title }}"
      description: "{{ input.description }}"
      assignee:
        name: "{{ input.assignee_email }}"
      duedate: "{{ formatDate(input.due_date, 'yyyy-MM-dd') }}"
      customfield_10000: "{{ input.epic_key }}"  # Add to epic

Example 3: Search and Update Multiple Issues

Find all open bugs and add a label:

- id: find_open_bugs
  type: jira_connector
  config:
    operation: searchIssues
    jql: "project = PROJ AND type = Bug AND status = Open AND created >= -7d ORDER BY created DESC"
    maxResults: 50

- id: loop_bugs
  type: loop
  items: "{{ find_open_bugs_1.response }}"

- id: add_label
  type: jira_connector
  config:
    operation: updateIssue
    issueIdOrKey: "{{ loop_bugs_1.current.key }}"
    fields:
      labels:
        - "{{ loop_bugs_1.current.fields.labels }}"
        - "investigated"

Example 4: Transition Issue to "Done"

Move an issue through your workflow:

- id: complete_issue
  type: jira_connector
  config:
    operation: transitionIssue
    issueIdOrKey: "{{ input.issue_key }}"
    transition:
      name: "Done"
    fields:
      resolution:
        name: "Fixed"
      fixVersions:
        - name: "{{ input.release_version }}"

Example 5: Add Comment with Details

Update stakeholders on progress:

- id: add_update
  type: jira_connector
  config:
    operation: addComment
    issueIdOrKey: "{{ input.issue_key }}"
    body: |
      *Status Update*
      • Progress: {{ input.progress }}%
      • Current Focus: {{ input.current_task }}
      • Next Steps: {{ input.next_steps }}

      Updated by: {{ input.updated_by }}

Example 6: Create Release and List Issues

Find all issues for a sprint:

- id: get_sprint
  type: jira_connector
  config:
    operation: getSprint
    boardId: "{{ input.board_id }}"
    sprintId: "{{ input.sprint_id }}"

- id: find_sprint_issues
  type: jira_connector
  config:
    operation: searchIssues
    jql: "sprint = {{ input.sprint_id }} AND project = PROJ ORDER BY priority DESC"
    maxResults: 100

JQL (Jira Query Language) Tips

Use JQL in searchIssues to find exactly what you need:

# Recent bugs assigned to me
project = PROJ AND type = Bug AND assignee = currentUser() AND updated >= -7d

# High priority stories in current sprint
sprint = BOARD_SPRINT AND type = Story AND priority = High

# Issues with specific label, ordered by due date
labels = urgent AND duedate >= -7d ORDER BY duedate ASC

# Issues created by specific user
project = PROJ AND creator = "user@company.com"

Rate Limits

Jira Cloud enforces API limits:

  • REST API: 1,000 requests per minute per user
  • App limits: May vary based on app type

Note: DeepChain handles rate limiting automatically.

Error Handling

Common Jira Errors

Error What It Means How to Fix
ISSUE_NOT_FOUND Issue key doesn't exist Check the issue key (case-sensitive!)
PROJECT_NOT_FOUND Project doesn't exist or you lack access Verify project key and permissions
INVALID_TRANSITION Can't transition from current status Check available transitions in Jira
INVALID_FIELD_VALUE Field value invalid Check picklist options for that field
Unauthorized Bad API token or insufficient permissions Re-authenticate and check permissions

Debugging

Enable debug logging:

Node Configuration:
  debug: true
  logRequest: true
  logResponse: true

Best Practices

1. Use Issue Keys, Not IDs

Always use the readable issue key (e.g., "PROJ-123"):

# Good
issueIdOrKey: "PROJ-123"

# Works but less readable
issueIdOrKey: "10000"

2. Check Transition Availability

Not all transitions are available from every status. Check what's allowed:

# Check Jira project settings > Workflow to see available transitions
transition:
  name: "In Progress"  # Must exist in your workflow

3. Handle Custom Fields Correctly

Custom fields use IDs like customfield_10000. Find your field IDs in Jira:

# Go to Jira > Issues > Fields Configuration to find custom field IDs
customfield_10000: "{{ input.custom_value }}"

4. Use Labels for Organization

Add meaningful labels for filtering later:

labels:
  - "{{ input.service }}"
  - "auto-created"
  - "{{ input.team }}"

5. Batch Operations with Loops

Instead of creating issues one by one, batch them in loops:

- id: loop_items
  type: loop
  items: "{{ input.issues }}"

- id: create_each
  type: jira_connector
  config:
    operation: createIssue
    fields:
      project:
        key: "PROJ"
      issuetype:
        name: "{{ loop_1.current.type }}"
      summary: "{{ loop_1.current.title }}"

Next Steps