5 Customization

ASynK differentiates between application configuration and application state. Configuration is user-facing key-value information, and something that a user does not typically change in the middle of a run. Configuration tells ASynK what to sync, where to put log files, etc.

Application state, on the other hand, is not meant to be modified directly by the user. It is used internally by the program to manage various things about the sync, etc.

In this section we only talk about application configuration. The application state is explained in more detail in the Internals, section.

5.1 config.json and config.py

The entire application configuration is stored as a JSON file in the application_root/config/ directory. It has copious comments and explanation of its various fields, so we will only list the main configurable parameters here, and will just point you to the source to find out more. You should not edit this JSON file directly as it might get updated in subsquent releases of ASynK.

All of your own customizations should be placed in the file ~/.asynk/config.py. You can look in the file for example customizations and further instructions. The first time you run ASynK, a copy of a sample config.py is made to ~/.asynk (which is the default per-user asynk config directory), or to a directory specified with the --user-dir command line option. For all subsequent runs, the default config.json is loaded, then the user customizations are executed by loading the config.py file from the user directory.

1. Location of directory containing logs. This should be the name of a directory relative to the ASynK user directory, which is ~/.asynk/ by default.
2. The prefix and separator to use for the ASynK sync tags/labels.
3. Default values for newly created profile, like sync direction, etc.
4. DB specific configuration. There are many instances where the capabilities of one PIM DB does no match another’s. If care is not take to bridge this gap, synching back and forth could lead to loss of information. ASynK is designed to ensure this does not happen, and we try very hard.

   Bridging this gap sometimes means taking a call on how to handle a particular situation. We have tried to make these essentially arbitrary calls configurable so interested users can tweak this to their liking.

   1. Outlook
      1. The fields to be synched: Outlook has a gazillion properties, many of them seemingly redundant. We have identified a subset of the really relevant ones here, and you can add or remove stuff you want or don’t want.
      2. Email classification by domains: Outlook does not really classify email addresses into Work, Home, Other etc. like Google does. Here you can tell ASynK how to do that based on the email addresses.
   2. BBDB
      1. Location of directory containing backup of BBDB stores. This should the name of a directory relative to the asynk user directory, which is ~/.asynk/ by default.
      2. Text Encodings: The list of text encodings that you want ASynK to try while attempting to read your BBDB
      3. Email classification by domains: Same as explained for Outlook
      4. Postal address map: Same as above, except that this is for postal addresses.
      5. Phones map: Ditto, for phones
      6. Notes map: BBDB really is really flexible, to the point that very basic fields are not standardized. There is no date of birth, middle name, web url, gender, and similar fields. However one can always have such data as a user-defined field. This map allows the mapping from a bbdb field name to one of the standard fields.
   3. Google Contacts
      1. Postal Map: Google’s address system is interesting - a user can either have a standard category, or a user defined label. A generic user defined label has the same problem as with others - it is hard to classify. So we need a map for Google as well.

   Note that your sync field customizations for all the databases should be consistent, otherwise there would be information loss as you sync your contacts around.

5.2 Authentication using ~/.netrc

For Google and CardDAV you are required to provide a username and password to perform most operations. These credentials can be specified in a number of ways including command line flags, or through the STDIN on being prompted for them. There is yet another way to set this up that will reduce your typing and will consolidate all your asynk related authentication information in the same place. That is by using the ~/.netrc file.

Let’s say you have a ASynK profile named testbbcc connects your BBDB file to a Google Contacts account. You can specify the auth credentials for this profile by inserting the following lines in youru ~/.netrc.

machine gc_testbbgc
  login <<< username >>>
  password <<< password >>>

Here the gc_ prefix to the profile name specifies clearly that this is a Google account. Replace the <<< >>> with your actual values.

Similarly for a CardDAV account credentials the gc_ prefix will become cd_. Like so:

machine cd_testbbcd
  login <<< username >>>
  password <<< password >>>

5.2.1 Using netrc for like-pair synching

If your profile is set up to sync betwen two like stores, for e.g. between two Google Contacts accounts, you can specify the login credentials in your netrc as follows:

machine gc1_testgcgc
  login <<< username >>>
  password <<< password >>>

machine gc2_testgcgc
  login <<< username >>>
  password <<< password >>>

Note the name of the machine specifies if it belongs to the first or second collection. Note that you could use the same credentials for both collections. This case would be useful to copy / mirror contacts from one folder to another.

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