Jira Integration Guide

Overview

The Jira integration allows your NINA workflows to seamlessly connect with Atlassian Jira for issue tracking and project management. This integration enables you to create, retrieve, update, and manage Jira issues, comments, attachments, and users directly from your workflows.

API Version: This integration uses Jira Cloud REST API v3 for all operations, ensuring compatibility with the latest Atlassian standards and features.

Status

We currently support CRUD operations for Issues (including attachments and comments) and Users (read for any Jira, write for Jira Server).

Some of the main resources we do not yet support include:

• Announcement Banner: Management of system-wide announcement banners.
• App Data Policies: Configuration and management of application data policies.
• Application Roles: Management of roles assigned to applications.
• Audit Records: Access to logs and records of system activities.
• Dashboards: Creation and management of custom dashboards for issue tracking.
• Filters: Management of saved search filters for issues.
• Groups: Management of user groups for permissions and access control.
• Permission Schemes: Management of permissions for different user roles.
• Projects: management of projects.
• Screens: Customization of screens used for issue creation and editing.
• Status: Management of issue statuses within workflows.
• Webhooks: Setup and management of webhooks for event notifications.
• Workflows: Management of workflows

Credential Configuration

Before using the Jira integration in your workflows, you need to configure credentials for authentication. The NINA platform supports three authentication methods for Jira:

Authentication Methods

1. Jira Cloud

For Atlassian Cloud-hosted Jira instances:

Field	Description	Example
Domain	Your Jira domain	your-company.atlassian.net
Email	Email address for your Atlassian account	[email protected]
API Token	API token generated from Atlassian account settings	ATATT3xFfGF0aW8n...

How to get your API Token:

1. Log in to your Atlassian account at https://id.atlassian.com/manage-profile/security/api-tokens
2. Click "Create API token"
3. Give the token a name (e.g., "NINA Integration")
4. Copy the generated token

2. Jira Server (Basic Auth)

For self-hosted Jira Server instances using username/password:

Field	Description	Example
Domain	Your Jira server URL	https://jira.your-company.com
Username	Your Jira username	username
Password	Your Jira password	password

3. Jira Server (Personal Access Token)

For self-hosted Jira Server instances using PAT:

Field	Description	Example
Domain	Your Jira server URL	https://jira.your-company.com
Personal Access Token	PAT generated from your Jira account	NjM4MzE2NDEwNTE0OkfPwMVBp7...

Creating a Jira Credential

1. Navigate to the Credentials section in NINA

2. Click Add New Credential

3. Fill in the credential details:

   • Name: A descriptive name (e.g., "Jira Production")
   • Description: Optional details about the credential's purpose
   • Integration Service: Select "Jira"
   • Auth Type: Choose "Jira Cloud", "Jira Server", or "Jira Server (PAT)"
   • Domain: Enter your Jira domain/URL
   • Fill in the authentication fields based on your selected auth type

4. Click Test Connection to verify credentials

5. Click Save to store the credential

Supported Resources and Operations

The Jira integration supports the following resources and operations:

Issue

Operation	Description
Create	Creates a new Jira issue
Get	Retrieves details of a specific issue
Update	Updates an existing issue
Delete	Deletes an issue
Search (getAll)	Searches for issues using JQL (Jira Query Language). Note: A JQL query is required - empty searches are not allowed by Jira API v3.
Natural Language Search	Searches for issues using natural language queries (AI-powered). Automatically converts your natural language query to JQL and returns matching issues.

Issue Attachment

Operation	Description
Add	Adds a file attachment to an issue
Get	Retrieves attachment information
Remove	Deletes an attachment

Issue Comment

Operation	Description
Add	Adds a comment to an issue
Get	Retrieves a specific comment
Get All	Retrieves all comments for an issue
Update	Updates an existing comment
Remove	Deletes a comment

User

Operation	Description
Get	Retrieves user information
Create*	Creates a new user (Jira Server only)
Delete*	Deletes a user (Jira Server only)

*Note: User creation and deletion are only available for Jira Server, not Jira Cloud.

Parameter Merging and Templating

The Jira integration takes full advantage of NINA's parameter merging and templating capabilities:

Parameter Sources (in order of precedence)

1. Node Parameters: Parameters configured directly in the Jira Integration Node
2. Extracted Parameters: Parameters automatically extracted from the input data
3. Input Data: The complete input data from upstream nodes

When a Jira Integration Node executes:

• It combines parameters from all sources
• Node parameters take precedence over extracted parameters
• Template variables within parameters are processed (using {{variable_name}} syntax)
• The combined parameters are used to execute the Jira operation

Example: Creating a Jira Issue

Basic Issue Creation

Below is an example of creating a basic Jira issue using the Integration Node:

Node Configuration:

{
  "integration_service": "jira",
  "resource": "issue",
  "operation": "create",
  "parameters": {
    "project": {
      "mode": "id",
      "value": "10001"
    },
    "issueType": {
      "mode": "id",
      "value": "10004"
    },
    "summary": "Security vulnerability detected",
    "additionalFields": {
      "description": "A critical SQL injection vulnerability was found in the login form.",
      "labels": ["security", "vulnerability"]
    }
  }
}

Creating an Issue with Template Variables

You can use template variables to dynamically insert values from input data:

Input Data from Previous Node:

{
  "vulnerability": {
    "type": "SQL Injection",
    "severity": "Critical",
    "location": "login.php",
    "description": "The login form is vulnerable to SQL injection attacks."
  },
  "scan_date": "2024-05-12"
}

Node Configuration with Template Variables:

{
  "integration_service": "jira",
  "resource": "issue",
  "operation": "create",
  "parameters": {
    "project": {
      "mode": "id", 
      "value": "10001"
    },
    "issueType": {
      "mode": "id",
      "value": "10004"
    },
    "summary": "{{vulnerability.severity}} {{vulnerability.type}} in {{vulnerability.location}}",
    "additionalFields": {
      "description": "**Vulnerability Details:**\n\n{{vulnerability.description}}\n\nDetected on: {{scan_date}}",
      "labels": ["security", "vulnerability", "{{vulnerability.type}}"]
    }
  }
}

Result:

This will create a Jira issue with:

• Summary: "Critical SQL Injection in login.php"
• Description containing the vulnerability details and scan date
• Labels: ["security", "vulnerability", "SQL Injection"]

Creating an Issue with Upstream Data Extraction

When an upstream node provides Jira-specific data, the Integration Node can automatically extract and use it:

Input Data from Previous Node:

{
  "project": "SEC",
  "issueType": "Bug",
  "summary": "Server timeout during peak hours",
  "description": "The application server is timing out when user load exceeds 1000 concurrent users.",
  "priority": "High",
  "assignee": "[email protected]"
}

Node Configuration (Minimal):

{
  "integration_service": "jira",
  "resource": "issue",
  "operation": "create",
  "parameters": {
    "labels": ["performance", "server"]
  }
}

Final Merged Parameters:

The integration automatically extracts Jira-specific fields from the input data and merges them with the node parameters:

{
  "project": "SEC",
  "issueType": "Bug",
  "summary": "Server timeout during peak hours",
  "description": "The application server is timing out when user load exceeds 1000 concurrent users.",
  "priority": "High",
  "assignee": "[email protected]",
  "labels": ["performance", "server"]
}

Example: Working with Issue Comments

Adding a Comment to an Issue

Node Configuration:

{
  "integration_service": "jira",
  "resource": "issueComment",
  "operation": "add",
  "parameters": {
    "issueKey": "SEC-1234",
    "comment": "This issue has been investigated. Root cause identified as memory leak in the authentication module."
  }
}

Adding a Comment with Template Variables

Input Data:

{
  "issue_id": "SEC-1234",
  "investigation": {
    "root_cause": "Memory leak in authentication module",
    "affected_components": ["auth-service", "session-manager"],
    "fix_status": "In Progress"
  },
  "assignee": "jane.smith"
}

Node Configuration:

{
  "integration_service": "jira",
  "resource": "issueComment",
  "operation": "add",
  "parameters": {
    "issueKey": "{{issue_id}}",
    "comment": "**Investigation Results:**\n\n- Root Cause: {{investigation.root_cause}}\n- Affected Components: {{investigation.affected_components}}\n- Fix Status: {{investigation.fix_status}}\n\nAssigned to {{assignee}} for resolution."
  }
}

Getting All Comments for an Issue

Node Configuration:

{
  "integration_service": "jira",
  "resource": "issueComment",
  "operation": "getAll",
  "parameters": {
    "issueKey": "SEC-1234",
    "returnAll": true
  }
}

Example: Working with Attachments

Adding an Attachment to an Issue

Input Data:

{
  "issue_key": "SEC-1234",
  "scan_report": {
    "name": "vulnerability_scan_report.pdf",
    "data": "BASE64_ENCODED_CONTENT_HERE"
  }
}

Node Configuration:

{
  "integration_service": "jira",
  "resource": "issueAttachment",
  "operation": "add",
  "parameters": {
    "issueKey": "{{issue_key}}",
    "binaryPropertyName": "scan_report"
  }
}

Removing an Attachment

Node Configuration:

{
  "integration_service": "jira",
  "resource": "issueAttachment",
  "operation": "remove",
  "parameters": {
    "attachmentId": "12345"
  }
}

Example: User Operations

Getting User Information

Node Configuration:

{
  "integration_service": "jira",
  "resource": "user",
  "operation": "get",
  "parameters": {
    "accountId": "5b10a2844c20165700ede21g"
  }
}

Creating a User (Jira Server Only)

Node Configuration:

{
  "integration_service": "jira",
  "resource": "user",
  "operation": "create",
  "parameters": {
    "username": "john.doe",
    "emailAddress": "[email protected]",
    "displayName": "John Doe",
    "additionalFields": {
      "password": "secure_password",
      "notification": true
    }
  }
}

Working with JQL (Jira Query Language)

Important: Jira Cloud REST API v3 requires a valid JQL query for all search operations. Empty searches are not allowed.

JQL queries use the syntax: field operator value. Common fields include project, status, priority, assignee, created, updated, summary, and labels.

Basic JQL Examples

Search by project:

{
  "parameters": {
    "options": {
      "jql": "project = SEC ORDER BY created DESC"
    }
  }
}

Search with multiple conditions:

{
  "parameters": {
    "options": {
      "jql": "project = SEC AND status = 'In Progress' AND priority = High"
    }
  }
}

Search with text matching:

{
  "parameters": {
    "options": {
      "jql": "project = SEC AND summary ~ 'vulnerability' AND created >= '2024-01-01'"
    }
  }
}

JQL with Template Variables

{
  "parameters": {
    "options": {
      "jql": "project = {{project_key}} AND priority = {{priority_level}} AND summary ~ '{{search_text}}'"
    }
  }
}

Key JQL Notes

• Quotes: Use single quotes for text values with spaces: status = 'In Progress'
• Operators: =, !=, >, <, ~ (contains), IN, AND, OR, NOT
• Functions: currentUser(), now(), startOfDay(), membersOf("group")
• Pagination: Use limit and returnAll parameters for large result sets

For more details, see Atlassian JQL Documentation.

Natural Language Search (AI-Powered)

The Jira integration supports searching issues using natural language queries, powered by Atlassian Intelligence's AI capabilities. This feature automatically converts your plain English queries into JQL, making it easier to search without learning JQL syntax.

How It Works

The Natural Language Search operation:

1. Takes your natural language query (e.g., "show me my open bugs")
2. Uses Jira's AI GraphQL API to convert it to JQL
3. Executes the generated JQL query
4. Returns the matching issues along with the generated JQL for transparency

Requirements

• Jira Cloud only (not available for Jira Server)
• Requires an active Atlassian Intelligence subscription (available on Standard, Premium, and Enterprise plans)
• Uses the @optIn experimental feature flag for the GraphQL API

Basic Natural Language Search Examples

Simple query for your activities:

{
  "integration_service": "jira",
  "resource": "issue",
  "operation": "naturalLanguageSearch",
  "parameters": {
    "query": "show me my activities from the last week"
  }
}

Generated JQL: assignee = currentUser() AND updated > startOfWeek("-1") ORDER BY updated DESC

Finding high-priority bugs:

{
  "integration_service": "jira",
  "resource": "issue",
  "operation": "naturalLanguageSearch",
  "parameters": {
    "query": "high priority bugs assigned to me",
    "limit": 20
  }
}

Project-specific search:

{
  "integration_service": "jira",
  "resource": "issue",
  "operation": "naturalLanguageSearch",
  "parameters": {
    "query": "open issues in the security project created this month"
  }
}

With Template Variables

You can use template variables in your natural language queries:

Input Data:

{
  "project_name": "Security",
  "status": "In Progress",
  "assignee": "john.doe"
}

Node Configuration:

{
  "integration_service": "jira",
  "resource": "issue",
  "operation": "naturalLanguageSearch",
  "parameters": {
    "query": "{{status}} issues in {{project_name}} assigned to {{assignee}}",
    "limit": 50,
    "fields": "summary,status,priority,assignee"
  }
}

Response Format

The Natural Language Search operation returns the same result structure as the regular search, plus two additional fields:

{
  "issues": [...],
  "generatedJQL": "assignee = currentUser() AND updated > startOfWeek(\"-1\") ORDER BY updated DESC",
  "naturalLanguageQuery": "show me my activities from the last week",
  "isLast": true
}

The generatedJQL field shows you exactly what JQL was generated, which is useful for:

• Understanding how your query was interpreted
• Learning JQL syntax
• Debugging unexpected results
• Reusing the generated JQL in future queries

Parameters

Parameter	Type	Required	Default	Description
query	string	Yes	-	Natural language query (e.g., "show me open bugs")
returnAll	boolean	No	false	Whether to return all results or limit to limit
limit	number	No	50	Maximum number of results to return
fields	string	No	"*all"	Comma-separated list of fields to include (e.g., "summary,status,priority")
expand	array	No	-	Additional data to include in response

Best Practices for Natural Language Search

1. Be Specific: More specific queries produce better results

   • Good: "critical bugs in login module created this week"
   • Less Good: "bugs"

2. Use Common Terms: The AI understands standard Jira terminology

   • "assigned to me", "high priority", "open", "in progress", etc.

3. Fallback to JQL: If the AI can't interpret your query, you'll get an error. In such cases, use the regular getAll operation with JQL.

4. Review Generated JQL: Check the generatedJQL in the response to understand how your query was interpreted. This helps you refine future queries.

5. Test Queries: Test your natural language queries to ensure they produce expected results before using them in production workflows.

6. Field Selection: Specify the fields parameter to limit returned data and improve performance:

   {
     "query": "my open issues",
     "fields": "summary,status,priority"
   }

Error Handling

If the natural language query cannot be converted to JQL, the operation will return an error:

{
  "error": "failed to convert natural language to JQL: JQL generation error occurred"
}

Common reasons for errors:

• The query is too ambiguous
• The AI service is temporarily unavailable
• Your Jira instance doesn't have Atlassian Intelligence enabled
• Network connectivity issues with the GraphQL API

Comparison: Natural Language vs JQL

Aspect	Natural Language Search	JQL Search
Ease of Use	Very easy - no syntax to learn	Requires JQL knowledge
Precision	Good for common queries	More precise control
Availability	Jira Cloud only (with AI subscription)	All Jira versions
Performance	Slightly slower (2 API calls)	Faster (1 API call)
Transparency	Returns generated JQL	You write the JQL
Best For	Quick searches, user-friendly interfaces	Complex queries, advanced users

Troubleshooting

Issue	Resolution
Authentication failures	Verify your credential configuration: check API token/username/password and ensure the domain is correct. For cloud instances, ensure you're using your email, not username.
"Project not found" errors	Verify the project ID or key is correct. You can find this in the URL when viewing the project in Jira (e.g., .../browse/SEC where SEC is the project key).
Issue type errors	Ensure the issue type ID is valid for the specified project. Different projects may support different issue types.
JQL query errors	Verify your JQL syntax. Common errors include missing quotes around text values or using incorrect field names.
Permission errors	The user associated with the credentials must have permission to perform the requested operation in Jira.
Rate limiting	If you hit rate limits, implement delays between operations or reduce frequency. Jira Cloud has stricter rate limits than Jira Server.
Attachment errors	Check the file size - Jira has attachment size limits (usually 10MB for cloud).
OAuth token expiration	For OAuth-based authentication, tokens may expire. The system should automatically refresh them, but if not, recreate the credential.

Best Practices

1. Use Descriptive Issue Summaries: Make summaries clear and specific - they'll be shown in dashboards and reports.

2. Leverage Template Variables: Use {{variable_name}} syntax to dynamically insert values from input data.

3. Set Default Parameters: Configure default parameters in the node that can be overridden by input data when needed.

4. Include Required Fields: Always include required fields like project, issue type, and summary for issue creation.

5. Consider Field Validation: Jira may have field validation rules - ensure data matches expected formats.

6. Use Search Wisely:

   • For user-friendly interfaces or simple queries, use Natural Language Search (Jira Cloud only)
   • For complex or precise queries, use JQL Search with the getAll operation
   • Review the generated JQL from Natural Language Search to learn JQL syntax

7. Batch Operations When Possible: When creating multiple issues or comments, consider batching them into a single API call.

8. Handle API Limits: Be aware of Jira API rate limits, especially on Jira Cloud.

9. Test With Small Datasets: When building workflows, test with small datasets before processing large amounts of data.

10. Secure Credentials: Keep your Jira API tokens and credentials secure. Use the system's built-in credential management rather than hardcoding values.