Documentation

CRM_Contact_Import_Parser_Contact extends CRM_Import_Parser
in package

Application

class to parse contact csv files

Properties

$_newContacts : array<string|int, mixed>: Array of successfully imported contact id's
$_rowCount : int: Total number of lines in file
$_tableName : mixed
$fieldMetadata : mixed
$relationshipLabels : array<string|int, mixed>: Relationship labels.
$_unparsedStreetAddressContacts : array<string|int, mixed>: Addresses that failed to parse.
$externalIdentifiers : mixed

Methods

addToErrorMsg() : mixed: Build error-message containing error-fields
createContact() : CRM_Contact_BAO_Contact: Method for creating contact.
getMappedFieldLabel() : string
getMappedRow() : array<string|int, mixed>: Transform the input parameters into the form handled by the input routine.
getMappingFieldFromMapperInput() : array<string|int, mixed>: Get the civicrm_mapping_field appropriate layout for the mapper input.
getTrackingFields() : array<string|int, mixed>: Get the fields to track the import.
getUserJobInfo() : array<string|int, mixed>: Get information about the provided job.
import() : void: Handle the values in import mode.
init() : mixed: The initializer code, called before processing.
checkForDuplicateExternalIdentifiers() : void: Return an error if the csv has more than one row with the same external identifier.
createRelationship() : void
fillPrimary() : mixed: Fill in the primary location.
formatContactParameters() : bool: Format contact parameters.
formatLocationBlock() : bool: Format location block ready for importing.
getFieldMappings() : array<string|int, mixed>: Get the field mappings for the import.
getInvalidValuesForContact() : array<string|int, mixed>: Get the invalid values in the params for the given contact.
getMetadataForEntity() : array<string|int, mixed>: Get the field metadata for the relevant entity.
getPossibleContactMatch() : int|null: Get the possible contact matches.
getRelatedContactLabel() : null|string: Get the related contact type.
getRelatedContactsParams() : array<string|int, mixed>: Get any related contacts designated for update.
getRelatedContactSubType() : null|string: Get the related contact sub type.
getRelatedContactType() : null|string: Get the related contact type.
getRelationshipLabel() : string: Get the relevant label for the relationship.
getRelationships() : array<string|int, mixed>: Get sorted available relationships.
getRelationshipType() : array<string|int, string>: Get the relationship type.
getStatus() : string
isParseStreetAddress() : bool: Is street address parsing enabled for the site.
lookupContactID() : int|null: Lookup the contact's contact ID.
processContact() : int|null
setFieldMetadata() : mixed: Set field metadata.
validateParams() : void
addFieldToParams() : void: Add the given field to the contact array.
checkStatesForCountry() : int|null: Check is any of the given states correlate to the country.
fillStateProvince() : array<string|int, mixed>
formatCommonData() : mixed: Format common params data to the format that was required a very long time ago.
formatParams() : mixed: Format params for update and fill mode.
formatProfileContactParams() : array<string|int, mixed>: Legacy format profile contact parameters.
getSuccessMessage() : string: Get the message for a successful import.
legacyCreateMultiple() : array<string|int, mixed>: Only called from import now... plus one place outside of core & tests.
tryToResolveCounty() : string|int
tryToResolveStateProvince() : int|string: Try to get the correct state province using what country information we have.

$_newContacts

Array of successfully imported contact id's


    protected
        array<string|int, mixed>
    $_newContacts
     = []

$_rowCount

Total number of lines in file


    protected
        int
    $_rowCount

$_tableName


    protected
        mixed
    $_tableName

$fieldMetadata


    protected
        mixed
    $fieldMetadata
     = []

$relationshipLabels

Relationship labels.


    protected
        array<string|int, mixed>
    $relationshipLabels
     = []

Temporary cache of labels to reduce queries in getRelationshipLabels.

e.g ['5a_b' => 'Employer', '5b_a' => 'Employee']

$_unparsedStreetAddressContacts

Addresses that failed to parse.


    private
        array<string|int, mixed>
    $_unparsedStreetAddressContacts
     = []

$externalIdentifiers


    private
        mixed
    $externalIdentifiers
     = []

addToErrorMsg()

Build error-message containing error-fields


    public
            static        addToErrorMsg(string $errorName, string &$errorMessage) : mixed

Once upon a time there was a dev who hadn't heard of implode. That dev wrote this function.

Parameters

$errorName : string: A string containing error-field name.
$errorMessage : string: A string containing all the error-fields, where the new errorName is concatenated.

createContact()

Method for creating contact.


    public
                    createContact(array<string|int, mixed> &$formatted[, int $contactId = NULL ]) : CRM_Contact_BAO_Contact

Parameters

$formatted : array<string|int, mixed>
$contactId : int = NULL

Return values

CRM_Contact_BAO_Contact —

If a duplicate is found an array is returned, otherwise CRM_Contact_BAO_Contact

getMappedFieldLabel()


    public
                    getMappedFieldLabel(array<string|int, mixed> $mappedField) : string

Parameters

$mappedField : array<string|int, mixed>: Field detail as would be saved in field_mapping table or as returned from getMappingFieldFromMapperInput

Return values

string

getMappedRow()

Transform the input parameters into the form handled by the input routine.


    public
                    getMappedRow(array<string|int, mixed> $values) : array<string|int, mixed>

Parameters

$values : array<string|int, mixed>: Input parameters as they come in from the datasource eg. ['Bob', 'Smith', 'bob@example.org', '123-456']

Return values

array<string|int, mixed> —

Parameters mapped to CiviCRM fields based on the mapping and specified contact type. eg. [ 'contact_type' => 'Individual', 'first_name' => 'Bob', 'last_name' => 'Smith', 'phone' => ['phone' => '123', 'location_type_id' => 1, 'phone_type_id' => 1], '5_a_b' => ['contact_type' => 'Organization', 'url' => ['url' => 'https://example.org', 'website_type_id' => 1]] 'im' => ['im' => 'my-handle', 'location_type_id' => 1, 'provider_id' => 1],

getMappingFieldFromMapperInput()

Get the civicrm_mapping_field appropriate layout for the mapper input.


    public
                    getMappingFieldFromMapperInput(array<string|int, mixed> $fieldMapping, int $mappingID, int $columnNumber) : array<string|int, mixed>

The input looks something like ['street_address', 1] and would be mapped to ['name' => 'street_address', 'location_type_id' => 1]

Parameters

$fieldMapping : array<string|int, mixed>: Field as submitted on the MapField form - this is a non-associative array, the keys of which depend on the data/ field. Generally it will be one of [$fieldName], [$fieldName, $locationTypeID, $phoneTypeIDOrIMProviderIDIfRelevant], [$fieldName, $websiteTypeID], If the mapping is for a related contact it will be as above but the first key will be the relationship key - eg. 5_a_b.
$mappingID : int
$columnNumber : int

Return values

array<string|int, mixed>

getTrackingFields()

Get the fields to track the import.


    public
                    getTrackingFields() : array<string|int, mixed>

Return values

array<string|int, mixed>

getUserJobInfo()

Get information about the provided job.


    public
            static        getUserJobInfo() : array<string|int, mixed>

name
id (generally the same as name)
label

Return values

array<string|int, mixed>

import()

Handle the values in import mode.


    public
                    import(array<string|int, mixed> $values) : void

Parameters

$values : array<string|int, mixed>: The array of values belonging to this line.

init()

The initializer code, called before processing.


    public
                    init() : mixed

checkForDuplicateExternalIdentifiers()

Return an error if the csv has more than one row with the same external identifier.


    protected
                    checkForDuplicateExternalIdentifiers(string $externalIdentifier) : void

Parameters

$externalIdentifier : string

createRelationship()


    protected
                    createRelationship(mixed $key, mixed $relContactId, mixed $primaryContactId) : void

Parameters

$key : mixed
$relContactId : mixed
$primaryContactId : mixed

fillPrimary()

Fill in the primary location.


    protected
                    fillPrimary(array<string|int, mixed> &$params, array<string|int, mixed> $values, string $entity, int|null $contactID) : mixed

If the contact has a primary address we update it. Otherwise we add an address of the default location type.

Parameters

$params : array<string|int, mixed>

Address block parameters

$values : array<string|int, mixed>

Input values

$entity : string

address, email, phone

$contactID : int|null

formatContactParameters()

Format contact parameters.


    protected
                    formatContactParameters(array<string|int, mixed> &$values, array<string|int, mixed> &$params) : bool

Parameters

$values : array<string|int, mixed>
$params : array<string|int, mixed>

Return values

bool

formatLocationBlock()

Format location block ready for importing.


    protected
                    formatLocationBlock(array<string|int, mixed> &$values) : bool

Note this formatting should all be by the time the code reaches this point

There is some test coverage for this in CRM_Contact_Import_Parser_ContactTest e.g. testImportPrimaryAddress.

Parameters

$values : array<string|int, mixed>

Return values

bool

getFieldMappings()

Get the field mappings for the import.


    protected
                    getFieldMappings() : array<string|int, mixed>

This is the same format as saved in civicrm_mapping_field except that location_type_id = 'Primary' rather than empty where relevant. Also 'im_provider_id' is mapped to the 'real' field name 'provider_id'

Return values

array<string|int, mixed>

getInvalidValuesForContact()

Get the invalid values in the params for the given contact.


    protected
                    getInvalidValuesForContact(array<string|int, mixed>|int|string $value, string $prefixString) : array<string|int, mixed>

Parameters

$value : array<string|int, mixed>|int|string
$prefixString : string

Return values

array<string|int, mixed>

getMetadataForEntity()

Get the field metadata for the relevant entity.


    protected
                    getMetadataForEntity(string $entity) : array<string|int, mixed>

Parameters

$entity : string

Return values

array<string|int, mixed>

getPossibleContactMatch()

Get the possible contact matches.


    protected
                    getPossibleContactMatch(array<string|int, mixed> $params, int|null $extIDMatch, int|string $dedupeRuleID) : int|null

the chosen dedupe rule falling back to
a check for the external ID.

Parameters

$params : array<string|int, mixed>
$extIDMatch : int|null
$dedupeRuleID : int|string

Return values

int|null —

IDs of a possible.

getRelatedContactLabel()

Get the related contact type.


    protected
                    getRelatedContactLabel(int|null $relationshipTypeID, int|string $relationshipDirection) : null|string

Parameters

$relationshipTypeID : int|null
$relationshipDirection : int|string

Return values

null|string

getRelatedContactsParams()

Get any related contacts designated for update.


    protected
                    getRelatedContactsParams(array<string|int, mixed> $params) : array<string|int, mixed>

This extracts the parts that relate to separate related contacts from the 'params' array.

It is probably a bit silly not to nest them more clearly in getParams in the first place & maybe in future we can do that.

Parameters

$params : array<string|int, mixed>

Return values

array<string|int, mixed> —

e.g ['5_a_b' => ['contact_type' => 'Organization', 'organization_name' => 'The Firm']]

getRelatedContactSubType()

Get the related contact sub type.


    protected
                    getRelatedContactSubType(int|null $relationshipTypeID, int|string $relationshipDirection) : null|string

Parameters

$relationshipTypeID : int|null
$relationshipDirection : int|string

Return values

null|string

getRelatedContactType()

Get the related contact type.


    protected
                    getRelatedContactType(int|null $relationshipTypeID, int|string $relationshipDirection) : null|string

Parameters

$relationshipTypeID : int|null
$relationshipDirection : int|string

Return values

null|string

getRelationshipLabel()

Get the relevant label for the relationship.


    protected
                    getRelationshipLabel(int $id, string $direction) : string

Parameters

$id : int
$direction : string

Return values

string

getRelationships()

Get sorted available relationships.


    protected
                    getRelationships() : array<string|int, mixed>

Return values

array<string|int, mixed>

getRelationshipType()

Get the relationship type.


    protected
                    getRelationshipType(int $relationshipTypeID) : array<string|int, string>

Parameters

$relationshipTypeID : int

Return values

array<string|int, string>

getStatus()


    protected
                    getStatus(int|null|string $outcome) : string

Parameters

$outcome : int|null|string

Return values

string

isParseStreetAddress()

Is street address parsing enabled for the site.


    protected
                    isParseStreetAddress() : bool

Return values

bool

lookupContactID()

Lookup the contact's contact ID.


    protected
                    lookupContactID(array<string|int, mixed> $params, bool $isMainContact) : int|null

Parameters

$params : array<string|int, mixed>
$isMainContact : bool

Return values

int|null

processContact()


    protected
                    processContact(array<string|int, mixed> $params, bool $isMainContact) : int|null

Parameters

$params : array<string|int, mixed>
$isMainContact : bool

Return values

int|null

setFieldMetadata()

Set field metadata.


    protected
                    setFieldMetadata() : mixed

validateParams()


    protected
                    validateParams(array<string|int, mixed> $params) : void

Parameters

$params : array<string|int, mixed>

addFieldToParams()

Add the given field to the contact array.


    private
                    addFieldToParams(array<string|int, mixed> &$contactArray, array<string|int, mixed> $locationValues, string $fieldName, mixed $importedValue) : void

Parameters

$contactArray : array<string|int, mixed>
$locationValues : array<string|int, mixed>
$fieldName : string
$importedValue : mixed

checkStatesForCountry()

Check is any of the given states correlate to the country.


    private
                    checkStatesForCountry(int $countryID, array<string|int, mixed> $possibleStates) : int|null

Parameters

$countryID : int
$possibleStates : array<string|int, mixed>

Return values

int|null

fillStateProvince()


    private
                    fillStateProvince(array<string|int, mixed> &$params) : array<string|int, mixed>

Parameters

$params : array<string|int, mixed>

Return values

array<string|int, mixed>

formatCommonData()

Format common params data to the format that was required a very long time ago.


    private
                    formatCommonData(array<string|int, mixed> $params, array<string|int, mixed> &$formatted) : mixed

I think the only useful things this function does now are

calls fillPrimary
possibly the street address parsing.

The other hundred lines do stuff that is done elsewhere. Custom fields should already be formatted by getTransformedValue and we don't need to re-rewrite them to a BAO style array since we call the api which does that.

The call to formatLocationBlock just does the address custom fields which, are already formatted by this point.

Parameters

$params : array<string|int, mixed>: Contain record values.
$formatted : array<string|int, mixed>: Array of formatted data.

formatParams()

Format params for update and fill mode.


    private
                    formatParams(array<string|int, mixed> &$params, int $cid) : mixed

Parameters

$params : array<string|int, mixed>: reference to an array containing all the. values for import
$cid : int: contact id.

formatProfileContactParams()

Legacy format profile contact parameters.


    private
                    formatProfileContactParams(array<string|int, mixed> &$params, array<string|int, mixed> $fields[, int|null $contactID = NULL ][, string|null $ctype = NULL ]) : array<string|int, mixed>

This is a formerly shared function - most of the stuff in it probably does nothing but copied here to star unravelling that...

Parameters

$params : array<string|int, mixed>
$fields : array<string|int, mixed>
$contactID : int|null = NULL
$ctype : string|null = NULL

Return values

array<string|int, mixed>

getSuccessMessage()

Get the message for a successful import.


    private
                    getSuccessMessage() : string

Return values

string

legacyCreateMultiple()

Only called from import now... plus one place outside of core & tests.


    private
            static        legacyCreateMultiple(array<string|int, mixed> $params[, array<string|int, mixed> $ids = [] ]) : array<string|int, mixed>

For single creates use the api instead (it's tested). For multiple a new variant of this function needs to be written and migrated to as this is a bit nasty

Parameters

$params : array<string|int, mixed>: (reference ) an assoc array of name/value pairs.
$ids : array<string|int, mixed> = []: The array that holds all the db ids. per http://wiki.civicrm.org/confluence/display/CRM/Database+layer "we are moving away from the $ids param "

Return values

array<string|int, mixed>

tryToResolveCounty()


    private
                    tryToResolveCounty(string $countyID, string|int|null $stateProvinceID, string|int|null $countryID) : string|int

Parameters

$countyID : string
$stateProvinceID : string|int|null
$countryID : string|int|null

Return values

string|int

tryToResolveStateProvince()

Try to get the correct state province using what country information we have.


    private
                    tryToResolveStateProvince(string $stateProvince, int|null|string $countryID) : int|string

If the state matches more than one possibility then either the imported country of the site country should help us....

Parameters

$stateProvince : string
$countryID : int|null|string

Return values

int|string

CRM_Contact_Import_Parser_Contact extends CRM_Import_Parser in package Application

Table of Contents

Properties

Methods

Properties

$_newContacts

$_rowCount

$_tableName

$fieldMetadata

$relationshipLabels

$_unparsedStreetAddressContacts

$externalIdentifiers

Methods

addToErrorMsg()

Parameters

Tags

createContact()

Parameters

Return values

getMappedFieldLabel()

Parameters

Tags

Return values

getMappedRow()

Parameters

Tags

Return values

getMappingFieldFromMapperInput()

Parameters

Tags

Return values

getTrackingFields()

Return values

getUserJobInfo()

Return values

import()

Parameters

init()

checkForDuplicateExternalIdentifiers()

Parameters

Tags

createRelationship()

Parameters

Tags

fillPrimary()

Parameters

Tags

formatContactParameters()

Parameters

Tags

Return values

formatLocationBlock()

Parameters

Tags

Return values

getFieldMappings()

Tags

Return values

getInvalidValuesForContact()

Parameters

Tags

Return values

getMetadataForEntity()

Parameters

Return values

getPossibleContactMatch()

Parameters

Tags

Return values

getRelatedContactLabel()

Parameters

Tags

Return values

getRelatedContactsParams()

Parameters

Tags

Return values

getRelatedContactSubType()

Parameters

Tags

CRM_Contact_Import_Parser_Contact extends CRM_Import_Parser
in package

Application