====== Concepts and behavior ======
===== Supported file formats =====
Only text based files are supported. The first line in the file must contain headers for the columns in the rest of the file. Columns may be separated either by comma (,), semi-colon (;) or tab characters. An example of a very simple supported file could be:

<code>
id;firstname;lastname;email
1;Largo;LaGrande;largo@example.com
2;Haggis;McMutton;haggis@example.com
3;Augustus;DeWatt;augustus@example.com
</code>

The file should preferably be [[http://en.wikipedia.org/wiki/Character_encoding|encoded]] using UTF-8 although Windows 1252 ("ANSI") is also supported.


<WRAP round info>
=== Note! ===
Make sure that your importfile not includes any "\"-signs as they are not allowed in the import for alternative-lists. 
</WRAP>
===== Access =====
The import feature is only available to authenticated Lime CRM administrator and super users.

===== Mapping date fields =====
Lime CRM Importer can import the most common forms of ISO 8601 date strings. The following date formats can be imported:

=== Dates ===
  * YYYY-MM-DD
  * YYYYMMDD
  * YYYY-MM (defaults to 1 for the day)
  * YYYY (defaults to 1 for month and day)

=== Times ===
  * hh:mm:ss.nn
  * hhmmss.nn
  * hh:mm (defaults to 0 for seconds)
  * hhmm (defaults to 0 for seconds)
  * hh (defaults to 0 for minutes and seconds)

=== Time Zones ===
  * Nothing, will use the server default timezone.
  * Z (UTC)
  * +/-hh:mm
  * +/-hhmm
  * +/-hh

=== Examples of valid dates ===

Dates, times and timezones can be combined together in order to create a date as you can see in the examples below:

  * 2007-01-14T20:34:22+00:00
  * 2007-01-25T12:00:00Z
  * 2007-01-25 12:00:00
  * 2016-01-01
  * 20160101
  * 2016
  * 2015-10

===== Mapping option fields =====
When mapping option fields in Lime CRM against column contents in the import file the file may contain a maximum of 30 different options, otherwise it will not be available for mapping.

===== Matching related records =====
Related records will be mapped on the condition that exactly one record matches the selected field in the related record. Example:

> Jennifer wants to import a number of contact persons and associate them with companies that already exist in the database. After mapping all data fields (first name, last name, title, etc.) she chooses to use the company customer number as key for matching existing companies. After the import has completed, she inspects the result and finds that five of the newly created persons don't have an associated company. After having a more detailed look she concludes that three of them didn't get mapped because there was no match at all on customer number and that for the remaining two there existed multiple companies having the same customer number.

===== Using keys =====
When mapping fields it is possible to select one or more keys to use to look up existing records for update. When using multiple key columns all keys must match to generate a hit. Update requires that exactly one record matches.

One of the following three behaviors must be selected when importing data and one or more keys have been specified:

  * **Create and update records** \\ If an existing record is found it will be updated, otherwise a new record will be created.
  * **Only update existing records** \\ If an existing record is found it will be updated, otherwise nothing will happen.
  * **Only create new records** \\ If an existing record is found the row will be ignored, otherwise a new record will be created.

<WRAP round info>
=== Note! ===
Data in non-empty fields will never be overwritten when updating existing records.
</WRAP>