Import characteristics

Import characteristics are properties you use to control and describe an import with the Bulk API.

The following characteristics are required:

• name (string): The name of this import (maximum 100 characters).

• identifierFieldName (string): The field which will be used to identify the entity. Must be a string value, at least 1 character and at most 100 characters long. The following field types are not supported:

  • Large text
  • Date
  • Boolean

The following characteristics are optional:

• isSyncTriggeredOnImport (boolean): Whether a sync is automatically created when uploading sync action data. If you set it to true, a sync will be created upon uploading sync action data; whereas, a sync will not automatically be created if setting it to false. If the property is not set, a sync will not automatically be created when uploading data and isSyncTriggeredOnImport will not be returned.

• dataRetentionDuration (duration): The length of time unsync'd data should remain in the staging area. Bulk API uses the ISO-8601 standard for specifying all durations. Valid values are anything from PT1H (1 hour) to P14D (2 weeks). This setting will default to P7D (7 days) if not explicitly set during import definition creation.

• autoDeleteDuration (duration): The length of time before the sync action definition will be automatically deleted. Bulk API uses the ISO-8601 standard for specifying all durations. The minimum duration is PT1H (1 hour) and the maximum duration is P365D (365 days)​. If the property is not set, automatic deletion will not occur and autoDeleteDuration will not be returned. This is typically used for one-time-use sync action definitions.

• importPriorityUri (string): Sets the priority of the data to import. It must reference an existing /imports/priorities/{id} URI. If the property is not set, the default "Bulk API" import priority will be used. To see the list of the available priorities, use the Retrieve a list of import priorities endpoint. Data import priority compares new data to existing data, then determines whether to update contact data depending on the source. If you are not familiar with how Eloqua handles data import priorities, see Data import priority for more information.

  In the majority of cases, you will want to use the default "Bulk API" import priority and not specify an importPriorityUri.

• updateRule (string): Indicates whether to update values in the Eloqua database from values imported with this import definition. updateRule will only be returned if included in the create or update definition request, and always is the default if updateRule is not included in definition creation or update. The available options are:

  • always: Always update
  • ifNewIsNotNull: Update if the new value is not blank
  • ifExistingIsNull: Update if the existing value is not blank
  • useFieldRule: Use the rule defined at the field level

• isUpdatingMultipleMatchedRecords (boolean): When set to true, if Eloqua finds multiple matching records for the identifierFieldName, Eloqua will update all of the records that match. If set to false, Eloqua updates based on its internal algorithm. isUpdatingMultipleMatchedRecords is always returned, and false is the default if isUpdatingMultipleMatchedRecords is not included in definition creation or update. For contact imports, the isUpdatingMultipleMatchedRecords property must be set to false in order to update Contact.Field(C_EmailAddress).

• importRule (string): Indicates if records are created & updated, created only, or updated only for Contact and Account imports. importRule will only be returned if included in the create or update definition request, and upsert behavior, createAndUpdate, is the default if importRule is not included in definition creation or update. The available options are:

  • createAndUpdate: Create and update (upsert)
  • updateOnly: Records are only imported if there is a match on identifierFieldName
  • createOnly: Records are only imported if there is not a match on identifierFieldName and or, for contacts only, Email Address

• nullIdentifierFieldName (boolean): When set to true, the identifierFieldName will be nulled when performing an account or contact import; whereas, the identifierFieldName will not be nulled when setting it to false. If the property is not set, the identifierFieldName will not be nulled and nullIdentifierFieldName will not be returned.

• updateRuleByField (object): Indicates whether to update values in the Eloqua database from values imported with this import definition by field. Each pair is a field name mapped to a rule type. If you do not specify an updateRuleByField, or leave a field out of updateRuleByField, the rule type defaults to the rule set with updateRule. The available options are:

  • always: Always update
  • ifNewIsNotNull: Update if the new value is not blank
  • ifExistingIsNull: Update if the existing value is not blank
  • useFieldRule: Use the rule defined at the field level