Skip to main content

Jira Integration

TeamAI avatar
Written by TeamAI
Updated this week

Overview

This guide provides step-by-step instructions for creating and configuring a Jira API integration within your workspace. The integration allows you to query Jira projects, issues, and tasks directly from your workspace.

Learning Objectives:

  • Create a new API tool for Jira integration

  • Configure the basic API connection settings

  • Set up dynamic variables for flexible querying

  • Understand Jira API URL structures for common queries

Prerequisites

You'll Need:

  • Access to a workspace with tool creation permissions

  • Jira Cloud instance URL and authentication credentials

  • Basic understanding of Jira project structure and terminology

Creating the Jira API Tool

Accessing the Tools Section

  1. Navigate to Tools in the left navigation panel

    • Click on the Tools icon in the left menu

    • Ensure you are in the main Tools section

  2. Initiate tool creation

    • Look for and click on the "Create a new tool" button or plus (+) icon

    • A configuration window will appear

  3. Enter basic tool information

    • In the Name field, enter "Jira API"

    • Select the appropriate Group (folder) where you want to store the tool

    • Set Visibility to either "Workspace," "Personal," or "Organization" based on your sharing needs

    • From the Tool Type dropdown, select "API Tool"

    • Click the "Create" button

Result: The tool will be created and you'll be taken to the configuration screen.

Configuring the API Connection

Setting Tool Details

  1. Customize tool appearance

    • Select an avatar icon or upload a custom image for the tool

    • Adjust the folder (group) if needed from the dropdown menu

  2. Access API configuration

    • Click on "API setup" in the left menu below the Details section

  3. Configure API endpoint

    • In the API URL field, enter your Jira instance URL with the appropriate endpoint:

    • https://your-jira-URL/rest/api/3/search/jql?

    • Set the Request Method to "GET" from the dropdown menu

Tip: Ensure you have the correct Jira URL. For Jira Cloud, it typically follows the format: https://your-organization.atlassian.net

Setting Up Dynamic Variables

  1. Define query variables

    • In the Variables section, define parameters that the AI should extract from user messages

    • Create variables for common Jira query parameters such as:

      • {{projectKey}} - The Jira project key (e.g., "PROJ")

      • {{issueType}} - Type of issue to query (e.g., "Task")

      • {{status}} - Issue status (e.g., "In Progress")

  2. Create dynamic URL structure

    • Modify your API URL to incorporate variables:

Result: Your API tool will now be able to dynamically insert values extracted from user conversations.

Testing Your Jira API Tool

Accessing the Test Environment

  1. Navigate to the Test & Launch section

    • From your tool configuration page, click on "Test & Launch" in the left navigation menu

    • This will open the testing interface where you can verify your API configuration

  2. Prepare for testing

    • Review the configured API URL to ensure it's correctly structured

    • Identify which variables will need sample values for testing

Providing Test Values

  1. Enter sample values for your variables

    • For each variable you defined (e.g., {{projectKey}}, {{issueType}}, {{status}}), enter valid test values

    • Use real values from your Jira instance:

      • Project Key: Enter an existing project key (e.g., "PROJ")

      • Issue Type: Enter a valid issue type (e.g., "Task")

      • Status: Enter a valid status (e.g., "In Progress")

  2. Review the complete request

    • The system will show you how your API URL looks with the test values inserted

    • Verify that the URL structure is correct and all parameters are properly formatted

Tip: Use values that you know will return a small but non-empty result set to make verification easier.

Running the Test

  1. Initiate the test

    • Click the "Run Test" button to execute a real API call with your configuration

    • The system will make the request using your provided values

  2. Evaluate the response

    • Review the API response to ensure:

      • The request was successful (check for HTTP 200 status)

      • The response contains the expected data format

      • Jira issues are correctly retrieved based on your query parameters

Result: If the test is successful, you'll see Jira data in the response panel. If not, you'll receive error details to help troubleshoot.

Important: If the test fails, check your authentication settings, URL structure, and the validity of your test values before proceeding.

Finalizing and Launching the Tool

Reviewing Test Results

  1. Verify functionality matches expectations

    • Confirm the API returns the expected data types and fields

    • Check that all variables are correctly interpolated in the request

    • Ensure pagination parameters work if you included them

  2. Make adjustments if needed

    • If issues are found, return to the API Setup section to make corrections

    • Common fixes include:

      • Adjusting URL encoding

      • Modifying field selections

      • Updating authentication details

Launching the Tool

  1. Complete the launch process

    • After successful testing, look for the "Launch" or "Publish" button

    • Review any final confirmation dialogs

    • Confirm the launch to make the tool available

  2. Verify availability

    • Check that the tool appears in your tools library

    • Confirm the visibility settings match your expectations (Personal, Workspace, or Organization)

Result: Your Jira API tool is now available for use within your workspace.

Configuring Common Query Types

Project-Based Queries

  1. Basic project query

    • URL structure:

      https://your-jira-URL/rest/api/3/search/jql?jql=project={{projectKey}}

    • This retrieves all issues within a specific project

  2. Task-specific project query

    • URL structure:

      https://your-jira-URL/rest/api/3/search/jql?jql=project={{projectKey}}&issuetype=task

    • This filters results to only include tasks within the project

Status-Filtered Queries

  1. Filter by project, type, and status

    • URL structure:

      text

      Copy

      https://your-jira-URL/rest/api/3/search/jql?jql=project={{projectKey}}&issuetype={{issueType}}&status={{status}}&fields=summary&maxResults=100

    • This retrieves tasks with a specific status and includes their summaries

Note: The fields=summary parameter ensures you receive useful information about each task, and maxResults=100 increases the default limit of 50 results.

Best Practices

  1. Use specific variable names: Choose descriptive variable names that clearly indicate what values they represent.

  2. Include field parameters: Always include the fields parameter to ensure you receive useful information in responses.

  3. Consider pagination: For large projects, use maxResults and implement pagination handling.

  4. Properly encode URL parameters: Ensure special characters in JQL queries are properly URL-encoded.

Common Questions

Q: Can I query multiple projects at once?
A: Yes, by using JQL's OR operator in your query: jql=project={{project1}} OR project={{project2}}.

Q: How do I handle authentication?
A: Configure API authentication in the Authentication section of the API setup. Jira Cloud typically requires Basic Authentication or API tokens.

Q: Why am I getting "no results" when I know issues exist?
A: Check that your JQL syntax is correct and that you have permission to view the queried issues.

Q: Can I sort the results?
A: Yes, add ORDER BY to your JQL query: jql=project={{projectKey}} ORDER BY created DESC.

Q: How do I filter by custom fields?
A: Use the custom field ID in your JQL: jql=project={{projectKey}} AND cf_10010="Value".

Related Articles
How to Use Tools(formerly called "plugins")?
Creating a GET Route Custom Plugin in TeamAI
Creating a POST Route Custom Plugin in TeamAI
Creating Custom Plugins in TeamAI
Personalizing Agent Instructions with System Variables
Did this answer your question?