Re: Some questions about the API

I'll CC to developer, might be interesting for some people there as well 
... (we split up the mailing lists to early, I know ...)

Bjoern Stierand wrote:
> Werner Schuster wrote:
> >  - What is this "number" that is referred to in the doc some of the 
> > XMLRPC
> > calls (eg. account.getByNumber); is this supposed to be the ID, or is
> > this
> > something completely different?
>
> Well, yes and no :) If you fetch a record with XML-RPC, most structures
> will return a 'number' and an 'id' attribute. The 'number' was used
> before 'id' was introduced - most of the time 'number' is just the ID
> with some prefix like 'SKY123423' for ID '123423'. You should use 'id'
> for now, 'number' is kinda deprecated.

This is plain wrong. "number" and "id" where both in the initial 
database schema and in effect the "number" is derived from the 
company_id (which is mapped to "id" in XML-RPC).

"number" is the human-readable primary key of an enterprise record while 
"id" is the machine generated internal ID. Since "number"'s are only 
exposed as part of the enterprises, they are filled with the company_id 
to validate the unique constraints on the number column.

"login" is basically the number of "persons". Ergo:
- ignore "login" for enterprise records
- ignore "number" for person records

It would be better if the XML-RPC API wouldn't emit the number for 
persons. You may want to file a bug on this.

> Every document type should have an 'id' attribute - but as projects
> are referred by their 'project code' most of the time, there are no
> 'getById/fetchIds' methods in here. Would make sense to add those,
> though.

Note: this is basically the same issue. "project code" is the human 
readable (and settable) ID while the project_id is the machine 
generated, internal one.

> >   + is this ID unique for each document or just for a document type; 
> > ie. can
> > 2 documents have the same ID if they are eg. an Account and an 
> > Appointment?
>
> It's unique for each document in the system.

Correct: its unique for the whole database. (unique for a document kind 
of makes no sense ;-)

> The 'id' attribute looks like this:
>
>     skyrix://some_string/123423
>
> The prefix 'skyrix://' is fixed, the string 'some_string' comes from 
> your 'skyrix_id' Default setting. The number behind it is the "real"
> id of the document - the long form with the 'skyrix://some_string'
> prefix makes it easier to distinguish between IDs of different
> installations (as the 'some_string' value should be different then).

The skyrix_id is actually required to be different for each OGo 
database. Its used mostly in conjunction with "mailing objects" - in 
case you mail an object to the same installation, you will be able to 
open that one immediatly.

> You can pass the whole string aswell as only the last part (that is:
> the integer number) to the methods - both should work.

I should point out that "just the number" is supposed to work because it 
is seen as a relative ID. Internally the ID will be expanded to a full 
EOGlobalID (and the skyrix:// URLs are just the external representation 
of a global ID).

> >    + is there an easy way to get from an Account to a Person document?
> > the only possibility I can think of would be some query like
> >  'fetchPerson("login like xyz")' (where xyz is the login);
> Yeah, that's the way.

Actually the qualifier should better read "login = 'zyz'".

> >    + does every Account have an associated Person document?
> Yes - in fact an account is stored in the same table ('person') - just
> with the flag 'is_account' turned on.

Note: persons, enterprises and teams are all views on the "company" 
table. Accounts are just special persons, but should be treated separate 
if possible - since in the future we may not always have the case that 
an account maps 1:1 to a person.

> >  - Enterprise: what fields does this document contain? There is no
> > description of it in the documentation;
>
> Hrmm, it's not in the docs? Strange - but you can check what fields
> it contains by just fetching some enterprise with XML-RPC - then the
> fields will show up in the reply. I'll have a look at the docs and
> add the missing description.

I still don't find the XML-RPC reference on

  http://www.opengroupware.org/en/devs/resources/xmlrpc/

Where did you get it?

> >  - FetchSpecification: this name is used throughout the doc as a type for
> > argument; but for Account, Person, etc. it is basically a document with a
> >  "qualifier" and a "sortOrdering" field; BUT for Appointment (in its
> > fetch* functions) it is a document with at least a "startDate" and/or an
> > "endDate" field;
> > I have looked at the WebObjects documentation of some classes, and I 
> > found the EOFetchSpecification class, which looks like the first kind 
> > (qualifier and sortOrdering) fields);

Yes, the fetch specification is pretty much the same like described 
there. Of course you don't map to database tables in the XML-RPC API but 
rather to the DocumentAPI datasource classes.

> The fetchSpecification is used here as a synonym for a variable
> containing arguments for a fetch operation. It can be a simple
> string containing a query (like "login like '*foobar*'") or a
> dictionary, containing the keys:
>
>     qualifier - the qualifier (the string shown above)
>     sortOrderings - result ordering
>     fetchLimit - well, that's obvious, isn't it :)
>     hints - dictionary containing advanced fetch attributes
>             attributes - which attributes are being fetched?
>
> I think there are some more, a look at EOControl+XmlRpcDirectAction.m
> should enlighten you :)
>
> As you found out right, the fetchSpecification for an appointment
> contains some more attributes like 'startDate', 'endDate', 'resources'
> 'companies' and 'timeZone'. This confuses a bit, maybe the API and/or
> the docs need some cleanup in here - the term fetchSpecification
> is misleading here.

I cannot follow here. "startDate", "endDate", "resources" and 
"companies" should be regular parts of the qualifier section of the 
fetchspec and "timeZone" should be a hint.

regards,
  Helge
--
http://www.opengroupware.org/

--
OpenGroupware.org XML-RPC
xmlrpc@xxxxxxxxxxxxxxxxx
http://mail.opengroupware.org/mailman/listinfo/xmlrpc