Jira

1. Overview

Jira is a widely-used project management and issue tracking platform developed by Atlassian. It is designed to help teams plan, track, and manage software development projects, as well as other types of work management. Jira provides powerful features for creating and organizing issues, tracking workflows, managing sprints, and collaborating across teams.

Through GoInsight's Jira node, you can seamlessly integrate issue management and project operations into your automation workflows. You can achieve comprehensive lifecycle management of issues, comments, attachments, users, and projects, including:

• Create and manage issues with customizable fields, priorities, and issue types.
• Search and retrieve issues using powerful JQL (Jira Query Language) queries.
• Add, update, and delete comments and attachments on issues.
• Manage users including creation, retrieval, and deletion.
• Monitor and control issue workflows by retrieving transitions, performing status changes, and viewing changelogs.
• Access project metadata such as projects, issue types, priorities, and statuses.
• Inspect create-issue metadata for a project and issue type to see required fields, schemas, and allowed values before using Create a New Issue.
• Interpret results consistently using standard agent-oriented outputs (Summary, Hint, Retryable, OriginalStatusCode) alongside StatusCode and ErrorMessage on most operations.

2. Prerequisites

Before using this node, you need to have a valid Jira account. Depending on your Jira deployment type (Cloud or Server/Data Center), you may need different types of credentials:

• For Jira Cloud: You'll need an API token and your Atlassian account email.
• For Jira Server/Data Center: You'll need a username and password, or a personal access token.

You may need administrator privileges or specific project permissions to perform certain operations such as creating users, deleting issues, or managing project configurations.

When automating or debugging, prefer the structured fields Summary, Hint, Retryable, OriginalStatusCode, StatusCode, and ErrorMessage (see Common response fields) instead of relying only on raw HTTP codes in logs.

3. Credentials

For detailed guidance on how to obtain and configure credentials for Jira, please refer to our official documentation: Credentials Configuration Guide.

4. Supported Operations

Summary

The Jira node provides operations organized around several core resources including Issues, Comments, Attachments, Users, Projects, and metadata (issue types, priorities, statuses, and create-issue field definitions). The following table summarizes all available operations:

Common response fields

Most operations return the following fields in addition to their primary payload. Use them for automation and agent recovery logic.

Unless an operation section says otherwise, assume these fields are present alongside the listed primary outputs.

Operation Details

Add Attachment to Issue

Add an attachment to a JIRA issue by uploading a file.

Input Parameters:

• IssueKey (string, required): Issue key (e.g. PROJ-123). Obtain from Get All Issues or Create a New Issue.
• FilePath (string, required): Local file path or base64-encoded file content.

Options:

• FileName (string, optional): Attachment file name; if omitted, a name is derived from FilePath.

Output:

• Attachments (object-array): Uploaded attachment objects (id, filename, size, mimeType, created, author, etc.).

Standard outputs: Common response fields.

Add Comment to Issue

Add a comment to an existing JIRA issue.

Input Parameters:

• IssueKey (string, required): Issue key.
• CommentBody (string, required): Comment body; supports Jira wiki markup or Atlassian Document Format (ADF).

Output:

• Comment (object): Created comment (id, body, author, created, updated, etc.).

Standard outputs: Common response fields.

Create a New Issue

Create a new issue in JIRA. For required custom fields or select values, call Get Create Issue Metadata first for the same ProjectKey and issue type (use IssueType id from Get Issue Types as IssueTypeId in metadata).

Prerequisites: Valid credentials. Use Get All Projects for ProjectKey, Get Issue Types for IssueType, Get Priorities for Priority, Find Users / Get All Users for Assignee.

Idempotency: Jira does not deduplicate by summary; repeated calls create duplicate issues. Optionally search with Get All Issues and JQL such as project = PROJ AND summary ~ "your title" before creating.

Input Parameters:

• ProjectKey (string, required): Project key (e.g. PROJ).
• Summary (string, required): Issue title.
• IssueType (string, required): Type name (e.g. Bug, Task, Story).

Options:

• Description (string, optional): Issue description.
• Priority (string, optional): Priority name from Get Priorities.
• Labels (string, optional): Comma-separated labels (e.g. bug,frontend).
• Assignee (string, optional): Cloud: accountId; Server: username.
• AdditionalFields (object, optional): Extra field key-value pairs for custom or standard fields not exposed above (e.g. customfield_10001, components, fixVersions, environment, duedate in YYYY-MM-DD).

Output:

• Issue (object): Created issue (id, key, self).

Standard outputs: Common response fields.

Create a User

Create a new user in JIRA with email and display name.

Important: This action is intended for Jira Server/Data Center. Jira Cloud does not support creating users through this API; the node may return success with ErrorMessage explaining the limitation and suggesting admin invite flows.

Input Parameters:

• EmailAddress (string, required): User email.
• DisplayName (string, required): Display name.

Options:

• Username (string, optional): Required on Jira Server; not used the same way on Cloud.
• Notification (bool, optional, default false): Whether to send a welcome/notification email to the new user.

Output:

• User (object): On Server, created user fields (name, emailAddress, displayName, active, timeZone, etc.); on Cloud often empty when creation is not supported.

Standard outputs: Common response fields.

Delete a User

Delete a user from JIRA by account ID (Cloud) or username (Server). Warning: Permanent; issues may lose assignee references.

Input Parameters (one of):

• AccountId (string): Jira Cloud account ID (from Find Users / Get All Users).
• Username (string): Jira Server username.

Output:

• Deleted (bool): Whether the user was deleted.

Standard outputs: Common response fields.

Delete an Issue

Delete an issue from JIRA. Warning: Irreversible.

Input Parameters:

• IssueKey (string): Issue key to delete (e.g. PROJ-123).

Options:

• DeleteSubtasks (string, optional, default false): Whether to cascade-delete subtasks (true / false).

Output:

• Deleted (bool): Whether the issue was deleted.

Standard outputs: Common response fields.

Get All Attachments

Retrieve all attachments from a JIRA issue.

Input Parameters:

• IssueKey (string, required): Issue key.

Output:

• Attachments (object-array): Attachment metadata (id, filename, size, mimeType, content URL, created, etc.).

Standard outputs: Common response fields.

Get All Comments

Retrieve all comments from a JIRA issue with pagination.

Input Parameters:

• IssueKey (string, required): Issue key.

Options:

• StartAt (number, optional, default 0): Page offset.
• MaxResults (number, optional, default 50, max 100): Page size.

Output:

• Comments (object-array): Comment objects.
• Total (number): Total comments on the issue.
• StartAt (number): Offset of this page.
• MaxResults (number): Page size requested.

Standard outputs: Common response fields.

Get All Issues

Search issues using JQL with pagination and optional field/expand filters.

Execution: Increment StartAt by MaxResults until StartAt >= Total to walk all pages.

Options:

• Jql (string, optional): JQL filter; if empty, returns issues visible to the user (subject to Jira limits).
• StartAt (number, optional, default 0): Page offset.
• MaxResults (number, optional, default 50, max 100): Page size.
• Fields (string, optional): Comma-separated fields, or *all / *navigable.
• Expand (string, optional): Comma-separated expand segments (e.g. renderedFields,changelog).

Output:

• Issues (object-array): Issue objects (id, key, self, fields, …).
• Total (number): Total matches for the JQL query.
• StartAt (number): This page offset.
• MaxResults (number): This page size.

Standard outputs: Common response fields.

Get All Projects

Get projects from JIRA with client-side paging in the node response.

Deployment note: On Jira Server (API v2), the upstream API does not offer true server-side pagination; all projects may be fetched in one upstream call and then paged in the tool. Jira Cloud (API v3) supports server-side pagination.

Options:

• StartAt (number, optional, default 0): Page offset.
• MaxResults (number, optional, default 50, max 100): Page size.

Output:

• Projects (object-array): Project objects (id, key, name, projectTypeKey, simplified, style, isPrivate, avatarUrls, self).
• TotalCount (number): Count in this page.
• HasMore (bool): Whether more pages exist.

Standard outputs: Common response fields.

Get All Users

Get users from JIRA with pagination.

Options:

• StartAt (number, optional, default 0): Page offset.
• MaxResults (number, optional, default 50, max 1000): Page size.

Output:

• Users (object-array): User objects (accountId, username, displayName, emailAddress, active, accountType, avatarUrls, self, timeZone, locale).
• TotalCount (number): Count in this page.
• HasMore (bool): Whether more pages exist.

Standard outputs: Common response fields.

Get Issue Changelog

Get the changelog (history of changes) for a JIRA issue.

Input Parameters:

• IssueKey (string, required): Issue key (e.g. PROJ-123).

Options:

• StartAt (number, optional, default 0): Changelog page offset.
• MaxResults (number, optional, default 100): Page size.

Output:

• Changelog (object): Change history payload from Jira.

Standard outputs: Common response fields.

Get Issue Transitions

List transitions allowed for the issue in its current status (depends on workflow and permissions).

Input Parameters:

• IssueKey (string, required): Issue key.

Options:

• Expand (string, optional): Comma-separated expand (e.g. transitions.fields).

Output:

• Transitions (object-array): Available transitions (use id as TransitionId in Transition an Issue).

Standard outputs: Common response fields.

Transition an Issue

Change issue status via a workflow transition. Some transitions require fields (for example resolution when closing); inspect Get Issue Transitions for required fields.

Input Parameters:

• IssueKey (string, required): Issue key.
• TransitionId (string, required): Transition id from Get Issue Transitions.

Options:

• Comment (string, optional): Comment recorded with the transition.
• UpdateFields (object, optional): Fields merged into the transition request fields section (e.g. {"resolution": {"name": "Done"}}).
• CustomUpdate (object, optional): Operations under the update section (e.g. worklog, labels add/remove). If Comment is also set, comment-related entries may be merged.

Output:

• Transitioned (bool): Whether the transition succeeded (upstream often returns HTTP 204).

Standard outputs: Common response fields.

Get Create Issue Metadata

Return paginated create field metadata for a project + issue type. Use before Create a New Issue when you need required flags, schemas, or allowedValues for selects.

Input Parameters:

• ProjectKey (string, required): Project key (e.g. PROJ) from Get All Projects.
• IssueTypeId (string, required): Issue type id from Get Issue Types.

Options:

• StartAt (number, optional, default 0): Field list offset (min 0).
• MaxResults (number, optional, default 50, max 200): Page size.

Output:

• Fields (object-array): Field metadata (fieldId, required, name, schema, hasDefaultValue, operations, optional allowedValues, …).
• TotalCount (number): Number of field entries in this response page.

Standard outputs: Common response fields.

Get Issue Types

List issue types for the entire Jira instance when ProjectKey is omitted, or only those available to a project when ProjectKey is set.

Options:

• ProjectKey (string, optional): Project key (e.g. PROJ). If omitted, returns all issue types defined in the instance (including types from other projects).

Output:

• IssueTypes (object-array): Objects with id, name, description, subtask, iconUrl, self, etc.
• TotalCount (number): Number of issue types returned.

Standard outputs: Common response fields.

Get Priorities

List all priorities configured in Jira.

Output:

• Priorities (object-array): Objects with id, name, description, iconUrl, statusColor, self.
• TotalCount (number): Number of priorities returned.

Standard outputs: Common response fields.

Get Statuses

List all statuses. Jira returns the full status catalog in one response (no pagination at the API).

Output:

• Statuses (object-array): Objects with id, name, description, iconUrl, statusCategory (new / indeterminate / done), self.
• TotalCount (number): Number of statuses returned.

Standard outputs: Common response fields.

Get a Comment

Retrieve one comment by ID.

Input Parameters:

• IssueKey (string, required): Issue key.
• CommentId (string, required): Comment ID from Get All Comments.

Output:

• Comment (object): Comment payload.

Standard outputs: Common response fields.

Get a User

Retrieve a user by AccountId (Cloud) or Username (Server). Provide the identifier that matches your deployment.

Options:

• AccountId (string, optional): Required for typical Jira Cloud lookups.
• Username (string, optional): Required for typical Jira Server lookups.
• Expand (string, optional): e.g. groups,applicationRoles.

Output:

• User (object): User profile fields (accountId, username, displayName, emailAddress, active, accountType, avatarUrls, self, timeZone, locale, …).

Standard outputs: Common response fields.

Get an Attachment

Retrieve metadata for one attachment.

Input Parameters:

• AttachmentId (string, required): From Get All Attachments or the issue’s attachment field.

Output:

• Attachment (object): Metadata (id, filename, size, mimeType, content, created, author, …).

Standard outputs: Common response fields.

Get an Issue

Load a single issue with optional field projection and expand segments.

Options:

• IssueKey (string): Issue key (e.g. PROJ-123). You should set this to fetch a concrete issue.
• Fields (string, optional): Comma-separated fields, or *all / *navigable.
• Expand (string, optional): e.g. renderedFields,changelog,transitions.

Output:

• Issue (object): Issue id, key, self, fields, … per Fields / Expand.

Standard outputs: Common response fields.

Remove a Comment

Permanently delete a comment. Warning: Cannot be undone.

Input Parameters:

• IssueKey (string, required): Issue key.
• CommentId (string, required): Comment ID from Get All Comments.

Output:

• Deleted (bool): Whether the comment was removed.

Standard outputs: Common response fields.

Remove an Attachment

Permanently delete an attachment. Warning: Cannot be undone.

Input Parameters:

• AttachmentId (string, required): Attachment ID from Get All Attachments or the issue payload.

Output:

• Deleted (bool): Whether the attachment was removed.

Standard outputs: Common response fields.

Find Users

Search users by name, username, or email substring.

Input Parameters:

• Query (string, required): Search string.

Options:

• StartAt (number, optional, default 0): Page offset.
• MaxResults (number, optional, default 50, max 1000): Page size.

Output:

• Users (object-array): Matching users for this page.
• TotalCount (number): Not a global total from Jira—this reflects the current page size / count returned for this request.

Standard outputs: Common response fields.

Update a Comment

Replace the entire body of an existing comment.

Input Parameters:

• IssueKey (string, required): Issue key.
• CommentId (string, required): Comment ID from Get All Comments.
• CommentBody (string, required): New body (wiki markup or ADF).

Output:

• Comment (object): Updated comment.

Standard outputs: Common response fields.

Update an Issue

Patch issue fields. Only keys present in UpdateFields are sent upstream; other fields stay unchanged.

Input Parameters:

• IssueKey (string, required): Issue key.
• UpdateFields (object, required): Map of Jira field names to values (same shape as the REST API). Examples: summary (string), description (string), priority ({"name": "High"}), assignee (Cloud: {"accountId": "…"}, Server: {"name": "username"}), labels (array of strings), components ([{"name": "Backend"}]).

Output:

• Updated (bool): true when upstream returns 204 No Content for the edit.

Standard outputs: Common response fields.

5. Example Usage

This section will guide you through creating a simple workflow to create a new issue in your JIRA project.

Scenario: You want to create an automated workflow that creates a new bug report in your JIRA project whenever triggered.

Workflow Overview: The workflow consists of three basic nodes: Start → Jira (Create a New Issue) → Answer.

Step-by-Step Guide:

1. Add the Jira Node:
   • In the workflow canvas, click the "+" button to add a new node.
   • In the pop-up panel, select the "Tools" tab.
   • Find and select Jira from the tool list.
   • In the list of supported operations for Jira, click to select Create a New Issue. This will add the corresponding node to the canvas.
2. Configure the Node:
   • Click on the newly added Create a New Issue node, and the configuration panel will expand on the right side.
   • Credential Configuration: At the top of the panel, locate the credentials field. Click the dropdown menu and select your pre-configured Jira credentials. If you haven't set up credentials yet, refer to the Credentials Configuration Guide.
   • Parameter Configuration: Fill in the following parameters to create your issue:
   • ProjectKey: Enter your project key (e.g., 'PROJ' or 'DEV'). This identifies which project the issue will be created in.
   • Summary: Enter a descriptive title for your issue (e.g., 'Login page not loading correctly').
   • IssueType: Specify the type of issue you're creating (e.g., 'Bug', 'Task', or 'Story').
   • Description (Optional): Provide a detailed description of the issue (e.g., 'When users click the login button, the page shows a loading spinner but never completes').
   • Priority (Optional): Set the priority level (e.g., 'High', 'Medium', or 'Low').
   • Labels (Optional): Add labels separated by commas (e.g., 'frontend,urgent').
   • Assignee (Optional): Enter the account ID or username of the person to assign this issue to.
   • AdditionalFields (Optional): Use an object value for custom fields or extra standard fields (for example components, duedate) when they are not covered by the fields above.
3. Run and Verify:
   • Once all required parameters are correctly filled in, any error indicators in the top right corner of the workflow canvas will disappear.
   • Click the "Test Run" button in the top right corner of the canvas to execute the workflow.
   • After successful execution, click the log icon in the top right corner to view the detailed input and output of the node, and verify that the issue was created successfully.
   • You can also go to your JIRA project to confirm that the new issue appears in your issue list.

Final Workflow Summary: After completing these steps, your entire workflow is configured. When you click "Test Run", a new issue will be successfully created in your JIRA project with all the specified details. The node returns the created issue (including Issue.key) plus the standard response fields such as Summary and StatusCode, which you can use in subsequent workflow steps.

6. FAQs

Q: I'm getting a 401 or 403 error when trying to create an issue. What should I check?

A: Please verify the following:

• Ensure your Jira credentials are correctly configured and haven't expired.
• For Jira Cloud, make sure you're using a valid API token (not your account password).
• Verify that your account has the necessary permissions to create issues in the specified project.
• Check that the project key you're using exists and is accessible to your account.

Q: My issue creation fails with "Field is required" error. What's wrong?

A: Different Jira projects may have different required fields based on their configuration:

• Check with your Jira administrator to see which fields are mandatory for your project.
• Some projects may require custom fields that aren't listed in the basic parameters.
• Use Get Create Issue Metadata to list required fields and allowed values, then pass them via the AdditionalFields object (for example customfield_10001, components, fixVersions).

Q: What do Summary, Hint, and Retryable mean on the response?

A: These are standard agent-oriented fields (see Common response fields):

• Summary: Short human-readable outcome on success.
• Hint: When something failed, a suggested next step (for example fix credentials or supply a missing field).
• Retryable: Whether repeating the same call might succeed (often true for transient network errors, false for validation or permission errors).

Q: Why do I see both StatusCode and OriginalStatusCode?

A: OriginalStatusCode is the HTTP status returned by Jira (for example 200, 201, 204, 400, 401). StatusCode is the GoInsight wrapper status (200 means the tool finished handling the call; you should still read ErrorMessage for business or API errors). If OriginalStatusCode is 0, the client did not get a normal HTTP response from Jira (timeout or network path issue); use Hint and Retryable to decide what to do next.

Q: Can I create users on Jira Cloud with "Create a User"?

A: Create a User targets Jira Server/Data Center. Jira Cloud does not support creating users through this API path; use your organization’s admin/invite flows instead. The node may still return structured ErrorMessage text when Cloud is detected.

Q: How do I find a user's account ID for assigning issues?

A: You can obtain user account IDs through:

• Option 1: Use the "Get All Users" or "Find Users" operation in this node to retrieve a list of users with their account IDs.
• Option 2: In Jira Cloud, go to a user's profile and check the URL - the account ID will be visible in the URL string.

Q: What is JQL and how do I use it with "Get All Issues"?

A: JQL (Jira Query Language) is Jira's powerful query language for searching issues:

• Basic example: project = PROJ AND status = "In Progress"
• You can search by assignee: assignee = currentUser()
• Filter by date: created >= -7d
• Refer to Atlassian's JQL documentation for comprehensive syntax guidance.

Q: Can I upload multiple attachments to an issue at once?

A: The "Add Attachment to Issue" operation uploads one file at a time. To upload multiple files:

• Call the operation multiple times with the same IssueKey but different files.
• You can use GoInsight's loop functionality to iterate through a list of files.

Q: What's the difference between Jira Cloud and Jira Server/Data Center?

A: The main differences affecting API usage are:

• Authentication: Jira Cloud uses email + API token, while Server uses username + password or personal access tokens.
• User Identification: Cloud uses accountId, while Server uses username.
• API Endpoints: Cloud uses https://your-domain.atlassian.net, while Server uses your self-hosted domain.
• Project listing: Cloud supports true server-side pagination for Get All Projects; on many Server setups the API returns the full project list in one call and the node pages results locally (see Get All Projects).
• Make sure to configure your credentials appropriately based on your Jira deployment type.

7. Official Documentation

For advanced usage, detailed API specifications, and comprehensive feature documentation, please refer to the official Jira API documentation:

Jira Official API Documentation

For Jira Server/Data Center, refer to:

Jira Server API Documentation