zogi

XML-RPC Bundle For OpenGroupware's ZideStore Integration Server

zOGI is the ZideStore OpenGroupware Interface.

Two editions of OpenGroupware now support zOGI; the Objective-C ZideStore (via a bundle included since 2007-08-19, r1994) and the OpenGroupware Coils (Python) edition of OpenGroupware. The code hosted here is the development branch of the Objective-C implementation of the protocol. The OpenGroupware Coils implementation of the protocol is hosted within the OpenGroupware Coils project. The production version of the Objective-C implementation is in the ZideStore trunk. Documentation for both versions implementations is here - they work the same!

MISSION: To provide a clean and consistent XML-RPC API to the full suite of functionality provided by the OpenGroupware groupware server. zOGI provides a simple mechanism to build all manner of collaborative applications on the solid and robust platform provided by OpenGroupware extending and integrating groupware functionality to existing applications as well as creating new applications (such as Consonance).

To keep up-to-date with zOGI development it is recommended to follow the Ohloh journal for zOGI. Whenever zOGI is updated a brief entry is made on the journal. Subscribing to this journal requires creating an Ohloh account.

Applications

Several applications either have been built or are under development using the zOGI API to utilize the powerful OpenGroupware groupware and collaboration engine. If you have developed or are developing an application, utility, or component using the zOGI API please let us know and we'll list it here. Feedback on any existing zOGI application or project is also appreciated.

  • MICRMManager - A proprietary closed-source consumer of the zOGI API, however, MICRMManager is a great example of the power of zOGI and how OpenGroupware provides an excellent foundation for CRM applications.
  • Consonance - An Open Source .NET/Gtk# fat client. Currently under development.
  • OGoMojo - Several utilities were created for OpenGroupware administration using the old MOGI project. These are being ported over the the zOGI API. The name for the collection of .NET based OpenGrouware utilities is "OGoMojo".
    • LDAPTeamSync for syncing OpenGroupware teams with groups from a DSA has been ported.
    • LDAPAccountSync for pushing DSA accounts into OpenGroupware is expected to be ported in April or May of 2008.
    • MOGIMon should be ported about the same time as LDAPAccountSync.
  • HordeOGo - Provides drivers to use OpenGroupware as a backend to the Horde web application suite.
  • abas - A JSR-168 calendar portlet which provides a calendar UI for an OpenGroupware.org groupware server.

Links

API

  • getAuditEntries (introduced in r920 2008-03-05)
  • getFavoritesByType
  • unflagFavorites (introduced in r453 2007-06-26)
  • flagFavorites (introduced in r453 2007-06-26)
  • getLoginAccount
  • getNotifications (introduced on 2007-09-16: zOGI r635 / ZideStore r2008)
  • getObjectById
  • getObjectsById
  • getObjectVersionsById (Not supported in PHP wrapper)
  • getTypeOfObject (Not supported in PHP wrapper)
  • putObject
  • deleteObject
  • searchForObjects

Bindings

  • PHP
  • .NET - a .NET binding for the ZOGI protocol is provided by the Whitemice.ZOGI.Backend assembly which is part of the Consonance project. Use of this assembly is documented on the ZOGI page of the Consonance wiki.
  • Python should not require any binding, just use xmlrpclib.
  • Jython

Developer Tips

  • Developing Calendar applications
  • Understanding Entities
  • Example Import & Sync Script
  • Example Notification Script

Support & Community

Questions regarding zOGI, the zOGI API, or zOGI development should be directed to the XML-RPC mailling list hosted by the OpenGroupware project.

Understanding zOGI Entities

Each zOGI API call (with the exception of getTypeOfObject) will return, if successful, either a dictionary or an array of dictionaries. Every dictionary returned represents a groupware object of a specific type identified by the entityName attribute. * entityName - This attribute (a string) identifies the type of object represented by a dictionary. Valid entity name values are (this list may not yet be complete): * acl * Account * address * ApplicationAlert * Appointment * appointmentConflict * assignment * companyValue * Contact * defaults * Enterprise * File * Folder * logEntry * note * notification * objectLink * objectProperty * participant * ParticipantStatus * PluginData * Project * UserAlert * Resource * Task * taskNotation * Team * time * timeZone * Unknown * For the rules relating to processing entities see Understanding Entities.

Detail Levels

Object requests and search requests specify a detail level. This detail level is an integer that is used with a bit mask in order to specify how much information about the object(s) you requested should be marshaled and returned to the client. The detail levels are defined in the zOGIDetailLevels.h include file:

```

define zOGI_INCLUDE_NONE 0

define zOGI_INCLUDE_NOTATIONS 1

define zOGI_INCLUDE_OBJLINKS 2

define zOGI_INCLUDE_PARTICIPANTS 4

define zOGI_INCLUDE_COMPANYVALUES 8

define zOGI_INCLUDE_PROPERTIES 16

define zOGI_INCLUDE_LOGS 32

define zOGI_INCLUDE_CONFLICTS 64

define zOGI_INCLUDE_MEMBERSHIP 128

define zOGI_INCLUDE_CONTACTS 256

define zOGI_INCLUDE_ENTERPRISES 512

define zOGI_INCLUDE_PROJECTS 1024

define zOGI_INCLUDE_COMMENT 2048

define zOGI_INCLUDE_TASKS 4096

define zOGI_INCLUDE_PLUGINS 8192

define zOGI_INCLUDE_CONTENTS 16384

define zOGI_INCLUDE_ACLS 32768

define zOGI_INCLUDE_EVERYTHING 65535

```

If a detail level of zero is specified then only the objects core attributes are returned. Specifying details not appropriate to the object returned is acceptable, that request will simply ignored for the object of the inappropriate types. This allows you to requests object of different types, such as tasks and appointments, in a single call to getObjectsById while still retrieving all the information you need.

For instance if you wanted both the properties and participants of an appointment you would request a detail level of 20 (16 + 4). You can also specify a detail level of 65535 as short hand for retrieving all the available information about the objects. But it is best to only retrieve the information you require in order to avoid placing unnecessary load on the groupware server.

The detail levels of zOGI_INCLUDE_OBJLINKS (2), zOGI_INCLUDE_PROPERTIES (16), and zOGI_INCLUDE_LOGS (32) apply to all object types.

Special Keys

The zOGI dictionary representing an object may have several keys whose start with the underscore character. These are special keys usually added to the dictionary as a result of the specified detail level. The contents of a special key is always a, possibly empty, array. Special keys are:

  • ACCESS - This key contains an array of acl entities.
  • COMPANYVALUES - This key will contain an array of companyValue entity dictionaries. This is only relevant for Contact and Enterprise entities.
  • CONTENTS
  • CONFLICTS - This key is an array of appointmentConflict entities and represents the conflicts that are present with the appointment.
  • DEFAULTS - This key is an array of a single defaults entity, it is only returned by a call to getLoginAccount.
  • FLAGS - This key is an array of strings used to provide hints to the client about the object. The FLAGS key can also be submitted back to the server in the case of putObject and deleteObject in order to influence how the operation is performed. The meaning of the strings in the FLAGS key is specific both to the method being called and the type of entity being manipluted via the method.
  • LOGS - This key will contain an array of logEntry entity dictionaries. This represents the change history of the object. This should only be requested if desired as a long-lived object can have a significant amount of history.
  • MEMBERSHIP
  • NOTES - Contains the notes for an Appointment or Project; in the case of a Task it contains taskNotations.
  • OBJECTLINKS - Contains the objectLinks related to the entity.
  • PARTICIPANTS - This key will contain an array of participant entity dictionaries.
  • PLUGINDATA - This key may contain an array of PluginData entities.
  • PROPERTIES - This key will contain an array of objectProperty entity dictionaries.

Project Information

Labels:
objective-c opengroupware xml-rpc collaberation