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:
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.
Navigate to Configuration on the top header menu.
Click on the Integration icon on the left sidebar.
Type Freshservice in the search box to find the integration, then click it to select it.
Click + Connection, on the right side of the Connections section. A new connection window will appear.
Configure the following fields to create a connection to Freshservice.
Connection Name: The desired name for the connection.
Site: Specifies the site to use the integration connection. Use the drop-down menu to select the site. The Share to Internal Sites option enables all sites defined as internal sites to use the connection. Selecting a specific site will only enable that site to use the connection.
Recipient site for events from connections Shared to Internal Sites: This field appears if you selected Share to Internal Sites for Site to let you select the internal site to deploy the integration connection.
Agent Name (Optional): Specifies the proxy agent required to build the connection. Use the dropdown menu to select the proxy agent from a list of previously configured proxy agents.
Description (Optional): Add your desired description for the connection.
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.
Configure User Permissions: Defines which users have access to the connection.
Active: Check the tick box to ensure the connection is available for use.
System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.
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.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.
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.
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.
Click OK to close the alert window.
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
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
Navigate to Admin > Service Management > Service Desk Settings > Field Manager > Ticket Fields > Ticket Form.
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. | |
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
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
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
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
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
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
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
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
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
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
Navigate to Admin > Service Management > Service Desk Settings > Field Manager > Ticket Fields > Ticket Form.
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
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
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.