Re: Some questions about the API

Hi Werner, hi list,

I'll try to answer some questions - if something is wrong, please
correct me! :)

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.

>  - ID:
>   +does every document type have an ID? it seems like about all
> parts of the XML-RPC have an *.fetchIds or *.getByID call, except for
> project.*; 
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.

>   + 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.

>   + what is the ID or what is it supposed to contain? Some XMLRPC sample
> calls simply pass a number as argument, whereas others pass an URI that
> contains the ID number;
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).

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

>  - Account:
>    + does an Account have a "name" field? the example calls suggest that,
> but it does not seem correct, or at least the description of the Account
> document does not show it;
IIrc you can pass a 'name' argument when creating an account, but it
won't show up when you fetch the same account again - that should be
considered as a bug.

>    + 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.

>    + 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.

>  - 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.

>  - 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);
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.

Greets

Bjoern

--
http://www.opengroupware.org

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