Proposal for a Common Groupware Interface Standard(C) 2001-2004 Miles Lott <milos@groupwhere.org>September 13, 2001 and December 29, 2003Table of Contents1 Scope2 The Services    2.1 Overview    2.2 Detail        2.2.1 Contacts        2.2.2 Schedule        2.2.3 Notes        2.2.4 Todo    2.3 Examples in XML-RPC3 Conclusion    3.1 Contacts:    3.2 Schedule:    3.3 Notes:    3.4 Todo:1 ScopeAs many different opensource and freesoftware groupware systemsare being developed, the full realization of the dream ofa connected world should be prefaced by an agreement tointeroperate. There are limited ways in which cooperationwith these and commercial groupware systems may be achecived,the majority if not all of which were derived via the establishmentof open standards. These might include email (POP3/IMAP),contacts(LDAP,vcard), or scheduling(ical/vcal). It is feltthat while these have proven themselves to be very useful,they are insufficient to satisfy the real needs of a typicalbusiness environment.This document hopes to provide a reasonable, if limited,recommendation for a set of standardized methods to be usedfor groupware services interaction. More specifically, ithopes to address the need for such a standard as well asto spur discussion about the common service names and methodsthemselves.Examples will be given for implementations in XML-RPC, sincethis standard is relatively fixed and open.This document does not provide recommendations for the underlyingaccess control system which would allow or deny a particularaction.Also not discussed here is login and authorization to beused for initial access to a service provider.2 The Services2.1 OverviewThere are a few common services types that will be neededfor minimum useability of a groupware server or application.They are:* Contacts* Schedule* Notes* TodoThese services are represented already in places such asexisting groupware client-server applications and also inthe PalmOS basic-4 buttons and applications. Different systemsmay have different names for these services internally,e.g. Contacts - addresses, addressbook, people, Schedule- calendar, agenda, meetings.Within each of these services are some common methods thatwould be called to store, retreive, or update data:* read_list* read* save* delete2.2 Detail2.2.1 ContactsThe concept of contacts may encompass local addressbooks,LDAP, and lists stored in other media. The purpose of thecontacts service is not to duplicate or attempt to replacethese. In some respects, it might do just that. But itsgoal is more so to provide a common and shareable way forthe other core services to create, edit, and read a commonuser and address list. All of the other services may usethe contact service to obtain record owner information tobe used in access control. They would also use them whenit is required to share this data, as with a meeting whereother local and non-local users will be invited to attend.Contacts may include the local installed user base, userson other cooperative servers, or email addresses used forlimited cooperation with other groupware services that arenot compliant with this service scheme or implementationsthereof. It could also include individuals using web-basedor local ISP email services. The scope of this document,however, is to define the service with regard to the commonmethods to be used for server-server and client-server communications:* read_listThis method is used to list contacts, with or without limits,filters, or search criteria. In this way it can be usedfor simple lists or to search for contact records and theiridentifiers. The optional search criteria includes:1. start - Start at this identifier (integer: default 0)2. limit - Limit to this number of records returned(integer:  unlimited by default)3. fieldlist - limit to showing only these fields (array:  default to identifier, owner identifier, possibly firstname  and lastname)4. filter - Show records that are public or private only,  or other system-specific filters, e.g group or company(string:  default '')5. query - Search internal fieldlist for a value (string:  default '')The return for this method includes:1. count of number of records returned(integer)2. array consisting of: array: identifier => (array: fieldlist  key => value pairs)* readOnce the identifier for a single contact record is known,the contact may be read for more detail using this method.This takes two parameters:1. identifier - (integer: no default)2. fieldlist - limit to showing only these fields (array:  default to identifier, owner identifier, possibly firstname  and lastname)And returns:1. array consisting of: array: identifier => (array: fieldlist  key => value pairs)* saveThis is a method used to save an existing record or createa new one. If the identifier for an existing record is notpassed, a new entry will be created.* deleteThis will allow deletion of a record by passing its identifier.2.2.2 Schedule2.2.3 Notes2.2.4 Todo2.3 Examples in XML-RPCQuery the contacts service for read_list, using only startand limit to grab the first 5 records, starting with identifier1. Additionally, return only the firstname and lastnamefields n_given and n_family (firstname and lastname in pseudovcard format):<methodCall><methodName>service.contacts.read_list</methodName><params><param><value><struct><member><name>start</name><value><string>1</string></value></member><member><name>limit</name><value><string>5</string></value></member><member><name>fields</name><value><struct><member><name>n_given</name><value><string>n_given</string></value></member><member><name>n_family</name><value><string>n_family</string></value></member></struct></value></member><member><name>query</name><value><string></string></value></member><member><name>filter</name><value><string></string></value></member></struct></value></param></params></methodCall>3 ConclusionThis document outlined the following services and methods:3.1 Contacts:* service.contacts.read_list([search criteria])* service.contacts.read(identifier,[fieldlist])* service.contacts.save(fields)* service.contacts.delete(identifier)3.2 Schedule:* service.schedule.read_list([search criteria])* service.schedule.read(identifier,[fieldlist])* service.schedule.save(fields)* service.schedule.delete(identifier)3.3 Notes:* service.notes.read_list([search criteria])* service.notes.read(identifier,[fieldlist])* service.notes.save(fields)* service.notes.delete(identifier)3.4 Todo:* service.todo.read_list(search criteria)* service.todo.read(identifer,[fieldlist])* service.todo.save(fields)* service.todo.delete(identifier)