> ## Documentation Index
> Fetch the complete documentation index at: https://docs.genesiscomputing.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Jira Connector Tools
> Connect to Jira, create and update issues, run JQL searches, and sync workflows between Genesis and Jira.
## **Overview**
This page documents the **manual tool surface** that an agent (or a flow) can call to act on Jira on demand. It is **not** the same as automatic ticket pickup — for that, configure [Jira Automation (Auto-Pickup)](/docs/Setup/Jira-Automation), which uses these same credentials but adds webhook/polling intake and trigger rules so Genesis starts work on a ticket without being asked.
Before using this tool group, make sure a Jira connection has been saved as described in [Setup Jira API Parameters](/docs/Setup/Setup-Jira-API-Params).
### **Tool Name**
```json theme={null}
jira_connector_tools
```
### **Purpose**
The **jira\_connector\_tools** group integrates Genesis workflows with Jira. Authenticate to a Jira instance, create or update issues, search with JQL, transition statuses, pull project metadata to keep work in sync, and, when Jira automation is enabled, configure shared worker and polling automation.
#### **Functions Available**
1. **`jira_connector`**: *`Standard Jira issue, comment, attachment, and search operations.`*
2. **`jira_automation_setup_action`**: *`Read or update shared Jira automation and service-worker settings, validate or provision the Jira worker, and sync the scheduled Jira poller Flow.`*
3. **`jira_automation_action`**: *`Run Jira automation actions such as a manual POLL_ONCE pass against the saved configuration.`*
### **Key Features & Functions**
Establish a secure session with your Jira Cloud or Server instance.
Open new tasks, bugs, or stories and modify fields, assignees, and priorities.
Run targeted queries to find and report on issues across projects.
Move issues through statuses with `TRANSITION_ISSUE` using a transition id or a target status name.
Fetch projects, issue types, and workflow options to drive automation.
## **Input Parameters for Each Function**
### **`jira_connector`**
**Parameters**
| **Name** | **Definition** | **Format** |
| - | - | :-: |
| **action** | Operation to perform. Supported: `CREATE_ISSUE`, `CREATE_CHILD_ISSUE`, `UPDATE_ISSUE`, `ADD_COMMENT`, `GET_ISSUE`, `GET_ATTACHMENTS`, `SEARCH_ISSUES`, `CREATE_LINK`, `ADD_ATTACHMENT`, `TRANSITION_ISSUE`, `LIST_PROJECTS`. | String (required) |
| **jira\_url** | Base URL of the Jira instance. Example: `https://yourcompany.atlassian.net`. | String |
| **username** | Jira username or email for authentication. | String |
| **api\_token** | API token or password for authentication. | String |
| **project\_key** | Project key for issue actions. | String |
| **issue\_key** | Issue key for `UPDATE_ISSUE`, `ADD_COMMENT`, `GET_ISSUE`, `GET_ATTACHMENTS`, `CREATE_LINK`, `ADD_ATTACHMENT`, or `TRANSITION_ISSUE`. For `CREATE_CHILD_ISSUE`, use as the parent key (or pass `parent_key`). | String |
| **issue\_type** | Type for new issues. Common: `Bug`, `Task`, `Story`, `Epic`, `Subtask`. | String |
| **summary** | Title for the issue. | String |
| **description** | Issue description for `CREATE_ISSUE`, `CREATE_CHILD_ISSUE`, and `UPDATE_ISSUE` (updates the issue description field, not a comment). Comment body for `ADD_COMMENT` when `comment` is omitted. Optional text for `SEARCH_ISSUES`. | String |
| **comment** | Comment text for `ADD_COMMENT` only (alias for `description`). Not used by `UPDATE_ISSUE` — pass the new issue description in `description` instead. | String |
| **comment\_visibility** | Optional `ADD_COMMENT` visibility: `public` shares with the customer; `internal` creates an agent-only JSM note. Omit it to preserve Jira's existing/default behavior. | String |
| **assignee** | Username or account id to assign. | String |
| **priority** | Priority value. Common: `Highest`, `High`, `Medium`, `Low`, `Lowest`. | String |
| **labels** | Labels to apply. | Array of strings |
| **include** | Optional list for `GET_ISSUE`: `comments`, `worklog`, `remotelink`, `development`, `issue_links`, `changelog` (comma-separated string also accepted). Use `include=['comments']` when authoritative public/internal comment visibility is needed; the default recent preview may report visibility as `unknown`. | Array of strings |
| **custom\_fields** | Map of custom field ids to values. | Object |
| **status** | Target workflow status name for `TRANSITION_ISSUE` when `transition_id` is omitted. Genesis matches the name against available transition labels and destination statuses. Also used by `CREATE_ISSUE`, `UPDATE_ISSUE`, and `SEARCH_ISSUES`. | String |
| **transition\_id** | Optional explicit workflow transition id for `TRANSITION_ISSUE`. If omitted, pass the target status name via `status` and Genesis resolves it automatically. | String |
| **target\_issue\_key** | The other issue key for `CREATE_LINK`; becomes the inward issue (e.g. the Story that `issue_key` tests or blocks). | String |
| **link\_type** | Issue link type name for `CREATE_LINK`, exactly as configured in Jira (e.g. `Blocks`, `Relates`, `Duplicate`, or `tests` when X-ray is installed). | String |
| **attachment\_uri** | Required for `ADD_ATTACHMENT`. Scoped URI for a stored file: `genesis-file://`, `attachment:/`, `sandbox:/mnt/data/`, or `query-result://`. Arbitrary local paths and http(s) URLs are not accepted. | String |
| **filename** | Optional filename override for `ADD_ATTACHMENT`; defaults to the resolved file's name. | String (optional) |
| **jql\_query** | JQL for search operations. | String |
| **max\_results** | Maximum number of results to return. | Integer |
| **connection\_id** | Optional explicit Genesis Jira connection id (for example `jira.team-service` or `team-service`). When omitted, Genesis resolves the requester-aware effective Jira default (My default, then Role default). | String |
**`LIST_PROJECTS`:** Lists the projects visible to the selected connection. The response's `result.projects` contains each project's `key`, `name`, and `id`; `result.truncated` is true when the listing stops at the 10,000-project cap. This reads the full listing: Jira Cloud makes one request per 50 projects (up to 200 requests), while Server/Data Center makes one request.
```python theme={null}
jira_connector(action="LIST_PROJECTS", connection_id="jira.acme")
```
**`UPDATE_ISSUE` description vs `ADD_COMMENT`:** With `action="UPDATE_ISSUE"`, the `description` parameter updates the Jira issue's **description** field (via the fields API). It is not posted as a comment. To add a comment on an existing issue, use `action="ADD_COMMENT"` with `issue_key` and `comment` or `description`. For `UPDATE_ISSUE`, `comment` is ignored so a stray `comment` argument cannot overwrite the issue description.
**`ADD_COMMENT` visibility (JSM):** For Jira Service Management requests, set `comment_visibility` to `public` when replying to the customer or `internal` for an agent-only note. When omitted, Genesis preserves Jira's existing/default comment behavior. Successful `ADD_COMMENT` responses can include `comment_id`, `visibility`, `visibility_verified`, and related fields. If Jira applies a different visibility than requested, the tool returns `Success: false` with `visibility_mismatch` and `retry_safe: false` — do not retry because the comment already exists.
**`CREATE_LINK`, `ADD_ATTACHMENT`, and `TRANSITION_ISSUE`:** `CREATE_LINK` links two issues as `issue_key` → `link_type` → `target_issue_key` (for example, link an X-ray Test to its Story with `link_type="tests"`). `ADD_ATTACHMENT` uploads a file from Genesis storage to an issue via a scoped URI. `TRANSITION_ISSUE` moves an issue through its workflow — pass `transition_id` directly, or pass a target `status` name and Genesis resolves the transition automatically.
**Action Review for writes:** `CREATE_ISSUE`, `CREATE_CHILD_ISSUE`, `UPDATE_ISSUE`, `ADD_COMMENT`, `TRANSITION_ISSUE`, `CREATE_LINK`, and `ADD_ATTACHMENT` run under Action Review. The deployment policy may apply a write immediately or wait for a person to approve it. A pending result means nothing has changed yet; an uncertain result has `action_review.status="reconciliation_required"` — do not retry it blindly. For an uncertain attachment upload, check the issue's attachments manually before deciding what to do: Jira does not provide a client-chosen upload identity for automatic reconciliation. Mutating requests sent through `connection_api_action` are also outside this family.
**`ADD_ATTACHMENT` staging:** Genesis reads the scoped source before the Action Review decision and holds a private snapshot of its bytes for that proposal. The upload is limited to 20 MB. A `query-result://` source must belong to the same user, bot, and thread; its query may run once while staging, but approval and submission use the captured bytes rather than running it again. The snapshot is checked against its recorded filename, content type, size, and digest before submission, then released when the proposal is terminal (the Action Review sweep retries cleanup failures). See [Databricks durability](/docs/deployments/Databricks/Genesis-On-Databricks#durable-git-repositories) for Databricks volume storage, access, and restart behavior. For example, use `action="ADD_ATTACHMENT"`, `issue_key="OPS-42"`, and `attachment_uri="sandbox:/mnt/data/triage.log"`; set `filename` only to override the stored file's name.
Prefer API tokens over passwords for Jira Cloud. Create tokens from your Atlassian account and store them securely.
**`SEARCH_ISSUES` on Jira Cloud:** Genesis calls Atlassian's enhanced `/rest/api/3/search/jql` endpoint with a JSON POST body (`jql`, `fields`, `maxResults`). The enhanced search contract does not include the legacy `startAt` offset parameter — non-zero offsets return an error. Narrow your JQL to stay within the returned page. Jira Server/Data Center continues to use the classic search API with offset pagination via `startAt`.
### Write identity and connection selection
Genesis scopes Jira **write** actions — `CREATE_ISSUE`, `CREATE_CHILD_ISSUE`,
`UPDATE_ISSUE`, `ADD_COMMENT`, `CREATE_LINK`, `ADD_ATTACHMENT`, and
`TRANSITION_ISSUE` — by the resolved connection identity:
* **User OAuth** connections act as the requesting user. Writes require a
requesting user in the active thread context.
* **Personal** PAT or API-token connections allow writes only when the
requesting user owns that connection.
* **Shared** PAT or API-token connections fail closed for bot writes unless
the connection's **Write identity** (locator field `identity_type`) is
`service_account` or `team_owned`, or Genesis uses the dedicated Jira
service-worker token for automation-managed threads. `connection_api_action`
only reads Jira: it refuses `POST`/`PUT`/`PATCH`/`DELETE`, so every Jira change
goes through `jira_connector` and Action Review.
Admins set the field in the Connections page edit form or with
`connections_action` UPDATE - which replaces the stored locator, so the full
locator must be resent: `auth_type`, `host`, `email`, `token_scope_mode` and
`identity_type` for Cloud API-token connections, or `auth_type`, `host` and
`identity_type` for Server/DC PAT connections; `api_token` or `pat` may be
omitted to keep the stored secret reference. Older markers on existing rows (`credential_owner_type` /
`owner_type`, or a truthy `is_service_account` / `service_account` /
`team_owned` flag) are still honoured but not recommended. See
[Setup Jira API Parameters](/docs/Setup/Setup-Jira-API-Params).
When a write is blocked, the tool returns `Success: false` with a message that
names the connection and the `identity_type` field to set, plus a `Suggestion`
to configure a Genesis Jira service account, use the requester's own
connection, or pass an allowed `connection_id`.
Successful and blocked write responses include a `provenance` object with
connection id, auth mode, identity type, Jira identity email, requester ids,
and whether service-worker auth was used. For shared or service-worker writes,
`ADD_COMMENT` appends `Posted by Genesis on behalf of {requester email}.` when
the requester email is available and the comment does not already include that
attribution.
`jira_automation_setup_action` and `jira_automation_action` are available by
default. Operators can disable them by setting
`GENESIS_ENABLE_JIRA_AUTOMATION=false` or an equivalent falsey value on one of
the Jira automation flag aliases; while disabled, both helpers return the Jira
automation disabled message.
### **`jira_automation_setup_action`**
Use this helper to manage the same shared Jira automation and service-worker
settings exposed in the Config UI. Shared setup actions require
`access_config_panel` or `manage_all_connections`.
**Common parameters**
| **Name** | **Definition** | **Format** | **Default** |
| - | - | :-: | :-: |
| **action** | Setup action to perform. Values: `GET_CONFIG`, `CONFIGURE_AUTOMATION`, `CONFIGURE_WORKER`, `VALIDATE_WORKER`, `PROVISION_WORKER`, `SYNC_FLOW`, `SETUP`. | String (required) | none |
| **automation\_config** | Optional dictionary of Jira Automation UI fields to save in one payload. | Object | none |
| **service\_worker\_config** | Optional dictionary of Jira Worker UI fields to save in one payload. | Object | none |
| **validate\_worker** | For `SETUP`, validate and bind the worker after saving config. | Boolean | none |
| **provision\_worker** | For `SETUP`, provision or invite the worker after saving config. | Boolean | none |
| **wait\_for\_user\_seconds** | Seconds to wait for an invited worker to appear during validate or provision. | Integer | none |
**Automation convenience parameters**
| **Name** | **Definition** | **Format** | **Default** |
| - | - | :-: | :-: |
| **enabled** | Whether Jira automation should be enabled. | Boolean | none |
| **ingestion\_mode** | Detection mode. Values: `polling`, `hybrid`, `webhook`. | String | none |
| **auto\_pickup** | Whether matching Jira tickets should automatically start Genesis work. | Boolean | none |
| **jira\_connection\_id** | Explicit Jira connection id, usually `jira.`. | String | none |
| **jira\_connection\_name** | Convenience Jira connection name; Genesis converts it to `jira.`. | String | none |
| **poll\_interval\_seconds** | Polling interval in seconds. | Integer | none |
| **poll\_lookback\_minutes** | Initial or manual lookback window in minutes. | Integer | none |
| **poll\_max\_results** | Maximum Jira issues to inspect in one poll pass. | Integer | none |
| **automation\_bot\_id** | Genesis bot that should receive Jira-triggered work. | String | none |
| **project\_keys** | Jira project keys to monitor. Accepts a list or comma-separated string. | Array of strings or String | none |
| **issue\_jql\_filter** | Additional Jira JQL filter applied before work is dispatched. | String | none |
| **trigger\_type** | Pickup trigger. Values: `status`, `assignment`, `status_or_assignment`, `comment_keyword`, `hybrid`. | String | none |
| **trigger\_on\_statuses** | Statuses that should trigger pickup. Accepts a list or comma-separated string. | Array of strings or String | none |
| **trigger\_on\_assignees** | Assignee names, emails, or Jira account IDs that should trigger pickup. | Array of strings or String | none |
| **trigger\_on\_comment\_keywords** | Comment keywords or mentions that should trigger pickup. | Array of strings or String | none |
| **status\_on\_pickup** | Optional Jira status Genesis should move the issue to when work begins. | String | none |
| **status\_on\_needs\_info** | Optional Jira status Genesis should move the issue to when requirements are incomplete. | String | none |
| **status\_on\_done** | Optional Jira status Genesis should move the issue to when work is completed. | String | none |
| **webhook\_secret** | Optional secret used to validate Jira webhook deliveries. | String | none |
**Service-worker convenience parameters**
| **Name** | **Definition** | **Format** | **Default** |
| - | - | :-: | :-: |
| **worker\_label** | Human-facing service worker label, for example `@genesis`. | String | none |
| **worker\_email** | Email for the dedicated Jira service user. | String | none |
| **worker\_display\_name** | Expected Jira display name for the worker. | String | none |
| **worker\_api\_token** | Optional worker Jira API token. | String | none |
| **org\_id** | Optional Atlassian organization ID for provisioning or invites. | String | none |
| **admin\_api\_key** | Optional Atlassian admin API key for provisioning. | String | none |
| **additional\_groups** | Optional Atlassian groups for the worker. Accepts a list or comma-separated string. | Array of strings or String | none |
| **worker\_project\_keys** | Optional Jira projects to validate worker assignability for. | Array of strings or String | none |
| **auto\_bind\_assignment\_trigger** | Whether validation or provisioning should bind worker assignment triggers automatically. | Boolean | none |
| **send\_notification** | Whether Atlassian should email invited worker accounts. | Boolean | none |
| **invitation\_message** | Optional invite message for the service worker. | String | none |
**Example**
```python theme={null}
jira_automation_setup_action(
action="CONFIGURE_AUTOMATION",
enabled=True,
ingestion_mode="polling",
jira_connection_name="shared",
poll_interval_seconds=300,
project_keys=["ENG"],
trigger_type="assignment",
trigger_on_assignees=["@genesis"],
automation_bot_id="Eve",
)
```
### **`jira_automation_action`**
Use this helper to run programmatic Jira automation actions from chat or a
scheduled Genesis Flow.
**Parameters**
| **Name** | **Definition** | **Format** | **Default** |
| - | - | :-: | :-: |
| **action** | Automation action to perform. Currently supports `POLL_ONCE`. | String (required) | none |
| **lookback\_minutes** | Optional manual polling lookback override in minutes. | Integer | none |
When `lookback_minutes` is omitted, `POLL_ONCE` respects the saved
`poll_interval_seconds` throttle and can return a skipped message if the
previous poll ran too recently.
**Example**
```python theme={null}
jira_automation_action(
action="POLL_ONCE",
lookback_minutes=15,
)
```
## **Use Cases**
1. **Auto-create incidents from platform events**
When a data quality check fails, open a `Bug` in the correct project with context attached.
2. **Sync task progress**
Move issues to `In Progress` or `Done` when Genesis tasks are started or completed with `TRANSITION_ISSUE`. Use `UPDATE_ISSUE` with `description` to change the issue body; use `ADD_COMMENT` to post activity in the comment thread.
3. **Link related issues and attach evidence**
Use `CREATE_LINK` to connect tests to stories or mark blockers, and `ADD_ATTACHMENT` to upload logs, screenshots, SQL output, or reports from Genesis storage.
4. **JSM customer replies and internal notes**
Use `ADD_COMMENT` with `comment_visibility="public"` to reply to the customer or `comment_visibility="internal"` for agent-only notes on Jira Service Management requests.
5. **Programmatic reporting**
Run scheduled JQL searches for open blockers and post summaries to Slack.
6. **Sprint coordination**
Batch update assignees and priorities ahead of sprint planning.
7. **Governance and audits**
Pull full issue details with history and attachments for compliance reviews.
\*\*Deleting or bulk editing issues in Jira is hard to undo. \*\*Test your automation in a non-production project first.
## **Workflow/How It Works**
1. **Authenticate**
Provide `jira_url`, `username`, and `api_token` to establish a session.
2. **Operate on issues**
Use `create_issue`, `update_issue`, `get_issue`, and `transition_issue` as tasks progress.
3. **Search and report**
Execute `search_issues` with `jql_query` to produce lists for dashboards or alerts.
4. **Pull context**
Call `get_projects` and `get_workflows` to discover valid types, fields, and transitions.
Custom fields vary by project. Use `get_issue` on a known ticket or the Jira REST API browser to confirm field ids before automating writes.
## **Integration Relevance**
* **project\_manager\_tools** to mirror milestones and task states.
* **data\_dev\_tools** to tie engineering work to Jira user stories.
* **slack\_tools** to notify channels on issue creation or failure transitions.
* **file\_manager\_tools** to attach logs, screenshots, or reports to issues.
* **handoff** to hand off Jira updates as part of multi-agent workflows.
## **Configuration Details**
* Use the full HTTPS base URL for your instance.
* Ensure the API token has permissions for the target projects.
* Match `project_key`, `issue_type`, and custom field ids to the project configuration.
* Workflow transitions require a valid `transition_id` or a `status` name that matches an available transition for the issue’s current workflow state.
## **Limitations or Notes**
1. Jira Cloud and Server/Data Center use different search APIs — Cloud enhanced search is a JSON POST to `/rest/api/3/search/jql` without `startAt` offsets; Server/DC uses the classic search API with offset pagination.
2. API rate limits may require pagination or backoff for large queries.
3. Permissions and screens can block writes to required fields if not supplied.
4. On Jira Server/Data Center, large searches can paginate with offset-based `startAt`. On Jira Cloud, enhanced search does not support offset pagination — narrow JQL instead.
5. Tokens expire or can be revoked. Handle authentication failures gracefully.
## **Output**
* **Authentication**
Confirmation of the authenticated user and scopes.
* **Issue Operations**
Keys, URLs, updated field snapshots, and current status after actions.
* **Search Results**
Arrays of issues with key metadata from JQL queries.
* **Project and Workflow Data**
Project listings, issue types, transitions, and related configuration.
* **Errors**
Clear messages for permission problems, invalid fields, missing transitions, connectivity issues, or blocked shared PAT/API-token write identity.
* **Write provenance**
For write actions, a `provenance` object describing the resolved connection, auth mode, identity type, Jira account email, requester, and whether service-worker auth was used.
* **Comment visibility**
For `ADD_COMMENT` with `comment_visibility`, responses can include `comment_id`, `requested_visibility`, `public`, `visibility`, `visibility_verified`, and warnings such as `visibility_mismatch` when Jira applied a different visibility than requested. `GET_ISSUE` comments include `public` and `visibility` when fetched with `include=['comments']`.
## **Related Pages**
* [Setup Jira API Parameters](/docs/Setup/Setup-Jira-API-Params) — configure the credentials this tool group uses.
* [Jira Automation (Auto-Pickup)](/docs/Setup/Jira-Automation) — have Genesis pick up Jira tickets automatically instead of (or in addition to) calling these tools manually.
* [Connections](/docs/Setup/Connections) — manage the saved Jira connection.
* [Web Access Tools](/docs/Genbot-Toolkit/Web-Access-Tools) — use `connection_api_action` for long-tail Jira/JSM REST endpoints not covered by `jira_connector`.