3 Concepts

This chapter explains some of the key terminology we will use through the rest of this documentation. This is also required reading before you can dig into the code, if you are so inclined.

3.1 Your Information and How it is Organized

3.1.1 PIMDBs

Google, MS Outlook and BBDB are know as “PIM Databases”, and each is a “PIM DB”, or pimdb. PIM stands for Personal Information Manager. PIMDB is PIM Database.

Each PIMDB is referred to using a unique two letter specifier -’bb’ for BBDB, ’gc’ for Google Contacts, ’cd’ for CardDAV and ’ol’ for Outlook. This two letter specifier is called a dbid

3.1.2 Items

Your personal information collection includes contacts, notes, appointments, and tasks. In AsynK we refer to each piece of PIM information in your databases as an Item. When we want to refer a specific type of Item we would refer to them as Items - Contact, Task, Note, or Appointment as applicable.

Every Item has an ID known as a ItemID that is guaranteed to be unique within its containing Folder.

A pimdb can contain one or more Item types. Outlook supports all of them. Google covers Contacts and Appointments well, and BBDB only does contacts. In future we will be able to deal with all the contact types, but for now, the only support is for Contacts.

3.1.3 Message Store

Instead of defining a message store in general terms, let me just give you what they are for each of the PIMDBs we have.

In Google, a Message Store is identified by a user login/password. If you have two Google accounts you have access to two Message Stores on Google Contacts.

With CardDAV, as you can have any number server and a user login/password for your account on that server. In this case a Message Store is the server name - with a leading http or https, and a trailing port number, and associated user credentials.

With MS Outlook, there is a built in concept of a MessageStore. Each account you create becomes a Message Store. If you add a PST file to your profile, it becomes a distinct Message Store. Essentially, The ASynK Message Store corresponds directly with a Outlook Message Store.

A Note on Outlook Profiles: ASynK only works on the default Outlook Profile, and the contained Stores, folders, and contacts. This is important to keep in mind. You cannot specify a different Outlook profile to operate on.

And finally, in BBDB, a BBDB file is the Message Store. Simple :)

3.1.4 Folders

Message Stores are logically divided into Folders. Google and Outlook internally organize their items into Folders (Google actually calls them Groups), but there is no native folder support in BBDB.

Folders are assigned a unique ID determined by the PIMDB, and typically when the folder is created. ASynK provides a way of viewing the available folders, their names, and IDs in a given PIMDB / Message Store.

3.1.4.1 Folders in BBDB

The fact that there is no native folder support in BBDB is more than offset by the fact that is infinitely customizable, and we can support a user-level model of folders as we wish. This is how it works:

Normally, all the contacts in a BBDB store will be in a folder called default. If, however, a contact has a notes field with key titled folder, it will be put into the logical folder with the name specified in the value part of that BBDB notes. For e.g. if (``folder'' . ``Buddies'') is a notes field in a contact, the ASynK will treat it as being in the folder called Buddies.

If you do not like the folder key for your BBDB notes field, and want to call it group instead, you can do that too. Refer to the Customizing AsynK chapter below on how this can be done.

A BBDB folder’s Name and ID are the same, and are taken from the value of the notes field as explained above.

3.2 ASynK Profile

ASynK allows you to keep any folder in a pimdb in sync with any folder in one of the other pimdbs. The configuration and state of synchronization between a pair of folders is captured in a sync Profile. Most ASynK operations operate on a specified sync profile. So you will need to set up at least one profile before you can play with ASynK.

Each Profile has the following information associated with it:

1. Name: A unique alphanumeric string that identifies the profile, and is required for most sync operations. This is specified at the time of profile creation, and has to be provided by the user. A profile’s name cannot be changed after creation.
2. Folder IDs: The IDs for the two folders that are to be synched. The required IDs have to be specified by the user at the time of profile creation. The IDs are assigned by the PIM DBs when the folders are created. ASynK can be used to list the existing folders in a PIMDB and their IDs, so the user can use the appropriate IDs at profile creation time.
3. DB IDs: Two DB IDs that hold the folders that are to be synched. This is specified at the time of profile creation and has to be specified by the user. They have to one of the supported DB IDs, which are ’bb’, ’gc’, ’cd’ and ’ol’, in this version. The order in which the DB IDs are specified matters - as explained below.
4. Sync Timestamps: The start and end of the last successful sync operation for this profile. The end of the last sync is the timestamp used to query the pimdbs for updates that have to be synched. These are initialized and updated automatically by the system and you do not have to worry about it.
5. Conflict Resolution Direction: Occasionally one ends up editing an item in multiple places or devices, and this situation leads to a conflict - i.e. the same item has been updated since the last sync on both ends. There is no magic way to figure out which is the correct version. So we have to use a pre-determined tie breaker. This parameter tells the system in which direction to resolve this conflict. This field can be specified at the time of profile creation, but defaults to the first dbid specified in the profile. Once profile is created, the direction of conflict resolution cannot be specified for a operation.
6. Sync Direction: Although ASynK is designed to be a two way sync, you might be interested in setting up certain profiles to sync in only one direction - i.e. new entries and updates to existing entries will only flow in one direction. This can be specified at the time of profile creation and also be specified for every sync operation. If it is a one way sync, currently the flow will be from db1 to db2 (i.e. the first db in the profile to the second db). Note: This has to be fixed.

This document was generated on November 10, 2017 using texi2html 5.0.