egroupware/phpgwapi/doc/xmlrpc/gw_interface.lyx
2003-12-28 15:58:08 +00:00

404 lines
8.5 KiB
Plaintext

#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