Zendesk

LAST UPDATED: 06/17/2024

Overview

Zendesk Support allows users to create, track, prioritize and manage service tickets for customer support services. D3 SOAR’s integration with Zendesk can help clients automate processes such as creating and managing tickets and users. For example, agents can manage and respond to tickets from any source, including help center request forms, emails, text chat, mobile phones, and social media platforms.

D3 SOAR is providing REST operations to function with Zendesk.

Zendesk is available for use in:

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

Known Limitations

The Zendesk API is rate limited. Only allow a certain number of requests per minute depending on your plan and the endpoint. If a request exceeds this limit, you'll get a 429 status code, and the remaining request will need to be retried later.

Plan	Requests per minute
Essential (legacy)	10
Team	200
Professional	400
Enterprise	700

Endpoints	Rate Limit
Create or Update User	5 requests per minute
List Tickets	50 requests per minute where num is over 500
List Users	100 requests per minute where num is over 10,000
Update Ticket	30 requests per 10 mins per user 100 requests per min per account 300 requests per min per account with the High Volume API add-on

READER NOTE

For more information about Zendesk’s API usage limits, please refer to Rate limits | Zendesk Developer Docs.

Connection

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

Parameter	Description	Example
Default
Server URL	The server URL of the Zendesk instance.	https://***.zendesk.com/***
Authentication Type	The authentication type to use for the connection. The authentication options are Password and API token.	Password
Authentication Type : Password
Username	The user name used to establish the API connection.	*****@d3security.com
Password	The password to authenticate the API connection. This parameter only applies if the selected authentication type is password.	*****
API Version	The version of the API to use for the connection.	V2
Authentication Type : API Token
Username	The user name used to establish the API connection.	*****@d3security.com
API Token	The API token to authenticate the API connection. This parameter only applies if the selected authentication type is API token.	*****
API Version	The version of the API to use for the connection.	V2

Permission Requirements

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

Command	Required Permission
Command	User Type	Product	User type = Staff member Roles (from least to all access right)
Add Comment	Staff member	Support	Contributor, Light Agent, Agent, Administrator
Assign User To Ticket	Staff member	Support	Agent, Administrator
Create or Update User	Staff member	Support	Administrator
Create Ticket	Staff member	Support	Contributor, Light Agent, Agent, Administrator
Fetch Event	Staff member	Support	Contributor, Light Agent, Agent, Administrator
Get Tickets Details	Staff member	Support	Contributor, Light Agent, Agent, Administrator
List Tickets	Staff member	Support	Contributor, Light Agent, Agent, Administrator
List Users	Staff member	Support	Contributor, Light Agent, Agent, Administrator
Update Ticket	Staff member	Support	Contributor, Light Agent, Agent, Administrator
Upload File To Ticket	Staff member	Support	Contributor, Light Agent, Agent, Administrator
List Organizations	Staff member	Support	Contributor, Light Agent, Agent, Administrator
Update Organization	Staff member	Support	Agent, Administrator Note: Agents with no permissions restrictions can only update "notes" on organizations.
Get Users By Organization	Staff member	Support	Contributor, Light Agent, Agent, Admin
List Groups	Staff member	Support	Contributor, Light Agent, Agent, Admin
Test Connection	Staff member	Support	Contributor, Light Agent, Agent, Administrator

As Zendesk is using role-based access control (RBAC), the API access token is generated based on a specific user account and the application. Therefore, the command permissions are inherited from the user account’s role. Users need to configure their user profile from the Zendesk console for each command in this integration.

READER NOTE

Zendesk’s default user profiles and their allowed permissions are as follows:

User type: Staff member and Product: Support
- Contributors: Can provide limited support.
- Light Agents: Can view and add private comments to Zendesk tickets.
- Agents: Can edit Zendesk tickets from the groups that they belong to.
- Administrators: Can manage all settings, except billing.
User type: End User
- End users are also referred to as customers. They generate support requests from any of the available support channels. End users do not have access to any of the administrator and agent features of Zendesk Support. They can only submit and track tickets and communicate with agents publicly. Ticket comments made by end users are never private.
- An end user account cannot be used for building connections, but can be used in some integration command parameters (e.g., the Create or Update User commands). You can select End User for the user type.

See Understanding Zendesk Support user roles from Zendesk’s documentation for more information on user roles.

Zendesk Support has two types of user roles with differentiated permissions. End users, sometimes referred to as customers, have limited permissions that allow them to generate support requests and communicate with support agents. Staff members (also denoted as team members on Zendesk’s user interface) have different levels of permissions to resolve support requests and manage admin settings. This section will provide instructions on creating both types of user roles from the Zendesk Support platform. See Understanding Zendesk Support user roles from Zendesk’s documentation for more information on user roles.

Configuring Zendesk to Work with D3 SOAR

Adding a New End User

Log in to Zendesk Support with your credentials.
Hover over the + Add tab in the top toolbar and select User.
The Add new user window will appear. Select End user for User Type. Enter the user’s Name and Email.
Click Add.
The created user’s profile will open. Input the additional information for the user.

READER NOTE

This section was written based on the Zendesk Support as of November 2022. For the most up to date instructions, see Adding end users from Zendesk help.

Adding a New Staff Member

Log in to Zendesk Support with admin credentials.
Access the Admin Center. Click the Zendesk Products icon in the top bar, then select Admin Center.
In the Admin Center, click People on the sidebar, then select Teams > Team members.
The Team Members page will open. Click Add team member.
Enter the new user’s Name and Email. Click Next.
In the Assign role section, select the user’s role using the dropdown list. Click Save. The new user is saved and receives a welcome email and link to sign in.
(Optional) Open the user's profile that appears at the top of the list on the Team members page to set any additional roles.

READER NOTE

This section was written based on the Zendesk Support as November 2022. For the most up-to-date instructions, see Adding agents and admins from Zendesk help.

Setting Up the Zendesk API Access

Log in to Zendesk Support (https://www.zendesk.com/login/#login) with admin credentials. You will need to input your Zendesk subdomain and password.
After logging in, copy and save the domain portion of the URL ([subdomain].zendesk.com). It will be used as the Server URL for building an integration connection in D3 SOAR. See the screenshot below for reference.
Click the Zendesk Products icon in the top bar, then select Admin Center.
In the Admin Center, click Apps and integrations on the sidebar, then select APIs > Zendesk API.
In the Zendesk API Settings tab, enable Password Access and/or Token access based on your use case. This is the authentication type you will use o build the integration connection in D3 SOAR.

READER NOTE

If you will solely use password access to authenticate the API connection, you will not need to follow the steps below on creating an API token.

To create a new API token, click Add API token. You may input an API token description. Click Copy to copy the API token. After you have saved the token, click Save.

WARNING

You will not be able to view the API token after you click Save or leave the page. Make sure you copy and save the API token in a secure location. It is required to build the integration connection in D3 SOAR.

Configuring D3 SOAR to Work with Zendesk

Log in to D3 SOAR.
Find the Zendesk integration.
1. Navigate to Configuration on the top header menu.
2. Click on the Integration icon on the left sidebar.
3. Type Zendesk 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 Zendesk.
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. Configure User Permissions: Defines which users have access to the connection.
7. Active: Check the tick box to ensure the connection is available for use.
8. System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.
  Authenticating with Password
  1. Server URL (domain level): Input the server URL saved from step 2 of Setting Up the Zendesk API Access.
  2. Authentication Type: Select Password from the dropdown list.
  3. Username: Input the Zendesk username of the account used to set up the Zendesk API access.
  4. Password: Input the Zendesk login password of the account.
  5. API version: Input the API version used for the connection. The default version is v2.
  Authenticating with API Token
  1. Server URL (domain level): Input the server URL saved from step 2 of Setting Up the Zendesk API Access.
  2. Authentication Type: Select API token from the dropdown list
  3. Username: Input the Zendesk username used to generate the API token.
  4. API Token: Input the API token saved from step 6 of Setting Up the Zendesk API Access.
  5. API version: Input the API version used for the connection. The default version is v2.
9. 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.
10. 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.
1. 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.
2. Click OK to close the alert window.
3. Click + Add to create and add the configured connection.

Commands

Zendesk 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 Zendesk API, please refer to the Zendesk API reference.

READER NOTE

Certain permissions are required for each command. Please refer to the Permission Requirements and Configuring Zendesk 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.

Add Comment

Adds a comment to the specified ticket.

READER NOTE

Ticket ID is a required parameter to run this command.

Run the List Tickets command to obtain the Ticket ID. Ticket IDs can be found in the raw data at the path $.tickets[*].id.
If the Ticket ID you have entered does not exist, no new ticket will be created. D3 SOAR will return an error about the Ticket ID not found and no comments will be added to valid tickets.

Input

Input Parameter	Required/Optional	Description	Example
Ticket ID	Required	The ID of the ticket to add a comment. The ticket ID can be obtained using the List Tickets command.	*****
Comment	Required	The comment text to add to the ticket.	Hello, World!
Is Public	Optional	Sets whether the comment is public. The default value is True. See Adding comments to tickets from Zendesk help for more about the visibility of public and private comments.	False

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

{
    "ticket": {
        "url": "https://*****.zendesk.com/*****",
        "id": *****,
        "external_id": null,
        "via": {
            "channel": "api",
            "source": {
                "from": {},
                "to": {},
                "rel": null
            }
        },
        "created_at": "2021-11-05T18:33:01Z",
        "updated_at": "2021-11-05T22:02:08Z",
        "type": null,
        "subject": "Pizza Lunch 1105ff",
        "raw_subject": "Pizza Lunch 1105ff",
        "description": "The Pizza is Yummy.1105ff",
        "priority": "low",
        "status": "open",
        "recipient": null,
        "requester_id": *****,
        "submitter_id": *****,
        "assignee_id": *****,
        "organization_id": null,
        "group_id": *****,
        "collaborator_ids": [],
        "follower_ids": [],
        "email_cc_ids": [],
        "forum_topic_id": null,
        "problem_id": null,
        "has_incidents": false,
        "is_public": true,
        "due_at": null,
        "tags": [],
        "custom_fields": [],
        "satisfaction_rating": null,
        "sharing_agreement_ids": [],
        "fields": [],
        "followup_ids": [],
        "ticket_form_id": *****,
        "brand_id": *****,
        "allow_channelback": false,
        "allow_attachments": true
    },
    "audit": {
        "id": *****,
        "ticket_id": *****,
        "created_at": "2021-11-05T22:02:08Z",
        "author_id": *****,
        "metadata": {
            "system": {
                "client": "PostmanRuntime/7.28.3",
                "ip_address": "***.***.***.***",
                "location": "Vancouver, BC, Canada",
                "latitude": 49.25*****,
                "longitude": -123.0972
            },
            "custom": {}
        },
        "events": [
            {
                "id": *****,
                "type": "Comment",
                "author_id": *****,
                "body": "hello, world. 1103ii Good Afternoon!",
                "html_body": "<div class=\"zd-comment\" dir=\"auto\"><p dir=\"auto\">hello, world. 1103ii Good Afternoon!</p></div>",
                "plain_body": "hello, world. 1103ii Good Afternoon!",
                "public": false,
                "attachments": [],
                "audit_id": *****
            }
        ],
        "via": {
            "channel": "api",
            "source": {
                "from": {},
                "to": {},
                "rel": null
            }
        }
    }
}

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

{
    "url": "https://*****.zendesk.com/*****",
    "id": *****,
    "external_id": null,
    "via": {
        "channel": "api",
        "source": {
            "from": {},
            "to": {},
            "rel": null
        }
    },
    "created_at": "2021-11-05T18:33:01Z",
    "updated_at": "2021-11-05T22:02:08Z",
    "type": null,
    "subject": "Pizza Lunch 1105ff",
    "raw_subject": "Pizza Lunch 1105ff",
    "description": "The Pizza is Yummy.1105ff",
    "priority": "low",
    "status": "open",
    "recipient": null,
    "requester_id": *****,
    "submitter_id": *****,
    "assignee_id": *****,
    "organization_id": null,
    "group_id": *****,
    "collaborator_ids": [],
    "follower_ids": [],
    "email_cc_ids": [],
    "forum_topic_id": null,
    "problem_id": null,
    "has_incidents": false,
    "is_public": true,
    "due_at": null,
    "tags": [],
    "custom_fields": [],
    "satisfaction_rating": null,
    "sharing_agreement_ids": [],
    "fields": [],
    "followup_ids": [],
    "ticket_form_id": *****,
    "brand_id": *****,
    "allow_channelback": false,
    "allow_attachments": true
}

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

{
  "TicketID": *****
}

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

url	https://***.zendesk.com/***
id	*****
external_id	None
via	{'channel': 'api', 'source': {'from': {}, 'to': {}, 'rel': None}}
created_at	2021-11-05T18:33:01Z
updated_at	2021-11-05T22:02:08Z
type	None
subject	Pizza Lunch 1105ff
raw_subject	Pizza Lunch 1105ff
description	The Pizza is Yummy.1105ff
priority	low
status	open
recipient	None
requester_id	*****
submitter_id	*****
assignee_id	*****
organization_id	None
group_id	*****
collaborator_ids	[]
follower_ids	[]
email_cc_ids	[]
forum_topic_id	None
problem_id	None
has_incidents	False
is_public	True
due_at	None
tags	[]
custom_fields	[]
satisfaction_rating	None
sharing_agreement_ids	[]
fields	[]
followup_ids	[]
ticket_form_id	*****
brand_id	*****
allow_channelback	False
allow_attachments	True

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.	Add 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 Zendesk 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: Didn’t find a record for this Ticket ID.

Error Sample Data

Add Comment failed.

Status Code: 404.

Message: Didn’t find a record for this Ticket ID.

Create or Update User

Creates or updates a Zendesk user. If the input user email does not exist, a new user will be created; if the input user email exists, the existing user will be updated.

READER NOTE

Before creating new users, remember to check the number of available seats. Users with admin or agent roles are included in the support seat count. If you exceed the maximum number of seats, an error will return. See Managing agent seats for Support from Zendesk help for more information.
The system will not return any alerts or error messages if the user already exists. You will only be able to update the existing user using this command.
Inputting an email address of an existing user will update the user with the input values of other parameters.
If a user has been assigned to tickets, the user cannot be updated using Light User and End User roles.
For User Role, in Zendesk API, role property only accepts three possible values: "end-user", "agent", and "admin". D3 adds “custom_role_id” to get a Light-agent option.
- There are two user types: End User and Staff member. Agent, Admin and Light Agent belong to the Staff member user type. The Zendesk API groups them together under User Role, while you can distinguish them from the Zendesk UI.

Input

Input Parameter	Required/Optional	Description	Example
Name	Required	The name of the user. Spaces, special characters and numbers are supported.	Support
Email	Required	The email address of the user. Input email addresses must be valid.	support@test.com
Role	Optional	The role of the user. The possible input values are End User, Agent, Admin and Light Agent. The default value is End User.	Agent

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

{
    "user": {
        "id": *****,
        "url": "https://*****.zendesk.com/*****",
        "name": "support",
        "email": "*****@*****.***",
        "created_at": "2021-11-05T22:28:22Z",
        "updated_at": "2021-11-05T22:28:22Z",
        "time_zone": "America/Vancouver",
        "iana_time_zone": "America/Vancouver",
        "phone": null,
        "shared_phone_number": null,
        "photo": null,
        "locale_id": *****,
        "locale": "en-US",
        "organization_id": null,
        "role": "end-user",
        "verified": false,
        "external_id": null,
        "tags": [],
        "alias": null,
        "active": true,
        "shared": false,
        "shared_agent": false,
        "last_login_at": null,
        "two_factor_auth_enabled": false,
        "signature": null,
        "details": null,
        "notes": null,
        "role_type": null,
        "custom_role_id": null,
        "moderator": false,
        "ticket_restriction": "requested",
        "only_private_comments": false,
        "restricted_agent": true,
        "suspended": false,
        "default_group_id": null,
        "report_csv": false,
        "user_fields": {}
    }
}

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

{
    "id": *****,
    "url": "https://*****.zendesk.com/*****",
    "name": "support",
    "email": "*****@*****.***",
    "created_at": "2021-11-05T22:28:22Z",
    "updated_at": "2021-11-05T22:28:22Z",
    "time_zone": "America/Vancouver",
    "iana_time_zone": "America/Vancouver",
    "phone": null,
    "shared_phone_number": null,
    "photo": null,
    "locale_id": *****,
    "locale": "en-US",
    "organization_id": null,
    "role": "end-user",
    "verified": false,
    "external_id": null,
    "tags": [],
    "alias": null,
    "active": true,
    "shared": false,
    "shared_agent": false,
    "last_login_at": null,
    "two_factor_auth_enabled": false,
    "signature": null,
    "details": null,
    "notes": null,
    "role_type": null,
    "custom_role_id": null,
    "moderator": false,
    "ticket_restriction": "requested",
    "only_private_comments": false,
    "restricted_agent": true,
    "suspended": false,
    "default_group_id": null,
    "report_csv": false,
    "user_fields": {}
}

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

{
  "UserID": *****,
  "EmailAddress": "*****@*****.***",
  "UserName": "support",
  "UserRole": "end-user"
}

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

id	*****
url	https://***.zendesk.com/***
name	support
email	***@*.*
created_at	2021-11-05T22:28:22Z
updated_at	2021-11-05T22:28:22Z
time_zone	America/Vancouver
iana_time_zone	America/Vancouver
phone	None
shared_phone_number	None
photo	None
locale_id	*****
locale	en-US
organization_id	None
role	end-user
verified	False
external_id	None
tags	[]
alias	None
active	True
shared	False
shared_agent	False
last_login_at	None
two_factor_auth_enabled	False
signature	None
details	None
notes	None
role_type	None
custom_role_id	None
moderator	False
ticket_restriction	requested
only_private_comments	False
restricted_agent	True
suspended	False
default_group_id	None
report_csv	False
user_fields	{}

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 or Update 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 Zendesk 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: Couldn't authenticate you.

Error Sample Data

Create or Update User failed.

Status Code: 401.

Message: Couldn't authenticate you.

Assign User To Ticket

Assigns a user to the specified ticket.

READER NOTE

User Email and Ticket ID are required parameters to run this command.

Run the List Users command to obtain the User Email. User Email can be found in the raw data at the path $.users[*].email.
Run the List Tickets command to obtain the ticket ID. Ticket IDs can be found in the raw data at the path $.tickets[*].id.
You may assign a user to the same ticket, or to different tickets.

Input

Input Parameter

Required/Optional

Description

Example

User Email

Required

The email address of the user. You can obtain user email addresses from the List Users command.

Note: Users with the End User or Light Agent roles cannot be assigned to tickets.

*****@d3soar.com

Ticket ID

Required

The ID of the ticket to assign the user to. Ticket IDs can be obtained using the List Tickets 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

{
    "ticket": {
        "url": "https://*****.zendesk.com/*****",
        "id": *****,
        "external_id": null,
        "via": {
            "channel": "api",
            "source": {
                "from": {},
                "to": {},
                "rel": null
            }
        },
        "created_at": "2021-11-05T18:33:01Z",
        "updated_at": "2021-11-05T22:52:49Z",
        "type": null,
        "subject": "Pizza Lunch 1105ff",
        "raw_subject": "Pizza Lunch 1105ff",
        "description": "The Pizza is Yummy.1105ff",
        "priority": "low",
        "status": "open",
        "recipient": null,
        "requester_id": *****,
        "submitter_id": *****,
        "assignee_id": *****,
        "organization_id": null,
        "group_id": *****,
        "collaborator_ids": [],
        "follower_ids": [],
        "email_cc_ids": [],
        "forum_topic_id": null,
        "problem_id": null,
        "has_incidents": false,
        "is_public": true,
        "due_at": null,
        "tags": [],
        "custom_fields": [],
        "satisfaction_rating": null,
        "sharing_agreement_ids": [],
        "fields": [],
        "followup_ids": [],
        "ticket_form_id": *****,
        "brand_id": *****,
        "allow_channelback": false,
        "allow_attachments": true
    },
    "audit": {
        "id": *****,
        "ticket_id": *****,
        "created_at": "2021-11-05T22:52:49Z",
        "author_id": *****,
        "metadata": {
            "system": {
                "client": "PostmanRuntime/7.28.3",
                "ip_address": "***.***.***.***",
                "location": "Vancouver, BC, Canada",
                "latitude": 49.25*****,
                "longitude": -123.0972
            },
            "custom": {}
        },
        "events": [
            {
                "id": *****,
                "type": "Comment",
                "author_id": *****,
                "body": "Assign ticket ***** to the *****@*****.***.",
                "html_body": "<div class=\"zd-comment\" dir=\"auto\"><p dir=\"auto\">Assign ticket ***** to the <a href=\"mailto:*****@*****.***\" rel=\"noreferrer\">*****@*****.***</a>.</p></div>",
                "plain_body": "Assign ticket ***** to the *****@*****.***.",
                "public": true,
                "attachments": [],
                "audit_id": *****
            },
            {
                "id": *****,
                "type": "Change",
                "value": "*****",
                "field_name": "assignee_id",
                "previous_value": "*****"
            },
            {
                "id": *****,
                "type": "Notification",
                "via": {
                    "channel": "rule",
                    "source": {
                        "from": {
                            "deleted": false,
                            "title": "Notify assignee of assignment",
                            "id": *****
                        },
                        "rel": "trigger"
                    }
                },
                "subject": "[{{ticket.account}}] Assignment: {{ticket.title}}",
                "body": "You have been assigned to this ticket (#{{ticket.id}}).\n\n{{ticket.comments_formatted}}",
                "recipients": [
                    *****
                ]
            },
            {
                "id": *****,
                "type": "Notification",
                "via": {
                    "channel": "rule",
                    "source": {
                        "from": {
                            "deleted": false,
                            "title": "Notify requester and CCs of comment update",
                            "id": *****
                        },
                        "rel": "trigger"
                    }
                },
                "subject": "[{{ticket.account}}] Re: {{ticket.title}}",
                "body": "Your request ({{ticket.id}}) has been updated. To add additional comments, reply to this email.\n{{ticket.comments_formatted}}",
                "recipients": [
                    *****
                ]
            }
        ],
        "via": {
            "channel": "api",
            "source": {
                "from": {},
                "to": {
                    "name": "*****",
                    "address": "*****@*****.***"
                },
                "rel": null
            }
        }
    }
}

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

{
    "url": "https://*****.zendesk.com/*****",
    "id": *****,
    "external_id": null,
    "via": {
        "channel": "api",
        "source": {
            "from": {},
            "to": {},
            "rel": null
        }
    },
    "created_at": "2021-11-05T18:33:01Z",
    "updated_at": "2021-11-05T22:52:49Z",
    "type": null,
    "subject": "Pizza Lunch 1105ff",
    "raw_subject": "Pizza Lunch 1105ff",
    "description": "The Pizza is Yummy.1105ff",
    "priority": "low",
    "status": "open",
    "recipient": null,
    "requester_id": *****,
    "submitter_id": *****,
    "assignee_id": *****,
    "organization_id": null,
    "group_id": *****,
    "collaborator_ids": [],
    "follower_ids": [],
    "email_cc_ids": [],
    "forum_topic_id": null,
    "problem_id": null,
    "has_incidents": false,
    "is_public": true,
    "due_at": null,
    "tags": [],
    "custom_fields": [],
    "satisfaction_rating": null,
    "sharing_agreement_ids": [],
    "fields": [],
    "followup_ids": [],
    "ticket_form_id": *****,
    "brand_id": *****,
    "allow_channelback": false,
    "allow_attachments": true
}

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

{
  "AssigneeID": *****
}

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

url	https://***.zendesk.com/***
id	*****
external_id	None
via	{'channel': 'api', 'source': {'from': {}, 'to': {}, 'rel': None}}
created_at	2021-11-05T18:33:01Z
updated_at	2021-11-05T22:52:49Z
type	None
subject	Pizza Lunch 1105ff
raw_subject	Pizza Lunch 1105ff
description	The Pizza is Yummy.1105ff
priority	low
status	open
recipient	None
requester_id	*****
submitter_id	*****
assignee_id	*****
organization_id	None
group_id	*****
collaborator_ids	[]
follower_ids	[]
email_cc_ids	[]
forum_topic_id	None
problem_id	None
has_incidents	False
is_public	True
due_at	None
tags	[]
custom_fields	[]
satisfaction_rating	None
sharing_agreement_ids	[]
fields	[]
followup_ids	[]
ticket_form_id	*****
brand_id	*****
allow_channelback	False
allow_attachments	True

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.	Assign User To Ticket 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 Zendesk 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: Can not find the user by email.

Error Sample Data

Assign User To Ticket failed.

Status Code: 404.

Message: Can not find the user by email.

Create Ticket

Creates a new ticket.

READER NOTE

The created ticket will be unassigned by default. If the Requester Email parameter is not defined, the creator account’s (the account used to authenticate and build the integration connection) email address will be used by default.
Priority, Type and Tags are optional parameters for this command.
- If the Priority and Type parameters are not defined, no default values will be used. The corresponding field of the ticket will be empty.
- If the input or default Requester Email belongs to an organization, the corresponding organization tags will be added to the created ticket.

Input

Input Parameter	Required/Optional	Description	Example
Description	Required	The description of the ticket.	I'm sending this email to report an issue regarding setting up the new product. Please help troubleshoot.
Subject	Optional	The subject of the ticket. If no subject is entered, the description will be used as the subject.	Product Setup Issue
Priority	Optional	The priority level of the ticket. The valid priorities are Urgent, High, Normal and Low.	Normal
Type	Optional	The type of the ticket. The valid types are Problem, Incident, Question, and Task.	Incident
Tags	Optional	The tags to add to the ticket. Any organization tags from the requester’s organization will be inherited by default.	[ "tag1", "tag2" ]
Requester Email	Optional	The email address of the user requesting the ticket. Requester emails can be obtained using the List Users command. Note: If this parameter is not defined, the creator account’s (the account used to authenticate and build the integration connection) email address will be used by default.	*****@d3security.com
Assignee Email	Optional	The email address of the assigned user. Assignee emails can be obtained using the List Users command. If this parameter is not defined, an unassigned ticket will be created. Note: Users with the End User or Light Agent roles cannot be the assignee.	*****@d3soar.com
Additional Fields	Optional	The additional fields to add to the ticket in JSON format. See Tickets from Zendesk Developer Docs for a list of valid fields to add. Note: If the input additional fields include description, subject, raw_subject, priority, type, tags, requester and assignee_email fields, they will overwrite the corresponding input parameters for this command.	{ "recipient": "*****@security.com" }

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

{
    "ticket": {
        "url": "https://*****.zendesk.com/*****",
        "id": *****,
        "external_id": null,
        "via": {
            "channel": "api",
            "source": {
                "from": {},
                "to": {},
                "rel": null
            }
        },
        "created_at": "2022-02-04T01:34:24Z",
        "updated_at": "2022-02-04T01:34:24Z",
        "type": "task",
        "subject": "Pizza Yummy",
        "raw_subject": "Pizza Yummy",
        "description": "start working",
        "priority": "normal",
        "status": "open",
        "recipient": null,
        "requester_id": *****,
        "submitter_id": *****,
        "assignee_id": *****,
        "organization_id": *****,
        "group_id": *****,
        "collaborator_ids": [],
        "follower_ids": [],
        "email_cc_ids": [],
        "forum_topic_id": null,
        "problem_id": null,
        "has_incidents": false,
        "is_public": true,
        "due_at": null,
        "tags": [
            "installation"
        ],
        "custom_fields": [],
        "satisfaction_rating": null,
        "sharing_agreement_ids": [],
        "fields": [],
        "followup_ids": [],
        "ticket_form_id": *****,
        "brand_id": *****,
        "allow_channelback": false,
        "allow_attachments": true
    },
    "audit": {
        "id": *****,
        "ticket_id": *****,
        "created_at": "2022-02-04T01:34:24Z",
        "author_id": *****,
        "metadata": {
            "system": {
                "client": "PostmanRuntime/7.29.0",
                "ip_address": "***.***.***.***",
                "location": "Vancouver, BC, Canada",
                "latitude": 49.25*****,
                "longitude": -123.0972
            },
            "custom": {}
        },
        "events": [
            {
                "id": *****,
                "type": "Comment",
                "author_id": *****,
                "body": "start working",
                "html_body": "<div class=\"zd-comment\" dir=\"auto\"><p dir=\"auto\">start working</p></div>",
                "plain_body": "start working",
                "public": true,
                "attachments": [],
                "audit_id": *****
            },
            {
                "id": *****,
                "type": "Create",
                "value": "*****",
                "field_name": "assignee_id"
            },
            {
                "id": *****,
                "type": "Create",
                "value": "normal",
                "field_name": "priority"
            },
            {
                "id": *****,
                "type": "Create",
                "value": "*****",
                "field_name": "requester_id"
            },
            {
                "id": *****,
                "type": "Create",
                "value": "Pizza Yummy",
                "field_name": "subject"
            },
            {
                "id": *****,
                "type": "Create",
                "value": [
                    "installation"
                ],
                "field_name": "tags"
            },
            {
                "id": *****,
                "type": "Create",
                "value": "task",
                "field_name": "type"
            },
            {
                "id": *****,
                "type": "Create",
                "value": "open",
                "field_name": "status"
            },
            {
                "id": *****,
                "type": "Create",
                "value": "*****",
                "field_name": "group_id"
            },
            {
                "id": *****,
                "type": "Create",
                "value": "*****",
                "field_name": "organization_id"
            },
            {
                "id": *****,
                "type": "Create",
                "value": "*****",
                "field_name": "brand_id"
            },
            {
                "id": *****,
                "type": "Create",
                "value": "*****",
                "field_name": "ticket_form_id"
            },
            {
                "id": *****,
                "type": "Notification",
                "via": {
                    "channel": "rule",
                    "source": {
                        "from": {
                            "deleted": false,
                            "title": "Notify all agents of received request",
                            "id": *****
                        },
                        "rel": "trigger"
                    }
                },
                "subject": "[{{ticket.account}}] {{ticket.title}}",
                "body": "A ticket (#{{ticket.id}}) by {{ticket.requester.name}} has been received. It is unassigned.\n\n{{ticket.comments_formatted}}",
                "recipients": [
                    *****
                ]
            },
            {
                "id": *****,
                "type": "Notification",
                "via": {
                    "channel": "rule",
                    "source": {
                        "from": {
                            "deleted": false,
                            "title": "Notify requester of new proactive ticket",
                            "id": *****
                        },
                        "rel": "trigger"
                    }
                },
                "subject": "{{ticket.title}}",
                "body": "This ticket was created on your behalf.\n\n{{ticket.comments_formatted}}\n\nTo add additional comments, reply to this email.",
                "recipients": [
                    *****
                ]
            }
        ],
        "via": {
            "channel": "api",
            "source": {
                "from": {},
                "to": {
                    "name": "*****",
                    "address": "*****@*****.***"
                },
                "rel": null
            }
        }
    }
}

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

{
    "url": "https://*****.zendesk.com/*****",
    "id": *****,
    "external_id": null,
    "via": {
        "channel": "api",
        "source": {
            "from": {},
            "to": {},
            "rel": null
        }
    },
    "created_at": "2022-02-04T01:34:24Z",
    "updated_at": "2022-02-04T01:34:24Z",
    "type": "task",
    "subject": "Pizza Yummy",
    "raw_subject": "Pizza Yummy",
    "description": "start working",
    "priority": "normal",
    "status": "open",
    "recipient": null,
    "requester_id": *****,
    "submitter_id": *****,
    "assignee_id": *****,
    "organization_id": *****,
    "group_id": *****,
    "collaborator_ids": [],
    "follower_ids": [],
    "email_cc_ids": [],
    "forum_topic_id": null,
    "problem_id": null,
    "has_incidents": false,
    "is_public": true,
    "due_at": null,
    "tags": [
        "installation"
    ],
    "custom_fields": [],
    "satisfaction_rating": null,
    "sharing_agreement_ids": [],
    "fields": [],
    "followup_ids": [],
    "ticket_form_id": *****,
    "brand_id": *****,
    "allow_channelback": false,
    "allow_attachments": true
}

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

{
  "TicketID": *****
}

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

url	https://***.zendesk.com/***
id	*****
external_id	None
via	{'channel': 'api', 'source': {'from': {}, 'to': {}, 'rel': None}}
created_at	2022-02-04T01:34:24Z
updated_at	2022-02-04T01:34:24Z
type	task
subject	Pizza Yummy
raw_subject	Pizza Yummy
description	start working
priority	normal
status	open
recipient	None
requester_id	*****
submitter_id	*****
assignee_id	*****
organization_id	*****
group_id	*****
collaborator_ids	[]
follower_ids	[]
email_cc_ids	[]
forum_topic_id	None
problem_id	None
has_incidents	False
is_public	True
due_at	None
tags	installation
custom_fields	[]
satisfaction_rating	None
sharing_agreement_ids	[]
fields	[]
followup_ids	[]
ticket_form_id	*****
brand_id	*****
allow_channelback	False
allow_attachments	True

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 Ticket 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 Zendesk 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: Couldn't authenticate you.

Error Sample Data

Create Ticket failed.

Status Code: 401.

Message: Couldn't authenticate you.

Export Search Results

Exports a set of results returned from searching objects (tickets, organizations, users or groups). This command can return more than 1,000 results. The result set is returned as a single object, ordered by the created_at attribute.

READER NOTE

The differences between Export Search Results and Fetch Event commands are:

This command can return more than 1,000 results, while Fetch Event is limited to a maximum of 1,000 results.
This command is exported for specific object type, while fetch event can search for all types.

Input

Input Parameter	Required/Optional	Description	Example
Start Time	Optional	The start time (in UTC Time) of the time range for searching tickets, organizations, users and groups.	2022-04-01 00:00
End Time	Optional	The end time (in UTC Time) of the time range for searching tickets, organizations, users and groups.	2022-04-02 00:00
Limit	Optional	The maximum number of objects (i.e., tickets, organizations, users or groups) to return. If the value of this parameter is not defined or 0, all objects will be returned.	100
Object Type	Required	The object type to search. The searcheable object types are Ticket, Organization, User and Group. If this parameter is not defined, tickets will be searched by default.	Ticket
Query	Required	The query to filter the returned results. Refer to the provided sample data in D3 SOAR to help you create a query string. See the Zendesk Support search reference for more information on the query syntax. Note: (1) Use the following format to search for multiple values with each value separated by a space: property keyword+operator+search term For example, to search for the specified object type with an open or closed status, the following syntax should be used: status:new status:closed Consecutive values with the same property keywords will use a or logic (as shown in the previous example) for the query. Values with different property words will use an and logic for the query. (2) If the input search values contain double quotation marks, the escape character “\” must precede the double quotation mark. Double quotation marks must also surround a search value if it contains non-alphanumeric characters (e.g. spaces and commas). For example, to search for My “New” Organization-D3, D3 test, the following syntax should be used: “My \"New\" Organization-D3, D3 test" (3) The input value of the “Query Time Type” parameter cannot match the corresponding property keywords. For example, if you have defined the “Query Time Type” parameter as “Created Time”, a “created” property keyword in the query string will be ignored and overridden. However, if the defined value for the “Query Time Type” parameter is “Created Time” and an “updated” property keyword is used for the query string, both values will be accepted. Other date property keywords (i.e., due_date and solved) will be accepted. (4) The Object Type parameter defines what is being searched. The type property keyword cannot be used in the query string to filter object types. Otherwise, an error will be returned.	Sample Data for Ticket Search status:open subject:"test subject" Sample Data for Organization Search status:new status:closed Sample Data for User Search name:customer role:end-user Sample Data for Group Search name:support
Query Time Type	Optional	The time type (Created Time or Updated Time) to query results. Created Time will be the default value if this parameter is not defined.	Create Time

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 FOR TICKET SEARCH

JSON

{
  "results": [
    {
      "url": "https://*****.zendesk.com/*****",
      "id": *****,
      "external_id": null,
      "via": {
        "channel": "api",
        "source": {
          "from": {},
          "to": {},
          "rel": null
        }
      },
      "created_at": "2022-06-04T14:16:51Z",
      "updated_at": "2022-06-08T01:22:49Z",
      "type": "question",
      "subject": "Test Subject *****",
      "raw_subject": "Test Subject *****",
      "description": "Test Desp *****",
      "priority": "normal",
      "status": "open",
      "recipient": null,
      "requester_id": *****,
      "submitter_id": *****,
      "assignee_id": *****,
      "organization_id": *****,
      "group_id": *****,
      "collaborator_ids": [],
      "follower_ids": [],
      "email_cc_ids": [],
      "forum_topic_id": null,
      "problem_id": null,
      "has_incidents": false,
      "is_public": true,
      "due_at": null,
      "tags": [
        "security",
        "test",
        "testpurpose2",
        "vancouver"
      ],
      "custom_fields": [
        {
          "id": *****,
          "value": "abc"
        }
      ],
      "satisfaction_rating": null,
      "sharing_agreement_ids": [],
      "fields": [
        {
          "id": *****,
          "value": "abc"
        }
      ],
      "followup_ids": [],
      "ticket_form_id": *****,
      "brand_id": *****,
      "allow_channelback": false,
      "allow_attachments": true,
      "result_type": "ticket"
    }
  ]
}

SAMPLE DATA FOR ORGANIZATION SEARCH

CODE

{
  "results": [
    {
      "url": "https://*****.zendesk.com/*****",
      "id": *****,
      "name": "EnergyOrg",
      "shared_tickets": false,
      "shared_comments": false,
      "external_id": null,
      "created_at": "2022-06-07T17:32:28Z",
      "updated_at": "2022-06-07T22:10:46Z",
      "domain_names": [],
      "details": "",
      "notes": "",
      "group_id": null,
      "tags": [
        "usa"
      ],
      "organization_fields": {
        "country": "usa",
        "org_type": "energy",
        "status": "new"
      },
      "result_type": "organization"
    }
  ]
}

SAMPLE DATA FOR USER SEARCH

CODE

{
  "results": [
    {
      "id": *****,
      "url": "https://*****.zendesk.com/*****",
      "name": "*****",
      "email": "*****@*****.***",
      "created_at": "2022-05-27T20:45:29Z",
      "updated_at": "2022-05-27T20:45:30Z",
      "time_zone": "America/Vancouver",
      "iana_time_zone": "America/Vancouver",
      "phone": null,
      "shared_phone_number": null,
      "photo": {
        "url": "https://*****.zendesk.com/*****",
        "id": *****,
        "file_name": "profile_image_*****_*****.png",
        "content_url": "https://*****.zendesk.com/*****",
        "mapped_content_url": "https://*****.zendesk.com/*****",
        "content_type": "image/png",
        "size": 10183,
        "width": 80,
        "height": 80,
        "inline": false,
        "deleted": false,
        "thumbnails": [
          {
            "url": "https://*****.zendesk.com/*****",
            "id": 658682352206*****,
            "file_name": "profile_image_*****_*****_thumb.png",
            "content_url": "https://*****.zendesk.com/*****",
            "mapped_content_url": "https://*****.zendesk.com/*****",
            "content_type": "image/png",
            "size": *****33*****,
            "width": 3*****,
            "height": 3*****,
            "inline": false,
            "deleted": false
          }
        ]
      },
      "locale_id": *****,
      "locale": "en-US",
      "organization_id": null,
      "role": "end-user",
      "verified": false,
      "external_id": null,
      "tags": [],
      "alias": null,
      "active": true,
      "shared": false,
      "shared_agent": false,
      "last_login_at": null,
      "two_factor_auth_enabled": false,
      "signature": null,
      "details": null,
      "notes": null,
      "role_type": null,
      "custom_role_id": null,
      "moderator": false,
      "ticket_restriction": "requested",
      "only_private_comments": false,
      "restricted_agent": true,
      "suspended": false,
      "default_group_id": null,
      "report_csv": false,
      "user_fields": {},
      "result_type": "user"
    }
  ]
}

SAMPLE DATA FOR GROUP SEARCH

CODE

{
  "results": [
    {
      "url": "https://*****.zendesk.com/*****",
      "id": *****,
      "is_public": true,
      "name": "Support",
      "description": "",
      "default": true,
      "deleted": false,
      "created_at": "2022-05-27T20:45:25Z",
      "updated_at": "2022-05-27T20:45:25Z",
      "result_type": "group"
    }
  ]
}

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

{
  "ObjectIDs": *****
}

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.	Export Search Results 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 Zendesk 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: You must have a valid support account to call this API.

Error Sample Data

Export Search Results failed.

Status Code: 403.

Message: You must have a valid Support account to call this API.

Fetch Event

Returns results (tickets, organizations, users and groups) for ingestion as events into D3 SOAR from the Zendesk platform based on your defined input values.

Input

READER NOTE

Only the “Start Time” parameter is required for this command. If all other optional input parameters are not defined, up to 1,000 events (including tickets, organizations, users and groups) will be returned sorted by the latest created time in Zendesk. In this case, the default time range for the returned results will be between your input for the “Start Time” parameter and the current time.

Input Parameter	Required/Optional	Description	Example
Start Time	Required	The start time (in UTC Time) of the time range for fetching tickets, organizations, users and groups.	2022-04-02 00:00
End Time	Optional	The end time (in UTC Time) of the time range for fetching tickets, organizations, users and groups. Note: If this parameter is not defined, the current time will be automatically used as the value by default.	2022-04-20 00:00
Number of Event(s) Fetched	Optional	The maximum number of the most recent results (tickets, organization, users and groups) by created time or updated time to return as events for data ingestion. Note: If the value of this parameter is not defined or not a positive integer greater than zero, all results (maximum of 1,000) will be returned. Use the Export Search Result command if you have more than 1,000 results to return.	100
Search Condition	Optional	The query to filter the returned results. Refer to the provided sample data in D3 SOAR to help you create a query string. See the Zendesk Support search reference for more information on the query syntax. Note: (1) Use the following format to search for multiple values with each value separated by a space: property keyword+operator+search term For example, to search for tickets or users with an open status, the following syntax should be used: type:ticket type:user status:open Consecutive values with the same property keywords will use a or logic (as shown in the previous example) for the query. Values with different property words will use an and logic for the query. (2) If the input search values contain double quotation marks, the escape character “\” must precede the double quotation mark. Double quotation marks must also surround a search value if it contains non-alphanumeric characters (e.g. spaces and commas). For example, to search for My “New” Organization-D3, D3 test, the following syntax should be used: “My \"New\" Organization-D3, D3 test" (3) The input value of the “Query Time Type” parameter cannot match the corresponding property keywords. For example, if you have defined the “Query Time Type” parameter as “Created Time”, a “created” property keyword in the query string will be ignored and overridden. However, if the defined value for the “Query Time Type” parameter is “Created Time” and an “updated” property keyword is used for the query string, both values will be accepted. Other date property keywords (i.e., due_date and solved) will be accepted. (4) If the “type” property keyword is not in the query string, all tickets, users, organizations and groups will be searched.	Sample Data for Ticket Search type:ticket status:open subject:"test subject" Sample Data for Organization Search type:organization status:new status:closed description:“My \"New\" Organization-D3, D3 test" Sample Data for User Search type:user name:customer role:end-user created>2014-08-01 created<=2014-08-05 Sample Data for Group Search type:group name:support solved>4hours
Query Time Type	Optional	The time type (Created Time or Updated Time) to query results. Created Time will be the default value if this parameter is not defined.	Created Time

Output

READER NOTE

The Event Type (i.e. tickets, users, organizations or groups) is extracted from $.results.[*].result_type JSON path in the returned raw data by using default field mapping.

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

{
    "results": [
        {
            "url": "https://*****.zendesk.com/*****",
            "id": *****,
            "external_id": null,
            "via": {
                "channel": "api",
                "source": {
                    "from": {},
                    "to": {},
                    "rel": null
                }
            },
            "created_at": "2022-06-04T14:16:51Z",
            "updated_at": "2022-06-08T01:22:49Z",
            "type": "question",
            "subject": "Test Subject *****",
            "raw_subject": "Test Subject *****",
            "description": "Test Desp *****",
            "priority": "normal",
            "status": "open",
            "recipient": null,
            "requester_id": *****,
            "submitter_id": *****,
            "assignee_id": *****,
            "organization_id": *****,
            "group_id": *****,
            "collaborator_ids": [],
            "follower_ids": [],
            "email_cc_ids": [],
            "forum_topic_id": null,
            "problem_id": null,
            "has_incidents": false,
            "is_public": true,
            "due_at": null,
            "tags": [
                "security",
                "test",
                "testpurpose2",
                "vancouver"
            ],
            "custom_fields": [
                {
                    "id": *****,
                    "value": "abc"
                }
            ],
            "satisfaction_rating": null,
            "sharing_agreement_ids": [],
            "fields": [
                {
                    "id": *****,
                    "value": "abc"
                }
            ],
            "followup_ids": [],
            "ticket_form_id": *****,
            "brand_id": *****,
            "allow_channelback": false,
            "allow_attachments": true,
            "result_type": "ticket"
        },
        {
            "url": "https://*****.zendesk.com/*****",
            "id": *****,
            "name": "EnergyOrg",
            "shared_tickets": false,
            "shared_comments": false,
            "external_id": null,
            "created_at": "2022-06-07T17:32:28Z",
            "updated_at": "2022-06-07T22:10:46Z",
            "domain_names": [],
            "details": "",
            "notes": "",
            "group_id": null,
            "tags": [
                "usa"
            ],
            "organization_fields": {
                "country": "usa",
                "org_type": "energy",
                "status": "new"
            },
            "result_type": "organization"
        }
    ]
}

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

{
  "EventIDs": [*****,*****]
}

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

Start Time (UTC)	2023-02-07 12:32:41
End Time (UTC)	2023-02-07 12:37:41
EventsCount	2

Fetch Event Field Mapping

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.

The Zendesk integration in D3 SOAR has some pre-configured field mappings for the four categories of events (ticket, organization, user, and group), which correspond to the following four event sources:

Default Event Source
Configures the field mapping for the fields which are common for tickets, organizations, users and groups (e.g. id, created_at, and updated_at). The default event source has a “Main Event JSON Path” (i.e., $.results) 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: $.result
  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 result. The child node denoting the Event Type field would be result_type. Putting it together, the JSON Path expression to extract the Event Type is $.result.result_type.

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 Zendesk integration’s Fetch Event command’s Default Event Source mapping does not include Unique Event Key in order to fetch the same fetched target (i.e. tickets, organizations, users, and groups) with multiple updates.

Event Source for Ticket
Configures the additional field mapping for the fields which are specific to events categorized as ticket-related (e.g. priority and tags). In the response raw data, the event source Search String will be {$.result_type}=ticket. Click Edit Event Source to view the Search String.
Note: The Event Source for Ticket field mapping will be applied in addition to the Default Event Source field mapping for ticket-related events.
Event Source for Organization
Configures the additional field mapping for fields which are specific to events categorized as organization-related (e.g. domain_names, notes and details). In the response raw data, the event source Search String will be {$.result_type}=organization. Click Edit Event Source to view the Search String. Note: The Event Source for Organization field mapping will be applied in addition to the Default Event Source field mapping for organization-related events.
Event Source for User
Configures the additional field mapping for fields which are specific to events categorized as user-related (e.g. role, email and phone). In the response raw data, the event source Search String will be {$.result_type}=user. Click Edit Event Source to view the Search String.
Note: The Event Source for User field mapping will be applied in addition to the Default Event Source field mapping for user-related events.
Event Source for Group
Configures the additional field mapping for fields which are specific to events categorized as group-related (e.g. name, default and deleted). In the response raw data, the event source Search String will be {$.result_type}=group. Click Edit Event Source to view the Search String.
Note: The Event Source for Group field mapping will be applied in addition to the Default Event Source field mapping for group-related events.

The pre-configured field mappings for the four event sources are detailed below:

Field Name	Source Field
Default Event Source (Main Event JSON Path: $.result)
Original event ID	.id
Event Type	.result_type
Start Time	..created_at
Updated Time	.updated_at
Event Source for Ticket (Search String: {$.result_type}=ticket) The search string format is {jsonpath}=value. If the value of the result_type key is ticket in the event object under raw data, then the created or updated ticket-related events will use the field mapping below.
Ticket Type	.type
Ticket Subject	.subject
Description	.description
Priority	.priority
Status	.status
Requester ID	.requester_id
Submitter ID	.submitter_id
Assignee ID	.assignee_id
Organization ID	.organization_id
Group ID	.group_id
Has Incidents	.has_incidents
Is Public	.is_public
Tags	.tags
Event Source for Organization (Search String: {$.result_type}=organization) The search string format is {jsonpath}=value. If the value of the result_type key is organization in the event object under raw data, then the created or updated organization-related events will use the field mapping below.
Organization Name	.name
Organization Domains	.domain_names
Description	.details
Notes	.notes
Group ID	.group_id
Tags	.tags
Event Source for User (Search String: {$.result_type}=user) The search string format is {jsonpath}=value. If the value of the result_type key is user in the event object under raw data, then the created or updated user-related events will use the field mapping below.
Username	.name
Email Address	.email
Time Zone	.time_zone
Phone Number	.phone
Locale	.locale
Organization ID	.organization_id
Role	.role
Tags	.tags
Description	.details
Notes	.notes
Event Source for Group (Search String: {$.result_type}=group) The search string format is {jsonpath}=value. If the value of the result_type key is group in the event object under raw data, then the created or updated group-related events will use the field mapping below.
Is Public	.is_public
Group Name	.name
Description	.description
Is Default	.default
Is Deleted	.deleted

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.	Fetch Event failed. Failed on getting organizations data.
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 Zendesk 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: You must have a valid Support account to call this API.

Error Sample Data

Fetch Event failed. Failed on getting organizations data.

Status Code: 403.

Message: You must have a valid Support account to call this API.

Get Tickets Details

Returns details of the specified tickets.

READER NOTE

Input parameter Ticket IDs is required to run this command.

Run the List Tickets command to obtain Ticket IDs. Ticket IDs can be found in the raw data at the path $.tickets[*].id.

Input

Input Parameter	Required/Optional	Description	Example
Ticket IDs	Required	The IDs of the tickets to retrieve details. Ticket IDs can be obtained using the List Tickets command.	[*****,2]

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

{
    "tickets": [
        {
            "url": "https://*****.zendesk.com/*****",
            "id": *****,
            "external_id": null,
            "via": {
                "channel": "sample_ticket",
                "source": {
                    "from": {},
                    "to": {},
                    "rel": null
                }
            },
            "created_at": "2021-10-29T04:31:32Z",
            "updated_at": "2021-11-05T18:02:39Z",
            "type": "incident",
            "subject": "New Sub 1105ab",
            "raw_subject": "New Sub 1105ab",
            "description": "Hi there,\n\nI’m sending an email because I’m having a problem setting up your new product. Can you help me troubleshoot?\n\nThanks,\n *****\n\n",
            "priority": "normal",
            "status": "open",
            "recipient": null,
            "requester_id": *****,
            "submitter_id": *****,
            "assignee_id": *****,
            "organization_id": null,
            "group_id": *****,
            "collaborator_ids": [],
            "follower_ids": [],
            "email_cc_ids": [],
            "forum_topic_id": null,
            "problem_id": null,
            "has_incidents": false,
            "is_public": true,
            "due_at": null,
            "tags": [
                "sample",
                "support",
                "zendesk"
            ],
            "custom_fields": [],
            "satisfaction_rating": null,
            "sharing_agreement_ids": [],
            "fields": [],
            "followup_ids": [],
            "ticket_form_id": *****,
            "brand_id": *****,
            "allow_channelback": false,
            "allow_attachments": true
        },
        {
            "url": "https://*****.zendesk.com/*****",
            "id": *****,
            "external_id": null,
            "via": {
                "channel": "api",
                "source": {
                    "from": {},
                    "to": {},
                    "rel": null
                }
            },
            "created_at": "2021-11-05T17:49:48Z",
            "updated_at": "2021-11-05T17:49:48Z",
            "type": null,
            "subject": "Test Ticket on Nov 5!",
            "raw_subject": "Test Ticket on Nov 5!",
            "description": "Description or comment?",
            "priority": "urgent",
            "status": "open",
            "recipient": null,
            "requester_id": *****,
            "submitter_id": *****,
            "assignee_id": *****,
            "organization_id": *****,
            "group_id": *****,
            "collaborator_ids": [],
            "follower_ids": [],
            "email_cc_ids": [],
            "forum_topic_id": null,
            "problem_id": null,
            "has_incidents": false,
            "is_public": true,
            "due_at": null,
            "tags": [
                "jon_created1"
            ],
            "custom_fields": [],
            "satisfaction_rating": null,
            "sharing_agreement_ids": [],
            "fields": [],
            "followup_ids": [],
            "ticket_form_id": *****,
            "brand_id": *****,
            "allow_channelback": false,
            "allow_attachments": true
        }
    ],
    "next_page": null,
    "previous_page": null,
    "count": *****
}

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

[
    {
        "url": "https://*****.zendesk.com/*****",
        "id": *****,
        "external_id": null,
        "via": {
            "channel": "sample_ticket",
            "source": {
                "from": {},
                "to": {},
                "rel": null
            }
        },
        "created_at": "2021-10-29T04:31:32Z",
        "updated_at": "2021-11-05T18:02:39Z",
        "type": "incident",
        "subject": "New Sub 1105ab",
        "raw_subject": "New Sub 1105ab",
        "description": "Hi there,\n\nI'm sending an email because I'm having a problem setting up your new product. Can you help me troubleshoot?\n\nThanks,\n*****\n\n",
        "priority": "normal",
        "status": "open",
        "recipient": null,
        "requester_id": *****,
        "submitter_id": *****,
        "assignee_id": *****,
        "organization_id": null,
        "group_id": *****,
        "collaborator_ids": [],
        "follower_ids": [],
        "email_cc_ids": [],
        "forum_topic_id": null,
        "problem_id": null,
        "has_incidents": false,
        "is_public": true,
        "due_at": null,
        "tags": [
            "sample",
            "support",
            "zendesk"
        ],
        "custom_fields": [],
        "satisfaction_rating": null,
        "sharing_agreement_ids": [],
        "fields": [],
        "followup_ids": [],
        "ticket_form_id": *****,
        "brand_id": *****,
        "allow_channelback": false,
        "allow_attachments": true
    },
    {
        "url": "https://*****.zendesk.com/*****",
        "id": *****,
        "external_id": null,
        "via": {
            "channel": "api",
            "source": {
                "from": {},
                "to": {},
                "rel": null
            }
        },
        "created_at": "2021-11-05T17:49:48Z",
        "updated_at": "2021-11-05T17:49:48Z",
        "type": null,
        "subject": "Test Ticket on Nov 5!",
        "raw_subject": "Test Ticket on Nov 5!",
        "description": "Description or comment?",
        "priority": "urgent",
        "status": "open",
        "recipient": null,
        "requester_id": *****,
        "submitter_id": *****,
        "assignee_id": *****,
        "organization_id": *****,
        "group_id": *****,
        "collaborator_ids": [],
        "follower_ids": [],
        "email_cc_ids": [],
        "forum_topic_id": null,
        "problem_id": null,
        "has_incidents": false,
        "is_public": true,
        "due_at": null,
        "tags": [
            "jon_created1"
        ],
        "custom_fields": [],
        "satisfaction_rating": null,
        "sharing_agreement_ids": [],
        "fields": [],
        "followup_ids": [],
        "ticket_form_id": *****,
        "brand_id": *****,
        "allow_channelback": false,
        "allow_attachments": true
    }
]

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

{
  "TicketIDs": [*****, *****],
  "Subjects": ["New Sub 1105ab", "Test Ticket on Nov 5!"],
  "Descriptions": [
    "Hi there,\n\nI'm sending an email because I'm having a problem setting up your new product. Can you help me troubleshoot?\n\nThanks,\n*****\n\n",
    "Description or comment?"
  ],
  "Statuses": ["open", "open"],
  "Priorities": ["normal", "urgent"],
  "Types": ["incident", "question"],
  "RequestIDs": [*****, *****],
  "AssigneeIDs": [*****, *****]
}

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

url	https://***.zendesk.com/***	https://***.zendesk.com/***
id	*****	*****
external_id	None	None
via	{'channel': 'sample_ticket', 'source': {'from': {}, 'to': {}, 'rel': None}}	{'channel': 'api', 'source': {'from': {}, 'to': {}, 'rel': None}}
created_at	2021-10-29T04:31:32Z	2021-11-05T17:49:48Z
updated_at	2021-11-05T18:02:39Z	2021-11-05T17:49:48Z
type	incident	None
subject	New Sub 1105ab	Test Ticket on Nov 5!
raw_subject	New Sub 1105ab	Test Ticket on Nov 5!
description	Hi there, I'm sending an email because I'm having a problem setting up your new product. Can you help me troubleshoot? Thanks, *****	Description or comment?
priority	normal	urgent
status	open	open
recipient	None	None
requester_id	*****	*****
submitter_id	*****	*****
assignee_id	*****	*****
organization_id	None	*****
group_id	*****	*****
collaborator_ids	[]	[]
follower_ids	[]	[]
email_cc_ids	[]	[]
forum_topic_id	None	None
problem_id	None	None
has_incidents	FALSE	FALSE
is_public	TRUE	TRUE
due_at	None	None
tags	['sample', 'support', 'zendesk']	['jon_created1']
custom_fields	[]	[]
satisfaction_rating	None	None
sharing_agreement_ids	[]	[]
fields	[]	[]
followup_ids	[]	[]
ticket_form_id	*****	*****
brand_id	*****	*****
allow_channelback	FALSE	FALSE
allow_attachments	TRUE	TRUE

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 Tickets Details 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 Zendesk 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: Ticket ID 9: Record Not Found.

Error Sample Data

Get Tickets Details failed.

Status Code: 404.

Message: Ticket ID 9: Record Not Found.

Get Users By Organization

Lists users in the specified organization.

READER NOTE

Organization ID is a required parameter to run this command.

Run the List Organizations command to obtain Organization ID. Organization IDs can be found in the raw data at the path $.organizations.id.

Input

Input Parameter	Required/Optional	Description	Example
Organization ID	Required	The ID of the organization to list users. Organization IDs can be obtained using the List Organizations 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

{
    "users": [
        {
            "id":  *****,
            "url": "https://*****.zendesk.com/*****",
            "name": "*****",
            "email": "*****@*****.***",
            "created_at": "2022-02-15T21:42:03Z",
            "updated_at": "2022-02-15T22:27:31Z",
            "time_zone": "America/Vancouver",
            "iana_time_zone": "America/Vancouver",
            "phone": null,
            "shared_phone_number": null,
            "photo": null,
            "locale_id": *****,
            "locale": "en-US",
            "organization_id": *****,
            "role": "agent",
            "verified": false,
            "external_id": null,
            "tags": [],
            "alias": null,
            "active": true,
            "shared": false,
            "shared_agent": false,
            "last_login_at": null,
            "two_factor_auth_enabled": null,
            "signature": null,
            "details": null,
            "notes": null,
            "role_type": null,
            "custom_role_id": null,
            "moderator": false,
            "ticket_restriction": null,
            "only_private_comments": false,
            "restricted_agent": false,
            "suspended": false,
            "default_group_id": *****,
            "report_csv": false,
            "user_fields": {}
        }
    ],
    "next_page": null,
    "previous_page": null,
    "count": 1
}

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

[
    {
        "id":  *****,
        "url": "https://*****.zendesk.com/*****",
        "name": "*****",
        "email": "*****@*****.***",
        "created_at": "2022-02-15T21:42:03Z",
        "updated_at": "2022-02-15T22:27:31Z",
        "time_zone": "America/Vancouver",
        "iana_time_zone": "America/Vancouver",
        "phone": null,
        "shared_phone_number": null,
        "photo": null,
        "locale_id": *****,
        "locale": "en-US",
        "organization_id": *****,
        "role": "agent",
        "verified": false,
        "external_id": null,
        "tags": [],
        "alias": null,
        "active": true,
        "shared": false,
        "shared_agent": false,
        "last_login_at": null,
        "two_factor_auth_enabled": null,
        "signature": null,
        "details": null,
        "notes": null,
        "role_type": null,
        "custom_role_id": null,
        "moderator": false,
        "ticket_restriction": null,
        "only_private_comments": false,
        "restricted_agent": false,
        "suspended": false,
        "default_group_id": *****,
        "report_csv": false,
        "user_fields": {}
    }
]

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

{
  "UserIDs": [ *****],
  "UserNames": ["*****"]
}

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

id	*****
url	https://***.zendesk.com/***
name	*****
email	***@*.*
created_at	2022-02-15T21:42:03Z
updated_at	2022-02-15T22:27:31Z
time_zone	America/Vancouver
iana_time_zone	America/Vancouver
phone	None
shared_phone_number	None
photo	None
locale_id	1
locale	en-US
organization_id	*****
role	agent
verified	FALSE
external_id	None
tags	[]
alias	None
active	TRUE
shared	FALSE
shared_agent	FALSE
last_login_at	None
two_factor_auth_enabled	None
signature	None
details	None
notes	None
role_type	None
custom_role_id	None
moderator	FALSE
ticket_restriction	None
only_private_comments	FALSE
restricted_agent	FALSE
suspended	FALSE
default_group_id	*****
report_csv	FALSE
user_fields	{}

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 Users By Organization 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 Zendesk 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: Organization ID Not Found.

Error Sample Data

Get Users By Organization failed.

Status Code: 404.

Message: Organization ID Not Found.

List Groups

Lists Zendesk groups and corresponding details that the connector has access authorization to.

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

{
    "groups": [
        {
            "url": "https://*****.zendesk.com/*****",
            "id": *****,
            "name": "Support",
            "description": "",
            "default": true,
            "deleted": false,
            "created_at": "2022-02-07T19:15:01Z",
            "updated_at": "2022-02-07T19:15:01Z"
        }
    ],
    "next_page": null,
    "previous_page": null,
    "count": 1
}

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

[
    {
        "url": "https://*****.zendesk.com/*****",
        "id": *****,
        "name": "Support",
        "description": "",
        "default": true,
        "deleted": false,
        "created_at": "2022-02-07T19:15:01Z",
        "updated_at": "2022-02-07T19:15:01Z"
    }
]

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

{
  "GroupIDs": [*****],
  "GroupNames": ["Support"]
}

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

url	https://***.zendesk.com/***
id	*****
name	Support
description
default	TRUE
deleted	FALSE
created_at	2022-02-07T19:15:01Z
updated_at	2022-02-07T19:15:01Z

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 Groups 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 Zendesk 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: You must have a valid Support account to call this API.

Error Sample Data

List Groups failed.

Status Code: 403.

Message: You must have a valid Support account to call this API.

List Organizations

Lists all organizations in Zendesk.

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

{
    "organizations": [
        {
            "url": "https://*****.zendesk.com/*****",
            "id": *****,
            "name": "D3 Security",
            "shared_tickets": false,
            "shared_comments": false,
            "external_id": null,
            "created_at": "2022-02-07T19:15:01Z",
            "updated_at": "2022-02-07T19:15:01Z",
            "domain_names": [],
            "details": null,
            "notes": null,
            "group_id": null,
            "tags": [],
            "organization_fields": {
                "default_zendesk_requester_id": "defaultUser",
                "support_description": null
            }
        }
    ],
    "next_page": null,
    "previous_page": null,
    "count": 1
}

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

[
    {
        "url": "https://*****.zendesk.com/*****",
        "id": *****,
        "name": "D3 Security",
        "shared_tickets": false,
        "shared_comments": false,
        "external_id": null,
        "created_at": "2022-02-07T19:15:01Z",
        "updated_at": "2022-02-07T19:15:01Z",
        "domain_names": [],
        "details": null,
        "notes": null,
        "group_id": null,
        "tags": [],
        "organization_fields": {
            "default_zendesk_requester_id": "defaultUser",
            "support_description": null
        }
    }
]

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

{
  "OrganizationIDs": *****,
  "OrganizationNames": [ "D3 Security" ]
}

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

url	https://***.zendesk.com/***
id	*****
name	D3 Security
shared_tickets	FALSE
shared_comments	FALSE
external_id	None
created_at	2022-02-07T19:15:01Z
updated_at	2022-02-07T19:15:01Z
domain_names	[]
details	None
notes	None
group_id	None
tags	[]
organization_fields	{'default_zendesk_requester_id': 'defaultUser', 'support_description': None}

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 Organizations 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 Zendesk 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: You must have a valid Support account to call this API.

Error Sample Data

List Organizations failed.

Status Code: 403.

Message: You must have a valid Support account to call this API.

Search Tickets

Returns tickets based on the specified query.

READER NOTE

All input parameters in this command are optional.

If all inputs are empty, a full ticket list with detail will be returned.

Input

Input Parameter

Required/Optional

Description

Example

Query

Optional

The query to filter the returned results. The returned tickets are sorted by created time, in descending order. Refer to the provided sample data in D3 SOAR to help you create a query string. See the Zendesk Support search reference for more information on the query syntax.

Note:

(1) Use the following format to search for multiple values with each value separated by a space:

property keyword+operator+search term

For example, to search for tickets with an open status, the following syntax should be used:

status:open

Consecutive values with the same property keywords will use a or logic (as shown in the previous example) for the query. Values with different property words will use an and logic for the query.

(2) If the input search values contain double quotation marks, the escape character “\” must precede the double quotation mark. Double quotation marks must also surround a search value if it contains non-alphanumeric characters (e.g. spaces and commas).

For example, to search for My “New” Ticket-D3, D3 test, the following syntax should be used:

“My \"New\" Ticket-D3, D3 test"

(3) Datetime values conditions must be defined using the ISO8601 syntax. For example, to search for a ticket created before November *****, *****021 at 10:30 a.m., the following syntaxes can be used:

created<=2021-11-06T10:30:00Z

or

created<=2021-11-06T10:30:00-08:00 (Pacific Standard Time)

status:open group:”Level *****” created<=2021-11-06T10:30:00Z created>=2021-11-05T18:30:00Z

Limit

Optional

The maximum number of the most recently created tickets to return. The default value is 100.

500

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

{
    "results": [
        {
            "url": "https://*****.zendesk.com/*****",
            "id": *****,
            "external_id": null,
            "via": {
                "channel": "api",
                "source": {
                    "from": {},
                    "to": {},
                    "rel": null
                }
            },
            "created_at": "2021-11-05T23:59:54Z",
            "updated_at": "2021-11-05T23:59:54Z",
            "type": null,
            "subject": "Pizza Lunch 1105oo",
            "raw_subject": "Pizza Lunch 1105oo",
            "description": "The Pizza is Yummy.1105oo",
            "priority": "high",
            "status": "open",
            "recipient": null,
            "requester_id": *****,
            "submitter_id": *****,
            "assignee_id": *****,
            "organization_id": null,
            "group_id": *****,
            "collaborator_ids": [],
            "follower_ids": [],
            "email_cc_ids": [],
            "forum_topic_id": null,
            "problem_id": null,
            "has_incidents": false,
            "is_public": true,
            "due_at": null,
            "tags": [
                "tag1",
                "tag2"
            ],
            "custom_fields": [],
            "satisfaction_rating": null,
            "sharing_agreement_ids": [],
            "fields": [],
            "followup_ids": [],
            "ticket_form_id": *****,
            "brand_id": *****,
            "allow_channelback": false,
            "allow_attachments": true,
            "result_type": "ticket"
        },
        {
            "url": "https://*****.zendesk.com/*****",
            "id": *****,
            "external_id": null,
            "via": {
                "channel": "api",
                "source": {
                    "from": {},
                    "to": {},
                    "rel": null
                }
            },
            "created_at": "2021-11-05T23:47:01Z",
            "updated_at": "2021-11-05T23:47:01Z",
            "type": null,
            "subject": "Pizza Lunch 1105nn",
            "raw_subject": "Pizza Lunch 1105nn",
            "description": "The Pizza is Yummy.1105nn",
            "priority": null,
            "status": "open",
            "recipient": null,
            "requester_id": *****,
            "submitter_id": *****,
            "assignee_id": *****,
            "organization_id": null,
            "group_id": *****,
            "collaborator_ids": [],
            "follower_ids": [],
            "email_cc_ids": [],
            "forum_topic_id": null,
            "problem_id": null,
            "has_incidents": false,
            "is_public": true,
            "due_at": null,
            "tags": [
                "jon",
                "test1105"
            ],
            "custom_fields": [],
            "satisfaction_rating": null,
            "sharing_agreement_ids": [],
            "fields": [],
            "followup_ids": [],
            "ticket_form_id": *****,
            "brand_id": *****,
            "allow_channelback": false,
            "allow_attachments": true,
            "result_type": "ticket"
        },
        {
            "url": "https://*****.zendesk.com/*****",
            "id": *****,
            "external_id": null,
            "via": {
                "channel": "api",
                "source": {
                    "from": {},
                    "to": {},
                    "rel": null
                }
            },
            "created_at": "2021-11-05T23:45:11Z",
            "updated_at": "2021-11-05T23:45:11Z",
            "type": null,
            "subject": "Pizza Lunch 1105mm",
            "raw_subject": "Pizza Lunch 1105mm",
            "description": "The Pizza is Yummy.1105mm",
            "priority": null,
            "status": "open",
            "recipient": null,
            "requester_id": *****,
            "submitter_id": *****,
            "assignee_id": *****,
            "organization_id": null,
            "group_id": *****,
            "collaborator_ids": [],
            "follower_ids": [],
            "email_cc_ids": [],
            "forum_topic_id": null,
            "problem_id": null,
            "has_incidents": false,
            "is_public": true,
            "due_at": null,
            "tags": [],
            "custom_fields": [],
            "satisfaction_rating": null,
            "sharing_agreement_ids": [],
            "fields": [],
            "followup_ids": [],
            "ticket_form_id": *****,
            "brand_id": *****,
            "allow_channelback": false,
            "allow_attachments": true,
            "result_type": "ticket"
        },
        {
            "url": "https://*****.zendesk.com/*****",
            "id": *****,
            "external_id": null,
            "via": {
                "channel": "api",
                "source": {
                    "from": {},
                    "to": {},
                    "rel": null
                }
            },
            "created_at": "2021-11-05T23:41:32Z",
            "updated_at": "2021-11-05T23:41:32Z",
            "type": null,
            "subject": "Pizza Lunch 1105ll",
            "raw_subject": "Pizza Lunch 1105ll",
            "description": "The Pizza is Yummy.1105ll",
            "priority": null,
            "status": "open",
            "recipient": null,
            "requester_id": *****,
            "submitter_id": *****,
            "assignee_id": *****,
            "organization_id": null,
            "group_id": *****,
            "collaborator_ids": [],
            "follower_ids": [],
            "email_cc_ids": [],
            "forum_topic_id": null,
            "problem_id": null,
            "has_incidents": false,
            "is_public": true,
            "due_at": null,
            "tags": [],
            "custom_fields": [],
            "satisfaction_rating": null,
            "sharing_agreement_ids": [],
            "fields": [],
            "followup_ids": [],
            "ticket_form_id": *****,
            "brand_id": *****,
            "allow_channelback": false,
            "allow_attachments": true,
            "result_type": "ticket"
        },
        {
            "url": "https://*****.zendesk.com/*****",
            "id": *****,
            "external_id": null,
            "via": {
                "channel": "api",
                "source": {
                    "from": {},
                    "to": {},
                    "rel": null
                }
            },
            "created_at": "2021-11-05T23:32:34Z",
            "updated_at": "2021-11-05T23:32:34Z",
            "type": null,
            "subject": null,
            "raw_subject": null,
            "description": "The Pizza is Yummy.1105jj No Sub",
            "priority": "low",
            "status": "open",
            "recipient": null,
            "requester_id": *****,
            "submitter_id": *****,
            "assignee_id": *****,
            "organization_id": null,
            "group_id": *****,
            "collaborator_ids": [],
            "follower_ids": [],
            "email_cc_ids": [],
            "forum_topic_id": null,
            "problem_id": null,
            "has_incidents": false,
            "is_public": true,
            "due_at": null,
            "tags": [],
            "custom_fields": [],
            "satisfaction_rating": null,
            "sharing_agreement_ids": [],
            "fields": [],
            "followup_ids": [],
            "ticket_form_id": *****,
            "brand_id": *****,
            "allow_channelback": false,
            "allow_attachments": true,
            "result_type": "ticket"
        },
        {
            "url": "https://*****.zendesk.com/*****",
            "id": *****,
            "external_id": null,
            "via": {
                "channel": "api",
                "source": {
                    "from": {},
                    "to": {},
                    "rel": null
                }
            },
            "created_at": "2021-11-05T19:11:53Z",
            "updated_at": "2021-11-05T19:11:53Z",
            "type": null,
            "subject": "TestTicket1001",
            "raw_subject": "TestTicket1001",
            "description": "TestTicket1001",
            "priority": "high",
            "status": "open",
            "recipient": null,
            "requester_id": *****,
            "submitter_id": *****,
            "assignee_id": *****,
            "organization_id": *****,
            "group_id": *****,
            "collaborator_ids": [],
            "follower_ids": [],
            "email_cc_ids": [],
            "forum_topic_id": null,
            "problem_id": null,
            "has_incidents": false,
            "is_public": true,
            "due_at": null,
            "tags": [],
            "custom_fields": [],
            "satisfaction_rating": null,
            "sharing_agreement_ids": [],
            "fields": [],
            "followup_ids": [],
            "ticket_form_id": *****,
            "brand_id": *****,
            "allow_channelback": false,
            "allow_attachments": true,
            "result_type": "ticket"
        },
        {
            "url": "https://*****.zendesk.com/*****",
            "id": *****,
            "external_id": null,
            "via": {
                "channel": "api",
                "source": {
                    "from": {},
                    "to": {},
                    "rel": null
                }
            },
            "created_at": "2021-11-05T18:33:01Z",
            "updated_at": "2021-11-05T22:52:49Z",
            "type": null,
            "subject": "Pizza Lunch 1105ff",
            "raw_subject": "Pizza Lunch 1105ff",
            "description": "The Pizza is Yummy.1105ff",
            "priority": "low",
            "status": "open",
            "recipient": null,
            "requester_id": *****,
            "submitter_id": *****,
            "assignee_id": *****,
            "organization_id": null,
            "group_id": *****,
            "collaborator_ids": [],
            "follower_ids": [],
            "email_cc_ids": [],
            "forum_topic_id": null,
            "problem_id": null,
            "has_incidents": false,
            "is_public": true,
            "due_at": null,
            "tags": [],
            "custom_fields": [],
            "satisfaction_rating": null,
            "sharing_agreement_ids": [],
            "fields": [],
            "followup_ids": [],
            "ticket_form_id": *****,
            "brand_id": *****,
            "allow_channelback": false,
            "allow_attachments": true,
            "result_type": "ticket"
        },
        {
            "url": "https://*****.zendesk.com/*****",
            "id": *****,
            "external_id": null,
            "via": {
                "channel": "api",
                "source": {
                    "from": {},
                    "to": {},
                    "rel": null
                }
            },
            "created_at": "2021-11-05T18:32:06Z",
            "updated_at": "2021-11-05T21:58:48Z",
            "type": null,
            "subject": "Pizza Lunch 1105",
            "raw_subject": "Pizza Lunch 1105",
            "description": "The Pizza is Yummy.1105ee",
            "priority": "low",
            "status": "open",
            "recipient": null,
            "requester_id": *****,
            "submitter_id": *****,
            "assignee_id": *****,
            "organization_id": *****,
            "group_id": *****,
            "collaborator_ids": [],
            "follower_ids": [],
            "email_cc_ids": [],
            "forum_topic_id": null,
            "problem_id": null,
            "has_incidents": false,
            "is_public": true,
            "due_at": null,
            "tags": [],
            "custom_fields": [],
            "satisfaction_rating": null,
            "sharing_agreement_ids": [],
            "fields": [],
            "followup_ids": [],
            "ticket_form_id": *****,
            "brand_id": *****,
            "allow_channelback": false,
            "allow_attachments": true,
            "result_type": "ticket"
        },
        {
            "url": "https://*****.zendesk.com/*****",
            "id": *****,
            "external_id": null,
            "via": {
                "channel": "api",
                "source": {
                    "from": {},
                    "to": {},
                    "rel": null
                }
            },
            "created_at": "2021-11-05T18:30:43Z",
            "updated_at": "2021-11-05T18:30:43Z",
            "type": null,
            "subject": "My printer is on fire! 1105ee",
            "raw_subject": "My printer is on fire! 1105ee",
            "description": "The smoke is very colorful.",
            "priority": "urgent",
            "status": "open",
            "recipient": null,
            "requester_id": *****,
            "submitter_id": *****,
            "assignee_id": *****,
            "organization_id": *****,
            "group_id": *****,
            "collaborator_ids": [],
            "follower_ids": [],
            "email_cc_ids": [],
            "forum_topic_id": null,
            "problem_id": null,
            "has_incidents": false,
            "is_public": true,
            "due_at": null,
            "tags": [],
            "custom_fields": [],
            "satisfaction_rating": null,
            "sharing_agreement_ids": [],
            "fields": [],
            "followup_ids": [],
            "ticket_form_id": *****,
            "brand_id": *****,
            "allow_channelback": false,
            "allow_attachments": true,
            "result_type": "ticket"
        }
    ],
    "facets": null,
    "next_page": null,
    "previous_page": null,
    "count": 9
}

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

[
    {
        "url": "https://*****.zendesk.com/*****",
        "id": *****,
        "external_id": null,
        "via": {
            "channel": "api",
            "source": {
                "from": {},
                "to": {},
                "rel": null
            }
        },
        "created_at": "2021-11-05T23:59:54Z",
        "updated_at": "2021-11-05T23:59:54Z",
        "type": null,
        "subject": "Pizza Lunch 1105oo",
        "raw_subject": "Pizza Lunch 1105oo",
        "description": "The Pizza is Yummy.1105oo",
        "priority": "high",
        "status": "open",
        "recipient": null,
        "requester_id": *****,
        "submitter_id": *****,
        "assignee_id": *****,
        "organization_id": null,
        "group_id": *****,
        "collaborator_ids": [],
        "follower_ids": [],
        "email_cc_ids": [],
        "forum_topic_id": null,
        "problem_id": null,
        "has_incidents": false,
        "is_public": true,
        "due_at": null,
        "tags": [
            "tag1",
            "tag2"
        ],
        "custom_fields": [],
        "satisfaction_rating": null,
        "sharing_agreement_ids": [],
        "fields": [],
        "followup_ids": [],
        "ticket_form_id": *****,
        "brand_id": *****,
        "allow_channelback": false,
        "allow_attachments": true,
        "result_type": "ticket"
    },
    {
        "url": "https://*****.zendesk.com/*****",
        "id": *****,
        "external_id": null,
        "via": {
            "channel": "api",
            "source": {
                "from": {},
                "to": {},
                "rel": null
            }
        },
        "created_at": "2021-11-05T23:47:01Z",
        "updated_at": "2021-11-05T23:47:01Z",
        "type": null,
        "subject": "Pizza Lunch 1105nn",
        "raw_subject": "Pizza Lunch 1105nn",
        "description": "The Pizza is Yummy.1105nn",
        "priority": null,
        "status": "open",
        "recipient": null,
        "requester_id": *****,
        "submitter_id": *****,
        "assignee_id": *****,
        "organization_id": null,
        "group_id": *****,
        "collaborator_ids": [],
        "follower_ids": [],
        "email_cc_ids": [],
        "forum_topic_id": null,
        "problem_id": null,
        "has_incidents": false,
        "is_public": true,
        "due_at": null,
        "tags": [
            "jon",
            "test1105"
        ],
        "custom_fields": [],
        "satisfaction_rating": null,
        "sharing_agreement_ids": [],
        "fields": [],
        "followup_ids": [],
        "ticket_form_id": *****,
        "brand_id": *****,
        "allow_channelback": false,
        "allow_attachments": true,
        "result_type": "ticket"
    },
    {
        "url": "https://*****.zendesk.com/*****",
        "id": *****,
        "external_id": null,
        "via": {
            "channel": "api",
            "source": {
                "from": {},
                "to": {},
                "rel": null
            }
        },
        "created_at": "2021-11-05T23:45:11Z",
        "updated_at": "2021-11-05T23:45:11Z",
        "type": null,
        "subject": "Pizza Lunch 1105mm",
        "raw_subject": "Pizza Lunch 1105mm",
        "description": "The Pizza is Yummy.1105mm",
        "priority": null,
        "status": "open",
        "recipient": null,
        "requester_id": *****,
        "submitter_id": *****,
        "assignee_id": *****,
        "organization_id": null,
        "group_id": *****,
        "collaborator_ids": [],
        "follower_ids": [],
        "email_cc_ids": [],
        "forum_topic_id": null,
        "problem_id": null,
        "has_incidents": false,
        "is_public": true,
        "due_at": null,
        "tags": [],
        "custom_fields": [],
        "satisfaction_rating": null,
        "sharing_agreement_ids": [],
        "fields": [],
        "followup_ids": [],
        "ticket_form_id": *****,
        "brand_id": *****,
        "allow_channelback": false,
        "allow_attachments": true,
        "result_type": "ticket"
    },
    {
        "url": "https://*****.zendesk.com/*****",
        "id": *****,
        "external_id": null,
        "via": {
            "channel": "api",
            "source": {
                "from": {},
                "to": {},
                "rel": null
            }
        },
        "created_at": "2021-11-05T23:41:32Z",
        "updated_at": "2021-11-05T23:41:32Z",
        "type": null,
        "subject": "Pizza Lunch 1105ll",
        "raw_subject": "Pizza Lunch 1105ll",
        "description": "The Pizza is Yummy.1105ll",
        "priority": null,
        "status": "open",
        "recipient": null,
        "requester_id": *****,
        "submitter_id": *****,
        "assignee_id": *****,
        "organization_id": null,
        "group_id": *****,
        "collaborator_ids": [],
        "follower_ids": [],
        "email_cc_ids": [],
        "forum_topic_id": null,
        "problem_id": null,
        "has_incidents": false,
        "is_public": true,
        "due_at": null,
        "tags": [],
        "custom_fields": [],
        "satisfaction_rating": null,
        "sharing_agreement_ids": [],
        "fields": [],
        "followup_ids": [],
        "ticket_form_id": *****,
        "brand_id": *****,
        "allow_channelback": false,
        "allow_attachments": true,
        "result_type": "ticket"
    },
    {
        "url": "https://*****.zendesk.com/*****",
        "id": *****,
        "external_id": null,
        "via": {
            "channel": "api",
            "source": {
                "from": {},
                "to": {},
                "rel": null
            }
        },
        "created_at": "2021-11-05T23:32:34Z",
        "updated_at": "2021-11-05T23:32:34Z",
        "type": null,
        "subject": null,
        "raw_subject": null,
        "description": "The Pizza is Yummy.1105jj No Sub",
        "priority": "low",
        "status": "open",
        "recipient": null,
        "requester_id": *****,
        "submitter_id": *****,
        "assignee_id": *****,
        "organization_id": null,
        "group_id": *****,
        "collaborator_ids": [],
        "follower_ids": [],
        "email_cc_ids": [],
        "forum_topic_id": null,
        "problem_id": null,
        "has_incidents": false,
        "is_public": true,
        "due_at": null,
        "tags": [],
        "custom_fields": [],
        "satisfaction_rating": null,
        "sharing_agreement_ids": [],
        "fields": [],
        "followup_ids": [],
        "ticket_form_id": *****,
        "brand_id": *****,
        "allow_channelback": false,
        "allow_attachments": true,
        "result_type": "ticket"
    },
    {
        "url": "https://*****.zendesk.com/*****",
        "id": *****,
        "external_id": null,
        "via": {
            "channel": "api",
            "source": {
                "from": {},
                "to": {},
                "rel": null
            }
        },
        "created_at": "2021-11-05T19:11:53Z",
        "updated_at": "2021-11-05T19:11:53Z",
        "type": null,
        "subject": "TestTicket1001",
        "raw_subject": "TestTicket1001",
        "description": "TestTicket1001",
        "priority": "high",
        "status": "open",
        "recipient": null,
        "requester_id": *****,
        "submitter_id": *****,
        "assignee_id": *****,
        "organization_id": *****,
        "group_id": *****,
        "collaborator_ids": [],
        "follower_ids": [],
        "email_cc_ids": [],
        "forum_topic_id": null,
        "problem_id": null,
        "has_incidents": false,
        "is_public": true,
        "due_at": null,
        "tags": [],
        "custom_fields": [],
        "satisfaction_rating": null,
        "sharing_agreement_ids": [],
        "fields": [],
        "followup_ids": [],
        "ticket_form_id": *****,
        "brand_id": *****,
        "allow_channelback": false,
        "allow_attachments": true,
        "result_type": "ticket"
    },
    {
        "url": "https://*****.zendesk.com/*****",
        "id": *****,
        "external_id": null,
        "via": {
            "channel": "api",
            "source": {
                "from": {},
                "to": {},
                "rel": null
            }
        },
        "created_at": "2021-11-05T18:33:01Z",
        "updated_at": "2021-11-05T22:52:49Z",
        "type": null,
        "subject": "Pizza Lunch 1105ff",
        "raw_subject": "Pizza Lunch 1105ff",
        "description": "The Pizza is Yummy.1105ff",
        "priority": "low",
        "status": "open",
        "recipient": null,
        "requester_id": *****,
        "submitter_id": *****,
        "assignee_id": *****,
        "organization_id": null,
        "group_id": *****,
        "collaborator_ids": [],
        "follower_ids": [],
        "email_cc_ids": [],
        "forum_topic_id": null,
        "problem_id": null,
        "has_incidents": false,
        "is_public": true,
        "due_at": null,
        "tags": [],
        "custom_fields": [],
        "satisfaction_rating": null,
        "sharing_agreement_ids": [],
        "fields": [],
        "followup_ids": [],
        "ticket_form_id": *****,
        "brand_id": *****,
        "allow_channelback": false,
        "allow_attachments": true,
        "result_type": "ticket"
    },
    {
        "url": "https://*****.zendesk.com/*****",
        "id": *****,
        "external_id": null,
        "via": {
            "channel": "api",
            "source": {
                "from": {},
                "to": {},
                "rel": null
            }
        },
        "created_at": "2021-11-05T18:32:06Z",
        "updated_at": "2021-11-05T21:58:48Z",
        "type": null,
        "subject": "Pizza Lunch 1105",
        "raw_subject": "Pizza Lunch 1105",
        "description": "The Pizza is Yummy.1105ee",
        "priority": "low",
        "status": "open",
        "recipient": null,
        "requester_id": *****,
        "submitter_id": *****,
        "assignee_id": *****,
        "organization_id": *****,
        "group_id": *****,
        "collaborator_ids": [],
        "follower_ids": [],
        "email_cc_ids": [],
        "forum_topic_id": null,
        "problem_id": null,
        "has_incidents": false,
        "is_public": true,
        "due_at": null,
        "tags": [],
        "custom_fields": [],
        "satisfaction_rating": null,
        "sharing_agreement_ids": [],
        "fields": [],
        "followup_ids": [],
        "ticket_form_id": *****,
        "brand_id": *****,
        "allow_channelback": false,
        "allow_attachments": true,
        "result_type": "ticket"
    },
    {
        "url": "https://*****.zendesk.com/*****",
        "id": *****,
        "external_id": null,
        "via": {
            "channel": "api",
            "source": {
                "from": {},
                "to": {},
                "rel": null
            }
        },
        "created_at": "2021-11-05T18:30:43Z",
        "updated_at": "2021-11-05T18:30:43Z",
        "type": null,
        "subject": "My printer is on fire! 1105ee",
        "raw_subject": "My printer is on fire! 1105ee",
        "description": "The smoke is very colorful.",
        "priority": "urgent",
        "status": "open",
        "recipient": null,
        "requester_id": *****,
        "submitter_id": *****,
        "assignee_id": *****,
        "organization_id": *****,
        "group_id": *****,
        "collaborator_ids": [],
        "follower_ids": [],
        "email_cc_ids": [],
        "forum_topic_id": null,
        "problem_id": null,
        "has_incidents": false,
        "is_public": true,
        "due_at": null,
        "tags": [],
        "custom_fields": [],
        "satisfaction_rating": null,
        "sharing_agreement_ids": [],
        "fields": [],
        "followup_ids": [],
        "ticket_form_id": *****,
        "brand_id": *****,
        "allow_channelback": false,
        "allow_attachments": true,
        "result_type": "ticket"
    }
]

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

{
  "TicketIDs": [***, ***, ***, ***, ***, ***, ***, ***, ***]
}

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

url	https://***.zendesk.com/***	https://***.zendesk.com/***	https://***.zendesk.com/***	https://***.zendesk.com/***	https://***.zendesk.com/***	https://***.zendesk.com/***	https://***.zendesk.com/***	https://***.zendesk.com/***	https://***.zendesk.com/***
id	*****	*****	*****	*****	*****	*****	*****	*****	*****
external_id	None	None	None	None	None	None	None	None	None
via	{'channel': 'api', 'source': {'from': {}, 'to': {}, 'rel': None}}	{'channel': 'api', 'source': {'from': {}, 'to': {}, 'rel': None}}	{'channel': 'api', 'source': {'from': {}, 'to': {}, 'rel': None}}	{'channel': 'api', 'source': {'from': {}, 'to': {}, 'rel': None}}	{'channel': 'api', 'source': {'from': {}, 'to': {}, 'rel': None}}	{'channel': 'api', 'source': {'from': {}, 'to': {}, 'rel': None}}	{'channel': 'api', 'source': {'from': {}, 'to': {}, 'rel': None}}	{'channel': 'api', 'source': {'from': {}, 'to': {}, 'rel': None}}	{'channel': 'api', 'source': {'from': {}, 'to': {}, 'rel': None}}
created_at	2021-11-05T23:59:54Z	2021-11-05T23:47:01Z	2021-11-05T23:45:11Z	2021-11-05T23:41:32Z	2021-11-05T23:32:34Z	2021-11-05T19:11:53Z	2021-11-05T18:33:01Z	2021-11-05T18:32:06Z	2021-11-05T18:30:43Z
updated_at	2021-11-05T23:59:54Z	2021-11-05T23:47:01Z	2021-11-05T23:45:11Z	2021-11-05T23:41:32Z	2021-11-05T23:32:34Z	2021-11-05T19:11:53Z	2021-11-05T22:52:49Z	2021-11-05T21:58:48Z	2021-11-05T18:30:43Z
type	None	None	None	None	None	None	None	None	None
subject	Pizza Lunch 1105oo	Pizza Lunch 1105nn	Pizza Lunch 1105mm	Pizza Lunch 1105ll	None	TestTicket1001	Pizza Lunch 1105ff	Pizza Lunch 1105	My printer is on fire! 1105ee
raw_subject	Pizza Lunch 1105oo	Pizza Lunch 1105nn	Pizza Lunch 1105mm	Pizza Lunch 1105ll	None	TestTicket1001	Pizza Lunch 1105ff	Pizza Lunch 1105	My printer is on fire! 1105ee
description	The Pizza is Yummy.1105oo	The Pizza is Yummy.1105nn	The Pizza is Yummy.1105mm	The Pizza is Yummy.1105ll	The Pizza is Yummy.1105jj No Sub	TestTicket1001	The Pizza is Yummy.1105ff	The Pizza is Yummy.1105ee	The smoke is very colorful.
priority	high	None	None	None	low	high	low	low	urgent
status	open	open	open	open	open	open	open	open	open
recipient	None	None	None	None	None	None	None	None	None
requester_id	*****	*****	*****	*****	*****	*****	*****	*****	*****
submitter_id	*****	*****	*****	*****	*****	*****	*****	*****	*****
assignee_id	*****	*****	*****	*****	*****	*****	*****	*****	*****
organization_id	None	None	None	None	None	*****	None	*****	*****
group_id	*****	*****	*****	*****	*****	*****	*****	*****	*****
collaborator_ids	[]	[]	[]	[]	[]	[]	[]	[]	[]
follower_ids	[]	[]	[]	[]	[]	[]	[]	[]	[]
email_cc_ids	[]	[]	[]	[]	[]	[]	[]	[]	[]
forum_topic_id	None	None	None	None	None	None	None	None	None
problem_id	None	None	None	None	None	None	None	None	None
has_incidents	FALSE	FALSE	FALSE	FALSE	FALSE	FALSE	FALSE	FALSE	FALSE
is_public	TRUE	TRUE	TRUE	TRUE	TRUE	TRUE	TRUE	TRUE	TRUE
due_at	None	None	None	None	None	None	None	None	None
tags	['tag1', 'tag2']	['jon', 'test1105']	[]	[]	[]	[]	[]	[]	[]
custom_fields	[]	[]	[]	[]	[]	[]	[]	[]	[]
satisfaction_rating	None	None	None	None	None	None	None	None	None
sharing_agreement_ids	[]	[]	[]	[]	[]	[]	[]	[]	[]
fields	[]	[]	[]	[]	[]	[]	[]	[]	[]
followup_ids	[]	[]	[]	[]	[]	[]	[]	[]	[]
ticket_form_id	*****	*****	*****	*****	*****	*****	*****	*****	*****
brand_id	*****	*****	*****	*****	*****	*****	*****	*****	*****
allow_channelback	FALSE	FALSE	FALSE	FALSE	FALSE	FALSE	FALSE	FALSE	FALSE
allow_attachments	TRUE	TRUE	TRUE	TRUE	TRUE	TRUE	TRUE	TRUE	TRUE
result_type	ticket	ticket	ticket	ticket	ticket	ticket	ticket	ticket	ticket

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.	Search Tickets 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 Zendesk 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: Record Not Found.

Error Sample Data

Search Tickets failed.

Status Code: 404.

Message: Record Not Found.

List Users

Lists users with the specified role.

READER NOTE

Due to the limitations of the Zendesk API, the available input options for the User Role parameter are End-User, Agent and Admin. Light agent and contributor user roles will be returned when Agent is selected.

Input

Input Parameter	Required/Optional	Description	Example
User Role	Optional	The role of the users to retrieve. The valid input options are End-User, Agent, and Admin. If this parameter is not selected, all roles will be returned.	Agent

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

{
    "users": [
        {
            "id": *****,
            "url": "https://*****.zendesk.com/*****",
            "name": "*****",
            "email": "*****@*****.***",
            "created_at": "2021-10-29T04:31:23Z",
            "updated_at": "2021-11-06T01:24:09Z",
            "time_zone": "America/Vancouver",
            "iana_time_zone": "America/Vancouver",
            "phone": null,
            "shared_phone_number": null,
            "photo": null,
            "locale_id": *****,
            "locale": "en-US",
            "organization_id": *****,
            "role": "admin",
            "verified": true,
            "external_id": null,
            "tags": [],
            "alias": null,
            "active": true,
            "shared": false,
            "shared_agent": false,
            "last_login_at": "2021-11-06T01:24:09Z",
            "two_factor_auth_enabled": null,
            "signature": null,
            "details": null,
            "notes": null,
            "role_type": null,
            "custom_role_id": null,
            "moderator": true,
            "ticket_restriction": null,
            "only_private_comments": false,
            "restricted_agent": false,
            "suspended": false,
            "default_group_id": *****,
            "report_csv": true,
            "user_fields": {}
        },
        {
            "id": *****,
            "url": "https://*****.zendesk.com/*****",
            "name": "*****",
            "email": "*****@*****.***",
            "created_at": "2021-10-29T04:31:32Z",
            "updated_at": "2021-10-29T04:31:33Z",
            "time_zone": "America/Vancouver",
            "iana_time_zone": "America/Vancouver",
            "phone": null,
            "shared_phone_number": null,
            "photo": {
                "url": "https://*****.zendesk.com/*****",
                "id": *****,
                "file_name": "profile_image_*****_*****.png",
                "content_url": "https://*****.zendesk.com/*****",
                "mapped_content_url": "https://*****.zendesk.com/*****",
                "content_type": "image/png",
                "size": 10254,
                "width": 80,
                "height": 80,
                "inline": false,
                "deleted": false,
                "thumbnails": [
                    {
                        "url": "https://*****.zendesk.com/*****",
                        "id": *****,
                        "file_name": "profile_image_*****_*****_thumb.png",
                        "content_url": "https://*****.zendesk.com/*****",
                        "mapped_content_url": "https://*****.zendesk.com/*****",
                        "content_type": "image/png",
                        "size": 2402,
                        "width": 32,
                        "height": 32,
                        "inline": false,
                        "deleted": false
                    }
                ]
            },
            "locale_id": *****,
            "locale": "en-US",
            "organization_id": null,
            "role": "end-user",
            "verified": false,
            "external_id": null,
            "tags": [],
            "alias": null,
            "active": true,
            "shared": false,
            "shared_agent": false,
            "last_login_at": null,
            "two_factor_auth_enabled": false,
            "signature": null,
            "details": null,
            "notes": null,
            "role_type": null,
            "custom_role_id": null,
            "moderator": false,
            "ticket_restriction": "requested",
            "only_private_comments": false,
            "restricted_agent": true,
            "suspended": false,
            "default_group_id": null,
            "report_csv": false,
            "user_fields": {}
        },
        {
            "id": *****,
            "url": "https://*****.zendesk.com/*****",
            "name": "*****",
            "email": "*****@d3security.com",
            "created_at": "2021-11-05T18:13:10Z",
            "updated_at": "2021-11-05T22:39:49Z",
            "time_zone": "America/Vancouver",
            "iana_time_zone": "America/Vancouver",
            "phone": null,
            "shared_phone_number": null,
            "photo": null,
            "locale_id": *****,
            "locale": "en-US",
            "organization_id": null,
            "role": "admin",
            "verified": true,
            "external_id": null,
            "tags": [],
            "alias": null,
            "active": true,
            "shared": false,
            "shared_agent": false,
            "last_login_at": "2021-11-05T21:19:58Z",
            "two_factor_auth_enabled": null,
            "signature": null,
            "details": null,
            "notes": null,
            "role_type": null,
            "custom_role_id": null,
            "moderator": true,
            "ticket_restriction": null,
            "only_private_comments": false,
            "restricted_agent": false,
            "suspended": false,
            "default_group_id": *****,
            "report_csv": true,
            "user_fields": {}
        },
        {
            "id": *****,
            "url": "https://*****.zendesk.com/*****",
            "name": "support",
            "email": "*****@*****.***",
            "created_at": "2021-11-05T22:28:22Z",
            "updated_at": "2021-11-05T22:50:48Z",
            "time_zone": "America/Vancouver",
            "iana_time_zone": "America/Vancouver",
            "phone": null,
            "shared_phone_number": null,
            "photo": null,
            "locale_id": *****,
            "locale": "en-US",
            "organization_id": null,
            "role": "agent",
            "verified": false,
            "external_id": null,
            "tags": [],
            "alias": "",
            "active": true,
            "shared": false,
            "shared_agent": false,
            "last_login_at": null,
            "two_factor_auth_enabled": null,
            "signature": "",
            "details": "",
            "notes": "",
            "role_type": null,
            "custom_role_id": null,
            "moderator": false,
            "ticket_restriction": "groups",
            "only_private_comments": false,
            "restricted_agent": true,
            "suspended": false,
            "default_group_id": *****,
            "report_csv": false,
            "user_fields": {}
        },
        {
            "id": *****,
            "url": "https://*****.zendesk.com/*****",
            "name": "*****",
            "email": "*****@d3security.com",
            "created_at": "2021-11-05T22:31:03Z",
            "updated_at": "2021-11-05T22:31:04Z",
            "time_zone": "America/Vancouver",
            "iana_time_zone": "America/Vancouver",
            "phone": null,
            "shared_phone_number": null,
            "photo": null,
            "locale_id": *****,
            "locale": "en-US",
            "organization_id": null,
            "role": "admin",
            "verified": false,
            "external_id": null,
            "tags": [],
            "alias": null,
            "active": true,
            "shared": false,
            "shared_agent": false,
            "last_login_at": null,
            "two_factor_auth_enabled": null,
            "signature": null,
            "details": null,
            "notes": null,
            "role_type": null,
            "custom_role_id": null,
            "moderator": true,
            "ticket_restriction": null,
            "only_private_comments": false,
            "restricted_agent": false,
            "suspended": false,
            "default_group_id": *****,
            "report_csv": true,
            "user_fields": {}
        },
        {
            "id": *****,
            "url": "https://*****.zendesk.com/*****",
            "name": "*****",
            "email": "*****@*****.***",
            "created_at": "2021-11-05T18:26:04Z",
            "updated_at": "2021-11-05T20:28:26Z",
            "time_zone": "America/Vancouver",
            "iana_time_zone": "America/Vancouver",
            "phone": null,
            "shared_phone_number": null,
            "photo": null,
            "locale_id": *****,
            "locale": "en-US",
            "organization_id": null,
            "role": "agent",
            "verified": true,
            "external_id": null,
            "tags": [],
            "alias": null,
            "active": true,
            "shared": false,
            "shared_agent": false,
            "last_login_at": "2021-11-05T18:37:01Z",
            "two_factor_auth_enabled": null,
            "signature": null,
            "details": null,
            "notes": null,
            "role_type": null,
            "custom_role_id": null,
            "moderator": false,
            "ticket_restriction": null,
            "only_private_comments": false,
            "restricted_agent": false,
            "suspended": false,
            "default_group_id": *****,
            "report_csv": false,
            "user_fields": {}
        }
    ],
    "next_page": null,
    "previous_page": null,
    "count": 6
}

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

[
    {
        "id": *****,
        "url": "https://*****.zendesk.com/*****",
        "name": "*****",
        "email": "*****@*****.***",
        "created_at": "2021-10-29T04:31:23Z",
        "updated_at": "2021-11-06T01:24:09Z",
        "time_zone": "America/Vancouver",
        "iana_time_zone": "America/Vancouver",
        "phone": null,
        "shared_phone_number": null,
        "photo": null,
        "locale_id": *****,
        "locale": "en-US",
        "organization_id": *****,
        "role": "admin",
        "verified": true,
        "external_id": null,
        "tags": [],
        "alias": null,
        "active": true,
        "shared": false,
        "shared_agent": false,
        "last_login_at": "2021-11-06T01:24:09Z",
        "two_factor_auth_enabled": null,
        "signature": null,
        "details": null,
        "notes": null,
        "role_type": null,
        "custom_role_id": null,
        "moderator": true,
        "ticket_restriction": null,
        "only_private_comments": false,
        "restricted_agent": false,
        "suspended": false,
        "default_group_id": *****,
        "report_csv": true,
        "user_fields": {}
    },
    {
        "id": *****,
        "url": "https://*****.zendesk.com/*****",
        "name": "*****",
        "email": "*****@*****.***",
        "created_at": "2021-10-29T04:31:32Z",
        "updated_at": "2021-10-29T04:31:33Z",
        "time_zone": "America/Vancouver",
        "iana_time_zone": "America/Vancouver",
        "phone": null,
        "shared_phone_number": null,
        "photo": {
            "url": "https://*****.zendesk.com/*****",
            "id": *****,
            "file_name": "profile_image_*****_*****.png",
            "content_url": "https://*****.zendesk.com/*****",
            "mapped_content_url": "https://*****.zendesk.com/*****",
            "content_type": "image/png",
            "size": 10254,
            "width": 80,
            "height": 80,
            "inline": false,
            "deleted": false,
            "thumbnails": [
                {
                    "url": "https://*****.zendesk.com/*****",
                    "id": *****,
                    "file_name": "profile_image_*****_*****_thumb.png",
                    "content_url": "https://*****.zendesk.com/*****",
                    "mapped_content_url": "https://*****.zendesk.com/*****",
                    "content_type": "image/png",
                    "size": *****40*****,
                    "width": 3*****,
                    "height": 3*****,
                    "inline": false,
                    "deleted": false
                }
            ]
        },
        "locale_id": *****,
        "locale": "en-US",
        "organization_id": null,
        "role": "end-user",
        "verified": false,
        "external_id": null,
        "tags": [],
        "alias": null,
        "active": true,
        "shared": false,
        "shared_agent": false,
        "last_login_at": null,
        "two_factor_auth_enabled": false,
        "signature": null,
        "details": null,
        "notes": null,
        "role_type": null,
        "custom_role_id": null,
        "moderator": false,
        "ticket_restriction": "requested",
        "only_private_comments": false,
        "restricted_agent": true,
        "suspended": false,
        "default_group_id": null,
        "report_csv": false,
        "user_fields": {}
    },
    {
        "id": *****,
        "url": "https://*****.zendesk.com/*****",
        "name": "*****",
        "email": "*****@d3security.com",
        "created_at": "2021-11-05T18:13:10Z",
        "updated_at": "2021-11-05T22:39:49Z",
        "time_zone": "America/Vancouver",
        "iana_time_zone": "America/Vancouver",
        "phone": null,
        "shared_phone_number": null,
        "photo": null,
        "locale_id": *****,
        "locale": "en-US",
        "organization_id": null,
        "role": "admin",
        "verified": true,
        "external_id": null,
        "tags": [],
        "alias": null,
        "active": true,
        "shared": false,
        "shared_agent": false,
        "last_login_at": "2021-11-05T21:19:58Z",
        "two_factor_auth_enabled": null,
        "signature": null,
        "details": null,
        "notes": null,
        "role_type": null,
        "custom_role_id": null,
        "moderator": true,
        "ticket_restriction": null,
        "only_private_comments": false,
        "restricted_agent": false,
        "suspended": false,
        "default_group_id": *****,
        "report_csv": true,
        "user_fields": {}
    },
    {
        "id": *****,
        "url": "https://*****.zendesk.com/*****",
        "name": "support",
        "email": "*****@*****.***",
        "created_at": "2021-11-05T22:28:22Z",
        "updated_at": "2021-11-05T22:50:48Z",
        "time_zone": "America/Vancouver",
        "iana_time_zone": "America/Vancouver",
        "phone": null,
        "shared_phone_number": null,
        "photo": null,
        "locale_id": *****,
        "locale": "en-US",
        "organization_id": null,
        "role": "agent",
        "verified": false,
        "external_id": null,
        "tags": [],
        "alias": "",
        "active": true,
        "shared": false,
        "shared_agent": false,
        "last_login_at": null,
        "two_factor_auth_enabled": null,
        "signature": "",
        "details": "",
        "notes": "",
        "role_type": null,
        "custom_role_id": null,
        "moderator": false,
        "ticket_restriction": "groups",
        "only_private_comments": false,
        "restricted_agent": true,
        "suspended": false,
        "default_group_id": *****,
        "report_csv": false,
        "user_fields": {}
    },
    {
        "id": *****,
        "url": "https://*****.zendesk.com/*****",
        "name": "*****",
        "email": "*****@d3security.com",
        "created_at": "2021-11-05T22:31:03Z",
        "updated_at": "2021-11-05T22:31:04Z",
        "time_zone": "America/Vancouver",
        "iana_time_zone": "America/Vancouver",
        "phone": null,
        "shared_phone_number": null,
        "photo": null,
        "locale_id": *****,
        "locale": "en-US",
        "organization_id": null,
        "role": "admin",
        "verified": false,
        "external_id": null,
        "tags": [],
        "alias": null,
        "active": true,
        "shared": false,
        "shared_agent": false,
        "last_login_at": null,
        "two_factor_auth_enabled": null,
        "signature": null,
        "details": null,
        "notes": null,
        "role_type": null,
        "custom_role_id": null,
        "moderator": true,
        "ticket_restriction": null,
        "only_private_comments": false,
        "restricted_agent": false,
        "suspended": false,
        "default_group_id": *****,
        "report_csv": true,
        "user_fields": {}
    },
    {
        "id": *****,
        "url": "https://*****.zendesk.com/*****",
        "name": "*****",
        "email": "*****@*****.***",
        "created_at": "2021-11-05T18:26:04Z",
        "updated_at": "2021-11-05T20:28:26Z",
        "time_zone": "America/Vancouver",
        "iana_time_zone": "America/Vancouver",
        "phone": null,
        "shared_phone_number": null,
        "photo": null,
        "locale_id": *****,
        "locale": "en-US",
        "organization_id": null,
        "role": "agent",
        "verified": true,
        "external_id": null,
        "tags": [],
        "alias": null,
        "active": true,
        "shared": false,
        "shared_agent": false,
        "last_login_at": "2021-11-05T18:37:01Z",
        "two_factor_auth_enabled": null,
        "signature": null,
        "details": null,
        "notes": null,
        "role_type": null,
        "custom_role_id": null,
        "moderator": false,
        "ticket_restriction": null,
        "only_private_comments": false,
        "restricted_agent": false,
        "suspended": false,
        "default_group_id": *****,
        "report_csv": false,
        "user_fields": {}
    }
]

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

{
  "UserIDs": [***, ***, ***, ***, ***, ***],
  "UserNames": ["*****", "*****", "*****", "*****", "*****", "*****"],
  "Emails": ["*****@*****.***", "*****@*****.***", "*****@*****.***", "*****@*****.***", "*****@*****.***"]
}

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

id	*****	*****	*****	*****	*****	*****
url	https://***.zendesk.com/***	https://***.zendesk.com/***	https://***.zendesk.com/***	https://***.zendesk.com/***	https://***.zendesk.com/***	https://***.zendesk.com/***
name	*****	*****	*****	support	*****	*****
email	***@*.*	***@*.*	***@*.*	***@*.*	***@*.*	***@*.*
created_at	2021-10-29T04:31:23Z	2021-10-29T04:31:32Z	2021-11-05T18:13:10Z	2021-11-05T22:28:22Z	2021-11-05T22:31:03Z	2021-11-05T18:26:04Z
updated_at	2021-11-06T01:24:09Z	2021-10-29T04:31:33Z	2021-11-05T22:39:49Z	2021-11-05T22:50:48Z	2021-11-05T22:31:04Z	2021-11-05T20:28:26Z
time_zone	America/Vancouver	America/Vancouver	America/Vancouver	America/Vancouver	America/Vancouver	America/Vancouver
iana_time_zone	America/Vancouver	America/Vancouver	America/Vancouver	America/Vancouver	America/Vancouver	America/Vancouver
phone	None	None	None	None	None	None
shared_phone_number	None	None	None	None	None	None
photo	None	{'url': 'https://***.zendesk.com/*', 'id': *, 'file_name': 'profile_image_*_*.png', 'content_url': 'https://*.zendesk.com/* ', 'mapped_content_url': 'https://*.zendesk.com/* ', 'content_type': 'image/png', 'size': 10254, 'width': 80, 'height': 80, 'inline': False, 'deleted': False, 'thumbnails': [{'url': 'https://*.zendesk.com/*', 'id': *, 'file_name': 'profile_image_*_*_thumb.png', 'content_url': 'https://*.zendesk.com/* ', 'mapped_content_url': 'https://*.zendesk.com/* ', 'content_type': 'image/png', 'size': *40*, 'width': 3*, 'height': 3***, 'inline': False, 'deleted': False}]}	None	None	None	None
locale_id	1	1	1	1	1	1
locale	en-US	en-US	en-US	en-US	en-US	en-US
organization_id	*****	None	None	None	None	None
role	admin	end-user	admin	agent	admin	agent
verified	TRUE	FALSE	TRUE	FALSE	FALSE	TRUE
external_id	None	None	None	None	None	None
tags	[]	[]	[]	[]	[]	[]
alias	None	None	None		None	None
active	TRUE	TRUE	TRUE	TRUE	TRUE	TRUE
shared	FALSE	FALSE	FALSE	FALSE	FALSE	FALSE
shared_agent	FALSE	FALSE	FALSE	FALSE	FALSE	FALSE
last_login_at	2021-11-06T01:24:09Z	None	2021-11-05T21:19:58Z	None	None	2021-11-05T18:37:01Z
two_factor_auth_enabled	None	FALSE	None	None	None	None
signature	None	None	None		None	None
details	None	None	None		None	None
notes	None	None	None		None	None
role_type	None	None	None	None	None	None
custom_role_id	None	None	None	None	None	None
moderator	TRUE	FALSE	TRUE	FALSE	TRUE	FALSE
ticket_restriction	None	requested	None	groups	None	None
only_private_comments	FALSE	FALSE	FALSE	FALSE	FALSE	FALSE
restricted_agent	FALSE	TRUE	FALSE	TRUE	FALSE	FALSE
suspended	FALSE	FALSE	FALSE	FALSE	FALSE	FALSE
default_group_id	*****	None	*****	*****	*****	*****
report_csv	TRUE	FALSE	TRUE	FALSE	TRUE	FALSE
user_fields	{}	{}	{}	{}	{}	{}

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 Users 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 Zendesk 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: You must have a valid Support account to call this API.

Error Sample Data

List Users failed.

Status Code: 403.

Message: You must have a valid Support account to call this API.

Update Organization

Updates fields in the specified organization.

READER NOTE

Organization ID is a required parameter to run this command.
- Run the List Organizations command to obtain the Organization ID. Organization IDs can be found in the raw data at the path $.organizations.id.
Group ID and Organization Fields are optional parameters to run this command.
- Run the List Groups command to obtain the Group ID. Group ID can be found in hte raw data at the path $.groups[*].id.
- You can view and add organization fields from the Zendesk user interface. In the Zendesk Admin Center, navigate to People > Configuration > Organization Fields. See Adding custom fields to organizations from Zendesk help for instructions on creating custom organization fields.
- After adding a custom field (e.g. organization_type), you can update the field in the Organizations Fields parameter (e.g. {"organization_type":"default"}). The custom field will be updated after running the command. Run the List Organization to view any updates made to custom organization fields. Check the raw data at the path $.organizations[*].organization_fields.
Existing tickets will not be updated with the input organization tags by running this command.
The User Can Add Comments parameter is only applicable when the Users Can View All Organization Tickets is set to true. Otherwise, the command will be ignored.

Input

Input Parameter	Required/Optional	Description	Example
Organization ID	Required	The ID of the organization to update. Organization IDs can be obtained using the List Organizations command.	*****
Organization Name	Optional	The updated name of the organization.	D3 cyber lab
Notes	Optional	The notes about the organization. Note: Notes are only visible to admins and agents.	Important Client!
Details	Optional	The organization information (e.g. address). Notes: Details are only visible to admins and agents.	Address1
Group ID	Optional	The ID of the agent group to assign incoming tickets from users in the organization to. Group IDs can be obtained using the List Groups command.	*****
Domains	Optional	Emails from these domains will be added to the organization.	[ "acme.com", "ajax.com" ]
Tags	Optional	The tags to add to tickets requested by users in the organization. You can restrict forum access by tags.	[ "tag1", "tag2" ]
Users Can View All Organization Tickets	Optional	Specifies if users can view all the tickets in this organization.	True
Users Can Add Comments	Optional	Specifies if users can add comments to tickets in this organization. Note: This parameter is only valid if users have permission to view all organization tickets.	True
Organization Fields	Optional	The custom fields for the organization in JSON format. Custom organization fields can be created from Zendesk and viewed using the List Organizations command.	{ "default_zendesk_requester_id": "DefaultUser" }

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

{
    "organization": {
        "url": "https://*****.zendesk.com/*****",
        "id": *****,
        "name": "D3 cyber lab",
        "shared_tickets": true,
        "shared_comments": false,
        "external_id": null,
        "created_at": "2022-02-07T19:15:01Z",
        "updated_at": "2022-02-16T00:08:33Z",
        "domain_names": [
            "acme.com",
            "ajax.com"
        ],
        "details": "address_1",
        "notes": "Important Client!",
        "group_id": *****,
        "tags": [
            "tag1",
            "tag2"
        ],
        "organization_fields": {
            "default_zendesk_requester_id": "defaultUser",
            "support_description": "DEScription"
        }
    }
}

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

{
    "url": "https://*****.zendesk.com/*****",
    "id": *****,
    "name": "D3 cyber lab",
    "shared_tickets": true,
    "shared_comments": false,
    "external_id": null,
    "created_at": "2022-02-07T19:15:01Z",
    "updated_at": "2022-02-16T00:08:33Z",
    "domain_names": [
        "acme.com",
        "ajax.com"
    ],
    "details": "address_1",
    "notes": "Important Client!",
    "group_id": *****,
    "tags": [
        "tag1",
        "tag2"
    ],
    "organization_fields": {
        "default_zendesk_requester_id": "defaultUser",
        "support_description": "DEScription"
    }
}

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

url	https://***.zendesk.com/***
id	*****
name	D3 cyber lab
shared_tickets	True
shared_comments	False
external_id	None
created_at	2022-02-07T19:15:01Z
updated_at	2022-02-16T00:08:33Z
domain_names	http://acme.com http://ajax.com
details	address_1
notes	Important Client!
group_id	*****
tags	tag1 tag2
organization_fields	{'default_zendesk_requester_id': 'defaultUser', 'support_description': 'DEScription'}

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.	Update Organization 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 Zendesk 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: Organization ID Not Found.

Error Sample Data

Update Organization failed.

Status Code: 404.

Message: Organization ID Not Found.

Update Ticket

Update the content of the specified ticket.

READER NOTE

Ticket ID is a required parameter to run this command.

Run the List Ticket command to obtain the Ticket ID. Ticket IDs can be found in the raw data at the path $.tickets[*].id.

Requester Email and Assignee Email are optional parameters to run this command.

Run the List Users command to obtain the Requester Email and Assignee Email. Emails can be found in the raw data at the path $.users[*].email.

Input

Input Parameter	Required/Optional	Description	Example
Ticket ID	Required	The ID of the ticket to update. Ticket IDs can be obtained using the List Tickets command.	*****
Subject	Optional	The updated subject of the ticket. If this parameter is not defined, the previous subject will be unchanged.	Product Setup Issue
Priority	Optional	The updated priority level of the ticket.	Normal
Tags	Optional	The updated tags of the ticket.	["tag1","tag2"]
Requester Email	Optional	The updated email address of the user requesting the ticket. Requester emails can be obtained using the List Users command.	*****@d3security.com
Assignee Email	Optional	The email address of the assigned user. Assignee emails can be obtained using the List Users command.	*****@d3soar.com
Status	Optional	The updated status of the ticket.	Solved
Comment	Optional	The updated comment text of the ticket.	Test comment
Additional Fields	Optional	The additional fields to add in JSON format. See Tickets from Zendesk’s Developer Docs for the list of available fields. Note: If the input JSON object contains the comment, subject, raw_subject, priority, status, tags, requester and assignee_email fields, then the field value will overwrite the value of the corresponding input parameter. The read-only field can not be updated.	{ "recipient": "*****@security.com" }

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

{
    "ticket": {
        "url": "https://*****.zendesk.com/*****",
        "id": *****,
        "external_id": null,
        "via": {
            "channel": "api",
            "source": {
                "from": {},
                "to": {},
                "rel": null
            }
        },
        "created_at": "2022-02-04T01:34:24Z",
        "updated_at": "2022-02-04T01:49:28Z",
        "type": "task",
        "subject": "NEW Subject.0203a",
        "raw_subject": "NEW Subject.0203a",
        "description": "start working",
        "priority": "normal",
        "status": "open",
        "recipient": null,
        "requester_id": *****,
        "submitter_id": *****,
        "assignee_id": *****,
        "organization_id": *****,
        "group_id": *****,
        "collaborator_ids": [],
        "follower_ids": [],
        "email_cc_ids": [],
        "forum_topic_id": null,
        "problem_id": null,
        "has_incidents": false,
        "is_public": true,
        "due_at": null,
        "tags": [
            "installation"
        ],
        "custom_fields": [],
        "satisfaction_rating": null,
        "sharing_agreement_ids": [],
        "fields": [],
        "followup_ids": [],
        "ticket_form_id": *****,
        "brand_id": *****,
        "allow_channelback": false,
        "allow_attachments": true
    },
    "audit": {
        "id": *****,
        "ticket_id": *****,
        "created_at": "2022-02-04T01:49:28Z",
        "author_id": *****,
        "metadata": {
            "system": {
                "client": "PostmanRuntime/7.29.0",
                "ip_address": "***.***.***.***",
                "location": "Vancouver, BC, Canada",
                "latitude": 49.25*****,
                "longitude": -123.0972
            },
            "custom": {}
        },
        "events": [
            {
                "id": *****,
                "type": "Change",
                "value": "NEW Subject.0203a",
                "field_name": "subject",
                "previous_value": "Pizza Yummy"
            }
        ],
        "via": {
            "channel": "api",
            "source": {
                "from": {},
                "to": {},
                "rel": null
            }
        }
    }
}

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

{
  "ticket": {
    "url": "https://*****.zendesk.com/*****",
    "id": *****,
    "external_id": null,
    "via": {
      "channel": "api",
      "source": {
        "from": {},
        "to": {},
        "rel": null
      }
    },
    "created_at": "2022-02-04T01:34:24Z",
    "updated_at": "2022-02-04T01:49:28Z",
    "type": "task",
    "subject": "NEW Subject.0203a",
    "raw_subject": "NEW Subject.0203a",
    "description": "start working",
    "priority": "normal",
    "status": "open",
    "recipient": null,
    "requester_id": *****,
    "submitter_id": *****,
    "assignee_id": *****,
    "organization_id": *****,
    "group_id": *****,
    "collaborator_ids": [],
    "follower_ids": [],
    "email_cc_ids": [],
    "forum_topic_id": null,
    "problem_id": null,
    "has_incidents": false,
    "is_public": true,
    "due_at": null,
    "tags": [
      "installation"
    ],
    "custom_fields": [],
    "satisfaction_rating": null,
    "sharing_agreement_ids": [],
    "fields": [],
    "followup_ids": [],
    "ticket_form_id": *****,
    "brand_id": *****,
    "allow_channelback": false,
    "allow_attachments": true
  }
}

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

{
  "TicketID": *****
}

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.	Update Ticket 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 Zendesk 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: Can not find the assignee by email address.

Error Sample Data

Update Ticket failed.

Status Code: 404.

Message: Can not find the assignee by email address.

Upload File To Ticket

Upload a file and add it to the specified ticket.

READER NOTE

Ticket ID is a required parameter to run this command.

Run List Tickets command to obtain the Ticket ID. Ticket IDs can be found in the raw data at the path $.tickets[*].id.

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:

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
Ticket ID	Required	The ID of the ticket to which the uploaded file is added. The ticket ID can be obtained from the List Tickets command.	*****
File IDs	Required	Chooses the file path according to the file source. The options for file paths are: Incident Attachment: Incident.file.file ID Playbook File: Task output Artifact File: Incident.Events.file.file ID	[ "*****" ]
File Source	Required	Specifies the file source. 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 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

{
    "ticket": {
        "url": "https://*****.zendesk.com/*****",
        "id": *****,
        "external_id": null,
        "via": {
            "channel": "api",
            "source": {
                "from": {},
                "to": {},
                "rel": null
            }
        },
        "created_at": "2021-11-05T23:36:08Z",
        "updated_at": "2021-11-06T04:50:09Z",
        "type": null,
        "subject": "No Sub?",
        "raw_subject": "No Sub?",
        "description": "1105jj description No Subject",
        "priority": "normal",
        "status": "new",
        "recipient": null,
        "requester_id": *****,
        "submitter_id": *****,
        "assignee_id": null,
        "organization_id": *****,
        "group_id": *****,
        "collaborator_ids": [],
        "follower_ids": [],
        "email_cc_ids": [],
        "forum_topic_id": null,
        "problem_id": null,
        "has_incidents": false,
        "is_public": true,
        "due_at": null,
        "tags": [
            "jon"
        ],
        "custom_fields": [],
        "satisfaction_rating": null,
        "sharing_agreement_ids": [],
        "fields": [],
        "followup_ids": [],
        "ticket_form_id": *****,
        "brand_id": *****,
        "allow_channelback": false,
        "allow_attachments": true
    },
    "audit": {
        "id": *****,
        "ticket_id": *****,
        "created_at": "2021-11-06T04:50:09Z",
        "author_id": *****,
        "metadata": {
            "system": {
                "client": "PostmanRuntime/7.28.3",
                "ip_address": "***.***.***.***",
                "location": "Vancouver, BC, Canada",
                "latitude": 49.25*****,
                "longitude": -123.0972
            },
            "custom": {}
        },
        "events": [
            {
                "id": *****,
                "type": "Comment",
                "author_id": *****,
                "body": "Two pictures attached to Ticket 13.",
                "html_body": "<div class=\"zd-comment\" dir=\"auto\"><p dir=\"auto\">Two pictures attached to Ticket 13.</p></div>",
                "plain_body": "Two pictures attached to Ticket 13.",
                "public": true,
                "attachments": [
                    {
                        "url": "https://*****.zendesk.com/*****",
                        "id": *****,
                        "file_name": "pic1.jpg",
                        "content_url": "https://*****.zendesk.com/*****",
                        "mapped_content_url": "https://*****.zendesk.com/*****",
                        "content_type": "image/jpeg",
                        "size": 3840,
                        "width": 225,
                        "height": 225,
                        "inline": false,
                        "deleted": false,
                        "thumbnails": [
                            {
                                "url": "https://*****.zendesk.com/*****",
                                "id": *****,
                                "file_name": "pic1_thumb.jpg",
                                "content_url": "https://*****.zendesk.com/*****",
                                "mapped_content_url": "https://*****.zendesk.com/*****",
                                "content_type": "image/jpeg",
                                "size": 382*****,
                                "width": 80,
                                "height": 80,
                                "inline": false,
                                "deleted": false
                            }
                        ]
                    },
                    {
                        "url": "https://*****.zendesk.com/*****",
                        "id": *****,
                        "file_name": "pic2.jfif",
                        "content_url": "https://*****.zendesk.com/*****",
                        "mapped_content_url": "https://*****.zendesk.com/*****",
                        "content_type": "image/jpeg",
                        "size": 6972,
                        "width": 500,
                        "height": 750,
                        "inline": false,
                        "deleted": false,
                        "thumbnails": [
                            {
                                "url": "https://*****.zendesk.com/*****",
                                "id": *****,
                                "file_name": "pic2_thumb.jfif",
                                "content_url": "https://*****.zendesk.com/*****",
                                "mapped_content_url": "https://*****.zendesk.com/*****",
                                "content_type": "image/jpeg",
                                "size": 1655,
                                "width": 53,
                                "height": 80,
                                "inline": false,
                                "deleted": false
                            }
                        ]
                    }
                ],
                "audit_id": *****
            },
            {
                "id": *****,
                "type": "Notification",
                "via": {
                    "channel": "rule",
                    "source": {
                        "from": {
                            "deleted": false,
                            "title": "Notify requester and CCs of comment update",
                            "id": *****
                        },
                        "rel": "trigger"
                    }
                },
                "subject": "[{{ticket.account}}] Re: {{ticket.title}}",
                "body": "Your request ({{ticket.id}}) has been updated. To add additional comments, reply to this email.\n{{ticket.comments_formatted}}",
                "recipients": [
                    *****
                ]
            }
        ],
        "via": {
            "channel": "api",
            "source": {
                "from": {},
                "to": {
                    "name": "*****",
                    "address": "*****@*****.***"
                },
                "rel": null
            }
        }
    }
}

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

{
    "url": "https://*****.zendesk.com/*****",
    "id": *****,
    "external_id": null,
    "via": {
        "channel": "api",
        "source": {
            "from": {},
            "to": {},
            "rel": null
        }
    },
    "created_at": "2021-11-05T23:36:08Z",
    "updated_at": "2021-11-06T04:50:09Z",
    "type": null,
    "subject": "No Sub?",
    "raw_subject": "No Sub?",
    "description": "1105jj description No Subject",
    "priority": "normal",
    "status": "new",
    "recipient": null,
    "requester_id": *****,
    "submitter_id": *****,
    "assignee_id": null,
    "organization_id": *****,
    "group_id": *****,
    "collaborator_ids": [],
    "follower_ids": [],
    "email_cc_ids": [],
    "forum_topic_id": null,
    "problem_id": null,
    "has_incidents": false,
    "is_public": true,
    "due_at": null,
    "tags": [
        "jon"
    ],
    "custom_fields": [],
    "satisfaction_rating": null,
    "sharing_agreement_ids": [],
    "fields": [],
    "followup_ids": [],
    "ticket_form_id": *****,
    "brand_id": *****,
    "allow_channelback": false,
    "allow_attachments": true
}

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

{
  "AttachmentFileNames": ["*****.png","*****.xlsm"]
}

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

url	https://***.zendesk.com/***
id	*****
external_id	None
via	{'channel': 'api', 'source': {'from': {}, 'to': {}, 'rel': None}}
created_at	2021-11-05T23:36:08Z
updated_at	2021-11-06T04:50:09Z
type	None
subject	No Sub?
raw_subject	No Sub?
description	1105jj description No Subject
priority	normal
status	new
recipient	None
requester_id	*****
submitter_id	*****
assignee_id	None
organization_id	*****
group_id	*****
collaborator_ids	[]
follower_ids	[]
email_cc_ids	[]
forum_topic_id	None
problem_id	None
has_incidents	False
is_public	True
due_at	None
tags	jon
custom_fields	[]
satisfaction_rating	None
sharing_agreement_ids	[]
fields	[]
followup_ids	[]
ticket_form_id	*****
brand_id	*****
allow_channelback	False
allow_attachments	True

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.	Upload File To Ticket 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 Zendesk 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: D3 download file failed:"The specified File does not exist".

Error Sample Data

Upload File To Ticket failed.

Status Code: 404.

Message: D3 download file failed:"The specified File does not exist".

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.

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.	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 Zendesk 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: You must have a valid support account to call this API.

Error Sample Data

Test Connection failed. Failed to check the connector.

Status Code: 403.

Message: You must have a valid Support account to call this API