fodoj / groovehq

Ruby gem for GrooveHQ api

GrooveHQ ruby client library

Client library for talking to GrooveHQ API. Supports all endpoints, as well as chaining API requests for hypermedia links.

Usage

First of all, initialize client:

client = GrooveHQ::Client.new("MY_API_TOKEN")

And then talk to API:

client.tickets(page: 2).first.number

Hypermedia support

Gem supports hypermedia links and allows to chain unlimited amount of requests like this:

client.tickets(page: 2).rels[:next].get.first.rels[:customer].get.email

List of all methods

Client methods really just map 1 to 1 to API, see all of them beyond. Check the API docs for list of available options.

agent(email)
agents(options = {})
attachments(message_id)
update_customer(options = {})
customer(email)
customers(options = {})
delete_webhook(id)
folders(options = {})
groups(options = {})
mailboxes(options = {})
create_message(ticket_number, options)
create_webhook(options)
message(message_id)
messages(ticket_number, options = {})
tickets_count(options = {})
create_ticket(options)
ticket(ticket_number)
tickets(options = {})
ticket_state(ticket_number)
update_ticket_state(ticket_number, state)
ticket_assignee(ticket_number)
update_ticket_assignee(ticket_number, assignee)
update_ticket_priority(ticket_number, priority)
update_ticket_assigned_group(ticket_number, assigned_group)

groovehq's Issues

Next/Prev hrefs link when using ResourceCollection

Steps to reproduce:

client = Groovehq::Client.new

client.tickets.rels[:next].get
# ArgumentError: bad argument (expected URI object or URI string)
# from /Users/ross/.gem/ruby/2.3.0/gems/httparty-0.13.7/lib/httparty/request.rb:55:in `path='

tickets.rels[:next].href
# => nil

Add attachments support

https://www.groovehq.com/docs/attachments

going to and from web URLs for tickets

correct me if i am wrong, but there doesn't seem to be a way to take a URL from the ticket web interface and determine the API ticket ID and visa-versa?

I want to export my GrooveHQ data NOW ... actually a quick solution

Now not really an issue ... here's a quick solution to getting your GrooveHQ data out of the system asap. I wrote it up here so you may consider incorporating into the gem.

In a file called groovehq_private_token put the value for Private Token in API Settings:

I put this in my Gemfile

source 'https://rubygems.org'
gem 'groovehq', path: 'groovehq'

And this in my dump_groovehq.rb file

require 'groovehq'
require 'pp'

export_dir = "groovehq_dump"
export_all = true # false exports just tickets and skips config
export_attachments = true # false skips exporting any attachment info
collapse_single_message = true # If just on message on ticket put everything in the ticket directory

client = GrooveHQ::Client.new(File.read('groovehq_private_token').chomp)

Dir.mkdir export_dir unless Dir.exist? export_dir

if export_all

  subdir = "#{export_dir}/config"
  Dir.mkdir subdir unless Dir.exist? subdir

  client.agents.each {|agent|
    File.open("#{subdir}/agent-#{agent.id}.yml", "w") {|f| f.puts agent.to_yaml}
  }

  client.customers.each {|customer|
    File.open("#{subdir}/customer-#{customer.id}.yml", "w") {|f| f.puts customer.to_yaml}
  }

  client.folders.each {|folder|
    File.open("#{subdir}/folder-#{folder.id}.yml", "w") {|f| f.puts folder.to_yaml}
  }

  client.groups.each {|group|
    File.open("#{subdir}/group-#{group.id}.yml", "w") {|f| f.puts group.to_yaml}
  }

  client.mailboxes.each {|mailbox|
    File.open("#{subdir}/mailbox-#{mailbox.id}.yml", "w") {|f| f.puts mailbox.to_yaml}
  }
end

client.tickets(per_page: 50).each {|ticket|

  puts "Exporting ticket #{ticket.number}"
  ticketdir = "#{export_dir}/ticket-#{ticket.number}"
  Dir.mkdir ticketdir unless Dir.exist? ticketdir

  File.open("#{ticketdir}/ticket.yml", "w") {|f| f.puts ticket.to_yaml}

  ticket.rels[:messages] && ticket.rels[:messages].get.each_with_index {|message, message_index|

    msgdir = collapse_single_message && ticket.message_count==1 ? ticketdir : "#{ticketdir}/#{message_index}"
    Dir.mkdir msgdir unless Dir.exist? msgdir

    File.open("#{msgdir}/message.yml", "w") {|f| f.puts message.to_yaml}
    File.open("#{msgdir}/message.txt", "w") {|f| f.puts message.plain_text_body}
    File.open("#{msgdir}/message.html", "w") {|f| f.puts message.body} if message.body != message.plain_text_body || message.body.strip.squeeze.downcase != message.plain_text_body.strip.squeeze.downcase

    export_attachments && message.rels[:attachments] && message.rels[:attachments].get.each {|attachment|
      File.open("#{msgdir}/attachment.yml", "w") {|f| f.puts attachment.to_yaml}
      File.open("#{msgdir}/#{attachment.filename}", "w") {|f|
        begin
          response = HTTParty.get(attachment.url)
        rescue
          STDERR.puts "Issue fetching attachment #{msgdir}/#{attachment.filename} - skipping"
          next
        end
        f.binmode
        f.write response.body
      }
    }
  }

}

download dump_groovehq.rb.txt Forced to use .txt extension

If you're fairly new to Ruby you will want to know:

• create the 3 files in the same directory
• run the command bundle install
  • permissions problem? run sudo bundle install
• adjust the export options at top of script
• run the script with the command bundle exec ruby dump_groovehq.rb
• go have coffee

HTTP 414 URI Too Long

When creating a ticket (Client.create_ticket(options)) with a long body parameter, this client blows up with a URI Too Long error sent back from the server. This leads me to believe that somehow the ticket parameters are being send as URL parameters rather than POST body parameters.

I tried to look over the code, play around with different ways to pass in the create_ticket option block (wrapping it in a hash like {body: ticket}, etc) but unfortunately, I am less familiar with HTTParty and had to get my code working.

Since this is the only real call I make, I simply implemented it myself with RestClient:

RestClient.post "https://api.groovehq.com/v1/tickets", ticket, { 'Authorization' => "Bearer #{ACCESS_TOKEN}" }

I would love to resolve this and switch back to groovehq since tt'd be nice to use/support a proper API client rather than roll something half-baked. Happy to provide more info, try stuff out, etc.

Could not set company_name of customer when creating a new ticket

For example:
client.create_ticket(from:'[email protected]', to:'[email protected]', body: 'test from api', email: '[email protected]', company_name: 'Cogent Pty Ltd', subject: 'I want this to set company name')

The ticket was created correctly, but the Customer record did get the company name set. I can set the company name with an update_customer() call but I thought the create_ticket() could do it too.