[Sommaire] [Imprimer]

   1  
   2  
   3  Proposal for a Common Groupware Interface Standard
   4  
   5  (C) 2001-2004 Miles Lott <milos@groupwhere.org>
   6  
   7  September 13, 2001 and December 29, 2003
   8  
   9  Table of Contents
  10  
  11  1 Scope
  12  2 The Services
  13      2.1 Overview
  14      2.2 Detail
  15          2.2.1 Contacts
  16          2.2.2 Schedule
  17          2.2.3 Notes
  18          2.2.4 Todo
  19      2.3 Examples in XML-RPC
  20  3 Conclusion
  21      3.1 Contacts:
  22      3.2 Schedule:
  23      3.3 Notes:
  24      3.4 Todo:
  25  
  26  
  27  
  28  1 Scope
  29  
  30  As many different opensource and freesoftware groupware systems
  31  are being developed, the full realization of the dream of
  32  a connected world should be prefaced by an agreement to
  33  interoperate. There are limited ways in which cooperation
  34  with these and commercial groupware systems may be achecived,
  35  the majority if not all of which were derived via the establishment
  36  of open standards. These might include email (POP3/IMAP),
  37  contacts(LDAP,vcard), or scheduling(ical/vcal). It is felt
  38  that while these have proven themselves to be very useful,
  39  they are insufficient to satisfy the real needs of a typical
  40  business environment.
  41  
  42  This document hopes to provide a reasonable, if limited,
  43  recommendation for a set of standardized methods to be used
  44  for groupware services interaction. More specifically, it
  45  hopes to address the need for such a standard as well as
  46  to spur discussion about the common service names and methods
  47  themselves.
  48  
  49  Examples will be given for implementations in XML-RPC, since
  50  this standard is relatively fixed and open.
  51  
  52  This document does not provide recommendations for the underlying
  53  access control system which would allow or deny a particular
  54  action.
  55  
  56  Also not discussed here is login and authorization to be
  57  used for initial access to a service provider.
  58  
  59  2 The Services
  60  
  61  2.1 Overview
  62  
  63  There are a few common services types that will be needed
  64  for minimum useability of a groupware server or application.
  65  They are:
  66  
  67  * Contacts
  68  
  69  * Schedule
  70  
  71  * Notes
  72  
  73  * Todo
  74  
  75  These services are represented already in places such as
  76  existing groupware client-server applications and also in
  77  the PalmOS basic-4 buttons and applications. Different systems
  78  may have different names for these services internally,
  79  e.g. Contacts - addresses, addressbook, people, Schedule
  80  - calendar, agenda, meetings.
  81  
  82  Within each of these services are some common methods that
  83  would be called to store, retreive, or update data:
  84  
  85  * read_list
  86  
  87  * read
  88  
  89  * save
  90  
  91  * delete
  92  
  93  2.2 Detail
  94  
  95  2.2.1 Contacts
  96  
  97  The concept of contacts may encompass local addressbooks,
  98  LDAP, and lists stored in other media. The purpose of the
  99  contacts service is not to duplicate or attempt to replace
 100  these. In some respects, it might do just that. But its
 101  goal is more so to provide a common and shareable way for
 102  the other core services to create, edit, and read a common
 103  user and address list. All of the other services may use
 104  the contact service to obtain record owner information to
 105  be used in access control. They would also use them when
 106  it is required to share this data, as with a meeting where
 107  other local and non-local users will be invited to attend.
 108  
 109  Contacts may include the local installed user base, users
 110  on other cooperative servers, or email addresses used for
 111  limited cooperation with other groupware services that are
 112  not compliant with this service scheme or implementations
 113  thereof. It could also include individuals using web-based
 114  or local ISP email services. The scope of this document,
 115  however, is to define the service with regard to the common
 116  methods to be used for server-server and client-server communications:
 117  
 118  * read_list
 119  
 120  This method is used to list contacts, with or without limits,
 121  filters, or search criteria. In this way it can be used
 122  for simple lists or to search for contact records and their
 123  identifiers. The optional search criteria includes:
 124  
 125  1. start - Start at this identifier (integer: default 0)
 126  
 127  2. limit - Limit to this number of records returned(integer:
 128    unlimited by default)
 129  
 130  3. fieldlist - limit to showing only these fields (array:
 131    default to identifier, owner identifier, possibly firstname
 132    and lastname)
 133  
 134  4. filter - Show records that are public or private only,
 135    or other system-specific filters, e.g group or company(string:
 136    default '')
 137  
 138  5. query - Search internal fieldlist for a value (string:
 139    default '')
 140  
 141  The return for this method includes:
 142  
 143  1. count of number of records returned(integer)
 144  
 145  2. array consisting of: array: identifier => (array: fieldlist
 146    key => value pairs)
 147  
 148  * read
 149  
 150  Once the identifier for a single contact record is known,
 151  the contact may be read for more detail using this method.
 152  This takes two parameters:
 153  
 154  1. identifier - (integer: no default)
 155  
 156  2. fieldlist - limit to showing only these fields (array:
 157    default to identifier, owner identifier, possibly firstname
 158    and lastname)
 159  
 160  And returns:
 161  
 162  1. array consisting of: array: identifier => (array: fieldlist
 163    key => value pairs)
 164  
 165  * save
 166  
 167  This is a method used to save an existing record or create
 168  a new one. If the identifier for an existing record is not
 169  passed, a new entry will be created.
 170  
 171  * delete
 172  
 173  This will allow deletion of a record by passing its identifier.
 174  
 175  2.2.2 Schedule
 176  
 177  2.2.3 Notes
 178  
 179  2.2.4 Todo
 180  
 181  2.3 Examples in XML-RPC
 182  
 183  Query the contacts service for read_list, using only start
 184  and limit to grab the first 5 records, starting with identifier
 185  1. Additionally, return only the firstname and lastname
 186  fields n_given and n_family (firstname and lastname in pseudo
 187  vcard format):
 188  
 189  <methodCall>
 190  
 191  <methodName>service.contacts.read_list</methodName>
 192  
 193  <params>
 194  
 195  <param>
 196  
 197  <value><struct>
 198  
 199  <member><name>start</name>
 200  
 201  <value><string>1</string></value>
 202  
 203  </member>
 204  
 205  <member><name>limit</name>
 206  
 207  <value><string>5</string></value>
 208  
 209  </member>
 210  
 211  <member><name>fields</name>
 212  
 213  <value><struct>
 214  
 215  <member><name>n_given</name>
 216  
 217  <value><string>n_given</string></value>
 218  
 219  </member>
 220  
 221  <member><name>n_family</name>
 222  
 223  <value><string>n_family</string></value>
 224  
 225  </member>
 226  
 227  </struct></value>
 228  
 229  </member>
 230  
 231  <member><name>query</name>
 232  
 233  <value><string></string></value>
 234  
 235  </member>
 236  
 237  <member><name>filter</name>
 238  
 239  <value><string></string></value>
 240  
 241  </member>
 242  
 243  </struct></value>
 244  
 245  </param>
 246  
 247  </params>
 248  
 249  </methodCall>
 250  
 251  3 Conclusion
 252  
 253  This document outlined the following services and methods:
 254  
 255  3.1 Contacts:
 256  
 257  * service.contacts.read_list([search criteria])
 258  
 259  * service.contacts.read(identifier,[fieldlist])
 260  
 261  * service.contacts.save(fields)
 262  
 263  * service.contacts.delete(identifier)
 264  
 265  3.2 Schedule:
 266  
 267  * service.schedule.read_list([search criteria])
 268  
 269  * service.schedule.read(identifier,[fieldlist])
 270  
 271  * service.schedule.save(fields)
 272  
 273  * service.schedule.delete(identifier)
 274  
 275  3.3 Notes:
 276  
 277  * service.notes.read_list([search criteria])
 278  
 279  * service.notes.read(identifier,[fieldlist])
 280  
 281  * service.notes.save(fields)
 282  
 283  * service.notes.delete(identifier)
 284  
 285  3.4 Todo:
 286  
 287  * service.todo.read_list(search criteria)
 288  
 289  * service.todo.read(identifer,[fieldlist])
 290  
 291  * service.todo.save(fields)
 292  
 293  * service.todo.delete(identifier)