Calendar Connectors

1. Overview

Totalview 3 can be extended by implementing connectors that handle the specific communications with external systems.

This document gives you an in depth description of the calendar connectors and how Totalview 3 interacts with external calendar systems.

The calendar connector handles the synchronization of appointments between Totalview 3 and the external calendar system. The connector monitors users in the external system and notifies the Totalview 3 server when changes in the user’s appointments occur. The connector also creates, updates and deletes appointments upon requests from the Totalview 3 server.

Currently there are connectors for Exchange 2003, Exchange 2007, Exchange 2010, Exchange Online and Lotus Notes.

 

1.1 Abbreviations used in this document

CC – The calendar connector that handles the communication between the Totalview 3 server and the external calendar system.

TV3 – The Totalview 3 system. If not otherwise stated it identifies the Totalview 3 server.

 

2. General description of the calendar synchronization

The interface between the Totalview 3 server and Calendar connector is generalized and is independent of the actual calendar system.

It is the responsibility of the TV3 server and the CC to send real-time notifications, based on certain rules, when changes are made in user’s appointments.

Appointments created in the calendar system will not be created in TV3 but only shown runtime. This means that calendar appointments are only visible in TV3 while the CC is connected. Appointments created or updated in TV3 will be visible in TV3 even if CC is not connected.

Appointments created in the calendar system will not be created in TV3 but only shown runtime. This means that calendar appointments are only visible in TV3 while the CC is connected.
Appointments created or updated in TV3 will be visible in TV3 even if CC is not connected.

 

2.1. XML requests

The TV3 server notifies the CC about changes in user’s appointments by using create, update and delete XML requests.

The TV3 server also uses XML requests to notify the CC about the users that are to be synchronized.

 

2.2. The TV3 server synchronization rules

Not all users or appointments created in TV3 are synchronized with the CC. The following rules state what users and appointments are synchronized with the CC.

  • Only active users with a valid Calendar ID and with Synchronize Calendar enabled are synchronized. These settings are available in Admin/User
  • Only appointments with state class of type Busy or OutOfOffice are synchronized. State class settings are available in Admin/State
  • The TV3 is not allowed to update or create recurring appointments
  • When appointments created in TV3 are synchronized with the CC, the CC returns a calendar key that is used in subsequent requests on the same appointment
  • When appointments updated in TV3 are synchronized with the CC, the CC updates the appointment in the calendar system based on the calendar key
  • When appointments deleted in Totalview are synchronized with the CC, the CC deletes the appointment in the calendar system based on the calendar key
  • If an appointment changes in the CC after it is promoted to current in TV3, then the current state will reflect the change. Exception to this is if the appointment is moved (see below).
  • If an appointment is deleted in the CC after it is promoted to current in TV3, no changes are applied to the promoted appointment.
  • If an appointment is moved in the CC after it is promoted to current in TV3, then the appointment will be treated as a new appointment. No change will be made on the current state.

 

Below are the extra rules applied if Synchronize current is enabled. N.B. This feature is both available for the Exchange connector and the Lotus Notes Connector.

  • Current states with state class of type Busy or OutOfOffice and where End type is set to Actual or Expected are synchronized.
  • If a new current state is set prior to Actual or Expected end of the synchronized state, no additional synchronization occurs. I.e. if current state is synchronized from 13.00 to 14.00 and the user changes to another state at 13.30, the Exchange appointment will still show 13.00 to 14.00.
  • If the current state goes beyond the Expected end, no additional synchronization occurs. I.e. if current state is synchronized from 13.00 to 14.00 and no new state occurs at 14.00 then the Exchange appointment will still show 13.00 to 14.00.

 

See section 4. Exchange synchronization for a description of the CC and Exchange communication.

See section 5. Lotus Notes synchronization for a description of the CC and the Lotus Notes communication.

 

2.3. XML notifications

The CC monitors the calendar system and when an appointment change occurs (create, update, delete) an XML notification is sent to the TV3 server.

 

2.4. The Calendar connector synchronization rules

Not all users and appointments created in the calendar system are synchronized with the TV3. The following rules state what users and appointments are synchronized with the TV3.

  • Only users requested by the TV3 server will be synchronized
  • Only appointments with type of Busy or OutOfOffice are synchronized
  • Appointments with subject starting with * are not synchronized (* is the default setting but can be changed in the calendar connector setup)
  • Private appointments are synchronized with the subject set to the text “private”
  • Recurring appointments are synchronized for a defined number of days ahead. This is necessary to reduce the number of appointments returned from the calendar connector. The number of days is specified in the Admin/Connectors
  • When synchronizing an appointment that is not created or modified in Totalview, i.e. is created in the calendar system, the appointments start and end state is based on the Busy profile shortname and the OOF profile shortname specified in the Admin/Connectors

 

 

3. The Calendar connectors life cycle

The Totalview3 (TV3) server receives real-time notifications from the calendar connector (CC) when a user modifies an appointment in the calendar system. Also the CC receives real-time notifications from the TV3 server when a user modifies an appointment in TV3. By using this approach it is possible to have the TV3 and the calendar system synchronized.

 

3.1 Synchronized data

Appointment data is sent between the CC and the TV3 as XML structures containing the following information:

Key Unique key identifying the appointment in the calendar system
Subject The subject part of the appointment
Location The location of the meeting
StartDate, EndDate Time span of the appointment
Appstatus BUSY, OOF (Out Of Office), FREE or TENTATIVE.
Apptype Recurring or normal appointment
Appscope Public or private appointment

 

3.2 Connector start up

The CC runs as a service and at start up, the connector connects to the TV3 server to verify the license and to receive information about the external calendar system and a list of users to synchronize.

The CC then connects to the calendar system and starts synchronizing the users.

Buffered changes

If no CC is running and appointments are changed in TV3, these changes are buffered in TV3 and then synchronized when the CC is back running.

In case of no CC running, the rule is that it is always the TV3 data that is the correct data. This means that in case of no CC running, and that the same appointment is changed in both TV3 and the calendar system, then it will be the TV3 changes that are used when the connector is back.

3.3 Connector execution

When executing the CC listens for commands from the TV3 server to be executed on the calendar system and monitors users in the calendar system for changes.

The TV3 server sends create, update and delete appointment requests to the CC which in turn executes the command on the calendar system.

The CC also monitors the users in the calendar system. This monitoring is done by polling for changes at certain intervals. If there are any changes in user’s appointments, the TV3 server is notified.

Because the monitoring is done by polling, there might be a delay before an appointment change in the calendar system is visible in TV3.

3.4 Communication model between the CC and TV3

  • When the connector service starts, using the IP address and port from its settings, it opens a socket communication channel sending an authentication request to the TV3 server
  • If the communication channel cannot be opened, the operation is repeated according to a maximum number of retries which is a setting of the connector
  • The same retry mechanism will be issued if for any reasons if the connector looses connection with TV3 server
  • If the username and password are accepted by TV3 then an accept message is sent back to the connector, otherwise a deny response is issued and the communication channel is closed
  • The accept message contains settings configuring the connector such as the address and credentials of the calendar system that will be queried for appointments
  • After it received accept, the connector tries to connect to calendar system. If the connection succeeds a calendarconnectionevent stating connected is sent to TV server. Otherwise it will retry to connect to Exchange a specified number of times. For each failure, a calendarconnectionevent stating connecting is sent or, if the specified possible times are reached, the connector is stopped and calendarconnectionevent stating disconnected is sent to TV3 server
  • If the connector detects that the calendar system cannot be reached, a calendarconnectionevent stating disconnected is sent to TV3 server indicating that any further request should not be sent because it will be impossible to serve. The connector will infinitely retry to establish the connection with the calendar system and when this succeeds the TV server will receive a calendarconnectionevent stating connected meaning that requests can be served again

3.5 Supported calendar system operations

  • Searching appointments
  • Add/Modify/Remove appointments
  • Subscribe for appointment changes

3.6 How subscribing for user appointments works

When the TV3 makes a subscription for a specific users appointments, it expects the current list of appointments in that user’s calendar folder and as long as the subscription is not removed, the TV3 expects to receive notification events if appointments are created, updated or deleted for the monitored user.

To be efficient to limit the amount of data the date interval in which CC looks for appointments is described by the following rule:

  • Non-recurring appointments are queried from yesterday and to infinity
  • Recurring appointments are queried from yesterday and a configurable number of days ahead. This is to limit the amount of recurring appointments returned from the CC to the TV3

When the day changes (midnight), appointments older than yesterday are reported as deleted.

When crossing midnight the date window for recurring appointments changes and a new search for recurring appointments are executed for the new day.

4. Exchange synchronization

The CC communicates with Exchange by using the WebDAV protocol or the EWS (Exchange Web Services).

The WebDAV/EWS enables the CC to create, update and delete appointments in the Exchange server.

Using WebDAV the CC can query the Exchange server for changes in user’s appointments. This query is done at certain intervals and therefore there might be a delay before an appointments change is reflected in TV3.

Using EWS, the Exchange server notifies the CC and thus there is no need for querying for changes.

The CC sends the WebDAV/EWS request using a query user with extended Exchange user rights. See the Totalview 3 Exchange security settings.pdf for information on how to create the query user.

See section 4.4 Synchronization functionality  and 4.5 Synchronization functionality using EWS for a more detailed explanation of the synchronization.

4.1 Specific Exchange issues

This section lists issues that are specific to the Exchange server synchronization.

IIS and Exchange log file size using WebDAV

When using WebDAV, the CC is using polling to monitor Exchange users and for this reason log files on the IIS or Exchange server might grow large.

Each polling on each user creates data in the log file and the polling runs 24/7.

When using EWS, the Exchange server notifies the CC about changes and thus there is not need for polling.

Multible calendar folders

If the user has multiple calendars, the calendar to use can be specified by adding two || (pipes) after the calendar ID. E.g. if using calendar2, the Calendar ID can be specified as user@domain||\calendar\calendar2.

If no calendar is specified, then the first calendar is used.


Using service credentials

The credentials from the connector login accept message must be empty if the connector is configured to use the windows service credentials to connect to authenticate to Exchange.

4.2 Switching between WebDAV and EWS

If the CC is changed from WebDAV to EWS or vice versa, then synchronized appointments with additional information saved in TV3 will lose this information in TV3. The appointments are preserved in the CC.

After the switch, new appointments with additional information saved in TV3 will execute as usual.

Additional information is saved on appointments if TV3 creates or alters the synchronized appointment. The additional information is information like phone setting and state settings.

An example is Vacation appointments created in TV3 and synchronized with the CC. The Vacation appointments are shown with its own state and colour in TV3, but if changing the CC type, the Vacation appointments will be shown as a regular CC appointment.

The reason for the loss of additional information is that the calendar key is not the same using WebDAV and EWS, and thus the link between the CC appointment and the TV3 appointment is lost. To regain the link between the CC appointment and the TV3 appointment, the TV3 appointments are removed and then resynchronized from the CC.

We recommend that the EWS (Exchange Web Services) connector is used when synchronizing appointment. WebDAV is not supported on Exchange 2010 and will be outfaced.

4.3 Installed files

The following files are installed with the Exchange WebDAV calendar connector:

Totalview3Connector.dll
Totalview3Exchange.dll
Totalview3ExchangeSrv.exe
validation.xsd and
config.xml

The following files are installed with the Exchange EWS calendar connector:

Formula.Baseconnector.dll
Formula.ExchangeEWSAPIConnector.dll
Microsoft.Exchange.Webservices.dll
Totalview3ExchangeEWS.exe
messageSchema.xsd and
EWSAPIMessages.xsd

Installing the service manually

If you want to install the Exchange service manually and not use the Totalview 3 Admin to install the service, you must install the Totalview3ExchangeSrv.exe if using WebDAV or TotalView3ExchangeEWS.exe if using EWS.

See also the Totalview 3 Admin guide.pdf on how to install services manually.

4.4 Synchronization functionality using WebDAV

The CC takes care of the two way communication between TV3 and the Exchange server. It synchronizes appointment from the Exchange calendar offering up to date status information.

Technologies used

.NET Framework 2.0

HTTP(S)/WebDAV

TCP Socket communication

XML

2

4.4.1 The WebDAV protocol

The acronym stands for the World Wide Web Distributed Authoring and Versioning and it’s a set of extensions of the well known HTTP protocol. The Exchange server having WebDAV enabled exposes mailboxes content and metadata information structured using XML properties. DASL (DAV searching and locating protocol) allows searching mailbox data based on property values. Microsoft bases its Outlook Web Access web application (allowing users to access their mailbox using a web browser and offering a similar usage experience as Outlook) on this protocol, querying all the mailbox data over HTTP. The connector queries data like Outlook Web Access does in version Exchange 2003, only that it targets just the Calendar part of the mailboxes. Outlook Web Access does not use WebDAV in Exchange 2007 server, but WebDAV is supported.

 

4.4.2 Deployment and supported Exchange versions

  • The CC can be used in organizations that use Exchange 2003, 2007, Exchange 2010, 2013 and Office 365 Exchange Online. EWS is not supported by Exchange 2003 and WebDAV is not supported on Exchange 2010.
  • The CC can be installed on any machine in the network (standalone, on the TV3 Server machine, on the Exchange machine)
  • The CC runs as a Windows service

4.4.3 Exchange permissions level

The CC extracts appointments information so it operates just on the Calendar folder of the mailboxes.

The query user credentials used to connect to the Exchange server (domain, username, and password) are obtained either from the Totalview server or automatically taken from the windows service in which the connector runs.

See the Totalview 3 Exchange security settings.pdf for information on how to create the query user.

4.5 Synchronization functionality using EWS

The CC takes care of the two way communication between TV3 and the Exchange server. It synchronizes appointment from the Exchange calendar offering up to date status information. Deploy

Technologies used

.NET Framework 3.5

Exchange Web Services

TCP Socket communication

XML, SOAP

3

4.5.1 The EWS protocol

Exchange Web Services (EWS) is the new way Microsoft provides the functionality of enabling client applications to communicate with Exchange server. Microsoft bases its Outlook Web Access web application (allowing users to mailbox access via web browser and offering a similar usage experience as Outlook) on EWS. EWS was introduced starting with Exchange 2007 and extended in Exchange 2010 to replace the WebDAV protocol which was offering similar functionality but was phased out. SOAP provides the messaging framework for messages sent between the client application and the Exchange Server. The SOAP messages are sent by HTTP(S).

4.5.2 Deployment and supported Exchange versions

  • The CC can be used in organizations that use Exchange 2007, 2010. EWS is not supported by Exchange 2003.
  • The CC can be installed on any machine in the network (standalone, on the TV3 Server machine, on the Exchange machine)
  • The CC runs as a Windows service

4.5.3 Exchange permissions level

The connector extracts appointments information so it operates on the Calendar folder of the mailboxes. When the connector starts, it must be provided with the credentials of a user having impersonation rights. Impersonation rights allows an user or the application using this account (in our case, the connector) to impersonate a given user account (the user having the mailbox on which the connector operates on)

See the Totalview 3 Exchange security settings.pdf for information on how to create the query user.

5. Lotus Notes synchronization

The Lotus Notes synchronization enables the TV3 server to create, update and delete appointments in Lotus Notes user’s calendar folders. The Lotus Notes synchronization also monitors Lotus Notes users calendar folders and notifies the TV3 server when changes occur.

Synchronization using Lotus Notes client API

The CC and Lotus Notes communicate by using the Lotus Notes client API.

The client API enables the CC to create, update and delete appointments in the Lotus Notes server.

The client API also enables the CC to query the Lotus Notes server for changes in user’s appointments. This query is done at certain intervals and therefore there might be a delay before an appointments change is reflected in TV3.

The CC sends the request using a query user with extended user rights to other users’ folders. The query user obtains these user rights by getting them granted by other users.

5.1 Specific Lotus Notes issues

When handling recurring appointments, Lotus Notes only creates one appointment and lets the rules for the recurring appointments be stored in this one appointment.

Currently the CC only looks for appointments created within the last 12 months. That means that if a recurring appointment is created more than 12 months ago, it will not be synchronized with TV3.

Using service credentials

It is not possible to use service credentials when using the Lotus Notes connector.

Username and password must be passed from the TV3 server.

 

Query user rights

Lotus Notes calendar users must grant the query user access to their calendar folder.

5.2 Installed files

The following files are installed with the Lotus Notes CC:

Totalview3Connector.dll
Totalview3LotusNotes.dll
Totalview3LotusNotesSrv.exe
validation.xsd
config.xml
Interop.Domino.dll

Installing the service manually

If you want to install the Lotus Notes service manually and not use the Totalview 3 Admin to install the service, you must install the Totalview3LotusNotesSrv.exe.

See also the Totalview 3 Admin guide.pdf on how to install the service manually.

5.3 Synchronization functionality description

The CC takes care of the two way communication between Totalview and the Lotus Notes Domino server. The CC synchronizes appointments from the LotusNotes calendar offering up to date status information.

Technologies used

.NET Framework 2.0

LotusNotes Object API, part of the LotusNotes mail client

TCP Socket communication

XML

4

5.3.1 Lotus Notes Object API

The Lotus Notes client object API is the way in which IBM allows data access and manipulation in the Domino mailboxes database without bringing up the Lotus Notes client interface. The object API is built using COM (Component Object Model) technology. This powerful feature opens up the Lotus Notes system to third party development. IBM does not offer the Object API as a separate SDK and it’s only shipped as part of the Lotus Notes client.

5.3.2 Deployment and supported Lotus Notes versions

  • The CC can be used in organizations that use IBM Domino 6
  • Since client object API is vital for the CC to be able to run, the Lotus Notes client must be installed on the same machine as the CC. The CC can use any of the versions 6, 7 or 8 of the Lotus Notes client
  • The CC can be installed on any machine in the network (standalone, on the TV3 machine, on the Domino machine) as long as the Lotus Notes client is also installed

5.3.3 Lotus Notes permissions level

At start-up the CC must be provided with the credentials of a user having access rights to other users calendar folders in which queries will be made.

5.3.4 How subscribing for user appointments works

Note that Lotus Notes doesn’t support subscription to a specific folder in a user’s mailbox. Because native Lotus Notes subscription mechanism is not available, the CC detects created/changed/deleted appointments by making subsequent searches at an interval and comparing the current list of appointments with a previously known one. Below you can see the subscription operations from the Lotus Notes CC perspective:

  • The CC receives a subscription request from Total View server for a user in the form of an addsubscription XML message
  • The CC makes a search query and gets that user appointments from a specified date interval
  • The user is added in the active subscriptions list
  • If the above two operations are successful then an addsubscriptionresult XML message containing the list of appointments and having status true is sent back to TV3 server. Once TV3 receives this message it can rest assured that any changes in the users appointments will be notified with a dedicated event
  • For each user in the subscriptions list, at 30 seconds interval the CC searches all the appointments that have the modified date greater than the last request time. Using the saved results of the previous search and the current results the CC finds out if changes appeared (meaning appointments were created, updated or deleted)
  • Once the CC identifies what type of change occurred, it sends an appointmentevent message containing the fields of the appointment and the type of change (create, update, delete). Having these events, TV3 can update the appointments list received initially without polling by itself to Lotus Notes/Domino
  • If an error occurs for a specific active subscription, TV3 is notified with a subscriptionerrorevent XML message indicating the user and the failure reason. Receiving this TV3 can clear the user’s appointments list and re-initiate the subscription

6. The config.xml file

The config.xml file, located in the same directory as the calendar connector files contains the start-up parameters for the service.

The config file is maintained by the Admin and should not be updated manually.

The config file contains the following parameters:

<startparameters>
<tvserverip>127.0.0.1</tvserverip>
<tvserverport>3333</tvserverport>
<connectorname>Exchange</connectorname>
<timeout>30</timeout>
<reconnectinterval>30</reconnectinterval>
<reconnectmaxattempts>-1</reconnectmaxattempts>
<logginglevel>2</logginglevel>
</startparameters>

 

Tvserverip and tvserverport The address and port of the TV3 server. When the CC starts, it connects to the TV3 server using these settings
Connectorname The name of connector defined in Totalview Admin. The connector must be created in Admin before the connector is allowed to connect to the Totalview server. When connected, parameters defined in Admin for the connector is sent to the Exchange CC
Timeout Timeout setting used when the CC tries to connect to the TV3 server
Reconnectinterval If the CC is disconnected from the TV3 server, this setting defines how many seconds to wait until the next reconnection is tried
Reconnectmaxattempts If the CC is disconnected from the TV3 server, this settings defines how often reconnection should be tried before abandoned. If setting is -1, the reconnection continues forever
Logginglevel 0 = disabled

1 = error and start/stop events

2 = 1 + in and out message dates

3 = 2 + full in and out message bodies

Last edited on June 8th, 2018