]po[ XML-RPC Package

The XML-RPC is an example of a Service Oriented Architecture (SOA) which allows external applications to access the underlying data structures of both ]project-open[ and the OpenACS platform on which it operates.

Object Model

A ]po[ object consists of an object_id, an object_type and a number of fields that can be stored in more then one table. In particular, derived object types (such as "im_employee", for example) consist of information that are stored in more then one table.

The SQLAPI provides a consistent layer that hides the fact that information may be stored in different tables. For SQLAPI, an object consists of a set of attributes.

The ]po[ XML-RPC currently defines the "SQLAPI" protocol that implements a generic SQL Bridge in order to reduce the number of procedures. It defines the following set of remote procedure calls (RPCs):

• SQLAPI.Login:
  Authenticate the client and generate a session key.
  
• SQLAPI.Object_Types:
  Returns the list of all object types in the system.
  
• SQLAPI.Select:
  Allows to retreive a set of objects of a specific object_type, based on a number of selection criteria. SQLAPI.SELECT somehow resembles the SQL "select" command.
  However, SELECT only returns a set of object_id's and does not posess the advanced SQL functions such as joins, "order by", "group by" etc.
  
• SQLAPI.Object_Fields:
  Returns a list of all object fields, together with their SQL type.
  
• SQLAPI.Get_Object:
  Returns all fields of a single object as a key-value list. OBJECT_INFO takes into account fields from several tables ("extension tables") as defined in the "DynField" ]po[ SQL metadata system. For example, an "employee" object is described by the tables "acs_objects" (basic object information such as creation date, ...), "person" (first and last name), "parties" (email, URL), "users" (login and authentication information) and "im_employees" (recruiting and payroll information).
  
• SQLAPI.PlPgSQL:
  Execute any PlPg/SQL procedure. These procedures are used to create new objects and to delete objects. Please see the data model reference for available PlPg/SQL routines and their arguments.
  
• SQLAPI.Update:
  Allows to modify an existing objects. UPDATE works similar to "OBJECT_INFO" by updating information in all "extension tables" of an object.

 

Execution Status and Error Treatment

All SQLAPI methods return a list of values with the first element being the error status. The string "ok" indicates a successful execution. Any other value indicates an error situation, with the second element being a human readable error message.

Stateless Protocol Authentication

"SQLAPI" is a "stateless" protocol. That means that each remote procedure call is executed independently from any previous procedure call.

This means that the client has to maintain the session state and needs to send authentication information with every procedure call. This "auth_info" structure consists of a list that is returned by the SQLAPI.Login call. It has the following structure ("[" and "]" indicating the start and end an ordered list):

["token", user_id, timestamp, token]

• The literal "token" as the first element indicates that token-based authentication is used. Other types of autentication may be supported in future versions.
  
• "user_id" indicates the ID of a ]po[ user as defined by the "parties" table in ]po[.
  
• "timestamp" is a SQL timestamp in the format "YYYY-MM-DD HH:MM:SS" (for example: "2006-08-05 14:48:09" to indicate the 5th of August, 2006 at 2:48pm of the server's default timezone). You can use the empty string to indicate an infinite end date.
  
• "token" is a base64 encoded alphanumeric string of 40 characters returned by the server. The token represents a cryptographic SHA1 hash signature of users's password. The exact length of the token may vary in the future and occupy up to 1024 characters.