How to Create and Route Jira Issues from a Jinba Workflow

Summary

• Jira automation in Jinba requires three config values (base_url, email, and api_token) and covers seven tools: JIRA_CREATE_ISSUE, JIRA_GET_ISSUE, JIRA_SEARCH_ISSUES, JIRA_UPDATE_ISSUE, JIRA_TRANSITION_ISSUE, JIRA_ADD_COMMENT, and JIRA_LIST_PROJECTS.
• Creating an issue requires project_key, summary, and issue_type; retrieve the correct project key first with JIRA_LIST_PROJECTS to avoid errors.
• Route and triage with transition IDs rather than status names, assign users by accountId, and verify the final state using JIRA_SEARCH_ISSUES with JQL.
• Add a JQL pre-check before creating or commenting to prevent duplicate issues caused by network retries.
• Build and deploy this end-to-end Jira automation faster with Jinba Flow, where each step is explicit, auditable, and team-shared.

To open a Jira issue from a workflow, use JIRA_CREATE_ISSUE with config: base_url, email, and api_token, plus input: project_key, summary, and issue_type. Discover the correct project key first with JIRA_LIST_PROJECTS. The task is complete when the issue is created and searchable via JIRA_SEARCH_ISSUES.

This guide covers the full sequence: authenticating with the Jira API, finding the project, creating an issue, routing it through status transitions, and verifying the result with JQL. The tools used are JIRA_CREATE_ISSUE, JIRA_GET_ISSUE, JIRA_SEARCH_ISSUES, JIRA_UPDATE_ISSUE, JIRA_TRANSITION_ISSUE, JIRA_ADD_COMMENT, and JIRA_LIST_PROJECTS.

Step 1: Connect Jinba to Your Jira Instance

Every Jinba tool that integrates with Jira requires three values in its config block: base_url, email, and api_token. These values form the basis of all Jira automation built with Jinba.

Generate an API token from Atlassian account security settings. Store the token in a secret manager or environment variable. Do not hardcode it in a script or workflow definition.

The base_url follows the pattern https://your-domain.atlassian.net. Once both values are available, the config block used in every subsequent command looks like this:

config:
base_url: "https://your-domain.atlassian.net"
email: "you@example.com"
api_token: "<your_token>"

Step 2: Find Your Project Key with JIRA_LIST_PROJECTS

Before creating an issue, the exact project_key for the target project is required. Project keys are short uppercase identifiers such as PROJ, WEB, or API. Passing the wrong key returns an error, so the correct key should be retrieved programmatically rather than guessed.

JIRA_LIST_PROJECTS calls GET /rest/api/3/project and returns every project the configured credentials can access, including each project's key, name, and id.

tool: JIRA_LIST_PROJECTS
config:
base_url: "https://your-domain.atlassian.net"
email: "you@example.com"
api_token: "<your_token>"

Identify the key for the project where the issue should be created and carry it into the next step.

Step 3: Create the Issue with JIRA_CREATE_ISSUE

JIRA_CREATE_ISSUE calls POST /rest/api/3/issue and is the core action in any Jira automation that generates tickets. The required input fields are project_key, summary, and issue_type.

tool: JIRA_CREATE_ISSUE
config:
base_url: "https://your-domain.atlassian.net"
email: "you@example.com"
api_token: "<your_token>"
input:
project_key: "PROJ"
summary: "Fix login button on main page"
issue_type: "Bug"

Common values for issue_type are Bug, Task, Story, and Epic. The successful response includes the new issue's key (for example, PROJ-42) and id. Both values should be stored; the next three steps use them.

Duplicate risk. Due to network retries, JIRA_CREATE_ISSUE can execute more than once for a single logical event. Before creating, run JIRA_SEARCH_ISSUES with a JQL query that matches the intended summary and a narrow creation window. If a matching issue already exists, skip creation and use the existing key.

Step 4: Route and Triage the Issue

Creating the issue is the first step. Routing requires assigning ownership, moving the issue to the correct status, and adding context needed by other tools or team members.

Transition the status with JIRA_TRANSITION_ISSUE

In Jira, issues move between statuses through transitions, not by writing directly to the status field. Each transition has a numeric id and a human-readable name such as Start Progress or Send to QA. Workflows vary by project, so the transitionId for In Progress in one project differs from another.

Retrieve the available transitions for an issue using GET /rest/api/3/issue/{issueIdOrKey}/transitions. The response lists each transition's id and name. Use the id rather than the name when calling JIRA_TRANSITION_ISSUE.

tool: JIRA_TRANSITION_ISSUE
config:
base_url: "https://your-domain.atlassian.net"
email: "you@example.com"
api_token: "<your_token>"
input:
issueIdOrKey: "PROJ-42"
transitionId: "21"

Transition types include global (available from any status), common (available from a defined set of statuses), and looping (returning an issue to its current status to trigger validators). Confirm which type applies before building a sequence that depends on a specific transition being available.

Update fields with JIRA_UPDATE_ISSUE

JIRA_UPDATE_ISSUE modifies fields on an existing issue: description, labels, priority, assignee, and custom fields such as a RAG status indicator.

The assignee field requires an accountId. The accountId is a stable, unique identifier tied to an Atlassian account, not a display name or email address. Retrieve the accountId via the Jira API before building any automation that assigns issues, and store the value as a workflow variable rather than hardcoding a name that can change.

tool: JIRA_UPDATE_ISSUE
config:
base_url: "https://your-domain.atlassian.net"
email: "you@example.com"
api_token: "<your_token>"
input:
issueIdOrKey: "PROJ-42"
fields:
assignee:
accountId: "5b10a2844c20165700ede21g"
priority:
name: "Highest"

To update a custom field, use its field ID (for example, customfield_10020) as the key. Field IDs are visible in the Jira field configuration screens or via the API.

Add context with JIRA_ADD_COMMENT

JIRA_ADD_COMMENT posts a comment to a specific issue. Use it to log output from external systems, record automated decisions, or surface information that the assignee needs without requiring a separate notification channel.

tool: JIRA_ADD_COMMENT
config:
base_url: "https://your-domain.atlassian.net"
email: "you@example.com"
api_token: "<your_token>"
input:
issueIdOrKey: "PROJ-42"
body: "Automated triage complete. On-call engineer assigned. Monitoring link: "

The same at-least-once delivery risk applies to comments as it does to JIRA_CREATE_ISSUE. Before posting, retrieve the issue with JIRA_GET_ISSUE and inspect the most recent comment. If the last comment was posted by the same automation within the last few minutes, skip the new post.

Step 5: Verify with JIRA_SEARCH_ISSUES and JQL

JIRA_SEARCH_ISSUES accepts a JQL string and returns matching issues. It completes the automation loop by confirming that the create, update, and transition steps produced the expected state.

JQL supports functions, field comparisons, and status category filters. Useful patterns for teams managing due-date-driven workflows:

• All open bugs in a project: project = "PROJ" AND issuetype = Bug AND status != Done
• Issues approaching their due date (amber): duedate <= "1w" AND statusCategory != Done
• Issues at risk today (red): duedate <= now() AND statusCategory != Done
• Confirm a specific issue transitioned correctly: summary ~ "API latency" AND status = "In Progress"

JQL date functions operate on calendar time, not working hours. Issues in a Waiting for Customer status count against the due date even while paused. If SLA precision matters, a dedicated time-tracking app is required; native JQL does not account for paused time.

These same queries power saved filters. A saved filter named Red Tickets can be attached to a dashboard gadget, providing a live view of at-risk issues without any additional configuration.

Complete Example: Critical Bug from Detection to In Progress

A monitoring system detects API latency above 2000ms. The target outcome is a triaged Jira issue, assigned to the on-call engineer, marked In Progress, and verified before the automation exits.

Step 1: Create the issue

tool: JIRA_CREATE_ISSUE
input:
project_key: "OPS"
summary: "Critical Bug: API latency > 2000ms"
issue_type: "Bug"

The response returns issueKey: OPS-88.

Step 2: Assign and set priority

tool: JIRA_UPDATE_ISSUE
input:
issueIdOrKey: "OPS-88"
fields:
assignee:
accountId: "5b10a2844c20165700ede21g"
priority:
name: "Highest"

Step 3: Add diagnostic context

tool: JIRA_ADD_COMMENT
input:
issueIdOrKey: "OPS-88"
body: "P99 latency: 2340ms at 14:03 UTC. Trace ID: abc-9912. Auto-assigned to on-call rotation."

Step 4: Transition to In Progress

tool: JIRA_TRANSITION_ISSUE
input:
issueIdOrKey: "OPS-88"
transitionId: "21"

Step 5: Verify

tool: JIRA_SEARCH_ISSUES
input:
jql: "summary ~ \"API latency\" AND status = \"In Progress\" AND project = OPS"

A non-empty result confirms the full workflow completed successfully. If the result is empty, the transition did not apply, and the workflow should raise an alert rather than silently exit.

What to Build Next

The five-step sequence above covers the core of Jira automation with Jinba: authenticate, find the project, create, route, and verify. Each step is explicit and auditable, which makes failures straightforward to locate.

From this base, teams typically extend in two directions. The first is conditional routing: using JIRA_SEARCH_ISSUES to check existing issues before creating new ones, or reading a custom field value before deciding which transition to apply. The second is scheduled verification: running a JIRA_SEARCH_ISSUES query on a schedule to find issues where the RAG status has not been updated, then using JIRA_UPDATE_ISSUE to correct the field automatically.

Both extensions use the same seven tools covered here. No additional tools are required.

Frequently Asked Questions

What credentials are required to automate Jira with Jinba?

Three values are required: the Jira base_url (e.g., https://your-domain.atlassian.net), the email associated with the Atlassian account, and an Atlassian API token. These three values are placed in the config block of every Jinba Jira tool. Generate the API token from Atlassian account security settings and store it in a secret manager or environment variable; never hardcode it.

How do I find the correct Jira project key for automation?

Use the JIRA_LIST_PROJECTS tool to retrieve all projects the configured credentials can access, then locate the key field (e.g., PROJ, WEB) for the target project. Project keys are short uppercase identifiers, and guessing them leads to errors. JIRA_LIST_PROJECTS calls the Jira REST API and returns each project's key, name, and ID, so the correct key can be selected programmatically.

What are the required input fields for creating a Jira issue with Jinba?

The required inputs are project_key, summary, and issue_type. The workflow must provide the exact project key, a concise summary, and a valid issue type such as Bug, Task, Story, or Epic. The response includes the new issue's key (e.g., PROJ-42) and ID, which are used for subsequent updates.

How can I prevent duplicate Jira issues when using JIRA_CREATE_ISSUE?

Before creating, run a JIRA_SEARCH_ISSUES query with JQL that matches the intended summary and a narrow time window; if a match exists, skip creation and reuse the existing key. Network retries can cause the create tool to execute more than once, so a JQL pre-check reduces the risk of duplicates and is the recommended practice for idempotent automation.

Why does JIRA_TRANSITION_ISSUE require a transition ID instead of a status name?

In Jira, issues move between statuses via transitions, each with a numeric ID; status names are not directly writable, and transition IDs vary by project workflow. The available transitions for an issue must first be retrieved through the Jira API, and the correct transitionId must then be passed to the tool. Using the name instead of the ID can fail because names can be ambiguous or workflow-specific.

How do I find a user's accountId for assigning Jira issues?

Fetch the accountId from the Jira API using a user lookup endpoint or by inspecting an existing issue's assignee field. The accountId is a stable identifier, not a display name or email. The assignee field in JIRA_UPDATE_ISSUE requires an accountId. Store this value as a workflow variable rather than hardcoding a username that can change.

What is JQL and how can it verify Jira automation results?

JQL (Jira Query Language) is a search syntax for filtering issues; use it with JIRA_SEARCH_ISSUES to confirm that create, update, and transition steps produced the expected state. JQL supports functions, field comparisons, and status category filters. Examples include project = "PROJ" AND issuetype = Bug AND status != Done or summary ~ "API latency" AND status = "In Progress".

Can I schedule Jira automation workflows in Jinba?

Yes. Run JIRA_SEARCH_ISSUES on a schedule to find issues that need attention (e.g., stale RAG status) and then use JIRA_UPDATE_ISSUE to correct them automatically. Scheduled verification is a common extension after building the basic create-route-verify sequence. It uses the same seven Jinba Jira tools; no additional tools are required.