source: trunk/phpgwapi/doc/xmlrpc/gw_interface.lyx @ 2

#LyX 1.1 created this file. For more info see http://www.lyx.org/
\lyxformat 218
\textclass docbook
\language english
\inputencoding auto
\fontscheme default
\graphics default
\paperfontsize default
\spacing single 
\papersize Default
\paperpackage a4
\use_geometry 0
\use_amsmath 0
\paperorientation portrait
\secnumdepth 3
\tocdepth 3
\paragraph_separation indent
\defskip medskip
\quotes_language english
\quotes_times 2
\papercolumns 1
\papersides 1
\paperpagestyle default

\layout Title

Proposal for a Common Groupware Interface Standard
\layout Author

(C) 2001-2004 Miles Lott <milos@groupwhere.org>
\layout Date

September 13, 2001 and December 29, 2003
\layout Standard


\begin_inset LatexCommand \tableofcontents{}

\end_inset 


\layout Section

Scope
\layout Standard

As many different opensource and freesoftware groupware systems are being
 developed, the full realization of the dream of a connected world should
 be prefaced by an agreement to interoperate.
 There are limited ways in which cooperation with these and commercial groupware
 systems may be achecived, the majority if not all of which were derived
 via the establishment of open standards.
 These might include email (POP3/IMAP), contacts(LDAP,vcard), or scheduling(ical
/vcal).
 It is felt that while these have proven themselves to be very useful, they
 are insufficient to satisfy the real needs of a typical business environment.
\layout Standard

This document hopes to provide a reasonable, if limited, recommendation
 for a set of standardized methods to be used for groupware services interaction.
 More specifically, it hopes to address the need for such a standard as
 well as to spur discussion about the common service names and methods themselve
s.
\layout Standard

Examples will be given for implementations in XML-RPC, since this standard
 is relatively fixed and open.
\layout Standard

This document does not provide recommendations for the underlying access
 control system which would allow or deny a particular action.
\layout Standard

Also not discussed here is login and authorization to be used for initial
 access to a service provider.
\layout Section

The Services
\layout Subsection

Overview
\layout Standard

There are a few common services types that will be needed for minimum useability
 of a groupware server or application.
 They are:
\layout Itemize

Contacts
\layout Itemize

Schedule
\layout Itemize

Notes
\layout Itemize

Todo
\layout Standard

These services are represented already in places such as existing groupware
 client-server applications and also in the PalmOS basic-4 buttons and applicati
ons.
 Different systems may have different names for these services internally,
 e.g.
 Contacts - addresses, addressbook, people, Schedule - calendar, agenda,
 meetings.
\layout Standard

Within each of these services are some common methods that would be called
 to store, retreive, or update data:
\layout Itemize

read_list
\layout Itemize

read
\layout Itemize

save
\layout Itemize

delete
\layout Subsection

Detail
\layout Subsubsection

Contacts
\layout Standard

The concept of contacts may encompass local addressbooks, LDAP, and lists
 stored in other media.
 The purpose of the contacts service is not to duplicate or attempt to replace
 these.
 In some respects, it might do just that.
 But its goal is more so to provide a common and shareable way for the other
 core services to create, edit, and read a common user and address list.
 All of the other services may use the contact service to obtain record
 owner information to be used in access control.
 They would also use them when it is required to share this data, as with
 a meeting where other local and non-local users will be invited to attend.
\layout Standard

Contacts may include the local installed user base, users on other cooperative
 servers, or email addresses used for limited cooperation with other groupware
 services that are not compliant with this service scheme or implementations
 thereof.
 It could also include individuals using web-based or local ISP email services.
 The scope of this document, however, is to define the service with regard
 to the common methods to be used for server-server and client-server communicat
ions:
\layout Itemize

read_list
\layout Standard

This method is used to list contacts, with or without limits, filters, or
 search criteria.
 In this way it can be used for simple lists or to search for contact records
 and their identifiers.
 The optional search criteria includes:
\layout Enumerate

start - Start at this identifier (integer: default 0)
\layout Enumerate

limit - Limit to this number of records returned(integer: unlimited by default)
\layout Enumerate

fieldlist - limit to showing only these fields (array: default to identifier,
 owner identifier, possibly firstname and lastname)
\layout Enumerate

filter - Show records that are public or private only, or other system-specific
 filters, e.g group or company(string: default '')
\layout Enumerate

query - Search internal fieldlist for a value (string: default '')
\layout Standard

The return for this method includes:
\layout Enumerate

count of number of records returned(integer)
\layout Enumerate

array consisting of: array: identifier => (array: fieldlist key => value
 pairs)
\layout Itemize

read
\layout Standard

Once the identifier for a single contact record is known, the contact may
 be read for more detail using this method.
 This takes two parameters:
\layout Enumerate

identifier - (integer: no default)
\layout Enumerate

fieldlist - limit to showing only these fields (array: default to identifier,
 owner identifier, possibly firstname and lastname)
\layout Standard

And returns:
\layout Enumerate

array consisting of: array: identifier => (array: fieldlist key => value
 pairs)
\layout Itemize

save
\layout Standard

This is a method used to save an existing record or create a new one.
 If the identifier for an existing record is not passed, a new entry will
 be created.
\layout Itemize

delete
\layout Standard

This will allow deletion of a record by passing its identifier.
\layout Subsubsection

Schedule
\layout Subsubsection

Notes
\layout Subsubsection

Todo
\layout Subsection

Examples in XML-RPC
\layout Standard

Query the contacts service for read_list, using only start and limit to
 grab the first 5 records, starting with identifier 1.
 Additionally, return only the firstname and lastname fields n_given and
 n_family (firstname and lastname in pseudo vcard format):
\layout Code

<methodCall>
\layout Code

<methodName>service.contacts.read_list</methodName>
\layout Code

<params>
\layout Code

<param>
\layout Code

<value><struct>
\layout Code

<member><name>start</name>
\layout Code

<value><string>1</string></value>
\layout Code

</member>
\layout Code

<member><name>limit</name>
\layout Code

<value><string>5</string></value>
\layout Code

</member>
\layout Code

<member><name>fields</name>
\layout Code

<value><struct>
\layout Code

<member><name>n_given</name>
\layout Code

<value><string>n_given</string></value>
\layout Code

</member>
\layout Code

<member><name>n_family</name>
\layout Code

<value><string>n_family</string></value>
\layout Code

</member>
\layout Code

</struct></value>
\layout Code

</member>
\layout Code

<member><name>query</name>
\layout Code

<value><string></string></value>
\layout Code

</member>
\layout Code

<member><name>filter</name>
\layout Code

<value><string></string></value>
\layout Code

</member>
\layout Code

</struct></value>
\layout Code

</param>
\layout Code

</params>
\layout Code

</methodCall>
\layout Section

Conclusion
\layout Standard

This document outlined the following services and methods:
\layout Subsection

Contacts:
\layout Itemize

service.contacts.read_list([search criteria])
\layout Itemize

service.contacts.read(identifier,[fieldlist])
\layout Itemize

service.contacts.save(fields)
\layout Itemize

service.contacts.delete(identifier)
\layout Subsection

Schedule:
\layout Itemize

service.schedule.read_list([search criteria])
\layout Itemize

service.schedule.read(identifier,[fieldlist])
\layout Itemize

service.schedule.save(fields)
\layout Itemize

service.schedule.delete(identifier)
\layout Subsection

Notes:
\layout Itemize

service.notes.read_list([search criteria])
\layout Itemize

service.notes.read(identifier,[fieldlist])
\layout Itemize

service.notes.save(fields)
\layout Itemize

service.notes.delete(identifier)
\layout Subsection

Todo:
\layout Itemize

service.todo.read_list(search criteria)
\layout Itemize

service.todo.read(identifer,[fieldlist])
\layout Itemize

service.todo.save(fields)
\layout Itemize

service.todo.delete(identifier)
\the_end