How to use the OpenGroupware.org XML-RPC API

OpenGroupware.org contains a smart XML-RPC API to perform almost all possible actions non-interactive from a program or a script. This description will show, how to use the OpenGroupware.org XML-RPC API with Perl or Python.

Traps

• Umlauts
  

  Umlauts (8-bit characters) must be transmitted in unicode (UTF-8) format.

• Integer values
  

  The SOAP::Lite module which performs the complete XMLRPC handling transmits integer values as integers in the XML-RPC request. The OpenGroupware database expects this values as strings, so you must convert them to strings manually. This could be done with the type method of SOAP::Data class. You could call SOAP::Data->type directly.

          SOAP::Data->type(string => 123);
      

• Hash values (Python dictionaries)
  

  The examples shown in the OGo XML-RPC API documentation are working with Python dictionaries. When use with Perl, you must replace that data structures with Perl hash references. You could bless them directly into Perl objects (see the RPC::Ogo module as an example).

Create users from script

If you have not ever been work with XML-RPC I will show you a short example how to create OpenGroupware users from script with XML-RPC.

This is a Perl expample wich uses the SOAP::Lite module to do the hard word. With the use of this module, remote processing with XML-RPC is very easy. If you prefer the Python programming language you should use the xmlrpclib module. With Python 2.2 and below you should use a patched version of this library which supports HTTP Basic Authentication. It can be downloaded from http://developer.skyrix.com/02_skyrix/xmlrpc/xmlrpclib.py.

The example script

Das XML-RPC Beispiel ist zweistufig aufgebaut. Eine zentrale Klasse stellt die Verbindung zum XML-RPC Server her. Von dieser Klasse erben alle Klassen, die auf einzelnen Methoden des XML-RPC API zugreifen wollen.

The example script consists of two parts. The constructor of the main class OGo connects the XML-RPC daemon. All subclasses could inherit the constructor from this class.

Main Class

    package OGo;

    use XMLRPC::Lite;
    use Carp;
    use strict;


    sub new {
        my $this = shift;
        my $pass = shift;

        croak "Missing OGo root password\n" unless $pass;

        my $class = ref($this) || $this;
        my $self = {};
        bless $self, $class;

        $self->{'ogo'} = XMLRPC::Lite
            ->proxy("http://root:$pass\@localhost:20001/x/xmlrpc");

        return $self;
    }


    ### EOP ###
    1;

The attribute 'ogo' contains the XMLRPC::Lite object. All calls to the server are method calls of this object.

Functional Class

The funcitonal class creates a user in OpenGroupware. It will derived from the OGo class defined above. The call method calls the remote method on the server via XML-RPC .

    package OGo::User;

    use Carp;
    use strict;

    use base qw(OGo);

    sub create {
        my ($self,$login,$pass,$name,$firstname) = @_;

        croak "Missing login name\n";

        $data = {
                 login     => $login
                 firstname => $firstname,
                 name      => $name,
               };

        my $account = $self->_insert($data);
        $self->_setPassword($account->{'number'},$pass);
    }


    sub _insert {
        my $self = shift;
        my $data = shift;
        $self->call('account.insert',$data);
    }


    sub _setPassword {
        my ($self,$uid,$pass) = @_;

        my $salt = join '',
                   ('.', '/', 0..9, 'A'..'Z', 'a'..'z')[rand 64, rand 64]);
        $cpass = crypt $pass,$salt;

        $self->call('account.setPassword',$uid,$pass,'true');
    }


    ### EOP ###
    1;

Next to this module you could write modules for arbritary uses. The module provides the interface to other programes and encapsulate the XML-RPC handling. In our example a little programm loads the modules and creates the OGo user.

Example program to use the modules

Das kleine Script erstellt einen Benutzer. Es könnte weitere spezifische Klassen einbinden, die das XML-RPC API abstrahieren und deren Funktionalität über für den automatisierten Zugriff auf OGo Daten nutzen.

The small script creates an OGo user. It could access some other classes to abstract other methods and data structures of the OGo XML-RPC interface. Further examples will shown at the documentation of the RPC::Ogo module.

    #!/usr/bin/perl
    #
    #
    use OGo::User;

    # create user in OGo via XML-RPC
    my $ogo =  OGo::User->new($ogorootpw);
    $ogo->create($login,$userpass,$name,$firstname);

Python example

With python, the XML-RPC handling ist similar simple as in Perl.

    #!/usr/bin/env python2.2

    import xmlrpclib

    server = xmlrpclib.Server('http://localhost:20001/x/xmlrpc',
                              login='root',password='secret')

    result = server.account.insert (
                   {
                   'login'         : "martin",
                   'firstname'     : "Martin",
                   'name'          : "Werthmöller",
                   }
           )