Atlassian Jira Software

LAST UPDATED: SEPTEMBER 18, 2025

Overview

Atlassian Jira Software is an issue and project tracking platform used to plan, track and manage agile and software development projects.

D3 SOAR is providing REST operations to function with Jira Software.

Jira is available for use in:

D3 SOAR	V12.7.83.0+
Category	Case Management
Deployment Options	Option II, Option IV

Known Limitations

The add-on allows a maximum of 500 API requests within a 5-minute period. If this limit is exceeded, HTTP status 429 is returned along with a message indicating that the limit has been reached.

Refer to REST API Rate Limits for detailed information.

Connection

To connect to Jira Software from D3 SOAR, follow this part to collect the required information below:

Parameter	Description	Example
Default
Server URL	The server URL of the Jira instance.	https://<site>.atlassian.net
Authentication Method	The authentication method (basic or OAuth) to use for the connection.	OAuth Authentication
API Version	The version of the API to use for the connection.	3
Basic Authentication
User Name	The user name to establish the API connection.	***@*.***
API Token	The API token to authenticate the API connection.	*****
OAuth Authentication
Client ID	The client ID to authenticate the API connection.	*****
Client Secret	The client secret to authenticate the API connection.	*****
Authorization Code	The authorization code for OAuth2.0 authentication. Click the "Get Authorization" button on the Connection page to automatically generate an authorization code.	*****
Callback URL	The callback URL for OAuth2.0 authentication. See step 10 of OAuth 2.0 Authentication for more information.	https://***.***
Refresh Token	The refresh token for the OAuth2.0 authentication with the grant type of authorization code. Click the "Get Refresh Token" button on the Connection page to automatically generate a refresh token. This parameter is read-only and Auto-generated.	*****

Permission Requirements

All commands will require the following classic scopes to run:

read:jira-work
read:jira-user
write:jira-work
manage:jira-configuration
manage:jira-data-provider
manage:jira-project

Configuring Jira Software to Work with D3 SOAR

READER NOTE

There are two authentication methods to establish an integration connection with D3 SOAR: OAuth2.0 Authentication and Basic Authentication. Refer to the corresponding sections below depending on the use case.

OAuth 2.0 Authentication

Log into Jira.
Click on the profile icon on the top right corner, then select Developer Console.
On the Developer Console page, click Create and select OAuth 2.0 integration.
Enter an App Name, and agree to Atlassian developer terms. Click Create.
Select Permissions from the left sidebar. Locate Jira API, and click its adjacent Add button.
Click Configure.
On the Jira API page, click Edit Scopes.
Select the following required scopes, then click Save. For each commands' required permissions, see Permission Requirements.
Select Authorization from the left sidebar. Locate OAuth 2.0 (3LO), and click its adjacent Add button.
Enter the Callback URL generated from D3 SOAR (see step 4 of Authentication Type: OAuth Authentication under Configuring D3 SOAR to Work with Jira), then click Save changes.
Select Settings from the left sidebar. Under the Authentication details section, copy the Client ID and Secret for use to build the integration connection in D3 SOAR.

Basic Authentication

READER NOTE

The basic authentication method provides the same level of access as the user account would have access to on the Jira web UI.

Log into Jira.
Click Create API token.
The Create an API token dialog box will appear. Enter a Label name and click Create.
The generated API token will appear. Click Copy to save the API token to your clipboard. The API token will be required to build the integration connection in D3 SOAR.

ALERT

The API token is visible only once at the time of creation. Store it securely for future reference.

Creating a User

See Invite a user from Atlassian Support for instructions.

Setup Time Zone

Log into the Jira instance with the account that VSOC uses for authentication. Click the account icon on the top right corner, then click Manage account.
Click Account preferences. Under Time zone, click the current time zone; in the dropdown list, select UTC. The account that vSOC uses to connect to your Jira instance will then operate in the UTC time zone.

Configuring D3 SOAR to Work with Jira

Log in to D3 SOAR.
Find the Jira integration.
1. Navigate to Configuration on the top header menu.
2. Click on the Integration icon on the left sidebar.
3. Type Jira in the search box to find the integration, then click it to select it.
4. Click + Connection, on the right side of the Connections section. A new connection window will appear.
Configure the following fields to create a connection to Jira.
1. Connection Name: The desired name for the connection.
2. Site: The site on which to use the integration connection. Use the drop-down menu to select the site. The Share to Internal Sites option enables all internal sites to use the connection. Selecting a specific site will only enable that site to use the connection.
3. Recipient site for events from connections Shared to Internal Sites: This field is displayed when Share to Internal Sites is selected for the Site field, allowing selection of the internal site for deploying the integration connection.
4. Agent Name (Optional): The proxy agent required to build the connection. Use the dropdown menu to select the proxy agent from a list of previously configured proxy agents.
5. Description (Optional): The description for the connection.
6. Tenant (Optional): When configuring the connection from a master tenant site, users can choose the specific tenant sites with which to share the connection. Once this setting is enabled, users can filter and select the desired tenant sites from the dropdowns to share the connection.
7. Configure User Permissions: Defines which users have access to the connection.
8. Active: The checkbox that enables the connection to be used when selected.
9. System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.
  Note: It is recommended to use the OAuth authentication method to build an integration connection with Jira. Atlassian is progressively disabling the basic authentication method. See Atlassian's deprecation notice for more information.
  Authentication Type: Basic Authentication
  1. Input the server URL of the Jira instance.
  2. Select Basic Authentication.
  3. Input the Jira user name.
  4. Input the saved Jira API token (refer to step 4 of Basic Authentication).
  5. Input the API version to use for the connection. The default API version is 3.
  Authentication Type: OAuth Authentication
  1. Input the server URL of the Jira instance.
  2. Select OAuth Authentication.
  3. Input the saved Client ID (refer to step 11 of OAuth 2.0 Authentication).
  4. Input the saved Client Secret (refer to step 11 of OAuth 2.0 Authentication).
  5. Click Get Authorization to be directed to Atlassian's access request page. Select the server to allow access, then click Accept. An authentication code will appear, but no further action is required.
  6. Copy the D3 Callback URL, and paste it into Jira's Authentication page (refer to step 10 of OAuth 2.0 Authentication).
  7. Return to D3 SOAR. Click Get Refresh Token. The refresh token and authentication code will be automatically generated and entered into the corresponding parameters.
  8. Input the API version to use for the connection. The default API version is 3.
10. Connection Health Check: Periodically checks the connection status by scheduling the Test Connection command at the specified interval (in minutes). Available only for active connections, this feature also allows configuring email notifications for failed attempts.
11. Enable Password Vault: An optional feature that allows users to take the stored credentials from their own password vault. Refer to the password vault connection guide if needed.
Test the connection.
1. Click on the Test Connection button to verify credentials and connectivity. A success alert displays Passed with a green checkmark. If the connection fails, review the parameters and retry.
2. Click OK to close the alert window.
3. Click + Add to create and add the configured connection.

READER NOTE

If the server URL is unknown, log in to Atlassian Admin using admin credentials. A list of all organizations will be displayed. Select the desired organization to view the associated Atlassian products and their respective server URLs.
The Get Issue, List Transitions, and Transition Issue commands are not currently compatible with the version 3 of Jira's API. To use those commands, build a separate connection with API version 2.

Commands

Jira includes the following executable commands for users to set up schedules or create playbook workflows. With the Test Command, users can execute these commands independently for playbook troubleshooting.

Integration API Note

For more information about the Jira API, refer to the Jira API reference.

READER NOTE

Certain permissions are required for each command. Refer to the Permission Requirements and Configuring Jira to Work with D3 SOAR for details.

Note for Time-related parameters

The input format of time-related parameters may vary based on user account settings, which may cause the sample data in commands to differ from what is displayed. To adjust the time format, follow these steps:

Navigate to Configuration > Application Settings. Select Date/Time Format.
Choose the desired date and time format, then click on the Save button.

The selected time format will now be visible when configuring Date/Time command input parameters.

Add Comment To Issues

Adds a comment to issues in Jira.

READER NOTE

Input parameter Issue IDs or Keys is required to run this command.
- Run the Search Issues command to obtain Issue IDs or Keys. Issue Key can be found in the returned raw data at the path $.issues[*].key. There are other keys with the name "key". Ensure you have selected the provided JSON path. Issue IDs can be found in the returned raw data at the path $.issues[*].id.
The Visibility Type parameter can be used to restrict a comment's visibility. To use this function, follow the steps below:
- With an admin account, log in to Jira.
- Navigate to JIRA Settings > System > General Configuration.
- Ensure "Comment visibility" and is set to "Groups & Project Roles" and not "Project Roles only".
- To change the Comment visibility setting, click the Edit button at the top of the page.
- Scroll down the Options section, and find the Comment visibility setting. Select Groups and Project Roles.

Input

Input Parameter	Required/Optional	Description	Example
Issue IDs or Keys	Required	The IDs or keys of the issues to add a comment. Issue IDs and keys can be obtained using the Search Issues command.	JSON `[ "*****" ]`
Comment	Required	The comment text to add. You can input comments in plain text or HTML format. Please note, if you want to input HTML Markdown format, you can only use api version 2.	Conduct additional tests.
Visibility Type	Optional	The visibility type (i.e. group or role) to restrict the comment's visibility. The input value must correspond to the value defined in the Visibility Value parameter. Note: Comment visibility must be configured in Jira. Check under JIRA Settings > System > General Configuration for "Comment visibility" and ensure it is set to "Groups & Project Roles" and not "Project Roles only".	Role
Visibility Value	Optional	The name of the roles or groups to allow the comment's visibility. The input value must correspond to the value defined in the Visibility Type parameter. Note: Comment visibility must be configured in Jira. Check under JIRA Settings > System > General Configuration for "Comment visibility" and ensure it is set to "Groups & Project Roles" and not "Project Roles only".	Engineers

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Add Comment To Issues failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Jira portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: You are currently not a member of the project role: Administrators.

Error Sample Data

Add Comment To Issues failed.

Status Code: 400.

Message: You are currently not a member of the project role: Administrators.

Add Web Link

Creates or updates a remote issue link for an issue.

READER NOTE

Issue ID or Key is a required parameter to run this command.

Run the Search Issues command to obtain Issue ID or Key. Issue Key can be found in the returned raw data at the path $.issues[*].key. Ensure you have selected the provided JSON path. Issue IDs can be found in the returned raw data at the path $.issues[*].id. Note: There are other keys with the name "key".

Input

Input Parameter	Required/Optional	Description	Example
Issue ID or Key	Required	The ID or key of the issue to add a remote issue link. Issue IDs and keys can be obtained using the Search Issues command.	JSON `[ "*****" ]`
URL	Required	The URL link to add or update.	https://***.***
Title	Required	The title of the link.	test Remote Link 0808a v3

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Add Web Link failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Jira portal. Refer to the HTTP Status Code Registry for details.	Status Code: 401.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Issue does not exist or you do not have permission to see it.

Error Sample Data

Add Web Link failed.

Status Code: 401.

Message: Unauthorized.

Assign Issue To User

Assigns issue(s) to a specified user. This command should be used when the calling user has the Assign issue permission but does not have the Edit Issues permission for the project that contains the designated issue(s).

READER NOTE

Issue IDs or Keys and Assignee are required parameters to run this command.

Run the Search Issues command to obtain Issue IDs or Keys. Issue Key can be found in the returned raw data at the path $.issues[*].key. Ensure you have selected the provided JSON path. Issue IDs can be found in the returned raw data at the path $.issues[*].id. Note: There are other keys with the name "key".
The Assignee can be retrieved from the User List. The user you choose must have access to the project that your input issue is linked to.
- If you see the error message "User ____ cannot be assigned issues" when assigning an issue to a user, check that the user has appropriate access to the associated project.

Input

Input Parameter	Required/Optional	Description	Example
Issue IDs or Keys	Required	The IDs or keys of the issues to assign to the user. Issue IDs and keys can be obtained using the Search Issues command.	JSON `[ "*****" ]`
Assignee	Required	The email address or display name of the issue's assignee. Enter the assignee's full display name or email address to avoid ambiguity.	***@*.***

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Assign Issue To User failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Jira portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Issue does not exist or you do not have permission to see it.

Error Sample Data

Assign Issue To User failed.

Status Code: 404.

Message: Issue does not exist or you do not have permission to see it.

Create Issue

Creates an issue or subtasks (if enabled) in Jira.

READER NOTE

Project Key and Issue Type Name are required parameters to run this command.

Run the Get Create Meta command to obtain Project Key. Project Keys can be found in the returned raw data at the path $.projects[*].key.
Run the Get Create Meta command to obtain Issue Type Names. Issue Type Names can be found in the returned raw data at the path $.projects[*].issuetypes[*].name.

Input parameter Custom Fields is Optional to input to run this command.

Run the List Fields command to obtain Custom Fields.
If you are adding custom fields with an account ID, you can obtain the account ID using the Get Account IDs command. Account IDs can be found in the returned raw data at the path $.users[*].accountId.

Input

Input Parameter	Required/Optional	Description	Example
Project Key	Required	The key of the project to create the issue in. You can obtain the project key from returned raw data of the Get Create Meta command. Note: The project key is different from the project name.	*****
Issue Type Name	Required	The issue type to associate the issue. You can obtain all the available issue types for a specific project by running the Get Create Meta command. Note: Only configured issue types for the input project are valid for this parameter. Issue Type Names are case-sensitive.	Sub-task
Summary	Required	The summary text of the issue.	Issue's subtask1
Description	Optional	The description text of the issue. The description can be inputted in plain text or HTML format. Please note, if HTML Markdown format is to be used for input, only API version 2 can be used. For connection api version 3, Atlassian Document Format (ADF) JSON Object must be used for input.	subtask creation V3 description.0808d
Additional Information	Optional	The value of additional fields for the Epic and Sub-task issue types: Epic: The input additional information is the value of the Epic name. Sub-task: The input additional information is the value of the parent issue key.	New Epic
Assignee	Optional	The email address or display name of the issue's assignee. Enter the assignee's full display name or email address to avoid ambiguity.	***@*.***
Custom Fields	Optional	The JSON object containing the custom fields of the issue to update. The available custom fields can be obtained using the List Fields command. Note: The custom fields must be added to the issue's update screen. If you are adding custom fields with an account ID, you can obtain the account ID using the Get Account IDs command.	JSON `{ "customfield_10064": "Hello", "customfield_10003": [ { "accountId": "*****" } ] }`

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Create Issue failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Jira portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Specify a valid project ID or key.

Error Sample Data

Create Issue failed.

Status Code: 403.

Message: Specify a valid project ID or key.

Delete Issues

Deletes the specified issue(s).

READER NOTE

Input parameter Issue IDs or Keys is required to run this command.

Run the Search Issues command to obtain Issue IDs or Keys. Issue Key can be found in the returned raw data at the path $.issues[*].key. There are other keys with the name "key". Ensure you have selected the provided JSON path. Issue IDs can be found in the returned raw data at the path $.issues[*].id.

Input

Input Parameter	Required/Optional	Description	Example
Issue IDs or Keys	Required	The IDs or keys of the issues to retrieve details. Issue IDs and keys can be obtained using the Search Issues command.	JSON `[ "*****" ]`

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Delete Issues failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Jira portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Issue does not exist or you do not have permission to see it.

Error Sample Data

Delete Issues failed.

Status Code: 403.

Message: Issue does not exist or you do not have permission to see it.

Download Attachment

Downloads all attachment files of the specified issue.

READER NOTE

Issue ID or Key is a required parameter to run this command.

Run the Search Issues command to obtain Issue ID or Key. Issue Key can be found in the returned raw data at the path $.issues[*].key. There are other keys with the name "key". Ensure you have selected the provided JSON path. Issue IDs can be found in the returned raw data at the path $.issues[*].id.
If the command runs successfully with no returned results, there may be no attachments in your input issues or invalid input issue IDs or Keys.

Input

Input Parameter	Required/Optional	Description	Example
Issue ID or Key	Required	The ID or key of the issue to download attachments. Issue IDs and keys can be obtained using the Search Issues command.	*****

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Download Attachment failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Jira portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Invalid Token.

Error Sample Data

Download Attachment failed.

Status Code: 403.

Message: Invalid Token.

Edit Issue

Edits an issue in Jira.

READER NOTE

Issue ID or Key is a required parameter to run this command.

Run the Search Issues command to obtain Issue ID or Key. Issue Key can be found in the returned raw data at the path $.issues[*].key. There are other keys with the name "key". Ensure you have selected the provided JSON path. Issue IDs can be found in the returned raw data at the path $.issues[*].id.

The Assignee can be retrieved from the User List. The user you choose must have access to the project that your input issue is linked to.

If you see the error message "User ____ cannot be assigned issues" when assigning an issue to a user, check that the user has appropriate access to the associated project.

Input parameter Custom Fields is Optional to input to run this command.

Run the List Fields command to obtain Custom Fields.
If custom fields are added with an account ID, the account ID can be obtained using the Get Account IDs command. Account IDs can be found in the returned raw data under the path $.users[*].accountId.

Input

Input Parameter	Required/Optional	Description	Example
Issue Key or ID	Required	The Key or ID of the issue to update. Issue keys and IDs can be obtained using the Search Issues command.	*****
Summary	Optional	The updated summary text of the issue.	Issue change 808b v3
Description	Optional	The updated description text of the issue. The description can be inputted in plain text or HTML format. Please note, HTML Markdown format is to be inputted, api version 2 must be used. For connection api version 3, if markdown format is to be inputted, Atlassian Document Format (ADF) JSON Object must be inputted.	description. 808b v3
Assignee	Optional	The email address of display name of the issue's assignee. Enter the assignee's full display name or email address to avoid ambiguity.	***@*.***
Priority	Optional	The priority level of the issue. The built-in priorities are Highest, High, Medium, Low, Lowest. Note: If the priority field does not exist in the project, do not define this parameter.	Highest
Custom Fields	Optional	The JSON object containing the custom fields of the issue to update. The available custom fields can be obtained using the List Fields command. Note: The custom fields must be added to the issue's update screen. If you are adding custom fields with an account ID, you can obtain the account ID using the Get Account IDs command.	JSON `{ "customfield_10064": "Hello303b", "customfield_10003": [ { "accountId": "*****" } ] }`

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Edit Issue failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Jira portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Issue does not exist or you do not have permission to see it.

Error Sample Data

Edit Issue failed.

Status Code: 404.

Message: Issue does not exist or you do not have permission to see it.

Fetch Event

Returns issues based on the specified search conditions.

Input

Input Parameter	Required/Optional	Description	Example
Start Time	Optional	The start time of the time range to fetch issues in UTC time.	2022-08-01 00:00
End Time	Optional	The end time of the time range to fetch issues in UTC time.	2022-12-01 00:00
Query Time Type	Required	The time type to query results. The available time types are Issue Created Time, Updated Time, Resolved Time, Due Time and Last Viewed Time.	Created Time
Number of Event(s) Fetched	Optional	The maximum number of issues to return. If this parameter is not defined, all issues will be returned.	10
Search Condition	Optional	The JQL query string to return events. The commonly used syntax is <field> <operator> <value or function>. You may use the AND and OR operators between fields. See What is advanced searching in Jira Cloud? from Atlassian's documentation for more about JQL's syntax.	key= "*****"
Tolerance Scope (minute)	Optional	The tolerance scope (the default value is 10) in minutes of the query to fetch events between start and end time to avoid the loss of events. Events will be fetched between {Start Time - Tolerance Scope, End Time}.	10
Returned Fields	Optional	The list of fields to return for each issue should be used to retrieve a subset of fields. The possible values are "all", "navigable" and any issue field, prefixed with a minus to exclude. Note that if this field is specified but does not come with "all" or "navigable", the returned fields will only include specified fields.	JSON `[ "*all", "comment" , "-updated"]`

Output

To view the sample output data for all commands, refer to this article.

Fetch Event Field Mapping

See Field Mappings.

The Atlassian Jira Software system integration includes pre-configured field mappings for the default event source.

The Default Event Source is the default system-provided set of field mappings applied when the fetch event command is executed. It includes a Main Event JSON Path, which is the JSONPath expression that points to the base array of event objects. The source field path continues from this array to locate the required data.

The Main Event JSON Path can be viewed by clicking on the Edit Main JSON Path button.

Main Event JSON Path: $.issues
The issues array contains the event objects. Within each object, the key id denotes the Original event ID field. As such, the full JSONPath expression to extract the Original event ID is $.issues.id.

READER NOTE

The Unique Event Key field mapping is used to prevent duplicate event ingestions. D3 SOAR will check if the value of a selected JSON path matches any Unique Event Key of previously ingested events. If a match is found, the event will be dismissed. If no match is found, an event will be created. However, if no Unique Event Key is mapped, then the hash value from the event pending ingestion will be used to check for any matches with existing events. If no match is found, the event will be created.

Unlike most other D3 SOAR integrations, the Jira integration's Fetch Event command's Default Event Source mapping does not include Unique Event Key in order to fetch the same fetched issues with multiple updates.

The pre-configured field mappings are detailed below:

Field Name	Source Field
Original event ID	.id
Event name	.key
Event Type	.fields.issuetype.name
Description	.fields.issuetype.description
UTCEventTime	.fields.created
UpdateTime	.fields.updated
Status	.fields.status.name
Assignee	.fields.assignee.displayName

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Fetch Event failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Jira portal. Refer to the HTTP Status Code Registry for details.	Status Code: 401.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Error in the JQL Query: Expecting either \'OR\' or \'AND\' but got xxx.

Error Sample Data

Fetch Event failed.

Status Code: 401.

Message: Error in the JQL Query: Expecting either \'OR\' or \'AND\' but got xxx.

Get Account IDs

Returns account IDs of the specified users.

Input

Input Parameter	Required/Optional	Description	Example
User Display Names or Emails	Required	The display name or email addresses of the users to retrieve account IDs.	JSON `[ "***@*.***" ]`

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Account IDs failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Jira portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: User Display Names or Emails Not Found.

Error Sample Data

Get Account IDs failed.

Status Code: 404.

Message: User Display Names or Emails Not Found.

Get Comment From Issues

Returns all comments for the specified issue(s).

READER NOTE

Input parameter Issue IDs or Keys is required to run this command.

Run the Search Issues command to obtain Issue IDs or Keys. Issue Key can be found in the returned raw data at the path $.issues[*].key. Ensure you have selected the provided JSON path. Issue IDs can be found in the returned raw data path $.issues[*].id. Note: There are other keys with the name "key".
If the command runs successfully with no results, the specified issue may not have any existing comments.

Input

Input Parameter	Required/Optional	Description	Example
Issue IDs or Keys	Required	The IDs or keys of the issues to retrieve comments. Issue IDs and keys can be obtained using the Search Issues command.	JSON `[ "*****" ]`

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Comment From Issues failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Jira portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Issue does not exist or you do not have permission to see it.

Error Sample Data

Get Comment From Issues failed.

Status Code: 404.

Message: Issue does not exist or you do not have permission to see it.

Get Create Meta

Returns details of projects, issue types within projects, and the create screen fields for each issue type for the user. Use this command to populate the input parameters of the Create Issue command.

Input

N/A

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Create Meta failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Jira portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Invalid Token.

Error Sample Data

Get Create Meta failed.

Status Code: 403.

Message: Invalid Token.

Get Issue

Retrieves details of the specified issue(s).

READER NOTE

This is not currently compatible with the version 3 of Jira's API. It is recommended to build a separate connection with API version 2 to use this command.
Input parameter Issue IDs or Keys is required to run this command.
- Run the Search Issues command to obtain Issue IDs or Keys. Issue Key can be found in the returned raw data at the path $.issues[*].key. There are other keys with the name "key". Ensure you have selected the provided JSON path. Issue IDs can be found in the returned raw data at the path $.issues[*].id.

Input

Input Parameter	Required/Optional	Description	Example
Issue IDs or Keys	Required	The IDs or keys of the issues to retrieve details. Issue IDs and keys can be obtained using the Search Issues command.	JSON `[ "*****" ]`
Fields	Optional	The list of fields to return for the issue. This parameter supports a comma-separated list. If this parameter is not defined, all fields will be returned.	summary,description,comment
Expand	Optional	Additional information about the issues to include in the response data. This parameter supports a comma-separated list. The available expand options include: renderfields names schema transitions editmeta changelog versionRepresentations (Note: When included in the request, the Fields parameter is ignored.) For more information about the expand parameter, see POST /rest/api/3/issue/bulk from Atlassian's documentation.	names,transitions

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Issue failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Jira portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Issue does not exist or you do not have permission to see it.

Error Sample Data

Get Issue failed.

Status Code: 404.

Message: Issue does not exist or you do not have permission to see it.

Get Issue Links

Returns all issue links of the specified issue.

READER NOTE

Issue Key is a required parameter to run this command.

Run the Search Issues command to obtain Issue Keys. Issue Key can be found in the returned raw data at the path $.issues[*].key. Ensure you have selected the provided JSON path. Note: There are other keys with the name "key".
If the command runs successfully with no results, your input issue may not have any existing links.

Input

Input Parameter	Required/Optional	Description	Example
Issue Key	Optional	The key of the issue is to return links. Issue keys can be obtained using the Search Issues command.	*****

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Issue Links failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Jira portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Issue does not exist or you do not have permission to see it.

Error Sample Data

Get Issue Links failed.

Status Code: 404.

Message: Issue does not exist or you do not have permission to see it.

List Transitions

Returns transition(s) that can be performed by the user on specific issues, dependent on the issues' statuses.

READER NOTE

This is not currently compatible with the version 3 of Jira's API. It is recommended to build a separate connection with API version 2 to use this command.
Input parameter Issue IDs or Keys is required to run this command.
- Run the Search Issues command to obtain Issue IDs or Keys. Issue Key can be found in the returned raw data at the path $.issues[*].key. There are other keys with the name "key". Ensure you have selected the provided JSON path. Issue IDs can be found in the returned raw data at the path $.issues[*].id.

Input

Input Parameter	Required/Optional	Description	Example
Issue IDs or Keys	Required	The IDs or keys of the issues to retrieve transitions. Issue IDs and keys can be obtained using the Search Issues command.	JSON `[ "*****" ]`

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Transitions failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Jira portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Issue does not exist or you do not have permission to see it.

Error Sample Data

List Transitions failed.

Status Code: 404.

Message: Issue does not exist or you do not have permission to see it.

Link Issues

Creates a link between two issues. Use this operation to indicate a relationship between two issues and optionally add a comment to the from (outward) issue.

READER NOTE

Issue linking must be enabled for this command to run. See Configure issue linking from Atlassian's documentation for more details.
First Issue Key, Second Issue Key and Link Description are required parameters to run this command.
- Run the Search Issues command to obtain Issue Keys. Issue Key can be found in the returned raw data at the path $.issues[*].key.
- The available link descriptions can be found by navigating to Settings > Issue Features > Issue Linking in the Jira web app.

Input

Input Parameter	Required/Optional	Description	Example
First Issue Key	Required	The key of the first issue to link from. Issue keys can be obtained using the Search Issues command.	*****
Link Description	Required	The link relationship between the two issues (e.g. blocks, is blocked by). The available link descriptions (Inward or Outward) can be found by navigating to Settings > Issues > Issue Linking in the Jira web app. Note: This parameter is case-sensitive.	blocks
Second Issue Key	Required	The key of the second issue to link to. Issue keys can be obtained using the Search Issues command.	*****
Comment	Optional	The comments to be added for the link.	Local-* blocks Local-*

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Link Issues failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Jira portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Issue does not exist or you do not have permission to see it.

Error Sample Data

Link Issues failed.

Status Code: 404.

Message: Issue does not exist or you do not have permission to see it.

List Fields

Returns all system and custom issue fields.

Input

N/A

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Fields failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Jira portal. Refer to the HTTP Status Code Registry for details.	Status Code: 401.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Unauthorized User.

Error Sample Data

List Fields failed.

Status Code: 401.

Message: Unauthorized User.

List Projects

Returns a list of projects visible to the user, sorted by project key.

Input

N/A

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Projects failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Jira portal. Refer to the HTTP Status Code Registry for details.	Status Code: 401.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Unauthorized User.

Error Sample Data

List Projects failed.

Status Code: 401.

Message: Unauthorized User.

Search Issues

Searches for issues in Jira using JQL. For more information about JQL search queries, see What is advanced searching in Jira Cloud?

Input

Input Parameter	Required /Optional	Description	Example
Filter	Optional	The JQL query string to return events. The commonly used syntax is <field> <operator> <value or function>. You may use the AND and OR operators between fields. See What is advanced searching in Jira Cloud? from Atlassian's documentation for more about JQL's syntax.	project=testProject and created > "2022-08-09" and assignee="*****"

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Search Issues failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Jira portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Error in the JQL Query.

Error Sample Data

Search Issues failed.

Status Code: 403.

Message: Error in the JQL Query.

Transition Issues

Performs a transition of the specified issue(s).

READER NOTE

This is not currently compatible with the version 3 of Jira's API. It is recommended to build a separate connection with API version 2 to use this command.
Issue IDs or Keys and Transition Name are required parameters to run this command.
- Run the Search Issues command to obtain Issue IDs or Keys. Issue Key can be found in the returned raw data at the path $.issues[*].key. Ensure you have selected the provided JSON path. Issue IDs can be found in the returned raw data at the path $.issues[*].id. Note: There are other keys with the name "key".
- Run the List Transitions command to obtain Transition Name. Transition Name can be found in the returned raw data at the path $.transitions[*].name.

Input

Input Parameter	Required/Optional	Description	Example
Issue IDs or Keys	Required	The ID or key of the issue to undertake transitions. Issue IDs and keys can be obtained using the Search Issues command.	JSON `[ "*****" ]`
Transition Name	Required	The name of the issue transition to apply (e.g. In Progress). Transition names can be obtained using the List Transitions command, or from the Jira console.	In Progress
Transition Fields	Optional	The JSON object containing the custom fields, sub-fields and the updated values for the issue.	JSON `{ "assignee": { "name": "bob" }, "resolution": { "name": "Fixed" } }`

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Transition Issues failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Jira portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Issue does not exist or you do not have permission to see it.

Error Sample Data

Transition Issues failed.

Status Code: 404.

Message: Issue does not exist or you do not have permission to see it.

Unlink Issues

Deletes the specified issue link(s).

READER NOTE

Input parameter Link IDs is required to run this command.

Run the Get Issue Links command to obtain Link IDs. Link IDs can be found in the returned raw data at the path $.fields.issuelinks[*].id.

Input

Input Parameter	Required /Optional	Description	Example
Link IDs	Required	The ID(s) of the link(s) to delete. Link IDs can be obtained using the Get Issue Links command.	JSON `[ "*****" ]`

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Unlink Issues failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Jira portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: No issue link with id '10051' exists.

Error Sample Data

Unlink Issues failed.

Status Code: 404.

Message: No issue link with id '10051' exists.

Upload Files To Issue

Adds one or more attachments to a specified issue.

READER NOTE

Issue Key is a required parameter to run this command.

Run the Search Issues command to obtain Issue Keys. Issue Key can be found in the returned raw data at the path $.issues[*].key. Ensure you have selected the provided JSON path. Note: There are other keys with the name "key".

File ID and File Source

It is not recommended to use the Test Command feature with the Upload File To Issue command as it is designed for dynamic input files in Playbooks, Incident Attachments, and Artifact Attachments. There is a simple workaround to test the command:

Navigate to Configuration on the top bar menu.
Click on Utility Commands on the left sidebar menu.
Use the search box to find and select the Create a File from input Text Array command.
Select the Test tab.
Input the required information for the parameters.
Click on the Test Command button. A D3 File ID will appear in the output data after the file has been successfully created. The D3 File Source of the created file will be Playbook File).

Input

Input Parameter	Required/Optional	Description	Example
Issue Key	Required	The key of the issue to upload attachments. Issue Key can be obtained using the Search Issues command.	*****
File IDs	Required	The file path of the file source.	JSON `[ "***", "***" ]`
File Source	Required	The source of the file to upload. The options for file sources are: Incident Attachment File: Manually uploaded file from Incident Playbook File: Output from another Task Artifact File: Ingested Artifact in an Event	Playbook File

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Upload Files To Issue failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Jira portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Issue does not exist or you do not have permission to see it.

Error Sample Data

Upload Files To Issue failed.

Status Code: 404.

Message: Issue does not exist or you do not have permission to see it.

Test Connection

Allows users to perform a health check on an integration connection. Users can schedule a periodic health check by selecting Connection Health Check when editing an integration connection.

Input

N/A

Output

Output Type

Description

Return Data Type

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

More details about an error can be viewed in the Error tab.

String

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Test Connection failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Jira portal. Refer to the HTTP Status Code Registry for details.	Status Code: 401.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Unauthorized User.

Error Sample Data

Test connection failed.

Status Code: 401.

Message: Unauthorized User.

FAQ

Why am I seeing the “Something went wrong” error when creating an OAuth connection in D3 SOAR?

You may not have enabled the necessary permission scopes for your Jira API app. See step 8 of OAuth 2.0 Authentication for instructions on enabling the required scopes.

Why does my connection no longer work?

The refresh token may expire after a certain period of time. Follow the setup instructions again starting from step 5 of Authentication Type: OAuth Authentication under Configuring D3 SOAR to Work with Jira to request a new refresh token.