Class: Roart::Ticket

Inherits:
Object
  • Object
show all
Includes:
Callbacks, MethodFunctions, Validations
Defined in:
lib/roart/ticket.rb

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Validations

#errors, included, #invalid?, #valid?, #validator

Methods included from Callbacks

#after_create, #after_update, #before_create, #before_update

Methods included from MethodFunctions

#add_methods!

Constructor Details

#initialize(attributes = nil) ⇒ Ticket

Creates a new ticket. Attributes queue and subject are required. Expects a hash with the attributes of the ticket.

ticket = MyTicket.new(:queue => "Some Queue", :subject => "The System is Down.")
ticket.id #-> This will be the ID of the ticket in the RT System.



24
25
26
27
28
29
30
31
32
33
34
35
 
# File 'lib/roart/ticket.rb', line 24

def initialize(attributes=nil)
  if attributes
    @attributes = Roart::Tickets::DefaultAttributes.merge(attributes)
  else
    @attributes = Roart::Tickets::DefaultAttributes
  end
  @attributes.update(:id => 'ticket/new')
  @saved = false
  @history = false
  @new_record = true
  add_methods!
end

Instance Attribute Details

#full ⇒ Object (readonly)

Returns the value of attribute full.



17
18
19
 
# File 'lib/roart/ticket.rb', line 17

def full
  @full
end

#history ⇒ Object (readonly)

Returns the value of attribute history.



17
18
19
 
# File 'lib/roart/ticket.rb', line 17

def history
  @history
end

#saved ⇒ Object (readonly)

Returns the value of attribute saved.



17
18
19
 
# File 'lib/roart/ticket.rb', line 17

def saved
  @saved
end

Class Method Details

.authenticate(options) ⇒ Object

Sets the username and password used to connect to the RT server Required: :user sets the username to connect to RT :pass sets the password for the user to connect with This can be used to change a connection once the Ticket class has been initialized. Not required if you sepecify :user and :pass in the connection method

class Ticket < Roart::Ticket
  connection :server => 'server'
  authenticate :user => 'user', :pass => 'pass'
end



215
216
217
 
# File 'lib/roart/ticket.rb', line 215

def authenticate(options)
  @connection.authenticate(options)
end

.connection(options = nil) ⇒ Object

Accepts parameters for connecting to an RT server. Required: :server sets the URL for the rt server, :ie rt.server.com/ Optional: :user sets the username to connect to RT :pass sets the password for the user to connect with :adapter is the connection adapter to connect with. Defaults to Mechanize

class Ticket < Roart::Ticket
  connection :server => 'server', :user => 'user', :pass => 'pass'
end



194
195
196
197
198
199
200
 
# File 'lib/roart/ticket.rb', line 194

def connection(options=nil)
  if options
    @connection = Roart::Connection.new({:adapter => "mechanize"}.merge(options))
  else
    defined?(@connection) ? @connection : nil
  end
end

.create(options) ⇒ Object

creates a new ticket object and immediately saves it to the database.



232
233
234
235
236
 
# File 'lib/roart/ticket.rb', line 232

def create(options)
  ticket = self.new(options)
  ticket.save
  ticket
end

.default_queue(options = nil) ⇒ Object

Adds a default queue to search each time. This is overridden by specifically including a :queue option in your find method. This can be an array of queue names or a string with a single queue name.



223
224
225
226
227
228
229
 
# File 'lib/roart/ticket.rb', line 223

def default_queue(options=nil)
  if options
    @default_queue = options
  else
    defined?(@default_queue) ? @default_queue : nil
  end
end

.find(*args) ⇒ Object

Searches for a ticket or group of tickets with an active record like interface.

Find has 3 different ways to search for tickets

  • search for tickets by the id. This will search for the Ticket with the exact id and will automatically load the entire ticket into the object (full will return true).

  • search for all tickets with a hash for search options by specifying :all along with your options. This will return an array of tickets or an empty array if no tickets are found that match the options.

  • search for a single ticket with a hash for search options by specifying :first along with your options. This will return a single ticket object or nil if no tickets are found.

A hash of options for search paramaters are passed in as the last argument.

Parameters

  • :queue or :queues - the name of a queue in the ticket system. This can be specified as a string, a symbol or an array of strings or symbols. The array will search for tickets included in either queue.

  • :status - the status of the tickets to search for. This can be specified as a string, a symbol or an array of strings or symbols.

  • :subject, :content, content_type, file_name - takes a string and searches for that string in the respective field.

  • :created, :started, :resolved, :told, :last_updated, :starts, :due, :updated - looks for dates for the respective fields. Can take a Range, Array, String, Time. Range will find all tickets between the two dates (after the first, before the last). Array works the same way, using #first and #last on the array. The elements should be either db-time formatted strings or Time objects. Time will be formatted as a db string. String will be passed straight to the search.

  • :custom_fields - takes a hash of custom fields to search for. the key should be the name of the field exactly how it is in RT and the value will be what to search for.

Examples

# find first
MyTicket.find(:first)
MyTicket.find(:first, :queue => 'My Queue')
MyTicket.find(:first, :status => [:new, :open])
MyTicket.find(:first, :queue => 'My Queue', :status => :resolved)
MyTicket.find(:first, :custom_fields => {:phone => '8675309'})

# find all
MyTicket.find(:all, :subject => 'is down')
MyTicket.find(:all, :created => [Time.now - 300, Time.now])
MyTicket.find(:all, :queues => ['my queue', 'issues'])

# find by id
MyTicket.find(12345)



172
173
174
175
176
177
178
179
 
# File 'lib/roart/ticket.rb', line 172

def find(*args)
  options = args.last.is_a?(Hash) ? args.pop : {}
  case args.first
    when :first then  find_initial(options)
    when :all then    find_all(options)
    else              find_by_ids(args, options)
  end
end

Instance Method Details

#comment(comment, opt = {}) ⇒ Object

Add a comment to a ticket Example:

tix = Ticket.find(1000)
tix.comment("This is a comment", :time_worked => 45, :cc => '[email protected]')

Raises:



87
88
89
90
91
92
93
94
95
96
 
# File 'lib/roart/ticket.rb', line 87

def comment(comment, opt = {})
  comment = {:text => comment, :action => 'Correspond'}.merge(opt)

  uri = "#{self.class.connection.server}/REST/1.0/ticket/#{self.id}/comment"
  payload = comment.to_content_format
  resp = self.class.connection.post(uri, :content => payload)
  resp = resp.split("\n")
  raise TicketSystemError, "Ticket Comment Failed" unless resp.first.include?("200")
  !!resp[2].match(/^# Message recorded/)
end

#histories ⇒ Object

loads the ticket history from rt



52
53
54
 
# File 'lib/roart/ticket.rb', line 52

def histories
  @histories ||= Roart::History.default(:ticket => self)
end

#load_full! ⇒ Object

Loads all information for a ticket from RT and lets full to true. This changes the ticket object and adds methods for all the fields on the ticket. Custom fields will be prefixed with ‘cf’ so a custom field of ‘phone’ would be cf_phone. custom fields hold their case from how they are defined in RT, so a custom field of PhoneNumber would be cf_PhoneNumber and a custom field of phone_number would be cf_phone_number



42
43
44
45
46
47
48
 
# File 'lib/roart/ticket.rb', line 42

def load_full!
  unless self.full
    ticket = self.class.find(self.id)
    @attributes = ticket.instance_variable_get("@attributes")
    add_methods!
  end
end

#new_record? ⇒ Boolean

Returns:

  • (Boolean) 


105
106
107
 
# File 'lib/roart/ticket.rb', line 105

def new_record?
  return @new_record
end

#save ⇒ Object

if a ticket is new, calling save will create it in the ticketing system and assign the id that it gets to the id attribute. It returns true if the save was successful, and false if something went wrong



58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
 
# File 'lib/roart/ticket.rb', line 58

def save
  if self.id == "ticket/new"
    self.create
  else
    self.before_update
    uri = "#{self.class.connection.server}/REST/1.0/ticket/#{self.id}/edit"
    payload = @attributes.clone
    payload.delete("text")
    payload.delete("id") # Can't have text in an update, only create, use comment for updateing
    payload = payload.to_content_format
    resp = self.class.connection.post(uri, :content => payload)
    resp = resp.split("\n")
    raise TicketSystemError, "Ticket Update Failed" unless resp.first.include?("200")
    resp.each do |line|
      if line.match(/^# Ticket (\d+) updated./)
        self.after_update
        return true
      else
        #TODO: Add warnign to ticket
      end
    end
    return false
  end
end

#save! ⇒ Object

works just like save, but if the save fails, it raises an exception instead of silently returning false

Raises:



100
101
102
103
 
# File 'lib/roart/ticket.rb', line 100

def save!
  raise TicketSystemError, "Ticket Create Failed" unless self.save
  true
end