Jira

📋

Jira

Automate Jira issue tracking, agile boards, and sprints

The Jira node connects your workflows to Atlassian Jira through the Jira Cloud REST API. It creates and updates issues, runs JQL searches, moves issues through workflow transitions, manages comments and attachments, and works with agile boards and sprints. Use it to keep Jira in sync with the rest of your automations without manual data entry.

Common uses include:

Creating issues automatically when an alert, form, or upstream system raises work.
Updating issue fields, priorities, and custom fields from workflow data.
Searching for issues with JQL and driving downstream steps from the results.
Transitioning issues through their workflow (for example, To Do → In Progress → Done).
Adding comments and attachments to keep issues current.
Planning agile work by moving issues into sprints and reading board or sprint contents.

Before You Start

What you may need	Where to set it up	Why it matters
Jira connection	Jira Connection	Stores the base URL, account email, and API token used to authenticate every action.
Project keys, issue types, field IDs	Global Variables	Keep frequently used Jira values consistent and easy to update across workflows.
A Jira API token	Atlassian account security settings	The connector authenticates with Basic auth built from your email and API token.

Connection

Every Jira action requires a Jira connection, referenced by connectionId. The connection is a JiraConnectionDetails record with these fields:

Field	Required	Description
`baseUrl`	Yes	Jira site base URL (e.g., `https://your-domain.atlassian.net`)
`email`	Yes	Atlassian account email used for authentication
`apiToken`	Yes	Atlassian API token paired with the email

The connector authenticates with HTTP Basic auth, sending Authorization: Basic base64(email:apiToken). Requests target the Jira platform API under /rest/api/3/* and the agile API under /rest/agile/1.0/*.

Configure the connection under Connections > Jira in the Global Configurator, then reference it from each step.

How Parameters Are Resolved

Each action reads its inputs from a configuration key named jira<Action>Details — for example, jiraCreateIssueDetails for jira:createIssue or jiraSearchIssuesDetails for jira:searchIssues.

connectionId is read raw (not expression-resolved).
All other parameters support {{expression}} resolution, so you can pass values from earlier steps or global variables.
List-style fields such as labels, fields, and issueKeys accept either a comma-separated string or a list.
Numeric fields such as maxResults and startAt accept a number or a numeric string.

Actions

Action	Description
`jira:createIssue`	Create a new issue in a project
`jira:getIssue`	Retrieve a single issue by key
`jira:updateIssue`	Update fields on an existing issue
`jira:searchIssues`	Search issues with a JQL query
`jira:transitionIssue`	Move an issue through a workflow transition
`jira:assignIssue`	Assign an issue to a user
`jira:addComment`	Add a comment to an issue
`jira:getComments`	List comments on an issue
`jira:addAttachment`	Attach a file to an issue
`jira:linkIssues`	Create a link between two issues
`jira:updateCustomField`	Set a single custom field value
`jira:getSprintIssues`	List issues in a sprint
`jira:moveToSprint`	Move issues into a sprint
`jira:getProject`	Get project details
`jira:listProjects`	List accessible projects
`jira:listUsers`	List users assignable to a project
`jira:getTransitions`	List available transitions for an issue
`jira:listBoards`	List agile boards
`jira:listSprints`	List sprints on a board

jira:createIssue

Creates a new issue in a project. Returns the created issue key and a browseUrl link to the issue.

Parameters

Parameter	Type	Required	Default	Description
`connectionId`	string	Yes	--	Reference to the Jira connection
`projectKey`	string	Yes	--	Target project key (e.g., `OPS`)
`issueType`	string	Yes	--	Issue type name (e.g., `Task`, `Bug`, `Story`)
`summary`	string	Yes	--	Issue summary/title
`description`	string	No	--	Issue description
`priority`	string	No	--	Priority name (e.g., `High`)
`assignee`	string	No	--	Account ID of the assignee
`labels`	string or list	No	--	Labels as CSV or list
`additionalFields`	object	No	--	Extra field name-value pairs passed through to Jira

Example: Create a bug from an alert

Field	Value
connectionId	`jira-prod`
projectKey	`OPS`
issueType	`Bug`
summary	`Checkout service returning 500s`
priority	`High`
labels	`incident, checkout`

What happens:

The node builds a /rest/api/3/issue request using the resolved fields.
Jira creates the issue and returns its key.
The output includes the issue key and a browseUrl for direct access.

jira:getIssue

Retrieves a single issue by its key.

Parameters

Parameter	Type	Required	Default	Description
`connectionId`	string	Yes	--	Reference to the Jira connection
`issueKey`	string	Yes	--	Issue key (e.g., `OPS-1234`)
`fields`	string or list	No	all navigable fields	Fields to return, as CSV or list

jira:updateIssue

Updates fields on an existing issue. Jira returns HTTP 204 on success; the node reports the update result.

Parameters

Parameter	Type	Required	Default	Description
`connectionId`	string	Yes	--	Reference to the Jira connection
`issueKey`	string	Yes	--	Issue key to update
`recordData`	object	Yes	--	Field name-value pairs to update

Output: { "status": ..., "issueKey": "OPS-1234" }

jira:searchIssues

Runs a JQL search and returns matching issues. Uses the /rest/api/3/search/jql endpoint.

Parameters

Parameter	Type	Required	Default	Description
`connectionId`	string	Yes	--	Reference to the Jira connection
`jql`	string	Yes	--	JQL query string
`fields`	string or list	No	--	Fields to return per issue
`maxResults`	number or numeric string	No	--	Maximum issues to return
`startAt`	number or numeric string	No	--	Zero-based index of the first result

Example: Find open high-priority bugs

Field	Value
connectionId	`jira-prod`
jql	`project = OPS AND type = Bug AND priority = High AND statusCategory != Done`
maxResults	`50`

jira:transitionIssue

Moves an issue through a workflow transition. Find valid transition IDs with jira:getTransitions.

Parameters

Parameter	Type	Required	Default	Description
`connectionId`	string	Yes	--	Reference to the Jira connection
`issueKey`	string	Yes	--	Issue key to transition
`transitionId`	string	Yes	--	Target transition ID
`comment`	string	No	--	Comment added with the transition
`additionalFields`	object	No	--	Fields required by the transition screen

jira:assignIssue

Assigns an issue to a user by account ID.

Parameters

Parameter	Type	Required	Default	Description
`connectionId`	string	Yes	--	Reference to the Jira connection
`issueKey`	string	Yes	--	Issue key to assign
`accountId`	string	Yes	--	Account ID of the assignee

jira:addComment

Adds a comment to an issue.

Parameters

Parameter	Type	Required	Default	Description
`connectionId`	string	Yes	--	Reference to the Jira connection
`issueKey`	string	Yes	--	Issue key
`body`	string	Yes	--	Comment text

jira:getComments

Lists comments on an issue.

Parameters

Parameter	Type	Required	Default	Description
`connectionId`	string	Yes	--	Reference to the Jira connection
`issueKey`	string	Yes	--	Issue key
`maxResults`	number or numeric string	No	--	Maximum comments to return

jira:addAttachment

Attaches a file to an issue. The file is read from the referenced storage path.

Parameters

Parameter	Type	Required	Default	Description
`connectionId`	string	Yes	--	Reference to the Jira connection
`issueKey`	string	Yes	--	Issue key
`filePath`	string	Yes	--	Path to the file to attach

Output: { "status": ..., "issueKey": ..., "filePath": ..., "attachments": [ ... ] }

jira:linkIssues

Creates a link between two issues (for example, blocks or relates to).

Parameters

Parameter	Type	Required	Default	Description
`connectionId`	string	Yes	--	Reference to the Jira connection
`inwardIssueKey`	string	Yes	--	Inward side of the link
`outwardIssueKey`	string	Yes	--	Outward side of the link
`linkType`	string	Yes	--	Link type name (e.g., `Blocks`)

jira:updateCustomField

Sets a single custom field value on an issue.

Parameters

Parameter	Type	Required	Default	Description
`connectionId`	string	Yes	--	Reference to the Jira connection
`issueKey`	string	Yes	--	Issue key
`fieldId`	string	Yes	--	Custom field ID (e.g., `customfield_10011`)
`fieldValue`	any	Yes	--	Value to set

jira:getSprintIssues

Lists issues in a sprint (agile API).

Parameters

Parameter	Type	Required	Default	Description
`connectionId`	string	Yes	--	Reference to the Jira connection
`sprintId`	string	Yes	--	Sprint ID
`fields`	string or list	No	--	Fields to return per issue
`maxResults`	number or numeric string	No	--	Maximum issues to return

jira:moveToSprint

Moves one or more issues into a sprint.

Parameters

Parameter	Type	Required	Default	Description
`connectionId`	string	Yes	--	Reference to the Jira connection
`sprintId`	string	Yes	--	Target sprint ID
`issueKeys`	string or list	Yes	--	Issue keys to move, as CSV or list

jira:getProject

Gets details for a single project.

Parameters

Parameter	Type	Required	Default	Description
`connectionId`	string	Yes	--	Reference to the Jira connection
`projectKey`	string	Yes	--	Project key

jira:listProjects

Lists projects the authenticated user can access.

Parameters

Parameter	Type	Required	Default	Description
`connectionId`	string	Yes	--	Reference to the Jira connection
`maxResults`	number or numeric string	No	--	Maximum projects to return

jira:listUsers

Lists users assignable to a project.

Parameters

Parameter	Type	Required	Default	Description
`connectionId`	string	Yes	--	Reference to the Jira connection
`projectKey`	string	Yes	--	Project key
`maxResults`	number or numeric string	No	--	Maximum users to return

Output: { "users": [ ... ], "total": ... }

jira:getTransitions

Lists the workflow transitions available for an issue in its current status. Use the returned IDs with jira:transitionIssue.

Parameters

Parameter	Type	Required	Default	Description
`connectionId`	string	Yes	--	Reference to the Jira connection
`issueKey`	string	Yes	--	Issue key

jira:listBoards

Lists agile boards (agile API).

Parameters

Parameter	Type	Required	Default	Description
`connectionId`	string	Yes	--	Reference to the Jira connection
`maxResults`	number or numeric string	No	--	Maximum boards to return

jira:listSprints

Lists sprints on a board (agile API).

Parameters

Parameter	Type	Required	Default	Description
`connectionId`	string	Yes	--	Reference to the Jira connection
`boardId`	string	Yes	--	Board ID
`maxResults`	number or numeric string	No	--	Maximum sprints to return

Output

Each action returns the relevant Jira response payload. Common shapes include:

Action	Output highlights
`jira:createIssue`	Created issue key plus a `browseUrl` link
`jira:updateIssue`	`status` and `issueKey` (Jira returns HTTP 204)
`jira:searchIssues`	Matching issues with the requested fields
`jira:addAttachment`	`status`, `issueKey`, `filePath`, and `attachments` list
`jira:listUsers`	`users` list and `total` count

Common Error Scenarios

Error	Type	Likely Cause	What to Check
Missing configuration	`VALIDATION_ERROR`	The `jira<Action>Details` config map is missing or empty	Confirm the action's parameter block is populated
Required parameter missing	`VALIDATION_ERROR`	A required field (e.g., `projectKey`, `issueKey`, `jql`) is blank	Provide all required parameters for the action
Connection not found	`NOTFOUND_ERROR`	The referenced `connectionId` does not resolve to a Jira connection	Verify the connection exists in the Global Configurator
Jira API error	HTTP error	Jira rejects the request (bad field, permissions, missing issue)	The node reports `Jira API HTTP error (<status>): <body>` — inspect the status and body
Invalid transition	HTTP error	The `transitionId` is not valid from the issue's current status	Call `jira:getTransitions` first to get valid IDs

Best Practices

Store the connection once. Configure a single Jira connection in the Global Configurator and reference it by connectionId across all steps.
Look up transitions dynamically. Transition IDs vary by workflow and current status. Call jira:getTransitions before jira:transitionIssue instead of hard-coding IDs.
Use account IDs for assignment. Jira Cloud identifies users by account ID, not username or email. Resolve account IDs with jira:listUsers.
Keep JQL specific. Narrow searches with project, type, and status filters, and set maxResults to avoid pulling large result sets.
Reference custom fields by ID. Custom fields use IDs like customfield_10011. Store these in global variables so workflows stay readable.
Pass values through expressions. All parameters except connectionId support {{expression}} resolution — use it to wire Jira steps to upstream data.

Jira

Before You Start​

Connection​

How Parameters Are Resolved​

Actions​

jira:createIssue​

jira:getIssue​

jira:updateIssue​

jira:searchIssues​

jira:transitionIssue​

jira:assignIssue​

jira:addComment​

jira:getComments​

jira:addAttachment​

jira:linkIssues​

jira:updateCustomField​

jira:getSprintIssues​

jira:moveToSprint​

jira:getProject​

jira:listProjects​

jira:listUsers​

jira:getTransitions​

jira:listBoards​

jira:listSprints​

Output​

Common Error Scenarios​

Best Practices​

Before You Start

Connection

How Parameters Are Resolved

Actions

jira:createIssue

jira:getIssue

jira:updateIssue

jira:searchIssues

jira:transitionIssue

jira:assignIssue

jira:addComment

jira:getComments

jira:addAttachment

jira:linkIssues

jira:updateCustomField

jira:getSprintIssues

jira:moveToSprint

jira:getProject

jira:listProjects

jira:listUsers

jira:getTransitions

jira:listBoards

jira:listSprints

Output

Common Error Scenarios

Best Practices