========================= XML-RPC access to Roundup ========================= .. contents:: Introduction ------------ Version 1.4 of Roundup includes an XML-RPC frontend. Some installations find that roundup-admins requirement of local access to the tracker instance limiting. The XML-RPC frontend provides the ability to execute a limited subset of commands similar to those found in roundup-admin from remote machines. There are two ways to access the xmlrpc interface: stand alone roundup-xmlrpc-server access via the roundup server stand alone roundup-xmlrpc-server --------------------------------- The Roundup XML-RPC standalone server must be started before remote clients can access the tracker via XML-RPC. ``roundup-xmlrpc-server`` is installed in the scripts directory alongside ``roundup-server`` and roundup-admin``. When invoked, the location of the tracker instance must be specified. roundup-xmlrpc-server -i ``/path/to/tracker`` The default port is ``8000``. An alternative port can be specified with the ``--port`` switch. accessing via roundup server ---------------------------- In addition to running a stand alone server described above, the xmlrpc service is available from the roundup HTTP server. Access it by sending text/xml data to the URL for the roundup tracker with the last component of the url set to 'xmlrpc'. security consideration ====================== Note that the current ``roundup-xmlrpc-server`` implementation does not support SSL. This means that usernames and passwords will be passed in cleartext unless the server is being proxied behind another server (such as Apache or lighttpd) that provide SSL. client API ---------- The server currently implements four methods. Each method requires that the user provide a username and password in the HTTP authorization header in order to authenticate the request against the tracker. ======= ==================================================================== Command Description ======= ==================================================================== list arguments: *classname, [property_name]* List all elements of a given ``classname``. If ``property_name`` is specified, that is the property that will be displayed for each element. If ``property_name`` is not specified the default label property will be used. display arguments: *designator, [property_1, ..., property_N]* Display a single item in the tracker as specified by ``designator`` (e.g. issue20 or user5). The default is to display all properties for the item. Alternatively, a list of properties to display can be specified. create arguments: *classname, arg_1 ... arg_N* Create a new instance of ``classname`` with ``arg_1`` through ``arg_N`` as the values of the new instance. The arguments are name=value pairs (e.g. ``status='3'``). set arguments: *designator, arg_1 ... arg_N* Set the values of an existing item in the tracker as specified by ``designator``. The new values are specified in ``arg_1`` through ``arg_N``. The arguments are name=value pairs (e.g. ``status='3'``). lookup arguments: *classname, key_value* looks up the key_value for the given class. The class needs to have a key and the user needs search permission on the key attribute and id for the given classname. filter arguments: *classname, list or None, attributes* list can be None (requires ``allow_none=True`` when instantiating the ServerProxy) to indicate search for all values, or a list of ids. The attributes are given as a dictionary of name value pairs to search for. ======= ==================================================================== sample python client ==================== :: >>> import xmlrpclib >>> roundup_server = xmlrpclib.ServerProxy('http://username:password@localhost:8000', allow_none=True) >>> roundup_server.list('user') ['admin', 'anonymous', 'demo'] >>> roundup_server.list('issue', 'id') ['1'] >>> roundup_server.display('issue1') {'assignedto' : None, 'files' : [], 'title' = 'yes, ..... } >>> roundup_server.display('issue1', 'priority', 'status') {'priority' : '1', 'status' : '2'} >>> roundup_server.set('issue1', 'status=3') >>> roundup_server.display('issue1', 'status') {'status' : '3' } >>> roundup_server.create('issue', "title='another bug'", "status=2") '2' >>> roundup_server.filter('user',None,{'username':'adm'}) ['1'] >>> roundup_server.filter('user',['1','2'],{'username':'adm'}) ['1'] >>> roundup_server.filter('user',['2'],{'username':'adm'}) [] >>> roundup_server.filter('user',[],{'username':'adm'}) [] >>> roundup_server.lookup('user','admin') '1' If you are accessing the interface via the roundup HTTP server, a url similar to: http://username:password@localhost:8000/tracker/xmlrpc should be used.