vCard support

Work in Progress This page is just a stub of a work in progress doc for vCard support. There's not much here yet.

Location/Email/Phone Model Differencies Between CiviCRM And vCard

In CiviCRM, emails and phones are parts of locations:

• location A [primary]
  • phone P1 [primary]
  • phone P2
  • email E1 [primary]
  • email E2

• location B [primary]
  • phone P3 [primary]
  • phone P4
  • email E3 [primary]
  • email E4

In vCard, the structure is one level "flatter":

• location A [primary]
• location B
• phone P1 [primary]
• phone P2
• phone P3
• email E1 [primary]
• email E2

vCard Export

On export CiviCRM simply "flattens" the structure to match vCard's schema. Phone numbers and email addresses are filtered so that they are not repeated in the vCard (if, for example, P2 = P3).

The location marked as preferred in CiviCRM is of TYPE=PREF in vCard.

The locations of location_type "Home" in CiviCRM are of TYPE=HOME in vCard; likewise for "Work" and TYPE=WORK. In the (near) future this will be moved to the vcard_name field of the location_type table.

CiviCRM generates vCards for all of its contact types (Individuals, Organizations and Households). For non-Individuals, the organization_name and household_name are used in place of last name (the vCard specs suggests using vCards for non-personal contacts as well as personal).

vCard Export Known Issues

Currently, CiviCRM does not set properly the encoding of the generated vCard contents. This works as far as the contact info is encoded in US-ASCII only, i.e. does not contain "high"/"national" characters. The used classes do not support non-US-ASCII encodings, so we'll have to add this to the "upstream" class.

vCard Import

vCard import is not yet implemented.

vCard Import Known Issues

There is no way to check whether a vCard contains an Individual contact, an Organization or a Household one. Most probably will either assume Individual or provide the user with a drop-down.

We should most probably assume that the phone and email data from the "flat" vCard structure belongs to the first location. Also, we should map TYPE=WORK and TYPE=HOME in our model accordingly.

As with export, the import will initially work only for US-ASCII data. Please also take a look at the Contact_Vcard_Parse Known Issues.

Classes

CiviCRM uses the Contact_Vcard_Build and Contact_Vcard_Parse PEAR classes for import and export.

vCard 2.1 vs. 3.0

There are two vCard standards, vCard 2.1 and 3.0. The 3.0 is much more flexible (and, at the same time, "lax"), while 2.1 seems to be supported by wider scope of applications (i.e., if something supports vCards it surely supports 2.1 and only might support 3.0).

Currently, CiviCRM exports vCards in the 2.1 format. This can be later extended to be a config setting.

Both Parse and Build classes support both 2.1 and 3.0 out-of-the-box (but neither supports non-US-ASCII data yet).