Google Calendar Import Documentation

Version 0.98

The Calendar Import Utility is a Windows application that allows calendar events to be migrated from an Exchange Server to Google Apps.

This document defines how to properly run and configure the Calendar Import Windows application.


Platform Requirements

  • Windows Based PC (XP, Vista, Server) with .NET 3.5 Installed (Available through Windows Update or directly from MS)
  • Google Apps Premier or Education Edition
  • Microsoft Exchange 2000, 2003, 2007


  • System Requirements (for .net 3.5)
    • Supported Operating Systems: Windows Server 2003; Windows Server 2008; Windows Vista; Windows XP
    • Processor: 400 MHz Pentium processor or equivalent (Minimum); 1GHz Pentium processor or equivalent (Recommended)
    • RAM: 96 MB (Minimum); 256 MB (Recommended)
    • Hard Disk: Up to 500 MB of available space may be required
    • CD or DVD Drive: Not required
    • Display: 800 x 600, 256 colors (Minimum); 1024 x 768 high color, 32-bit (Recommended)

Tested On

  • Windows XP Pro with .NET 3.5 Installed
  • Google Apps Premier
  • Microsoft Exchange 2003

Installation

The Calendar Import utility is delivered a Windows MSI Installer which includes product documentation. The provided installer package will add Start Menu items, and an entries under Add/Remove Programs.


Licensing

The Google Calendar Import Utility requires a license to be installed to be fully functional. Without a license file, the application will be in "Trial Mode", allowing you to perform actions on only one user at a time. To obtain a license, please contact LTech for pricing.

License installation instructions will be included with your license.


Google Apps Configuration

Google Apps must be configured to use Two-Legged OAuth. This will allow Google Apps services to use OAuth to retrieve user specific data without requesting the user's permission. The domain must also have an admin user for the utility. An existing admin user account is all that is necessary but it may be beneficial to create a separate user admin account.

OAuth configuration for Google Apps domains is available on the administrator dashboard under the section titled Advanced Tools. The OAuth consumer key and secret is available under this menu as well.

**The Provisioning API for Google Apps must also be enabled to operate the utility. This option is enabled under the 'Users and groups' section.**


Windows Application Configuration

Configuration options are entered manually, but a configuration option is available as well that allows configuration options to be saved for future usage.

Configuration

Configuration is broken down into five separate sections on the main form.

Google Apps Credentials

  • Domain - This is the source Google Apps domain to use for the export.
  • Login - This is the admin user that will be used to query Google Apps for user information.
  • Password - The admin user's password.
  • OAuth Key - OAuth Consumer Key.
  • OAuth Secret - OAuth Consumer Secret.

Exchange Credentials

  • Exchange Server - This is the Exchange server where calendar information will be imported from.
  • Exchange Admin User- This is the Exchange admin user that will be used to query for calendar events.
  • Exchange Admin Password - The Exchange admin user's password.
  • Source Domain - The Exchange domain.
  • Time Zone - This dropdown represents the time zone that the Exchange Server is running under. By default the current time zone of the computer running the utility is selected.
  • Enable Forms Authentication - Check this option if the exchange server has forms based authentication enabled on it.

Note: Some time zones are current unsupported but often have a suitable alternative time zone with the same UTC

Select Users

  • Select All - Click select all to select all domain users.
  • Clear Selection - Clears the selected users from the check box list.
  • Upload File - Upload a comma separated or line separated file containing the users that you would like backed up.

Optional

  • Output Path - This is the directory that user reports will be exported to. In the case of the Calendar Import Utility the folder specified will contain reports for each user. This field is not required and will default to 'C:\export' which will be created if it does not exist.
  • Sleep After - By default the Calendar Import Utility will sleep between a specified amount of requests. The default value is 100 requests, but can be changed by specifying a different numerical value here.
  • Sleep For - By default the Calendar Import Utility will sleep between a specified amount of requests. The default value for this parameter is 10 seconds, but can be changed by specifying a different numerical value here. If the value 0 is supplied it will effectively disable sleeping between requests.
  • Reset Calendar - this will delete each event on each user's calendar as the import runs. This is useful for "starting over" when running multiple imports.

Configuration File

The configuration file for the application is named 'DocumentBackup.exe.config', and the following parameters are the configuration file options that are available.

By default configuration options are commented out of the file, but if the configuration file option is used the comments should be removed and sample placeholder information should be replaced where appropriate.

The configuration file option is provided as a means to store commonly used configuration settings for future use. Using the configuration file is not required to use the Calendar Import Utility.


Required Fields

  • GoogleAppDomain - This is the destination domain for Microsoft exchange calendar events.
  • GoogleAppsAdminUser - This is the admin user that will be used to query Google Apps for user information.
  • GoogleAppsAdminPassword - The admin user's password.
  • ProcessDomain - This specified whether the utility will process the entire domain or whether to look for the 'UserName' key and process a single user. Valid options for this field are "true" and "false". If any other values are supplied the value of the key will be inferred as false.
  • UserName - This key specifies a username for the utility to backup, if the ProcessDomain key is set to true this value key is ignored
  • OAuthConsumerKey - OAuth Consumer Key.
  • OAuthConsumerSecret - OAuth Consumer Secret.
  • ExchangeServer - This is the Exchange server where calendar information will be imported from.
  • ExchangeAdminLogin - This is the Exchange admin user that will be used to query for calendar events.
  • ExchangeAdminPassword - The Exchange admin user's password.

Optional Fields

  • OutputDirectory - This is the directory that user reports will be exported to. In the case of the Calendar Import Utility the folder specified will contain reports for each user. This field is not required and will default to 'C:\export' which will be created if it does not exist.
  • SleepInterval - By default the Calendar Import Utility will sleep between a specified amount of requests. The default value is 100 requests, but can be changed by specifying a different numerical value here.
  • SleepPeriod - By default the Calendar Import Utility will sleep between a specified amount of requests. The default value for this parameter is 10 seconds, but can be changed by specifying a different numerical value here. If the value 0 is supplied it will effectively disable sleeping between requests.

Example Configuration File

*Note* - After first run all settings listed below are encrypted to secure sensitive information

Example Use Cases

In all cases the following keys are assumed to be contained under the appSettings section in the configuration file 'CalendarImport.exe.config'


Use Case
 Configuration Keys
Domain Import
 <add key="GoogleAppsDomain" value="domain.com"/>
<add key="GoogleAppsAdminLogin" value="administrator"/>
<add key="GoogleAppsAdminPassword" value="password"/>
<add key="ProcessAllUsers" value="true"/>
<add key="OAuthConsumerKey" value="domain.com"/>
<add key="OAuthConsumerSecret" value="DdhDnX8921d"/>
<add key="ExchangeServer" value="http://exchange.domain.com/" />
<add key="ExchangeAdminUser" value="admin@domain.com" />
<add key="ExchangeDomain" value="domain.com" />
<add key="FormsBasedAuth" value="false" />
User Import
 <add key="GoogleAppsDomain" value="domain.com"/>
<add key="GoogleAppsAdminLogin" value="administrator"/>
<add key="GoogleAppsAdminPassword" value="password"/>
<add key="ProcessAllUsers" value="false"/>
<add key="UserName" value="username" />
<add key="OAuthConsumerKey" value="domain.com"/>
<add key="OAuthConsumerSecret" value="DdhDnX8921d"/>
<add key="ExchangeServer" value="http://exchange.domain.com/" />
<add key="ExchangeAdminUser" value="admin@domain.com" />
<add key="ExchangeAdminPassword" value="password" />
<add key="ExchangeDomain" value="domain.com" />
<add key="FormsBasedAuth" value="false" />
Override Export Directory <add key="GoogleAppsDomain" value="domain.com"/>
<add key="GoogleAppsAdminLogin" value="administrator"/>
<add key="GoogleAppsAdminPassword" value="password"/>
<add key="ProcessAllUsers" value="true"/>
<add key="OAuthConsumerKey" value="domain.com"/>
<add key="OAuthConsumerSecret" value="DdhDnX8921d"/>
<add key="ExchangeServer" value="http://exchange.domain.com/" />
<add key="ExchangeAdminUser" value="admin@domain.com" />
<add key="ExchangeAdminPassword" value="password" />
<add key="OutputDirectory" value="C:\export\googleapps\domain.com\calendar" />
<add key="ExchangeDomain" value="domain.com" />
<add key="FormsBasedAuth" value="false" />
Override Sleep Intervals <add key="GoogleAppsDomain" value="domain.com"/>
<add key="GoogleAppsAdminLogin" value="administrator"/>
<add key="GoogleAppsAdminPassword" value="password"/>
<add key="ProcessAllUsers" value="true"/>
<add key="OAuthConsumerKey" value="domain.com"/>
<add key="OAuthConsumerSecret" value="DdhDnX8921d"/>
<add key="ExchangeServer" value="http://exchange.domain.com/" />
<add key="ExchangeAdminUser" value="admin@domain.com" />
<add key="ExchangeAdminPassword" value="password" />
<add key="SleepInterval" value="500" />
<add key="SleepLength" value="50" />
<add key="ExchangeDomain" value="domain.com" />
<add key="FormsBasedAuth" value="false" />

Calendar Import Process

Calendar Importer leverages WebDAV and Google Apps Calendar Data API to provide a per user sync of calendar information.

Listed below are the guidelines for special event types used by which an Microsoft Exchange Calendar is converted to a Google Calendar. These guidelines dictate the import of meeting requests and recurring appointments.


Meeting Requests

Meeting requests are supported by the Calendar Importer. Meetings typically will be returned multiple times during the duration of the import. To ensure that duplicates are not entered onto the Google Apps calendar the following process has been put into place:

  • Meetings are only entered onto the organizer's Google Calendar. Events will become available to other users when the organizer's calendar is processed.
  • If a meeting is found but the current user is not the organizer it will be skipped and will instead be created when the organizer's calendar is processed.

Due to the process by which meetings are handled the following behavior may be observed:

  • During a single user sync some meetings may not be immediately available in Google Calendar.
  • The number of events imported may be significantly lower than the appointments retrieved from Microsoft Exchange.

This behavior is by design and lets the Calendar Importer provide the following features:

  • Imported events will be actual meetings between domain users instead of single events on each user's calendar.
  • Guests lists are preserved, enabling the collaborative aspects of Google Apps.
  • Event organizers will be able to send out invites, and update meetings without having to recreate meetings from Microsoft Exchange.

Recurring Appointments

Recurring Appointments are a supported feature. Recurring appointments are handled using the iCalendar specification for recurring appointments. Because both Microsoft Exchange and Google Apps support this format, a one to one matching of recurring appointments is directly available.

Due to how recurring appointments are handled, the number of events imported may be significantly lower than the appointments retrieved from Microsoft Exchange. Recurrences of appointments are skiipped during appointment, and only the master event is imported into Google Calendar. Recurrences are created implicitly by Google Calendar.


Output

User reports are stored under the output directory specified at runtime. User reports contain contain statistics on a user level including amount of errors, and amount of succesful entries. Along with a list of the items imported to the users Google Calendar.

Domain level reporting is also stored under the output directory specified at runtime. This report contains a summary of statistics for all users.


Executing Imports

Once all required fields are entered the import is ready to be ran. To run the utility you can click the 'Run' button that is placed along with the required fields, or you can click over to the 'Run' tab and start the backup from there.

If all parameters are valid, and the backup is started, all logging will be printed to the main text box on the 'Run' tab. At any point you can the output from the utility can be exported to a .txt file.

Reporting

The Calendar Import Utility supports reports for both users and domains. After completing processing, a user report is created that lists the following information:

  • Date of backup
  • Username
  • User first name and last name
  • Domain
  • Number of successfully imported calendar events
  • Number of calendar events unable to be imported
  • Elapsed time
  • List of successfully imported calendar events
  • List of calendar events unable to be imported and reason per calendar events

User reports are stored under the output directory.


Example User Report

Domain reports aggregate content from the user reports and provide a summary of the processing that was done for the domain.

Domain reports contain the following information:

  • Date of backup
  • Domain
  • Number of users
  • Number of successfully imported calendar events
  • Average number of calendar events imported per user
  • Number of calendar events unable to be exported
  • Average number of calendar events unable to be imported per user
  • Elapsed time
  • List of users exported, plus success and error counts for each user.

Example Domain Report