doc/xmlrpc.txt

   1 =========================
   2 XML-RPC access to Roundup
   3 =========================
   4
   5 .. contents::
   6
   7 Introduction
   8 ------------
   9 Version 1.4 of Roundup includes an XML-RPC frontend. Some installations find
  10 that roundup-admins requirement of local access to the tracker instance
  11 limiting. The XML-RPC frontend provides the ability to execute a limited subset
  12 of commands similar to those found in roundup-admin from remote machines.
  13
  14 roundup-xmlrpc-server
  15 ---------------------
  16 The Roundup XML-RPC server must be started before remote clients can access the
  17 tracker via XML-RPC. ``roundup-xmlrpc-server`` is installed in the scripts
  18 directory alongside ``roundup-server`` and roundup-admin``. When invoked, the
  19 location of the tracker instance must be specified.
  20
  21         roundup-xmlrpc-server -i ``/path/to/tracker``
  22
  23 The default port is ``8000``. An alternative port can be specified with the
  24 ``--port`` switch.
  25
  26 security consideration
  27 ======================
  28 Note that the current ``roundup-xmlrpc-server`` implementation does not
  29 support SSL. This means that usernames and passwords will be passed in
  30 cleartext unless the server is being proxied behind another server (such as
  31 Apache or lighttpd) that provide SSL.
  32
  33 client API
  34 ----------
  35 The server currently implements four methods. Each method requires that the
  36 user provide a username and password in the HTTP authorization header in order
  37 to authenticate the request against the tracker.
  38
  39 ======= ====================================================================
  40 Command Description
  41 ======= ====================================================================
  42 list    arguments: *classname, [property_name]*
  43
  44         List all elements of a given ``classname``. If ``property_name`` is
  45         specified, that is the property that will be displayed for each
  46         element. If ``property_name`` is not specified the default label
  47         property will be used.
  48
  49 display arguments: *designator, [property_1, ..., property_N]*
  50
  51         Display a single item in the tracker as specified by ``designator``
  52         (e.g. issue20 or user5). The default is to display all properties
  53         for the item. Alternatively, a list of properties to display can be
  54         specified.
  55
  56 create  arguments: *classname, arg_1 ... arg_N*
  57
  58         Create a new instance of ``classname`` with ``arg_1`` through
  59         ``arg_N`` as the values of the new instance. The arguments are
  60         name=value pairs (e.g. ``status='3'``).
  61
  62 set     arguments: *designator, arg_1 ... arg_N*
  63
  64         Set the values of an existing item in the tracker as specified by
  65         ``designator``. The new values are specified in ``arg_1`` through
  66         ``arg_N``. The arguments are name=value pairs (e.g. ``status='3'``).
  67
  68 filter  arguments: *classname, list or None, attributes*
  69
  70         list can be None (requires ``allow_none=True`` when
  71         instantiating the ServerProxy) to indicate search for all values,
  72         or a list of ids. The attributes are given as a dictionary of
  73         name value pairs to search for.
  74 ======= ====================================================================
  75
  76 sample python client
  77 ====================
  78 ::
  79
  80         >>> import xmlrpclib
  81         >>> roundup_server = xmlrpclib.ServerProxy('http://username:password@localhost:8000', allow_none=True)
  82         >>> roundup_server.list('user')
  83         ['admin', 'anonymous', 'demo']
  84         >>> roundup_server.list('issue', 'id')
  85         ['1']
  86         >>> roundup_server.display('issue1')
  87         {'assignedto' : None, 'files' : [], 'title' = 'yes, ..... }
  88         >>> roundup_server.display('issue1', 'priority', 'status')
  89         {'priority' : '1', 'status' : '2'}
  90         >>> roundup_server.set('issue1', 'status=3')
  91         >>> roundup_server.display('issue1', 'status')
  92         {'status' : '3' }
  93         >>> roundup_server.create('issue', "title='another bug'", "status=2")
  94         '2'
  95         >>> roundup_server.filter('user',None,{'username':'adm'})
  96         ['1']
  97         >>> roundup_server.filter('user',['1','2'],{'username':'adm'})
  98         ['1']
  99         >>> roundup_server.filter('user',['2'],{'username':'adm'})
 100         []
 101         >>> roundup_server.filter('user',[],{'username':'adm'})
 102         []