Pimlical Android Help

Synchronizing to Other Devices

Pimlical supports two types of calendars:

As a user, you can choose to use either one or both types of calendar. The local calendar is always more secure and more private, since you have total control over where the data is displayed and synced to. The Android calendars provide a simpler way of sharing calendars with other devices connected to the internet (cloud-based servers), but as a user you have less control over the information as it is stored on Google's servers and is synced using Google's software. With AutoSync, the local calendar can now be shared easily with multiple devices/desktops via a cloud-based server, but many users may still prefer to continue using DirectSync which provides an off-cloud sync solution and a higher degree of security.

In general, Pimlical/Android and Pimlical/Desktop should match on the MAJOR version (i.e. if you are using V-4.1.x of P/A, you should be using V-4.x of P/D).

Contacts and Memos

Pimlical also supports a local contacts and a local memos database. These databases can be synced to other devices using AutoSync or DirectSync. Pimlical can also utilize the built-in Android contacts database for linking purposes. The Android contacts database is completely separate from Pimlical's contacts database and is synced to Gmail contacts via Google's sync software.

Android Calendar Sync

If Pimlical is using Android calendars (you select calendars in menu | Select Calendars), these calendars are continuously synced by Google's Android Sync software. This sync takes place at regular intervals (the exact frequency is dependent on many variables). There is a menu command in Pimlical (menu | Sync Now) which tells Google's Sync software to immediately proceed with syncing the database (and that is all it does). 

Pimlical does not automatically refresh its calendar unless you set the preference: GoogleRefreshInterval to a value other than 0. If 0, you will need to manually refresh the calendar (menu | Refresh Calendar) in order to see the updated information. If the preference is set to a non-zero value, then that specifies the interval between automatic refreshes of the calendar. If you set that preference to -1, Pimlical will refresh the calendar immediately on any change to the native Android calendar provided that it gets properly notified (not all versions/implementations of the Android OS include this notification feature).

Local Calendar, Contacts, Memos Sync

If Pimlical is using its own local databases, you can sync those databases to a desktop running Pimlical using DirectSync, or to any device/desktop running Pimlical Calendar using AutoSync.

DirectSync is the original sync method and still provides the highest degree of security as you can sync from an Android device to the desktop without ever going through any cloud-based server (the data will, however, be present momentarily on the local WiFi network. You can sync any number of Android devices to a desktop, but you can not use DirectSync to sync from desktop to desktop or Android device directly to another Android device (for that, you will need to use AutoSync). DirectSync does require that both devices be physically adjacent (unless using a WebDAV server) and does require interaction on both devices.

Unless security/safety is an overriding consideration, and if using a cloud-based server or a local NAS or Drive connected to your router is acceptable (and it will be for the majority of users), then the best option is the newer AutoSync as it is more flexible and can operate automatically in the background.

DirectSync

DirectSync supports three basic sync methods:
For further information on syncing, see the document on DirectSync (on the desktop: menu | Help | Using DirectSync to Android..., or on the web: http://www.PimlicoSoftware.com/PimlicalDirectSync.htm)..

AutoSync using Cloud-based Server

AutoSync was introduced in V-3.5.1 and is an alternative sync method to DirectSync which uses a cloud-based server or network drive. Any number of devices (desktop or Android) that can connect to the same cloud-based account can then sync with each other. AutoSync supports Dropbox as well as a directly accessible network server that maps onto the desktop's operating system, or a remote server (See Description of Remote Servers) that is accessible by FTP/FTPS. So AutoSync can be used to sync from desktop to desktop as well as from Android to Android (DirectSync can only sync between desktop and Android).

To use AutoSync with aconventional cloud-based server, you need to set up a Dropbox account (Since only Dropbox is supported at this time). Free Dropbox accounts are more than suitable for accomodating the highly compact Pimlical databases (the average database is not likely to be much larger than 2-3Mb at most)..

Once you have set up a Dropbox account you can sync any Pimlical databases to the server (or you can overwrite the server, or have the server overwrite the device, depending on a preference settings.

To use a cloud-based server such as DropBox, the first step is to setup an account on Dropbox as all Pimlical users that will be syncing their calendars together must have access to the same account. Since Dropbox provides free accounts, you may want to set up a new account just for that purpose. At the current time, Dropbox (like many other cloud-based server solutions) offers free accounts with limited storage. The Pimlical files are so small, however, that even the smallest accounts (usually 2Gb or so) are more than sufficient to handle the storage of the PIM data and all the backups etc.

After setting up an account, invoke AutoSync manually on the desktop or Android device (Menu | Files | AutoSync in P/D or menu | AutoSync in P/A). The first time this access occurs, a web browser will be launched asking for confirmation of the access to the dropbox account. For P/D, you will need to confirm authorized access (Pimlical/Android will exit AutoSync to allow authorization to take place).  After responding positively, the sync will proceed in Pimlical/Desktop. In Pimlical/Android you will need to invoke AutoSync a second time.

Pimlical uses this folder by default: Apps/PimlicalApp/PimlicalAutoSync for the PIM data. The Apps folder is created automatically by Dropbox. The PimlicalApp folder is created automatically when Pimlical first logs into the Dropbox server (PimlicalApp being the name of the application). So the first part of that path, Apps\PimlicalApp\, is set by dropbox, not Pimlical, and can not be changed. The preference AutoSyncPath just provides the server name (Dropbox) and the remainder of the path below, so normally, the path in the preference AutoSyncFilePath becomes: CloudRail\Dropbox\PimlicalAutoSync. You should not change this unless you have some compelling reason to do so. In future releases, you will be able to select other cloud-based servers by replacing 'Dropbox' with the name of the cloud-based server.

You can select Files in the left side-panel in Dropbox to see these folders and the files within them.

If you get any kind of error initially, you may need to manually create the PimlicalApp/PimlicalAutoSync folders in dropbox. Also, try resetting AutoSync authentication (P/D: Menu | Special | Reset AutoSync Authentication, P/A: Menu | Debug | Reset AutoSync).

If you invoke AutoSync manually, you will see brief displays of its progress (at bottom right in the status bar in P/D, or via 'Toasts' in P/A - 'Toasts' are brief messages that appear in the middle of the screen for a few seconds and then disappear). If AutoSync is invoked automatically by the preference setting (see below), you will only see a message indicating that AutoSync has started and when it ends (although any error messages will always be displayed). If the preference, DebugMode is set to true, however, you will see these brief displays even when AutoSync is being invoked automatically.

The options that AutoSync uses are set in preferences - see below. By default, Pimlical performs a normal synchronize operation (as opposed to an overwrite) from the local calendar, contacts and memos on the device, to the corresponding files on the server. When you sync for the first time, there are obviously no files on the server, so an overwrite is performed from the local device to the server to set the files up for first time usage. You can also set the preference AutoSyncAction to ensure that the server is initially overwritten.

The only thing that a user will typically have to setup to use AutoSync is to set the preference: AutoSyncFrequency to a value other than 0 seconds. Remember, that syncing to the server will take several minutes or more and setting a very short value will simply cause constant annoying interruptions, so if you set a value of say 30 seconds, it's not going to work satisfactorily (nor are there really any conditions under which it's really necessary to sync that rapidly). A reasonable, absolute minimum value would likely be something in the 15 minute range.

The preference TimeOfDayForAutoSync can be used to guarantee that an AutoSync has taken place by a certain time each day. For example, you have the frequency set to 8h, so it will sync three times a day. But when you get up at 8am, you want to be 100% certain that an AutoSync took place at 8am so that you are looking at the most recently synced data.

Dropbox now requiring explicit login each time

There is a new issue with AutoSync, because Dropbox now requires that you log in for every sync. Previously, the login credentials were remembered and could be re-used. It might be that you have an older set of login credentials that have been "grandfathered in" and in that case, you may still be able to sync with Dropbox without logging in. Otherwise, you will have to log in every time you want to sync, and may not be able to use the AutoSyncFrequency preference to  sync automatically.

To enable AutoSync (presuming you can use it), set the preference AutoSyncFrequency to the frequency with which you want to sync. Do not make this too short, or it will interfere with your use of Pimlical as while a database is being synced, you cannot modify it. A reasonable, smallest value might be something like 10-15 minutes. Syncing with dropbox is not very fast, so if you have a really large local calendar, you may want to split it into a current calendar and an archive calendar for efficiency.

If you have a subscription, you can set the preference: AlwaysResetBeforeAutoSync  to true, so that it performs the reset automatically when you invoke autosync. If there is still an issue using that preference, you might need to extend the delay time before syncing, which you can do by adjusting the preference:  AutoSyncDelayAfterReset to a slightly larger value. Otherwise, if you do not have a subscripttion, you will have to use Menu | Debug | Reset AutoSync  before every manual invocation of the sync.

AutoSync using a Remote Server (Subscription Feature)

Using an external drive on the local network was introduced in V-4.2.x and is an alternative to syncing with Dropbox. A simple way of setting up a drive is to connect an external USB hard drive to your network router. Most contemporary routers have a USB port to which you can connect an external hard drive. If you log into the network router (usually on the address: 192.168.0.1), you should be able to configure access to the hard drive. You can access the drive either via FTP or the more secure FTPS (if you have not set up a user name and login for your router, this is definitely the time to take that necessary step to improve security!). See the section Setting up a Remote Server in the For Advanced section of the online manual for directions on how to set up a Remote Server.

In order to tell AutoSync to use this hard drive on the Remote Server for autosync, set the preference: AutoSyncFilePath to the value: RemoteServer. When using a Remote Server, the preference: AlwaysResetBeforeAutoSync is ignored as there is no reset needed for the Remote Server. Pimlical will log in to the server at the start of AutoSync and logoff at the completion. AutoSync will use the first Remote Server listed in the preference: RemoteServerList. It's probably best though to explicitly reference which Remote Server you wish to use and you can do this by following the RemoteServer legend in the AutoSyncFilePath preference with a comma and then the tag that identifies a particular Remote Server (such as: RemoteServer,Router

As mentioned elsewhere, when setting up a drive for the first time, it's a very good idea to have an Android File Manager that handles FTP (like File Manager+ ) so you can review files on the hard drive and verify that AutoSync is writing files as expected to the PimlicalAutoSync directory (in the example for the Tenda router, this would be: /sda1/PimlicalAutoSync/). When specifying any paths, remember that paths will always use the forward slash for that drive. It's just a bit of an historic anomaly that Windows uses the backslash for paths on local drives.

AutoSync using a Web Domain as a Remote Server

This same mechanism can be used to access a web-based server that you have access to. In that case, you might use someting like: RemoteServer,Pimlico where Pimlico was the tag attribute for one of the Remote Servers defined in RemoteServerList. Again, remember that access to a web domain page over the internet is likely going to be slower than accessing a drive attached to the router, and you may need to tweak the preference: RemoteServerTImeout.

You will still find that using a web page is far faster than using Dropbox and likely more reliable too! Setting up a web-based server if often a lot more complicated due to idiosyncrasies of various web-hosting sites, local firewalls, etc. so be sure to set aside some time and expect to do some fiddling to get it all working for you.

Resolving Conflicts

There are two types of conflicts that can occur - a conflict with other devices trying to access the server at the same time to sync, and a local conflict where a sync is being performed in the background at the same time the user is modifying the database.

Server Conflicts

A locking mechanism prevents more than one device from syncing with the server at a time, and you may see a message on your device that AutoSync has been deferred for a short moment due to such activity.  A device wishing to access the server checks first to see if there is a lock file present in that folder. The lock files have a .lock extension, and a filename that identifies the device (and you can pick your own filename for each device in a preference setting on that device). If there are no lock files present, the device creates a lock file and then checks back a brief moment later to see if any other lock files have been created due to race conditions. If so, the device removes its lock file and sets a timer to perform the lock file check again in a random interval. A brief message will appear on the screen indicating that it will try AutoSync again in a few seconds. Obviously, if the Frequency of syncing is set to a very short time interval and there are a lot of devices trying to sync with the server, you may see a lot more conflicts occurring.

Local Conflicts

Local Conflicts occur when the user is updating the database when an AutoSync operation is about to start or is in progress. Before automatically launching AutoSync, Pimlical checks to see if any dialogs that can modify the database are open (i.e. Edit dialog, a dialog invoked from a selection list, etc.) and if so, will defer AutoSync for one minute. Note that if you open up the Edit Dialog and then leave it open, AutoSync will not run. In general it is never a good idea to leave a dialog that can modify the database open for an extended period of time, so it's a good practice to avoid doing that.

Pimlical will attempt AutoSync at times where a dialog is open that can not directly modify the database - for example, if an Event Selection List is being displayed, it is safe for AutoSync to proceed, although the selection list itself will not be refreshed with any potentially new information from the sync until the user returns to the main view.

Synchronization Conflicts

These should never occur provided that you set the preference LatestUpdateAlwaysPrevails to its default value of True. If set to False, the sync mechanism will not attempt to resolve conflicts and will duplicate the items that were modified on both platforms since the last sync. With multiple users automatically syncing to the same server, this will of course result in what appears to be endless duplications of events, especially of floating events which are automatically updated on each individual platform at different times.
Preference Settings
Prior to using AutoSync, it's a good idea to review those preferences that directly affect how AutoSync operates. Usually, the only preference a user would need to modify is AutoSyncFrequency as the default value of 0s (zero seconds) effectively disables AutoSync completely. Remember to avoid picking such a small time interval that Pimlical is constantly trying to sync with the server

Preference NameDefault ValueDescription
LatestUpdateAlwaysPrevailsTrueAutomatically resolves conflicts in favor of item that was most recently modified if true. If false, both items are preserved in the database so the user can decide which item prevails. Conflicts only occurs when both items have been modified after the most recent Sync.
MaintainAuditTrailfalsewhen issues arise in AutoSync, they are logged to an audittrail file. Set this to true to help diagnose issues
AutoSyncFilePathCloudRail/Dropbox/
PimlicalAutoSync/		Path to the Cloud or Local Network Server. Up to the slash is the server designation. For a Remote Server, start the preference with "RemoteServer" followed with an optional comma and a remote server tag to specify which remote server to use from the preference: RemoteServerList.
AutoSyncFrequency0sset to 0s to disable AutoSync, otherwise set to interval between syncs (avoid values much less than say 15m or so).
TimeOfDayForAutoSync00:00You can set this preference to a time of day to guarantee that an AutoSync has taken place no later than this time today. Leave at midnight to disable this feature. You must also have AutoSyncFrequency set to a value other than 0s in order for this preference to have effect.
AutoSyncNameYou can override the default device name with anything you like, such as "MyNexus6" or "Macbook Air". If blank, Pimlical automatically assigns a unique device name
AutoSyncThreshold5mA timeout value for AutoSync. After this amount of time goes by, any device still maintaining a lock flag is presumed to have stalled for some reason.
DisplayMessageWhenAutosyncCompletesTrueSet to False to avoid seeing the brief message that AutoSync has completed (also suppresses initial message too). Has no affect on messages that appear when AutoSync is manually invoked by menu command.
LocalCalendarSyncThreshold10Specifies the lower limit on the number of seconds discrepancy between two date/time stamps to consider them to be identical (i.e. with a value of 10, if the date/time stamps differ by 10 or less seconds, they will be considered to be identical. Caters to differences in real-time clocks on different platforms
AutoSyncActionSynchronizeSets the Default sync operation for AutoSync. Can also be set to P/A Overwrites Server or to Server Overwrites P/A
AutoSyncOptionsCalendar,tasks,
contacts,memos		Specifies which databases are to be synced.
AutoSyncNotificationVibratesTrueSet to false to turn off vibration for the notification that AutoSync is taking place (new in P/A: V-3.5.09). Only relevant for Android OS
ApptCategoriesToSync(All)This preference specifies which Appointment categories are to be synced to the Android device. If blank or set to (All),  all categories are synced.
TaskCategoriesToSync(All)This preference specifies which Task categories are to be synced to the Android device. If blank or set to (All),  all categories are synced.
ContactCategoriesToSync(All)This preference specifies which Contact categories are to be synced to the Android device. If blank or set to (All),  all categories are synced.
MemoCategoriesToSync(All)This preference specifies which Memo categories are to be synced to the Android device. If blank or set to (All),  all categories are synced.
DoNotSyncEventsPriorToDate(None)To avoid syncing events prior to some cutoff date, specify the date here. This can greatly speed up the syncing of calendars by, say, ignoring events more than a year old (not likely there's a need to sync those older events).
DaysToKeepDeletedRecords30This preference specifies for how many days, Pimlical should keep deleted records in the database prior to deleting them. For AutoSync and DirectSync to work properly, it is very important that deleted records not be removed prior to syncing to a device that still has those records. If they get removed prematurely, the sync routine will think the record was missing and instead of deleting it on the platform being synced to, it will restore the undeleted record to the platform that no longer had the record. A value of 30 days (default) should ensure that all syncs have been completed (presuming you sync to all devices at least more frequently than once a month).
AlwaysResetBeforeAutoSyncTrueSubscription Feature: when set to True, Pimlical will perform a reset on the login credentials, so the login screen appears every time when invoking AutoSync. This  caters to  the new requirement from DropBox that users log in every time to Dropbox to perform an AutoSync (i.e. the saved login credentials are no longer honored).
AutoSyncDelayAfterReset5Subscription Feature: This preference specifies the number of seconds between the automatic reset (preference above set to True) and the subsequent invocation of AutoSync. If there are still issues with AutoSync, you could try setting this to a larger value (say 10-15 seconds).
ShowSyncChangesOnlyTrueNormally, only items that have been changed on one platform are included in the log file. When set to False, every event is included even if they are identical on both platforms.
DisplaySyncLogFalseSet this preference to True to display a log of the Sync operation at the conclusion of the Sync.

Trouble-Shooting Problems with AutoSync - General

If you are seeing any issues with AutoSync, the first step is to try a manual sync as you will see more status and error messages if you invoke AutoSync manually (alternatively, if you set DebugMode to True, you will also see the messages even on a sync invoked from the timer) . Also set the preference MaintainAuditTrail to True as you will see information regarding the sync logged into the local Audit trail file (P/D: PimlicalDesktop_AuditTrail.txt, P/A: PimlicalAndroid_AuditTrail.txt) in the local Pimlical folder. Also, set the preference DebugMode to True temporarily as in debug mode, more information is written to the AuditTrail files.

Also look in the Pimlical folder for the log file which will have the filename: AutoSync.log as that will also have information about the sync process on that particular platform.

Look in the Pimlical folder for any error files (error files have a .ERROR extension and send those files to Technical Support for analysis if you see any. These are standard text files that you can view in any text editor, so look at those files first yourself as the issue may be obvious.

Finally, the server itself will have a master log file which shows when every device synced to the server.

Trouble-Shooting Problems with AutoSync

The first step is to look at Dropbox and locate the Apps folder - is there a PimlicalApp folder inside that folder? And if you click on that, do you see the PimlicalAutoSync folder inside the PimlicalApp folder? If so, what files do you see inside the PimlicalAutoSync folder?

Sometimes when a remote server/dropbox hiccoughs, a Lock file may be left on the server (a Lock file has the extension .lock), in that case, simply delete the lock file and other devices should then sync (a device will always remove its own lock file, but will not remove the lock file of another device).

Note that Dropbox now requires that Pimlical log in every time to access Dropbox. In that case, you must perform the reset on the old credentials, either by setting the preference: AlwaysResetBeforeAutoSync, or by going into Menu | Debug | Reset AutoSync.  This is only an issue when using Dropbox for AutoSync.

Resetting everything to start from a known good state

Sometimes, you want to be sure that you can restart from a known good state - for example, you have one platform that you KNOW is good, and you are not sure of what is in dropbox and/or syncing with other devices just doesn't seem to be working correctly. To handle this:

    1. Make a backup of your good platform, so if something goes wrong, you won't lose your only good copy.
    2. In Dropbox, delete PimlicalLocalCalendar.*, contacts.* and memos.* in the Apps/PimlicalApp/PimlicalAutoSync folder and delete all *.lock files (Where * means anything, so as an extension, this means delete ALL files with that name regardless of the file extension).
    3. On each platform you want to re-initialize, delete all files in the PimlicalCalendars, PimlicalContacts and PimlicalMemos folders.
    4. Invoke AutoSync on your good platform and make sure there are no errors recorded.
    5. Invoke AutoSync on all the other platforms that you want to initialize.
Using Multiple Local Calendar Files

You can set up as many local calendar files as you wish, but only one can be viewed at any one time in Pimlical/Android and only the currently selected local calendar will be synced to the server. To switch to a different local calendar, use menu | Select Local Calendar. If you don't see this menu option, go into Menu | Preferences and select the preference: MenuCommandsAndOrder in the [commands/Functions] section and make sure that menu  item is selected for display.

A typical use of having multiple local calendars is when you have an enormous calendar database with lots of historical data that you rarely need to look at, but must be able to view when it's needed. By putting the older data in an archive calendar(s), you can keep the current local calendar compact so it reads quickly. And on those rare occasions where you need to look at the archive, having to switch to it and wait for it to read is a small penalty to pay for the much faster response you get by keeping the  current calendar relatively compact.

Why Deleted Records are kept in the database

Deleted records must be preserved in the database for at least a while in order for syncing to work properly. If you think about it for a moment, you will realize that if you remove ALL traces of Record X from Platform B, when you sync Platform A and Platform B, if Platform A has Record X, the sync routine will assume that this must be a new record that was never synced to Platform B and will promptly copy it to B as a new record. From your perspective it may look like the record you deleted just reappeared and something is wrong, but the problem was caused by removing all traces of a deleted record. Had that deleted record stayed in the database, then when syncing, the routines would see the deleted record on Platform B, observe that the date/time stamp was later, and then would delete record X from Platform A. So do not use the commands to remove deleted records in some misguided belief that it is a good thing to do! For one thing, the Pimlical databases are so compact that removing records to save space is a complete waste of effort and accomplishes nothing. Second, you can always hide deleted records from view, so there is no reason whatsoever that keeping deleted records should ever pose any issue.

Delete records must be kept for at least long enough that a sync will take place - example: if all AutoSync devices sync every other day,. then you MUST hold deleted records for at least 2 days and would set the preference: DaysToKeepDeletedRecords to 3 as a minimum value. If this preference is set to too small a value, then deleted records will mysteriously re-appear from time to time.
New Login Requirement by Dropbox

Dropbox now (in 2023) requires that on every access/session, that the user logs in to Dropbox. The remembered credentials are no longer honored. Some fortunate users that have older credentials may find that they can circumvent this requirement as it appears that Dropbox has "grandfathered-in" some of the older credentials. If you have an old backup of your preferences, you might look at the preference: CloudRailServiceLoginString as you just might be able to copy that into your current preferences to find yourself "grandfathered-in". But for all other users, you must reset those credentials before attempting an AUtoSync. If you have a subscription, you can just set the preference: AlwaysResetBeforeAutoSync to True and Pimlical will do the reset for you when you invoke AutoSync.  Otherwise, you will have to go into Menu | Debug | Reset AutoSync first and you will have to do that every time you invoke AutoSync.