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 issue workflows by retrieving transitions, changelogs, and status updates.
• Access project metadata such as projects, issue types, priorities, and statuses.

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.

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 various metadata resources. The following table summarizes all available operations:

Operation Details

Add Attachment to Issue

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

Input Parameters:

• IssueKey: Issue key.
• FilePath: File path or base64 content.

Options:

• FileName: File name (optional).

Output:

• Attachments (object-array): Uploaded attachments.
• StatusCode (number): Status code.
• ErrorMessage (string): Error message.

Add Comment to Issue

Add a comment to an existing JIRA issue.

Input Parameters:

• IssueKey: Issue key.
• CommentBody: Comment text content.

Output:

• Comment (object): Created comment.
• StatusCode (number): Status code.
• ErrorMessage (string): Error message.

Create a New Issue

Create a new issue in JIRA with specified project, summary, issue type, and optional fields like description, priority, labels, and assignee.

Options:

• ProjectKey: Project key, e.g., 'PROJ'.
• Summary: Issue summary (title).
• IssueType: Issue type, e.g., 'Bug', 'Task', 'Story'.
• Description: Issue description.
• Priority: Priority level.
• Labels: Labels separated by commas.
• Assignee: Assignee account ID or username.
• CustomFields: Custom fields in JSON format.

Output:

• Issue (object): Created issue data.
• StatusCode (number): Operation status code.
• ErrorMessage (string): Error message if any.

Create a User

Create a new user in JIRA with specified email, display name and optional username.

Input Parameters:

• EmailAddress: User email address (required).
• DisplayName: User display name (required).

Options:

• Username: Username (required for Jira Server, optional for Cloud).
• Notification: Send notification email, 'true' or 'false'.

Output:

• User (object): Created user object with fields: accountId, emailAddress, displayName, active.
• StatusCode (number): Operation status code: 200 (success), 500 (API error), -1 (parameter error).
• ErrorMessage (string): Error message if any, empty string on success.

Delete a User

Delete a user from JIRA by account ID (Cloud) or username (Server).

Options:

• AccountId: User account ID (for Jira Cloud).
• Username: Username (for Jira Server).

Output:

• Deleted (bool): Whether the user was successfully deleted (boolean).
• StatusCode (number): Operation status code: 200 (success), 500 (API error), -1 (parameter error).
• ErrorMessage (string): Error message if any, empty string on success.

Delete an Issue

Delete an issue from JIRA. This operation is irreversible and will permanently remove the issue.

Options:

• IssueKey: Issue key to delete.
• DeleteSubtasks: Whether to delete subtasks.

Output:

• Deleted (bool): Whether the issue was successfully deleted.
• StatusCode (number): Operation status code.
• ErrorMessage (string): Error message if any.

Get All Attachments

Retrieve all attachments from a JIRA issue.

Input Parameters:

• IssueKey: Issue key.

Output:

• Attachments (object-array): Attachments array.
• StatusCode (number): Status code.
• ErrorMessage (string): Error message.

Get All Comments

Retrieve all comments from a JIRA issue with pagination support.

Input Parameters:

• IssueKey: Issue key.

Options:

• StartAt: Pagination start position.
• MaxResults: Maximum results per page.

Output:

• Comments (object-array): Comments array.
• Total (number): Total comments.
• StartAt (number): Start position.
• MaxResults (number): Max results.
• StatusCode (number): Status code.
• ErrorMessage (string): Error message.

Get All Issues

Search and retrieve multiple JIRA issues using JQL with pagination and field filtering support.

Options:

• Jql: JQL query string.
• StartAt: Pagination start position.
• MaxResults: Maximum results per page.
• Fields: Comma-separated fields.
• Expand: Comma-separated expand fields.

Output:

• Issues (object-array): Array of issues.
• Total (number): Total number of issues.
• StartAt (number): Start position.
• MaxResults (number): Max results.
• StatusCode (number): Status code.
• ErrorMessage (string): Error message.

Get All Projects

Get all projects from JIRA with pagination support. Returns a list of project objects.

Options:

• StartAt: Starting position for pagination, default 0.
• MaxResults: Maximum number of results per page, default 50, max 100.

Output:

• Projects (object-array): A list of project objects with fields: id, key, name, projectTypeKey, simplified, style, isPrivate, avatarUrls, self.
• TotalCount (number): Number of projects returned in current page.
• HasMore (bool): Indicates whether there are more projects available for pagination.
• StatusCode (number): Operation status code: 200 (success), 500 (API error), -1 (parameter error).
• ErrorMessage (string): Error description if operation fails, empty string on success.

Get All Users

Get all users from JIRA with pagination support. Returns a list of user objects.

Options:

• StartAt: Starting position for pagination, default 0.
• MaxResults: Maximum number of results per page, default 50, max 1000.

Output:

• Users (object-array): A list of user objects with fields: accountId, username, displayName, emailAddress, active, accountType, avatarUrls, self, timeZone, locale.
• TotalCount (number): Number of users returned in current page.
• HasMore (bool): Indicates whether there are more users available for pagination.
• StatusCode (number): Operation status code: 200 (success), 500 (API error), -1 (parameter error).
• ErrorMessage (string): Error description if operation fails, empty string on success.

Get Issue Changelog

Get the changelog (history of changes) for a JIRA issue, including field changes, status transitions, and other modifications.

Options:

• IssueKey: Issue key, e.g., 'PROJ-123'.
• StartAt: Pagination start position.
• MaxResults: Maximum number of results per page.

Output:

• Changelog (object): Changelog data containing change history records.
• StatusCode (number): Operation status code.
• ErrorMessage (string): Error message if any.

Get Issue Transitions

Get available transitions for a JIRA issue based on its current status and user permissions.

Input Parameters:

• IssueKey: Issue key.

Options:

• Expand: Fields to expand.

Output:

• Transitions (object-array): Available transitions.
• StatusCode (number): Status code.
• ErrorMessage (string): Error message.

Get Issue Types

Get all issue types or issue types for a specific project from JIRA. Returns a list of issue type objects including Bug, Task, Story, Epic, etc.

Options:

• ProjectKey: Optional project key to get issue types for specific project (e.g. 'PROJ').

Output:

• IssueTypes (object-array): A list of issue type objects with fields: id, name, description, subtask, iconUrl, self.
• TotalCount (number): Number of issue types returned.
• StatusCode (number): Operation status code: 200 (success), 500 (API error), -1 (parameter error).
• ErrorMessage (string): Error description if operation fails, empty string on success.

Get Priorities

Get all priorities from JIRA. Returns a list of priority objects including Highest, High, Medium, Low, Lowest, etc.

Output:

• Priorities (object-array): A list of priority objects with fields: id, name, description, iconUrl, statusColor, self.
• TotalCount (number): Number of priorities returned.
• StatusCode (number): Operation status code: 200 (success), 500 (API error), -1 (parameter error).
• ErrorMessage (string): Error description if operation fails, empty string on success.

Get Statuses

Get all statuses from JIRA. Returns a list of status objects including To Do, In Progress, Done, etc. with their status categories (new, indeterminate, done).

Output:

• Statuses (object-array): A list of status objects with fields: id, name, description, iconUrl, statusCategory, self.
• TotalCount (number): Number of statuses returned.
• StatusCode (number): Operation status code: 200 (success), 500 (API error), -1 (parameter error).
• ErrorMessage (string): Error description if operation fails, empty string on success.

Get a Comment

Retrieve a specific comment from a JIRA issue by comment ID.

Input Parameters:

• IssueKey: Issue key.
• CommentId: Comment ID.

Output:

• Comment (object): Comment data.
• StatusCode (number): Status code.
• ErrorMessage (string): Error message.

Get a User

Retrieve user information from JIRA by account ID (Cloud) or username (Server).

Options:

• AccountId: User account ID (for Jira Cloud).
• Username: Username (for Jira Server).
• Expand: Expand fields, e.g., 'groups,applicationRoles'.

Output:

• User (object): User object with fields: accountId, username, displayName, emailAddress, active, accountType, avatarUrls, self, timeZone, locale.
• StatusCode (number): Operation status code: 200 (success), 500 (API error), -1 (parameter error).
• ErrorMessage (string): Error message if any, empty string on success.

Get an Attachment

Retrieve metadata information for a specific JIRA attachment.

Input Parameters:

• AttachmentId: Attachment ID.

Output:

• Attachment (object): Attachment metadata.
• StatusCode (number): Status code.
• ErrorMessage (string): Error message.

Get an Issue

Get detailed information about a specific JIRA issue by its key, with optional field filtering and expansion.

Options:

• IssueKey: Issue key to retrieve.
• Fields: Comma-separated list of fields to return.
• Expand: Comma-separated list of fields to expand.

Output:

• Issue (object): Issue detailed information.
• StatusCode (number): Operation status code.
• ErrorMessage (string): Error message if any.

Remove a Comment

Delete a specific comment from a JIRA issue.

Input Parameters:

• IssueKey: Issue key.
• CommentId: Comment ID to delete.

Output:

• Deleted (boolean): Whether deleted.
• StatusCode (number): Status code.
• ErrorMessage (string): Error message.

Remove an Attachment

Delete a specific attachment from JIRA.

Input Parameters:

• AttachmentId: Attachment ID to delete.

Output:

• Deleted (boolean): Whether deleted.
• StatusCode (number): Status code.
• ErrorMessage (string): Error message.

Find Users

Searches for users by their name, username, or email address. Returns a list of user objects.

Input Parameters:

• Query: A query string to search for users by their name, username, or email address.

Options:

• StartAt: The index of the first result to return in a page of results (default: 0).
• MaxResults: The maximum number of results to return per page (default: 50, max: 1000).

Output:

• Users (object-array): A list of found user objects.
• TotalCount (number): The total number of users that match the query.
• StatusCode (number): The HTTP status code returned. 200 indicates success, -1 indicates parameter error, 500 indicates an exception.
• ErrorMessage (string): A string detailing any error encountered during the request or exception thrown.

Update a Comment

Update an existing comment on a JIRA issue.

Input Parameters:

• IssueKey: Issue key.
• CommentId: Comment ID to update.
• CommentBody: New comment text.

Output:

• Comment (object): Updated comment.
• StatusCode (number): Status code.
• ErrorMessage (string): Error message.

Update an Issue

Update fields of an existing JIRA issue.

Input Parameters:

• IssueKey: Issue key to update.
• UpdateFields: JSON string of fields to update.

Output:

• Updated (boolean): Whether updated successfully.
• StatusCode (number): Status code.
• ErrorMessage (string): Error message.

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.
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 will return the created issue data, including the issue key, 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 the CustomFields parameter to provide any additional required fields in JSON format.

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