AppSuite:VCardMapping

Open-Xchange Contact to vCard Mapping

This article is valid until the version 7.10.4 of the Open Xchange Server. For newer versions please visit https://documentation.open-xchange.com/index.html

This information is valid from 7.8.0 on.

This article describes the mapping rules that are used when converting contacts to or from vCards using the Open-Xchange Server.

Introduction

In former releases of the Open-Xchange Server, when a contact was imported from a vCard, the server only stored vCard parameter values that could be mapped to internal OX properties of a contact, and ignored all further unknown or not mappable properties. Especially during CardDAV synchronization, this often led to partial data loss after the client fetched a previously imported vCard again from the server, for example if the client tried to save a third instant messenger property, a geographical location, or the PGP public key of the contact.

To circumvent these kinds of problems, the vCard import- and export-workflow was redesigned, and now allows to store the original vCard as well besides the mappable contact properties. If enabled, the original data as sent by the client is stored automatically in the context filestore, and is considered again during export in a way where any updates to the OX contact are merged back into the original vCard.

To support the described merging process, the mapping between OX contact attributes and vCard properties has been slightly adjusted to allow a deterministic conversion in both directions. Additionally, all OX contact attributes that are not covered by a well-known vCard property are exported as extended properties, so that all OX properties in an exported vCard are recognized correctly again during import. Further details about the mapping are documented in Mapping Rules below.

Configuration

Whether original vCards should be stored or not, as well as their maximum allowed size, can be controlled by some new properties in the configuration file contact.properties:

# Specifies whether the original files are persisted during vCard import or 
# CardDAV synchronization. If enabled, the original vCard files will be stored 
# in the appropriate filestore and are considered during export again. If 
# disabled, all not mapped information is discarded and is no longer available 
# when exporting the vCard again. 
# Defaults to "true". 
com.openexchange.contact.storeVCards=true 

# Configures the maximum allowed size of a (single) vCard file in bytes. 
# vCards larger than the configured maximum size are rejected and not parsed 
# by the server. A value of "0" or smaller is considered as unlimited. 
# Defaults to 4194304. 
com.openexchange.contact.maxVCardSize=4194304

Please note that storing the original vCard requires an attached filestore for the context, so in case there is none (as indicated via com.openexchange.capability.filestore=false), this feature is not available - importing and exporting vCards then works much like before, i.e. no original vCard is saved, and only mappable properties are persisted.

Workflows

When importing and exporting contacts to or from vCard, there are basically two operation modes: On the one hand, the independent import or export of a contact to or from a vCard, and on the other hand, the process of merging contact updates into an original vCard (or the other way around, merging updated vCards into contacts).

While the first one is mainly used for one-time import-/export-purposes, the latter one is performed during a continuous synchronization of contacts as done via CardDAV, yet also a one-time export will pick up and merge with an existing vCard in case it exists. So, importing and exporting basically involves the following steps:

Export a contact with no original vCard:
- Start with a blank vCard
- Write all mapped OX properties into the vCard based on the mapping rules below

Export a contact with an original vCard:
- Load the stored vCard
- Merge all mapped OX properties into the vCard based on the mapping rules below

Import a vCard and create a new contact:
- Create a new contact
- Parse all mapped properties based on the mapping rules below
- Additionally, store the original vCard

Import a vCard and update an existing contact:
- Load the stored contact
- Parse all mapped properties based on the mapping rules below
- Store or overwrite a previously stored original vCard

Mapping Rules

Mapping between known OX contact attributes and vCard attributes is based on the following rules, where some of the mappings are simple and direct, while others are bit more complicated due to their different representations in the underlying data models.

Simple Mappings

Simple mappings refer to properties where some kind of direct mapping between OX contact attributes and vCard attributes exist. Since many properties in vCards can be defined more than once, the mapping uses the most preferred (based on the PREF type parameter) or first property in the vCard. The following list gives an overview about the directly mapped, simple properties:

Simple Mappings
OX column ID	OX attribute name	vCard property	Remarks
517	anniversary	ANNIVERSARY
511	birthday	BDAY
100	categories	CATEGORIES
101	private_flag	CLASS	Only exported if `true`
500	display_name	FN
515	nickname	NICKNAME
518	note	NOTE
570	image1	PHOTO
515	nickname	NICKNAME
5	last_modified	REV	Ignored during import
520	position	TITLE
514	profession	ROLE
223	uid	UID
558	url	URL

Extended Mappings

Besides the mappings where a direct property mapping is possible, there are some more mappings from OX contact fields to other well-known vCard properties or custom extended properties:

Extended Mappings
OX column ID	OX attribute name	vCard property	Remarks
537	assistant_name	X-ASSISTANT	Additional fallbacks to X-MS-ASSISTANT, X-KADDRESSBOOK-X-AssistantsName, X-EVOLUTION-ASSISTANT
536	manager_name	X-MANAGER	Additional fallbacks to X-MS-MANAGER, X-KADDRESSBOOK-X-ManagersName, X-EVOLUTION-MANAGER
516	spouse_name	X-SPOUSE	Additional fallbacks to X-MS-SPOUSE, X-KADDRESSBOOK-X-SpouseName, X-EVOLUTION-SPOUSE
513	number_of_children	X-MS-CHILD
616	yomi_first_name	X-PHONETIC-FIRST-NAME
617	yomi_last_name	X-PHONETIC-LAST-NAME
571	userfield01	X-OX-USERFIELD-01
572	userfield02	X-OX-USERFIELD-02
573	userfield03	X-OX-USERFIELD-03
574	userfield04	X-OX-USERFIELD-04
575	userfield05	X-OX-USERFIELD-05
576	userfield06	X-OX-USERFIELD-06
577	userfield07	X-OX-USERFIELD-07
578	userfield08	X-OX-USERFIELD-08
579	userfield09	X-OX-USERFIELD-09
580	userfield10	X-OX-USERFIELD-10
581	userfield11	X-OX-USERFIELD-11
582	userfield12	X-OX-USERFIELD-12
583	userfield13	X-OX-USERFIELD-13
584	userfield14	X-OX-USERFIELD-14
585	userfield15	X-OX-USERFIELD-15
586	userfield16	X-OX-USERFIELD-16
587	userfield17	X-OX-USERFIELD-17
588	userfield18	X-OX-USERFIELD-18
589	userfield19	X-OX-USERFIELD-19
590	userfield20	X-OX-USERFIELD-20
522	room_number	X-OX-ROOM-NUMBER
535	info	X-OX-INFO
529	number_of_employee	X-OX-NUMBER-OF-EMPLOYEE
534	business_category	X-OX-BUSINESS-CATEGORY
532	X-OX-COMMERCIAL-REGISTER
531	tax_id	X-OX-TAX-ID
530	sales_volume	X-OX-SALES-VOLUME
521	employee_type	X-OX-EMPLOYEE-TYPE
512	marital_status	X-OX-MARITAL-STATUS
618	yomi_company	X-OX-YOMI-COMPANY
102	color_label	X-OX-COLOR-LABEL

Advanced mappings

Apart from the simple mappings above, there are also more complex vCard properties that refer to or are influenced by more than one OX contact property.

Addresses

https://tools.ietf.org/html/rfc6350#section-6.3.1
OX contacts have three address types: business, home and and other
For each, OX stores the properties street, city, state, postal code and country
Additionally, the mailing label for snail mail (as set by some Outlook clients) is held in addressHome, addressBusiness and addressOther
In vCards, ADR properties have the cardinality *, and may have an assigned LABEL for the mailing label
Each one is stored as structured value (post office box, extended address, street address, locality, region, postal code, country name)
The address parts are mapped between OX contacts and vCards as follows:
- street <-> street address
- city <-> locality
- state <-> region
- postal code <-> postal code
- country <-> country name
- address <-> LABEL
Hence, there are no corresponding OX fields for post office box and extended address
During import, the mapping to vCard ADR properties is based on the TYPE parameters and follows the following rules:
- For the business address, the first ADR property with type work and type pref is parsed
  if not found, parse the first with type work
  if not found, delete the corresponding OX address properties
- For the home address, the first ADR property with type home and type pref is parsed
  if not found, parse the first with type home
  if not found, delete the corresponding OX address properties
- For the other address, the first ADR property with type x-other and type pref is parsed
  if not found, parse the first with type x-other
  if not found, parse the first without type parameters home and work
  if not found, delete the corresponding OX address properties
During export, the OX contact addresses are serialized to a previously saved original vCard as follows:
- Generally, if no single OX property that forms a specific address is set anymore, the corresponding vCard property is deleted during the update
- For the business address, the first ADR property with type work and type pref is updated
  if not found, update the first property with type work and add the pref type
  if not found, add a new property with types work and pref
- For the home address, the first ADR property with type home and type pref is updated
  if not found, update the first property with type home
  if not found, add a new property with type home
- For the other address, the first ADR property with type x-other and type pref is updated
  if not found, update the first property with type x-other
  if not found, update the first property without types home and work and add the x-other type
  if not found, add a new property with type x-other

E-Mails

https://tools.ietf.org/html/rfc6350#section-6.4.2
OX contacts allow storing three different e-mail addresses: email1 (~business), email2 (~home) and email3 (~other)
A telex address is stored at telephone_telex in OX contacts, yet it is expressed as EMAIL type in vCards
In vCards, EMAIL properties have the cardinality *
During import, the mapping to vCard EMAIL properties is based on the TYPE parameters and follows the following rules:
- Generally, if no matching vCard EMAIL property is found, the corresponding OX email property is deleted
- For the business mail address, the first EMAIL property with type work and type pref is parsed
  if not found, parse the first with type work
  if not found, and all EMAIL properties have no distinguishing type (i.e. none is marked work, home, x-other or TLX), parse the most preferred one
- For the home mail address, the first EMAIL property with type home and type pref is parsed
  if not found, parse the first with type home
  if not found, and all EMAIL properties have no distinguishing type (i.e. none is marked work, home, x-other or TLX), parse the 2nd most preferred one
- For the other mail address, the first EMAIL property with type x-other and type pref is parsed
  if not found, parse the first with type x-other
  if not found, parse the EMAIL property that is grouped with an X-ABLabel with value _$!<Other>!$_
  if not found, parse the first without type parameter work, home, x-other or TLX
  if not found, and all EMAIL properties have no distinguishing type (i.e. none is marked work, home, x-other or TLX), parse the 3rd most preferred one
- For the telex address, the first EMAIL property with type TLX and type pref is parsed
  if not found, parse the first with type TLX
During export, the OX contact mail addresses are serialized to a previously saved original vCard as follows:
- Generally, if no single OX property that forms a specific email is set anymore, the corresponding vCard property is deleted during the update
- For the business mail address, the first EMAIL property with type work and type pref is updated
  if not found, update the first with type work and add the pref type
  if not found, and all EMAIL properties have no distinguishing type (i.e. none is marked work, home, x-other or TLX), update the most preferred one and add the work type
  if not found, add a new property with types work and pref
- For the home mail address, the first EMAIL property with type home and type pref is updated
  if not found, update the first with type home
  if not found, and all EMAIL properties have no distinguishing type (i.e. none is marked work, home, x-other or TLX), update the 2nd most preferred one and add the home type
  if not found, add a new property with type home
- For the other mail address, the first EMAIL property with type x-other and type pref is updated
  if not found, update the first with type x-other
  if not found, update the EMAIL property that is grouped with an X-ABLabel with value _$!<Other>!$_ and add the x-other type
  if not found, and all EMAIL properties have no distinguishing type (i.e. none is marked work, home, x-other or TLX), update the 3rd most preferred one and add the x-other type
  if not found, add a new property with types x-other
- For the telex address, the first EMAIL property with type tlx and type pref is updated
  if not found, update the first with type tlx
  if not found, add a new property with type tlx

Instant Messenger

https://tools.ietf.org/html/rfc6350#section-6.4.3
OX contacts allow to store two IM addresses: instant_messenger1 (~business), instant_messenger2 (~home)
OX contacts store IM addresses as arbitrary strings, there are no special protocol semantics applied
In vCards, IMPP properties have the cardinality *
In vCards, an instant messenger addresses are formed as URI, where the protocol part indicate the messenger type (such as 'aim' or 'irc')
During import, the mapping to vCard IMPP properties is based on the TYPE parameters and follows the following rules:
- The whole URI string is stored during import
- Generally, if no matching vCard IMPP property is found, the corresponding OX instant messenger properties are deleted
- For the business IM address, the first IMPP property with type work and type pref is parsed
  if not found, parse the first with type work
- For the home IM address, the first IMPP property with type home and type pref is parsed
  if not found, parse the first with type home
  if not found, parse the first without type parameter
During export, the OX contact IM addresses are serialized to a previously saved original vCard as follows:
- If the stored value represents a URI, this URI is used directly, otherwise, a synthetic URI is constructed
- Generally, if no single OX property that forms a specific IM address is set anymore, the corresponding vCard property is deleted during the update
- For the business IM address, the first IMPP property with type work and type pref is updated
  if not found, update the first with type work and add the pref type
  if not found, add a new property with types work and pref
- For the home IM address, the first IMPP property with type home and type pref is updated
  if not found, update the first with type home
  if not found, add a new property with types home

Organization

https://tools.ietf.org/html/rfc6350#section-6.6.4
OX contacts store organizational attributes at company, department and branches
In vCards, the structured ORG property holds the X.520 Organization Name and Organization Unit attributes [CCITT.X520.1988]
During import, the mapping to the vCard ORG property is based on the following rules:
- The first value from the structured ORG property is used as company
- The second value from the structured ORG property is used as department
- All further values from the structured ORG property are used as branches
- If no ORG property is found, all corresponding contact attributes are deleted, too
During export, the OX contact's organizational attributes are serialized to a previously saved original vCard as follows:
- If no single OX property that forms the ORG property is set anymore, the corresponding vCard property is deleted during the update
- The structured value is always rewritten
- The company is used as first value of the structured value
- The department is used as second value of the structured value
- The branches are used as further values of the structured value

Telephone

https://tools.ietf.org/html/rfc6350#section-6.4.1
OX contacts store telephone and fax numbers at the fields telephone_business1, telephone_business2, fax_business, telephone_callback, telephone_car, telephone_company, telephone_home1, telephone_home2, fax_home, cellular_telephone1, cellular_telephone2, telephone_other, fax_other, telephone_isdn, telephone_pager, telephone_primary, telephone_radio, telephone_ttytdd, telephone_ip, telephone_assistant
In vCards, TEL properties have the cardinality *
During import, the mapping from vCard TEL properties is based on the TYPE parameters and follows the following rules:
- Generally, if no matching vCard TEL property is found, the corresponding OX telephone properties are deleted
- For the telephone_pager attribute, the most preferred TEL property with type pager is parsed
- For the telephone_ttytdd attribute, the most preferred TEL property with type textphone is parsed
- For the telephone_isdn attribute, the most preferred TEL property with type isdn is parsed
- For the telephone_car attribute, the most preferred TEL property with type car is parsed
- For the cellular_telephone1 attribute, the most preferred TEL property with type cell is parsed
- For the cellular_telephone2 attribute, the most preferred TEL property with types cell and x-2nd is parsed
  if not found, parse the second most preferred TEL property with type cell
- For the telephone_callback attribute, the most preferred TEL property with type x-callback is parsed
- For the telephone_company attribute, the most preferred TEL property with type x-company is parsed
- For the telephone_assistant attribute, the most preferred TEL property with type x-assistant is parsed
- For the telephone_ip attribute, the most preferred TEL property with type x-ip is parsed
- For the telephone_radio attribute, the most preferred TEL property with type x-radio is parsed
- For the telephone_primary attribute, the most preferred TEL property with type x-primary is parsed
- For the fax_business attribute, the most preferred TEL property with types fax and type work is parsed
- For the fax_home attribute, the most preferred TEL property with types fax and type home is parsed
- For the fax_other attribute, the most preferred TEL property with types fax and type x-other is parsed
- For the telephone_business1 attribute, the most preferred TEL property with types voice and type work is parsed
  if not found, parse the most preferred TEL property with type work and without any of the types text, fax, cell, video, pager, textphone
- For the telephone_business2 attribute, the most preferred TEL property with types voice, work and x-2nd is parsed
  if not found, parse the most preferred TEL property with types work and x-2nd and without any of the types text, fax, cell, video, pager, textphone
  if not found, parse the second most preferred TEL property with types voice and work
  if not found, parse the second most preferred TEL property with types work and without any of the types text, fax, cell, video, pager, textphone
- For the telephone_home1 attribute, the most preferred TEL property with types voice and type home is parsed
  if not found, parse the most preferred TEL property with type home and without any of the types text, fax, cell, video, pager, textphone
- For the telephone_home2 attribute, the most preferred TEL property with types voice, home and x-2nd is parsed
  if not found, parse the most preferred TEL property with types home and x-2nd and without any of the types text, fax, cell, video, pager, textphone
  if not found, parse the second most preferred TEL property with types voice and home
  if not found, parse the second most preferred TEL property with types home and without any of the types text, fax, cell, video, pager, textphone
- For the telephone_other attribute, the most preferred TEL property with type x-other is parsed
During export, the OX contact telephone numbers are serialized to a previously saved original vCard as follows:
- Generally, if the OX telephone property is not set anymore, the corresponding vCard property is deleted during the update
- For the telephone_pager attribute, the most preferred TEL property with type pager is updated
  if not found, add a new TEL property with type pager
- For the telephone_ttytdd attribute, the most preferred TEL property with type textphone is updated
  if not found, add a new TEL property with type textphone
- For the telephone_isdn attribute, the most preferred TEL property with type isdn is updated
  if not found, add a new TEL property with type isdn
- For the telephone_car attribute, the most preferred TEL property with type car is updated
  if not found, add a new TEL property with type car
- For the cellular_telephone1 attribute, the most preferred TEL property with type cell is updated
  if not found, add a new TEL property with type cell
- For the cellular_telephone2 attribute, the most preferred TEL property with types cell and x-2nd is updated
  if not found, parse the update the most preferred TEL property with type cell and add the type x-2nd
  if not found, add a new TEL property with types cell and x-2nd
- For the telephone_callback attribute, the most preferred TEL property with type x-callback is updated
  if not found, add a new TEL property with type x-callback
- For the telephone_company attribute, the most preferred TEL property with type x-company is updated
  if not found, add a new TEL property with type x-company
- For the telephone_assistant attribute, the most preferred TEL property with type x-assistant is updated
  if not found, add a new TEL property with type x-assistant
- For the telephone_ip attribute, the most preferred TEL property with type x-ip is updated
  if not found, add a new TEL property with type x-ip
- For the telephone_radio attribute, the most preferred TEL property with type x-radio is updated
  if not found, add a new TEL property with type x-radio
- For the telephone_primary attribute, the most preferred TEL property with type x-primary is updated
  if not found, add a new TEL property with type x-primary
- For the fax_business attribute, the most preferred TEL property with types fax and type work is updated
  if not found, add a new TEL property with types fax and `work
- For the fax_home attribute, the most preferred TEL property with types fax and type home is updated
  if not found, add a new TEL property with types fax and home
- For the fax_other attribute, the most preferred TEL property with types fax and type x-other is updated
  if not found, add a new TEL property with types fax and x-other
- For the telephone_business1 attribute, the most preferred TEL property with types voice and type work is updated
  if not found, update the most preferred TEL property with type work and without any of the types text, fax, cell, video, pager, textphone
  if not found, add a new TEL property with types voice, work and pref
- For the telephone_business2 attribute, the most preferred TEL property with types voice, work and x-2nd is updated
  if not found, update the most preferred TEL property with types work and x-2nd and without any of the types text, fax, cell, video, pager, textphone
  if not found, update the second most preferred TEL property with types voice and work and add the type x-2nd
  if not found, update the second most preferred TEL property with types work and without any of the types text, fax, cell, video, pager, textphone and add the type x-2nd
  if not found, add a new TEL property with types voice, work and x-2nd
- For the telephone_home1 attribute, the most preferred TEL property with types voice and type home is updated
  if not found, update the most preferred TEL property with type home and without any of the types text, fax, cell, video, pager, textphone
  if not found, add a new TEL property with types voice, home and pref
- For the telephone_home2 attribute, the most preferred TEL property with types voice, home and x-2nd is updated
  if not found, update the most preferred TEL property with types home and x-2nd and without any of the types text, fax, cell, video, pager, textphone
  if not found, update the second most preferred TEL property with types voice and home and add the type x-2nd
  if not found, update the second most preferred TEL property with types home and without any of the types text, fax, cell, video, pager, textphone and add the type x-2nd
  if not found, add a new TEL property with types voice, home and x-2nd
- For the telephone_other attribute, the most preferred TEL property with type x-other is updated
  if not found, add a new TEL property with types voice and x-other

(Structured) name

https://tools.ietf.org/html/rfc6350#section-6.2.2
OX contacts stores name-related properties at the fields: first_name, last_name, second_name, suffix and title
In vCards, the structured property N stores the different parts of a name, which are family, given, additional, prefixes and suffixes
The parts are mapped between OX contacts and vCards as follows:
- last_name <-> family
- first_name <-> given
- second_name <-> additional
- title <-> prefixes
- suffix <-> suffixes
During import, the mapping to the vCard N property is based on the following rules:
- If there's no N property in the vCard, all name-related properties of the contact are deleted
- Otherwise, the properties are imported based on the above mapping, with the multi-values in prefixes and suffixes being concatenated into the corresponding OX contact properties title and suffix
During export, the OX contact name properties are serialized to a previously saved original vCard as follows:
- If no single OX property that forms the structured name is set anymore, the corresponding vCard property is deleted during the update
- Otherwise, the names serialized into a new or already existing N property following the above mapping rules, with the multi-value properties prefixes and suffixes being filled with the title and suffix values, split by whitespace

Organization

https://tools.ietf.org/html/rfc6350#section-6.6.4
OX contacts store the organization-related properties at the fields company, branches and department
In vCards, the structured text property ORG holds organizational name and units associated with the vCard, i.e. the organization name, followed by zero or more levels of organizational unit names
The OX properties are mapped to the ORG structured value in the order company, department and branches
During import, the mapping to the vCard ORG property is based on the following rules:
- If there's no ORG property in the vCard, all organization-related properties of the contact are deleted
- Otherwise, the values of the structured property are imported, where the first value is mapped to the company, the second one to the department, and all further ones as branches
During export, the OX contact name properties are serialized to a previously saved original vCard as follows:
- If no single organization-related OX property is set anymore, the corresponding vCard property is deleted during the update
- Otherwise, the values are serialized into a new or already existing ORG property, where the company as the first value, the department as the second one, and the branches as further values

Anonymous

Search

AppSuite:VCardMapping

Namespaces

More

Page actions

Contents

Introduction

Configuration

Workflows

Mapping Rules

Simple Mappings

Extended Mappings

Advanced mappings

Addresses

E-Mails

Instant Messenger

Organization

Telephone

(Structured) name

Organization

Navigation

Navigation

Wiki tools

Wiki tools

Anonymous

Search

AppSuite:VCardMapping

Introduction

Configuration

Workflows

Mapping Rules

Simple Mappings

Extended Mappings

Advanced mappings

Addresses

E-Mails

Instant Messenger

Organization

Telephone

(Structured) name

Organization

Navigation

Wiki tools

Page tools

Categories