Class: ZendeskSupportAPI::Tickets

Inherits:
Object
  • Object
show all
Defined in:
lib/zendesk_support_api/tickets.rb

Overview

Tickets class - developer.zendesk.com/rest_api/docs/support/tickets

Class Method Summary collapse

Class Method Details

.all(client) ⇒ Array

Lists out all tickets (paginates over every page)

Examples:

ZendeskSupportAPI::Tickets.all(client)
#=> Grabbing tickets (total: 215336)... / ...done
#=> [{ticket1},{ticket2}...{ticket215336}]

Parameters:

Returns:

  • (Array) 


144
145
146
147
148
149
150
151
152
153
154
155
 
# File 'lib/zendesk_support_api/tickets.rb', line 144

def self.all(client)
  tickets = []
  page = "tickets.json#{includes}&page=1"
  until page.nil?
    res = client.request(:get, page)
    client.("tickets (total: #{res['count']})", page.split('=').last)
    tickets += ticket_map(res['tickets'], res)
    page = next_page(res)
  end
  puts ' ...done'
  tickets
end

.create(client, ticket) ⇒ Hash|String

Create a ticket

Examples:

ticket = {
  subject: "This is a test ticket",
  followers: [
    { user_email: '[email protected]', action: 'put' },
    { user_id: 123, action: 'put' }
  ],
  comment: {
    body: "This goes into the test ticket body!"
  },
  tags: ["free_user", "ignore"]
}
ZendeskSupportAPI::Tickets.create(client, ticket)
#=> {
#=>   "id": 1,
#=>   "subject": "This is a test ticket",
#=>   ...
#=> }

Parameters:

Returns:

  • (Hash|String) 


214
215
216
217
218
219
 
# File 'lib/zendesk_support_api/tickets.rb', line 214

def self.create(client, ticket)
  res = client.request(:post, 'tickets.json', ticket: ticket)
  return "Creation failed: #{res['details']}" if res['error']

  res
end

.create_many(client, tickets) ⇒ ZendeskSupportAPI::Client.handle_job

Creates many tickets

Parameters:

  • client (ZendeskSupportAPI::Client) —

    The client instance to use

  • tickets (Array) —

    The array of ticket hashes to use for creation

Returns:



227
228
229
230
 
# File 'lib/zendesk_support_api/tickets.rb', line 227

def self.create_many(client, tickets)
  res = client.request(:post, 'tickets/create_many.json', tickets: tickets)
  client.handle_job(res)
end

.includes ⇒ String

Prints out the include string

Examples:

ZendeskSupportAPI::Tickets.includes
#=> '?include=users,organizations,ticket_forms,comment_count'

Returns:

  • (String) 


29
30
31
 
# File 'lib/zendesk_support_api/tickets.rb', line 29

def self.includes
  '?include=users,organizations,ticket_forms,comment_count'
end

.list(client, sort = 'id', order = 'asc') ⇒ Array

List out tickets (first 100)

Examples:

ZendeskSupportAPI::Tickets.list(client)
#=> [
#=>   {
#=>     "id":      35436,
#=>     "subject": "Help I need somebody!",
#=>     ...
#=>   },
#=>   {
#=>     "id":      20057623,
#=>     "subject": "Not just anybody!",
#=>     ...
#=>   },
#=>   ...
#=> ]

Parameters:

  • client (ZendeskSupportAPI::Client) —

    The client instance to use

  • sort (String) (defaults to: 'id') —

    The sort method to use

  • order (String) (defaults to: 'asc') —

    The order method to use

Returns:

  • (Array) 


125
126
127
128
129
130
131
132
 
# File 'lib/zendesk_support_api/tickets.rb', line 125

def self.list(client, sort = 'id', order = 'asc')
  return "Invalid sort '#{sort}'" unless sort_valid?(sort)
  return "Invalid order '#{order}'" unless %w[asc desc].include?(order)

  url = "tickets.json#{includes}#{sort_order(sort, order)}"
  res = client.request(:get, url)
  res['tickets'].map { |t| ticket_object(t, res) }
end

.list_followers(client, tid) ⇒ Array

List followers of a ticket

Parameters:

Returns:

  • (Array) 


327
328
329
330
331
332
333
 
# File 'lib/zendesk_support_api/tickets.rb', line 327

def self.list_followers(client, tid)
  res = client.request(:get, "tickets/#{tid}/followers")['users']
  res['users'].each do |user|
    user['organization'] = select_obj(res['organizations'], user[org_id])
  end
  res['users']
end

.mark_as_spam(client, tid) ⇒ String

Mark a ticket as spam and suspend the user

Parameters:

Returns:

  • (String) 


282
283
284
285
286
287
 
# File 'lib/zendesk_support_api/tickets.rb', line 282

def self.mark_as_spam(client, tid)
  res = client.request(:put, "tickets/#{tid}/mark_as_spam.json")
  return "Unable to mark ticket as spam: #{res['error']}" if res['error']

  "Ticket #{tid} marked as spam"
end

.mark_many_as_spam(client, tids) ⇒ ZendeskSupportAPI::Client.handle_job

Mark many tickets as spam and suspend their users

Parameters:

Returns:



295
296
297
298
299
 
# File 'lib/zendesk_support_api/tickets.rb', line 295

def self.mark_many_as_spam(client, tids)
  url = "tickets/mark_many_as_spam.json?ids=#{tids.join(',')}"
  res = client.request(:put, url)
  client.handle_job(res)
end

.merge(client, tid, hash) ⇒ ZendeskSupportAPI::Client.handle_job

Merge Tickets into Target Ticket

Examples:

merge_hash = {
  ids: [112, 113, 114],
  source_comment: "Closing in favor of #111",
  target_comment: "Merging #112, #113, and #114 into this ticket"
}
ZendeskSupportAPI::Tickets.merge(client, 111, merge_hash)

Parameters:

  • client (ZendeskSupportAPI::Client) —

    The client instance to use

  • tid (Integer) —

    The Ticket ID to merge into

  • hash (Hash) —

    The Hash to use for the merge (see example)

Returns:



316
317
318
319
 
# File 'lib/zendesk_support_api/tickets.rb', line 316

def self.merge(client, tid, hash)
  res = client.request(:post, "tickets/#{tid}/merge.json", hash)
  client.handle_job(res)
end

.next_page(res) ⇒ nil|String

Returns the string of the next_page for pagination

Parameters:

  • res (Hash) —

    The Hash containing the response from a request

Returns:

  • (nil|String) 


62
63
64
 
# File 'lib/zendesk_support_api/tickets.rb', line 62

def self.next_page(res)
  (res['next_page'].nil? ? nil : res['next_page'].split('/').last)
end

.org_id ⇒ String

Prints out organization_id

Examples:

ZendeskSupportAPI::Tickets.org_id #=> 'organization_id'

Returns:

  • (String) 


73
74
75
 
# File 'lib/zendesk_support_api/tickets.rb', line 73

def self.org_id
  'organization_id'
end

.select_obj(array, id) ⇒ Hash

Selects an object from an array based on a user ID

Parameters:

  • array (Array) —

    An array of to look in

  • id (Integer) —

    The ID to use

Returns:

  • (Hash) 


98
99
100
 
# File 'lib/zendesk_support_api/tickets.rb', line 98

def self.select_obj(array, id)
  array.select { |a| a['id'] == id }.first
end

.show(client, tid) ⇒ Hash

Shows details about a specific ticket

Examples:

ZendeskSupportAPI::Tickets.show(client, 35436)
#=> {
#=>   "id":      35436,
#=>   "subject": "My printer is on fire!",
#=>   ...
#=> }

Parameters:

Returns:

  • (Hash) 


171
172
173
174
175
 
# File 'lib/zendesk_support_api/tickets.rb', line 171

def self.show(client, tid)
  url = "tickets/#{tid}.json#{includes}"
  res = client.request(:get, url)
  res['ticket'].map { |t| ticket_object(t, res) }
end

.show_many(client, tids) ⇒ Array

Show details about many tickets

Parameters:

Returns:

  • (Array) 


183
184
185
186
187
 
# File 'lib/zendesk_support_api/tickets.rb', line 183

def self.show_many(client, tids)
  url = "tickets/show_many.json#{includes}&ids=#{tids.join(',')}"
  res = client.request(:get, url)
  res['tickets'].map { |t| ticket_object(t, res) }
end

.sort_order(sort, order) ⇒ String

Prints out the sort_by and order_by string for the url

Examples:

ZendeskSupportAPI::Tickets.sort_order('id', 'desc')
#=> '&sort_by=id&order_by=desc'

Parameters:

  • sort (String) —

    The sort string to use

  • order (String) —

    The order string to use

Returns:

  • (String) 


43
44
45
 
# File 'lib/zendesk_support_api/tickets.rb', line 43

def self.sort_order(sort, order)
  "&sort_by=#{sort}&order_by=#{order}"
end

.sort_valid?(sort) ⇒ Boolean

Determines if given string is a valid sort function

Examples:

ZendeskSupportAPI::Tickets.sort_valid? 'assignee' #=> true
ZendeskSupportAPI::Tickets.sort_valid? 'blah' #=> false

Parameters:

  • sort (String) —

    The sort string to use

Returns:

  • (Boolean) 


15
16
17
18
19
 
# File 'lib/zendesk_support_api/tickets.rb', line 15

def self.sort_valid?(sort)
  valid = %w[assignee assignee_name created_at group id locale requester
             requester.name status subject updated_at]
  valid.include?(sort)
end

.ticket_map(tickets, res) ⇒ Hash

Maps users into user_objects

Parameters:

  • tickets (Array) —

    The Array of tickets to map

  • res (Hash) —

    The has containing the response from a request

Returns:

  • (Hash) 


53
54
55
 
# File 'lib/zendesk_support_api/tickets.rb', line 53

def self.ticket_map(tickets, res)
  tickets.map { |t| ticket_object(t, res) }
end

.ticket_object(ticket, res) ⇒ Hash

Creates a ticket object

Parameters:

  • ticket (Hash) —

    The ticket Hash to use

  • res (Array) —

    The response to use for mapping

Returns:

  • (Hash) 


83
84
85
86
87
88
89
90
 
# File 'lib/zendesk_support_api/tickets.rb', line 83

def self.ticket_object(ticket, res)
  ticket.merge(
    organization: select_obj(res['organizations'], ticket[org_id]),
    form: select_obj(res['ticket_forms'], ticket['form_id']),
    requester: select_obj(res['users'], ticket['requester_id']),
    assignee: select_obj(res['users'], ticket['assignee_id'])
  )
end

.update(client, tid, ticket) ⇒ Hash|String

Updates a ticket

Parameters:

  • client (ZendeskSupportAPI::Client) —

    The client instance to use

  • tid (Integer) —

    The ticket ID to update

  • ticket (Hash) —

    The ticket hash to use

Returns:

  • (Hash|String) 


239
240
241
242
243
244
 
# File 'lib/zendesk_support_api/tickets.rb', line 239

def self.update(client, tid, ticket)
  res = client.request(:put, "tickets/#{tid}.json", ticket: ticket)
  return "Update of #{tid} failed: #{res['error']}" if res['error']

  res
end

.update_many(client, tickets) ⇒ ZendeskSupportAPI::Client.handle_job

Updates many tickets

Examples:

tickets = [
  {
    id: 123,
    tags: ['ultimate', 'urgent']
  },
  {
    id: 124,
    followers: [
      { user_id: 123, action: 'delete' }
    ]
  },
  {
    id: 125,
    subject: 'Staging Instance having issues'
  }
]
ZendeskSupportAPI::Tickets.update_many(client, tickets)

Parameters:

  • client (ZendeskSupportAPI::Client) —

    The client instance to use

  • tickets (Array) —

    The array of ticket hashes to use for updates

Returns:



271
272
273
274
 
# File 'lib/zendesk_support_api/tickets.rb', line 271

def self.update_many(client, tickets)
  res = client.request(:put, 'tickets/update_many.json', tickets: tickets)
  client.handle_job(res)
end