Calendar Connectors

1. Overview

Totalview 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 interacts with external calendar systems.

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

Currently there are connectors for Exchange 2010 SP1, Exchange 2013, Exchange 2016, Exchange Online, Google calendar and Lotus Notes.

1.1 Abbreviations used in this document

CC – The calendar connector that handles the communication between the Totalview server and the external calendar system.
TV – The Totalview system. If not otherwise stated it identifies the Totalview server.

2. General description of the calendar synchronization

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

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

../../_images/CC-Diagram.png

2.1. XML requests

The TV server notifies the CC about changes in user’s appointments by using create, update and delete XML requests.
The TV server also uses XML requests to notify the CC about the users that are to be synchronized.

2.2. The TV server synchronization rules

Not all users or appointments created in TV 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, OutOfOffice, Working Elsewhere and Tentative are synchronized. State class settings are available in Admin/State

  • The TV is not allowed to update or create recurring appointments

  • When appointments created in TV 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 TV are synchronized with the CC, the CC updates the appointment in the calendar system based on the calendar key

  • When appointments deleted in TV 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 TV, 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 TV, no changes are applied to the promoted appointment.

  • If an appointment is moved in the CC after it is promoted to current in TV, 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.

  • Current states with state class of type Busy, OutOfOffice, Working Elsewhere, Tentative 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 TV server.

2.4. The Calendar connector synchronization rules

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

  • Only users requested by the TV server will be synchronized

  • Only appointments with type of Busy, OutOfOffice, Working Elsewhere and Tentative 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 profile mappings specified in the Admin/Connectors

3. The Calendar connectors life cycle

The Totalview (TV) 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 TV server when a user modifies an appointment in TV. By using this approach it is possible to have the TV and the calendar system synchronized.

3.1 Synchronized data

Appointment data is sent between the CC and the TV 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 TV 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 TV, these changes are buffered in TV and then synchronized when the CC is back running.

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

3.3 Connector execution

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

The TV 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 TV 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 TV.

3.4 Communication model between the CC and TV

  • 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 TV 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 TV server

  • If the username and password are accepted by TV 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 TV server

  • If the connector detects that the calendar system cannot be reached, a calendarconnectionevent stating disconnected is sent to TV 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 TV 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 TV 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 TV

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 EWS API(Exchange Web Services) or Graph API (Exchange online).

The API enables the CC to create, update and delete appointments in the Exchange server.

Using the API 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 TV.

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

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

See section 4.4 Synchronization functionality and 4.5 Synchronization functionality using the API 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.

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 Exchange on premise and Exchange online

If users are moved from on premise to Exchange online the link between the Exchange appointment and Totalview appointment changes. This results in all appointments being re-synchronized with Totalview with a new key. Any Totalview info attached to the old appointment will be lost and the appointment will be mapped to the profile settings in TotalviewAdmin.Connectors.

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

4.3 Installing the service manually

If required the CC service can be installed manually and not using TotalviewAdmin, e.g. if service is running on other machine than the TotalviewServer service.

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

4.4 Synchronization functionality using EWS

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

Technologies used

.NET Framework 4.6

Exchange Web Services

TCP Socket communication

XML, SOAP

../../_images/3.jpg

4.4.1 The EWS protocol

Exchange Web Services (EWS) 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.4.2 Deployment and supported Exchange versions

  • The CC can be used in organizations that use Exchange 2010 SP3 and newer.

  • The CC can be installed on any machine in the network (standalone, on the TV Server machine or on the Exchange machine)

  • The CC runs as a Windows service

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

4.5 Synchronization functionality using the Graph API

The Graph API enables the CC to synchronize with Exchange Online. The Graph API uses REST to talk to Exchange Online and can be setup up for polling or as listening for evens from Exchange online.

4.5.1 Exchange permissions level

The connector extracts appointments information so it operates on the Calendar folder of the mailboxes. The Graph API must be given sufficient rights to access users calendar appointments.

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

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

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 TV server.

Query user rights

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

5.2 Installed files

Installing the service manually

If you want to install the Lotus Notes service manually and not use the Totalview 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

../../_images/4.jpg

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 or newer

  • 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 TV 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 Totalview 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 TV server. Once TV 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, TV can update the appointments list received initially without polling by itself to Lotus Notes/Domino

  • If an error occurs for a specific active subscription, TV is notified with a subscriptionerrorevent XML message indicating the user and the failure reason. Receiving this TV 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 TV server. When the CC starts, it connects to the TV 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 TV server

Reconnectinterval

If the CC is disconnected from the TV server, this setting defines how many seconds to wait until the next reconnection is tried

Reconnectmaxattempts

If the CC is disconnected from the TV 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