OCSManager Specifications¶

Architecture and Design¶

Introduction¶

OpenChange Server is working using a one-way mechanism:

1. A remote client queries the server for data
2. OpenChange server turns the query into mapistore calls
3. mapistore calls the appropriate backend function
4. backend reply is processed along the stack (return values)
5. data is pushed to the client

It means there is no mechanism for OpenChange Server to trigger an action on its own, independently from a client request.

This starts to be a problem when for example we receive a new e-mail in a remote system handled by a backend such as an IMAP server. We have no mechanism to tell the client new data is available. While some MAPI client (like Outlook) will check for changes using a timer, some others assumes they will be notified on changes and wait indefinitely for a notification.

OCSManager and its notification service intends to address this issue.

Addressing the issue¶

In this version of the document, we only try to address the notification issue similar to Exchange 2003 behavior (different from Exchange 2010 asynchronous notification system). In this case, a notification is sent back to the client as part of a MAPI response. This notify call doesn't have any request, it's only a server side action. Along this response's payload, the server may send a UDP notification to the client on the address/port the client specified within EcRRegisterPushNotification (0x4) RPC call of the emsmdb interface.

One of the assumption made is that clients keeping the connection opened (and registered for notifications) will send IDLE request to the server in the very same way Web applications do to keep the connection alive. It means that on a regular basis, clients will send a empty payload to the server.

We will make use of this IDLE request to push pending notifications from OpenChange Server to the client.

Notifying OpenChange server¶

However we still do have to notify OpenChange server and create a notification queue it can process independently from the server process.

This part of the process is handled by ocsmanager:

• This separate process executes Web Services and wait for notifications from remote systems (using XML payloads).
• Upon new notification, OCSManager process the payload and push a notification into a message queue (mqueue) specific to the user, folder and table.
• OpenChange Server checks for pending notifications in the queue (asynchronously) and process them when new data is available
• OpenChange Server creates the notification payload and send it along with current MAPI response.

You may have noticed we talked about message queues specific to the user and the folder and/or the table. The main reason is that a client may register for several notifications at the same time and even open multiple connections onto the remote system (by altering the DCERPC context or opening a new connection). If we had a single queue per user, the "first arrived, first served" rule would apply when it comes to read the queue. Since reading the queue results in flushing it, we wouldn't be able to dispatch notifications on the correct connection properly.

Using queues specific to users, folders and tables ensure each data is pushed on a specific pipe. If a client registered twice for the same notification, the "first arrived, first served" rule doesn't cause any issues.

Getting Started¶

Follow this guide to setup, install and run OCSManager: OCSManager Installation Guide

Configuration File specifications¶

This document describes the ocsmanager.ini configuration file and options that control ocsmanager service behavior: OCSManager Configuration File

Protocol Specifications¶

Error Mapping¶

This document provides a listing of the different errors OCSManager handles

Authentication¶

This document describes the authentication protocol used in ocsmanager:

• network transactions
• request/response payloads
• errors

Notification¶

This document describes the notification protocol used in ocsmanager:

• network transactions
• request/response payloads
• errors

Backend Requirements¶

This document describes the mapistore management API that refers to OCSManager along with the pending patches to apply to existing backends.

Designer Thoughts¶

• TDB doesn't provide a way to search for key easily unless we traverse the entire database. Also if we are using wildcard characters to replace missing parameters (such as password), we'll need to perform complex searches (similarly to startswith, include, endswith etc.). Implementing an indexing layer on top of TDB similarly to what LDB provides may provide better performances.