fogbugz-api.rb

require 'rubygems' rescue nil
require 'hpricot'
require 'net/https'
require 'cgi'

class FogBugzError < StandardError; end

# FogBugz class
class FogBugz

  # Version of the FogBuz API this was written for.  If the minversion returned
  # by FogBugz is greater than this value this library will not function.
  # TODO
  # 1. If API mismatch... destroy Object?
  API_VERSION = 5

  # This is an array of all possible values that can be returned on a case.
  # For methods that ask for cols wanted for a case this array will be used if
  # their is nothing else specified.
  CASE_COLUMNS = %w(ixBug fOpen sTitle sLatestTextSummary ixBugEventLatestText
    ixProject sProject ixArea sArea ixGroup ixPersonAssignedTo sPersonAssignedTo
    sEmailAssignedTo ixPersonOpenedBy ixPersonResolvedBy ixPersonClosedBy
    ixPersonLastEditedBy ixStatus sStatus ixPriority sPriority ixFixFor sFixFor
    dtFixFor sVersion sComputer hrsOrigEst hrsCurrEst hrsElapsed c sCustomerEmail
    ixMailbox ixCategory sCategory dtOpened dtResolved dtClosed ixBugEventLatest
    dtLastUpdated fReplied fForwarded sTicket ixDiscussTopic dtDue sReleaseNotes
    ixBugEventLastView dtLastView ixRelatedBugs sScoutDescription sScoutMessage
    fScoutStopReporting fSubscribed events)

  attr_reader :url, :token, :use_ssl, :api_version, :api_minversion, :api_url

  # Creates an instance of the FogBugz class.  
  # 
  # * url: URL to your FogBugz installation.  URL only as in my.fogbugz.com
  #   without the http or https.
  # * use_ssl: Does this server use SSL?  true/false
  # * token: Already have a token for the server?  You can provide that here.
  #
  # Connects to the specified FogBugz installation and grabs the api.xml file
  # to get other information such as API version, API minimum version, and the
  # API endpoint. Also sets http/https connection to the server and sets the
  # token if provided. FogBugzError will be raise if the minimum API version
  # returned by FogBugz is greater than API_VERSION of this class.
  #
  # Example Usage:
  #
  # fb = FogBugz.new("my.fogbugz.com",true)
  #
  def initialize(url,use_ssl=false,token=nil)
    @url = url
    @use_ssl = use_ssl
    connect

    # Attempt to grap api.xml file from the server specified by url.  Will let
    # us know API is functional and verion matches this class
    result = Hpricot.XML(@connection.get("/api.xml").body)

    @api_version = (result/"version").inner_html.to_i
    @api_minversion = (result/"version").inner_html.to_i
    @api_url = "/" + (result/"url").inner_html

    # Make sure this class will work w/ API version
    raise FogBugzError, "API version mismatch" if (API_VERSION < @api_minversion)

    @token = token ? token : ""
  end

  # Validates a user with FogBugz.  Saves the returned token for use with other
  # commands.
  #
  # If a token was already specified with new it will be overwritten with the
  # token picked up by a successful authentication.
  def logon(email,password)
    cmd = {"cmd" => "logon", "email" => email, "password" => password}

    result = Hpricot.XML(@connection.post(@api_url, to_params(cmd)).body)

    if (result/"error").length >= 1
      # error code 1 = bad login
      # error code 2 = ambiguous name
      case (result/"error").first["code"]
        when "1"
          raise FogBugzError, (result/"error").inner_html
        when "2"
          ambiguous_users = []
          (result/"person").each do |person|
            ambiguous_users << CDATA_REGEXP.match(person.inner_html)[1]
          end
          raise FogBugzError, (result/"error").inner_html + " " + ambiguous_users.join(", ")
      end  # case
    elsif (result/"token").length == 1
      # successful login
      @token = CDATA_REGEXP.match((result/"token").inner_html)[1]
    end
  end

  def logoff
    cmd = {"cmd" => "logoff", "token" => @token}
    result = Hpricot.XML(@connection.post(@api_url, to_params(cmd)).body)
    @token = ""
  end

  def filters
    cmd = {"cmd" => "listFilters", "token" => @token}
    result = Hpricot.XML(@connection.post(@api_url, to_params(cmd)).body)
    return_value = Hash.new
    (result/"filter").each do |filter|
      # create hash for each new project
      filter_name = filter.inner_html
      return_value[filter_name] = Hash.new
      return_value[filter_name]["name"] = filter_name
      return_value[filter_name] = filter.attributes.merge(return_value[filter_name])
    end
    return_value
  end

  def projects(fWrite=false, ixProject=nil)
    return_value = Hash.new
    cmd = {"cmd" => "listProjects", "token" => @token}
    {"fWrite"=>"1"}.merge(cmd) if fWrite
    {"ixProject"=>ixProject}.merge(cmd) if ixProject
    result = Hpricot.XML(@connection.post(@api_url,to_params(cmd)).body)
    return list_process(result,"project","sProject")
  end

  # Returns an integer, which is ixProject for the project created
  # TODO - change to accept Has of parameters?
  def new_project(sProject, ixPersonPrimaryContact, fAllowPublicSubmit, ixGroup, fInbox)

    # I would have thought that the fAllowPublicSubmit would have been
    # true/false... instead seems to need to be 0 or 1.
    cmd = {
      "cmd" => "newProject",
      "token" => @token,
      "sProject" => sProject,
      "ixPersonPrimaryContact" => ixPersonPrimaryContact.to_s,
      "fAllowPublicSubmit" => fAllowPublicSubmit.to_s,
      "ixGroup" => ixGroup.to_s,
      "fInbox" => fInbox.to_s
    }
    result = Hpricot.XML(@connection.post(@api_url,to_params(cmd)).body)
    return (result/"ixProject").inner_html.to_i
  end

  def areas(fWrite=false, ixProject=nil, ixArea=nil)
    return_value = Hash.new
    cmd = {"cmd" => "listAreas", "token" => @token}
    cmd = {"fWrite"=>"1"}.merge(cmd) if fWrite
    cmd = {"ixProject"=>ixProject}.merge(cmd) if ixProject
    cmd = {"ixArea" => ixArea}.merge(cmd) if ixArea
    result = Hpricot.XML(@connection.post(@api_url,to_params(cmd)).body)
    return list_process(result,"area","sArea")
  end

  def fix_fors(ixProject=nil,ixFixFor=nil)
    return_value = Hash.new
    cmd = {"cmd" => "listFixFors", "token" => @token}
    {"ixProject"=>ixProject}.merge(cmd) if ixProject
    {"ixFixFor" => ixFixFor}.merge(cmd) if ixFixFor
    result = Hpricot.XML(@connection.post(@api_url,to_params(cmd)).body)
    return list_process(result,"fixfor","sFixFor")
  end

  def categories
    cmd = {"cmd" => "listCategories", "token" => @token}
    result = Hpricot.XML(@connection.post(@api_url,to_params(cmd)).body)
    return list_process(result,"category","sCategory")
  end

  def priorities
    cmd = {"cmd" => "listPriorities", "token" => @token}
    result = Hpricot.XML(@connection.post(@api_url,to_params(cmd)).body)
    return list_process(result,"priority","sPriority")
  end

  # Returns list of people in corresponding categories.  
  #
  # * fIncludeNormal: Only include Normal users.  If no options specified,
  #   fIncludeNormal=1 is assumed.
  # * fIncludeCommunity: true/false Will include Community users in return.
  # * fIncludeVirtual: true/false Will include Virtual users in return.
  def people(fIncludeNormal="1", fIncludeCommunity=nil, fIncludeVirtual=nil)
    cmd = {
      "cmd" => "listPeople",
      "token" => @token,
      "fIncludeNormal" => fIncludeNormal
    }
    cmd = {"fIncludeCommunity" => "1"}.merge(cmd) if fIncludeCommunity
    cmd = {"fIncludeVirtual" => "1"}.merge(cmd) if fIncludeVirtual
    result = Hpricot.XML(@connection.post(@api_url, to_params(cmd)).body)
    return list_process(result,"person","sFullName")
  end

  # Returns a list of statuses for a particular category.
  #
  # * ixCategory => category to return statuses for.  If not specified, then all are returned.
  # * fResolved => If = 1 then only resolved statuses are returned.
  def statuses(ixCategory=nil,fResolved=nil)
    cmd = {
      "cmd" => "listStatuses",
      "token" => @token
    }
    cmd = {"ixCategory"=>ixCategory}.merge(cmd) if ixCategory
    cmd = {"fResolved"=>fResolved}.merge(cmd) if fResolved
    result = Hpricot.XML(@connection.post(@api_url,to_params(cmd)).body)
    return list_process(result,"status","sStatus")
  end

  # Returns a list of mailboxes that you have access to.
  def mailboxes
    cmd = {
      "cmd" => "listMailboxes",
      "token" => @token
    }
    result = Hpricot.XML(@connection.post(@api_url,to_params(cmd)).body)
    # usually lists were keyed w/ a name field.  Mailboxes just
    # weren't working for me so I'm going with ixMailbox value
    return list_process(result,"mailbox","ixMailbox")
  end

  # Searches for FogBugz cases
  #
  # * q: Query for searching. Should hopefully work just like the Search box
  #   within the FogBugz application.
  # * cols: Columns of information to be returned for each case found.  Consult
  #   FogBugz API documentation for a list.  If this is not specified the
  #   CASE_COLUMNS will be used.  This will request every possible datapoint (as
  #   of API version 5) for each case.
  # * max: Maximum number of cases to be returned for your search.  Will return
  #   all if not specified.
  def search(q, cols=CASE_COLUMNS, max=nil)
    # TODO - shoudl I worry about the "operations" returned
    # in the <case>?
    
    cmd = {
      "cmd" => "search",
      "token" => @token,
      "q" => q,
      # ixBug is the key for the hash returned so I'm adding it to the cols array just in case
      "cols" => (cols + ["ixBug"]).join(",")
    }
    cmd = {"max" => max}.merge(cmd) if max
    result = Hpricot.XML(@connection.post(@api_url,to_params(cmd)).body)
    return_value = list_process(result,"case","ixBug")
    # if one of the returned cols = events, then process 
    # this list and replace its spot in the Hash
    # with this instead of a string of XML
    return_value.each do |key,value|
      return_value[key]["events"] = list_process(Hpricot.XML(return_value[key]["events"]),"event","ixBugEvent") if return_value[key].has_key?("events")
    end
    return_value
  end

  # Creates a FogBugz case.  
  #
  # * params: must be a hash keyed with values from the FogBugz API docs.
  #   sTitle, ixProject (or sProject), etc...
  # * cols: columns to be returned about the case which gets created.  Ff not
  #   passed will use constant list (all) provided with Class
  def new_case(params, cols=CASE_COLUMNS)
    case_process("new",params,cols)
  end

  protected

  CDATA_REGEXP = /<!\[CDATA\[(.*?)\]\]>/

  # Makes connection to the FogBugz server
  #
  # Assumes port 443 for SSL connections and 80 for non-SSL connections.
  # Possibly should provide a way to override this.
  def connect
    @connection = Net::HTTP.new(@url, @use_ssl ? 443 : 80) 
    @connection.use_ssl = @use_ssl
    @connection.verify_mode = OpenSSL::SSL::VERIFY_NONE if @use_ssl
  end

  def case_process(cmd,params,cols)
    cmd = {
      "cmd" => cmd,
      "token" => @token,
      "cols" => cols.join(",")
    }.merge(params)
    result = Hpricot.XML(@connection.post(@api_url, to_params(cmd)).body)
    return_value = list_process(result,"case","ixBug")
    # if one of the returned cols = events, then process 
    # this list and replace its spot in the Hash
    # with this instead of a string of XML
    return_value.each do |key,value|
      return_value[key]["events"] = list_process(Hpricot.XML(return_value[key]["events"]),"event","ixBugEvent") if return_value[key].has_key?("events")
    end
    return_value[return_value.keys[0]]
  end

  # method used by other list methods to process the XML returned by FogBugz API.
  #
  # * xml => XML to process
  # * element => individual elements within the XML to create Hashes for within the returned value
  # * element_name => key for each individual Hash within the return value.
  #
  # EXAMPLE XML
  #<response>
  #	<categories>
  #		<category>
  #			<ixCategory>1</ixCategory>
  #			<sCategory><![CDATA[Bug]]></sCategory>
  #			<sPlural><![CDATA[Bugs]]></sPlural>
  #			<ixStatusDefault>2</ixStatusDefault>
  #			<fIsScheduleItem>false</fIsScheduleItem>
  #		</category>
  #		<category>
  #			<ixCategory>2</ixCategory>
  #			<sCategory><![CDATA[Feature]]></sCategory>
  #			<sPlural><![CDATA[Features]]></sPlural>
  #			<ixStatusDefault>8</ixStatusDefault>
  #			<fIsScheduleItem>false</fIsScheduleItem>
  #		</category>
  #	</categories>
  #</response>
  #
  # EXAMPLE CAll
  # list_process(xml, "category", "sCategory")
  #
  # EXAMPLE HASH RETURN
  #
  # {
  #   "Bug" => { 
  #       "ixCategory" => 1,
  #       "sCategory" => "Bug",
  #       "sPlural" => "Bugs",
  #       "ixStatusDefault" => 2,
  #       "fIsScheduleItem" => false
  #   },
  #   "Feature" => {
  #       "ixCategory" => 2,
  #       "sCategory" => "Feature",
  #       "sPlural" => "Features",
  #       "ixStatusDefault" => 2,
  #       "fIsScheduleItem" => false
  #   }
  # }
  def list_process(xml, element, element_name)
    return_value = Hash.new
    (xml/"#{element}").each do |item|
      if element_name[0,1] == "s"
        item_name = CDATA_REGEXP.match((item/"#{element_name}").inner_html)[1]
      else
        item_name = (item/"#{element_name}").inner_html 
      end
      return_value[item_name] = Hash.new

      item.each_child do |attribute|
        return_value[item_name][attribute.name] = attribute.inner_html
        # convert values to proper types
        return_value[item_name][attribute.name] = CDATA_REGEXP.match(attribute.inner_html)[1] if (attribute.name[0,1] == "s" or attribute.name[0,3] == "evt") and attribute.inner_html != "" and CDATA_REGEXP.match(attribute.inner_html) != nil
        return_value[item_name][attribute.name] = return_value[item_name][attribute.name].to_i if (attribute.name[0,2] == "ix" or attribute.name[0,1] == "n")
        return_value[item_name][attribute.name] = (return_value[item_name][attribute.name] == "true") ? true : false if attribute.name[0,1] == "f"

      end
    end

    return_value
  end

  # Converts a hash such as 
  #   {
  #     :cmd => "logon", 
  #     :email => "austin.moody@gmail.com", 
  #     :password => "yeahwhatever",
  #   }
  # to
  #   "cmd=logon&email=austin.moody@gmail.com&password=yeahwhatever"
  def to_params(hash)
    hash.map{|key, value| "#{key}=#{CGI.escape(value.to_s)}" }.join('&')
  end
end