Jira Connector Tools

​

Overview

​

Tool Name

jira_connector_tools

​

Purpose

​

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

​

Input Parameters for Each Function

​

jira_connector

jira_connector(action="LIST_PROJECTS", connection_id="jira.acme")

​

Write identity and connection selection

• 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.

​

jira_automation_setup_action

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

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.

​

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.

​

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 — configure the credentials this tool group uses.
• Jira Automation (Auto-Pickup) — have Genesis pick up Jira tickets automatically instead of (or in addition to) calling these tools manually.
• Connections — manage the saved Jira connection.
• Web Access Tools — use connection_api_action for long-tail Jira/JSM REST endpoints not covered by jira_connector.