Import - Insert Related Contact Entities and Create Relationships (Employer, Spouse, etc.)

Summary
=======
This enhancement provides a method for mapping/importing data about related contacts (Spouse, Employer, etc) from a flat import record structure.

Each column in the import file which carries data about a related entity will be flagged by the user during the "Map Fields" step (step 2) with a relationship type. The user will then map each of these columns to the appropriate entity property. For example. if the selected relationship type = 'Spouse', the appropriate contact properties for individuals are mappable - so use could map Spouse -> First Name, Spouse -> Last Name, Spouse -> Email -> Work

During import processing, related entities will be handled as separate contact record inserts/updates (with duplicate checking) - and the specified Relationship object will also be created (if it doesn't already exist).

• • • NOTE: To avoid the additional UI complexity of having the user organize related entity mappings into 'sets' - we will limit implementation to support for mapping only ONE instance of a given relationship type (e.g. user can't map two different Parent or Child relationships - as we we would then need additional tagging to know which set of properties belongs together). This means we can assume that all properties linked to a given relationship type belong to a single contact entity instance.

Implementation
============
1. Add options to the normally displayed option list in the map fields selector for each valid relationship type relative to the type of contacts being imported. These should be grouped together below a 'separator' option, sorted by target contact type+rel type name.
EXAMPLE of options where Individual contacts are being imported:

• related contact info -
  Child of
  Sibling of
  Parent of
  Spouse of
  Employee of
  Volunteer for

2. If any of these 'related info' options are selected, then the appropriate property mapping option selector (WITHOUT the relationship type options) is shown. This <select> functions the same way as the 'normal' mapping column - offering properties appropriate to the contact type linked to that column (e.g. first name, last name, etc. if contact type = Individ, etc.). Hierselects should be in place as usual for location properties (Street Address -> Home....).

NOTE: If the selected relationship type supports 'any contact type' as the target, than ALL available contact properties for the 3 types would need to be listed in the map properties select. However, this is an edge case - as we currently don't have any examples of relationship types which are configured in that way. Recommend filtering out relationship types with ambigous contact_type definitions for now since they complicate things considerably.

See full example below for an illustration of common case of <select> elements / options.

3. An additional 'new contact' insert is attempted (after invoking specified type of duplicate checking on the 'set') - for each marked relationship type.

4. Subsequent to successful insert of related contact, the specified relationship record is created.

5. For the built-in (reserved) 'Spouse' relationship type - we also insert the following additional records:

• a new Household record with Household Name = 'The $last_name Household' (after dupe checking for existing record)
• 2 'member of household' relationship records (one for the primary contact and one for the Spouse)

NOTE: For now, we will only make the assumption of creating a Household record for the 'Spouse' case - since Child/Parent relationships are less likely to share a Household.

FULL EXAMPLE:

• User marks 3 columns in initial mapping step as 'Spouse of'
• A second mapping <select> is displayed for each column, and the user chooses
  • First Name
  • Last Name
  • Email + Work
• User marks another column as 'Employee of'
  • User picks Organization Name from newly displayed <select>
• Given these mappings, processing for each row in import file is:

• insert record for primary contact (after dupe checking)
• check for non-null values in the 3 'Spouse of' fields and validate against requirements for that contact type
  ++ in this case, we have a valid second contact record if either fname+lname OR email are present
  ++ rows w/ null values in related contact fields are ok, rows w/ insufficient or invalid values are added to error stack
• insert record for related contact individual (after dupe checking)
• insert Spouse relationship record
• insert Household contact record (e.g. 'The Smith Household')
• insert 'Household Member' relationship records for primary contact and spouse
• insert Organization contact record using mapped Organization Name (after dupe checking)
• insert Employee/Employer relationship record