zOGI is the ZideStore OpenGroupware Interface.

As of 2007-08-19 (r1994) of OpenGroupware the zOGI protocol bundle is included in the official builds of ZideStore Development continues here, with the zOGI included in ZideStore being the "stable" branch; use this branch, at your own risk, for the latest and greatest.

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

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.
• Screenshots: Calendar, Call List Management, Contacts, Enterprise Data, Search
• Consonance - An Open Source .NET/Gtk# fat client. Currently under development.
• Screenshots: Calendar, Contacts, Tasks, Task Notations, Login
• Calendar - An AJAX component developed on MooTools that provides an interface to the OpenGroupware calendar.
• Screenshot: Screenshot
• OGoX - Currently in the planning stage. OGoX is an web portal to the OpenGroupware server developed using the Ext JS framework. Initial focus is on creating an Ext JS friendly JavaScript wrapper around the zOGI API.
• 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.
• HordOGo - Provides drivers to use OpenGroupware as a backend to the Horde web application suite.
• Code for HordOGo is currently hosed in the zOGI repository under the directory for PHP bindings.
• abas - A JSR-168 calendar portlet which provides a calendar UI for an OpenGroupware.org groupware server.

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