> For the complete documentation index, see [llms.txt](https://docs.kognitos.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kognitos.com/legacy/legacy-experience/books/reference/jira.md).

# Jira

Procedures and concepts for the Jira integration.

{% hint style="info" %}
The following documentation is for **Jira v1.3.1** *(BDK)*.
{% endhint %}

## Overview

This integration provides automation capabilities for Jira, enabling streamlined workflows and enhanced productivity. Connect your processes with Jira to automate routine tasks and improve operational efficiency.

## Prerequisites

### 1. Required Books

The following Book(s) need to be added to your agent so it can learn and understand the automation procedures defined within them:

* **Jira**

#### How to Add the Book(s)

1. Go to **Books** → **All Books**.
2. Search for the name of the book and click on it.
3. Click on <kbd>**Install**</kbd> or <kbd>**Add Connection**</kbd> to add the book to your agent.
4. If adding a connection, you'll be prompted for [**connectivity**](#connectivity) details.

## Connectivity

This section outlines the available methods for connecting to the Book, along with the required configuration details for each.

### Connect using Email, Domain and API Token

Connects to Jira using email and API token.

| Label     | Description                                                                                                                                                                                      | Type        |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |
| Email     | Your Atlassian account email — the one you use to log in. Example: "<john@company.com>"                                                                                                          | `text`      |
| Domain    | Your Jira Cloud site domain. This is the host part of the URL you see in the browser when using Jira. Example: "mycompany.atlassian.net" (from <https://mycompany.atlassian.net/jira/>...)       | `text`      |
| API Token | An API token generated from your Atlassian account settings. Go to: <https://id.atlassian.com/manage-profile/security/api-tokens> Click "Create API token", give it a label, and copy the value. | `sensitive` |

## Procedures

### to assign an (issue) in *jira*

Assigns a Jira issue to a user

Looks up the user by email and assigns the issue to them.

**Input Concepts**

| Concept                | Description                               | Type         | Required | Default Value |
| ---------------------- | ----------------------------------------- | ------------ | -------- | ------------- |
| [`issue`](#jira-issue) | The issue to assign (must have a key)     | `jira issue` | Yes      | (no default)  |
| `assignee`             | The email address of the person to assign | `text`       | Yes      | (no default)  |

**Output Concepts**

| Concept                | Description       | Type         |
| ---------------------- | ----------------- | ------------ |
| [`issue`](#jira-issue) | the updated issue | `jira issue` |

**Examples**

Assign an issue to a user

```generic
search some issues from jira whose key is "MYPROJ-1"
assign the issue in jira whose assignee is "john@company.com"
```

Create and assign an issue

```generic
create an issue in jira whose project is "MYPROJ" and whose summary is "New task"
assign the issue in jira whose assignee is "jane@company.com"
```

### to create an (issue) in *jira*

Creates a new issue in a Jira project

**Input Concepts**

| Concept       | Description                                           | Type   | Required | Default Value |
| ------------- | ----------------------------------------------------- | ------ | -------- | ------------- |
| `project`     | The project key where the issue will be created       | `text` | Yes      | (no default)  |
| `summary`     | The title/summary of the issue                        | `text` | Yes      | (no default)  |
| `issue type`  | The type of issue to create (defaults to "Task")      | `text` | No       | Task          |
| `description` | Optional plain-text body/description of the issue     | `text` | No       | (no default)  |
| `labels`      | Optional list of string labels to attach to the issue | `text` | No       | (no default)  |

**Output Concepts**

| Concept                | Description       | Type         |
| ---------------------- | ----------------- | ------------ |
| [`issue`](#jira-issue) | the created issue | `jira issue` |

**Examples**

Create a task in a project

```generic
create an issue in jira
... whose project is "MYPROJ"
... whose summary is "Fix login bug"
```

Create a bug with a description

```generic
create an issue in jira
... whose project is "MYPROJ"
... whose summary is "Button not clickable"
... whose issue type is "Bug"
... whose description is "The submit button on the checkout page is unresponsive on mobile"
```

Create a story with labels

```generic
create an issue in jira
... whose project is "MYPROJ"
... whose summary is "User can reset password"
... whose issue type is "Story"
... whose labels are ["auth", "frontend"]
```

### to create some (issues) in *jira*

Creates multiple issues in a Jira project in a single operation

Each issue in the list needs at least a summary. The issue type defaults to "Task" if not specified.

**Input Concepts**

| Concept                 | Description                                         | Type         | Required | Default Value |
| ----------------------- | --------------------------------------------------- | ------------ | -------- | ------------- |
| `project`               | The project key where issues will be created        | `text`       | Yes      | (no default)  |
| [`issues`](#jira-issue) | A list of issues to create (summary and issue type) | `jira issue` | Yes      | (no default)  |

**Output Concepts**

| Concept                 | Description                | Type         |
| ----------------------- | -------------------------- | ------------ |
| [`issues`](#jira-issue) | the list of created issues | `jira issue` |

**Examples**

Create multiple tasks

```generic
bulk create some issues in jira
... whose project is "MYPROJ"
... whose issues are the new issues
```

Create tasks with different types

```generic
bulk create some issues in jira
... whose project is "MYPROJ"
... whose issues are the new issues
```

### to delete an (issue) in *jira*

Deletes an issue from Jira

Permanently removes the issue. This action cannot be undone.

**Input Concepts**

| Concept                | Description                           | Type         | Required | Default Value |
| ---------------------- | ------------------------------------- | ------------ | -------- | ------------- |
| [`issue`](#jira-issue) | The issue to delete (must have a key) | `jira issue` | Yes      | (no default)  |

**Output Concepts**

| Concept           | Description                           | Type    |
| ----------------- | ------------------------------------- | ------- |
| [`issue`](#thing) | None. Raises an exception on failure. | `thing` |

**Examples**

Delete a specific issue

```generic
search some issues from jira whose key is "MYPROJ-1"
delete the issue in jira
```

Create and then delete an issue

```generic
create an issue in jira whose project is "MYPROJ" and whose summary is "Temp task"
delete the issue in jira
```

### to edit an (issue) in *jira*

Edits an existing issue in Jira

Compares the provided issue against its current state in Jira and updates only the fields that have changed. Supports updating summary, status, issue type, priority, assignee, description, and labels.

**Input Concepts**

| Concept                | Description                   | Type         | Required | Default Value |
| ---------------------- | ----------------------------- | ------------ | -------- | ------------- |
| [`issue`](#jira-issue) | The issue with updated fields | `jira issue` | Yes      | (no default)  |

**Output Concepts**

| Concept                | Description       | Type         |
| ---------------------- | ----------------- | ------------ |
| [`issue`](#jira-issue) | the updated issue | `jira issue` |

**Examples**

Update the summary of an issue

```generic
search some issues from jira whose key is "MYPROJ-1"
set the summary of the issue to "Updated title"
edit the issue in jira
```

Change priority

```generic
search some issues from jira whose key is "MYPROJ-1"
set the priority of the issue to "High"
edit the issue in jira
```

Add a description

```generic
search some issues from jira whose key is "MYPROJ-1"
set the description of the issue to "This needs to be fixed before release"
edit the issue in jira
```

Update labels

```generic
search some issues from jira whose key is "MYPROJ-1"
set the labels of the issue to ["bug", "urgent"]
edit the issue in jira
```

### to get the (labels) from *jira*

Fetches all available label names in the Jira instance

Use this before creating or editing issues with labels to discover the exact label names (case-sensitive) available in your Jira workspace.

**Output Concepts**

| Concept  | Description                                      | Type   |
| -------- | ------------------------------------------------ | ------ |
| `labels` | alphabetically sorted list of label name strings | `text` |

**Examples**

List all available labels

```generic
get the labels from jira
```

Discover labels before creating an issue

```generic
get the labels from jira
create an issue in jira
... whose project is "MYPROJ"
... whose summary is "Fix login bug"
... whose labels are ["frontend", "bug"]
```

### to search some (issues) from *jira*

![FILTER - CAPABLE](https://img.shields.io/static/v1?label=FILTER\&message=CAPABLE\&color=blue)

Searches for issues in Jira

If no filter is provided, returns all issues. Supported filter fields include any Jira field: project, status, assignee, priority, issue type, summary, created, updated, labels, reporter, resolution, and more. Supported filter operators: is (equals), is not (not equals), is in (membership), is less than, is greater than, is at most, is at least, and, or, is not (negation)

**Output Concepts**

| Concept                 | Description                 | Type         |
| ----------------------- | --------------------------- | ------------ |
| [`issues`](#jira-issue) | the list of matching issues | `jira issue` |

**Examples**

Retrieve all issues

```generic
search some issues from jira
```

Search for issues in a project

```generic
search some issues from jira whose project is "MYPROJ"
```

Search for open issues

```generic
search some issues from jira whose status is "Open"
```

Search for high priority bugs

```generic
search some issues from jira whose issue type is "Bug" and whose priority is "High"
```

Get the first 10 issues

```generic
search some issues from jira whose limit is 10
```

## Concepts

### Jira issue

An Issue in Jira

| Field Name    | Description                                    | Type                     |
| ------------- | ---------------------------------------------- | ------------------------ |
| `id`          | The unique identifier of the issue             | `text`                   |
| `key`         | The issue key (e.g., PROJ-123)                 | `text`                   |
| `summary`     | The summary/title of the issue                 | `text`                   |
| `status`      | The current status of the issue                | `text`                   |
| `issue_type`  | The type of the issue (e.g., Bug, Story, Task) | `text`                   |
| `priority`    | The priority level of the issue                | `text`                   |
| `assignee`    | The display name of the assignee               | `text`                   |
| `created`     | The creation date of the issue                 | `text`                   |
| `updated`     | The last updated date of the issue             | `text`                   |
| `description` | The description/body of the issue (plain text) | `optional[text]`         |
| `labels`      | List of string labels attached to the issue    | `optional[list of text]` |

### Thing

No description


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.kognitos.com/legacy/legacy-experience/books/reference/jira.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.