Table of Contents

  1. System Requirements
  2. Installation
  3. Registration
  4. Getting Started
  5. Backing Up
  6. Syncing Calendars
  7. Syncing Contacts
  8. Tips and Tricks
  9. Known Issues
  10. Troubleshooting
  11. Uninstalling
  12. Restoring to Pre-Install State

System Requirements

Installation

Installing Spanning Sync is easy:

  1. Quit System Preferences if it is open.
  2. Download the latest version of Spanning Sync from spanningsync.com/download.
  3. Open the downloaded .dmg file.
  4. Read and agree to the licensing agreement
  5. Double-click the Spanning Sync pref pane.
  6. Select "Install for current user" or "Install for all users on the system", as appropriate.
The Spanning Sync download package includes an Uninstaller which will completely uninstall Spanning Sync, should you ever need to do so.

Registration

You can try Spanning Sync free for up to 15 days. After the trial period, the software will stop synchronizing your data and prompt you to either register or uninstall.

To register, open the Spanning Sync preference pane, wait for the prompt, and click the "Buy" link. You must login to Spanning Sync using a valid Google Account and password in order for the prompt to appear.

Getting Started

Once you've downloaded and installed Spanning Sync, you're ready to start synchronizing your calendars and contacts.

Important: Before syncing any calendars, make sure that there are no calendar events which exist in multiple calendars. Having the same calendar events in multiple calendars confuses Apple Sync Services and can result in data loss. Spanning Tools for Mac includes a tool which can identify such events.

Sign In…

Click the Sign In button, then enter your Gmail or Google Apps email address and password.

Click the Sign In button to activate your account.

Select a Schedule…

Spanning Sync syncs immediately whenever the calendars and contacts on your Mac change, but the schedule you select here guarantees a minimum interval for changes to be pulled down from Google.

Enable Calendar Syncing…

  1. Click the Calendars tab.
  2. Select the "Sync calendars" checkbox.
  3. Pair your iCal calendars with the Google calendars that you want to sync with.
Calendar pairs are always one-to-one. That is, each iCal calendar syncs with at most one Google calendar. Synchronization occurs in both directions unless one of the calendars is read-only (like a calendar of holidays or a shared calendar to which you have read-only access).

Continue to pair as many iCal and Google calendars as you like.

Important: Please see the Backing Up section before proceeding.

Enable Contact Syncing…

  1. Click the Contacts tab.
  2. Select the "Sync contacts" checkbox.

Sync!

If you'd like to begin a sync immediately, click the Sync Now button.

Note: The first sync session always takes much longer than subsequent syncs because every single calendar event and contact has to be sent over the network. 10 minutes for each large calendar and/or a large Address Book is typical.

That's it! Your calendars and contacts are now automatically synchronized in both directions. If you are syncing any other devices or applications with calendars or contacts on your Mac, they will reflect new and updated events in Google Calendar.

Use the menu bar icon to manually start a sync, to check the time of the last sync, or as a shortcut to the preference pane. To turn the menu bar icon off, uncheck the "Show status in menu bar" checkbox in the preference pane.

Backing Up

Calendars and contacts can be among the most important things on your computer. While we've rigorously tested Spanning Sync, it's difficult to predict what will happen when several applications and devices are syncing the same data at the same time. For this reason, we highly recommend backing up your data.

Note: When first opened, Spanning Sync creates backups of your calendars and contacts and stores them at ~/Library/Application Support/Spanning Sync.

iCal

To back up your iCal calendars, select "Back up iCal" from the File menu.

To restore your iCal calendars, select "Restore iCal" from the File menu.

Google Calendar

The best way to automatically back up and restore Google Calendar is to use Spanning Backup. Spanning Sync customers get $10 off the regular price.

To manually back up your Google calendars:

  1. Login to Google Calendar and select Settings > Calendars > Export calendars.
  2. A zip file containing ICS versions of all of your calendars will be downloaded to your computer.

To manually restore your Google calendars:

  1. Login to Google Calendar and select Settings > Calendars > Import calendar.
  2. Choose an ICS file on your Mac and a Google calendar to which they'll be added, then click Import. (Note that events will be added to the calendar you select, so you need to create a new calendar first to wind up with a calendar with only the events from your backup.)

Address Book

To backup your Address Book, select "Export > Address Book Archive" from the File menu.

To restore your Address Book, select "Import > Address Book Archive" from the File menu.

Google Contacts

The best way to automatically back up and restore Google Contacts is to use Spanning Backup. Spanning Sync customers get $10 off the regular price.

To manually back up your Google contacts:

  1. Sign in to Gmail.
  2. Click Contacts along the left side of any Gmail page.
  3. Click Export in the lower-left corner of your Contacts.
  4. Choose whether to export all contacts or only one group.
  5. Select the CSV format.
  6. Click Export.
  7. Choose Save to Disk then click OK.
  8. Select a location to save your file, and click 'OK.'

Note: Manual contact backups will not include group information. This is a known issue, and Google is working to resolve it.

To manually restore your Google Contacts:

  1. Log in to Gmail.
  2. Click Contacts on the left side of any Gmail page.
  3. Click Import in the bottom-left corner.
  4. Click Browse... and locate the CSV file you'd like to upload.
  5. Select the file and click Import.
Once you've successfully uploaded the document, Google will display the number of contacts imported.

Syncing Calendars

Syncing calendars from Apple's iCal to Google Calendar is easy. Before starting, you should already have created the iCal calendars and Google calendars that you wish to sync with each other.

In the Calendars tab of the Spanning Sync preference pane, you'll see a list of iCal calendars on the left and Google calendars on the right. To begin syncing a pair of calendars, select the checkbox next to the iCal calendar you want to sync and then choose the corresponding Google calendar from the pop-up menu.

Calendar pairs are always one-to-one. That is, each iCal calendar syncs with at most one Google calendar. Synchronization occurs in both directions unless one of the calendars is read-only (like a calendar of holidays or a shared calendar to which you have read-only access).

When you sync a calendar for the first time, all events from iCal are sent to Google and all events from Google are sent to iCal (assuming the sync method is set to "Sync both directions"; more about this later). Naturally, this kind of sync will take much longer than normal. 5-10 minutes is typical but a very large calendar with many thousands of events can take up to 30 minutes. Subsequent syncs will only take a few seconds.

Syncing One-way

Spanning Sync allows you to sync two calendars in a single direction, protecting one calendar from ever being modified by the syncing process. To do so, double-click the calendar pair to bring up the options panel and choose either "Sync to iCal" or "Sync to Google" from the "Sync method" popup menu. "Sync to iCal" means that data will only flow to iCal and the data on Google will never be modified. "Sync to Google" means that data will only flow to Google and the data in iCal will never be modified. Choosing "Sync both directions" enables traditional synchronization between both calendars. You can also change the sync method from the button bar at the bottom of the calendar list.

Skipping Old Events

For large, older calendars you may be able to speed up the sync process by skipping over older events. To do so, double-click the calendar pair to bring up the options panel, check the "Do not sync events older than" checkbox and choose a number of days. Events older than that will not be synced, with one exception: recurring events are always synced.

Syncing Alarms

iCal and Google Calendar both offer a variety of alarm options. If alarm syncing is enabled in the calendar options panel, then Spanning Sync will map existing iCal alarms to your choice of popup alarms, email messages, or SMS messages on Google Calendar. Existing Google Calendar popup alarms will sync to iCal as a message+sound alarm. Existing Google Calendar email message and SMS alarms will not sync since it's unlikely that you'd want to receive those alarms twice.

Replacing Data

You can replace all existing events in a Google calendar with the contents of an iCal calendar by selecting "Replace Data on Google" from the Advanced tab of the Spanning Sync preference pane. However, care should be used when doing this as Google does not completely delete the calendar events for up to a week. Doing this more than once during that period can lead to a situation where the calendar account has gone "over-quota" with Google and further syncs will fail until Google purges the old data.

You cannot replace an iCal calendar with the contents of a Google calendar during a sync since Apple doesn't allow it. Instead, you can delete the existing iCal calendar, create a new one with the same name, pair it in the Spanning Sync preference pane, and sync.

Duplicates

Duplication can be a serious concern when synchronizing data across servers and devices. Spanning Sync uses specialized technology to prevent duplicate calendar events from appearing in iCal or Google. If duplicates do appear, there may be an issue with time zones or other devices and services that you sync with. Please see the troubleshooting section at the end of this document.

One great way to keep duplicates in check is to use the Calendar Cleaner program, which is part of Spanning Tools for Mac. Spanning Sync customers get $5 off the regular price.

Syncing Contacts

Spanning Sync keeps contacts in your Mac OS X Address Book synchronized with your Gmail contacts. Contact names, street addresses, phone numbers, email addresses, IM addresses, job titles, notes, and pictures are synchronized.

Contact Groups

If you only want a subset of your Address Book contacts to sync, use the contact group feature of Spanning Sync.

In the above example, only contacts in the Address Book group "Businesses" will sync to Google and all new contacts from Google will be placed in the "Businesses" group. In this mode, contacts are deleted from Google only when they are completely deleted from Address Book, not when they are deleted from the Address Book group.

Syncing One-Way

Spanning Sync allows you to sync contacts in a single direction, protecting either your Mac or your Google contacts from ever being modified by the syncing process. To do so, choose either "Sync to Address Book" or "Sync to Google" from the popup menu in the upper-right corner of the Contacts pane. "Sync to Address Book" means that data will only flow to Address Book and the data on Google will never be modified. "Sync to Google" means that data will only flow to Google and the data in Address Book will never be modified. Choosing "Sync both directions" enables traditional synchronization between both sets of contacts.

Duplicates

Duplication can be a serious concern when synchronizing data across servers and devices. Spanning Sync uses specialized technology to prevent duplicate contacts from appearing in Address Book or Google. If duplicates do appear, it's probably because a contact with an unusual name (e.g. no last name) existed in both Address Book and Google that couldn't be matched up with one another.

One great way to keep duplicates in check is to use the Contacts Cleaner program, which is part of Spanning Tools for Mac. Spanning Sync customers get $5 off the regular price.

Tips and Tricks

Sync Multiple Macs

Spanning Sync can do much more than just sync your calendars and contacts with Google. By using Google as a "hub," you can sync data on multiple Macs to each other.

Syncing multiple Macs is easy.

  1. Create new Google calendars for each of the iCal calendars you wish to sync.
  2. If you haven't done so already, create matching iCal calendars on all of the Macs that you want to sync.
  3. Install Spanning Sync on each of the Macs.
  4. On each Mac, enter the same Google account name and password and pair the same iCal calendars to the same Google calendars. The Spanning Sync preference pane should look nearly identical on each computer.
  5. Begin syncing each Mac with Spanning Sync.
Note: If you're syncing multiple Macs with the same Google account, you only need to purchase a single Spanning Sync license.

Sync Multiple Google Accounts

You may have multiple Google accounts for which you use Google Calendar, and yet want to sync these to a single Mac. This is made possible by Google's calendar sharing feature.

  1. Let's call whichever Google account has the most calendars that you're interested in your "primary" account.
  2. Login to Google Calendar for the other accounts and share your calendars with the primary account. Be sure to enable full read/write permissions ("Make changes to events") for the primary account.
  3. Login to Spanning Sync using your primary Google account. You should see calendars from all of your shared accounts and can now sync all of them with iCal.

Log Window

The log window can help provide detailed information about status of the syncing process and which calendar events and contacts are changing. You can open the log window from the Advanced tab of the Spanning Sync preference pane.

Sync Address Book Birthdays

A little-known feature of iCal and Address Book lets you create a virtual Birthdays calendar and sync it to Google.

  1. Open iCal, go to preferences, and select "Show Birthdays calendar."

  2. If you haven't done so already, add a Birthday field to the Address Book template and start adding birthdays for your contacts.
  3. A "Birthdays" calendar will now show up in Spanning Sync which you can sync to Google Calendar.

Starting a Sync From a Script

While Spanning Sync is not currently AppleScriptable, you can initiate a sync via AppleScript, Automator action, Mac OS X service, or shell script by invoking this shell command:

"/Library/PreferencePanes/Spanning Sync.prefPane/Contents/Resources/Spanning Sync.app/Contents/MacOS/Spanning Sync" -sync-now -exitWhenDone

Note: Place a "~" at the beginning of the above path if you installed the pref pane for only the current user.

Customizing the Sync Schedule

The Account & Schedule tab offers some basic scheduling options, however advanced users might want to customize the sync schedule. To do so, copy and paste these lines into Terminal (located in the Utilities folder), replacing seconds with the number of seconds you want between each sync:

defaults delete com.spanningsync nextScheduledSync
defaults write com.spanningsync syncInterval -int seconds
"/Library/PreferencePanes/Spanning Sync.prefPane/Contents/Resources/Spanning Sync.app/Contents/MacOS/Spanning Sync" -notify-read

Note: Place a "~" at the beginning of the above path if you installed the pref pane for only the current user.

Delete Protection

Spanning Sync will notify you if five or more contacts or calendar events are to be deleted from your Mac or from Google and give you a chance to skip them so the data isn't deleted. If you'd like to be notified when Spanning Sync is about to delete any data, then set the threshold to one by copy and pasting this line into Terminal (located in the Utilities folder):

defaults write com.spanningsync deleteWarningThreshold -int 1

Merging All Data

By option-clicking the "Start Over" button in the Advanced tab of the pref pane, you can cause the next sync to merge all of the selected data between your Mac and Google. This is like starting over without losing your preferences.

Known Issues

Syncing CalDAV Calendars

Currently, Apple does not allow sync software to modify CalDAV calendars so these calendars will only sync one-way to Google.

Copying & Pasting Events

Copying an event and then pasting it into the same calendar creates a duplicate event. Even if you plan to change the pasted event, iCal will probably sync the pasted event to other sync clients on the computer (including Spanning Sync) before you've changed it. When this happens, the pasted event can become incorrectly linked to the existing event in Google Calendar. If you want to use one event as a template for another, paste it into a new "scratch" calendar, make the modifications, then move it back to the desired calendar.

Moving Events Between Calendars

In iCal, if you move an event from one calendar to another, the change may not sync to Google. To work around this issue:

  1. Select the event in iCal and press Command-X ("Cut").
  2. Select the calendar to which you would like to move the event.
  3. Press Command-V ("Paste").

Deleting Paired Calendars

Deleting an iCal calendar that you sync is fine, however if you then create a new iCal calendar and pair it with the same Google Calendar that was paired with the deleted calendar, there could be unexpected side effects such as deleted events. If you really need to do this, you should do a "Start Over" from the Advanced tab of the Spanning Sync pref pane before syncing with the new calendar.

Spotlight Indexing

Spotlight may try to index some of Spanning Sync's data files, causing unnecessary CPU usage after each sync. To prevent this, open the Spotlight pref pane and drag this folder to the list in the Privacy tab:

Note: In Lion, access the ~/Library folder by holding down the Option key while selecting the Go menu in the Finder.

Spanning Sync and Entourage

Some users find that Entourage causes Spanning Sync to sync every 10 seconds. This occurs because Entourage is "trickle syncing" every 10 seconds and, since Spanning Sync trickle syncs too, Apple Sync Services asks Spanning Sync to sync each time. To prevent the problem, you can turn off trickle syncing in Spanning Sync by copy and pasting the below lines into Terminal (located in the Utilities folder):

defaults write com.spanningsync noTrickleSyncing -bool YES

Note: Place a "~" at the beginning of the above path if you installed the pref pane for only the current user.

Note: With trickle syncing turned off, Spanning Sync will only sync on its schedule and won't sync immediately when changes are made to Address Book or iCal.

Spanning Sync and Little Snitch

Some users have reported issues between Spanning Sync and Little Snitch, while others have reported that the two work fine together. The trick seems to be that you need to allow port 80 and port 443 access to the following:

/Library/PreferencePanes/Spanning Sync.prefPane
/Library/PreferencePanes/Spanning Sync.prefPane/Contents/Resources/Spanning Sync.app
/Library/PreferencePanes/Spanning Sync.prefPane/Contents/Resources/Spanning Sync Notifier.app

Note: Place a "~" at the beginning of the above path if you installed the pref pane for only the current user.

Troubleshooting

Finding and Fixing Common Problems

Spanning Tools for Mac is a suite of utilities that analyzes, reports, and fixes dozens of problems with iCal, Address Book, and Apple Sync Services—problems ranging from the obvious, such as duplicated calendar events, to the subtle, such as invalid calendar dates and poorly formatted contact names. A discount is available for Spanning Sync customers.

Contacting Spanning Sync

Before contacting Spanning Sync, please review the topics and suggestions below. If you can't resolve the problem, please send us a troubleshooting report:

  1. Open the Spanning Sync preference pane.
  2. Click the "Advanced" tab.
  3. Click the "Create Report" button.
  4. Email the file the appears on your desktop to support@spanningsync.com along with a detailed description of the problem.

Resetting Spanning Sync

Some of the topics below suggest "starting over" with Spanning Sync. "Starting over" with Spanning Sync will never cause data to be lost; it will only cause the next sync to take a long time. Here's how:

  1. Open the Spanning Sync preference pane.
  2. Click the "Advanced" tab.
  3. Check "Start Over".
  4. Click "OK".
Note: After the "start over" procedure you'll need to re-enter your account information and re-select your calendar/contact syncing options.

Resetting Apple Sync Services

Some of the topics below suggest resetting Apple's Sync Services, which is one of the functions provided by Spanning Tools for Mac. You can also do so manually:

  1. Open iSync (in /Applications).
  2. Go to preferences.
  3. Click "Reset Sync History".
  4. Read the fine print.

Resetting Google Calendar

If information in iCal is correct but information in Google Calendar is wrong, you can replace calendar data on Google with calendar data in iCal:

  1. Open the Spanning Sync preference pane.
  2. Click the "Reset…" button.
  3. Check "Replace info on Google Calendar with info from this computer".
  4. Click "OK".
  5. Sync.
Important: Resetting Google Calendar will remove attendee information and non-default alarms from synced Google calendars. Don't do this more than once a week as it can cause your Google Calendars account to go over-quota.

Nothing Happens When I Sync

Try one or more of the following:

The Spanning Sync Preference Pane Doesn't Show Up

The Unix permissions on your Preference Panes folder are probably incorrect. To solve the problem:

  1. Open Disk Utility, located in /Applications/Utilities.
  2. Select your boot drive in the Disk Utility window.
  3. Click the Repair Permissions button.
  4. Install Spanning Sync.

Calendar Events Are Duplicated

Duplicates can occur due to time zone mismatch issues where two or more of your calendar sources have different time zone settings. For example, the calendar on an iPhone can have time zone support turned on while iCal on the computer has time zone support turned off. If you create an event in a different time zone and then do a "refresh" sync, you could end up with duplicates or time shifts. It's also a good idea to check each of your Google calendars to make sure their time zones are set the same as your iCal calendars, and the same for any other device or server that you sync with.

We recommend that you verify that all four of these time zone settings are the same:

Non-Apple phone-syncing software is also known to duplicate calendar events. In this case, you should use Spanning Tools for Mac to remove the duplicates and then contact the developer of the software.

It's also possible that iCal is syncing new events before you're done editing them, which can cause a duplicate. To prevent this from happening, you can turn off trickle syncing in Spanning Sync by copy and pasting the below lines into Terminal (located in the Utilities folder):

defaults write com.spanningsync noTrickleSyncing -bool YES

Note: Spanning Tools for Mac includes tools for removing duplicates from both iCal and Address Book, and also solves dozens of other common problems. A discount is available for Spanning Sync customers.

Google Calendars Don't Show Up

If no Google calendars show up in the Spanning Sync preference pane, try one or more of the following:

Google Calendar Shows Up as "Unknown"

Google can occasionally get confused about a calendar and stop sending us its name, so it shows up as "Unknown" in the Spanning Sync preference pane. To fix the problem, just log into Google Calendar, change the name of the affected calendar, save it, then change it back, and save again. Then refresh Spanning Sync by quitting System Preferences, reopening it, and reopening Spanning Sync. The correct calendar name should be listed.

Preference Pane Shows "An unknown error occurred"

Various networking problems can cause the preference pane to show an error "An unknown error occurred. Please check your network settings." Here are some things to check for:

Disabling Upgrade Reminders

If you're still running Mac OS X 10.4 "Tiger", you can't update to Spanning Sync 3 (which requires Leopard or better). But each time you launch the Spanning Sync pref pane it will prompt you to upgrade. You can prevent the Spanning Sync pref pane from prompting you to upgrade by copy this line and pasting it into a Terminal window:

sudo mv /Library/PreferencePanes/Spanning\ Sync.prefPane/Contents/Resources/English.lproj/Update.nib /Library/PreferencePanes/Spanning\ Sync.prefPane/Contents/Resources/English.lproj/Update.nib.disabled

Uninstalling

The download package comes with an Uninstaller which will completely remove Spanning Sync.

You can also manually remove Spanning Sync by entering the following into a Terminal window:

rm -r ~/Library/Application\ Support/Spanning\ Sync
killall Spanning\ Sync
killall Spanning\ Sync\ Notifier

and if installed for "this user":

rm -R "~/Library/PreferencePanes/Spanning Sync.prefPane"

or if installed for "all users on the system":

sudo rm -R "/Library/PreferencePanes/Spanning Sync.prefPane"

Restoring to Pre-Install State

When Spanning Sync is installed, a backup of your Mac's calendar and contact data is made automatically. To restore from that backup:
  1. Quit iCal, Address Book, and System Preferences if they're open
  2. Extract your backups:
  3. Delete your existing data:
  4. Replace it with your backed-up data:
  5. Log out of OS X and then log back in
Your data should now be restored to pre-install state. If not, or if you have any questions or run into any problems along the way, please contact us at support@spanningsync.com.

Legal

Copyright ©2006-2010 Spanning Sync, Inc. All rights reserved. Spanning, Spanning Sync, Spanning Tools, the Spanning Sync and Spanning Tools logos, and "Save 5+Make 5" are trademarks of Spanning Sync, Inc.

Mac and the Mac logo are trademarks of Apple, Inc., registered in the U.S. and other countries.