The XML-RPC protocol is a standard way to connect to or exchange data with eGroupWare.

As XML-RPC specifies the transport protocol only XML-RPC homepage, I start here to document the available methods and their parameters.

If you are looking for a small / simple example on how to use eGW with XMLRPC, check out the xmlrpc app. To use it you need to create an interserver account (link in the sidebox menu of the xmlrpc app under Admin) and use client-server test to contact the created server. Please note not all tests are working in a standard eGW environment, as some are disabled in the code for security reasons.

The url for XML-RPC is http://<your_egroupware>/xmlrpc.php

Now to the documented methods:

phpgwapi

There is one really important function: authorization / login to create a eGW session. This is the only function which can be called without a session!

system.login

<?xml version="1.0"?>
<methodCall>

<methodName>system.login</methodName>

<params>

<param>

<value><struct>

<member>

<name>domain</name>

<value><string>default</string></value>

</member>

<member>

<name>username</name>

<value><string>bubba</string></value>

</member>

<member>

<name>password</name>

<value><string>gump</string></value>

</member>

</struct></value>

</param>

</params>

</methodCall>
Please note the domain is the eGW domain (database instance) and NOT the fully qualified domain-name (eg. 'default')!!!

To allow an easier (less lengthy) documentation I use now the following syntax instead of the sent http-traffic:

system.login(struct(

'domain' => 'default', // this is the eGW domain

'username' => 'my-account',

'password' => 'my-password'

))

To describe the used XML-RPC type, I use struct(...), array(...), int(...), dateTime.iso8601(...), base64(...), just single quotes for strings and for boolean True or False. This syntax is used for methods as well as responses. To specify alternatives is use curved brackets and pipe to separate the alternatives, eg. {'yes'|'no'}.

As a response you get a session-id for a successful login:
<methodResponse>

<params>

<param>

<value><struct>

<member>

<name>sessionid</name>

<value><string>cf5c5534307562fc57915608377db007</string></value>

</member>

<member>

<name>kp3</name>

<value><string>2fe54daa11c8d52116788aa3f93cb70e</string></value>

</member>

</struct></value>

</param>

</params>

</methodResponse>

or in my self-defined syntax:
methodResponse(struct(

'sessionid'=>'cf5c5534307562fc57915608377db007', // this is of cause only an example response

'kp3' => '2fe54daa11c8d52116788aa3f93cb70e'

))

And for a failed login:
You get no response but a HTTP 401 Authenticate header, which some clients need to ask the credentials from the users.

This document is for XML-RPC, the (SOAP)? calls use the same methods and parameters, but a different syntax:
<?xml version="1.0"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" xmlns:xsd="http://www.w3.org/1999/XMLSchema" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:si="http://soapinterop.org/xsd"
xmlns:ns6="http://soapinterop.org" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body> <ns6:system_login>
<server_name xsi:type=":string">my.host.name</server_name>
<username xsi:type=":string">bubba</username>
<password xsi:type=":string">gump</password>
</ns6:system_login>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

system.logout

This is to end the session on the server. After that call no further call with a session-id are possible.
system.logout(struct(

'sessionid' => 'ea35cac53d2c12bd05caecd97304478a',

'kp3' => '4f2b256e0da4e7cbbebaac9f1fc8ca4a'

))

methodResponse(struct(

'GOODBYE' => 'XOXO'

))

How to call other methods / pass the session-id

There are 2 possibilities now:
1) If your xmlrpc clients / layer supports cookies (receives them and sends them back) there is nothing you need to do :-)
2) Once a successful login return packet has been received and sessionid/kp3 have been extracted, every subsequent packet sent to the eGroupWare server must be preceded by an Authorization header. Here is a sample header:

POST /egroupware/xmlrpc.php HTTP/1.0
User-Agent: PHP XMLRPC 1.0
Host: my.local.host
Authorization: Basic ZDgxNDIyZDRkYjg?5NDEyNGNiMzZlMDhhZTdlYzAxZmY?6NTU3YzkyYjBmNGE?4ZDVlOTUzMzI?2YmU?2OTQyNjM?3YjQ?=
Content-Type: text/xml
Content-Length: 875

The longish string is a base64 encoding of the $sessionid . ':' . $kp3.

Methods of other eGW applications

• AddressbookXmlRpc search, read, create or edit contacts
• CalendarXmlRpc search, read, create or edit appointments
• InfoLogXmlRpc search, read, create or edit ToDo's, notes or phonecalls

List of used XML-RPC faults

Under certain error-conditions a method can return a XML-RPC fault, instead a regular methodResponse:

<?xml version="1.0"?>
<methodResponse>

<fault>

<value><struct>

<member>

<name>faultCode</name>

<value><int>9</int></value>

</member>

<member>

<name>faultString</name>

<value><string>Access denied</string></value>

</member>

</struct></value>

</fault>

</methodResponse>

This is a list of the used fault-codes and -strings
1: Unknown method
2: Invalid return payload: enabling debugging to examine incoming payload
3: Incorrect parameters passed to method
4: Can't introspect: method unknown
5: Didn't receive 200 OK from remote server.
6: No data received from server.
7: No SSL support compiled in.
8: CURL error
9: Access denied
10: Entry does not (longer) exist!

If you have more questions about XML-RPC mail them to me (RalfBecker) or the developers-list (egroupware-developers AT lists DOT sourceforge DOT net) and I will (try to) answer them here.

---

Back to DeveloperDocs