austinmoody-fogbugz-api 0.0.2

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2008 Austin Moody
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,28 @@
+= Ruby FogBugz API Wrapper
+
+My attempt at creating a wrapper for the FogBugz API in Ruby.  
+
+More about FogBugz: http://www.fogbugz.com
+More about FogBugz API: http://www.fogcreek.com/FogBugz/docs/60/topics/advanced/API.html
+
+This is very much a work in progress.  Any questions, concerns, or if you want to help out please e-mail me: austin.moody@gmail.com
+
+== Installation
+
+GEM coming soon hopefully.  For now nab the fogbugz-api.rb file and require in your Ruby script.
+
+== Requirements
+
+* Hpricot (http://code.whytheluckystiff.net/hpricot/)
+* net/https
+* A login to a FogBugz server
+
+== Example Usage
+
+	fb = FogBugz.new("my.fogbugz.com",true)
+	
+	fb.logon("me@email.com","mypassword")
+	
+	case_search = fb.search("API errors")
+	
+	fb.logoff

data/TODO

@@ -0,0 +1,4 @@
+== FogBugz API Todo
+
+* Finish it!  At the moment it is very incomplete.  Pretty much just the list functions, search, and newCase.  
+* Create tests and make sure they work.

data/fogbugz-api.rb

@@ -0,0 +1 @@
+require "lib/fogbugz-api"

data/lib/fogbugz-api.rb

@@ -0,0 +1,375 @@
+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 listPriorities
+    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,
+      "cols" => cols.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

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification 
+name: austinmoody-fogbugz-api
+version: !ruby/object:Gem::Version 
+  version: 0.0.2
+platform: ruby
+authors: 
+- Austin Moody
+- Gregory McIntyre
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-07-03 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: hpricot
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0.6"
+    version: 
+description: 
+email: austin.moody@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+- LICENSE
+- TODO
+files: 
+- README.rdoc
+- LICENSE
+- TODO
+- fogbugz-api.rb
+- lib
+- lib/fogbugz-api.rb
+has_rdoc: true
+homepage: http://github.com/austinmoody/ruby-fogbugz-api/wikis
+post_install_message: 
+rdoc_options: 
+- --main
+- README.rdoc
+- --inline-source
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Ruby wrapper for FogBugz API
+test_files: []
+