Zendesk v2.0.0

About the connector

Zendesk is a customer ticketing system that allows companies a method of tracking and responding to customer service requests.

This document provides information about the Zendesk connector, which facilitates automated interactions with Zendesk using FortiSOAR™ playbooks. Add the Zendesk connector as a step in FortiSOAR™ playbooks and perform automated operations, such as creating a new ticket on Zendesk, retrieving all tickets from Zendesk, or marking a ticket as spam on Zendesk.

Version information

Connector Version: 2.0.0

FortiSOAR™ Version Tested on: 5.1.0-464

Authored By: Fortinet

Certified: Yes

Release Notes for version 2.0.0

Following enhancements have been made to the Zendesk connector in version 2.0.0:

• Added the following new operations and playbooks:
  • Get Deleted Ticket List
  • Get Ticket Related Details
  • Mark Ticket as Spam
  • Restore Ticket
  • Delete Ticket
  • Delete Ticket Permanently
  • Delete Bulk Tickets
  • Delete Bulk Of Tickets Permanently
• Added input parameters to the Get Ticket List operation.

Installing the connector

From FortiSOAR™ 5.0.0 onwards, use the Connector Store to install the connector. For the detailed procedure to install a connector, click here.
You can also use the yum command to install connectors. Connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™ repository and run the yum command as a root user to install connectors:

yum install cyops-connector-zendesk

Prerequisites to configuring the connector

• You must have the URL of Zendesk server to which you will connect and perform automated operations and credentials to access that server.
• To access the FortiSOAR™ UI, ensure that port 443 is open through the firewall for the FortiSOAR™ instance.

Configuring the connector

For the procedure to configure a connector, click here

Configuration parameters

In FortiSOAR™, on the Connectors page, click the Zendesk connector row (if you are in the Grid view on the Connectors page) and in the Configurations tab enter the required configuration details:

Parameter	Description
Server URL	URL of the ZenDesk server to which you will connect and perform the automated operations.
Username	Username to access the Zendesk account to which you will connect and perform the automated operations.
Password	Password to access the Zendesk account to which you will connect and perform the automated operations.
Verify SSL	Specifies whether the SSL certificate for the server is to be verified or not. By default, this option is set as True.

Actions supported by the connector

The following automated operations can be included in playbooks, and you can also use the annotations to access operations from FortiSOAR™ release 4.10.0 and onwards:

Function	Description	Annotation and Category
Create Ticket	Create a new ticket in Zendesk based on the subject, assignee ID, description, and other input parameters you have specified.	ticket_create Investigation
Get Ticket List	Retrieves the list of all the tickets from Zendesk.	ticket_list Investigation
Get Ticket Details	Retrieves the details of a ticket from Zendesk based on the ticket ID you have specified.	ticket_details Investigation
Update Ticket	Updates an existing ticket on Zendesk based on the ticket ID and other input parameters you have specified.	ticket_update Investigation
Get Deleted Ticket List	Retrieves a maximum of 100 deleted tickets, per page, from Zendesk. The result includes all deleted, but not yet archived tickets, which have not yet been scrubbed for the past 30 days.	ticket_deleted_list Investigation
Get Ticket Related Details	Retrieves related information for a ticket from Zendesk based on the ticket ID you have specified.	ticket_related_details Investigation
Mark Ticket as Spam	Marks a ticket as spam in Zendesk based on the ticket ID you have specified.	ticket_mark_spam Investigation
Restore Ticket	Restores a previously deleted ticket on Zendesk based on the ticket ID you have specified. You can get the IDs of deleted tickets using the Get Deleted Ticket List action.	ticket_deleted_restore Investigation
Delete Ticket	Deletes a ticket from Zendesk based on the ticket ID you have specified. You can delete 400 tickets every minute using this action. You can get the IDs of deleted tickets using the Get Deleted Ticket List action.	ticket_delete Investigation
Delete Ticket Permanently	Deletes a ticket permanently (ticket has already been deleted) from Zendesk based on the ticket ID you have specified. You can get the ID of deleted tickets using the Get Deleted Ticket List action. If this action succeeds, the ticket is permanently deleted, and the ID of this ticket will not be listed in the Get Deleted Ticket List action. This action cannot be undone.	ticket_deleted_permanently Investigation
Delete Bulk Tickets	Deletes multiple tickets from Zendesk based on a comma-separated list of ticket IDs you have specified. You can specify a maximum of 100 ticket IDs to be deleted in a single operation. You can get the IDs of deleted tickets using the Get Deleted Ticket List action.	delete_bulk_tickets Investigation
Delete Bulk Of Tickets Permanently	Deletes tickets permanently (ticket has already been deleted) from Zendesk based on a comma-separated list of ticket IDs you have specified. You can specify a maximum of 100 ticket IDs to be deleted in a single operation. If one ticket fails to be deleted, this action still attempts to delete the other tickets. If the job succeeds, the tickets that were successfully deleted are permanently deleted, and the IDs of these tickets will not be listed in the Get Deleted Ticket List action. This action cannot be undone.	delete_bulk_tickets_permanently Investigation

operation: Create Ticket

Input parameters

Parameter	Description
Assignee ID	ID of the assignee to whom you want to assign the newly created ticket.
Subject	Subject of the ticket that you want to create on Zendesk.
Description	Description of the ticket that you want to create on Zendesk.
Priority	(Optional) Priority of the ticket that you want to create on Zendesk. You can choose from the following options: Low, Normal, High, or Urgent.
Type	(Optional) Type of the ticket that you want to create on Zendesk. You can choose from the following options: Question, Incident, Problem, or Task.
Tags	(Optional) List of tags that you want to add to the ticket that you want to create on Zendesk.

Output

The output contains the following populated JSON schema:
{
"audit": {
"id": "",
"ticket_id": "",
"created_at": "",
"events": [
{
"id": "",
"public": "",
"audit_id": "",
"plain_body": "",
"type": "",
"body": "",
"attachments": [],
"author_id": "",
"html_body": ""
}
],
"metadata": {
"custom": {},
"system": {
"location": "",
"ip_address": "",
"longitude": "",
"latitude": "",
"client": ""
}
},
"via": {
"source": {
"to": {},
"rel": "",
"from": {}
},
"channel": ""
},
"author_id": ""
},
"ticket": {
"id": "",
"followup_ids": [],
"updated_at": "",
"forum_topic_id": "",
"has_incidents": "",
"organization_id": "",
"group_id": "",
"recipient": "",
"satisfaction_rating": "",
"requester_id": "",
"brand_id": "",
"assignee_id": "",
"collaborator_ids": [],
"submitter_id": "",
"due_at": "",
"description": "",
"url": "",
"external_id": "",
"allow_attachments": "",
"fields": [],
"priority": "",
"problem_id": "",
"email_cc_ids": [],
"status": "",
"type": "",
"custom_fields": [],
"follower_ids": [],
"is_public": "",
"sharing_agreement_ids": [],
"tags": [],
"created_at": "",
"via": {
"source": {
"to": {},
"rel": "",
"from": {}
},
"channel": ""
},
"subject": "",
"raw_subject": "",
"allow_channelback": ""
}
}

operation: Get Ticket List

Input parameters

Parameter	Description
Count	Number of tickets that you want to fetch from Zendesk.
Sort By	Field by which you want to sort the tickets. You can choose from the following options: Assignee, Assignee Name, Created At, ID, Locale, Requester Name, Status, Subject or Updated At.
Sort Order	Sorting order of the tickets, choose between Ascending or Descending.

Output

The output contains the following populated JSON schema:
{
"next_page": "",
"count": "",
"tickets": [
{
"id": "",
"followup_ids": [],
"updated_at": "",
"forum_topic_id": "",
"url": "",
"has_incidents": "",
"organization_id": "",
"group_id": "",
"recipient": "",
"satisfaction_rating": "",
"due_at": "",
"brand_id": "",
"requester_id": "",
"status": "",
"created_at": "",
"allow_channelback": "",
"assignee_id": "",
"description": "",
"custom_fields": [],
"external_id": "",
"fields": [],
"priority": "",
"problem_id": "",
"allow_attachments": "",
"type": "",
"follower_ids": [],
"is_public": "",
"sharing_agreement_ids": [],
"tags": [],
"email_cc_ids": [],
"via": {
"source": {
"from": {},
"rel": "",
"to": {}
},
"channel": ""
},
"subject": "",
"raw_subject": "",
"collaborator_ids": [],
"submitter_id": ""
}
],
"previous_page": ""
}

operation: Get Ticket Details

Input parameters

Parameter	Description
Ticket ID	ID of the ticket whose details you want to retrieve from Zendesk.

Output

The output contains the following populated JSON schema:
{
"ticket": {
"id": "",
"followup_ids": [],
"updated_at": "",
"forum_topic_id": "",
"collaborator_ids": [],
"has_incidents": "",
"organization_id": "",
"group_id": "",
"recipient": "",
"satisfaction_rating": "",
"due_at": "",
"brand_id": "",
"requester_id": "",
"status": "",
"created_at": "",
"submitter_id": "",
"type": "",
"assignee_id": "",
"description": "",
"custom_fields": [],
"external_id": "",
"allow_attachments": "",
"fields": [],
"priority": "",
"problem_id": "",
"email_cc_ids": [],
"url": "",
"follower_ids": [],
"is_public": "",
"sharing_agreement_ids": [],
"tags": [],
"via": {
"source": {
"from": {},
"rel": "",
"to": {}
},
"channel": ""
},
"subject": "",
"raw_subject": "",
"allow_channelback": ""
}
}

operation: Update Ticket

Input parameters

Parameter	Description
Ticket ID	ID of the ticket that you want to update on ZenDesk.
Comment	(Optional) Comment that you want to add to the ticket that you want to update on Zendesk.
Priority	(Optional) Priority that you want to set for the ticket that you want to update on Zendesk. You can choose from the following options: Low, Normal, High, or Urgent.
Type	(Optional) Type that you want to set for the ticket that you want to update on Zendesk. You can choose from the following options: Question, Incident, Problem, or Task.
Tags	(Optional) List of tags that you want to add to the ticket that you want to update on Zendesk.
Assignee ID	(Optional) ID of the assignee to whom you want to assign the ticket.

Output

The output contains the following populated JSON schema:
{
"audit": {
"id": "",
"ticket_id": "",
"created_at": "",
"events": [
{
"id": "",
"public": "",
"audit_id": "",
"plain_body": "",
"body": "",
"type": "",
"attachments": [],
"author_id": "",
"html_body": ""
}
],
"metadata": {
"notifications_suppressed_for": [
""
],
"custom": {},
"system": {
"location": "",
"ip_address": "",
"longitude": "",
"latitude": "",
"client": ""
}
},
"via": {
"source": {
"to": {},
"rel": "",
"from": {}
},
"channel": ""
},
"author_id": ""
},
"ticket": {
"id": "",
"followup_ids": [],
"updated_at": "",
"forum_topic_id": "",
"collaborator_ids": [],
"has_incidents": "",
"organization_id": "",
"group_id": "",
"recipient": "",
"satisfaction_rating": "",
"due_at": "",
"brand_id": "",
"requester_id": "",
"status": "",
"created_at": "",
"submitter_id": "",
"type": "",
"assignee_id": "",
"description": "",
"custom_fields": [],
"external_id": "",
"allow_attachments": "",
"fields": [],
"priority": "",
"problem_id": "",
"email_cc_ids": [],
"url": "",
"follower_ids": [],
"is_public": "",
"sharing_agreement_ids": [],
"tags": [],
"via": {
"source": {
"from": {},
"rel": "",
"to": {}
},
"channel": ""
},
"subject": "",
"raw_subject": "",
"allow_channelback": ""
}
}

operation: Get Deleted Ticket List

Input parameters

Parameter	Description
Count	Number of deleted tickets that you want to fetch from Zendesk.
Sort By	Field by which you want to sort the deleted tickets. You can choose from the following options: Assignee, Assignee Name, Created At, ID, Locale, Requester Name, Status, Subject or Updated At.
Sort Order	Sorting order of the deleted tickets, choose between Ascending or Descending.

Output

The output contains the following populated JSON schema:
{
"count": "",
"deleted_tickets": [
{
"subject": "",
"description": "",
"previous_state": "",
"id": "",
"actor": {
"id": "",
"name": ""
},
"deleted_at": ""
}
],
"previous_page": "",
"next_page": ""
}

operation: Get Ticket Related Details

Input parameters

Parameter	Description
Ticket ID	ID of the ticket whose related information you want to retrieve from Zendesk.

Output

The output contains the following populated JSON schema:
{
"ticket_related": {
"jira_issue_ids": [],
"url": "",
"from_archive": "",
"topic_id": "",
"incidents": "",
"followup_source_ids": []
}
}

operation: Mark Ticket as Spam

Input parameters

Parameter	Description
Ticket ID	ID of the ticket that you want to mark as spam in Zendesk.

Output

No output schema is available at this time.

operation: Restore Ticket

Input parameters

Parameter	Description
Ticket ID	ID of the ticket (which was previously deleted) that you want to restore on Zendesk.

Output

The output contains the following populated JSON schema:
{
"message": ""
}

operation: Delete Ticket

Input parameters

Parameter	Description
Ticket ID	ID of an existing ticket that you want to delete from Zendesk.

Output

The output contains the following populated JSON schema:
{
"message": ""
}

operation: Delete Ticket Permanently

Input parameters

Parameter	Description
Ticket ID	ID of an already deleted ticket that you want to delete permanently from Zendesk.

Output

The output contains the following populated JSON schema:
{
"message": ""
}

operation: Delete Bulk Tickets

Input parameters

Parameter	Description
Ticket ID	ID of existing tickets that you want to delete from Zendesk. You can specify a maximum of 100 ticket IDs in the CSV or list format.

Output

The output contains the following populated JSON schema:
{
"messages": []
}

operation: Delete Bulk Of Tickets Permanently

Input parameters

Parameter	Description
Ticket ID	IDs of already deleted tickets that you want to delete permanently from Zendesk. You can specify a maximum of 100 ticket IDs in the CSV or list format.

Output

The output contains the following populated JSON schema:
{
"messages": []
}

Included playbooks

The Sample - Zendesk - 2.0.0 playbook collection comes bundled with the Zendesk connector. These playbooks contain steps using which you can perform all supported actions. You can see bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the Zendesk connector.

• Create Ticket
• Delete Bulk Tickets
• Delete Bulk Tickets permanently
• Delete Ticket
• Delete Ticket Permanently
• Get Deleted Ticket List
• Get Ticket Details
• Get Ticket List
• Get Ticket Related Details
• Mark Ticket as Spam
• Restore Deleted Ticket
• Update Ticket

Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during the connector upgrade and delete.