Google Contact Import Documentation

Version 0.98

The Contact Import Utility is a Windows application that allows contacts to be migrated from an Exchange Server to Google Apps.

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


Platform Requirements

  • Windows Based PC (XP, Vista, Server) with .NET 3.5 Installed (Available through Windows Update or directly from Micosoft)
  • 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 Google Contact 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 Contact 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.
  • Enable Forms Authentication - Check this option if the exchange server has forms based authentication enabled on it.

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 Contact 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 Contact 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 Contact 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 Contacts - this will delete each user's contacts 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 Contact Import Utility.


Required Fields

  • GoogleAppDomain - This is the destination domain for Microsoft exchange contacts.
  • 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 contact information will be imported from.
  • ExchangeAdminLogin - This is the Exchange admin user that will be used to query for contacts.
  • 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 Contact 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 Contact 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 Contact 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 'ContactImporterGUI.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="ExchangeAdminPassword" value="password" />
<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\contacts" />
<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" />

Output

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

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 the output from the utility can be exported to a .txt file.

Reporting

The Contact 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 contacts
  • Number of contacts unable to be imported
  • Elapsed time
  • List of successfully imported contacts
  • List of contacts unable to be imported and reason per contact

    • 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 contacts
    • Average number of contacts imported per user
    • Number of contacts unable to be exported
    • Average number of contacts unable to be imported per user
    • Elapsed time
    • List of users exported, plus success and error counts for each user.

    Example Domain Report