Atlassian Jira Service Management

LAST UPDATED: OCT 23, 2024

Overview

Atlassian Jira Service Management empowers teams to deliver excellent service experiences with features such as self-service, automation, SLAs, and CSAT reporting.

D3 SOAR is providing REST operations to function with Atlassian Jira Service Management.

Atlassian Jira Service Management is available for use in:

D3 SOAR	V14.0.52.0+
Category	Case Management
Deployment Options	Option II, Option IV

Permission Requirements

Each endpoint in the Atlassian Jira Service Management API requires a certain permission scope. The following are required scopes for the commands in this integration:

Command	Required Permission
Create Request	write:servicedesk-request
Create Request Comment	write:servicedesk-request
Get Request	read:servicedesk-request
Get Transitions	read:servicedesk-request
List Requests	read:servicedesk-request
List Request Type	read:servicedesk-request
List Service Desk	read:servicedesk-request
Perform Transiton	write:servicedesk-request
Test Connection	N/A

Connection

To connect to Atlassian Jira Service Management from D3 SOAR, please follow this part to collect the required information below:

Parameter	Description	Example
Default
Authentication Method	The type for authentication. If you select OAuth Authentication, please ensure that your OAuth 2.0 integration app has the following Jira API permission classic scopes: read:servicedesk-request, write:servicedesk-request.	Basic Authentication
Basic Authentication
Server URL (domain level)	The server URL of the Jira instance.	https://team-*****.atlassian.net
User Name	The user name to establish the API connection.	***@*.***
API Token	The API Token for authentication.	*****
OAuth Authentication
Server URL (domain level)	The server URL of the Jira instance.	https://team-*****.atlassian.net
Client ID	The Client ID for authentication.	*****
Client Secret	The client secret for authentication.	*****
Authorization Code	The authorization code is used for the OAuth2.0 with the grant type of OAuth 2.0. Please click Get Authorization button on the Connection page to automatically generate an authorization code.	*****
Callback URL	The callback url is used for the OAuth2.0 with the grant type of OAuth 2.0. Please add this callback url on JIRA console according to the instructions.	https://***.***
Refresh Token	The refresh token is used for the OAuth2.0 with the grant type of OAuth 2.0. Please click Get Refresh Token button on the Connection page to automatically generate a refresh token.	*****

Configuring Atlassian Jira Service Management to Work With D3 SOAR

OAuth 2.0 Authentication

Log in to Jira (https://developer.atlassian.com/console/myapps/) with your credentials.
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), 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 in to Jira (https://id.atlassian.com/manage-profile/security/api-tokens) with your credentials.
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

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 Atlassian Jira Service Management

Log in to D3 SOAR.
Find the Atlassian Jira Service Management integration.
1. Navigate to Configuration on the top header menu.
2. Click on the Integration icon on the left sidebar.
3. Type Atlassian Jira Service Management in the search box to find the integration, then click it to select it.
4. Click New Connection, on the right side of the Connections section. A new connection window will appear.
Configure the following fields to create a connection to Atlassian Jira Service Management.
1. Connection Name: The desired name for the connection.
2. 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.
3. 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.
4. 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.
5. Description (Optional): Add your desired description for the connection.
6. Tenant (Optional): When configuring the connection from a master tenant site, you have the option to choose the specific tenant sites you want to share the connection with. Once you enable this setting, you 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: Check the tick box to ensure the connection is available for use.
9. System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.
  Authentication Type: Basic Authentication
  
  1. Select Basic Authentication.
  2. Input the server URL of your Jira Service Management instance.

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

3. Input your user name.

4. Input your API token.

Authentication Type: OAuth Authentication

1. Select OAuth Authentication.

2. Input the server URL of your Jira Service Management instance.

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

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

j. Connection Health Check: Updates the connection status you have created. A connection health check is done by scheduling the Test Connection command of this integration. This can only be done when the connection is active.

To set up a connection health check, check the Connection Health Check tickbox. You can customize the interval (minutes) for scheduling the health check. An email notification can be set up after a specified number of failed connection attempts.

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

a. 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 checkmark appear beside the Test Connection button. If the test connection fails, please check your connection parameters and try again.

b. Click OK to close the alert window.

c. Click + Add to create and add the configured connection.

Commands

Atlassian Jira Service Management 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 Atlassian Jira Service Management, please refer to the Atlassian Jira Service Management API reference.

READER NOTE

Certain permissions are required for each command. Please refer to the Permission Requirements and Configuring Atlassian Jira Service Management to Work with D3 SOAR for details.

Note for Time-related parameters

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.

Create Request

Creates a new request in Jira Service Management.

READER NOTE

Service Desk ID and Request Type ID are required parameters to run this command.

Run the List Service Desk command to obtain the Service Desk ID. Service Desk IDs can be found in the returned raw data at the path $.value.[*].id.
Run the List Request Type command to obtain the Request Type ID. Request Type IDs can be found in the returned raw data at the path $.value.[*].id.
The input Service Desk ID and Request Type ID must correspond to each other. Run the List Request Type command with a Service Desk ID and check the returned corresponding Request Type ID.

Input

Input Parameter	Required/Optional	Description	Example
Service Desk ID	Required	The ID of the service desk in which to create a new request. You can obtain the Service Desk ID using the List Service Desk command.	*****
Request Type ID	Required	The ID of the request type for the request. You can obtain the Request Type ID using the List Request Type command.	*****
Request Field Values	Required	The JSON-formatted request field values. Request field values are a map of Jira field IDs and their values. See Field input formats (The Jira Service Management Cloud REST API), for details of each field's JSON semantics and the values they can take.	JSON `{ "summary": "Request * **", "description": "I need a * *** * ** Mac" }`

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.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "_expands": [
        "participant",
        "status",
        "sla",
        "requestType",
        "serviceDesk",
        "attachment",
        "action",
        "comment"
    ],
    "issueId": "*****",
    "issueKey": "*****",
    "requestTypeId": "*****",
    "serviceDeskId": "*****",
    "createdDate": {
        "iso8601": "2022-12-07T21:26:25+0100",
        "jira": "2022-12-07T20:26:25.272+0000",
        "friendly": "Today 9:26 PM",
        "epochMillis": 1670444785272
    },
    "reporter": {
        "accountId": "*****",
        "emailAddress": "*****@*****.*****",
        "displayName": "D3 System Engineer Team",
        "active": true,
        "timeZone": "CET",
        "_links": {
            "jiraRest": "https://*****.*****",
            "avatarUrls": {
                "48x48": "https://*****.*****",
                "24x24": "https://*****.*****",
                "16x16": "https://*****.*****",
                "32x32": "https://*****.*****"
            },
            "self": "https://*****.*****"
        }
    },
    "requestFieldValues": [
        {
            "fieldId": "*****",
            "label": "Summary",
            "value": "Request IT help via REST"
        },
        {
            "fieldId": "*****",
            "label": "Description",
            "value": "I need a new mouse for my Mac",
            "renderedValue": {
                "html": "<p>I need a new mouse for my Mac</p>"
            }
        },
        {
            "fieldId": "*****",
            "label": "Attachment",
            "value": []
        }
    ],
    "currentStatus": {
        "status": "Waiting for support",
        "statusCategory": "INDETERMINATE",
        "statusDate": {
            "iso8601": "2022-12-07T21:26:25+0100",
            "jira": "2022-12-07T20:26:25.272+0000",
            "friendly": "Today 9:26 PM",
            "epochMillis": 1670444785272
        }
    },
    "_links": {
        "jiraRest": "https://*****.*****",
        "web": "https://*****.*****",
        "self": "https://*****.*****",
        "agent": "https://*****.*****"
    }
}

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

JSON

{
    "_expands": [
        "participant",
        "status",
        "sla",
        "requestType",
        "serviceDesk",
        "attachment",
        "action",
        "comment"
    ],
    "issueId": "*****",
    "issueKey": "*****",
    "requestTypeId": "*****",
    "serviceDeskId": "*****",
    "createdDate": {
        "iso8601": "2022-12-07T21:26:25+0100",
        "jira": "2022-12-07T20:26:25.272+0000",
        "friendly": "Today 9:26 PM",
        "epochMillis": 1670444785272
    },
    "reporter": {
        "accountId": "*****",
        "emailAddress": "*****@*****.*****",
        "displayName": "D3 System Engineer Team",
        "active": true,
        "timeZone": "CET",
        "_links": {
            "jiraRest": "https://*****.*****",
            "avatarUrls": {
                "48x48": "https://*****.*****",
                "24x24": "https://*****.*****",
                "16x16": "https://*****.*****",
                "32x32": "https://*****.*****"
            },
            "self": "https://*****.*****"
        }
    },
    "requestFieldValues": [
        {
            "fieldId": "*****",
            "label": "Summary",
            "value": "Request IT help via REST"
        },
        {
            "fieldId": "*****",
            "label": "Description",
            "value": "I need a new mouse for my Mac",
            "renderedValue": {
                "html": "<p>I need a new mouse for my Mac</p>"
            }
        },
        {
            "fieldId": "*****",
            "label": "Attachment",
            "value": []
        }
    ],
    "currentStatus": {
        "status": "Waiting for support",
        "statusCategory": "INDETERMINATE",
        "statusDate": {
            "iso8601": "2022-12-07T21:26:25+0100",
            "jira": "2022-12-07T20:26:25.272+0000",
            "friendly": "Today 9:26 PM",
            "epochMillis": 1670444785272
        }
    },
    "_links": {
        "jiraRest": "https://*****.*****",
        "web": "https://*****.*****",
        "self": "https://*****.*****",
        "agent": "https://*****.*****"
    }
}

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 error tab 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 Request 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 Atlassian Jira Service Management 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: The request type you are trying to view does not exist.

Error Sample Data

Create Request failed.

Status Code: 404.

Message: The request type you are trying to view does not exist.

Create Request Comment

Creates a public or private (internal) comment on a customer request, with the visibility set to public. The user will be recorded as the author of the comment. Attachment files can be added along with the comment.

READER NOTE

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

Run the List Requests command to obtain Issuer ID or Key. Issuer ID or Key can be found in the raw data at the path $.values.[*].issueId or $.values.[*].issueKey.

File ID and File Source

It is not recommended to use the Test Command feature with the Create Request Comment 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.
Click on 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 ID Or Key	Required	The ID or key of the customer request whose transitions will be retrieved. Issue ID Or Key can be obtained using List Requests command.	*****
Comment	Optional	The content of the comment.	Please find the screenshot and the log file attached.
Public	Optional	Controls whether the comment and its attachments are visible to customers.	True
File IDs	Optional	The file path of the file source to be added to the customer request.	JSON `[ "***", "***" ]`
File Source	Optional	The file 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

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

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "Result": {
        "comment": {
            "_expands": [
                "attachment",
                "renderedBody"
            ],
            "id": "*****",
            "body": "Please find the screenshot and the log file attached. !screenshot.png|thumbnail! [^log.txt] _(32 kB)_",
            "public": true,
            "author": {
                "accountId": "*****",
                "name": "*****",
                "key": "*****",
                "emailAddress": "*****@*****.*****",
                "displayName": "*****",
                "active": true,
                "timeZone": "Australia/Sydney",
                "_links": {
                    "jiraRest": "https://*****.*****:*****",
                    "avatarUrls": {
                        "16x16": "https://*****.*****",
                        "24x24": "https://*****.*****",
                        "32x32": "https://*****.*****",
                        "48x48": "https://*****.*****"
                    },
                    "self": "https://*****.*****"
                }
            },
            "created": {
                "epochMillis": 1444360920000,
                "friendly": "Today 10:22 AM",
                "iso8601": "2015-10-09T10:22:00+0700",
                "jira": "2015-10-09T10:22:00.000+0700"
            },
            "_links": {
                "self": "https://*****.*****"
            }
        },
        "attachments": {
            "_expands": [],
            "size": 2,
            "start": 2,
            "limit": 2,
            "isLastPage": false,
            "_links": {
                "base": "https://*****.*****",
                "context": "context",
                "next": "https://*****.*****",
                "prev": "https://*****.*****"
            },
            "values": [
                {
                    "filename": "screenshot.png",
                    "temporaryAttachmentIDs": "*****",
                    "author": {
                        "accountId": "*****",
                        "name": "*****",
                        "key": "*****",
                        "emailAddress": "*****@*****.*****",
                        "displayName": "*****",
                        "active": true,
                        "timeZone": "Australia/Sydney",
                        "_links": {
                            "jiraRest": "https://*****.*****",
                            "avatarUrls": {
                                "16x16": "https://*****.*****",
                                "24x24": "https://*****.*****",
                                "32x32": "https://*****.*****",
                                "48x48": "https://*****.*****"
                            },
                            "self": "https://*****.*****"
                        }
                    },
                    "created": {
                        "epochMillis": 1444360920000,
                        "friendly": "Today 10:22 AM",
                        "iso8601": "2015-10-09T10:22:00+0700",
                        "jira": "2015-10-09T10:22:00.000+0700"
                    },
                    "size": 23123,
                    "mimeType": "image/png",
                    "_links": {
                        "jiraRest": "https://*****.*****",
                        "content": "https://*****.*****",
                        "thumbnail": "https://*****.*****"
                    }
                },
                {
                    "filename": "log.txt",
                    "temporaryAttachmentIDs": "*****",
                    "author": {
                        "accountId": "*****",
                        "name": "*****",
                        "key": "*****",
                        "emailAddress": "*****@*****.*****",
                        "displayName": "*****",
                        "active": true,
                        "timeZone": "Australia/Sydney",
                        "_links": {
                            "jiraRest": "https://*****.*****",
                            "avatarUrls": {
                                "16x16": "https://*****.*****",
                                "24x24": "https://*****.*****",
                                "32x32": "https://*****.*****",
                                "48x48": "https://*****.*****"
                            },
                            "self": "https://*****.*****"
                        }
                    },
                    "created": {
                        "epochMillis": 1444360920000,
                        "friendly": "Today 10:22 AM",
                        "iso8601": "2015-10-09T10:22:00+0700",
                        "jira": "2015-10-09T10:22:00.000+0700"
                    },
                    "size": 32132,
                    "mimeType": "text/plain",
                    "_links": {
                        "jiraRest": "https://*****.*****",
                        "content": "https://*****.*****"
                    }
                }
            ]
        }
    }
}

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

JSON

{
      "CommentID": "*****", 
      "TemporaryAttachmentIDs": "*****", "*****",
      "FileNames":  "blueJay.png", "lakeLouise.jpg"
}

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 error tab 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 Request Comment 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 Atlassian Jira Service Management 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 ID Or Key Not Found.

Error Sample Data

Create Request Comment failed.

Status Code: 404.

Message: Issue ID Or Key Not Found.

Get Request

Returns all requests from the specified issuer.

READER NOTE

Issuer ID or Key is an optional parameter to run this command.

Run the List Requests command to obtain Issuer ID or Key. Issuer ID or Key can be found in the raw data at the path $.values.[*].issueId or $.values.[*].issueKey.
If no input parameters are defined, all requests will be returned.

Input

Input Parameter	Required/Optional	Description	Example
Issuer ID or Key	Required	The ID or key of the issuer to return requests for. You can obtain the Issuer ID or Key using the List Requests command.	*****

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.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "_expands": [
        "participant",
        "status",
        "sla",
        "requestType",
        "serviceDesk",
        "attachment",
        "action",
        "comment"
    ],
    "issueId": "*****",
    "issueKey": "ITSAMPLE-18",
    "requestTypeId": "*****",
    "serviceDeskId": "*****",
    "createdDate": {
        "iso8601": "2022-12-07T21:26:25+0100",
        "jira": "2022-12-07T20:26:25.272+0000",
        "friendly": "Today 9:26 PM",
        "epochMillis": 1670444785272
    },
    "reporter": {
        "accountId": "*****",
        "emailAddress": "*****@*****.*****",
        "displayName": "D3 System Engineer Team",
        "active": true,
        "timeZone": "CET",
        "_links": {
            "jiraRest": "https://*****.*****",
            "avatarUrls": {
                "48x48": "https://*****.*****",
                "24x24": "https://*****.*****",
                "16x16": "https://*****.*****",
                "32x32": "https://*****.*****"
            },
            "self": "https://*****.*****"
        }
    },
    "requestFieldValues": [
        {
            "fieldId": "*****",
            "label": "Summary",
            "value": "Request IT help via REST"
        },
        {
            "fieldId": "*****",
            "label": "Description",
            "value": "I need a new mouse for my Mac",
            "renderedValue": {
                "html": "<p>I need a new mouse for my Mac</p>"
            }
        },
        {
            "fieldId": "*****",
            "label": "Attachment",
            "value": []
        }
    ],
    "currentStatus": {
        "status": "Waiting for support",
        "statusCategory": "INDETERMINATE",
        "statusDate": {
            "iso8601": "2022-12-07T21:26:25+0100",
            "jira": "2022-12-07T20:26:25.272+0000",
            "friendly": "Today 9:26 PM",
            "epochMillis": 1670444785272
        }
    },
    "_links": {
        "jiraRest": "https://*****.*****",
        "web": "https://*****.*****",
        "self": "https://*****.*****",
        "agent": "https://*****.*****"
    }
}

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 error tab 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 Request 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 Atlassian Jira Service Management 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: Issuer ID or Key does not exist.

Error Sample Data

Get Request failed.

Status Code: 404.

Message: Issuer ID or Key does not exist.

Get Transitions

Returns a list of transitions that show users the actions they can take for each customer request. The command can take multiple requests and return transitions in a list. Note: "Show transition in the customer portal" must be selected for the transition to be retrieved by the customer.

READER NOTE

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

Run the List Requests command to obtain Issuer ID or Key. Issuer ID or Keys can be found in the raw data at the path $.values.[*].issueId or $.values.[*].issueKey.

Input

Input Parameter	Required/Optional	Description	Example
Issuer ID or Key	Required	The IDs or keys of the customer request whose transitions will be retrieved. Issuer ID or Key can be obtained using List Requests command.	JSON `[ "***", "***" ]`

Output

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

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "Results": [
        {
            "_expands": [],
            "issueIDOrKey": "*****",
            "size": 2,
            "start": 2,
            "limit": 2,
            "isLastPage": false,
            "_links": {
                "base": "https://*****.*****",
                "context": "context",
                "next": "https://*****.*****",
                "prev": "https://*****.*****"
            },
            "values": [
                {
                    "id": "*****",
                    "name": "Close Request"
                },
                {
                    "id": "*****",
                    "name": "Escalate Request"
                }
            ]
        },
        {
            "_expands": [],
            "issueIDOrKey": "*****",
            "size": 2,
            "start": 2,
            "limit": 2,
            "isLastPage": false,
            "_links": {
                "base": "https://your-domain.atlassian.net/rest/servicedeskapi",
                "context": "context",
                "next": "https://*****.*****",
                "prev": "https://*****.*****"
            },
            "values": [
                {
                    "id": "*****",
                    "name": "Close Request"
                },
                {
                    "id": "*****",
                    "name": "Escalate Request"
                }
            ]
        }
    ]
}

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

JSON

{
    "issueIDOrKeys": "*****", "*****" 
}

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 error tab 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 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 Atlassian Jira Service Management 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: Issuer ID or Key does not exist.

Error Sample Data

Get Transitions failed.

Status Code: 404.

Message: Issuer ID or Key does not exist.

List Requests

Returns a list of all requests.

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.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "_expands": [
        "participant",
        "status",
        "sla",
        "requestType",
        "serviceDesk",
        "attachment",
        "action",
        "comment"
    ],
    "size": 3,
    "start": 0,
    "limit": 50,
    "isLastPage": true,
    "_links": {
        "self": "https://*****.*****",
        "base": "https://*****.*****",
        "context": ""
    },
    "values": [
        {
            "_expands": [
                "participant",
                "status",
                "sla",
                "requestType",
                "serviceDesk",
                "attachment",
                "action",
                "comment"
            ],
            "issueId": "*****",
            "issueKey": "*****",
            "requestTypeId": "*****",
            "serviceDeskId": "*****",
            "createdDate": {
                "iso8601": "2022-12-07T21:26:25+0100",
                "jira": "2022-12-07T20:26:25.272+0000",
                "friendly": "Today 9:26 PM",
                "epochMillis": 1670444785272
            },
            "reporter": {
                "accountId": "*****",
                "emailAddress": "*****@*****.*****",
                "displayName": "D3 System Engineer Team",
                "active": true,
                "timeZone": "CET",
                "_links": {
                    "jiraRest": "https://****.*****",
                    "avatarUrls": {
                        "48x48": "https://****.*****",
                        "24x24": "https://****.*****",
                        "16x16": "https://****.*****",
                        "32x32": "https://****.*****"
                    },
                    "self": "https://****.*****"
                }
            },
            "requestFieldValues": [
                {
                    "fieldId": "*****",
                    "label": "Summary",
                    "value": "Request IT help via REST"
                },
                {
                    "fieldId": "*****",
                    "label": "Description",
                    "value": "I need a new mouse for my Mac",
                    "renderedValue": {
                        "html": "<p>I need a new mouse for my Mac</p>"
                    }
                },
                {
                    "fieldId": "*****",
                    "label": "Attachment",
                    "value": []
                }
            ],
            "currentStatus": {
                "status": "Waiting for support",
                "statusCategory": "INDETERMINATE",
                "statusDate": {
                    "iso8601": "2022-12-07T21:26:25+0100",
                    "jira": "2022-12-07T20:26:25.272+0000",
                    "friendly": "Today 9:26 PM",
                    "epochMillis": 1670444785272
                }
            },
            "_links": {
                "jiraRest": "https://****.*****",
                "web": "https://****.*****",
                "self": "https://****.*****",
                "agent": "https://****.*****"
            }
        },
        {
            "_expands": [
                "participant",
                "status",
                "sla",
                "requestType",
                "serviceDesk",
                "attachment",
                "action",
                "comment"
            ],
            "issueId": "*****",
            "issueKey": "*****",
            "requestTypeId": "*****",
            "serviceDeskId": "*****",
            "createdDate": {
                "iso8601": "2022-12-07T21:01:42+0100",
                "jira": "2022-12-07T20:01:42.268+0000",
                "friendly": "Today 9:01 PM",
                "epochMillis": 1670443302268
            },
            "reporter": {
                "accountId": "*****",
                "emailAddress": "*****@*****.*****",
                "displayName": "D3 System Engineer Team",
                "active": true,
                "timeZone": "CET",
                "_links": {
                    "jiraRest": "https://****.*****",
                    "avatarUrls": {
                        "48x48": "https://****.*****",
                        "24x24": "https://****.*****",
                        "16x16": "https://****.*****",
                        "32x32": "https://****.*****"
                    },
                    "self": "https://****.*****"
                }
            },
            "requestFieldValues": [
                {
                    "fieldId": "*****",
                    "label": "Summary",
                    "value": "Request IT help help via REST"
                },
                {
                    "fieldId": "*****",
                    "label": "Description",
                    "value": "I need a new mouse for my Mac",
                    "renderedValue": {
                        "html": "<p>I need a new mouse for my Mac</p>"
                    }
                },
                {
                    "fieldId": "*****",
                    "label": "Attachment",
                    "value": []
                }
            ],
            "currentStatus": {
                "status": "Waiting for support",
                "statusCategory": "INDETERMINATE",
                "statusDate": {
                    "iso8601": "2022-12-07T21:01:42+0100",
                    "jira": "2022-12-07T20:01:42.268+0000",
                    "friendly": "Today 9:01 PM",
                    "epochMillis": 1670443302268
                }
            },
            "_links": {
                "jiraRest": "https://****.*****",
                "web": "https://****.*****",
                "self": "https://****.*****",
                "agent": "https://****.*****"
            }
        },
        {
            "_expands": [
                "participant",
                "status",
                "sla",
                "requestType",
                "serviceDesk",
                "attachment",
                "action",
                "comment"
            ],
            "issueId": "*****",
            "issueKey": "*****",
            "requestTypeId": "*****",
            "serviceDeskId": "*****",
            "createdDate": {
                "iso8601": "2022-12-07T19:15:17+0100",
                "jira": "2022-12-07T18:15:17.156+0000",
                "friendly": "Today 7:15 PM",
                "epochMillis": 1670436917156
            },
            "reporter": {
                "accountId": "*****",
                "emailAddress": "*****@*****.*****",
                "displayName": "D3 System Engineer Team",
                "active": true,
                "timeZone": "CET",
                "_links": {
                    "jiraRest": "https://****.*****",
                    "avatarUrls": {
                        "48x48": "https://****.*****",
                        "24x24": "https://****.*****",
                        "16x16": "https://****.*****",
                        "32x32": "https://****.*****"
                    },
                    "self": "https://****.*****"
                }
            },
            "requestFieldValues": [
                {
                    "fieldId": "*****",
                    "label": "Summary",
                    "value": "Request JSD help via REST"
                },
                {
                    "fieldId": "*****",
                    "label": "Description",
                    "value": "I need a new *mouse* for my Mac",
                    "renderedValue": {
                        "html": "<p>I need a new <b>mouse</b> for my Mac</p>"
                    }
                },
                {
                    "fieldId": "*****",
                    "label": "Attachment",
                    "value": []
                }
            ],
            "currentStatus": {
                "status": "Waiting for support",
                "statusCategory": "INDETERMINATE",
                "statusDate": {
                    "iso8601": "2022-12-07T19:15:17+0100",
                    "jira": "2022-12-07T18:15:17.156+0000",
                    "friendly": "Today 7:15 PM",
                    "epochMillis": 1670436917156
                }
            },
            "_links": {
                "jiraRest": "https://****.*****",
                "web": "https://****.*****",
                "self": "https://****.*****",
                "agent": "https://****.*****"
            }
        }
    ]
}

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

SAMPLE DATA

JSON

[
    {
        "_expands": [
            "participant",
            "status",
            "sla",
            "requestType",
            "serviceDesk",
            "attachment",
            "action",
            "comment"
        ],
        "issueId": "*****",
        "issueKey": "*****",
        "requestTypeId": "*****",
        "serviceDeskId": "*****",
        "createdDate": {
            "iso8601": "2022-12-07T21:26:25+0100",
            "jira": "2022-12-07T20:26:25.272+0000",
            "friendly": "Today 9:26 PM",
            "epochMillis": 1670444785272
        },
        "reporter": {
            "accountId": "*****",
            "emailAddress": "*****@*****.*****",
            "displayName": "D3 System Engineer Team",
            "active": true,
            "timeZone": "CET",
            "_links": {
                "jiraRest": "https://*****.*****",
                "avatarUrls": {
                    "48x48": "https://*****.*****",
                    "24x24": "https://*****.*****",
                    "16x16": "https://*****.*****",
                    "32x32": "https://*****.*****"
                },
                "self": "https://*****.*****"
            }
        },
        "requestFieldValues": [
            {
                "fieldId": "*****",
                "label": "Summary",
                "value": "Request IT help via REST"
            },
            {
                "fieldId": "*****",
                "label": "Description",
                "value": "I need a new mouse for my Mac",
                "renderedValue": {
                    "html": "&lt;p&gt;I need a new mouse for my Mac&lt;/p&gt;"
                }
            },
            {
                "fieldId": "*****",
                "label": "Attachment",
                "value": []
            }
        ],
        "currentStatus": {
            "status": "Waiting for support",
            "statusCategory": "INDETERMINATE",
            "statusDate": {
                "iso8601": "2022-12-07T21:26:25+0100",
                "jira": "2022-12-07T20:26:25.272+0000",
                "friendly": "Today 9:26 PM",
                "epochMillis": 1670444785272
            }
        },
        "_links": {
            "jiraRest": "https://*****.*****",
            "web": "https://*****.*****",
            "self": "https://*****.*****",
            "agent": "https://*****.*****"
        }
    },
    {
        "_expands": [
            "participant",
            "status",
            "sla",
            "requestType",
            "serviceDesk",
            "attachment",
            "action",
            "comment"
        ],
        "issueId": "*****",
        "issueKey": "*****",
        "requestTypeId": "*****",
        "serviceDeskId": "*****",
        "createdDate": {
            "iso8601": "2022-12-07T21:01:42+0100",
            "jira": "2022-12-07T20:01:42.268+0000",
            "friendly": "Today 9:01 PM",
            "epochMillis": 1670443302268
        },
        "reporter": {
            "accountId": "*****",
            "emailAddress": "*****@*****.*****",
            "displayName": "D3 System Engineer Team",
            "active": true,
            "timeZone": "CET",
            "_links": {
                "jiraRest": "https://*****.*****",
                "avatarUrls": {
                    "48x48": "https://*****.*****",
                    "24x24": "https://*****.*****",
                    "16x16": "https://*****.*****",
                    "32x32": "https://*****.*****"
                },
                "self": "https://*****.*****"
            }
        },
        "requestFieldValues": [
            {
                "fieldId": "*****",
                "label": "Summary",
                "value": "Request IT help help via REST"
            },
            {
                "fieldId": "*****",
                "label": "Description",
                "value": "I need a new mouse for my Mac",
                "renderedValue": {
                    "html": "&lt;p&gt;I need a new mouse for my Mac&lt;/p&gt;"
                }
            },
            {
                "fieldId": "*****",
                "label": "Attachment",
                "value": []
            }
        ],
        "currentStatus": {
            "status": "Waiting for support",
            "statusCategory": "INDETERMINATE",
            "statusDate": {
                "iso8601": "2022-12-07T21:01:42+0100",
                "jira": "2022-12-07T20:01:42.268+0000",
                "friendly": "Today 9:01 PM",
                "epochMillis": 1670443302268
            }
        },
        "_links": {
            "jiraRest": "https://*****.*****",
            "web": "https://*****.*****",
            "self": "https://*****.*****",
            "agent": "https://*****.*****"
        }
    },
    {
        "_expands": [
            "participant",
            "status",
            "sla",
            "requestType",
            "serviceDesk",
            "attachment",
            "action",
            "comment"
        ],
        "issueId": "*****",
        "issueKey": "*****",
        "requestTypeId": "*****",
        "serviceDeskId": "*****",
        "createdDate": {
            "iso8601": "2022-12-07T19:15:17+0100",
            "jira": "2022-12-07T18:15:17.156+0000",
            "friendly": "Today 7:15 PM",
            "epochMillis": 1670436917156
        },
        "reporter": {
            "accountId": "*****",
            "emailAddress": "*****@*****.*****",
            "displayName": "D3 System Engineer Team",
            "active": true,
            "timeZone": "CET",
            "_links": {
                "jiraRest": "https://*****.*****",
                "avatarUrls": {
                    "48x48": "https://*****.*****",
                    "24x24": "https://*****.*****",
                    "16x16": "https://*****.*****",
                    "32x32": "https://*****.*****"
                },
                "self": "https://*****.*****"
            }
        },
        "requestFieldValues": [
            {
                "fieldId": "*****",
                "label": "Summary",
                "value": "Request JSD help via REST"
            },
            {
                "fieldId": "*****",
                "label": "Description",
                "value": "I need a new *mouse* for my Mac",
                "renderedValue": {
                    "html": "&lt;p&gt;I need a new &lt;b&gt;mouse&lt;/b&gt; for my Mac&lt;/p&gt;"
                }
            },
            {
                "fieldId": "*****",
                "label": "Attachment",
                "value": []
            }
        ],
        "currentStatus": {
            "status": "Waiting for support",
            "statusCategory": "INDETERMINATE",
            "statusDate": {
                "iso8601": "2022-12-07T19:15:17+0100",
                "jira": "2022-12-07T18:15:17.156+0000",
                "friendly": "Today 7:15 PM",
                "epochMillis": 1670436917156
            }
        },
        "_links": {
            "jiraRest": "https://*****.*****",
            "web": "https://*****.*****",
            "self": "https://*****.*****",
            "agent": "https://*****.*****"
        }
    }
]

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 error tab 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 Requests 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 Atlassian Jira Service Management 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: serverurl is invalid because it contains potentially dangerous HTML markup or JavaScript code.

Error Sample Data

List Requests failed.

Status Code: 403.

Message: serverurl is invalid because it contains potentially dangerous HTML markup or JavaScript code.

List Request Type

Retrieves all customer request types from a service desk.

READER NOTE

Service Desk ID is a required parameter to run this command.

Run the List Service Desk command to obtain the Service Desk ID. Service Desk IDs can be found in the returned raw data at the path $.value.[*].id.

Input

Input Parameter	Required/Optional	Description	Example
Service Desk ID	Required	The ID of the service desk to retrieve customer request types. You can obtain the Service Desk ID using the List Service Desk command.	*****

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.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "_expands": [
        "field"
    ],
    "size": 16,
    "start": 0,
    "limit": 50,
    "isLastPage": true,
    "_links": {
        "self": "https://*****.*****",
        "base": "https://*****.*****",
        "context": ""
    },
    "values": [
        {
            "_expands": [
                "field"
            ],
            "id": "*****",
            "_links": {
                "self": "https://*****.*****"
            },
            "name": "Fix an account problem",
            "description": "Having trouble accessing certain websites or systems? We'll help you out.",
            "helpText": "",
            "issueTypeId": "*****",
            "serviceDeskId": "*****",
            "portalId": "*****",
            "groupIds": [
                "*****"
            ],
            "icon": {
                "id": "*****",
                "_links": {
                    "iconUrls": {
                        "48x48": "https://*****.*****",
                        "24x24": "https://*****.*****",
                        "16x16": "https://*****.*****",
                        "32x32": "https://*****.*****"
                    }
                }
            }
        },
        {
            "_expands": [
                "field"
            ],
            "id": "*****",
            "_links": {
                "self": "https://*****.*****"
            },
            "name": "Get a guest wifi account",
            "description": "Raise a request to ask for temp wifi access for guests.",
            "helpText": "",
            "issueTypeId": "*****",
            "serviceDeskId": "*****",
            "portalId": "*****",
            "groupIds": [
                "*****"
            ],
            "icon": {
                "id": "*****",
                "_links": {
                    "iconUrls": {
                        "48x48": "https://*****.*****",
                        "24x24": "https://*****.*****",
                        "16x16": "https://*****.*****",
                        "32x32": "https://*****.*****"
                    }
                }
            }
        },
        {
            "_expands": [
                "field"
            ],
            "id": "*****",
            "_links": {
                "self": "https://*****.*****"
            },
            "name": "Get IT help",
            "description": "Get assistance for general IT problems and questions.",
            "helpText": "",
            "issueTypeId": "*****",
            "serviceDeskId": "*****",
            "portalId": "*****",
            "groupIds": [
                "*****",
                "*****"
            ],
            "icon": {
                "id": "*****",
                "_links": {
                    "iconUrls": {
                        "48x48": "https://*****.*****",
                        "24x24": "https://*****.*****",
                        "16x16": "https://*****.*****",
                        "32x32": "https://*****.*****"
                    }
                }
            }
        }
    ]
}

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

SAMPLE DATA

JSON

[
    {
        "_expands": [
            "field"
        ],
        "id": "*****",
        "_links": {
            "self": "https://*****.*****"
        },
        "name": "Fix an account problem",
        "description": "Having trouble accessing certain websites or systems? We'll help you out.",
        "helpText": "",
        "issueTypeId": "*****",
        "serviceDeskId": "*****",
        "portalId": "*****",
        "groupIds": [
            "*****"
        ],
        "icon": {
            "id": "*****",
            "_links": {
                "iconUrls": {
                    "48x48": "https://*****.*****",
                    "24x24": "https://*****.*****",
                    "16x16": "https://*****.*****",
                    "32x32": "https://*****.*****"
                }
            }
        }
    },
    {
        "_expands": [
            "field"
        ],
        "id": "*****",
        "_links": {
            "self": "https://*****.*****"
        },
        "name": "Get a guest wifi account",
        "description": "Raise a request to ask for temp wifi access for guests.",
        "helpText": "",
        "issueTypeId": "*****",
        "serviceDeskId": "*****",
        "portalId": "*****",
        "groupIds": [
            "*****"
        ],
        "icon": {
            "id": "*****",
            "_links": {
                "iconUrls": {
                    "48x48": "https://*****.*****",
                    "24x24": "https://*****.*****",
                    "16x16": "https://*****.*****",
                    "32x32": "https://*****.*****"
                }
            }
        }
    },
    {
        "_expands": [
            "field"
        ],
        "id": "*****",
        "_links": {
            "self": "https://*****.*****"
        },
        "name": "Get IT help",
        "description": "Get assistance for general IT problems and questions.",
        "helpText": "",
        "issueTypeId": "*****",
        "serviceDeskId": "*****",
        "portalId": "*****",
        "groupIds": [
            "*****",
            "*****"
        ],
        "icon": {
            "id": "*****",
            "_links": {
                "iconUrls": {
                    "48x48": "https://*****.*****",
                    "24x24": "https://*****.*****",
                    "16x16": "https://*****.*****",
                    "32x32": "https://*****.*****"
                }
            }
        }
    }
]

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 error tab 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 Request Type 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 Atlassian Jira Service Management 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: Service Desk ID Not Found.

Error Sample Data

List Request Type failed.

Status Code: 404.

Message: Service Desk ID Not Found.

List Service Desk

Retrieves all service desks in the Jira Service Management instance. The scope of this command is defined by the access rights of the user account that was used to set up the 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.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "size": 2,
    "start": 0,
    "limit": 50,
    "isLastPage": true,
    "_links": {
        "self": "https://*****.*****",
        "base": "https://*****.*****",
        "context": ""
    },
    "values": [
        {
            "id": "*****",
            "projectId": "*****",
            "projectName": "ITSM project-A",
            "projectKey": "*****",
            "_links": {
                "self": "https://*****.*****"
            }
        },
        {
            "id": "*****",
            "projectId": "*****",
            "projectName": "ITSM sample space",
            "projectKey": "*****",
            "_links": {
                "self": "https://*****.*****"
            }
        }
    ]
}

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

SAMPLE DATA

JSON

[
    {
        "id": "*****",
        "projectId": "*****",
        "projectName": "ITSM project-A",
        "projectKey": "*****",
        "_links": {
            "self": "https://*****.*****"
        }
    },
    {
        "id": "*****",
        "projectId": "*****",
        "projectName": "ITSM sample space",
        "projectKey": "*****",
        "_links": {
            "self": "https://*****.*****"
        }
    }
]

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 error tab 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 Service Desk 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 Atlassian Jira Service Management 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: serverurl is invalid because it contains potentially dangerous HTML markup or JavaScript code

Error Sample Data

List Service Desk failed.

Status Code: 403.

Message: serverurl is invalid because it contains potentially dangerous HTML markup or JavaScript code

Perform Transition

Performs a customer transition for a given request and transition.

READER NOTE

Issue ID Or Key and Transition ID are required parameters to run this command.

Run the List Requests command to obtain Issuer ID Or Key. Issuer ID or Keys can be found in the raw data at the path $.values.[*].issueId or $.values.[*].issueKey.
Run the Get Transitions command to obtain Transition IDs. Transition IDs can be found in the returned raw data at the path $.Results[*].values[*].

Input

Input Parameter	Required/Optional	Description	Example
Issue ID Or Key	Required	The ID or key of the request whose transitions will be retrieved. Issuer ID or Key can be obtained using List Requests command.	*****
Transition ID	Required	The ID of the transition to be performed. Transition IDs can be obtained using the Get Transitions Command.	*****
Comment	Optional	The comment explaining the reason for the transition.	Problem has been fixed.

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.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE

No Sample Data

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 error tab 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.	Perform Transition 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 Atlassian Jira Service Management 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 ID Or Key Not Found.

Error Sample Data

Perform Transition failed.

Status Code: 404.

Message: Issue ID Or Key Not Found.

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.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Error Handling

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

The error tab contains the responses from the 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. Failed to check the connector.
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 Atlassian Jira Service Management 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: serverurl is invalid because it contains potentially dangerous HTML markup or JavaScript code.

Error Sample Data

Test Connection failed. Failed to check the connector.

Status Code: 403.

Message: serverurl is invalid because it contains potentially dangerous HTML markup or JavaScript code.