# Jira tools (https://www.shipfox.io/docs/integrations/jira/tools)

Description: Look up the Jira tools, selectors, permissions, inputs, and outputs available to tool steps and agent steps.

This reference lists the shipped Jira tool catalog. See the [Jira
overview](https://www.shipfox.io/docs/integrations/jira) for authentication and setup.

## Selectors [#selectors]

A tool step names one standalone tool id in its `tool` field. An agent step
lists standalone selectors in its `integrations:` block. For the field
contracts, see [Tool step fields](https://www.shipfox.io/docs/reference/workflow-schema#tool-step-fields)
and [Agent integration fields](https://www.shipfox.io/docs/reference/workflow-schema#agent-integration-fields).

## Tool catalog [#tool-catalog]

Jira read tools require the `read:jira-work` OAuth scope. Jira write tools
require `write:jira-work`.

### tools

#### `get_issue`

Retrieve a Jira issue by its ID or key.

**Sensitivity:** read.

**Sensitive:** No.

**Required permissions:** `read`

**Selector tokens:** [`get_issue`](https://www.shipfox.io/docs/integrations/jira/tools#get_issue)

##### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `idOrKey` | string | Required | Jira issue ID or key, such as ENG-123 |
| `fields` | array | Optional |  |
| `fieldsByKeys` | boolean | Optional | Interpret fields by their keys instead of IDs |
| `expand` | string | Optional | Comma-separated Jira issue expansions |
| `properties` | array | Optional |  |
| `updateHistory` | boolean | Optional | Record this issue as viewed by the authorizing user |

#### `search_issues`

Search Jira issues with a JQL query.

**Sensitivity:** read.

**Sensitive:** No.

**Required permissions:** `read`

**Selector tokens:** [`search_issues`](https://www.shipfox.io/docs/integrations/jira/tools#search_issues)

##### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `jql` | string | Required | Jira Query Language expression |
| `maxResults` | integer | Optional | Maximum number of issues to return |
| `nextPageToken` | string | Optional | Pagination token from a previous search |
| `fields` | array | Optional |  |
| `fieldsByKeys` | boolean | Optional | Interpret fields by their keys instead of IDs |
| `expand` | string | Optional | Comma-separated Jira issue expansions |
| `properties` | array | Optional |  |
| `reconcileIssues` | array | Optional |  |

#### `get_issue_comments`

List the comments on a Jira issue.

**Sensitivity:** read.

**Sensitive:** No.

**Required permissions:** `read`

**Selector tokens:** [`get_issue_comments`](https://www.shipfox.io/docs/integrations/jira/tools#get_issue_comments)

##### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `idOrKey` | string | Required | Jira issue ID or key, such as ENG-123 |
| `startAt` | integer | Optional | Zero-based comment offset |
| `maxResults` | integer | Optional | Maximum number of comments to return |
| `orderBy` | string | Optional | Comment ordering expression |
| `expand` | string | Optional | Comma-separated Jira comment expansions |

#### `get_issue_transitions`

List the workflow transitions available for a Jira issue.

**Sensitivity:** read.

**Sensitive:** No.

**Required permissions:** `read`

**Selector tokens:** [`get_issue_transitions`](https://www.shipfox.io/docs/integrations/jira/tools#get_issue_transitions)

##### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `idOrKey` | string | Required | Jira issue ID or key, such as ENG-123 |
| `expand` | string | Optional | Comma-separated transition expansions, such as transitions.fields |

#### `get_project`

Retrieve a Jira project by its ID or key.

**Sensitivity:** read.

**Sensitive:** No.

**Required permissions:** `read`

**Selector tokens:** [`get_project`](https://www.shipfox.io/docs/integrations/jira/tools#get_project)

##### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `idOrKey` | string | Required | Jira project ID or key, such as ENG |
| `expand` | string | Optional | Comma-separated Jira project expansions |
| `properties` | array | Optional |  |

#### `get_user`

Retrieve a Jira user by Atlassian account ID.

**Sensitivity:** read.

**Sensitive:** No.

**Required permissions:** `read`

**Selector tokens:** [`get_user`](https://www.shipfox.io/docs/integrations/jira/tools#get_user)

##### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `accountId` | string | Required | Atlassian account ID |
| `expand` | string | Optional | Comma-separated Jira user expansions |

#### `create_issue`

Create a Jira issue using Jira REST issue fields. If both a project key and project ID or both an issue type name and issue type ID are supplied, the ID takes precedence.

**Sensitivity:** write.

**Sensitive:** No.

**Required permissions:** `write`

**Selector tokens:** [`create_issue`](https://www.shipfox.io/docs/integrations/jira/tools#create_issue)

##### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `projectKey` | string | Optional | Jira project key; projectId takes precedence if both are supplied |
| `projectId` | string | Optional | Jira project ID; takes precedence over projectKey |
| `summary` | string | Required | Issue summary |
| `issueType` | string | Optional | Issue type name; issueTypeId takes precedence if both are supplied |
| `issueTypeId` | string | Optional | Issue type ID; takes precedence over issueType |
| `assigneeAccountId` | string | Optional | Atlassian account ID to assign |
| `priority` | string | Optional | Jira priority name |
| `labels` | array | Optional |  |
| `body` | string | Optional | Plain-text issue description |
| `fields` | object | Optional | Jira issue fields keyed by their REST API field name |
| `update` | object | Optional | Jira issue field update operations |

#### `update_issue`

Update a Jira issue using Jira REST issue fields.

**Sensitivity:** write.

**Sensitive:** No.

**Required permissions:** `write`

**Selector tokens:** [`update_issue`](https://www.shipfox.io/docs/integrations/jira/tools#update_issue)

##### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `idOrKey` | string | Required | Jira issue ID or key, such as ENG-123 |
| `summary` | string | Optional | Replacement issue summary |
| `issueType` | string | Optional | Replacement issue type name; issueTypeId takes precedence if both are supplied |
| `issueTypeId` | string | Optional | Replacement issue type ID; takes precedence over issueType |
| `assigneeAccountId` | string | Optional | Atlassian account ID to assign |
| `priority` | string | Optional | Replacement Jira priority name |
| `labels` | array | Optional |  |
| `body` | string | Optional | Plain-text replacement issue description |
| `fields` | object | Optional | Jira issue fields keyed by their REST API field name |
| `update` | object | Optional | Jira issue field update operations |

#### `add_comment`

Add a plain-text comment to a Jira issue.

**Sensitivity:** write.

**Sensitive:** No.

**Required permissions:** `write`

**Selector tokens:** [`add_comment`](https://www.shipfox.io/docs/integrations/jira/tools#add_comment)

##### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `idOrKey` | string | Required | Jira issue ID or key, such as ENG-123 |
| `body` | string | Required | Plain-text comment body |

#### `transition_issue`

Move a Jira issue through a workflow transition.

**Sensitivity:** write.

**Sensitive:** No.

**Required permissions:** `write`

**Selector tokens:** [`transition_issue`](https://www.shipfox.io/docs/integrations/jira/tools#transition_issue)

##### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `idOrKey` | string | Required | Jira issue ID or key, such as ENG-123 |
| `transitionId` | string | Required | Jira workflow transition ID |
| `fields` | object | Optional | Jira issue fields keyed by their REST API field name |
| `update` | object | Optional | Jira issue field update operations |

#### `assign_issue`

Assign or unassign a Jira issue by Atlassian account ID.

**Sensitivity:** write.

**Sensitive:** No.

**Required permissions:** `write`

**Selector tokens:** [`assign_issue`](https://www.shipfox.io/docs/integrations/jira/tools#assign_issue)

##### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `idOrKey` | string | Required | Jira issue ID or key, such as ENG-123 |
| `accountId` | string \| null | Required | Atlassian account ID, or null to unassign |