Freshservice

Overview

Freshservice provides an intelligent, right-sized service management solution for modern businesses of all sizes. Freshservice does this by taking a fresh approach to building and delivering modern employee experiences and unified service management —empowering businesses to achieve efficiency, fast time-to-value, and improved employee satisfaction and productivity.

D3 SOAR is providing REST operations to function with Freshservice.

Freshservice is available for use in:

D3 SOAR	V14.0.576+
Category	ITSM
Deployment Options	Option II, Option IV

Known Limitations

Certain rate limits are imposed when using Freshservice's API. Refer to The Freshservice API from Freshservice's documentation for more information.

Connection

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

Parameter	Description	Example
Server URL	The server URL of the Freshservice API.	https://domain.freshservice.com
API Key	The API key for authentication.	YOUR_API_Key
API Version	The version of the API to use for the connection.	v2

Permission Requirements

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

Command	Required Permission
Close Tickets	Agent Roles > Tickets > View Tickets + Edit ticket properties
Create Ticket	Agent Roles > Tickets > View Tickets
Create Ticket Notes	Agent Roles > Tickets > View Tickets
Delete Ticket Attachments	Agent Roles > Tickets > View Tickets + Edit ticket properties
Delete Tickets	Agent Roles > Tickets > View Tickets + Delete a ticket
Get Tickets	Agent Roles > Tickets > View Tickets
List Tickets	Agent Roles > Tickets > View Tickets
Resolve Tickets	Agent Roles > Tickets > View Tickets + Edit ticket properties
Restore Tickets	Agent Roles > Tickets > View Tickets + Delete a ticket
Search Tickets	Agent Roles > Tickets > View Tickets
Update Tickets	Agent Roles > Tickets > View Tickets + Edit ticket properties
Test Connection	Agent Roles > Tickets > View Tickets

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

Reader Note
Understanding Roles for Agents : Freshservice.

Configuring Freshservice to Work with D3 SOAR

Obtaining the API Key

First, you will need an API key to enable the integration between Freshservice and D3 SOAR. See Where do I find my API key? : Freshservice for instructions on locating your API key. If additional users have been created, ensure to acquire the API key for the specific user you wish to configure.

Creating a Role

In Freshservice, navigate to Admin > User Management > Roles. Click on New Role. Select Agent Role from the options (although Admin Roles can also be selected, all current commands can function with Agent Roles as a minimum requirement).
Customize the permissions as per your needs, then click Save. For the list of required permissions for each command, refer to the Permission Requirements sections.

Creating an Agent and Assigning Roles

Navigate to Admin > User Management > Agents. Click on New Agent.
Fill out the necessary information fields and then click Create.
Locate and click on the agent you’ve just created to view more details. Go to the Permissions tab, then under Group and Roles, click Edit.
In the Roles section, select the role you created earlier. Opt for Across all groups in the service desk section, then click Save to finalize the configuration.

Configuring D3 SOAR to Work with Freshservice

Log in to D3 SOAR.
Find the Freshservice integration.
1. Navigate to Configuration on the top header menu.
2. Click on the Integration icon on the left sidebar.
3. Type Freshservice in the search box to find the integration, then click it to select it.
4. Click + Connection, on the right side of the Connections section. A new connection window will appear.
Configure the following fields to create a connection to Freshservice.
1. Connection Name: The desired name for the connection.
2. Site: Specifies the site to use the integration connection. Use the drop-down menu to select the site. The Share to Internal Sites option enables all sites defined as internal sites to use the connection. Selecting a specific site will only enable that site to use the connection.
3. Recipient site for events from connections Shared to Internal Sites: This field appears if you selected Share to Internal Sites for Site to let you select the internal site to deploy the integration connection.
4. Agent Name (Optional): Specifies the proxy agent required to build the connection. Use the dropdown menu to select the proxy agent from a list of previously configured proxy agents.
5. Description (Optional): Add your desired description for the connection.
6. Tenant (Optional): When configuring the connection from a master tenant site, you have the option to choose the specific tenant sites you want to share the connection with. Once you enable this setting, you can filter and select the desired tenant sites from the dropdowns to share the connection.
7. Configure User Permissions: Defines which users have access to the connection.
8. Active: Check the tick box to ensure the connection is available for use.
9. System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.
  1. Input the Server URL. This URL is unique to your Freshservice instance; the default value provided is a placeholder and will not function unless updated.
  2. Input the saved API Key from the Freshservice platform. Refer to Configuring Freshservice to Work with D3 SOAR for more information.
  3. Input the API Version. The default value is v2.
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.
11. 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.
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

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

Reader Note

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

Close Tickets

Changes the status of the specified tickets to "Closed".

Reader Note

The parameter Ticket IDs is required to run this command.

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

Input

Input Parameter	Required /Optional	Description	Example
Ticket IDs	Required	The IDs of the tickets to close. Ticked IDs can be obtained using the List Tickets or Search Tickets commands.	[ 3* ]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "results": [
        {
            "cc_emails": [],
            "fwd_emails": [],
            "reply_cc_emails": [],
            "spam": false,
            "email_config_id": ***,
            "fr_escalated": false,
            "group_id": null,
            "priority": 1,
            "requester_id": **,
            "requested_for_id": ***,
            "responder_id": null,
            "source": 1,
            "status": 5,
            "subject": "Activate your account at Freshservice Support Portal",
            "description": "\n\t\n\n\nHello d3security,A new account has been created for you in our Freshdesk Portal.To get started with using our Support Portal, you will have to activate your account. \n\n\nActivation lets you participate in our Forums, browse our Knowledge Base and view and respond to your tickets. __________________________________________________________________________ \n\nActivate your account by clicking on the link below. https://support.freshservice.com/register/KmKulxDTelywLD5BK0P__________________________________________________________________________If the above URL doesn't work, copy and paste it into your browser. \n\n\nIn case you are stuck, please write to us for assistance and one of our agents would be happy to help.Regards,\n\nFreshdesk\n\n\n\n\n\n\n\n\n\n",
            "description_text": " \r\n \r\n Hello d3security,  A new account has been created for you in our Freshdesk Portal.  To get started with using our Support Portal, you will have to activate your account.  \r\n Activation lets you participate in our Forums, browse our Knowledge Base and view and respond to your tickets.  __________________________________________________________________________  \r\n Activate your account by clicking on the link below.   https://support.freshservice.com/register/KmKulxDTelywLD5BK0P __________________________________________________________________________  If the above URL doesn't work, copy and paste it into your browser.  \r\n  In case you are stuck, please write to us for assistance and one of our agents would be happy to help.  Regards, \r\n Freshdesk \r\n   \r\n   \r\n   \r\n \r\n \r\n\r\n",
            "category": null,
            "sub_category": null,
            "item_category": null,
            "custom_fields": {
                "custom_note": null
            },
            "id": 33,
            "type": "Incident",
            "to_emails": [
                "test@example.freshservice.com"
            ],
            "department_id": null,
            "is_escalated": false,
            "tags": [],
            "due_by": "2023-09-08T21:00:00Z",
            "fr_due_by": "2023-09-01T18:00:00Z",
            "created_at": "2023-08-30T01:04:47Z",
            "updated_at": "2023-08-30T16:42:02Z",
            "attachments": [],
            "workspace_id": 2,
            "planned_start_date": null,
            "planned_end_date": "2023-08-30T16:42:00Z",
            "planned_effort": 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

{
    "TicketIDs": "\"[ 3* ]\"",
    "TicketStatuses": "\"[ 5 ]\""
}

Return Data

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

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

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

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

You can view more details about an error in the Error tab.

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

SAMPLE DATA

CODE

Successful

Result

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

SAMPLE DATA

results

{'ticket': {'cc_emails': [], 'fwd_emails': [], 'reply_cc_emails': [], 'spam': False, 'email_config_id': ***, 'fr_escalated': False, 'group_id': None, 'priority': 1, 'requester_id': ***, 'requested_for_id': ***, 'responder_id': None, 'source': 1, 'status': 5, 'subject': 'Activate your account at Freshservice Support Portal', 'description': '
\n\t
\n
\n
\nHello d3security,
A new account has been created for you in our Freshdesk Portal.
To get started with using our Support Portal, you will have to activate your account. \n
\n
\nActivation lets you participate in our Forums, browse our Knowledge Base and view and respond to your tickets.
__________________________________________________________________________ \n
\n
Activate your account by clicking on the link below.
https://support.freshservice.com/register/KmKulxDTelywLD5BK0P
__________________________________________________________________________
If the above URL doesn\'t work, copy and paste it into your browser. \n
\n
\n
In case you are stuck, please write to us for assistance and one of our agents would be happy to help.
Regards,\n
\n
Freshdesk
\n
\n
\n
\n
\n
\n
\n\n\n
\n', 'description_text': " \r\n \r\n Hello d3security, A new account has been created for you in our Freshdesk Portal. To get started with using our Support Portal, you will have to activate your account. \r\n Activation lets you participate in our Forums, browse our Knowledge Base and view and respond to your tickets. __________________________________________________________________________ \r\n Activate your account by clicking on the link below. https://support.freshservice.com/register/KmKulxDTelywLD5BK0P __________________________________________________________________________ If the above URL doesn't work, copy and paste it into your browser. \r\n In case you are stuck, please write to us for assistance and one of our agents would be happy to help. Regards, \r\n Freshdesk \r\n \r\n \r\n \r\n \r\n \r\n\r\n", 'category': None, 'sub_category': None, 'item_category': None, 'custom_fields': {'custom_note': None}, 'id': 3*, 'type': 'Incident', 'to_emails': ['test@example.freshservice.com'], 'department_id': None, 'is_escalated': False, 'tags': [], 'due_by': '2023-09-08T21:00:00Z', 'fr_due_by': '2023-09-01T18:00:00Z', 'created_at': '2023-08-30T01:04:47Z', 'updated_at': '2023-08-30T16:42:02Z', 'attachments': [], 'workspace_id': *, 'planned_start_date': None, 'planned_end_date': '2023-08-30T16:42:00Z', 'planned_effort': None}}

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.	Close 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 Freshservice 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: 666. Reason:Not Found.

Error Sample Data

Close Tickets failed.

Status Code: 404.

Message: Ticket ID: 666. Reason:Not Found.

Create Ticket

Creates a new ticket in your service desk. Please note, if you create custom fields or you add other values than out-of-box ones, or you want to create a ticket with additional fields other than the provided parameters, you can use Additional Fields parameter.

File ID and File Source

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

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

Reader Note

To use the Additional Fields parameter, follow the steps below:

Define Custom Fields in the Freshservice
1. Navigate to Admin > Service Management > Service Desk Settings > Field Manager > Ticket Fields > Ticket Form.
2. Use the available options to name and define your custom fields. Ensure to save your changes.
Check the Custom Field's System Name
In D3 SOAR, run the List Tickets command and view the raw data for any ticket. Your newly-created custom field will be visible (e.g., if you named it "Test123"), but its value will be null since previous tickets don't have this value assigned.
This is a method to identify the system name of the custom field, as the system name might differ from the display name. For example, a display name of "Test123" might have a system name of "test123". Always verify the system name prior to its usage.
Integrate Custom Field into the Additional Fields Parameter
- Use the following format to define custom fields in the Additional Fields parameter.
  CODE
```
{

     "custom_fields": {

          "your_custom_field_system_name": "value"

     }

}
```
- There are other predefined fields you can utilize. For fields that exist in D3 system parameters, inputting these in Additional Fields will override the D3 parameter value. For fields not present in D3 system parameters (e.g. "group_id"), the system name might differ from the display name (e.g. "Group").
  To confirm available fields, inspect the raw data of the List Tickets command. These fields should not fall under 'custom fields'. An input example is:
  CODE
```
{

    "cc_emails": [

        "support@example.com"

    ],

}
```

Make sure to always validate field system names against the raw data to prevent inconsistencies.

Input

Input Parameter	Required/Optional	Description	Example
Requester Email	Required	The email address of the requester. If there is no existing contact with this email in Freshservice, a new contact will be created.	service@example.com
Ticket Subject	Required	The subject of the ticket.	Suspicious phishing email
Description	Required	The HTML content of the ticket.	Details about the incident.2023***a
Priority	Optional	The priority level of the ticket. By default, it is set to Low if not specified. Note: Urgency and Impact levels can override this priority. Without set Urgency and Impact levels, the ticket will always default to Low regardless of the chosen priority.	Urgent
Status	Optional	The status of the ticket. The default status is Open if this parameter is not specified.	Open
Source	Optional	The source of the ticket. The default source is Phone if this parameter is not specified.	Email
Urgency	Optional	The urgency level of the ticket. The default urgency level is Low if this parameter is not specified.	High
Impact	Optional	The impact level of the ticket. The default impact level is Low if this parameter is not specified.	High
Additional Fields	Optional	The key-value pairs for custom or other desired fields during ticket creation. Ensure custom fields are first set up under Admin > Service Management > Service Desk Settings > Field Manager > Ticket Fields > Ticket Form. If field entries overlap with other parameters, the other parameters will be omitted. Refer to Customize Ticket Fields from Freshservice's documentation for more information.	{ "cc_emails": [ "support@example.com" ], "custom_fields": { "custom_note": "testNote123" } }
File IDs	Optional	The IDs of the files stored in D3 SOAR's database to upload as ticket attachments. The total attachment size cannot exceed 40 MB.	[ "810" ]
File Source	Optional	The file source of the files to upload as ticket attachments. 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

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "ticket": {
        "cc_emails": [
            "support@example.com"
        ],
        "fwd_emails": [],
        "reply_cc_emails": [
            "support@example.com"
        ],
        "fr_escalated": false,
        "spam": false,
        "email_config_id": null,
        "group_id": null,
        "priority": 2,
        "requester_id": ***,
        "requested_for_id": ***,
        "responder_id": null,
        "source": 1,
        "status": 2,
        "subject": "Suspicious phishing email",
        "to_emails": null,
        "department_id": null,
        "id": 31,
        "type": "Incident",
        "due_by": "2023-09-01T18:00:00Z",
        "fr_due_by": "2023-08-30T20:00:00Z",
        "is_escalated": false,
        "description": "Details about the incident.20230829c",
        "description_text": "Details about the incident.20230829c",
        "category": null,
        "sub_category": null,
        "item_category": null,
        "custom_fields": {
            "custom_note": null
        },
        "created_at": "2023-08-30T00:45:58Z",
        "updated_at": "2023-08-30T00:45:58Z",
        "tags": [],
        "attachments": [
            {
                "id": ***,
                "content_type": "image/png",
                "size": 4290,
                "name": "***.png",
                "attachment_url": "https://***.attachments.freshservice.com/data/helpdesk/attachments/production/***/original/***.png?response-content-type=image/png&Expires=***&Signature=***__&Key-Pair-Id=***",
                "created_at": "2023-08-30T00:45:58Z",
                "updated_at": "2023-08-30T00:45:58Z"
            },
            {
                "id": ***,
                "content_type": "application/octet-stream",
                "size": 936,
                "name": "***-1.json",
                "attachment_url": "https://***.attachments.freshservice.com/data/helpdesk/attachments/production/***/original/***-1.json?response-content-type=application/octet-stream&Expires=***&Signature=***__&Key-Pair-Id=***",
                "created_at": "2023-08-30T00:45:58Z",
                "updated_at": "2023-08-30T00:45:58Z"
            }
        ],
        "workspace_id": 2,
        "planned_start_date": null,
        "planned_end_date": null,
        "planned_effort": 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

{
    "TicketID": "\"3*\"",
    "Subject": "\"Suspicious phishing email\"",
    "TicketType": "\"Incident\"",
    "Priority": "\"2\"",
    "Status": "\"2\""
}

Return Data

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

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

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

You can view more details about an error in the Error tab.

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

SAMPLE DATA

CODE

Successful

Result

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

SAMPLE DATA

ticket

{'cc_emails': ['support@example.com'], 'fwd_emails': [], 'reply_cc_emails': ['support@example.com'], 'fr_escalated': False, 'spam': False, 'email_config_id': None, 'group_id': None, 'priority': 2, 'requester_id': ***, 'requested_for_id': ***, 'responder_id': None, 'source': 1, 'status': 2, 'subject': 'Suspicious phishing email', 'to_emails': None, 'department_id': None, 'id': 3*, 'type': 'Incident', 'due_by': '2023-09-01T18:00:00Z', 'fr_due_by': '2023-08-30T20:00:00Z', 'is_escalated': False, 'description': '

Details about the incident.20230829c

', 'description_text': 'Details about the incident.20230829c', 'category': None, 'sub_category': None, 'item_category': None, 'custom_fields': {'custom_note': None}, 'created_at': '2023-08-30T00:45:58Z', 'updated_at': '2023-08-30T00:45:58Z', 'tags': [], 'attachments': [{'id': ***, 'content_type': 'image/png', 'size': 4290, 'name': '***.png', 'attachment_url': 'https://***.attachments.freshservice.com/data/helpdesk/attachments/production/**/original/***.png?response-content-type=image/png&Expires=***&Signature=****&Key-Pair-Id=***', 'created_at': '2023-08-30T00:45:58Z', 'updated_at': '2023-08-30T00:45:58Z'}], 'workspace_id': *, 'planned_start_date': None, 'planned_end_date': None, 'planned_effort': 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.	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 Freshservice portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Unexpected/invalid field in request.

Error Sample Data

Create Ticket failed.

Status Code: 400.

Message: Unexpected/invalid field in request.

Create Ticket Notes

Creates a conversation note for the specified tickets.

File ID and File Source

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

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

Reader Note

The parameter Ticket IDs is required to run this command.

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

Input

Input Parameter	Required/Optional	Description	Example
Ticket IDs	Required	The IDs of the tickets to create a note. Ticket IDs can be obtained using the List Tickets or Search Tickets commands.	[ 3* ]
Note Content	Required	The HTML content of the note.	Say Hi
Private	Optional	The option to set the note to private, when True. The default value is True.	False
Notify Emails	Optional	The email addresses of agents or users to notify about the note.	[ "support@example.com" ]
File IDs	Optional	The IDs of the files stored in D3 SOAR's database to upload as note attachments.	[ "810" ]
File Source	Optional	The file source of the files to upload as ticket attachments. 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

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "results": [
        {
            "conversation": {
                "id": ***,
                "user_id": ***,
                "to_emails": [
                    "test@example.com"
                ],
                "body": "Say Hi",
                "body_text": "Say Hi",
                "ticket_id": 3*,
                "created_at": "2023-08-30T01:06:03Z",
                "updated_at": "2023-08-30T01:06:03Z",
                "incoming": false,
                "private": false,
                "support_email": null,
                "attachments": [
                    {
                        "id": ***,
                        "created_at": "2023-08-30T01:06:03Z",
                        "updated_at": "2023-08-30T01:06:03Z",
                        "name": "blueJay.png",
                        "attachment_url": "https://d3security.attachments.freshservice.com/data/helpdesk/attachments/production/***/original/***.png?response-content-type=image/png&Expires=***&Signature=***",
                        "content_type": "image/png",
                        "size": 4290,
                        "canonical_url": "https://d3security.freshservice.com/helpdesk/attachments/***"
                    }
                ]
            }
        }
    ]
}

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": "\"[ 3* ]\"",
    "NoteIDs": "\"[ ***]\"",
    "BodyTexts": "\"[ \\\"Say Hi\\\" ]\""
}

Return Data

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

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

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

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

You can view more details about an error in the Error tab.

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

SAMPLE DATA

CODE

Successful

Result

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

SAMPLE DATA

results

{'conversation': {'id': ***, 'user_id': ***, 'to_emails': ['test@example.com'], 'body': '
Say Hi
', 'body_text': 'Say Hi', 'ticket_id': 3*, 'created_at': '2023-08-30T01:06:03Z', 'updated_at': '2023-08-30T01:06:03Z', 'incoming': False, 'private': False, 'support_email': None, 'attachments': [{'id': 23001456072, 'created_at': '2023-08-30T01:06:03Z', 'updated_at': '2023-08-30T01:06:03Z', 'name': 'blueJay.png', 'attachment_url': 'https://test.attachments.freshservice.com/data/helpdesk/attachments/production/***/original/blueJay.png?response-content-type=image/png&Expires=***&Signature=***&Key-Pair-Id=***', 'content_type': 'image/png', 'size': 4290, 'canonical_url': 'https://**.freshservice.com/helpdesk/attachments/***'}]}}

Error Handling

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

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

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Create Ticket Notes 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 Freshservice 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: 666. Reason:Not Found.

Error Sample Data

Create Ticket Notes failed.

Status Code: 404.

Message: Ticket ID: 666. Reason:Not Found.

Delete Ticket Attachments

Deletes the specified attachments from a specific ticket. As a ticket's total attachment size can not exceed 40MB, you can use this command to manage a ticket's attachment size.

Reader Note

Ticket ID and Attachment IDs are required parameters to run this command.

Run the List Tickets or Search Tickets command to obtain Ticket IDs. Ticket IDs can be found in the returned raw data of both commands at the path $.tickets[*].id.
Run the Get Tickets command to obtain Attachment IDs. Attachment IDs can be found in the returned raw data at the path $.results[*].attachments[*].id.
Not all tickets contain attachments. Ensure the Ticket ID corresponds with the Attachment ID. It is recommended to first run the List Tickets or Search Tickets command to obtain the Ticket ID. Once acquired, use this ID with the Get Tickets command to retrieve attachments for deletion. Finally, pair the Ticket ID with Attachment IDs to run this command.

Input

Input Parameter	Required/Optional	Description	Example
Ticket ID	Required	The ID of the ticket to remove attachments. Ticket IDs can be obtained using the List Tickets or Search Tickets commands.	3*
Attachment IDs	Required	The IDs of the attachment files to remove. Attachment IDs can be obtained using the Get Tickets command.	2***1

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "results": [
        {
            "attachmentId": 2***1,
            "message": "The ticket attachment was deleted successfully."
        }
    ]
}

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

{
    "AttachmentIDs": "\"[ 2***1 ]\""
}

Return Data

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

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

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

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

You can view more details about an error in the Error tab.

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

SAMPLE DATA

CODE

Successful

Result

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

SAMPLE DATA

results

{'attachmentId': 2***1, 'message': 'The ticket attachment was deleted successfully.'}

Error Handling

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

The 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.	Delete Ticket Attachments 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 Freshservice 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: 7. AttachmentID: 23003016262. Reason:Not Found.

Error Sample Data

Delete Ticket Attachments failed.

Status Code: 404.

Message: Ticket ID: 7. AttachmentID: 23003016262. Reason:Not Found.

Delete Tickets

Deletes the specified tickets. Note: Deleted tickets are not permanently lost. You can restore them using the Restore Tickets command.

Reader Note

The parameter Ticket IDs is required to run this command.

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

Input

Input Parameter	Required/Optional	Description	Example
Ticket IDs	Required	The IDs of the tickets to delete. Ticket IDs can be obtained using the List Tickets or Search Tickets commands.	[ 3* ]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "results": [
        {
            "ticketId": 3*,
            "message": "The ticket was deleted successfully."
        }
    ]
}

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": "\"[ 3* ]\""
}

Return Data

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

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

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

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

You can view more details about an error in the Error tab.

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

SAMPLE DATA

CODE

Successful

Result

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

SAMPLE DATA

results

{'ticketId': 3*, 'message': 'The ticket was deleted successfully.'}

Error Handling

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

The 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.	Delete 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 Freshservice 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: 666. Reason:Not Found.

Error Sample Data

Delete Tickets failed.

Status Code: 404.

Message: Ticket ID: 666. Reason:Not Found.

Get Tickets

Retrieves details of the specified tickets.

Reader Note

The parameter Ticket IDs is required to run this command.

Run the List Tickets or Search Tickets command to obtain Ticket IDs. Ticket IDs can be found in the returned raw data of both commands 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 or Search Tickets commands.	[ 3* ]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "results": [
        {
            "ticket": {
                "cc_emails": [
                    "test@example.com"
                ],
                "fwd_emails": [],
                "reply_cc_emails": [
                    "test@example.com"
                ],
                "bcc_emails": null,
                "fr_escalated": false,
                "spam": false,
                "email_config_id": null,
                "group_id": null,
                "priority": 4,
                "requester_id": ***,
                "requested_for_id": ***,
                "responder_id": null,
                "source": 2,
                "status": 3,
                "subject": "Suspicious phishing email -New Subject",
                "to_emails": null,
                "sla_policy_id": ***,
                "applied_business_hours": **,
                "department_id": null,
                "id": 3*,
                "type": "Service Request",
                "due_by": "2023-08-30T16:00:00Z",
                "fr_due_by": "2023-08-30T13:00:00Z",
                "is_escalated": false,
                "description": "Update ticket test 0830a",
                "description_text": "Update ticket test 0830a",
                "custom_fields": {
                    "custom_note": "testNote830c"
                },
                "created_at": "2023-08-30T00:45:58Z",
                "updated_at": "2023-08-30T17:57:59Z",
                "urgency": 3,
                "impact": 2,
                "category": null,
                "sub_category": null,
                "item_category": null,
                "deleted": false,
                "attachments": [
                    {
                        "id": ***,
                        "content_type": "application/octet-stream",
                        "size": 936,
                        "name": "Untitled-1.json",
                        "attachment_url": "https://***.attachments.freshservice.com/data/helpdesk/attachments/production/***/original/***-1.json?response-content-type=application/octet-stream&Expires=***&Signature=***",
                        "created_at": "2023-08-30T00:45:58Z",
                        "updated_at": "2023-08-30T00:45:58Z"
                    }
                ],
                "workspace_id": *,
                "created_within_business_hours": false,
                "approval_status": 4,
                "approval_status_name": "Not Requested",
                "planned_start_date": null,
                "planned_end_date": null,
                "planned_effort": 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

{
    "TicketIDs": "\"[ 3* ]\"",
    "Subjects": "\"[ \\\"Suspicious phishing email -New Subject\\\" ]\"",
    "TicketTypes": "\"[ \\\"Service Request\\\" ]\"",
    "Priorities": "\"[ 4 ]\"",
    "Statuses": "\"[ 3 ]\""
}

Return Data

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

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

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

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

You can view more details about an error in the Error tab.

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

SAMPLE DATA

CODE

Successful

Result

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

SAMPLE DATA

results

{'ticket': {'cc_emails': ['test@example.com'], 'fwd_emails': [], 'reply_cc_emails': ['test@example.com'], 'bcc_emails': None, 'fr_escalated': False, 'spam': False, 'email_config_id': None, 'group_id': None, 'priority': 4, 'requester_id': ***, 'requested_for_id': ***, 'responder_id': None, 'source': 2, 'status': 3, 'subject': 'Suspicious phishing email -New Subject', 'to_emails': None, 'sla_policy_id': ***, 'applied_business_hours': 23000010065, 'department_id': None, 'id': ***, 'type': 'Service Request', 'due_by': '2023-08-30T16:00:00Z', 'fr_due_by': '2023-08-30T13:00:00Z', 'is_escalated': False, 'description': 'Update ticket test 0830a', 'description_text': 'Update ticket test 0830a', 'custom_fields': {'custom_note': 'testNote830c'}, 'created_at': '2023-08-30T00:45:58Z', 'updated_at': '2023-08-30T17:57:59Z', 'urgency': 3, 'impact': 2, 'category': None, 'sub_category': None, 'item_category': None, 'deleted': False, 'attachments': [{'id': ***, 'content_type': 'application/octet-stream', 'size': 936, 'name': '***-1.json', 'attachment_url': 'https://***.attachments.freshservice.com/data/helpdesk/attachments/production/***/original/***-1.json?response-content-type=application/octet-stream&Expires=***&Signature=***', 'created_at': '2023-08-30T00:45:58Z', 'updated_at': '2023-08-30T00:45:58Z'}], 'workspace_id': *, 'created_within_business_hours': False, 'approval_status': 4, 'approval_status_name': 'Not Requested', 'planned_start_date': None, 'planned_end_date': None, 'planned_effort': None}}

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 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 Freshservice 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: Resolve Ticket failed. Ticket ID: 188. Reason:Not Found.

Error Sample Data

Get Tickets failed.

Status Code: 404.

Message: Resolve Ticket failed. Ticket ID: 188. Reason:Not Found.

List Tickets

Retrieves tickets based on the given search criteria. Unless the 'deleted' predefined filter is used, by default, only tickets that have not been deleted or tagged as spam will be retrieved.

Reader Note

You can locate your Workspace ID within the URL in Freshservice by navigating to Admin > Account Setting > Manage Workspaces. Select your desired workspace and you'll find the Workspace ID in the URL. For example, if the URL is "d3securityhelpdesk.freshservice.com/a/admin/workspaces/2/edit", then the Workspace ID is 2.

Input

Input Parameter	Required/Optional	Description	Example
Workspace ID	Optional	The ID of the workspace to retrieve tickets. This parameter is relevant only for accounts that have the 'Workspaces' feature activated. Inputing a value of 0 will retrieve tickets from all workspaces, displaying only global-level fields. By default, only tickets from the primary workspace are retrieved for accounts with the 'Workspaces' feature enabled.	2
Predefined Filter	Optional	The state to filter retrieved tickets. By default, only tickets that have not been deleted or flagged as spam will be returned. To retrieve deleted tickets, please select Deleted.	New and My Open
Ticket Type	Optional	The ticket type to filter retrieved tickets. If this parameter is not defined, all ticket types will be returned.	Incident
Requester Email	Optional	The email address of the requester to filter retrieved tickets.	test@freshservice.com
Updated Since	Optional	The update datetime filter to retrieve tickets. Tickets updated beyond the specified datetime will be shown. By default, only tickets created within the recent 30 days are displayed. Use this parameter to retrieve older tickets.	2023-01-01 00:00

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "tickets": [
        {
            "subject": "What's wrong with my email?",
            "group_id": null,
            "department_id": null,
            "category": null,
            "sub_category": null,
            "item_category": null,
            "requester_id": ***,
            "responder_id": null,
            "due_by": "2023-09-08T20:15:45Z",
            "fr_escalated": false,
            "deleted": false,
            "spam": false,
            "email_config_id": null,
            "fwd_emails": [],
            "reply_cc_emails": [],
            "cc_emails": [],
            "is_escalated": false,
            "fr_due_by": "2023-09-01T17:15:45Z",
            "id": 1,
            "priority": 1,
            "status": 2,
            "source": 2,
            "created_at": "2023-08-29T20:15:45Z",
            "updated_at": "2023-08-29T20:15:45Z",
            "requested_for_id": **,
            "to_emails": null,
            "type": "Incident",
            "description": "Hi Team, I have been unable to send any emails since this morning. What's going on?Regards, Andrea ",
            "description_text": "Hi Team, I have been unable to send any emails since this morning. What's going on? Regards, Andrea",
            "custom_fields": {},
            "tags": [],
            "requested_for": {
                "email": "test@freshservice.com",
                "id": ***,
                "mobile": null,
                "name": "Andrea",
                "phone": null
            },
            "stats": {
                "created_at": "2023-08-29T20:15:45Z",
                "updated_at": "2023-08-29T20:15:45Z",
                "ticket_id": ***,
                "opened_at": null,
                "group_escalated": false,
                "inbound_count": 1,
                "status_updated_at": "2023-08-29T20:15:45Z",
                "outbound_count": 0,
                "pending_since": null,
                "resolved_at": null,
                "closed_at": null,
                "first_assigned_at": null,
                "assigned_at": null,
                "agent_responded_at": null,
                "requester_responded_at": null,
                "first_responded_at": null,
                "first_resp_time_in_secs": null,
                "resolution_time_in_secs": null
            },
            "workspace_id": *
        }
    ]
}

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": "\"[ 1 ]\"",
    "Subjects": "\"[ \\\"What's wrong with my email?\\\" ]\"",
    "TicketTypes": "\"[ \\\"Incident\\\" ]\"",
    "Priorities": "\"[ 1 ]\"",
    "Statuses": "\"[ 2 ]\""
}

Return Data

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

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

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

You can view more details about an error in the Error tab.

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

SAMPLE DATA

CODE

Successful

Result

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

SAMPLE DATA

tickets

{'subject': "What's wrong with my email?", 'group_id': None, 'department_id': None, 'category': None, 'sub_category': None, 'item_category': None, 'requester_id': ***, 'responder_id': None, 'due_by': '2023-09-08T20:15:45Z', 'fr_escalated': False, 'deleted': False, 'spam': False, 'email_config_id': None, 'fwd_emails': [], 'reply_cc_emails': [], 'cc_emails': [], 'is_escalated': False, 'fr_due_by': '2023-09-01T17:15:45Z', 'id': 1, 'priority': 1, 'status': 2, 'source': 2, 'created_at': '2023-08-29T20:15:45Z', 'updated_at': '2023-08-29T20:15:45Z', 'requested_for_id': 23000919344, 'to_emails': None, 'type': 'Incident', 'description': "
Hi Team,
I have been unable to send any emails since this morning. What's going on?
Regards,
Andrea
", 'description_text': "Hi Team, I have been unable to send any emails since this morning. What's going on? Regards, Andrea", 'custom_fields': {}, 'tags': [], 'requested_for': {'email': 'test@freshservice.com', 'id': ***, 'mobile': None, 'name': 'test', 'phone': None}, 'stats': {'created_at': '2023-08-29T20:15:45Z', 'updated_at': '2023-08-29T20:15:45Z', 'ticket_id': ***, 'opened_at': None, 'group_escalated': False, 'inbound_count': 1, 'status_updated_at': '2023-08-29T20:15:45Z', 'outbound_count': 0, 'pending_since': None, 'resolved_at': None, 'closed_at': None, 'first_assigned_at': None, 'assigned_at': None, 'agent_responded_at': None, 'requester_responded_at': None, 'first_responded_at': None, 'first_resp_time_in_secs': None, 'resolution_time_in_secs': None}, 'workspace_id': *}

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 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 Freshservice 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: invalid literal for int() with base 10.

Error Sample Data

List Tickets failed.

Status Code: 401.

Message: invalid literal for int() with base 10.

Resolve Tickets

Changes the status of the specified tickets to "Resolved".

Reader Note

The parameter Ticket IDs is required to run this command.

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

Input

Input Parameter	Required/Optional	Description	Example
Ticket IDs	Required	The IDs of the tickets to resolve. Ticket IDs can be obtained using the List Tickets or Search Tickets commands.	[ 3* ]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "results": [
        {
            "cc_emails": [
                "test@freshservice.com"
            ],
            "fwd_emails": [],
            "reply_cc_emails": [
                "test@freshservice.com"
            ],
            "spam": false,
            "email_config_id": null,
            "fr_escalated": false,
            "group_id": null,
            "priority": 2,
            "requester_id": ***,
            "requested_for_id": ***,
            "responder_id": null,
            "source": 1,
            "status": 4,
            "subject": "Suspicious phishing email",
            "description": "Details about the incident.20230829b",
            "description_text": "Details about the incident.20230829b",
            "category": null,
            "sub_category": null,
            "item_category": null,
            "custom_fields": {
                "custom_note": "testNote123"
            },
            "id": **,
            "type": "Incident",
            "to_emails": null,
            "department_id": null,
            "is_escalated": false,
            "tags": [],
            "due_by": "2023-09-01T18:00:00Z",
            "fr_due_by": "2023-08-30T20:00:00Z",
            "created_at": "2023-08-30T00:59:38Z",
            "updated_at": "2023-08-30T16:52:08Z",
            "attachments": [],
            "workspace_id": *,
            "planned_start_date": null,
            "planned_end_date": "2023-08-30T16:52:00Z",
            "planned_effort": 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

{
    "TicketIDs": "\"[ ** ]\"",
    "TicketStatuses": "\"[ 4 ]\""
}

Return Data

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

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

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

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

You can view more details about an error in the Error tab.

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

SAMPLE DATA

CODE

Successful

Result

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

SAMPLE DATA

results

{'ticket': {'cc_emails': ['test@freshservice.com'], 'fwd_emails': [], 'reply_cc_emails': ['test@freshservice.com'], 'spam': False, 'email_config_id': None, 'fr_escalated': False, 'group_id': None, 'priority': 2, 'requester_id': **, 'requested_for_id': ***, 'responder_id': None, 'source': 1, 'status': 4, 'subject': 'Suspicious phishing email', 'description': '
Details about the incident.20230829b
', 'description_text': 'Details about the incident.20230829b', 'category': None, 'sub_category': None, 'item_category': None, 'custom_fields': {'custom_note': 'testNote123'}, 'id': ***, 'type': 'Incident', 'to_emails': None, 'department_id': None, 'is_escalated': False, 'tags': [], 'due_by': '2023-09-01T18:00:00Z', 'fr_due_by': '2023-08-30T20:00:00Z', 'created_at': '2023-08-30T00:59:38Z', 'updated_at': '2023-08-30T16:52:08Z', 'attachments': [], 'workspace_id': *, 'planned_start_date': None, 'planned_end_date': '2023-08-30T16:52:00Z', 'planned_effort': None}}

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.	Resolve 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 Freshservice 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: 666. Reason:Not Found.

Error Sample Data

Resolve Tickets failed.

Status Code: 404.

Message: Ticket ID: 666. Reason:Not Found.

Restore Tickets

Restores the specified deleted tickets.

Reader Note

The parameter Ticket IDs is required to run this command.

Only the deleted tickets can be restored. Run the List Tickets command with the Predefined Filter input parameter set to deleted to obtain Ticket IDs. Ticket IDs can be found in the returned raw data of both commands at the path $.tickets[*].id.

Input

Input Parameter	Required/Optional	Description	Example
Ticket IDs	Required	The IDs of the deleted tickets to restore. The IDs of deleted tickets can be obtained using the List Tickets command and setting the Predefined Filter parameter to "Deleted".	[ 3* ]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "results": [
        {
            "ticketId": 3*,
            "message": "The ticket was restored successfully."
        }
    ]
}

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": "\"[ 3* ]\""
}

Return Data

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

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

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

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

You can view more details about an error in the Error tab.

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

SAMPLE DATA

CODE

Successful

Result

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

SAMPLE DATA

results

{'ticketId': 3*, 'message': 'The ticket was restored successfully.'}

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.	Restore 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 Freshservice 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: 6. Reason:Not Found.

Error Sample Data

Restore Tickets failed.

Status Code: 404.

Message: Ticket ID: 6. Reason:Not Found.

Search Tickets

Searches for specified tickets based on given query conditions. You can also use custom ticket fields created in your account to filter and obtain a list of tickets matching the specified criteria. At least one parameter must be defined.

Reader Note

You can locate your Assignee ID within the URL in Freshservice by navigating to Admin > User Management > Agents. Select your desired user and you'll find the Assignee ID in the URL. For example, if the URL "d3securityhelpdesk.freshservice.com/agents/23***7", then the Assignee ID is 23***7.

Input

Input Parameter	Required/Optional	Description	Example
Priority	Optional	The priority level to filter tickets. If this parameter is not specified, tickets of all priority levels will be returned.	High and Urgent
Status	Optional	The status to filter tickets. If this parameter is not specified, tickets with any status will be returned.	Open
Requester Email	Optional	The email address of the tickets' requester to filter tickets.	test@freshservice.com
Created After	Optional	The datetime filter to return tickets created after the designated date and time.	2023-08-29 00:00
Assignee ID	Optional	The ID of the tickets' assignee to filter tickets.	23000919339
Additional Query	Optional	The additional query conditions to filter tickets. Refer to The Freshservice API from Freshservice's documentation for sample query conditions.	updated_at:<'2023-08-29' AND priority:<3

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "tickets": [
        {
            "subject": "Request for Andrea : Dell Monitor",
            "group_id": null,
            "department_id": null,
            "category": null,
            "sub_category": null,
            "item_category": null,
            "requester_id": ***,
            "responder_id": ***,
            "due_by": "2023-09-01T17:16:00Z",
            "fr_escalated": false,
            "deleted": false,
            "spam": false,
            "email_config_id": null,
            "fwd_emails": [],
            "reply_cc_emails": [],
            "cc_emails": [],
            "is_escalated": false,
            "fr_due_by": "2023-08-30T19:16:00Z",
            "priority": 2,
            "source": 2,
            "status": 3,
            "created_at": "2023-08-29T20:15:48Z",
            "updated_at": "2023-08-29T22:55:04Z",
            "requested_for_id": **,
            "to_emails": null,
            "id": *,
            "type": "Service Request",
            "description": "",
            "description_text": "",
            "workspace_id": *,
            "custom_fields": {}
        }
    ],
    "total": 1
}

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": "\"[ \\\"Request for Andrea : Dell Monitor\\\" ]\"",
    "TicketTypes": "\"[ \\\"Service Request\\\" ]\"",
    "Priorities": "\"[ 2 ]\"",
    "Statuses": "\"[ 3 ]\""
}

Return Data

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

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

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

You can view more details about an error in the Error tab.

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

SAMPLE DATA

CODE

Successful

Result

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

SAMPLE DATA

tickets

{'subject': 'Request for Andrea : Dell Monitor', 'group_id': None, 'department_id': None, 'category': None, 'sub_category': None, 'item_category': None, 'requester_id': ***, 'responder_id': ***, 'due_by': '2023-09-01T17:16:00Z', 'fr_escalated': False, 'deleted': False, 'spam': False, 'email_config_id': None, 'fwd_emails': [], 'reply_cc_emails': [], 'cc_emails': [], 'is_escalated': False, 'fr_due_by': '2023-08-30T19:16:00Z', 'priority': 2, 'source': 2, 'status': 3, 'created_at': '2023-08-29T20:15:48Z', 'updated_at': '2023-08-29T22:55:04Z', 'requested_for_id': ***, 'to_emails': None, 'id': *, 'type': 'Service Request', 'description': '', 'description_text': '', 'workspace_id': *, 'custom_fields': {}}

total

1

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 Freshservice portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: blank query.

Error Sample Data

Search Tickets failed.

Status Code: 400.

Message: blank query.

Update Tickets

Updates the parameters of the specified tickets. Note: If you update custom fields, input values other than the preset ones, or wish to update the ticket(s) with extra fields not included in the provided parameters, use the Additional Fields parameter.

File ID and File Source

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

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

Reader Note

To use the Additional Fields parameter, follow the steps below:

Define Custom Fields in the Freshservice
1. Navigate to Admin > Service Management > Service Desk Settings > Field Manager > Ticket Fields > Ticket Form.
2. Use the available options to name and define your custom fields. Ensure to save your changes.
Check the Custom Field's System Name
In D3 SOAR, run the List Tickets command and view the raw data for any ticket. Your newly-created custom field will be visible (e.g., if you named it "Test123"), but its value will be null since previous tickets don't have this value assigned.
This is a method to identify the system name of the custom field, as the system name might differ from the display name. For example, a display name of "Test123" might have a system name of "test123". Always verify the system name prior to its usage.
Integrate Custom Field into the Additional Fields Parameter
- Use the following format to define custom fields in the Additional Fields parameter.
  CODE
```
{

     "custom_fields": {

          "your_custom_field_system_name": "value"

     }

}
```
- There are other predefined fields you can utilize. For fields that exist in D3 system parameters, inputting these in Additional Fields will override the D3 parameter value. For fields not present in D3 system parameters (e.g. "group_id"), the system name might differ from the display name (e.g. "Group").
  To confirm available fields, inspect the raw data of the List Tickets command. These fields should not fall under 'custom fields'. An input example is:
  CODE
```
{

    "cc_emails": [

        "support@example.com"

    ],

}
```

Make sure to always validate field system names against the raw data to prevent inconsistencies.

Input

Input Parameter	Required /Optional	Description	Example
Ticket IDs	Required	The IDs of the tickets to update. Ticket IDs can be obtained using the List Tickets or Search Tickets commands.	[ 3* ]
Requester Email	Optional	The email address of the requester. If there is no existing contact with this email in Freshservice, a new contact will be created.	test@example.com
Ticket Subject	Optional	The subject of the ticket.	Suspicious phishing email-New Subject
Description	Optional	The HTML content of the ticket.	Update ticket test 0830a
Priority	Optional	The priority level of the ticket. Note: Urgency and Impact levels can override this priority.	Urgent
Status	Optional	The status of the ticket.	Pending
Source	Optional	The source of the ticket.	Portal
Urgency	Optional	The urgency level of the ticket.	High
Impact	Optional	The impact level of the ticket.	Medium
Ticket Type	Optional	The updated type for the ticket.	Service Request
Tags	Optional	The tags for the ticket. All tags associated with the tickets should be specified here. Tags can be composed of any text, and if they don't already exist in the system, they will be created.	[ "IMPORTANT", "tag_1" ]
Additional Fields	Optional	The key-value pairs for custom or other desired fields during ticket creation. Ensure custom fields are first set up under Admin > Service Management > Service Desk Settings > Field Manager > Ticket Fields > Ticket Form. If field entries overlap with other parameters, the other parameters will be omitted. Refer to Customize Ticket Fields from Freshservice's documentation for more information.	{ "cc_emails": [ "test@example.com" ], "custom_fields": { "custom_note": "testNote830c" } }
File IDs	Optional	The IDs of the files stored in D3 SOAR's database to upload as ticket attachments. The total attachment size cannot exceed 40 MB.	[ "812" ]
File Source	Optional	The file source of the files to upload as ticket attachments. 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

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "results": [
        {
            "cc_emails": [
                "test@example.com"
            ],
            "fwd_emails": [],
            "reply_cc_emails": [
                "test@example.com"
            ],
            "spam": false,
            "email_config_id": null,
            "fr_escalated": false,
            "group_id": null,
            "priority": 4,
            "requester_id": ***,
            "requested_for_id": ***,
            "responder_id": null,
            "source": 2,
            "status": 3,
            "subject": "Suspicious phishing email -New Subject",
            "description": "Update ticket test 0830a",
            "description_text": "Update ticket test 0830a",
            "category": null,
            "sub_category": null,
            "item_category": null,
            "custom_fields": {
                "custom_note": "testNote830c"
            },
            "id": 31,
            "type": "Service Request",
            "to_emails": null,
            "department_id": null,
            "is_escalated": false,
            "tags": [
                "IMPORTANT",
                "tag_1"
            ],
            "due_by": "2023-08-30T16:00:00Z",
            "fr_due_by": "2023-08-30T13:00:00Z",
            "created_at": "2023-08-30T00:45:58Z",
            "updated_at": "2023-08-30T17:57:59Z",
            "attachments": [
                {
                    "id": ***,
                    "content_type": "image/png",
                    "size": 4290,
                    "name": "blueJay.png",
                    "attachment_url": "https://***.attachments.freshservice.com/data/helpdesk/attachments/production/***/original/***.png?response-content-type=image/png&Expires=***&Signature=***",
                    "created_at": "2023-08-30T00:45:58Z",
                    "updated_at": "2023-08-30T00:45:58Z"
                }
            ],
            "workspace_id": *,
            "planned_start_date": null,
            "planned_end_date": null,
            "planned_effort": 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

{
    "TicketIDs": "\"[ 3* ]\"",
    "Subjects": "\"[ \\\"Suspicious phishing email -New Subject\\\" ]\"",
    "TicketTypes": "\"[ \\\"Service Request\\\" ]\"",
    "Priorities": "\"[ 4 ]\"",
    "Statuses": "\"[ 3 ]\""
}

Return Data

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

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

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

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

You can view more details about an error in the Error tab.

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

SAMPLE DATA

CODE

Successful

Result

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

SAMPLE DATA

results

{'ticket': {'cc_emails': ['test@example.com'], 'fwd_emails': [], 'reply_cc_emails': ['test@example.com'], 'spam': False, 'email_config_id': None, 'fr_escalated': False, 'group_id': None, 'priority': 4, 'requester_id': ***, 'requested_for_id': ***, 'responder_id': None, 'source': 2, 'status': 3, 'subject': 'Suspicious phishing email -New Subject', 'description': 'Update ticket test 0830a', 'description_text': 'Update ticket test 0830a', 'category': None, 'sub_category': None, 'item_category': None, 'custom_fields': {'custom_note': 'testNote830c'}, 'id': **, 'type': 'Service Request', 'to_emails': None, 'department_id': None, 'is_escalated': False, 'tags': ['IMPORTANT', 'tag_1'], 'due_by': '2023-08-30T16:00:00Z', 'fr_due_by': '2023-08-30T13:00:00Z', 'created_at': '2023-08-30T00:45:58Z', 'updated_at': '2023-08-30T17:57:59Z', 'attachments': [{'id': ***, 'content_type': 'image/png', 'size': 4290, 'name': '**.png', 'attachment_url': 'https://**.attachments.freshservice.com/data/helpdesk/attachments/production/**/original/**.png?response-content-type=image/png&Expires=***&Signature=***', 'created_at': '2023-08-30T00:45:58Z', 'updated_at': '2023-08-30T00:45:58Z'}], 'workspace_id': *, 'planned_start_date': None, 'planned_end_date': None, 'planned_effort': None}}

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.	Update 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 Freshservice portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: It should be in the 'valid email address' format.

Error Sample Data

Update Tickets failed.

Status Code: 400.

Message: It should be in the 'valid email address' format.

Test Connection

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

Input

N/A

Output

Return Data

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

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

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

You can view more details about an error in the Error tab.

SAMPLE DATA

CODE

Successful

Error Handling

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

The 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 Freshservice portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Test Connection failed caused of an unexpected error. Please use test command and check Raw Data for the details.

Error Sample Data

Test Connection failed. Failed to check the connector.

Status Code: 400.

Message: Test Connection failed caused of an unexpected error. Please use test command and check Raw Data for the details.

FAQ

How can I add and define values for custom ticket fields?

First, add the desired custom fields from Freshservice's UI. Next, use the Create Ticket or Update Ticket commands to add values to existing custom ticket fields via the Additional Fields parameter in either commands. For further clarification, refer to the reader notes under the Create Ticket and Update Ticket commands.