Introduction

The Zendesk plugins can be used to read one or more Zendesk objects from your Zendesk account. This can allow you to get deeper insights into your customer success by enriching Zendesk data with other data sources.

Use case(s)

User Storie(s)

As a pipeline developer, I would like to fetch a single object from Zendesk, so that I can get deeper insights into my customer success stories.
As a pipeline developer, I would like to fetch multiple objects from Zendesk, so that I do not have to create multiple source nodes merely to replicate all objects to a destination.
As a pipeline developer, I would like to fetch all objects apart from a blacklist from Zendesk, so that I can skip a few objects, but don't have to specify all the remaining ones explicitly.

Plugin Type

Batch Source
Batch Sink
Real-time Source
Real-time Sink
Action
Post-Run Action
Aggregate
Join
Spark Model
Spark Compute

Configurables

This integration should be built using two plugins:

Zendesk single object

Used when you want to pull only a single object from Zendesk

Section	User Facing Name	Type	Description	Optional	Constraints
Basic	Admin Email	text	Zendesk's admin email.	No	Should validate email.
	API Token	text	Zendesk's API token. Can be obtained from the Zendesk Support Admin interface. Check out Zendesk's documentation for API Token generation.	No
	Subdomains	csv	List of Zendesk's Subdomains to read object from.	No	Can have multiple values.
	Object to Pull	select	Select an object to pull from Zendesk: Comments, Groups, Organizations, Satisfaction Ratings, Tags, Ticket Fields, Ticket Metrics, Ticket Metrics Events, Tickets, Users.	No	Defaults to all.

	Start Date	textbox	(required by some Zendesk's API Endpoints) The date in format YYYY-MM-DDThh:mm:ssZ, starting from which the data is requested.	No	Depends on list of the selected objects.

Zendesk multi-object

Used when you want to pull multiple objects from Zendesk

Section	User Facing Name	Type	Description	Optional	Constraints
Basic	Admin Email	text	Zendesk's admin email.	No	Should validate email.
	API Token	text	Zendesk's API token. Can be obtained from the Zendesk Support Admin interface. Check out Zendesk's documentation for API Token generation.	No
	Subdomains	csv	List of Zendesk's Subdomains to read objects from.	No	Can have multiple values.
	Objects to Pull	multi-select	Select a list of objects to pull from Zendesk: Comments, Groups, Organizations, Satisfaction Ratings, Tags, Ticket Fields, Ticket Metrics, Ticket Metrics Events, Tickets, Users	Yes	Defaults to all.
	Objects to Skip	multi-select	Select a list of objects to skip from Zendesk. All other objects will be pulled.	Yes	Only used when Objects to pull is not specified

	Start Date	textbox	(required by some Zendesk's API Endpoints) The date in format YYYY-MM-DDThh:mm:ssZ, starting from which the data is requested.	No	Depends on list of the selected objects.

The plugin should output one record per row in Zendesk, with an additional field specifying the object where the record came from. Refer to the Salesforce multi-objects plugin for examples

Design / Implementation Tips

v2 is current version of supported Zendesk's API.
Zendesk API has support of Incremental Exports. The API lets export data from specified start_time till end_time.
Plugin will be implemented using Zendesk Java Client by Cloudbees.
Authentication will be performed using Admin Email and API Token.
Output schema will be automatically generated from selected fields.

References

Object Reference

Object		API Reference	Incremental Exports	API Permissions (Allowed For)	Constraints
Comments
	Article Comments	https://developer.zendesk.com/rest_api/docs/help_center/comments#list-comments	No	Agents End-users
	Post Comments	https://developer.zendesk.com/rest_api/docs/help_center/post_comments#list-comments	No	Agents End-users
	Ticket Comments	https://developer.zendesk.com/rest_api/docs/support/ticket_comments#list-comments	Yes	Admins
	Requests Comments	https://developer.zendesk.com/rest_api/docs/support/requests#listing-comments	No	End-users
Groups		https://developer.zendesk.com/rest_api/docs/support/groups#list-groups	No	Admins Agents
Organizations		https://developer.zendesk.com/rest_api/docs/support/organizations#list-organizations	Yes	Agents
Satisfaction Ratings		https://developer.zendesk.com/rest_api/docs/support/satisfaction_ratings#list-satisfaction-ratings	No	Admins
Tags		https://developer.zendesk.com/rest_api/docs/support/tags#list-tags	No	Admins	Lists the 500 most popular tags in the last 60 days, in decreasing popularity.
Ticket Fields		https://developer.zendesk.com/rest_api/docs/support/ticket_fields#list-ticket-fields	No	Agents
Ticket Metrics		https://developer.zendesk.com/rest_api/docs/support/ticket_metrics#list-ticket-metrics	Yes	Agents
Ticket Metrics Events		https://developer.zendesk.com/rest_api/docs/support/ticket_metric_events#list-ticket-metric-events	Yes	Admins
Tickets		https://developer.zendesk.com/rest_api/docs/support/tickets#list-tickets	Yes	Admins
Users		https://developer.zendesk.com/rest_api/docs/support/users#list-users	Yes	Admins Agents Light Agents

Object Description

Field Name

Type

Comments

Article Comments

id

number

url

string

body

string

author_id

number

source_id

number

source_type

string

locale

string

html_url

string

created_at

datetime

updated_at

datetime

vote_sum

number

vote_count

number

Post Comments

id

number

url

string

body

string

author_id

number

post_id

number

official

boolean

html_url

string

created_at

datetime

updated_at

datetime

vote_sum

number

vote_count

number

Ticket Comments

id

number

type

string

body

string

html_body

string

plain_body

string

public

boolean

author_id

number

attachments

list[attachment]

Field Name

Type

attachment

id

number

file_name

string

content_url

string

url

string

mapped_content_url

string

content_type

string

width

number

height

number

size

number

thumbnails

list[photo]

Field Name	Type
photo
id	number
file_name	string
content_url	string
url	string
mapped_content_url	string
content_type	string
width	number
height	number
size	number
inline	boolean
deleted	boolean

inline

boolean

deleted

boolean

via

via_object

Field Name	Type
via_object
channel	string
source	map[string,object]

metadata

metadata_object

Field Name	Type
metadata_object
flags	list[number]
flags_options	map[string,object]

created_at

datetime

Requests Comments

id

number

type

string

request_id

number

body

string

html_body

string

plain_body

string

public

boolean

author_id

number

attachments

list[attachment]

Field Name

Type

attachment

id

number

file_name

string

content_url

string

url

string

mapped_content_url

string

content_type

string

width

number

height

number

size

number

thumbnails

list[photo]

Field Name	Type
photo
id	number
file_name	string
content_url	string
url	string
mapped_content_url	string
content_type	string
width	number
height	number
size	number
inline	boolean
deleted	boolean

inline

boolean

deleted

boolean

created_at

datetime

Groups

id

number

url

string

name

string

description

string

deleted

boolean

created_at

datetime

updated_at

datetime

Organizations

id

number

url

string

external_id

string

name

string

created_at

datetime

updated_at

datetime

domain_names

list[string]

details

string

notes

string

group_id

number

shared_tickets

boolean

shared_comments

boolean

tags

list[string]

organization_fields

map[string,object]

Satisfaction Ratings

id

number

url

string

assignee_id

number

group_id

number

requester_id

number

ticket_id

number

score

string

created_at

datetime

updated_at

datetime

comment

string

reason

string

reason_code

number

Tags

name

string

count

number

Ticket Fields

id

number

url

string

type

string

title

string

raw_title

string

description

string

raw_description

string

position

number

active

boolean

required

boolean

collapsed_for_agents

boolean

regexp_for_validation

string

title_in_portal

string

raw_title_in_portal

string

visible_in_portal

boolean

editable_in_portal

boolean

required_in_portal

boolean

tag

string

created_at

datetime

updated_at

datetime

system_field_options

list[field_object]

Field Name	Type
field_object
id	number
name	string
position	number
raw_name	string
url	string
value	string
default	boolean

custom_field_options

list[field_object]

Field Name	Type
field_object
id	number
name	string
position	number
raw_name	string
url	string
value	string
default	boolean

sub_type_id

number

removable

boolean

agent_description

string

Ticket Metrics

id

number

ticket_id

number

url

string

group_stations

number

assignee_stations

number

reopens

number

replies

number

assignee_updated_at

datetime

requester_updated_at

datetime

status_updated_at

datetime

initially_assigned_at

datetime

assigned_at

datetime

solved_at

datetime

latest_comment_added_at

datetime

first_resolution_time_in_minutes

time_in_minutes_object

Field Name	Type
time_in_minutes_object
calendar	number
business	number

reply_time_in_minutes

time_in_minutes_object

Field Name	Type
time_in_minutes_object
calendar	number
business	number

full_resolution_time_in_minutes

time_in_minutes_object

Field Name	Type
time_in_minutes_object
calendar	number
business	number

agent_wait_time_in_minutes

time_in_minutes_object

Field Name	Type
time_in_minutes_object
calendar	number
business	number

requester_wait_time_in_minutes

time_in_minutes_object

Field Name	Type
time_in_minutes_object
calendar	number
business	number

created_at

datetime

updated_at

datetime

Ticket Metrics Events

id

number

ticket_id

number

metric

string

instance_id

number

type

string

time

datetime

sla

sla_object

Field Name

Type

sla_object

target

number

business_hours

boolean

policy

policy_object

Field Name	Type
policy_object
id	number
title	string
description	string

status

status_object

Field Name	Type
status_object
calendar	number
business	number

deleted

boolean

Tickets

id

number

url

string

external_id

string

type

string

subject

string

raw_subject

string

description

string

priority

string

status

string

recipient

string

requester_id

number

submitter_id

number

assignee_id

number

organization_id

number

group_id

number

collaborator_ids

list[number]

collaborators

list[collaborators_object]

Field Name	Type
collaborators_object
name	string
email	string

email_cc_ids

list[number]

follower_ids

list[number]

forum_topic_id

number

problem_id

number

has_incidents

boolean

due_at

datetime

Design

Approach(s)

Properties

Security

Limitation(s)

Future Work

Some future work – HYDRATOR-99999
Another future work – HYDRATOR-99999

Test Case(s)

Test case #1
Test case #2

Sample Pipeline

Please attach one or more sample pipeline(s) and associated data.

Pipeline #1

Pipeline #2

Table of Contents

Checklist

User stories documented
User stories reviewed
Design documented
Design reviewed
Feature merged
Examples and guides
Integration tests
Documentation for feature
Short video demonstrating the feature