austinmoody-fogbugz-api 0.0.3 → 0.0.4

data/README.rdoc

@@ -1,28 +1,38 @@
 = Ruby FogBugz API Wrapper
 
-My attempt at creating a wrapper for the FogBugz API in Ruby.  
+An 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
+FogBugz: http://www.fogbugz.com/
 
-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
+FogBugz API Docs: http://www.fogcreek.com/FogBugz/docs/60/topics/advanced/API.html
+
+This is very much a work in progress. I needed to scratch an itch with an internal project and started on this. There are many functions of the API which are not yet implemented as a result. Please check the code to see what is done and what is not.
+
+If you want to help out please e-mail Austin (austin.moody@gmail.com) and he can add you as a collaborator.
 
 == Installation
 
-GEM coming soon hopefully.  For now nab the fogbugz-api.rb file and require in your Ruby script.
+You can install the gem from github.com by using these commands:
+
+gem sources -a http://gems.github.com
+
+sudo gem install austinmoody-fogbugz-api
 
 == 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
+fb = FogBugz.new("my.fogbugzserver.com",true) # create instance
+
+fb.logon("mylogin","mypassword") # logs into FogBugz and sets token
+
+mycases = fb.search("AssignedTo:\"Austin Moody\"") # search terms just as in FogBugz
+
+projects = fb.projects # get a list of projects
+
+fb.logoff # logout
+
+See the code and potentially the wiki at github.com for more information.

data/TODO

@@ -4,17 +4,6 @@
   * Case manipulation
     * edit, assign, reactivate, reopen, resolve, close, email, reply, forward
   * file uploads
-  * new area
-  * new person
-  * new fix for
-  * view project
-  * view area
-  * view person
-  * view fix for
-  * view category
-  * view priority
-  * view status
-  * view mailbox
   * working schedule
   * time tracking
   * source control

data/lib/fogbugz-api.rb

@@ -2,6 +2,7 @@ require 'rubygems' rescue nil
 require 'hpricot'
 require 'net/https'
 require 'cgi'
+require 'date'
 
 class FogBugzError < StandardError; end
 
@@ -56,7 +57,7 @@ class FogBugz
     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_minversion = (result/"minversion").inner_html.to_i
     @api_url = "/" + (result/"url").inner_html
 
     # Make sure this class will work w/ API version
@@ -117,8 +118,8 @@ class FogBugz
   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
+    cmd = {"fWrite"=>"1"}.merge(cmd) if fWrite
+    cmd = {"ixProject"=>ixProject}.merge(cmd) if ixProject
     result = Hpricot.XML(@connection.post(@api_url,to_params(cmd)).body)
     return list_process(result,"project","sProject")
   end
@@ -142,6 +143,21 @@ class FogBugz
     return (result/"ixProject").inner_html.to_i
   end
 
+  # Returns details about a specific project.  
+  # 
+  # * project: Either the id (ixProject) or the name (sProject).  
+  #
+  # Value returned is a Hash containing all properties of the located project.  nil is returned for unsuccessful search.
+  def project(project=nil)
+    return nil if not project
+    cmd = {"cmd" => "viewProject", "token" => @token}
+    cmd = {"ixProject" => project.to_s}.merge(cmd) if project.class == Fixnum
+    cmd = {"sProject" => project}.merge(cmd) if project.class == String
+    result = Hpricot.XML(@connection.post(@api_url,to_params(cmd)).body)
+    return_value =  list_process(result,"project","sProject")
+    return_value[return_value.keys[0]]
+  end
+
   def areas(fWrite=false, ixProject=nil, ixArea=nil)
     return_value = Hash.new
     cmd = {"cmd" => "listAreas", "token" => @token}
@@ -151,6 +167,34 @@ class FogBugz
     result = Hpricot.XML(@connection.post(@api_url,to_params(cmd)).body)
     return list_process(result,"area","sArea")
   end
+  
+  # Creates a new area within a specific project
+  #
+  # * ixProject: ID of the project to contain the new area.
+  # * sArea: Title of the new area.
+  # * ixPersonPrimaryContact: ID of the person who will be the primary contact for this area.  -1 will set to the Project's primary contact, which is the default if not specified.
+  def new_area(ixProject,sArea,ixPersonPrimaryContact=-1)
+    cmd = {"cmd" => "newArea", "token" => @token, "ixProject" => ixProject.to_s, "sArea" => sArea.to_s, "ixPersonPrimaryContact" => ixPersonPrimaryContact.to_s}
+    result = Hpricot.XML(@connection.post(@api_url,to_params(cmd)).body)
+    return (result/"ixArea").inner_html.to_i    
+  end
+
+  # Returns details about a specific area
+  #
+  # * area: Either the id of an area (ixArea) or the name of an area (sArea).  If passing name, then the ID of the project the area belongs to needs to be passed.
+  # * ixProject: ID of a project which contains specific area.  Needed if wanting details for area by name.
+  #
+  # Value returned is a Hash of containing all properties of the located area.  nil is returned for unsuccessful search.
+  def area(area=nil,ixProject=nil)
+    return nil if not area
+    cmd = {"cmd" => "viewArea", "token" => @token}
+    cmd = {"ixArea" => area.to_s}.merge(cmd) if area.class == Fixnum
+    cmd = {"sArea" => area}.merge(cmd) if area.class == String
+    cmd = {"ixProject" => ixProject.to_s}.merge(cmd) if ixProject
+    result = Hpricot.XML(@connection.post(@api_url,to_params(cmd)).body)
+    return_value = list_process(result,"area","sArea")
+    return_value[return_value.keys[0]]
+  end
 
   def fix_fors(ixProject=nil,ixFixFor=nil)
     return_value = Hash.new
@@ -161,17 +205,72 @@ class FogBugz
     return list_process(result,"fixfor","sFixFor")
   end
 
+  # Returns details about a specific Fix For (releases)
+  #
+  # * fix_for: Either the id of a Fix For (ixFixFor) or the name of a Fix For (sFixFor).  If passing name, then the ID of the project the area belongs to needs to be passed.
+  # * ixProject: ID of a project which contains specific Fix For.  Needed if wanting details for Fix For by name.
+  #
+  # Value returned is a Hash containing all properties of the located Fix For.  nil is returned for unsuccessful search.
+  def fix_for(fix_for,ixProject=nil)
+    return nil if not fix_for
+    cmd = {"cmd" => "viewFixFor", "token" => @token}
+    cmd = {"ixFixFor" => fix_for.to_s}.merge(cmd) if fix_for.class == Fixnum
+    cmd = {"sFixFor" => fix_for}.merge(cmd) if fix_for.class == String
+    cmd = {"ixProject" => ixProject.to_s}.merge(cmd) if ixProject
+    result = Hpricot.XML(@connection.post(@api_url,to_params(cmd)).body)
+    return_value = list_process(result,"fixfor","sFixFor")
+    return_value[return_value.keys[0]]
+  end
+  
+  # Creates a new FixFor within FogBugz.
+  #
+  # * sFixFor: Title for the new FixFor
+  # * fAssignable: Can cases be assigned to this FixFor?  true/false  Default is true.
+  # * ixProject: ID of the project this FixFor belongs to.  If -1 (which is default when not specified) this will be a global FixFor.
+  # * dtRelease: Release date for the new FixFor.  If not passed, no release date will be set.  Expecting DateTime class if value is passed.
+  def new_fix_for(sFixFor,fAssignable=true,ixProject=-1,dtRelease=nil)
+    return nil if dtRelease and dtRelease.class != DateTime
+    cmd = {"cmd" => "newFixFor","token"=>@token,"sFixFor"=>sFixFor,"fAssignable"=>(fAssignable) ? "1" : "0","ixProject"=>ixProject.to_s}
+    cmd = {"dtRelease"=>dtRelease}.merge(cmd) if dtRelease
+    result = Hpricot.XML(@connection.post(@api_url,to_params(cmd)).body)
+    return (result/"ixFixFor").inner_html.to_i        
+  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
+  
+  # Returns details about a specific Category
+  #
+  # * ixCategory: The id of the Category to view.
+  # 
+  # Value returned is a Hash containing all properties of the located Category.  nil is returned for unsucessful search.
+  def category(ixCategory)
+    cmd = {"cmd" => "viewCategory", "token" => @token, "ixCategory" => ixCategory.to_s}
+    result = Hpricot.XML(@connection.post(@api_url,to_params(cmd)).body)
+    return_value = list_process(result,"category","sCategory")
+    return_value[return_value.keys[0]]    
+  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 details about a specific priority
+  #
+  # * ixPriority: The id of the Priority to view
+  # 
+  # Value returned is a Hash containing all properties of the located Priority.  nil is returned for unsuccessful search.
+  def priority(ixPriority)
+    cmd = {"cmd" => "viewPriority", "token" => @token, "ixPriority" => ixPriority.to_s}
+    result = Hpricot.XML(@connection.post(@api_url,to_params(cmd)).body)
+    return_value = list_process(result,"priority","sPriority")
+    return_value[return_value.keys[0]]        
+  end
 
   # Returns list of people in corresponding categories.  
   #
@@ -191,6 +290,36 @@ class FogBugz
     return list_process(result,"person","sFullName")
   end
 
+  # Returns details for a specific FogBugz user.  Can search by person's ID or their email address.
+  #
+  # * ixPerson: ID for the person to display
+  # * sEmail: Email address for the person to display.
+  #
+  # Note: If you specify both, Email search seems to take precedence. 
+  #
+  # Value returned is a Hash of containing all properties of the located person.  nil is returned for unsuccessful search.
+  def person(ixPerson=nil,sEmail=nil)
+    return nil if not ixPerson || sEmail
+    cmd = {"cmd" => "viewPerson", "token" => @token}
+    cmd = {"ixPerson" => ixPerson.to_s}.merge(cmd) if ixPerson
+    cmd = {"sEmail" => sEmail}.merge(cmd) if sEmail
+    result = Hpricot.XML(@connection.post(@api_url, to_params(cmd)).body)
+    return_value = list_process(result,"person","sFullName")
+    return_value[return_value.keys[0]]
+  end
+  
+  # Creates a new Person within FogBugz.
+  #
+  # * sEmail: Email address of the new Person.
+  # * sFullname: Fullname of the new Person.
+  # * nType: Type for the new user.  0 = Normal User, 1 = Administrator, 2 = Community User, 3 = Virtual User
+  # * fActive: Is the new Person active? true/false
+  def new_person(sEmail,sFullname,nType,fActive=true)
+    cmd = {"cmd" => "newPerson", "token" => @token, "sEmail" => sEmail.to_s, "sFullname" => sFullname.to_s, "nType" => nType.to_s, "fActive" => (fActive) ? "1" : "0"}
+    result = Hpricot.XML(@connection.post(@api_url,to_params(cmd)).body)
+    return (result/"ixPerson").inner_html.to_i        
+  end
+
   # Returns a list of statuses for a particular category.
   #
   # * ixCategory => category to return statuses for.  If not specified, then all are returned.
@@ -206,6 +335,18 @@ class FogBugz
     return list_process(result,"status","sStatus")
   end
 
+  # Returns details about a specific status
+  #
+  # * ixStatus: The id of the Status to view
+  # 
+  # Value returned is a Hash containing all properties of the located Status.  nil is returned for unsuccessful search.  
+  def status(ixStatus)
+    cmd = {"cmd" => "viewStatus", "token" => @token, "ixStatus" => ixStatus.to_s}
+    result = Hpricot.XML(@connection.post(@api_url,to_params(cmd)).body)
+    return_value = list_process(result,"status","sStatus")
+    return_value[return_value.keys[0]]            
+  end
+
   # Returns a list of mailboxes that you have access to.
   def mailboxes
     cmd = {
@@ -218,6 +359,18 @@ class FogBugz
     return list_process(result,"mailbox","ixMailbox")
   end
 
+  # Returns details about a specific mailbox
+  #
+  # * ixMailbox: The id of the Mailbox to view
+  # 
+  # Value returned is a Hash containing all properties of the located Mailbox.  nil is returned for unsuccessful search.    
+  def mailbox(ixMailbox)
+    cmd = {"cmd" => "viewMailbox", "token" => @token, "ixMailbox" => ixMailbox.to_s}
+    result = Hpricot.XML(@connection.post(@api_url,to_params(cmd)).body)
+    return_value = list_process(result,"mailbox","ixMailbox")
+    return_value[return_value.keys[0]]    
+  end
+
   # Searches for FogBugz cases
   #
   # * q: Query for searching. Should hopefully work just like the Search box
@@ -232,13 +385,9 @@ class FogBugz
     # 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 = {"cmd" => "search","token" => @token,"q" => q, "cols" => cols.join(",")}
+    # ixBug is the key for the hash returned so I'm adding it to the cols array just in case
+    cmd = {"cols" => (cols + ["ixBug"])}.merge(cmd) if not cols.include?("ixBug")
     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")

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: austinmoody-fogbugz-api
 version: !ruby/object:Gem::Version 
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors: 
 - Austin Moody
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-07-03 00:00:00 -07:00
+date: 2008-07-09 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency