Changes between Initial Version and Version 1 of XmlRpcPlugin/Ruby

Apr 19, 2012, 9:27:15 AM (5 years ago)

Content moved from XmlRpcPlugin page.


  • XmlRpcPlugin/Ruby

    v1 v1  
     1=== Using XMLRPC from Ruby ===
     3You can either use the XMLRPC functionality included in the [ Ruby Standard Library] or [/attachment/wiki/XmlRpcPlugin/trac4r.tar.gz download the trac4r library] which does all the trivial stuff for you.
     5please refer to the '''SSL Support''' section if you need one.
     7==== trac4r Example ====
     8This example uses trac4r:
     11require 'trac4r/trac'
     12# 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)
     13trac = "", "myusername", "mypassword"
     14# get a list of all tickets (as an array of numbers) :include_closed => true # this is the default anyway
     16# get all the tickets
     17# NOTE: the results here are cached, so you can call it as often as you want without producing traffic more than once.
     18# use ":cached_results => false" to get the latest version :include_closed => true
     20# get a single ticket
     21ticket = 5
     22# print the data
     23puts "Title: #{ticket.summary}"
     24puts "Description: #{ticket.description}"
     25puts "Milestone: #{ticket.milestone}"
     26puts "Status: #{ticket.status}"
     27puts "Type: #{ticket.type}"
     28puts "Priority: #{ticket.priority}"
     29# get a list of all wiki pages
     31# download one page "SomeRandomPageName" # HTML version "AnotherRandomPageName" # trac syntax version (e.g. for editing)
     34# for previews use "content of a page in [wiki:WikiFormatting Trac syntax] as a ''String''"
     36# to post a page use "NameOfThePage", "content in Trac syntax"
     38# list the attachments of a wiki page "NameOfThePage"
     40# save an attachment"my_cool_document","w") do |f|
     42  f.write "NameOfThePage", "my_cool_document.pdf"
     45# upload an attachment to the page above
     46page = "NameOfThePage"
     47fn = "my_nice_doc.pdf"
     48fh =, "rb")
     49sdata =
     50data =
     51result =, name, "uploaded via ruby script", data)
     52# the correct result should be the name of the file:
     53puts "ERROR: uploading #{name} didn't work properly!" if result != name
     56Also see the included Documentation in trac4r/doc
     58If you need to do a custom query do
     63The first argument is the method name, all other arguments are directly passed to XMLRPC.
     64For this example of cause you could do `trac.api_version` instead ;)
     66If you have any problems with trac4r you can email me: niklas.cathor (eat) gmail dot com
     68==== xmlrpc Example ====
     70An example using XML-RPC directly with Ruby to append to a wiki page:
     73require 'xmlrpc/client'
     74user = "username"
     75password = "password"
     76page_name = "SandBoxRPC"
     77new_content = "\n\nMy new content"
     78new_comment = "Adding new content from ruby"
     80server = XMLRPC::Client.new2("https://#{user}:#{password}")
     81content ="wiki.getPage", page_name) + new_content"wiki.putPage", page_name, content, {"comment" => new_comment})
     85==== SSL Support + X509 ====
     86The standard ruby xmlrpc client for some reason does not support SSL at all.
     87In order to be able to use the XMLRPC over SSL with both
     88 * Client Certificate authentication
     89 * Basic Authentication
     90One must do as follows.
     92in order to proceed, you should have:
     93 * ca certificate in .pem format
     94 * personal certificate + RSA key in .p12 format (and its password, of course)
     95 * patched version of xmlrpc/client.rb
     96 * patched version of trac4r
     97 * username/password (for basic authentication)
     99Assuming you have the above, and your ca and user certificates are respectively:
     104===== The Instructions =====
     105 1. apply the patches:
     106   1. to the [attachment:"xmlrpc-client.SSL.patch" xmlrpc client]
     108sudo su -
     109cd /usr/lib/ruby/1.8/
     110patch -p0  < /path/to/xmlrpc-client.SSL.patch
     112   1. to the [attachment:"trac4r-1.2.3.SSL.patch" trac4r gem]
     114sudo su -
     115cd /var/lib/gems/1.8/gems/
     116patch -p0  < /path/to/trac4r-1.2.3.SSL.patch
     118 1. create a .yml file called {{{~/.trac/creds.yml}}} of the following structure:
     121tracurl: https://yourserver.yourdomain/yourproject
     122tracuser: yourwebuser
     123tracpass: yourwebpassword
     124certkey: /home/youruser/.openssl/certkey.p12
     125cacert: /home/youruser/.openssl/cacert.pem
     126keypass: yourkeypassword
     128   * do not forget to chmod the personal files to 600 or 400
     129 1. use the data in the code
     132require 'yaml'
     133require 'openssl'
     134require 'xmlrpc/client'
     135require 'trac4r'
     137## read the data from yaml:
     138$ymlname= "#{ENV['HOME']}/.trac/creds.yml"
     139if !File.exists?($ymlname)
     140    raise "Cannot open credentials file!"
     143    $vars = YAML::load_file($ymlname)
     144rescue Exception => e
     145    raise "Cannot load credentials file #{$ymlname}: #{e.message}\nTrace: #{e.stacktrace}"
     148## extract the certificate, and the key from the fles.
     149pkcs =$vars['certkey']),$vars['keypass'])
     150cert = pkcs.cert
     151key = pkcs.key
     152## connect to the server
     153trac =$vars['tracurl'], $vars['tracuser'], $vars['tracpass'], $vars['cacert'], cert, key)
     154## from now you can refer to the connection as open (or query it)
     155## use the API as explained above.
     158'''NOTE:''' The working environment of the code (trac4r + ssl) is:
     159 * Debian/GNU system: {{{Linux hostname 2.6.26-2-686 #1 SMP Mon Jun 21 05:58:44 UTC 2010 i686 GNU/Linux}}}
     160 * OpenSSL: {{{OpenSSL 0.9.8g 19 Oct 2007}}}
     161 * Ruby: {{{ruby 1.8.7 (2008-08-11 patchlevel 72) [i486-linux]}}}
     162 * The certificates have been issued by the above OpenSSL setup.