source: companies/celepar/phpgwapi/doc/xmlrpc/gw_interface.sgml @ 763

Revision 763, 10.9 KB checked in by niltonneto, 15 years ago (diff)

Importação inicial do Expresso da Celepar
Line 
1<!doctype article public "-//OASIS//DTD DocBook V3.1//EN">
2
3<article lang="en">
4<!-- DocBook file was created by LyX 1.1
5  See http://www.lyx.org/ for more information -->
6  <artheader>
7   <title>
8   Proposal for a Common Groupware Interface Standard
9  </title>
10  <author>
11   (C) 2001-2004 Miles Lott &lt;milos@groupwhere.org&gt;
12  </author>
13  <date>
14   September 13, 2001 and December 29, 2003
15  </date>
16  <para>
17   <toc></toc>
18  </para>
19  </artheader>
20  <sect1>
21   <title>
22   Scope
23  </title>
24  <para>
25   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.
26  </para>
27  <para>
28   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 themselves.
29  </para>
30  <para>
31   Examples will be given for implementations in XML-RPC, since this standard is relatively fixed and open.
32  </para>
33  <para>
34   This document does not provide recommendations for the underlying access control system which would allow or deny a particular action.
35  </para>
36  <para>
37   Also not discussed here is login and authorization to be used for initial access to a service provider.
38  </para>
39  </sect1>
40  <sect1>
41   <title>
42   The Services
43  </title>
44   <sect2>
45    <title>
46    Overview
47   </title>
48   <para>
49    There are a few common services types that will be needed for minimum useability of a groupware server or application. They are:
50   </para>
51   <itemizedlist>
52    <listitem>
53    <para>
54    Contacts
55    </para>
56   </listitem>
57    <listitem>
58    <para>
59    Schedule
60    </para>
61   </listitem>
62    <listitem>
63    <para>
64    Notes
65    </para>
66   </listitem>
67    <listitem>
68    <para>
69    Todo
70    </para>
71   </listitem>
72   </itemizedlist>
73   <para>
74    These services are represented already in places such as existing groupware client-server applications and also in the PalmOS basic-4 buttons and applications. Different systems may have different names for these services internally, e.g. Contacts - addresses, addressbook, people, Schedule - calendar, agenda, meetings.
75   </para>
76   <para>
77    Within each of these services are some common methods that would be called to store, retreive, or update data:
78   </para>
79   <itemizedlist>
80    <listitem>
81    <para>
82    read_list
83    </para>
84   </listitem>
85    <listitem>
86    <para>
87    read
88    </para>
89   </listitem>
90    <listitem>
91    <para>
92    save
93    </para>
94   </listitem>
95    <listitem>
96    <para>
97    delete
98    </para>
99   </listitem>
100   </itemizedlist>
101   </sect2>
102   <sect2>
103    <title>
104    Detail
105   </title>
106    <sect3>
107     <title>
108     Contacts
109    </title>
110    <para>
111     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.
112    </para>
113    <para>
114     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 communications:
115    </para>
116    <itemizedlist>
117     <listitem>
118     <para>
119     read_list
120     </para>
121    </listitem>
122    </itemizedlist>
123    <para>
124     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:
125    </para>
126    <orderedlist>
127     <listitem>
128     <para>
129     start - Start at this identifier (integer: default 0)
130     </para>
131    </listitem>
132     <listitem>
133     <para>
134     limit - Limit to this number of records returned(integer: unlimited by default)
135     </para>
136    </listitem>
137     <listitem>
138     <para>
139     fieldlist - limit to showing only these fields (array: default to identifier, owner identifier, possibly firstname and lastname)
140     </para>
141    </listitem>
142     <listitem>
143     <para>
144     filter - Show records that are public or private only, or other system-specific filters, e.g group or company(string: default '')
145     </para>
146    </listitem>
147     <listitem>
148     <para>
149     query - Search internal fieldlist for a value (string: default '')
150     </para>
151    </listitem>
152    </orderedlist>
153    <para>
154     The return for this method includes:
155    </para>
156    <orderedlist>
157     <listitem>
158     <para>
159     count of number of records returned(integer)
160     </para>
161    </listitem>
162     <listitem>
163     <para>
164     array consisting of: array: identifier =&gt; (array: fieldlist key =&gt; value pairs)
165     </para>
166    </listitem>
167    </orderedlist>
168    <itemizedlist>
169     <listitem>
170     <para>
171     read
172     </para>
173    </listitem>
174    </itemizedlist>
175    <para>
176     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:
177    </para>
178    <orderedlist>
179     <listitem>
180     <para>
181     identifier - (integer: no default)
182     </para>
183    </listitem>
184     <listitem>
185     <para>
186     fieldlist - limit to showing only these fields (array: default to identifier, owner identifier, possibly firstname and lastname)
187     </para>
188    </listitem>
189    </orderedlist>
190    <para>
191     And returns:
192    </para>
193    <orderedlist>
194     <listitem>
195     <para>
196     array consisting of: array: identifier =&gt; (array: fieldlist key =&gt; value pairs)
197     </para>
198    </listitem>
199    </orderedlist>
200    <itemizedlist>
201     <listitem>
202     <para>
203     save
204     </para>
205    </listitem>
206    </itemizedlist>
207    <para>
208     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.
209    </para>
210    <itemizedlist>
211     <listitem>
212     <para>
213     delete
214     </para>
215    </listitem>
216    </itemizedlist>
217    <para>
218     This will allow deletion of a record by passing its identifier.
219    </para>
220    </sect3>
221    <sect3>
222     <title>
223     Schedule
224    </title>
225    </sect3>
226    <sect3>
227     <title>
228     Notes
229    </title>
230    </sect3>
231    <sect3>
232     <title>
233     Todo
234    </title>
235    </sect3>
236   </sect2>
237   <sect2>
238    <title>
239    Examples in XML-RPC
240   </title>
241   <para>
242    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):
243   </para>
244   <programlisting>
245<![ CDATA [<methodCall>
246]]><![ CDATA [<methodName>service.contacts.read_list</methodName>
247]]><![ CDATA [<params>
248]]><![ CDATA [<param>
249]]><![ CDATA [<value><struct>
250]]><![ CDATA [<member><name>start</name>
251]]><![ CDATA [<value><string>1</string></value>
252]]><![ CDATA [</member>
253]]><![ CDATA [<member><name>limit</name>
254]]><![ CDATA [<value><string>5</string></value>
255]]><![ CDATA [</member>
256]]><![ CDATA [<member><name>fields</name>
257]]><![ CDATA [<value><struct>
258]]><![ CDATA [<member><name>n_given</name>
259]]><![ CDATA [<value><string>n_given</string></value>
260]]><![ CDATA [</member>
261]]><![ CDATA [<member><name>n_family</name>
262]]><![ CDATA [<value><string>n_family</string></value>
263]]><![ CDATA [</member>
264]]><![ CDATA [</struct></value>
265]]><![ CDATA [</member>
266]]><![ CDATA [<member><name>query</name>
267]]><![ CDATA [<value><string></string></value>
268]]><![ CDATA [</member>
269]]><![ CDATA [<member><name>filter</name>
270]]><![ CDATA [<value><string></string></value>
271]]><![ CDATA [</member>
272]]><![ CDATA [</struct></value>
273]]><![ CDATA [</param>
274]]><![ CDATA [</params>
275]]><![ CDATA [</methodCall>
276]]>   </programlisting>
277   </sect2>
278  </sect1>
279  <sect1>
280   <title>
281   Conclusion
282  </title>
283  <para>
284   This document outlined the following services and methods:
285  </para>
286   <sect2>
287    <title>
288    Contacts:
289   </title>
290   <itemizedlist>
291    <listitem>
292    <para>
293    service.contacts.read_list(&lsqb;search criteria&rsqb;)
294    </para>
295   </listitem>
296    <listitem>
297    <para>
298    service.contacts.read(identifier,&lsqb;fieldlist&rsqb;)
299    </para>
300   </listitem>
301    <listitem>
302    <para>
303    service.contacts.save(fields)
304    </para>
305   </listitem>
306    <listitem>
307    <para>
308    service.contacts.delete(identifier)
309    </para>
310   </listitem>
311   </itemizedlist>
312   </sect2>
313   <sect2>
314    <title>
315    Schedule:
316   </title>
317   <itemizedlist>
318    <listitem>
319    <para>
320    service.schedule.read_list(&lsqb;search criteria&rsqb;)
321    </para>
322   </listitem>
323    <listitem>
324    <para>
325    service.schedule.read(identifier,&lsqb;fieldlist&rsqb;)
326    </para>
327   </listitem>
328    <listitem>
329    <para>
330    service.schedule.save(fields)
331    </para>
332   </listitem>
333    <listitem>
334    <para>
335    service.schedule.delete(identifier)
336    </para>
337   </listitem>
338   </itemizedlist>
339   </sect2>
340   <sect2>
341    <title>
342    Notes:
343   </title>
344   <itemizedlist>
345    <listitem>
346    <para>
347    service.notes.read_list(&lsqb;search criteria&rsqb;)
348    </para>
349   </listitem>
350    <listitem>
351    <para>
352    service.notes.read(identifier,&lsqb;fieldlist&rsqb;)
353    </para>
354   </listitem>
355    <listitem>
356    <para>
357    service.notes.save(fields)
358    </para>
359   </listitem>
360    <listitem>
361    <para>
362    service.notes.delete(identifier)
363    </para>
364   </listitem>
365   </itemizedlist>
366   </sect2>
367   <sect2>
368    <title>
369    Todo:
370   </title>
371   <itemizedlist>
372    <listitem>
373    <para>
374    service.todo.read_list(search criteria)
375    </para>
376   </listitem>
377    <listitem>
378    <para>
379    service.todo.read(identifer,&lsqb;fieldlist&rsqb;)
380    </para>
381   </listitem>
382    <listitem>
383    <para>
384    service.todo.save(fields)
385    </para>
386   </listitem>
387    <listitem>
388    <para>
389    service.todo.delete(identifier)
390    </para>
391   </listitem>
392   </itemizedlist>
393   </sect2>
394  </sect1>
395
396
397</article>
Note: See TracBrowser for help on using the repository browser.