rt-client 0.2

data/rt/client.rb

@@ -0,0 +1,699 @@
+#!/usr/bin/ruby
+
+require "rubygems"
+require "rest_client"
+require "tmail"
+require "iconv"
+require 'mime/types' # requires both nokogiri and rcov.  Yuck.
+
+##A ruby library API to Request Tracker's REST interface. Requires the
+##rubygems rest-client, tmail and mime-types to be installed.  You can
+##create a file name .rtclientrc in the same directory as client.rb with a
+##default server/user/pass to connect to RT as, so that you don't have to
+##specify it/update it in lots of different scripts.
+##
+##TODO: Streaming, chunking attachments in compose method
+#
+# See each method for sample usage.  To use this, "gem install rt-client" and 
+#
+#  require "rt/client"
+
+class RT_Client
+
+  UA = "Mozilla/5.0 ruby RT Client Interface 0.2"
+  attr_reader :status, :site, :version, :cookies, :server, :user, :cookie
+  
+  # Create a new RT_Client object. Load up our stored cookie and check it.
+  # Log into RT again if needed and store the new cookie.  You can specify 
+  # login and cookie storage directories in 3 different ways:
+  #  1. Explicity during object creation
+  #  2. From a .rtclientrc file in the working directory of your ruby program
+  #  3. From a .rtclientrc file in the same directory as the library itself
+  #
+  # These are listed in order of priority; if you have explicit parameters,
+  # they are always used, even if you have .rtclientrc files.  If there
+  # is both an .rtclientrc in your program's working directory and 
+  # in the library directory, the one from your program's working directory
+  # is used.  If no parameters are specified either explicity or by use
+  # of a .rtclientrc, then the defaults of "rt_user", "rt_pass" are used
+  # with a default server of "http://localhost", and cookies are stored
+  # in the directory where the library resides.
+  #
+  #  rt= RT_Client.new( :server  => "https://tickets.ambulance.com/",
+  #                     :user    => "rt_user",
+  #                     :pass    => "rt_pass",
+  #                     :cookies => "/my/cookie/dir" )
+  #
+  #  rt= RT_Client.new # use defaults from .rtclientrc
+  #
+  # .rtclientrc format:
+  #  server=<RT server>
+  #  user=<RT user>
+  #  pass=<RT password>
+  #  cookies=<directory>
+  def initialize(*params)
+    @boundary = "----xYzZY#{rand(1000000).to_s}xYzZY"
+    @version = "0.2"
+    @status = "Not connected"
+    @server = "http://localhost/"
+    @user = "rt_user"
+    @pass = "rt_pass"
+    @cookies = Dir.pwd
+    config_file = Dir.pwd + "/.rtclientrc"
+    config = ""
+    if File.file?(config_file)
+      config = File.read(config_file)
+    else
+      config_file = File.dirname(__FILE__) + "/.rtclientrc"
+      config = File.read(config_file) if File.file?(config_file)
+    end
+    @server = $~[1] if config =~ /\s*server\s*=\s*(.*)$/i
+    @user = $~[1] if config =~ /^\s*user\s*=\s*(.*)$/i
+    @pass = $~[1] if config =~ /^\s*pass\s*=\s*(.*)$/i
+    @cookies = $~[1] if config =~ /\s*cookies\s*=\s*(.*)$/i
+    @resource = "#{@server}REST/1.0/"
+    if params.class == Array && params[0].class == Hash
+      param = params[0]
+      @user = param[:user] if param.has_key? :user
+      @pass = param[:pass] if param.has_key? :pass
+      if param.has_key? :server
+        @server = param[:server]
+        @server += "/" if @server !~ /\/$/
+        @resource = "#{@server}REST/1.0/"
+      end
+      @cookies  = param[:cookies] if param.has_key? :cookies
+    end
+    @login = { :user => @user, :pass => @pass }
+    cookiejar = "#{@cookies}/RT_Client.#{@user}.cookie" # cookie location
+    cookiejar.untaint
+    if File.file? cookiejar
+      @cookie = File.read(cookiejar).chomp
+      headers = { 'User-Agent'   => UA,
+                  'Content-Type' => "application/x-www-form-urlencoded",
+                  'Cookie'       => @cookie }
+    else
+      headers = { 'User-Agent'   => UA,
+                  'Content-Type' => "application/x-www-form-urlencoded" }
+      @cookie = ""
+    end
+    
+
+    site = RestClient::Resource.new(@resource, :headers => headers)
+    data = site.post "" # a null post just to check that we are logged in
+    
+    if @cookie.length == 0 or data =~ /401/ # we're not logged in
+      data = site.post @login, :headers => headers
+      puts data
+      @cookie = data.headers[:set_cookie].to_s.split('; ')[0]
+      # write the new cookie
+      if @cookie !~ /nil/
+        f = File.new(cookiejar,"w")
+        f.puts @cookie
+        f.close
+      end
+    end
+    headers = { 'User-Agent'   => UA,
+                'Content-Type' => "multipart/form-data; boundary=#{@boundary}",
+                'Cookie'       => @cookie }
+    @site = RestClient::Resource.new(@resource, :headers => headers)
+    @status = data
+    self.untaint
+  end
+
+  # gets the detail for a single ticket/user.  If its a ticket, its without
+  # history or attachments (to get those use the history method) .  If no
+  # type is specified, ticket is assumed.  takes a single parameter
+  # containing the ticket/user id, and returns a hash of RT Fields => values
+  # 
+  #  hash = rt.show(822)
+  #  hash = rt.show("822")
+  #  hash = rt.show("ticket/822")
+  #  hash = rt.show(:id => 822)
+  #  hash = rt.show(:id => "822")
+  #  hash = rt.show(:id => "ticket/822")
+  #  hash = rt.show("user/#{login}")
+  #  email = rt.show("user/somebody")["emailaddress"]
+  def show(id)
+    id = id[:id] if id.class == Hash
+    id = id.to_s
+    type = "ticket"
+    sid = id
+    if id =~ /(\w+)\/(.+)/
+      type = $~[1]
+      sid = $~[2]
+    end
+    reply = {}
+    resp = @site["#{type}/#{sid}/show"].get
+    resp.gsub!(/RT\/\d\.\d\.\d\s\d{3}\s.*\n\n/,"") # toss the HTTP response
+    resp.gsub!(/\n\n/,"\n") # remove double spacing, TMail stops at a blank line
+    return {:error => resp, }  if resp =~ /does not exist./
+    th = TMail::Mail.parse(resp)
+    th.each_header do |k,v|
+      reply["#{k}"] = v.to_s
+    end
+    reply
+  end
+
+  # Creates a new ticket.  Requires a hash that contains RT form fields as
+  # the keys.  Capitalization is important; use :Queue, not :queue.  You
+  # will need at least :Queue to create a ticket.  For a full list of fields
+  # you can use, try "/opt/rt3/bin/rt edit ticket/1". Returns the newly
+  # created ticket number, or a complete REST response.
+  #
+  #  id = rt.create( :Queue   => "Customer Service",
+  #                  :Cc      => "somebody\@email.com",
+  #                  :Subject => "I've fallen and I can't get up",
+  #                  :Text    => "I think my hip is broken.\nPlease help.",
+  #                  :"CF.{CustomField}" => "Urgent",
+  #                  :Attachment => "/tmp/broken_hip.jpg" )
+  def create(field_hash)
+    field_hash[:id] = "ticket/new"
+    payload = compose(field_hash)
+    resp = @site['ticket/new/edit'].post payload
+    new_id = resp.match(/Ticket\s*(\d+)/)
+    if new_id.class == MatchData
+      new_ticket = new_id[1]
+    else
+      new_ticket = resp
+    end
+    new_ticket # return the ticket number, or the full REST response
+  end
+
+  # create a new user.  Requires a hash of RT fields => values. Returns
+  # the newly created user ID, or the full REST response if there is an error.
+  # For a full list of possible parameters that you can specify, look at
+  # "/opt/rt/bin/rt edit user/1"
+  #
+  #  new_id = rt.create_user(:Name => "Joe Smith", :EmailAddress => "joes\@here.com")
+  def create_user(field_hash)
+    field_hash[:id] = "user/new"
+    payload = compose(field_hash)
+    resp = @site['user/new/edit'].post payload
+    new_id = resp.match(/User\s*(\d+)/)
+    if new_id.class == MatchData
+      new_user = new_id[1]
+    else
+      new_user = resp
+    end
+    new_user # return the new user id or the full REST response
+  end
+
+  # edit an existing ticket/user. Requires a hash containing RT
+  # form fields as keys.  the key :id is required.
+  # returns the complete REST response, whatever it is.  If the 
+  # id supplied contains "user/", it edits a user, otherwise
+  # it edits a ticket.  For a full list of fields you can edit,
+  # try "/opt/rt3/bin/rt edit ticket/1"
+  #
+  #  resp = rt.edit(:id => 822, :Status => "resolved")
+  #  resp = rt.edit(:id => ticket_id, :"CF.{CustomField}" => var)
+  #  resp = rt.edit(:id => "user/someone", :EMailAddress => "something@here.com")
+  #  resp = rt.edit(:id => "user/bossman", :Password => "mypass")
+  #  resp = rt.edit(:id => "user/4306", :Disabled => "1")
+  def edit(field_hash)
+    if field_hash.has_key? :id
+      id = field_hash[:id]
+    else
+      raise "RT_Client.edit requires a user or ticket id in the 'id' key."
+    end
+    type = "ticket"
+    sid = id
+    if id =~ /(\w+)\/(.+)/
+      type = $~[1]
+      sid = $~[2]
+    end
+    payload = compose(field_hash)
+    resp = @site["#{type}/#{sid}/edit"].post payload
+    resp
+  end
+  
+  # Comment on a ticket.  Requires a hash, which must have an :id key
+  # containing the ticket number.  Returns the REST response.  For a list of
+  # fields you can use in a comment, try "/opt/rt3/bin/rt comment ticket/1"
+  #
+  #  rt.comment( :id   => id,
+  #              :Text => "Oh dear, I wonder if the hip smells like almonds?",
+  #              :Attachment => "/tmp/almonds.gif" )
+  def comment(field_hash)
+    if field_hash.has_key? :id
+      id = field_hash[:id]
+    else
+      raise "RT_Client.comment requires a Ticket number in the 'id' key."
+    end
+    field_hash[:Action] = "comment"
+    payload = compose(field_hash)
+    @site["ticket/#{id}/comment"].post payload
+  end
+  
+  # correspond on a ticket.  Requires a hash, which must have an :id key
+  # containing the ticket number.  Returns the REST response.  For a list of
+  # fields you can use in correspondence, try "/opt/rt3/bin/rt correspond
+  # ticket/1"
+  #
+  #  rt.correspond( :id   => id,
+  #                 :Text => "We're sending help right away.",
+  #                 :Attachment => "/tmp/admittance.doc" )
+  def correspond(field_hash)
+    if field_hash.has_key? :id
+      if field_hash[:id] =~ /ticket\/(\d+)/
+        id = $~[1]
+      else
+        id = field_hash[:id]
+      end
+    else
+      raise "RT_Client.correspond requires a Ticket number in the 'id' key."
+    end
+    field_hash[:Action] = "correspond"
+    payload = compose(field_hash)
+    @site["ticket/#{id}/comment"].post payload
+  end
+  
+  # Get a list of tickets matching some criteria.
+  # Takes a string Ticket-SQL query and an optional "order by" parameter.
+  # The order by is an RT field, prefix it with + for ascending
+  # or - for descending.
+  # Returns a nested array of arrays containing [ticket number, subject]
+  # The outer array is in the order requested.
+  #
+  #  hash = rt.list(:query => "Queue = 'Sales'")
+  #  hash = rt.list("Queue='Sales'")
+  #  hash = rt.list(:query => "Queue = 'Sales'", :order => "-Id")
+  #  hash = rt.list("Queue='Sales'","-Id")
+  def list(*params)
+    query = params[0]
+    order = ""
+    if params.size > 1
+      order = params[1]
+    end
+    if params[0].class == Hash
+      params = params[0]
+      query = params[:query] if params.has_key? :query
+      order = params[:order] if params.has_key? :order
+    end
+    reply = []
+    resp = @site["search/ticket/?query=#{URI.escape(query)}&orderby=#{order}&format=s"].get
+    raise "Invalid query (#{query})" if resp =~ /Invalid query/
+    resp = resp.split("\n") # convert to array of lines
+    resp.each do |line|
+      f = line.match(/^(\d+):\s*(.*)/)
+      reply.push [f[1],f[2]] if f.class == MatchData
+    end
+    reply
+  end
+
+  # A more extensive(expensive) query then the list method.  Takes the same
+  # parameters as the list method; a string Ticket-SQL query and optional
+  # order, but returns a lot more information.  Instead of just the ID and
+  # subject, you get back an array of hashes, where each hash represents
+  # one ticket, indentical to what you get from the show method (which only
+  # acts on one ticket).  Use with caution; this can take a long time to
+  # execute.
+  # 
+  #  array = rt.query("Queue='Sales'")
+  #  array = rt.query(:query => "Queue='Sales'",:order => "+Id")
+  #  array = rt.query("Queue='Sales'","+Id")
+  #  => array[0] = { "id" => "123", "requestors" => "someone@..", etc etc }
+  #  => array[1] = { "id" => "126", "requestors" => "someone@else..", etc etc }
+  #  => array[0]["id"] = "123"
+  def query(*params)
+    query = params[0]
+    order = ""
+    if params.size > 1
+      order = params[1]
+    end
+    if params[0].class == Hash
+      params = params[0]
+      query = params[:query] if params.has_key? :query
+      order = params[:order] if params.has_key? :order
+    end
+    replies = []
+    resp = @site["search/ticket/?query=#{URI.escape(query)}&orderby=#{order}&format=l"].get
+    return replies if resp =~/No matching results./
+    raise "Invalid query (#{query})" if resp =~ /Invalid query/
+    resp.gsub!(/RT\/\d\.\d\.\d\s\d{3}\s.*\n\n/,"") # strip HTTP response
+    tickets = resp.split("\n--\n") # -- occurs between each ticket
+    tickets.each do |ticket|
+      ticket.gsub!(/^\n/,"") # strip leading blank lines
+      ticket.gsub!(/\n\n/,"\n") # remove blank lines for TMail
+      th = TMail::Mail.parse(ticket)
+      reply = {}
+      th.each_header do |k,v|
+        reply["#{k}"] = v.to_s
+      end
+      replies.push reply
+    end
+    replies
+  end
+  
+  # Get a list of history transactions for a ticket.  Takes a ticket ID and
+  # an optional format parameter.  If the format is ommitted, the short
+  # format is assumed.  If the short format is requested, it returns an
+  # array of 2 element arrays, where each 2-element array is [ticket_id,
+  # description].  If the long format is requested, it returns an array of
+  # hashes, where each hash contains the keys:
+  #
+  # id::           (history-id)
+  # Ticket::       (Ticket this history item belongs to)
+  # TimeTaken::    (time entered by the actor that generated this item)
+  # Type::         (what type of history item this is)
+  # Field::        (what field is affected by this item, if any)
+  # OldValue::     (the old value of the Field)
+  # NewValue::     (the new value of the Field)
+  # Data::         (Additional data about the item)
+  # Description::  (Description of this item; same as short format)
+  # Content::      (The content of this item)
+  # Creator::      (the RT user that created this item)
+  # Created::      (Date/time this item was created)
+  # Attachments::  (a hash describing attachments to this item)             
+  #
+  #  history = rt.history(881)
+  #  history = rt.history(881,"short")
+  #  => [["10501"," Ticket created by blah"],["10510"," Comments added by userX"]]
+  #  history = rt.history(881,"long")
+  #  history = rt.history(:id => 881, :format => "long")
+  #  => [{"id" => "6171", "ticket" => "881" ....}, {"id" => "6180", ...} ]
+  def history(*params)
+    id = params[0]
+    format = "short"
+    format = params[1].downcase if params.size > 1
+    comments = false
+    comments = params[2] if params.size > 2
+    if params[0].class == Hash
+       params = params[0]
+       id = params[:id] if params.has_key? :id
+       format = params[:format].downcase if params.has_key? :format
+       comments = params[:comments] if params.has_key? :comments
+    end
+    id = id.to_s
+    id = $~[1] if id =~ /ticket\/(\d+)/
+    resp = @site["ticket/#{id}/history?format=#{format[0,1]}"].get
+    if format[0,1] == "s"
+      if comments
+        h = resp.split("\n").select{ |l| l =~ /^\d+:/ }
+      else
+        h = resp.split("\n").select{ |l| l =~ /^\d+: [^Comments]/ }
+      end
+      list = h.map { |l| l.split(":") }
+    else
+      resp.gsub!(/RT\/\d\.\d\.\d\s\d{3}\s.*\n\n/,"") # toss the HTTP response
+      resp.gsub!(/^#.*?\n\n/,"") # toss the 'total" line
+      resp.gsub!(/^\n/m,"") # toss blank lines
+      items = resp.split("\n--\n") 
+      list = []
+      items.each do |item|
+        th = TMail::Mail.parse(item)
+        next if not comments and th["type"].to_s =~ /Comment/ # skip comments
+        reply = {}
+        th.each_header do |k,v|
+          attachments = []
+          case k
+            when "attachments"
+              temp = item.match(/Attachments:\s*(.*)/m)
+              if temp.class != NilClass
+                atarr = temp[1].split("\n")
+                atarr.map { |a| a.gsub!(/^\s*/,"") }
+                atarr.each do |a|
+                  i = a.match(/(\d+):\s*(.*)/)
+                  s={}
+                  s[:id] = i[1].to_s
+                  s[:name] = i[2].to_s
+                  sz = i[2].match(/(.*?)\s*\((.*?)\)/)
+                  if sz.class == MatchData
+                    s[:name] = sz[1].to_s
+                    s[:size] = sz[2].to_s
+                  end
+                  attachments.push s
+                end
+                reply["attachments"] = attachments
+              end
+            when "content"
+              reply["content"] = v.to_s
+              temp = item.match(/^Content: (.*?)^\w+:/m) # TMail strips line breaks
+              reply["content"] = temp[1] if temp.class != NilClass
+            else
+              reply["#{k}"] = v.to_s
+          end
+        end
+        list.push reply
+      end        
+    end
+    list
+  end
+  
+  # Get the detail for a single history item.  Needs a ticket ID and a 
+  # history item ID, returns a hash of RT Fields => values.  The hash
+  # also contains a special key named "attachments", whose value is
+  # an array of hashes, where each hash represents an attachment.  The hash
+  # keys are :id, :name, and :size.
+  # 
+  #  x = rt.history_item(21, 6692)
+  #  x = rt.history_item(:id => 21, :history => 6692)
+  #  => x = {"ticket" => "21", "creator" => "somebody", "description" => 
+  #  =>      "something happened", "attachments" => [{:name=>"file.txt",
+  #  =>      :id=>"3289", size=>"651b"}, {:name=>"another.doc"... }]}
+  def history_item(*params)
+    id = params[0]
+    history = params[1]
+    if params[0].class == Hash
+      params = params[0]
+      id = params[:id] if params.has_key? :id
+      history = params[:history] if params.has_key? :history
+    end
+    reply = {}
+    resp = @site["ticket/#{id}/history/id/#{history}"].get
+    return reply if resp =~ /not related/ # history id must be related to the ticket id
+    resp.gsub!(/RT\/\d\.\d\.\d\s\d{3}\s.*\n\n/,"") # toss the HTTP response
+    resp.gsub!(/^#.*?\n\n/,"") # toss the 'total" line
+    resp.gsub!(/^\n/m,"") # toss blank lines
+    th = TMail::Mail.parse(resp)
+    attachments = []
+    th.each_header do |k,v|
+      case k
+        when "attachments"
+          temp = resp.match(/Attachments:\s*(.*)[^\w|$]/m)
+          if temp.class != NilClass
+            atarr = temp[1].split("\n")
+            atarr.map { |a| a.gsub!(/^\s*/,"") }
+            atarr.each do |a|
+              i = a.match(/(\d+):\s*(.*)/)
+              s={}
+              s[:id] = i[1]
+              s[:name] = i[2]
+              sz = i[2].match(/(.*?)\s*\((.*?)\)/)
+              if sz.class == MatchData
+                s[:name] = sz[1]
+                s[:size] = sz[2]
+              end
+              attachments.push s
+            end
+            reply["#{k}"] = attachments
+          end
+        when "content"
+          reply["content"] = v.to_s
+          temp = resp.match(/^Content: (.*?)^\w+:/m) # TMail strips line breaks
+          reply["content"] = temp[1] if temp.class != NilClass
+        else
+          reply["#{k}"] = v.to_s
+      end
+    end
+    reply
+  end
+  
+  # Get a list of attachments related to a ticket.
+  # Requires a ticket id, returns an array of hashes where each hash
+  # represents one attachment.  Hash keys are :id, :name, :type, :size.
+  # You can optionally request that unnamed attachments be included, 
+  # the default is to not include them.
+  def attachments(*params)
+    id = params[0]
+    unnamed = params[1]
+    if params[0].class == Hash
+      params = params[0]
+      id = params[:id] if params.has_key? :id
+      unnamed = params[:unnamed] if params.has_key? :unnamed
+    end
+    unnamed = false if unnamed.to_s == "0"
+    id = $~[1] if id =~ /ticket\/(\d+)/
+    resp = @site["ticket/#{id}/attachments"].get
+    resp.gsub!(/RT\/\d\.\d\.\d\s\d{3}\s.*\n\n/,"") # toss the HTTP response
+    resp.gsub!(/^\n/m,"") # toss blank lines
+    th = TMail::Mail.parse(resp)
+    list = th["attachments"].to_s.split(",")
+    attachments = []
+    list.each do |v|
+      attachment = {}
+      m=v.match(/(\d+):\s+(.*?)\s+\((.*?)\s+\/\s+(.*?)\)/)
+      if m.class == MatchData
+        next if m[2] == "(Unnamed)" and !unnamed
+        attachment[:id] = m[1]
+        attachment[:name] = m[2]
+        attachment[:type] = m[3]
+        attachment[:size] = m[4]
+        attachments.push attachment
+      end
+    end
+    attachments
+  end
+  
+  # Get attachment content for single attachment.  Requires a ticket ID
+  # and an attachment ID, which must be related.  If a directory parameter
+  # is supplied, the attachment is written to that directory.  If not, 
+  # the attachment content is returned in the hash returned by the 
+  # function as the key 'content', along with some other keys you always get:
+  # 
+  # transaction:: the transaction id
+  # creator::     the user id number who attached it
+  # id::          the attachment id
+  # filename::    the name of the file
+  # contenttype:: MIME content type of the attachment
+  # created::     date of the attachment
+  # parent::      an attachment id if this was an embedded MIME attachment
+  #  
+  #  x = get_attachment(21,3879)
+  #  x = get_attachment(:ticket => 21, :attachment => 3879)
+  #  x = get_attachment(:ticket => 21, :attachment => 3879, :dir = "/some/dir")
+  def get_attachment(*params)
+    tid = params[0]
+    aid = params[1]
+    dir = nil
+    dir = params[2] if params.size > 2
+    if params[0].class == Hash
+      params = params[0]
+      tid = params[:ticket] if params.has_key? :ticket
+      aid = params[:attachment] if params.has_key? :attachment
+      dir = params[:dir] if params.has_key? :dir
+    end
+    tid = $~[1] if tid =~ /ticket\/(\d+)/
+    resp = @site["ticket/#{tid}/attachments/#{aid}"].get
+    resp.gsub!(/RT\/\d\.\d\.\d\s\d{3}\s.*\n\n/,"") # toss HTTP response
+    headers = TMail::Mail.parse(resp)
+    reply = {}
+    headers.each_header do |k,v|
+      reply["#{k}"] = v.to_s
+    end
+    content = resp.match(/Content:\s+(.*)/m)[1]
+    content.gsub!(/\n\s{9}/,"\n") # strip leading spaces on each line
+    content.chomp! 
+    content.chomp! 
+    content.chomp! # 3 carriage returns at the end
+    binary = Iconv.conv("ISO-8859-1","UTF-8",content) # convert encoding
+    if dir
+      fh = File.new("#{dir}/#{headers['Filename'].to_s}","wb")
+      fh.write binary
+      fh.close
+    else
+      reply["content"] = binary
+    end
+    reply
+  end
+  
+  # Add a watcher to a ticket, but only if not already a watcher.  Takes a
+  # ticket ID, an email address (or array of email addresses), and an
+  # optional watcher type.  If no watcher type is specified, its assumed to
+  # be "Cc".  Possible watcher types are 'Requestors', 'Cc', and 'AdminCc'.
+  #
+  #  rt.add_watcher(123,"someone@here.com")
+  #  rt.add_watcher(123,["someone@here.com","another@there.com"])
+  #  rt.add_watcher(123,"someone@here.com","Requestors")
+  #  rt.add_watcher(:id => 123, :addr => "someone@here.com")
+  #  rt.add_watcher(:id => 123, :addr => ["someone@here.com","another@there.com"])
+  #  rt.add_watcher(:id => 123, :addr => "someone@here.com", :type => "AdminCc")
+  def add_watcher(*params)
+    tid = params[0]
+    addr = []
+    type = "cc"
+    addr = params[1] if params.size > 1
+    type = params[2] if params.size > 2
+    if params[0].class == Hash
+      params = params[0]
+      tid = params[:id] if params.has_key? :id
+      addr = params[:addr] if params.has_key? :addr
+      type = params[:type] if params.has_key? :type
+    end
+    addr = addr.to_a.uniq # make it array if its just a string, and remove dups
+    type.downcase!
+    tobj = show(tid) # get current watchers
+    ccs = tobj["cc"].split(", ")
+    accs = tobj["admincc"].split(", ")
+    reqs = tobj["requestors"].split(", ")
+    watchers = ccs | accs | reqs # union of all watchers
+    addr.each do |e|
+      case type
+        when "cc"
+          ccs.push(e) if not watchers.include?(e)
+        when "admincc"
+          accs.push(e) if not watchers.include?(e)
+        when "requestors"
+          reqs.push(e) if not watchers.include?(e)
+      end
+    end
+    case type
+      when "cc"
+        edit(:id => tid, :Cc => ccs.join(","))
+      when "admincc"
+        edit(:id => tid, :AdminCc => accs.join(","))
+      when "requestors"
+        edit(:id => tid, :Requestors => reqs.join(","))
+    end
+  end
+  
+  # don't give up the password when the object is inspected
+  def inspect # :nodoc:
+    mystr = super()
+    mystr.gsub!(/(.)pass=.*?([,\}])/,"\\1pass=<hidden>\\2")
+    mystr
+  end
+  
+  private
+  
+  # Private helper for composing RT's "forms".  Requires a hash where the
+  # keys are field names for an RT form.  If there's a :Text key, the value
+  # is modified to insert whitespace on continuation lines.  If there's an
+  # :Attachment key, the value is assumed to be a comma-separated list of
+  # filenames to attach.  It returns a multipart MIME body complete
+  # with boundaries and headers, suitable for an HTTP POST.
+  def compose(fields) # :doc:
+    body = ""
+    if fields.class != Hash
+      raise "RT_Client.compose requires parameters as a hash."
+    end
+    
+    # fixup Text field for RFC822 compliance
+    if fields.has_key? :Text
+      fields[:Text].gsub!(/\n/,"\n ") # insert a space on continuation lines.
+    end
+
+    # attachments
+    if fields.has_key? :Attachments
+      fields[:Attachment] = fields[:Attachments]
+    end
+    if fields.has_key? :Attachment
+      filenames = fields[:Attachment].split(',')
+      i = 0
+      filenames.each do |v|
+        filename = File.basename(v)
+        mime_type = MIME::Types.type_for(v)[0]
+        i += 1
+        param_name = "attachment_#{i.to_s}"
+        body << "--#{@boundary}\r\n"
+        body << "Content-Disposition: form-data; "
+        body << "name=\"#{URI.escape(param_name.to_s)}\"; "
+        body << "filename=\"#{URI.escape(filename)}\"\r\n"
+        body << "Content-Type: #{mime_type.simplified}\r\n\r\n"
+        body << File.read(v) # oh dear, lets hope you have lots of RAM
+      end
+      # strip paths from filenames
+      fields[:Attachment] = filenames.map {|f| File.basename(f)}.join(',') 
+    end
+
+    field_array = fields.map { |k,v| "#{k}: #{v}" }
+    content = field_array.join("\n") # our form
+    # add the form to the end of any attachments
+    body << "--#{@boundary}\r\n"
+    body << "Content-Disposition: form-data; "
+    body << "name=\"content\";\r\n\r\n"
+    body << content << "\r\n"
+    body << "--#{@boundary}--\r\n"
+    body
+  end
+end  

data/rt/rtxmlsrv.rb

@@ -0,0 +1,246 @@
+#!/usr/bin/ruby
+
+## XML RPC service to provide a cross-platform API for
+## RT ticket creation/maintenance.  Essentially just a wrapper
+## around the rt/client library.
+
+require "rubygems"             # so we can load gems
+require "rt/client"            # rt-client REST library
+require "xmlrpc/server"        # that's what we're doing
+require "date"                 # for parsing arbitrary date formats
+
+PORT=8080
+MAX_CONN=50
+
+# extend the Hash class to 
+# translate string keys into symbol keys
+class Hash # :nodoc:
+  def remapkeys!
+    n = Hash.new
+    self.each_key do |key|
+      if key =~ /\{/
+        n[eval(":\"#{key}\"")] = self[key]
+      else
+        n[eval(":#{key}")] = self[key]
+      end
+    end
+    self.replace(n)
+    n = nil
+    self
+  end
+end
+
+class TicketSrv
+
+  def initialize
+  end
+  
+  INTERFACE = XMLRPC::interface("rt") {
+    meth 'string add_watcher(struct)','Calls RT_Client::add_watcher'
+    meth 'array attachments(struct)','Calls RT_Client::attachments'
+    meth 'string comment(struct)','Calls RT_Client::comment'
+    meth 'string correspond(struct)','Calls RT_Client::correspond'
+    meth 'string create(struct)','Calls RT_Client::create'
+    meth 'string create_user(struct)','Calls RT_Client::create_user'
+    meth 'string edit(struct)','Calls RT_Client::edit'
+    meth 'struct get_attachment(struct)','Calls RT_Client::get_attachment'
+    meth 'struct history(struct)','Calls RT_Client::history (long form)'
+    meth 'struct history_item(struct)','Calls RT_Client::history_item'
+    meth 'array list(struct)','Calls RT_Client::list'
+    meth 'array query(struct)','Calls RT_Client::query (long form)'
+    meth 'struct show(struct)','Calls RT_Client::show'
+  }
+
+  # Allows watchers to be added via RT_Client::add_watcher
+  # You need to pass :id, :addr, and optionally :type
+  def add_watcher(struct)
+    struct.remapkeys!
+    if struct.has_key? :user and struct.has_key? :pass
+      rt = RT_Client.new(:user => struct[:user], :pass => struct[:pass])
+    else
+      rt = RT_Client.new
+    end
+    val = rt.add_watcher(struct)
+    rt = nil
+    val
+  end
+
+  # Gets a list of attachments via RT_Client::attachments
+  # You need to pass :id, and optionally :unnamed
+  def attachments(struct)
+    struct.remapkeys!
+    if struct.has_key? :user and struct.has_key? :pass
+      rt = RT_Client.new(:user => struct[:user], :pass => struct[:pass])
+    else
+      rt = RT_Client.new
+    end
+    rt = RT_Client.new
+    val = rt.attachments(struct)
+    rt = nil
+    val
+  end
+
+  # Adds comments to tickets via RT_Client::comment
+  def comment(struct)
+    struct.remapkeys!
+    if struct.has_key? :user and struct.has_key? :pass
+      rt = RT_Client.new(:user => struct[:user], :pass => struct[:pass])
+    else
+      rt = RT_Client.new
+    end
+    val = rt.comment(struct)
+    rt = nil
+    val
+  end
+
+  # Allows new tickets to be created via RT_Client::correspond
+  def correspond(struct)
+    struct.remapkeys!
+    if struct.has_key? :user and struct.has_key? :pass
+      rt = RT_Client.new(:user => struct[:user], :pass => struct[:pass])
+    else
+      rt = RT_Client.new
+    end
+    val = rt.correspond(struct)
+    rt = nil
+    val
+  end
+
+  # Allows new tickets to be created via RT_Client::create
+  def create(struct)
+    struct.remapkeys!
+    if struct.has_key? :user and struct.has_key? :pass
+      rt = RT_Client.new(:user => struct[:user], :pass => struct[:pass])
+    else
+      rt = RT_Client.new
+    end
+    val = rt.create(struct)
+    rt = nil
+    val
+  end
+
+  # Allows new users to be created via RT_Client::create_user
+  def create_user(struct)
+    struct.remapkeys!
+    if struct.has_key? :user and struct.has_key? :pass
+      rt = RT_Client.new(:user => struct[:user], :pass => struct[:pass])
+    else
+      rt = RT_Client.new
+    end
+    val = rt.create_user(struct)
+    rt = nil
+    val
+  end
+
+  # Allows existing ticket to be modified via RT_Client::edit
+  def edit(struct)
+    struct.remapkeys!
+    if struct.has_key? :user and struct.has_key? :pass
+      rt = RT_Client.new(:user => struct[:user], :pass => struct[:pass])
+    else
+      rt = RT_Client.new
+    end
+    val = rt.edit(struct)
+    rt = nil
+    val
+  end
+
+  # Retrieves attachments via RT_Client::get_attachment
+  def get_attachment(struct)
+    struct.remapkeys!
+    if struct.has_key? :user and struct.has_key? :pass
+      rt = RT_Client.new(:user => struct[:user], :pass => struct[:pass])
+    else
+      rt = RT_Client.new
+    end
+    val = rt.get_attachment(struct)
+    rt = nil
+    val
+  end
+
+  # Gets the history of a ticket via RT_Client::history
+  def history(struct)
+    struct.remapkeys!
+    if struct.has_key? :user and struct.has_key? :pass
+      rt = RT_Client.new(:user => struct[:user], :pass => struct[:pass])
+    else
+      rt = RT_Client.new
+    end
+    val = rt.history(struct)
+    rt = nil
+    val
+  end
+
+  # Gets a single history item via RT_Client::history_item
+  def history_item(struct)
+    struct.remapkeys!
+    if struct.has_key? :user and struct.has_key? :pass
+      rt = RT_Client.new(:user => struct[:user], :pass => struct[:pass])
+    else
+      rt = RT_Client.new
+    end
+    val = rt.history_item(struct)
+    rt = nil
+    val
+  end
+
+  # Gets a list of tickets via RT_Client::list
+  def list(struct)
+    struct.remapkeys!
+    if struct.has_key? :user and struct.has_key? :pass
+      rt = RT_Client.new(:user => struct[:user], :pass => struct[:pass])
+    else
+      rt = RT_Client.new
+    end
+    val = rt.list(struct)
+    rt = nil
+    val
+  end
+
+  # Gets a list of tickets via RT_Client::query
+  def query(struct)
+    struct.remapkeys!
+    if struct.has_key? :user and struct.has_key? :pass
+      rt = RT_Client.new(:user => struct[:user], :pass => struct[:pass])
+    else
+      rt = RT_Client.new
+    end
+    val = rt.query(struct)
+    rt = nil
+    val
+  end
+
+  # Gets detail (minus history/attachments) via RT_Client::show
+  def show(struct)
+    struct.remapkeys!
+    if struct.has_key? :user and struct.has_key? :pass
+      rt = RT_Client.new(:user => struct[:user], :pass => struct[:pass])
+    else
+      rt = RT_Client.new
+    end
+    val = rt.show(struct)
+    rt = nil
+    val
+  end
+  
+end # class TicketSrv
+
+pid = fork do
+  Signal.trap('HUP','IGNORE')
+  # set up a log file
+  logfile = File.dirname(__FILE__) + "/ticketsrv.log"
+  accfile = File.dirname(__FILE__) + "/access.log"
+  acc = File.open(accfile,"a+")
+  $stderr.reopen acc # redirect $stderr to the log as well
+  # determine the IP address to listen on and create the server
+  sock = Socket.getaddrinfo(Socket.gethostname,PORT,Socket::AF_INET,Socket::SOCK_STREAM)
+  $s = XMLRPC::Server.new(sock[0][1], sock[0][3], MAX_CONN, logfile)
+  $s.set_parser(XMLRPC::XMLParser::XMLStreamParser.new)
+  $s.add_handler(TicketSrv::INTERFACE, TicketSrv.new)
+  $s.add_introspection
+  $s.serve  # start serving
+  $stderr.reopen STDERR
+  acc.close
+end
+Process.detach(pid)
+                              

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification 
+name: rt-client
+version: !ruby/object:Gem::Version 
+  version: "0.2"
+platform: ruby
+authors: 
+- Tom Lahti
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-03-27 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rest-client
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0.9"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: tmail
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.2.0
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: mime-types
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "1.16"
+    version: 
+description: RT_Client is a ruby object that accesses the REST interface version 1.0 of a Request Tracker instance.  See http://www.bestpractical.com/ for Request Tracker.
+email: toml@bitstatement.net
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- rt/client.rb
+- rt/rtxmlsrv.rb
+has_rdoc: true
+homepage: 
+post_install_message: 
+rdoc_options: 
+- --inline-source
+- --main
+- RT_Client
+require_paths: 
+- .
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: 1.8.6
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: 
+- A working installation of RT with the REST 1.0 interface
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Ruby object for RT access via REST
+test_files: []
+