226 | | You can either use the XMLRPC functionality included in the [http://ruby-doc.org/stdlib/libdoc/xmlrpc/rdoc/index.html Ruby Standard Library] or [/attachment/wiki/XmlRpcPlugin/trac4r.tar.gz download the trac4r library] which does all the trivial stuff for you. |
227 | | |
228 | | please refer to the '''SSL Support''' section if you need one. |
229 | | |
230 | | ==== trac4r Example ==== |
231 | | This example uses trac4r: |
232 | | {{{ |
233 | | #!ruby |
234 | | require 'trac4r/trac' |
235 | | # initialize the connection (username and password can be ommitted if not needed, but most of the time you will need them if anonymous doesn't have XMLRPC permissions) |
236 | | trac = Trac.new "https://dev.example.com/trac/my_awesome_project", "myusername", "mypassword" |
237 | | # get a list of all tickets (as an array of numbers) |
238 | | trac.tickets.list :include_closed => true # this is the default anyway |
239 | | # get all the tickets |
240 | | # NOTE: the results here are cached, so you can call it as often as you want without producing traffic more than once. |
241 | | # use ":cached_results => false" to get the latest version |
242 | | trac.tickets.get_all :include_closed => true |
243 | | # get a single ticket |
244 | | ticket = trac.tickets.get 5 |
245 | | # print the data |
246 | | puts "Title: #{ticket.summary}" |
247 | | puts "Description: #{ticket.description}" |
248 | | puts "Milestone: #{ticket.milestone}" |
249 | | puts "Status: #{ticket.status}" |
250 | | puts "Type: #{ticket.type}" |
251 | | puts "Priority: #{ticket.priority}" |
252 | | # get a list of all wiki pages |
253 | | trac.wiki.list |
254 | | # download one page |
255 | | trac.wiki.get_html "SomeRandomPageName" # HTML version |
256 | | trac.wiki.get_raw "AnotherRandomPageName" # trac syntax version (e.g. for editing) |
257 | | # for previews use |
258 | | trac.wiki.raw_to_html "content of a page in [wiki:WikiFormatting Trac syntax] as a ''String''" |
259 | | # to post a page use |
260 | | trac.wiki.put "NameOfThePage", "content in Trac syntax" |
261 | | # list the attachments of a wiki page |
262 | | trac.wiki.attachments "NameOfThePage" |
263 | | # save an attachment |
264 | | File.new("my_cool_document","w") do |f| |
265 | | f.write trac.wiki.get_attachment "NameOfThePage", "my_cool_document.pdf" |
266 | | end |
267 | | |
268 | | # upload an attachment to the page above |
269 | | page = "NameOfThePage" |
270 | | fn = "my_nice_doc.pdf" |
271 | | fh = File.new(fn, "rb") |
272 | | sdata = fh.read |
273 | | data = XMLRPC::Base64.new(sdata) |
274 | | result = trac.wiki.put_attachment(page, name, "uploaded via ruby script", data) |
275 | | # the correct result should be the name of the file: |
276 | | puts "ERROR: uploading #{name} didn't work properly!" if result != name |
277 | | }}} |
278 | | |
279 | | Also see the included Documentation in trac4r/doc |
280 | | |
281 | | If you need to do a custom query do |
282 | | {{{ |
283 | | #!ruby |
284 | | trac.query("system.getAPIVersion") |
285 | | }}} |
286 | | The first argument is the method name, all other arguments are directly passed to XMLRPC. |
287 | | For this example of cause you could do `trac.api_version` instead ;) |
288 | | |
289 | | If you have any problems with trac4r you can email me: niklas.cathor (eat) gmail dot com |
290 | | |
291 | | ==== xmlrpc Example ==== |
292 | | |
293 | | An example using XML-RPC directly with Ruby to append to a wiki page: |
294 | | {{{ |
295 | | #!ruby |
296 | | require 'xmlrpc/client' |
297 | | user = "username" |
298 | | password = "password" |
299 | | page_name = "SandBoxRPC" |
300 | | new_content = "\n\nMy new content" |
301 | | new_comment = "Adding new content from ruby" |
302 | | |
303 | | server = XMLRPC::Client.new2("https://#{user}:#{password}@trac.server.com/trac/login/xmlrpc") |
304 | | content = server.call("wiki.getPage", page_name) + new_content |
305 | | server.call("wiki.putPage", page_name, content, {"comment" => new_comment}) |
306 | | }}} |
307 | | |
308 | | ==== SSL Support + X509 ==== |
309 | | The standard ruby xmlrpc client for some reason does not support SSL at all. |
310 | | In order to be able to use the XMLRPC over SSL with both |
311 | | * Client Certificate authentication |
312 | | * Basic Authentication |
313 | | One must do as follows. |
314 | | |
315 | | in order to proceed, you should have: |
316 | | * ca certificate in .pem format |
317 | | * personal certificate + RSA key in .p12 format (and its password, of course) |
318 | | * patched version of xmlrpc/client.rb |
319 | | * patched version of trac4r |
320 | | * username/password (for basic authentication) |
321 | | |
322 | | Assuming you have the above, and your ca and user certificates are respectively: |
323 | | {{{ |
324 | | ~/.openssl/cacert.pem |
325 | | ~/.openssl/certkey.p12 |
326 | | }}} |
327 | | ===== The Instructions ===== |
328 | | 1. apply the patches: |
329 | | 1. to the [attachment:"xmlrpc-client.SSL.patch" xmlrpc client] |
330 | | {{{ |
331 | | sudo su - |
332 | | cd /usr/lib/ruby/1.8/ |
333 | | patch -p0 < /path/to/xmlrpc-client.SSL.patch |
334 | | }}} |
335 | | 1. to the [attachment:"trac4r-1.2.3.SSL.patch" trac4r gem] |
336 | | {{{ |
337 | | sudo su - |
338 | | cd /var/lib/gems/1.8/gems/ |
339 | | patch -p0 < /path/to/trac4r-1.2.3.SSL.patch |
340 | | }}} |
341 | | 1. create a .yml file called {{{~/.trac/creds.yml}}} of the following structure: |
342 | | {{{ |
343 | | --- |
344 | | tracurl: https://yourserver.yourdomain/yourproject |
345 | | tracuser: yourwebuser |
346 | | tracpass: yourwebpassword |
347 | | certkey: /home/youruser/.openssl/certkey.p12 |
348 | | cacert: /home/youruser/.openssl/cacert.pem |
349 | | keypass: yourkeypassword |
350 | | }}} |
351 | | * do not forget to chmod the personal files to 600 or 400 |
352 | | 1. use the data in the code |
353 | | {{{ |
354 | | #!ruby |
355 | | require 'yaml' |
356 | | require 'openssl' |
357 | | require 'xmlrpc/client' |
358 | | require 'trac4r' |
359 | | |
360 | | ## read the data from yaml: |
361 | | $ymlname= "#{ENV['HOME']}/.trac/creds.yml" |
362 | | if !File.exists?($ymlname) |
363 | | raise "Cannot open credentials file!" |
364 | | end |
365 | | begin |
366 | | $vars = YAML::load_file($ymlname) |
367 | | rescue Exception => e |
368 | | raise "Cannot load credentials file #{$ymlname}: #{e.message}\nTrace: #{e.stacktrace}" |
369 | | end |
370 | | |
371 | | ## extract the certificate, and the key from the fles. |
372 | | pkcs = OpenSSL::PKCS12.new(File.open($vars['certkey']),$vars['keypass']) |
373 | | cert = pkcs.cert |
374 | | key = pkcs.key |
375 | | ## connect to the server |
376 | | trac = Trac.new($vars['tracurl'], $vars['tracuser'], $vars['tracpass'], $vars['cacert'], cert, key) |
377 | | ## from now you can refer to the connection as open (or query it) |
378 | | ## use the API as explained above. |
379 | | }}} |
380 | | |
381 | | '''NOTE:''' The working environment of the code (trac4r + ssl) is: |
382 | | * Debian/GNU system: {{{Linux hostname 2.6.26-2-686 #1 SMP Mon Jun 21 05:58:44 UTC 2010 i686 GNU/Linux}}} |
383 | | * OpenSSL: {{{OpenSSL 0.9.8g 19 Oct 2007}}} |
384 | | * Ruby: {{{ruby 1.8.7 (2008-08-11 patchlevel 72) [i486-linux]}}} |
385 | | * The certificates have been issued by the above OpenSSL setup. |
| 226 | |
| 227 | See XmlRpcPlugin/Ruby. |