Your add-on can make 500 API requests per 5 minutes. Once you exceed the limit, calls will return HTTP status 429 and a message displaying that the limit has been reached.
The authorization code for OAuth2.0 authentication. Click the "Get Authorization" button on the Connection page to automatically generate an authorization code.
ucFDLlzx5*****************cHe8CPdIuM
Callback URL
The callback URL for OAuth2.0 authentication. See step 10 of OAuth 2.0 Authentication for more information.
https://d3pocsite/VSOC/Auth2Callback.aspx
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.
v1.M********************************Shp0
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 your use case.
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 Authenticationunder 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.
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
You will only be able to view the API token once upon its creation. Store it in a secure location for future reference.
Creating a User
See Invite a user from Atlassian Support for instructions.
Setup Time Zone
Login your Jira instance with the account that VSOC uses for authentication. Click your account icon on the top right corner, then click Manage account.
Click Account preferences on the left side, then under Time zone click the current time zone; in the dropdown list, select UTC. This account which VSOC uses to connect to your JIRA instance will use UTC as its time zone.
Configuring D3 SOAR to Work with Jira
Log in to D3 SOAR.
Find the Jira integration.
Navigate to Configuration on the top header menu.
Click on the Integration icon on the left sidebar.
Type Jira in the search box to find the integration, then click it to select it.
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.
Connection Name: The desired name for the connection.
Site: Specifies the site to use the integration connection. Use the drop-down menu to select the site. The Share to Internal Sites option enables all sites defined as internal sites to use the connection. Selecting a specific site will only enable that site to use the connection.
Recipient site for events from connections Shared to Internal Sites: This field appears if you selected Share to Internal Sites for Site to let you select the internal site to deploy the integration connection.
Agent Name (Optional): Specifies 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.
Description (Optional): Add your desired description for the connection.
Configure User Permissions: Defines which users have access to the connection.
Active: Check the tick box to ensure the connection is available for use.
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 your Jira instance. Note: If you do not know your server URL, log in to Atlassian Admin (https://admin.atlassian.com/) with admin credentials. A list of all organizations will appear. Select the desired organization to see the associated Atlassian products with their respective server URLs.
2. Select Basic Authentication. 3. Input your Jira user name. 4. Input your 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. Note: The Get Issue, List Transitions, and Transition Issue commands are not currently compatible with the version 3 of Jira's API. If you need to use those commands, it is recommended to build a separate connection with API version 2.
Authentication Type: OAuth Authentication
1. Input the server URL of your Jira instance. Note: If you do not know your server URL, log in to Atlassian Admin (https://admin.atlassian.com/) with admin credentials. A list of all organizations will appear. Select the desired organization to see the associated Atlassian products with their respective server URLs.
2. Input the saved Client ID (refer to step 11 of OAuth 2.0 Authentication). 3. Input the saved Client Secret (refer to step 11 of OAuth 2.0 Authentication). 4. Copy the D3 Callback URL, and paste it into Jira's Authentication page (refer to step 10 of OAuth 2.0 Authentication). 5. Click Get Authorization. You will 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. Return to D3 SOAR. Click Get Refresh Token. The refresh token and authentication code will be automatically generated and entered into the corresponding parameters. 7. Input the API version to use for the connection. The default API version is 3. Note: The Get Issue, List Transitions, and Transition Issue commands are not currently compatible with the version 3 of Jira's API. If you need to use those commands, it is recommended to build a separate connection with API version 2.
Enable Password Vault: An optional feature that allows users to take the stored credentials from their own password vault. Please refer to the password vault connection guide if needed.
Test the connection.
Click Test Connection to verify the account credentials and network connection. If the Test Connection Passed alert window appears, the test connection is successful. You will see Passed with a green checkmarkappear beside the Test Connection button. If the test connection fails, please check your connection parameters and try again.
Click OK to close the alert window.
Click +Add to create and add the configured connection.
Commands
Jira includes the following executable commands for users to set up schedules or create playbook workflows. With the Test Command, you can execute these commands independently for playbook troubleshooting.
Integration API Note
For more information about the Jira API, please refer to the Jira API reference.
The input format of time-related parameters may vary based on your account settings. As a result, the sample data provided in our commands is different from what you see. To set your preferred time format, follow these steps:
Navigate to Configuration > Application Settings. Select Date/Time Format.
Choose your desired date and time format.
After that, you will be able to view your preferred time format when configuring the DateTime input parameters for commands.
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.
[ "1***7" ]
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.
Comment test808a.
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".
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
SAMPLE DATA
CODE
No Sample Data
Key Fields
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
SAMPLE DATA
CODE
No Sample Data
Key Fields
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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 permissionbut 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 parametersto 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.
[ "***" ]
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.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
D3 customizes the Context Data by extracting the data from path $.AssignIssue in API returned JSON.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
SAMPLE DATA
CODE
{
"IssueKeys": [
"***"
]
}
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
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Result
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
ISSUEKEY
STATUS
SELECTEDACCOUNT
MATCHEDACCOUNTS
Successful
62***d5
['62***d5']
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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 parametersto 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.
LOCAL
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.
test@exaplme.com
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.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
SAMPLE DATA
CODE
No Sample Data
Key Fields
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
SAMPLE DATA
CODE
{
"IssueId": 1***7,
"IssueKey": "***"
}
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
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Result
Provides a brief summary of outputs in an HTML formatted table.
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
SAMPLE DATA
CODE
No Sample Data
Key Fields
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
SAMPLE DATA
CODE
{
"IssueKeys": [
"***"
]
}
Return Data
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command's input accepts an array of items (e.g. an array of issue keys) and one or more items within the array return an error from the API request.
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
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Result
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
ISSUEKEY
RESULT
Issue: *** was deleted successfully.
Error Handling
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
SAMPLE DATA
CODE
No Sample Data
Key Fields
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
SAMPLE DATA
CODE
{
"FileIDs": [
"***"
]
}
Return Data
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command's input accepts an array of items (e.g. an array of issue keys) and one or more items within the array return an error from the API request.
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
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Result
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
FILEID
FILENAME
MD5
SHA1
SHA256
lakeLouise.jpg
035***5A
A8D***8B
BC***75C
Error Handling
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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.
epic test\n*BOLD*\n{color:#ff5630}red{color}
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.
test@example.com
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.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
SAMPLE DATA
CODE
No Sample Data
Key Fields
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
SAMPLE DATA
CODE
{
"ID": [
"***"
],
"IssueKey": "***"
}
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
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Result
Provides a brief summary of outputs in an HTML formatted table.
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
D3 customizes the Context Data by extracting the data from path $.issues in API returned JSON.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
Please note that Fetch Event commands require event field mapping. Field mapping plays a key role in the data normalization process part of the event pipeline. Field mapping converts the original data fields from the different providers to the D3 fields which are standardized by the D3 Model. Please refer to Event and Incident Intake Field Mapping for details.
If you require a custom field mapping, click +Add Field to add a custom field mapping. You may also remove built-in field mappings by clicking x. Please note that two underscore characters will automatically prefix the defined Field Name as the System Name for a custom field mapping. Additionally, if an input Field Name contains any spaces, they will automatically be replaced with underscores for the corresponding System Name.
As a system integration, the Jira integration has some pre-configured field mappings for default field mapping.
Default Event Source The Default Event Source is the default set of field mappings that are applied when this fetch event command is executed. For out-of-the-box integrations, you will find a set of field mapping provided by the system. Default event source provides field mappings for common fields from fetched events. The default event source has a "Main Event JSON Path" (i.e., $.issues) that is used to extract a batch of events from the response raw data. Click Edit Event Source to view the "Main Event JSON Path".
Main Event JSON Path: $.issues The Main Event JSON Path determines the root path where the system starts parsing raw response data into D3 event data. The JSON path begins with $, representing the root element. The path is formed by appending a sequence of child elements to $, each separated by a dot (.). Square brackets with nested quotation marks ([‘...']) should be used to separate child elements in JSON arrays. For example, the root node of a JSON Path is issues. The child node denoting the Original event ID field would be id. Putting it together, the JSON Path 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 errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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.
[ "test@example.com" ]
Output
Raw Data
The primary response data from the API request.
SAMPLE DATA
JSON
{
"users": [
{
"accountId": "***",
"accountType": "atlassian",
"html": "D3 System Engineer Team - test@example.com",
"displayName": "D3 System Engineer Team"
}
]
}
Key Fields
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
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
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Result
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
users
{'accountId': '***', 'accountType': 'atlassian', 'html': 'D3 System Engineer Team - test@example.com', 'displayName': 'D3 System Engineer Team'}
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
SAMPLE DATA
CODE
No Sample Data
Key Fields
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
SAMPLE DATA
CODE
{
"IssueKeys": [
"***"
]
}
Return Data
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command's input accepts an array of items (e.g. an array of issue keys) and one or more items within the array return an error from the API request.
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
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Result
Provides a brief summary of outputs in an HTML formatted table.
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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
Raw Data
The primary response data from the API request.
SAMPLE DATA
JSON
Jira_getCreateMeta_raw_sample.json
Context Data
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
D3 customizes the Context Data by extracting the data from path $.projects in API returned JSON.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
SAMPLE DATA
CODE
Jira_getCreateMeta_context_sample.json
Key Fields
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
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
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Result
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
CODE
No Sample Data
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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.
[ "***" ]
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
Raw Data
The primary response data from the API request.
SAMPLE DATA
JSON
Jira_getIssue_v2_raw_sample.json
Context Data
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
SAMPLE DATA
CODE
No Sample Data
Key Fields
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
SAMPLE DATA
CODE
{
"IssueId": ***,
"IssueKey": "***"
}
Return Data
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command's input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
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
You can view more details about an error in the Error tab. Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Result
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
CODE
No Sample Data
Error Handling
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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 parameterto 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.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
D3 customizes the Context Data by extracting the data from path $.fields.issuelinks in API returned JSON.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
SAMPLE DATA
CODE
No Sample Data
Key Fields
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
SAMPLE DATA
CODE
{
"IssueKeys": [
"***"
]
}
Return Data
Indicates one of the possible command execution states: Successful, PartiallySuccessful, or Failed.
The Partially Successful state only occurs when a command's input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
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
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Result
Provides a brief summary of outputs in an HTML formatted table.
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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 parametersto 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.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
D3 customizes the Context data by extarcting $.issuelinks from the returned raw data.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command's input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
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
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Result
Provides a brief summary of outputs in an HTML formatted table.
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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.
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
D3 customizes the Context Data by extracting the data from path $.values in API returned JSON.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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.
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
Raw Data
The primary response data from the API request.
SAMPLE DATA
JSON
No Sample Data
Context Data
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
D3 customizes the Context Data by extracting the data from path $.issues[*].fields in API returned JSON.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
SAMPLE DATA
CODE
No Sample Data
Key Fields
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
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
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Result
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
CODE
No Sample Data
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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 parametersto 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.
[ "***" ]
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.
{
"assignee": {
"name": "bob"
},
"resolution": {
"name": "Fixed"
}
}
Output
Raw Data
The primary response data from the API request.
SAMPLE DATA
JSON
[
{
"expand": "renderedFields,names,schema,operations,editmeta,changelog,versionedRepresentations",
"id": "***",
"self": "https://api.atlassian.com/ex/jira/***-**-***-***-***/rest/api/3/issue/***",
"key": "***",
"fields": {
"status": {
"self": "https://api.atlassian.com/ex/jira/***-**-***-***-***/rest/api/3/status/3",
"description": "This issue is being actively worked on at the moment by the assignee.",
"iconUrl": "https://team-***.atlassian.net/images/icons/statuses/inprogress.png",
"name": "In Progress",
"id": "3",
"statusCategory": {
"self": "https://api.atlassian.com/ex/jira/***-**-***-***-***/rest/api/3/statuscategory/4",
"id": 4,
"key": "indeterminate",
"colorName": "yellow",
"name": "In Progress"
}
}
}
}
]
Context Data
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
SAMPLE DATA
CODE
No Sample Data
Key Fields
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command's input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
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
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Result
Provides a brief summary of outputs in an HTML formatted table.
{'status': {'self': 'https://api.atlassian.com/ex/jira/***-**-***-***-***/rest/api/3/status/3', 'description': 'This issue is being actively worked on at the moment by the assignee.', 'iconUrl': 'https://team-***.atlassian.net/images/icons/statuses/inprogress.png', 'name': 'In Progress', 'id': '3', 'statusCategory': {'self': 'https://api.atlassian.com/ex/jira/***-**-***-***-***a/rest/api/3/statuscategory/4', 'id': 4, 'key': 'indeterminate', 'colorName': 'yellow', 'name': 'In Progress'}}}
Error Handling
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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.
[ "***" ]
Output
Raw Data
The primary response data from the API request.
SAMPLE DATA
JSON
{
"***": {
"status": "Successful"
}
}
Context Data
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
SAMPLE DATA
CODE
No Sample Data
Return Data
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command's input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
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
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Result
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
10015
{'status': 'Successful'}
Error Handling
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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 parameterto 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".
It is not recommended to use the Test Command feature with the Submit Sample Files 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:
In D3 SOAR, navigate to Configuration on the top bar menu.
Click 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, then input the required information for the parameters. Click Test Command. A D3 File ID will appear in the output data after the file has been successfully created. (Note: 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.
[ "750", "751" ]
File Source
Required
The source of the file to upload. The options for file sources are:
Incident Attachment File: Manually uploaded file from Incident
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
SAMPLE DATA
CODE
No Sample Data
Key Fields
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command's input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
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
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Result
Provides a brief summary of outputs in an HTML formatted table.
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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 you to perform a health check on an integration connection. You can schedule a periodic health check by selecting Connection Health Check when editing an integration connection.
Input
N/A
Output
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
You can view more details about an error in the Error tab.
SAMPLE DATA
CODE
Successful
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you 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 Authenticationunder Configuring D3 SOAR to Work with Jira to request a new refresh token.
JavaScript errors detected
Please note, these errors can depend on your browser setup.
If this problem persists, please contact our support.
