Class: FogBugz

Inherits:
Object
  • Object
show all
Defined in:
lib/fogbugz-api.rb

Overview

FogBugz class

Constant Summary collapse

API_VERSION =

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?

5
CASE_COLUMNS =

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.

%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)

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(url, use_ssl = false, token = nil) ⇒ FogBugz

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)

Raises:



49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
 
# File 'lib/fogbugz-api.rb', line 49

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

Instance Attribute Details

#api_minversion ⇒ Object (readonly)

Returns the value of attribute api_minversion.



30
31
32
 
# File 'lib/fogbugz-api.rb', line 30

def api_minversion
  @api_minversion
end

#api_url ⇒ Object (readonly)

Returns the value of attribute api_url.



30
31
32
 
# File 'lib/fogbugz-api.rb', line 30

def api_url
  @api_url
end

#api_version ⇒ Object (readonly)

Returns the value of attribute api_version.



30
31
32
 
# File 'lib/fogbugz-api.rb', line 30

def api_version
  @api_version
end

#token ⇒ Object (readonly)

Returns the value of attribute token.



30
31
32
 
# File 'lib/fogbugz-api.rb', line 30

def token
  @token
end

#url ⇒ Object (readonly)

Returns the value of attribute url.



30
31
32
 
# File 'lib/fogbugz-api.rb', line 30

def url
  @url
end

#use_ssl ⇒ Object (readonly)

Returns the value of attribute use_ssl.



30
31
32
 
# File 'lib/fogbugz-api.rb', line 30

def use_ssl
  @use_ssl
end

Instance Method Details

#areas(fWrite = false, ixProject = nil, ixArea = nil) ⇒ Object 



145
146
147
148
149
150
151
152
153
 
# File 'lib/fogbugz-api.rb', line 145

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

#categories ⇒ Object 



164
165
166
167
168
 
# File 'lib/fogbugz-api.rb', line 164

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

#filters ⇒ Object 



103
104
105
106
107
108
109
110
111
112
113
114
115
 
# File 'lib/fogbugz-api.rb', line 103

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

#fix_fors(ixProject = nil, ixFixFor = nil) ⇒ Object 



155
156
157
158
159
160
161
162
 
# File 'lib/fogbugz-api.rb', line 155

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

#listPriorities ⇒ Object 



170
171
172
173
174
 
# File 'lib/fogbugz-api.rb', line 170

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

#logoff ⇒ Object 



97
98
99
100
101
 
# File 'lib/fogbugz-api.rb', line 97

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

#logon(email, password) ⇒ Object

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.



73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
 
# File 'lib/fogbugz-api.rb', line 73

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

#mailboxes ⇒ Object

Returns a list of mailboxes that you have access to.



210
211
212
213
214
215
216
217
218
219
 
# File 'lib/fogbugz-api.rb', line 210

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

#new_case(params, cols = CASE_COLUMNS) ⇒ Object

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



259
260
261
 
# File 'lib/fogbugz-api.rb', line 259

def new_case(params, cols=CASE_COLUMNS)
  case_process("new",params,cols)
end

#new_project(sProject, ixPersonPrimaryContact, fAllowPublicSubmit, ixGroup, fInbox) ⇒ Object

Returns an integer, which is ixProject for the project created TODO - change to accept Has of parameters?



128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
 
# File 'lib/fogbugz-api.rb', line 128

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

#people(fIncludeNormal = "1", fIncludeCommunity = nil, fIncludeVirtual = nil) ⇒ Object

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.



182
183
184
185
186
187
188
189
190
191
192
 
# File 'lib/fogbugz-api.rb', line 182

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

#projects(fWrite = false, ixProject = nil) ⇒ Object 



117
118
119
120
121
122
123
124
 
# File 'lib/fogbugz-api.rb', line 117

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

#search(q, cols = CASE_COLUMNS, max = nil) ⇒ Object

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.



231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
 
# File 'lib/fogbugz-api.rb', line 231

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

#statuses(ixCategory = nil, fResolved = nil) ⇒ Object

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.



198
199
200
201
202
203
204
205
206
207
 
# File 'lib/fogbugz-api.rb', line 198

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