ELITEA Toolkit Guide: Jira Integration

Introduction

Purpose of this Guide

This guide is your definitive resource for integrating and effectively utilizing the Jira toolkit within ELITEA. It provides a detailed, step-by-step walkthrough, from setting up your Jira API token to configuring the toolkit in ELITEA and seamlessly incorporating it into your Agents. By following this guide, you will unlock the power of automated issue tracking, streamlined project management workflows, and enhanced team collaboration, all directly within the ELITEA platform. This integration empowers you to leverage AI-driven automation to optimize your Jira-driven workflows, enhance team productivity, and improve project visibility within your organization.

Brief Overview of Jira

Jira, by Atlassian, is a leading project management and issue tracking platform widely used by software development teams and various business teams for planning, tracking, and managing work. It serves as a central hub for teams to collaborate on projects, manage tasks, track bugs, and streamline workflows. Jira offers a wide array of functionalities, including:

Integrating Jira with ELITEA brings these powerful project management and issue tracking capabilities directly into your AI-driven workflows. Your ELITEA Agents can then intelligently interact with your Jira projects and issues to automate task management, enhance project tracking, improve team collaboration, and leverage AI to optimize your entire project management lifecycle within Jira.

Toolkit's Account Setup and Configuration in Jira

Account Setup

If you do not yet have a Jira account, please follow these steps to create one:

  1. Visit Atlassian Website: Open your web browser and navigate to the official Atlassian website: https://www.atlassian.com/software/jira.
  2. Sign Up for Jira: Click on the "Try Jira free" or "Get it free" button to start the sign-up process for Jira.
  3. Create an Atlassian Account: Follow the prompts to create an Atlassian account. You can sign up using your email address, Google account, or Apple account. For professional use, it's recommended to use your company email address.
  4. Choose a Workspace/Site Name: During the signup process, you will be asked to choose a workspace or site name for your Jira instance. Enter a suitable name for your workspace.
  5. Set Up Your Project: Follow the remaining onboarding steps to set up your first Jira project. You will be prompted to choose a project template (e.g., Scrum, Kanban) and provide a project name.
  6. Explore Jira Features: Once your Jira board is ready, explore the onboarding tips and familiarize yourself with Jira features, projects, boards, and navigation.

Token/API Key Generation: Creating an API Token in Jira

For secure integration with ELITEA, it is essential to use a Jira API token for authentication. This method is more secure than using your primary Jira account password directly and allows you to control access permissions.

Follow these steps to generate an API token in Jira:

  1. Log in to Jira: Access your Jira workspace by navigating to your Jira URL (e.g., your-workspace.atlassian.net) and logging in with your credentials.

  2. Access Account Settings: Click on your profile avatar in the top right corner of the Jira interface. From the dropdown menu, select "Manage account".

    Jira-Manage_Account

  3. Navigate to Security Settings: In the Atlassian account settings page, navigate to the "Security" section in the left-hand sidebar.

    Jira-Security_tab

  4. Access API Tokens: Within the "Security" settings, locate the "API tokens" section and click on "Create and manage API tokens".

    Jira-Access_API_Token

  5. Create API Token: On the "API tokens" page, click the "Create API token" button.

  6. Name Your Token: In the "Create API token" dialog, enter a descriptive Label for your token, such as "ELITEA Integration Token" or "ELITEA Agent Access." This label will help you identify the purpose of this token later.

  7. Create Token: Click the "Create" button to generate the API token.

    Jira-API_Token_Creation

  8. Securely Copy and Store Your API Token: Immediately copy the generated API token that is displayed in the pop-up window. This is the only time you will see the full token value. Store it securely in a password manager or, preferably, ELITEA's built-in Secrets feature for enhanced security within ELITEA. You will need this API token to configure the Jira toolkit in ELITEA.

Jira-Copy_API_Token

Jira-Created_API_Tokens

System Integration with ELITEA

Agent Creation/Configuration

To integrate Jira functionalities into your workflows, you will need to configure the Jira toolkit within an ELITEA Agent. You can either create a new Agent specifically for Jira interactions or modify an existing Agent to incorporate Jira tools.

  1. Navigate to Agents Menu: In ELITEA, go to the Agents menu from the main navigation panel.
  2. Create or Edit Agent:
    • Create a New Agent: Click on the "+ Agent" button to initiate the creation of a new Agent. Follow the on-screen prompts to define essential Agent attributes such as Agent name, a descriptive Agent description, the desired Agent type, and initial instructions for the Agent.
    • Edit an Existing Agent: Select the Agent you intend to integrate with Jira from your list of Agents. Click on the Agent's name to open its configuration settings for editing.
  3. Access Tools Section: Within the Agent configuration interface, scroll down until you locate the "Tools" section. This section is where you will add and configure toolkits, including the Jira toolkit.

Toolkit Configuration

This section provides detailed instructions on how to configure the Jira toolkit within your ELITEA Agent.

  1. Add Toolkit: In the "Tools" section of the Agent configuration, click on the "+" icon. This action will display a dropdown list of available toolkits that can be integrated with your Agent.
  2. Select Jira Toolkit: From the dropdown list of available toolkits, choose "Jira". Selecting "Jira" will open the "New Jira tool" configuration panel, where you will specify the settings for your Jira integration.

  3. Configure Jira Toolkit Settings: Carefully fill in the following configuration fields within the "New Jira tool" section:

    • Name: Enter a descriptive Name for your Jira toolkit instance. Choose a name that is easily recognizable and helps you identify its purpose within your Agent's instructions (e.g., "ProjectJira", "IssueTrackerAccess", "JiraIntegration").
    • Description: Provide a concise Description for the toolkit. This description should clarify the toolkit's purpose or the specific Jira project it is intended to access (e.g., "Toolkit for accessing and managing issues in Jira", "Integration for Jira Project 'Project Alpha'").
    • URL: Enter the base URL of your Jira instance. Ensure you use the correct format, including https:// or http:// and the full workspace URL (e.g., https://your-workspace.atlassian.net/jira or https://your-company.atlassian.net). For Epam Jira, use https://jira.epam.com/jira/.
    • Username: Enter the Username associated with your Jira account for which you generated the API token. This is typically your email address used for Jira login.
    • Authentication Options - API Key: Select the "API Key" authentication option.
      • Password/Secret: Choose "Password" and paste the API token you generated in Jira (during the "Software-Specific Setup" section of this guide) into the "Password" field.
      • Enhanced Security with Secrets (Recommended): For enhanced security, it is strongly recommended to use ELITEA's Secrets Management feature to store your Jira API token securely. Instead of directly pasting the token into the "Password" field, select the "Secret" option and choose the pre-configured secret containing your Jira API token from the dropdown list. This prevents hardcoding sensitive credentials in your toolkit configuration.
    • Hosting Option: Select the appropriate "Hosting option" for your Jira instance:
      • Cloud: Select "Cloud" if you are using Jira Cloud (e.g., accessed via atlassian.net).
      • Server: Select "Server" if you are using a self-hosted Jira Server or Data Center instance. Note: When connecting to an Epam Jira instance, ensure you select "Server" as the Hosting option.
    • Advanced Settings: Adjust the advanced settings to fine-tune the toolkit's operation:
      • Additional Fields: Enumeration of custom fields which can be used (e.g. customfield_100450). Enter a comma-separated list of custom field IDs that you want to be accessible within the toolkit. This allows you to interact with custom fields specific to your Jira projects.
      • Verify SSL: Check this box to enable SSL verification for secure connections to your Jira instance. It is generally recommended to keep SSL verification enabled for enhanced security.

    Jira-Toolkit_Configuration

  4. Enable Desired Tools: In the "Tools" section within the Jira toolkit configuration panel, select the checkboxes next to the specific Jira tools that you want to enable for your Agent. It is crucial to enable only the tools that your Agent will actually need to use to adhere to the principle of least privilege and minimize potential security risks. Available tools include:

    • Search using JQL - Allows searching for Jira issues using Jira Query Language (JQL).
    • Create issue - Enables the Agent to create new Jira issues.
    • Update issue - Allows the Agent to update existing Jira issues.
    • List comments - Enables the Agent to list comments for a specific Jira issue.
    • Add comments - Allows the Agent to add new comments to a Jira issue.
    • Get attachments content - Enables the Agent to retrieve the content of attachments from a Jira issue.
    • List projects - Allows the Agent to list all projects in the Jira instance.
    • Set issue status - Allows the Agent to change the status of a Jira issue.
    • Get specific field info - Enables the Agent to retrieve information from a specific field of a Jira issue.
    • Get remote links - Allows the Agent to retrieve remote links associated with a Jira issue.
    • Link issues - Enables the Agent to create links between Jira issues.
    • Modify labels - Allows the Agent to add or remove labels from a Jira issue.
    • Generic request - Allows to send custom HTTP requests to Jira API.

  5. Complete Setup: After configuring all the necessary settings and enabling the desired tools, click the arrow icon (typically located at the top right of the toolkit configuration section) to finalize the Jira toolkit setup and return to the main Agent configuration menu.

  6. Click Save in the Agent configuration to save all changes and activate the Jira toolkit integration for your Agent.

Tool Overview: Jira Toolkit Functionalities

Once the Jira toolkit is successfully configured and added to your Agent, you can leverage the following tools within your Agent's instructions to enable intelligent interaction with your Jira projects and issues:

Instructions and Prompts for Using the Jira Toolkit

To effectively utilize the Jira toolkit within your ELITEA Agents, you need to provide clear and precise instructions within the Agent's "Instructions" field, telling the Agent how and when to use these tools.

General Instruction Structure:

When instructing your Agent to use a Jira tool, you will typically follow this pattern:

Use the "[tool_name]" tool to [describe the action you want to perform] in Jira.
Provide the following parameters:
- Parameter 1: <value or description of value>
- Parameter 2: <value or description of value>
- ...

Example Agent Instructions for Jira Toolkit Tools:

Important Considerations for Agent Instructions:

Best Practices and Use Cases for Jira Integration

Best Practices for Efficient Integration

Use Cases for Jira Toolkit Integration

The Jira toolkit opens up a wide range of automation possibilities for project management, issue tracking, and workflow automation within ELITEA. Here are some compelling use cases:

Troubleshooting and Support

Troubleshooting Common Issues

FAQs

  1. Q: Can I use my regular Jira password for the ELITEA integration?
    • A: No, it is strongly recommended to use a Jira API token instead of your main account password for security reasons. API tokens provide a more secure and controlled way to grant access to external applications like ELITEA.
  2. Q: What permissions should I grant to the Jira API Token?
    • A: Jira API tokens have a fixed scope (access to Jira REST API). You don't need to select specific scopes when generating the token. However, ensure that the Jira account associated with the API token has the necessary permissions within Jira to access and modify the projects and issues your Agent will be interacting with.
  3. Q: What is the correct format for the Jira URL in the toolkit configuration?
    • A: The Jira URL should be entered in the full format, including https:// or http:// and the complete workspace URL (e.g., https://your-workspace.atlassian.net/jira or https://your-company.atlassian.net). Ensure there are no typos or missing parts in the URL. For Epam Jira, use https://jira.epam.com/jira/.
  4. Q: Why is my Agent getting "Permission Denied" errors even though I think I have configured everything correctly?
    • A: Double-check the following:
      • API Token Validity: Ensure that the API token is valid and has not been revoked.
      • Jira Account Permissions: Verify that the Jira account associated with the API token has the necessary permissions to access the specific projects and issues your Agent is trying to interact with.
      • Hosting Option: Double-check that you have selected the correct "Hosting option" (Cloud or Server) in the Jira toolkit configuration, especially for self-hosted or Epam Jira instances.
      • Verify SSL Setting: If you are connecting to a Jira Server instance, try toggling the "Verify SSL" setting in the "Advanced Settings" of the toolkit configuration, as SSL verification issues can sometimes cause connection problems.

Support and Contact Information

If you encounter any issues, have questions, or require further assistance beyond what is covered in this guide regarding the Jira integration or ELITEA Agents in general, please do not hesitate to contact our dedicated ELITEA Support Team. We are here to help you resolve any problems quickly and efficiently and ensure you have a smooth and productive experience with ELITEA.

How to Reach ELITEA Support:

Best Practices for Effective Support Requests:

To help us understand and resolve your issue as quickly as possible, please ensure you provide the following information in your support email:

Before Contacting Support:

We encourage you to first explore the resources available within this guide and the broader ELITEA documentation. You may find answers to common questions or solutions to known issues in the documentation.

To further enhance your understanding and skills in integrating Jira with ELITEA, here are some helpful resources: