SyncML Synchronisation for iOS

SyncML Synchronisation for iOS - Page 1/26
SyncML Synchronisation for iOS
SyncML is an open synchronisation standard. Unlike many other synchronisation methods, which are often
under control of a single vendor, SyncML is supported by many vendors across many platforms, systems
and services. The power of SyncML lies in bringing together a wide variety of different devices and
software to share contacts, calendar and other data.
plan44.ch has experience with SyncML synchronisation software dating back to 2001, and today has one
of the most mature and feature rich SyncML implementations available.
This manual explains the SyncML features of plan44.ch's iOS apps, which are a the free SyncML LITE for
iOS for contacts synchronisation, the SyncML PRO for iOS for synchronizing the built-in iPhone calendar
and the Tasks+Cal+Sync with it's own fully SyncML enabled tasks and calendar functionality. For the first
time for a mobile device these apps also contain a full-featured SyncML server. A mobile server opens
completely new usage scenarios which were not possible before.
The plan44.ch SyncML enabled apps for iPhone are available on the AppStore. On a iPhone or a desktop
machine with iTunes installed, use the following link to get the apps:
http://itunes.apple.com/us/artist/id299521020
Contents
1. Usage Scenarios...............................................................................................................2
2. Choosing the SyncML service .........................................................................................3
Where to look for SyncML enabled services? ................................................................................................3
3. SyncML service setup parameters ...................................................................................4
4. Opening the SyncML client .............................................................................................4
5. SyncML Configuration .....................................................................................................5
Server Settings................................................................................................................................................6
Settings for the different data types...............................................................................................................7
Description of the available Sync Modes .......................................................................................................7
Special Options...............................................................................................................................................8
6. Synchronizing.................................................................................................................10
Viewing the Sync logs...................................................................................................................................11
Viewing debug logs ......................................................................................................................................11
7. AutoSync........................................................................................................................12
Setting up Autosync .....................................................................................................................................12
8. Suspend & Resume .......................................................................................................13
9. Using multiple SyncML accounts ...................................................................................13
Creating new SyncML accounts....................................................................................................................14
Synchronizing accounts.................................................................................................................................14
Deleting a SyncML account ..........................................................................................................................14
10. Using the SyncML server ...............................................................................................15
Synchronizing two iOS devices.....................................................................................................................16
Synchronizing other SyncML devices ...........................................................................................................17
11. Using Filters ...................................................................................................................18
Server Filters .................................................................................................................................................18
Client Filters..................................................................................................................................................18
Filter Syntax ..................................................................................................................................................18
Filter usage examples...................................................................................................................................20
12. Troubleshooting .............................................................................................................22
Error messages and error codes...................................................................................................................22
Reporting problems......................................................................................................................................26
!
© 2010-2012 by plan44.ch, CH Zürich, Switzerland - www.plan44.ch
SyncML Synchronisation for iOS - Page 2/26
13. Usage Scenarios
iPhone, iPad, iPod as a SyncML client
Acting as a SyncML client and accessing a server/service in the internet is todays most common usage for
SyncML in mobile devices.
All versions of "SyncML PRO" and "Tasks+Cal+Sync" are equipped with a SyncML client.
See Chapter 2 and subsequent about how to configure and use the SyncML client.
SyncML
Server/Service
Tasks+Cal+Sync or
SyncML PRO App
Other SyncML
enabled Phones
iPhone, iPad, iPod as a SyncML server
Tasks+Cal+Sync and SyncML Client for iOS also have a built-in SyncML server which allows completely
new synchronisation scenarios:
• direct synchronisation between iPhones, iPads or iPod touches, with no need for exposing data to
the internet or a third party service.
• direct synchronisation between an iPhone, iPad or iPod touch and any other Wi-Fi and SyncML enabled mobile phone from any vendor.
• direct synchronisation between an iPhone and desktop SyncML client software.
See Chapter "Using the SyncML Server" about how to use the SyncML server and how to configure
SyncML clients to use the iPhone based server.
Tasks+Cal+Sync or
SyncML PRO App
running as
SyncML Server
!
iOS devices
or other WiFi and
SyncML enabled phones
or desktop applications
© 2010-2012 by plan44.ch, CH Zürich, Switzerland - www.plan44.ch
SyncML Synchronisation for iOS - Page 3/26
14. Choosing the SyncML service
It is important to understand that the SyncML clients are just one side of a SyncML enabled
synchronisation. In order to synchronize, you usualle need a SyncML enabled internet service. Only in
case you want strictly local device-to-device sync over WiFi, you can use the built-in SyncML server of
Tasks+Cal+Sync and SyncML PRO (see Chapter on "Using the SyncML Server").
!
Please be aware that not many calendar, tasks list and contact managing services support SyncML
directly. For example, neither Apple iCal, nor MS Outlook, nor Google Calendar directly support
SyncML. However there are third party bridging solutions which can help.
Where to look for SyncML enabled services?
A large and mostly complete list of SyncML enabled software and services can be found in Wikipedia:
en.wikipedia.org/wiki/SyncML#SyncML_servers
While this list does not provide a lot of details, it is a good starting point to search for SyncML enabled
solutions.
Our SyncML clients work with any standards compliant SyncML server, and have been tested with many
products in the market. In particular, plan44.ch is working together with Oracle and Toffa:
• Oracle Beehive (www.oracle.com/beehive) and its predecessor Collaboration
Suite (OCS) provides SyncML synchronization as a standard feature. plan44.ch
and Synthesis SyncML clients are Oracle's recommended choice.
• AddressBookONE (www.addressbookone.com)
GooSync (www.goosync.com) from Toffa are all
SyncML based solutions which enable connecting
SyncML clients with other, non-SyncML services
(like Google Calendar with GooSync and various
social networking services with AddressBookONE).
Other services and software known working include eGroupware.org, horde.org, syncevolution.org,
funambol.com, consolidate.at, desknow.com, mdaemon.com, soocial.com, zyb.com, synkia.com,
o-sync.com, nexthaus.com, mobical.net, synchronica.com, mobiledit.com, and many others.
!
© 2010-2012 by plan44.ch, CH Zürich, Switzerland - www.plan44.ch
SyncML Synchronisation for iOS - Page 4/26
15. SyncML service setup parameters
Once you have choosen a SyncML enabled service, you should have the following information which
enables you to setup the iPhone SyncML client (or any other SyncML client, for that matter):
• The SyncML server URL. Note that this is usually a different URL than the one you are using to access
the service on the web.
• The SyncML server login (username and password). In most cases, this is the same user name and
password as required to login to the service via the web. Still, some services might have a different
login for sync.
• The database names. Each type of data (like contacts, calendar, tasks list) have a name on the server.
In many cases, these are "contacts", "events", "tasks" (which are also the default settings). However,
please make sure these apply to your SyncML service (e.g. Oracle uses different names).
that plan44.ch is usually the wrong address to ask for these setup parameters. We don't run
! Note
the SyncML service and don't have access to service specific support information. So please contact the SyncML service provider to obtain this information, not us.
16. Opening the SyncML client
First, start the SyncML enabled app. Since Version 3.0 of Tasks+Cal
+Sync and SyncML PRO, the SyncML synchronisation part of the
application is integrated into the preferences - just press the
preferences button in the top left to enter the preferences
main screen from where you have quick access to all sync
functions.
• The "About..." item at the top is useful to see the version of the
program itself and the SyncML engine (important for support). It
also contains an active link to the plan44.ch web site and a link for
downloading a quick reference PDF.
• "Sync now" starts a synchronisation (but please configure the sync
correctly first).
• "SyncML settings" is where you can configure all parameters
needed for sync. You can create multiple profiles if you have different sync servers to sync with.
• "Sync Log" shows a summary of past synchronisations including the status (and error message, in case
of problems).
• "Start SyncML Server" opens the SyncML server screen, which can
be used to sync other devices directly with your iOS device. See
chapter 9 for more information about the SyncML server.
!
!
SyncML LITE is a sync-only app and uses a tab bar at the bottom to choose between the different screens. The functionality
is the same as for the other two apps, but it has a slightly different layout:
• The "Synchronize" screen is where you can start a synchronisation and observe its progress and completion.
• The "Settings" is where you can configure the sync parameters.
• The "Profiles" screen allows to manage multiple SyncML
services.
• The "Log" screen shows a short summary of the results of
past synchronisations.
• The "About" screen is useful to see the version of the program itself and the SyncML engine. It also contains an active
link to the plan44.ch web site.
© 2010-2012 by plan44.ch, CH Zürich, Switzerland - www.plan44.ch
SyncML Synchronisation for iOS - Page 5/26
17. SyncML Configuration
Open the "SyncML Settings" from the preferences.
This will show the autosync settings and a list of your SyncML
accounts. When using the app for the first time, there is no SyncML
account configured yet, so please choose "Add new account..." to
create one.
most cases, you'll synchronize with a single SyncML server so
! In
you'll only need one SyncML account.
After creating a new account or choosing one of your existing
acconts for editing, you'll get to the SyncML Account screen.
The SyncML Account screen has the following options:
• Profile name: This is a desciptive label for the account you can
choose freely. It is also used to identify the account in the sync
logs and in the sync progress displays.
• Sync this account in autosync and global sync: If this switch is
off, the only way to sync this account is by pressing the "Sync this
account now" button (see below). If this switch is on, this account
will be included in autosync and will be synchronized when the
global "Sync Now" button (in the main preferences screen) is
pressed.
! Make sure to enable this only for accounts that were set-up
correctly and tested for working ok first in a separate (single
account) sync, because tracking down setup problems with
multiple accounts involved or syncs happening automatically
can be very tricky.
• Sync this account now: Pressing this button starts a synchronisation with this account only. This is useful for testing a new account's settings before including it into autosync or global sync.
• Server settings: This is where you configure the server URL and
login for the account (see details below)
• Contacts, Tasks, Calendar (it depends on the app which of these
are available). This is where you can enable and configure the synchronisation of the different types of data. Each needs at least the
correct "server path" (ask your SyncML server provider).
! Before iOS5 and iCloud, most people just had one single addres book or calendar, which was usually automatically selected for synchronisation. With iOS5
and iCloud, this has changed - most iOS devices now have at least local and and iCloud address
books and calendars. So unlike before, you need to select the correct address book or calendar to sync before synchronisation can work! See details below in paragraph "Special Options".
Duplicate
Account: duplicates the current account, in case you want to create a second account with
•
similar settings.
! Avoid using two accounts with the same server and the same login - this will inevitably lead to
massive sync confusion! Multiple accounts are fine to sync with more than one account on the
same server, or more than a single server.
• Delete Account: This is to remove an account from the app's settings. Deleting the account in the
app does however in no way modify the actual server account or it's data!
!
© 2010-2012 by plan44.ch, CH Zürich, Switzerland - www.plan44.ch
SyncML Synchronisation for iOS - Page 6/26
Server Settings
In the "Server Settings" screen you can set the details of the SyncML
server account to use:
• URL: Enter the server URL as specified by your SyncML service
provider.
! Note that secure connections with SSL/HTTPS are supported
- simply use https:// instead of http:// to start the Server URL.
• Bonjour: This is useful to find local SyncML servers (like another
iPhone). Note that this might also show other local web servers as
well, e.g. printer configuration pages, which are not suitable for
sync.
• SyncML Version: Usually, this does not need to be changed, because the best SyncML version is negotiated automatically with
the server. However, some servers which claim to support a newer
SyncML version might not correctly do so - with this setting you
can force the app to use a lower SyncML version (e.g. 1.1 instead
of 1.2).
! Note that this field shows the negotiated SyncML version
after the first successful sync with a server (and not longer
reads "automatic").
• User and Password: This is how you login to the SyncML service.
Normally (but not necessarily!), SyncML user and passwords are
the same as for accessing the service via the web.
• Ignore SSL errors: This switch allows to communicate with SSL
even if the certificate of the server cannot be verified or is expired.
! Note that this option is potentially dangerous, and should be
only used if you really know why you have to use it (e.g. if you have your own server with selfsigned certificates). Otherwise, ignoring SSL errors is a security risk!
• Use Proxy: If this switch is set to on (default), and the current network connection defines a HTTP
proxy, it is used to connect to the SyncML server. To avoid using the proxy, set this switch to off.
• Use HTTP Authentication: If your server needs HTTP authentication (only very few do), this switch can
be used to reveal secondary user and password fields for HTTP authentication.
• Log next Sync: In case of sync problems, switching this on will generate log files of the next sync attempt, and will ask you at the end of the synchronisation to transmit them to plan44.ch for diagnosis.
! Please don't just send logs - in order to diagnose problems please also send an email describing
the problem, and let us know the date and time of the sync attempts so we can locate the logs.
! Starting with Tasks+Cal+Sync 2.0.1, you can also use the built-in web server to view the logs from
a desktop computer's browser: Just choose "Keep for later" instead of "Yes, send logs", then
activate the built-in SyncML server and browse it from the desktop computer (in Safari, you can
find it via Bonjour, otherwise use the URL displayed on the server screen). Both iPhone and desktop computer must be logged into the same Wi-Fi network for that.
Legacy
mode: For certain servers which do not properly behave according to the SyncML standard,
•
this switch can help to make sync work as it turns on a number of workarounds.
! Only turn on "Legacy mode" in case you experience actual problems with a certain server, because this mode restricts some SyncML operations to older and simpler "legacy" versions that
may not have the same functionality than the newer versions.
!
© 2010-2012 by plan44.ch, CH Zürich, Switzerland - www.plan44.ch
SyncML Synchronisation for iOS - Page 7/26
Settings for the different data types
For all data types, the following settings are present:
• Server Path: This is how the database is called at the server's end.
The app shows default values here ("contacts", "events", ...)
which are widely used for SyncML servers, so in many cases you
don't need to change these.
! Still, some servers need different names here - please refer
to setup instructions from your SyncML provider. For example OCS needs "./contacts", "./calendar/events" and
"./calendar/tasks"
! Some servers (such as those based on our server engine) allow some extra options to be specified in addition to the
server DB name. Note that such options are server specific,
so please refer to your SyncML service provider's instructions to see if such extras are supported.
Therefore, in case of problems when synchronizing events or
emails with a certain server, disable the extra options and try
again.
Sync
Mode: This determines how to synchronize data. See next
•
paragraph for a detailed description of all sync modes. The default setting is "Normal" which means two-way synchronisation.
• Server Filter and Client Filter: These are advanced settings that
can be very useful to restrict data that is sent by the server or the client by certain conditions, such as
a match of a certain tag or contacts group. Please refer to the separate chapter on filters for details,
example uses and syntax of the (rather technical) filter expressions.
! Usage of filters is no-trivial. While you can build advanced sync scenarios using filters, it requires
a firm conception of the sync mechanisms in order to archieve useful results. Otherwise, toying
around with filters is most probably asking for trouble.
! While the SyncML standard does specify the filter mechanism, only very few servers implement it
(the iPhone server does). So please use the "server filter" option only with servers that understand filters.
Description of the available Sync Modes
• Normal: Normal two-way synchronisation. All changes on the device are sent to the server, all changes on the server are sent to the
device. This is the default mode of operation.
! For the initial synchronisation with a server and to recover from
error conditions (like data loss on client or server, prematurely
interrupted synchronisation etc.), a "Slow Sync" (see below)
might be needed and will be automatically performed even if
sync mode is set to "Normal".
Slow
Sync: Special two-way synchronisation needed for the very
•
first synchronisation with a server and to recover from error conditions. A "slow sync" is called slow because it includes that all data is
sent from the device to the server which can take some time. The
server takes an inventory of the device's data, so it'll be able to use
"normal sync" (only changes are transferred, which is of course
much faster) in subsequent syncs.
! This mode is normally used automatically by the software when needed, there is seldom a reason
to choose "slow sync" manually.
• Update Device: This is like "normal" sync, however only the device will be updated with changes from
the server - the data on the server will NEVER be changed at all.
! Using this mode means that you want to have a copy of server's data on your mobile device. This
implies that when you do an "update device" sync for the first time, all extra data on your device that does not exist in your server account will be deleted!
!
© 2010-2012 by plan44.ch, CH Zürich, Switzerland - www.plan44.ch
SyncML Synchronisation for iOS - Page 8/26
• Reload Device: This is a special "slow" sync as follows: First, all data on the device will be erased,
then, all data from the server will be copied to the device.
! This is a good mode to restore a device which has accidentally modified or deleted data on it.
! As this involves loosing all data that was not previously saved on the server, a warning message
will be shown when you start syncing in this mode.
• Update Server: This is like "normal" sync, but only changes made on the device will be sent to the
server. The data on the device will NOT be changed at all. Note that this mode does not work with all
SyncML servers (server must support "one way sync from client mode")
! Using this mode means that you want to make your server account an exact copy of the data on
your mobile device. This implies that when you do an "update server" sync for the first time, all
extra data in your server account that does not exist on your device will be deleted!
• Reload Server: This is the opposite of "reload device" and works as a special "slow" sync as follows:
First, all data on the server will be erased, then, all data from the device will be copied to the server.
! Note that this mode does not work with all SyncML servers (server must support "refresh from
client mode")
Special Options
These options apply only to some of the datatypes.
• Contact images scaling: With iOS devices having higher resolution cameras and displays, contacts
images tend to get quite large when created on the iOS device.
This has two drawbacks in respect to SyncML: for one transferring
large images during sync takes more time, especially in initial or
slow syncs. Second, not all SyncML servers can handle large images, which means that a single contact with a large image can
prevent successful contacts sync with some servers. The contacts
scaling allows to prevent these problems.
! Note that when scaling contact images is enabled, the contact image on your iOS device will not be scaled down directly; only the image sent out is a scaled down version. Still,
you might loose the full resolution of the contacts image
eventually, because only the scaled down version is stored in
your server. So when a contact is modified server-side, or you
use "reload device" to restore all your contacts from the server,
the contact will have the scaled down version of the image from then on.
• Contacts source selection: Starting with iOS 4.0, there can be
more than one source for contacts. Before iOS 4, there was a single local address book. With iOS 4, external services such as Exchange, Google, CardDAV can be included as well. With iOS5,
iCloud has been added to the possible sources.
! With the upgrade to iOS5, most users automatically got a
iCloud address book in addition to the local one. So it is important to check the contacts settings such that the right
contacts are actually selected.
Where
to store new entries: When new contacts are synced from
•
a SyncML server which do not have a category label that matches
one of the contact source names, the SyncML client needs to
know which contact source to send these to.
! Note that this contact source must be one of the contact sources selected for synchronisation.
Otherwise, sync attempts will fail with the "No data: check settings!" error message.
!
© 2010-2012 by plan44.ch, CH Zürich, Switzerland - www.plan44.ch
SyncML Synchronisation for iOS - Page 9/26
• Date Range Limits: For Calendar entries, you can limit the date
range of entries that are synchronized. If activated, only calendar
entries not older than the number of days set with "Past days" and
not more in the future than set with "Future days" will be synchronized.
! Not all SyncML servers support the date range option. In case
you experience problems synchronizing calendar, try disabling
the limit option.
! The date range option is conceptually a special kind of "server
filter" and is also transmitted to the server as such (depending
on the SyncML version). So in case you are also using server
filters and this limit option please be aware that these will be combined. See the separate chapter on filtering for details.
• Calendars to include in sync: For the SyncML PRO app, you can
select which of the iPhone's calendars should be included in sync.
You can either select to include all local calendars (e.g. calendars
created and synchronized via iTunes and iCal on the Mac) or individually select the calendars you want to synchronize.
! Note that only calendars which can be modified are available
for sync (so read-only subscribed calendars will not appear in
the selection menu).
• Allow creating new calendars from server categories in: This
option appears only on iOS5 and newer. When new entries are
synced from a SyncML server which have no category label that
matches one of the calendar labels and this option is configured,
SyncML PRO will create a new calendar in the specified calendar
account. If this option is disabled, the "store new entries in" setting (see below) will apply.
• Store new entries in: When new entries are synced from a SyncML server which do not have a category label that matches one of the calendar names, and "allow creating new calendars…" setting (see
above) is off, the SyncML client uses the calendar specified to store these entries.
! Note that this calendar must be one of the calendars selected for synchronisation. Otherwise,
sync attempts will fail with the "No data: check settings!" error message.
Include
Tags: For tasks entries, this switch allows to include the tags
•
from the Tasks+Cal+Sync application as specially labelled task
items. This is useful to back up to a SyncML server or when synchronizing with another iPhone with Tasks+Cal+Sync installed.
! After changing this switch, you should do a complete refresh in
either direction ("reload server" or "reload device") to avoid
mixing tags and tasks.
!
© 2010-2012 by plan44.ch, CH Zürich, Switzerland - www.plan44.ch
SyncML Synchronisation for iOS - Page 10/26
18. Synchronizing
When setup is complete, return to the root level "Preferences"
screen and press the "Sync now" button. (For SyncML LITE, switch to
the "Synchronize" screen and press the "Start Synchronisation"
button).
"Sync now" button starts a sync for all accounts that
! The
are configured for sync (see previous chapter). Usually
there is only one account configured, but if you have multiple accounts, you can also start a sync for single accounts by
opening the account's settings and use the "Sync this account
now" button.
This will start a synchronisation with the SyncML server as configured:
• The device will open a connection to communicate with the
SyncML server. It uses the system wide network settings (WiFi,
EDGE or 3G, depending on your iOS device and network availability).
! If you get "connection error" messages, this means that the
client cannot connect to the server. Please make sure you
have network connectivity (WiFi hotspot or cellular network coverage).
! If you get "No SyncML Response" message, the client
can connect to a server machine, but the server does not
appear to be a SyncML server. Usually, this happens when
your SyncML server URL is not correctly specified in the settings - please check for typos and verify with the provider of
the SyncML server that you are using the correct URL. For
most services, the SyncML URL is not the same as the URL
you can use in a web browser to access the server!
Data
will be synchronized. The main screen will show some pro•
gress information, such as how many items are sent and received.
! For each data type, synchronisation starts with a "checking"
phase. This is needed to find changes, additions and deletions made since the last sync and will always go through all
items in your databases. Note however that during "checking" phase, no data is transferred to the server. So even if
"checking" count might be high and take some time - "checking" does not cause any network
traffic (or cost).
• Finally, when sync is complete, the progress information bar disappears automatically. In case of a
problem, the progress information bar remains visible until you tap it. To see details about past synchronisations, have a look at the "Sync Log" screen, which can be opened from the preferences.
!
!
!
!
On devices with iOS 4.0 and multitasking (i.e. iPhone 3GS, iPhone 4/4S) and later, you can exit the
app while synchronisation is still running and it will complete in the background. In older iPhone OS
versions, no background processing is possible so leaving the app will abort the synchronisation.
In Tasks+Cal+Sync and SyncML PRO you can enable more than one SyncML account to be synchronized.
In Tasks+Cal+Sync and SyncML PRO, the preferences button reverts to a activity indicator (spinning
wheel) while a sync is in progress. It can be tapped to show or hide the sync progress information
bar, however, preferences are not accessible during sync.
© 2010-2012 by plan44.ch, CH Zürich, Switzerland - www.plan44.ch
SyncML Synchronisation for iOS - Page 11/26
Viewing the Sync logs
After a completed (or failed) synchronisation, you can view its
statistics by going to Preferences and choosing "Sync Log" (in
SyncML LITE, just switch the "Log" screen)
This will show the 30 most recent log entries, newest at the top.
Using the Trash can button, you can delete all log entries.
! The log shows a separate entry for each datatype synchronized. So if you have enabled sync for "Contacts" and "Calendar" in the settings and start a sync, you will get 2 new
entries in the log.
! The number of bytes shown are net content only (your data) but note that the total amount of bytes transferred over the
network is always higher as there is some protocol overhead
(8 KBytes sent and received extra in a typical session).
! The "Rejected" counts show how many records that were
sent to the server or received by the client were rejected due
to an error. Usually, these should be zero. In some cases, a
server might not be able to store a certain record, for example due to some particular properties like a large note or
photo, and therefore will reject the item. The client will try
re-sending the item in the next sync.
Viewing debug logs
There is another type of logs, the technical SyncML log files that can be useful to diagnose problems.
When a sync is run with "Log next sync" switch set to on in the server settings, the SyncML engine will
produce extended logs during sync and will offer to send these to plan44.ch.
don't just send logs - in order to diagnose problems please also send an email describing
! Please
the problem, and let us know the date and time of the sync attempts so we can locate the logs.
Starting with Tasks+Cal+Sync 2.0.1, you can also use the built-in web server to view the logs from a
desktop computer's browser: Just choose "Keep for later" instead of "Yes, send logs", then activate the
built-in SyncML server and browse it from the desktop computer (in Safari, you can find it via Bonjour,
otherwise use the URL displayed on the server screen). Both iPhone and desktop computer must be
logged into the same Wi-Fi network for that.
If you are using Tasks+Cal+Sync as a SyncML server, you can also have the server create logs by setting
the "Log server session" switch to ON on the server screen. These logs can be viewed in the same way as
described above (browse the URL displayed on the server screen from a desktop browser).
!
© 2010-2012 by plan44.ch, CH Zürich, Switzerland - www.plan44.ch
SyncML Synchronisation for iOS - Page 12/26
19. AutoSync
!
Since version 3.0, Tasks+Cal+Sync and SyncML PRO have an "autosync" option. Please note however that Apple still does not allow sync to happen entirely in the background.
Therefore, in order to have the apps sync automatically, they must be opened from time to time
to allow the sync to happen.
While using Tasks+Cal+Sync at all implies it will be opened freqently (to access tasks and calendar),
this is not automatically the case for SyncML PRO, because traditionally, SyncML PRO was a synconly-app and accessing the calendar was done using Apple's calendar app or other third party
apps.
That's why SyncML PRO now has inherited the calendar views from Tasks+Cal. With this, SyncML
PRO can be used as calendar app and this will guarantee it is opened many times during a day and
thus autosync has many opportunities to occur. You can still use other calendar apps in parallel, but
if you want autosync, make sure you adopt the habit of using SyncML PRO regularily.
Setting up Autosync
To enable Autosync, just go to preferences, SyncML Settings and set the switch "Automatically sync" to
on.
Three additional options will appear:
• when app is entered: This sets how often autosync occurs maximally when the app is opened or re-opened. This is to prevent a
lot of syncinc when quickly opening and hiding the app in sequence, which often happens when switching between apps.
! Note that this does not define how often the autosync
happens in general. Apple does not allow that the app
would sync in a fixed interval in background. So the sync can
happen only when opening or closing (see below) the app,
and this setting can be used to prevent that to happen too
often. You can also prevent autosync at app opening completely by choosing "no" for this setting.
• when the app is left with local changes: This sets if and how often maximally autosync occurs when the app is closed (meaning,
made disappear from view, like pressing the home button or
switching to another app).
! Sync at close is for commiting changes to the server you might have made to your data (unlike
sync at open, which is meant to make sure you get the most recent data from your SyncML server
whenever you open the calendar or tasks).
Therefore sync at close only runs if you have actually made any changes since the last sync. So
using the "always" setting here does not cause a lot of syncs. You can also prevent autosync at
app closing completely by choosing "no" for this setting.
• only when WiFi is available: If you don't want sync to happen over 3G or Edge, but only in WiFi networks, enable this option. This simply suppresses any autosync activity when there is no WiFi available.
!
!
!
!
Autosync only syncs SyncML accounts which have "Sync this
account in autosync and global sync" set to on.
Autosync does not happen for first syncs (for safety reasons).
You need to do at least one successful manual sync before
autosync will happen.
If one of the accounts included in autosync fails to complete,
the remaining accounts will not be synced. Again, this is for
safety reasons, to avoid messing up other accounts after a
failed sync with one account.
© 2010-2012 by plan44.ch, CH Zürich, Switzerland - www.plan44.ch
SyncML Synchronisation for iOS - Page 13/26
20. Suspend & Resume
A synchronisation can be interrupted, either manually or for external reasons e.g. when the network
connection breaks. In SyncML versions before 1.2, this caused the session to abort, and a subsequent
sync had to repeat the entire sync from start, and sometimes even required a slow sync to recover. With
large data sets, this could be very annoying.
Fortunately, SyncML DS 1.2 has a now a solution for this named Suspend & Resume. This means that an
interrupted sync will simply be resumed in the next attempt - at the point it was interrupted.
So if your sync aborts for whatever reason, you can resume it by simply pressing the sync button again.
& Resume is fully supported in the SyncML engine. But it can work only with servers that
! Suspend
support SyncML DS Version 1.2 and actually have the resume feature implemented. For example, libsynthesis based servers fully supports Suspend&Resume.
suspend a sync manually (for example because you need to
! To
leave WiFi coverage with an iPod touch while it is in the middle
of a sync, press the "Stop" button once. This causes a "soft"
suspend - the client tells the server it wants to suspend and
waits for the server to acknowledge the suspend. This this
takes some time until the sync actually stops. During this time,
the progess text changes to "Suspending...".
If you now press the stop button a second time, this will cause
a "hard" suspend to occur - the client then immediately stops the sync (but as it needs to save
some data to be able to resume, this might still take a few seconds). This is quite similar to what
happens when suddenly the network connection to the server breaks. Even in this case, SyncML 1.2
can resume the session later. But if you can avoid "hard" suspend, using "soft" suspend is the better choice for manually aborting a sync session.
you want to explicitly prevent that the next sync resumes a previously aborted or suspended
! Ifsync,
got to the sync mode setting and tap it to show the choices. If you hit "save" in the sync
mode choices (event if you don't change the sync mode), this will clear the suspended sync information and ensures that the next sync will start at the beginning with no attempt to resume.
21. Using multiple SyncML accounts
Tasks+Cal+Sync and SyncML PRO allow creating multiple SyncML accounts. This is useful to synchronize
a iPhone with more than one server or service. For example, you might want to backup your data to a
private server, but still be able to sync with your office server. This is possible by setting up more than one
SyncML account in the preferences.
accounts are for using more than one SyncML server.
! SyncML
Please don't create multiple SyncML accounts for the same
server/user combination - this will inevitably cause troubles
like duplicates or deleted items.
Server
With the possibility of multiple SyncML accounts, it becomes
! also possible to create a so-called circular sync situation,
which must be avoided under all circumstances because a
circular sync can severely mess up your data. Please always
make sure you have one single sync path between any two
participants in a sync scenario, and take into account other
means of synchronisation, not just SyncML
users of iCloud and SyncML PRO should be
! Especially
aware that their calendar is synchronized to other devices
Server
and computers automatically, and make sure SyncML does
not try to sync two devices/computers that are already kept
in sync by iCloud, directly or indirectly.
!
© 2010-2012 by plan44.ch, CH Zürich, Switzerland - www.plan44.ch
SyncML Synchronisation for iOS - Page 14/26
Creating new SyncML accounts
To create a new SyncML account, open Preferences and select
"SyncML Settings". Under "SyncML Accounts" use the "Add new
account..." button to create a new SyncML account. Alternatively,
you can select an existing SyncML account and use the "Duplicate
account…" button to create a new account with the same settings.
an account for the same server/user combination is
! Duplicating
not recommended (see above), therefore a warning appears
and if you choose to duplicate the account, the duplicate will
have the user name cleared to avoid accidental use of the
same user name.
Synchronizing accounts
Each SyncML account has a "Sync this account now" button to start a
synchronisation with only this account.
To automatically include a SyncML account for autosync or global
sync (when you press the "Sync now" button in the root level of the
preferences), set the "Sync this account in autosync and global sync"
switch to on.
Deleting a SyncML account
To delete a profile, scroll down in the SyncML Account settings
screen and press the red "Delete Account..." button.
a profile does not delete any data from the associ! Deleting
ated server or the device, but only the sync settings.
!
© 2010-2012 by plan44.ch, CH Zürich, Switzerland - www.plan44.ch
SyncML Synchronisation for iOS - Page 15/26
22. Using the SyncML server
Until Tasks+Cal+Sync and SyncML PRO, mobile devices could only
play the client role in SyncML. For the first time now Tasks+Cal+Sync
and SyncML PRO allow your iOS devices to act as a SyncML server,
which means that other devices can directly sync with it in the local
Wi-Fi network without needing a SyncML service in the internet. This
opens completely new sync scenarios, which were not possible
before.
To make the iOS device act as a server, simply choose "Start SyncML
Server" in the preferences screen.
This opens the server status screen and starts the SyncML server
immediately.
long as the server screen is open, SyncML clients in the
! As
local network (and even the internet if the local network
has no firewall) can potentially access the iPhone server. So
please make sure to activate the server only in trustworthy environments.
Now the iPhone based SyncML server can be accessed from other
SyncML clients (other iPhones or any other SyncML equipped device,
like many mobile phones, PDAs, Netbooks etc.)
To configure a client for accessing the iPhone server, you need to
know the following parameters:
• The SyncML server URL. This is shown right below the title on the
server status screen (like http://192.168.1.77:8888). For most
SyncML phone clients, you need to enter this URL manually - for
Bonjour capable clients (like plan44.ch's SyncML apps) you can
select the iPhone server from a list by name (like iPhone 3G Tasks+Cal SyncML Server)
• The SyncML server login (username and password). For this local
SyncML server, both username and password are "iphone"
• The database names. The names of the different data types on
the iPhone are:
• "contacts" for the iPhone address book contacts
• "events" for the calendar in Tasks+Cal+Sync or the iOS calendar in SyncML PRO
• "tasks" for the tasks list in Tasks+Cal+Sync
• "taggedtodo" for the tasks (to-do) list including the tags with all attributes and hierarchy. This usually makes sense only when the client is another Tasks+Cal+Sync equipped iOS device.
!
© 2010-2012 by plan44.ch, CH Zürich, Switzerland - www.plan44.ch
SyncML Synchronisation for iOS - Page 16/26
Synchronizing two iOS devices
You can use the built-in server to keep two (or more) iPhones' or iPad's contacts, calendar and task data
in sync without any external server or service required:
Tasks+Cal+Sync or
SyncML PRO App
running as
SyncML Server
Tasks+Cal+Sync or
SyncML PRO App
running as
SyncML Client
To setup this kind of synchronisation, perform the following steps:
1. Start the SyncML server from within Tasks+Cal+Sync or SyncML PRO in one of the iOS devices.
! For safety reasons, the SyncML server does not allow clients to modify data by default. If you
want to update data on the iPhone acting as server, change the "Allow changes to local data"
switch to "ON".
2. Setup the other iOS device sync settings as follows (you might want to create a new profile for that,
see "Using multiple SyncML accounts" chapter)
• In the server settings, use the "Bonjour" option to choose the other iOS device's server (make
sure both devices are logged into the same Wi-Fi network).
• Enter "iphone" as user name and also "iphone" as password.
• In the settings for the different data types, make sure the path for the address book contacts is
"contacts", for the calendar "events" and for the tasks/to-dos "taggedtodo". The latter is important as it selects not only tasks, but also the tags with all attributes.
• For the tasks, make sure the "Include Tags" switch is set to on.
3. Now you are ready to sync (like with any other SyncML server)
!
!
After initial sync, don't switch client and server roles! Always
use the same device as a server. Otherwise, the sync mechanism cannot track the changes correctly and duplicates are
likely to occur.
Never create a so called "circular sync" - this means if you
sync device A to device B, and device A to a server, never
sync device B to the same server as well!
Server
!
© 2010-2012 by plan44.ch, CH Zürich, Switzerland - www.plan44.ch
SyncML Synchronisation for iOS - Page 17/26
Synchronizing other SyncML devices
The SyncML server built into Tasks+Cal+Sync and SyncML PRO is fully standards compliant, so it will work
with any other SyncML enabled device which also conforms to the SyncML standard, like many
featurephones and smartphones from nearly all vendors.
Tasks+Cal+Sync or
SyncML PRO App
running as
SyncML Server
Any other SycML
and WiFi enabled
device
To setup sync with a SyncML enabled phone (or other device, like a Linux powered netbook with
SyncEvolution client for example):
1. Start the SyncML server from within Tasks+Cal+Sync or SyncML PRO in the iOS device.
! For safety reasons, the iOS SyncML server does not allow clients to modify data by default. If you
want to update data on the iOS device acting as server, change the "Allow changes to local
data" switch to "ON".
2. Configure the following settings in the device you want to sync
• Make sure the device can access the same Wi-Fi network as the iPhone.
• As SyncML server URL, enter the URL displayed on the server status screen of the iPhone app
(something like http://192.168.1.42:8888)
• Enter "iphone" as user name and also "iphone" as password.
• In the settings for the different data types, make sure the path for the address book contacts is
"contacts", for the calendar "events" and for the tasks "tasks".
3. Now you are ready to sync the device (like you would sync it with
any other SyncML server).
create a so called "circular sync" - this means if you
! Never
sync the iOS device with another phone, and also sync the
iOS device to a server, never sync the other phone to the
same server as well!
Server
!
© 2010-2012 by plan44.ch, CH Zürich, Switzerland - www.plan44.ch
SyncML Synchronisation for iOS - Page 18/26
23. Using Filters
!
Be warned - filters are a rather technical topic. Filters can help to set up advanced sync scenarios,
but can also cause hard to diagnose problems if not used with care and some insight into what is
actually happening during synchronisation. The following first describes the filter basics.
you are looking for some examples of simple filter usage you can use as-is without diving into
! Iftechnical
details, please see the example section at the end of this chapter.
Despite the warning above, the basic mechanism behind filters is quite simple: Filters restrict the data
items involved in a synchronisation according to certain criteria. Because there is always a server and a
client which both contain data, both can be potentially filtered. This is why there's a "Server Filter" and a
"Client Filter" under "Filter Conditions".
Server Filters
A server filter is a condition which restricts the data to be synchronized on the server to a subset of the
entire server data available. A common case is restricting to a certain category or date range. Often, the
reason to use server filters is to reduce the amount of data transferred to and kept on the mobile.
filters are entered in the client, but then transmitted as-is to the server. As long as the filter
! Server
term is syntactically correct, the server should be able to apply it. However, not many servers are
capable of filtering at all (but the Tasks+Cal+Sync and SyncML PRO servers of course do support
them!), or only with restrictions. Please check with your server provider if and what filter features
are supported.
"Date Range Limits" in the calendar settings is also a server filter with a more convenient user
! The
interface. It tells the server to filter the calendar by date. Not every server actually supports date
ranges. So if you experience sync errors with calendar, make sure to switch off the "Limit" switch,
as missing server support for date range could be the problem.
Client Filters
A client filter is a condition which restricts which data present in the iOS device is actually included in a
synchronisation with a server. It allows to expose only a subset of what you have on the iPhone/iPad/
iPod to your SyncML server. For example, you might want to synchronize with your office SyncML server,
but exclude the private part of your contacts and calendar from being ever transferred to the office
server. Client filters are applied locally in the iPhone application where you define them.
Filter Syntax
The filter syntax as defined by the SyncML standard with a few extensions is exposed as is (with the
exception of the "Date Range Limits" filter). We took this decision because filters are not a common
feature of many SyncML implementations (altough the standard defines them for a long time now).
The disadvantage is that you'll need to handle a slightly techie-style way to enter filters (funny symbol
characters, no arbitrary spacing allowed etc.).
The advantage is that no unexpected wizardry happens between what you enter and what your server
will see. So if you get instructions from your server provider what filter expressions are possible, you can
type them in exactly that way and it will work.
If you are interested in the full SyncML filter syntax (also called TAF, Target Address Filter in older SyncML
versions), you can look it up in the technical manual for libsynthesis which is available as PDF in "doc/
SySync_config_reference.pdf" of the open source repository for libsynthesis on gitorious, chapter 7
"Filters", especially 7.2. The following description is a bit simplified to better suit everyday filtering
needs.
Filter expressions look like:
FIELDNAME=value
Where FIELDNAME is a the criteria you want to test, and value is the literal value you want to compare.
The equal sign is the operator which expresses how to compare.
!
© 2010-2012 by plan44.ch, CH Zürich, Switzerland - www.plan44.ch
SyncML Synchronisation for iOS - Page 19/26
For client filters, and for some servers, the commonly used operator notation (=, <>, >, <, >= etc.) can be
used. However, the SyncML standard uses a special way to express operators as shown in the following
table:
client filter
server filter
case insensitive
client
filter
case insensitive
server
filter
meaning
=
&EQ;
^=
&iEQ;
equal
<>
&NE;
^<>
&iNE;
not equal
%
&CON;
^%
&iCON;
contains
$
&NCON;
^$
&iNCON;
does not contain
>
&GT;
^>
&iGT;
greater than
>=
&GE;
^>=
&iGE;
greater or equal
<
&LT;
^<
&iLT;
less than
<=
&LE;
^<=
&iLE;
less or equal
So for maximum SyncML conformance (= maximum chance a server will understand the filter) the
example filter, when used as server filter should be written as:
FIELDNAME&EQ;value
The possible FIELDNAMEs and values allowed depends on the data format and the server capabilities.
The following table shows some commonly supported fields:
FIELDNAME
possible Values
used for
CATEGORIES
category, tag, group names
all datatypes that support
categories
GROUP
same as CATEGORIES
contacts
FAMILY
family (last) name
contacts
GIVEN
first name
contacts
DUE
due date
tasks
STATUS
status string (COMPLETED, IN PROGRESS
etc.) or numeric value like for example 0=open
1=completed - depends on implementation.
tasks
CLASS
classification string (PUBLIC, PRIVATE,
CONFIDENTIAL) or numeric value like for
example 0=public, 1=private, 2=confidential)
all datatypes that support
classification
The values are written as is, with no quotes or other special chars:
GROUP=Private
or for a server filter
GROUP&EQ;Private
!
© 2010-2012 by plan44.ch, CH Zürich, Switzerland - www.plan44.ch
SyncML Synchronisation for iOS - Page 20/26
To express "has no value" or "has value", the following notation must be used:
client filter
server filter
meaning
FIELD*=E
FIELD&EQ;&NULL;
field is empty (no value)
FIELD*<>E
FIELD&NE;&NULL;
field is not empty (has value)
For more complex filter conditions, logical operators can be used:
client filter
server filter
meaning
&
&AND; or &amp;
logical AND
|
&OR;
logical OR
These can be used to chain multiple conditions like:
FIELD1=Value1|FIELD2=Value2
Filter usage examples
Client filter by CATEGORY to keep private data away from
corporate server
!
Note that in SyncML PRO, there is a special option to select only
some calendars for sync, so you don't need to use filters unless
you have a more complicated scenario.
that for contacts sync under iOS 4 and later, there is a spe! Note
cial option to choose which of potentially multiple address books
are to be synchronized. You might still want to use filters to restrict the sync to only a certain group within one of the address
books like shown in this example.
This is a common scenario. You have business contacts and calendar
stored in a a corporate SyncML server, and you sync it with your iOS
device. But you also want to use Tasks+Cal for your private calendaring
needs. Client filters provide a elegant solution to that.
Use two different tags in Tasks+Cal to mark "Home" and "Work"
entries on the iPhone. You can use the predefined green and blue tags,
or any of your own choice (name, color).
If you include contacts sync, create a contact group (named "Work" in
this example) to put your business contacts into. Note that at the time
of writing iOS does not allow you to create contact groups directly; however, you don't need to do that
because when you set up the filter like described here, the SyncML client will create the "Work" group as
soon as it receives contacts from the server.
Now use a client filter to include only those entries having the "Work" tag or are in the "Work" contacts
group to be included in sync:
CATEGORIES:^%Work
"%" means contains and "^" means case insensitive (see paragraph "Filter Syntax" above).
So this tests for "Work" to be contained in CATEGORIES. Note that we don't use "=" (equals), because a
entry might have more than one tag or group (category) attached.
When synchronizing now, only those entries that are marked "Work" will be synchronized - all others will
be omitted from the sync and will never be sent to the server.
!
© 2010-2012 by plan44.ch, CH Zürich, Switzerland - www.plan44.ch
SyncML Synchronisation for iOS - Page 21/26
!
!
Note the colon in the filter expression. It tells the sync engine that all entries coming from the
server must get the "Work" category assigned in case it isn't present already. This is very important because the server might not support categories/tags at all, so incoming entries might not
have a category at all. The colon ensures they will be put into "Work", so in the next sync, the new
record will match the filter condition. Without this, new records from the server would fall out of
the sync set.
Note that you need to enter the filter for the contacts and calendars separately, if you want the
"work only" restriction for both.
Server filter by CATEGORY to synchronize only certain calendars
If you have a server which shows multiple calendars by assigning them different categories, you might
want only some calendars to sync to the iPhone.
Assume the server has a calendar for each member of the family, plus one called "common" for events all
need to know. Using a filter like:
CATEGORIES&iCON;Common&OR;CATEGORIES&iCON;Joe
would sync all entries from the "common" calendar plus those from from "Joe".
If the server only supports one category per entry, the "contains" condition might not work as expected,
so you can also try:
CATEGORIES&EQ;Common&OR;CATEGORIES&EQ;Joe
!
The built-in servers of Tasks+Cal+Sync and SyncML PRO (see Using the SyncML Server) fully support filters. To specifiy server filters with a phone that does not have a settings option for it, just
include it in the server path as follows:
events?/fi(filter_expression_here)
!
© 2010-2012 by plan44.ch, CH Zürich, Switzerland - www.plan44.ch
SyncML Synchronisation for iOS - Page 22/26
24. Troubleshooting
!
?
This section gives some information about common problems that might occur
with SyncML synchronisation.
In addition, especially for more specific problems like compatibility with certain
environments etc., please always consult the plan44.ch support & FAQ page at
http://www.plan44.ch/support.php first.
Basically, if your connection to the internet is stable, synchronization should be no
problem. Just start a synchronization whenever you want to update your data.
Still, there are a few possible problems, many caused by interrupted sync sessions.
• SyncML PRO does not synchronize all calendar fields: SyncML PRO is restricted to what Apple's calendar API allows, which unfortunately is not full access to all aspects of the calendars. In particular,
meeting attendees cannot be synchronized.
! The separate calendar in Tasks+Cal+Sync was specially built to cover the features and fields
available in SyncML, so Tasks+Cal+Sync does support meeting attendee sync (and also a number
of other fields not available or accessible in the Apple iOS calendars).
• Synchronization aborts with error code: See error code explanation below for details.
• Strange behavior in general: If it seems to you that your data is not synchronized as it should, it is a
good thing to make a fresh start. SyncML is an incremental method - which means that the things that
happened in the past synchronizations influence what will happen in future synchronizations. This is a
good thing (saves a lot of time) under normal circumstances, but sometimes this dependency on the
past is replicating old problems. To make a new starting point, make sure you have all recent data
stored on the server and then set the sync mode to "reload device". This will cut all dependencies on
past synchronization problems.
• Sync always takes a long time: Most probably, the previous synchronization did not complete successfully, so a slow sync occurs. If this happens all the time, this indicates either a very poor quality of
the internet connection or a compatibility problem with the server used.
! If you need to report the problem to the SyncML service provider, please include date and exact
time of the failing sync attempt(s), username, and also the error message displayed at the end of
the synchronization in your report. Without this information, it is difficult for the service provider
to track down the problem.
• Duplicates: In some cases you might notice that some of your data gets duplicated. If this happens
only for a few contacts, this is perfectly normal, it shows that a record has been modified on your device and on the server in parallel. In order not to loose either modification, the server has kept both
versions of the record so you can decide which version is the "right" one. Just delete the version that
is obsolete on the device or on the server.
If you encounter a lot of duplicates without having modified anything, this indicates a compatibility
problem with the server used.
Please note that if you cannot successfully complete a synchronization, the probability of getting duplicates is slightly higher as there might have been problems in the previous synchronization.
• Missing fields: If you think that you don't get all data stored on the server or vice versa, not all server
fields get update with data you have on your mobile device - please consider that this might be perfectly normal. Why? Unlike proprietary synchronization technologies like iTunes and MobileMe,
SyncML is an open standard which allows synchronizing any compliant device with any compliant
server. However, not all servers and not all devices support the same set of data fields. A simple mobile phone is likely to support only telephone numbers, but no street address. Or some devices are
restricted to one address per contact, while others support separate work and private addresses. This
might be confusing on the first sight, but a properly set-up server will be smart enough to preserve
your data even if there is no exact 1:1 mapping possible.
Error messages and error codes
Configuration missing or no datastore enabled
This message is shown when trying to start a sync session while missing configuration information.
The reason for this message could be missing server URL, missing server paths of the individual data
stores, no database selected for sync at all, or database to sync with is not available on the device (for
example, corrupted contacts or calendar database on the device)
!
© 2010-2012 by plan44.ch, CH Zürich, Switzerland - www.plan44.ch
SyncML Synchronisation for iOS - Page 23/26
No data: check settings!?
This message is shown when no suitable contact sources or calendars (SyncML PRO) are selected, and/
or no calendar/contact source is selected for writing new entries to which is also part of the synchronisation. Please check in the settings, under contacts or calendar that at least one calendar or contact
source is selected, and that the place where new entries go to is included in the synchronisation.
Network error - please check internet connection
This means that the client cannot establish a connection to the server.
If this error occurs right after starting the synchronization, either the URL entered for the server is
wrong (no such server exists) or there is a basic networking problem.
If this error occurs in the middle of a synchronization, this is most likely an intermittent problem.
Invalid data from server (wrong URL?)
This is usually caused by an incorrect SyncML Server URL entered in the settings. It means that the
SyncML client can connect the server, but does not get a SyncML response as it should, but something
different, like a error message web page.
Access denied
This message is shown when the client cannot login with the server.
Usually, the reason is an invalid user name and/or password; Please check the settings and possibly reenter the password (note that depending on the server it usually is case sensitive).
Aborted by user
The synchronization was manually aborted by the user.
! If the server supports SyncML Version 1.2, aborted synchronizations can be resumed simply by
starting sync again. See Chapter "Suspend & Resume" for details.
Server database not found
A database (contacts, events, tasks…) was not found on the server.
Usually, this means that the database does not exist on the server side or has a different name than
what was entered as "server path" in the settings (see "Data Type Settings" paragraph in the "Configuration" chapter).
Local Database error
Some problem occurred accessing the device’s databases.
This also indicates some internal database problem, usually caused by corrupted data on the device.
Server Database Error
The server reported a problem accessing its data.
This usually indicates a server problem - please check with your SyncML service provider if you repeatedly get this message.
Server busy - try later
The SyncML server is not ready for processing a synchronisation right now. Just wait a few minutes
and try again.
Error Code=<number>
Some rarely occurring error codes do not have a text message, but are shown like this.
Some codes you might encounter are:
101
Server is busy
400
Bad request (usually a server compatibility problem)
405
Command not allowed (compatibility problem)
408
Timeout
412
Incomplete command (compatibility problem)
!
© 2010-2012 by plan44.ch, CH Zürich, Switzerland - www.plan44.ch
SyncML Synchronisation for iOS - Page 24/26
413
415
417
421
422
424
426
500
501
503
511
512
520
10xxx
20001
20002
20003
20004
20005
20006
20007
20008
20009
20010
20011
20012
20013
20014
20015
20016
20017
20018
20019
20020
20021
20022
20023
20025
!
Too large - the server cannot process some data sent by the client because it is too large. If
this happens when synchronizing contacts, it might be caused by large photos - try reducing
the photo size by using the "scale contact images" option.
Unsupported media type or format (usually this means that the server does not support this
type of data - for example synchronizing task to a server that has no support for tasks).
Retry later. This indicates some sort of temporary failure - retrying after a while might solve
the problem.
Unknown search grammar (server compatibility problem, usually with filters)
Bad CGI script. This might indicate that the server does not understand the special options
like date range restrictions or filters (see "Special Options" in the "SyncML Configuration"
chapter and the "Filters" chapter). Try turning off these options and remove server filter expressions if you have set any.
Size mismatch. This indicates a transmission problem of a large object, possibly caused by a
temporary network problem. Retrying (resuming) the session might help.
Partial item not accepted.
Command failed (usually a server malfunction of some kind or a SyncML compatibility problem)
Not implemented (compatibility problem)
Service unavailable. This usually indicates a temporary problem.
! Some servers send this error code when a session was interrupted with error only a
short time ago, and the server is not ready yet to start another session. Please wait a
few minutes and try to run the session again.
Server error (some general server error)
Synchronisation failed (generally failed due to some server error)
Server database full (the server has no room to store more data)
This has the same meaning like xxx, but indicates that the problem has occurred locally in
the client rather than in the server.
Bad or unknown transport protocol
Fatal problem with SyncML encoder/decoder
Cannot open communication
Cannot send data
Cannot receive data
Bad content type (message received with an unknown MIME-type)
Error processing incoming SyncML message (for example invalid XML or WBXML formatting)
Cannot close communication
Transport layer authorisation (e.g. HTTP auth) failed
Error parsing XML config file
Error reading config file
No configuration found at all, or not enough for requested operation (client) - you might
have forgotten to enter username or password.
Config file could not be found
License expired or no license found
Internal fatal error
Bad handle
Session aborted by user
Invalid license
Limited trial version
Connection timeout
Connection SSL certificate expired
Connection SSL certificate invalid
incomplete sync session (some datastores failed, some completed)
Out of memory
© 2010-2012 by plan44.ch, CH Zürich, Switzerland - www.plan44.ch
SyncML Synchronisation for iOS - Page 25/26
20026
20027
20028
20029
20030
20031
Connection impossible (e.g. no network available)
Establishing connection failed (e.g. network layer login failure)
element is already installed
this build is too new for this license (need upgrading license)
function not implemented
this license code is valid, but not for this product (e.g. STD license used in PRO product, or
client license in server product)
20032 Explicitly suspended by user
20033 this build is too old for this SDK/plugin
20034 unknown subsystem
20036 local datastore not ready
20037 session should be restarted from scratch
20038 internal pipe communication problem
20039 buffer too small for requested value
20040 value truncated to fit into field
20041 bad parameter
20042 out of range
20043 external transport failure (no details known in engine)
20044 class not registered
20500..20599
These represent SIG_xxx codes in Linux and Mac OS X versions of the SyncML engine.
Unexpected SIG_xxx will generate a error code of 20500+signal_code.
20998 Internal exception (client encountered an internal exception - a possible reason could be extreme shortage of memory in the device)
20999 Undefined internal error
21000...21999
Database plugin module specific error codes
!
© 2010-2012 by plan44.ch, CH Zürich, Switzerland - www.plan44.ch
SyncML Synchronisation for iOS - Page 26/26
Reporting problems
!
Please report problems via the plan44.ch support & FAQ page at
http://www.plan44.ch/support.php. This page automatically looks up keywords as you type in your
support request and suggests matching FAQ entries which might provide an immediate solution to
your problem. If not, you have the option to send your request to plan44.ch directly.
most cases, sync problems are specific to a SyncML service provider's environment. Therefore,
! In
please first ask your service provider in case of problems and mention that you use plan44.ch client
software. The service provider will then be able to analyze the problem and will contact us directly
in case they think the problem is in our client software.
reporting a bug or a problem (to the SyncML service provider or to us), please collect the
! Before
following data:
• Version of the software (please select the "About..." screen to find out the exact version number of the application (like 2.0.0) and the SyncML engine (like 3.4.0.1)
• Type of device (iPod, iPad, iPhone, what generation).
• URL of the server you are using to synchronize with.
• Error messages shown by the software.
• As the problem needs to be tracked down together with the SyncML service provider, please
include your user name you used to login to the SyncML service and the exact date and time
when you tried to synchronize.
• If possible, please re-run a sync which shows the problem with "Log next sync" switch in server
settings enabled, and allow logs to be sent to plan44.ch. Please note the date and time of the
test sync and report it together with your problem report by email, so we can locate the logs
you sent. Just sending logs without a problem report via our support page does not trigger
any action on our part.
Please use the plan44.ch support & FAQ page at http://www.plan44.ch/support.php for reporting
problems. Suggestions or ideas for enhancing the product are also welcome!
!
© 2010-2012 by plan44.ch, CH Zürich, Switzerland - www.plan44.ch
Download PDF