Using import and export parameters
Import and export parameters enable you to control and describe your imports and exports with the Bulk API. This tutorial will walkthrough how to use the following parameters:
mapDataCards
(Imports)syncActions
(Imports and Exports)importPriorityUri
(Imports)updateRule
(Imports)areSystemTimestampsInUTC
(Exports)linkUsers
(Imports)-
updateRuleByField
(Imports)
All of these parameters are optional. See Import Characteristics or Export Characteristics for a full list of available parameters.
mapDataCards
The mapDataCards
parameter enables you to decide whether or not custom object records or event registrants will be mapped on import. If set to true
, you'll need to specify the Eloqua entity field for mapping and the field that will be used for matching.
Here are the parameters you'll need to familiarize yourself with:
mapDataCards
(boolean): Whether or not custom object records or event registrants will be mapped on import. By default,mapDataCards
isfalse
. If you set it totrue
, you must specify the fields for mapping.mapDataCardsEntityField
(string): Specifies which Eloqua entity field will be used for mapping.mapDataCardsSourceField
(string): Specifies the source field that will be used for matching.mapDataCardsEntityType
(string): Specifies the entity of the custom object record or event import. Allowed values are "Contact" or "Company".mapDataCardsCaseSensitiveMatch
(boolean): Whether to perform a case sensitive search when mapping custom object records or events to a contact or account.
Example
Let's create a new custom object import and map records to contacts using the contact field ContactIdExt
:
HTTP Request
POST /api/bulk/2.0/customObjects/8/imports
Content-Type: application/json
Request Body
{
"name": "Simple CDO Contact Import 2",
"mapDataCards": "true",
"mapDataCardsEntityField": "{{Contact.Field(ContactIDExt)}}",
"mapDataCardsSourceField": "ContactIDExt",
"mapDataCardsEntityType": "Contact",
"mapDataCardsCaseSensitiveMatch": "false",
"updateRule": "always",
"dataRetentionDuration": "P7D",
"fields": {
"email": "{{CustomObject[8].Field[58]}}",
"first": "{{CustomObject[8].Field[405]}}",
"contactIDExt": "{{CustomObject[8].Field[406]}}"
},
"identifierFieldName": "contactIDExt"
}
"mapDataCardsEntityField": "{{Contact.Field(ContactIDExt)}}"
Because we want to map records to contacts using their contact ID, we are setting
mapDataCardsEntityField
to{{Contact.Field(ContactIDExt)}}
because{{Contact.Field(ContactIDExt)}}
is the internal Eloqua name for the field."mapDataCardsSourceField": "ContactIDExt"
The source field from the imported data that we will use for mapping is
ContactIDExt
, so we have setmapDataCardsSourceField
toContactIDExt
."contactIDExt": "{{CustomObject[8].Field[406]}}"
Whichever field you use for mapping has to exist in both entities (in this case on a contact record and CDO record). Meaning we have to create a new custom object data field for the
contactIDExt
value.
Response
{
"id": 836,
"parentId": 8,
"mapDataCards": true,
"mapDataCardsCaseSensitiveMatch": false,
"mapDataCardsEntityField": "{{Contact.Field(ContactIDExt)}}",
"mapDataCardsSourceField": "ContactIDExt",
"mapDataCardsEntityType": "Contact",
"name": "Simple CDO Contact Import 2",
"updateRule": "always",
"fields": {
"email": "{{CustomObject[8].Field[58]}}",
"first": "{{CustomObject[8].Field[405]}}",
"ContactIDExt": "{{CustomObject[8].Field[406]}}"
},
"identifierFieldName": "ContactIDExt",
"isSyncTriggeredOnImport": false,
"dataRetentionDuration": "P7D",
"isUpdatingMultipleMatchedRecords": false,
"uri": "/customObjects/8/imports/836",
"createdBy": "API.User",
"createdAt": "2016-02-01T21:43:03.7931253Z",
"updatedBy": "API.User",
"updatedAt": "2016-02-01T21:43:03.7931253Z"
}
Example
You may also want to include contact fields in the custom object import. We will use the mapDataCardsEntityField
parameter and match on contact email address. When updating contacts, you should always match on email address, as Eloqua will try to create new contacts if the email address doesn't already exist.
Note: When using the Bulk API, entities related to core entities are available as long as the relationship resolves to a single entity and not many. For example, Account fields could be included in Contact exports and Contact fields could be included in Custom Object exports, as the relationship in these scenarios always resolves to a single entity. Custom Objects do not always resolve to a single entity, i.e. there could be more than one Custom Object record mapped to a Contact, so Custom Object fields cannot be included in Contact exports. Read more within the Eloqua Markup Language version 2 reference page under the Available entities section.
Let's create a new custom object import that includes contact fields:
HTTP Request
POST /api/bulk/2.0/customObjects/8/imports
Content-Type: application/json
Request Body
{
"mapDataCards": true,
"mapDataCardsCaseSensitiveMatch": false,
"mapDataCardsEntityField": "{{Contact.Field(C_EmailAddress)}}",
"mapDataCardsSourceField": "customObjectEmail",
"mapDataCardsEntityType": "Contact",
"name": "Custom Object Import with Contact Updates",
"updateRule": "always",
"fields": {
"customObjectEmail": "{{CustomObject[8].Field[103]}}",
"contactFirstName": "{{CustomObject[8].Contact.Field(C_FirstName)}}"
},
"identifierFieldName": "customObjectEmail",
"isSyncTriggeredOnImport": true
}
syncActions
The syncActions
parameter enables you to declare in an import or export definition that Eloqua should perform additional actions when you importing or exporting data. Using a sync action parameter generally involves specifying the action
to perform and the destination
for the entities.
See Sync actions parameters to see a full list of actions you can perform using this parameter.
Example
Create a contact import definition and use a sync action to add contacts to a contact list:
HTTP Request
POST /api/bulk/2.0/contacts/imports
Content-Type: application/json
Request Body
{
"name": "Email Address Import",
"fields": {
"EmailAddress": "{{Contact.Field(C_EmailAddress)}}"
},
"identifierFieldName": "EmailAddress",
"syncActions": [
{
"destination": "{{ContactList[31]}}",
"action": "add"
}
]
}
Response
{
"name": "Email Address Import",
"fields": {
"EmailAddress": "{{Contact.Field(C_EmailAddress)}}"
},
"identifierFieldName": "EmailAddress",
"syncActions": [
{
"destination": "{{ContactList[31]}}",
"action": "add"
}
],
"isSyncTriggeredOnImport": false,
"dataRetentionDuration": "P7D",
"isUpdatingMultipleMatchedRecords": false,
"uri": "/contacts/imports/3",
"createdBy": "API.User",
"createdAt": "2018-01-29T14:29:15.2227712Z",
"updatedBy": "API.User",
"updatedAt": "2018-01-29T14:29:15.2227712Z"
}
importPriorityUri
The importPriorityUri
parameter is used to set the import to a different priority which overrides the default bulk API priority set in your Eloqua instance. You're able to discover your import priorities via this endpoint,
If you are not familiar with how Eloqua handles data import priorities, see Data import priority for more information.
Example
Create a new import and set the data import priority to #1.
HTTP request
POST /api/bulk/2.0/contacts/imports
Content-Type: application/json
Request body
{
"name":"Email Address Import",
"importPriorityUri":"/imports/priorities/100001",
"fields":{
"EmailAddress":"{{Contact.Field(C_EmailAddress)}}"
},
"identifierFieldName": "EmailAddress"
}
Response
{
"name": "Email Address Import",
"importPriorityUri": "/imports/priorities/100001",
"fields": {
"EmailAddress": "{{Contact.Field(C_EmailAddress)}}"
},
"identifierFieldName": "EmailAddress",
"isSyncTriggeredOnImport": false,
"dataRetentionDuration": "P7D",
"isUpdatingMultipleMatchedRecords": false,
"uri": "/contacts/imports/15",
"createdBy": "API.User",
"createdAt": "2018-01-24T15:29:02.5037857Z",
"updatedBy": "API.User",
"updatedAt": "2018-01-24T15:29:02.5037857Z"
}
updateRule
Import definitions include an updateRule
parameter, which specifies how Eloqua should handle updating records when you import a new value for an existing field. For example, if contact Sally Jones's email address in Eloqua is sally.jones9@example.com
, and you import a new email address for Sally Jones, the updateRule
determines whether Eloqua should retain the existing email address or replace it with the new one. If you do not specify an updateRule
, the rule type defaults to always
.
The following rule types are available:
always
: Always update.ifNewIsNotNull
: Update if the new value is not blank.ifExistingIsNull
: Update if the existing value is blank.useFieldRule
: Use the rule defined at the field level.
Example
Create a new contact import definition and set the update rule to always replace existing records with new values.
HTTP request
POST /api/bulk/2.0/contacts/imports
Content-Type: application/json
Request body
{
"name": "Email Address Import",
"fields": {
"EmailAddress": "{{Contact.Field(C_EmailAddress)}}",
"FirstName": "{{Contact.Field(C_FirstName)}}",
"LastName": "{{Contact.Field(C_LastName)}}",
"Company": "{{Contact.Field(C_Company)}}",
"Address1": "{{Contact.Field(C_Address1)}}",
"Address2": "{{Contact.Field(C_Address2)}}",
"City": "{{Contact.Field(C_City)}}",
"StateProvince": "{{Contact.Field(C_State_Prov)}}"
},
"identifierFieldName": "EmailAddress",
"updateRule": "always"
}
Response
{
"name": "Email Address Import",
"updateRule": "always",
"fields": {
"EmailAddress": "{{Contact.Field(C_EmailAddress)}}",
"FirstName": "{{Contact.Field(C_FirstName)}}",
"LastName": "{{Contact.Field(C_LastName)}}",
"Company": "{{Contact.Field(C_Company)}}",
"Address1": "{{Contact.Field(C_Address1)}}",
"Address2": "{{Contact.Field(C_Address2)}}",
"City": "{{Contact.Field(C_City)}}",
"StateProvince": "{{Contact.Field(C_State_Prov)}}"
},
"identifierFieldName": "EmailAddress",
"isSyncTriggeredOnImport": false,
"dataRetentionDuration": "P7D",
"isUpdatingMultipleMatchedRecords": false,
"uri": "/contacts/imports/6",
"createdBy": "API.User",
"createdAt": "2018-01-29T14:44:42.7717370Z",
"updatedBy": "API.User",
"updatedAt": "2018-01-29T14:44:42.7717370Z"
}
areSystemTimestampsInUTC
The boolean parameter areSystemTimestampsInUTC
enables you to control whether system timestamps will be exported in coordinated universal time (UTC).
Example
With areSystemTimestampsInUTC
set to true
, export accounts that have been created after September 9, 2016 13:46:20.975 UTC:
HTTP request
POST /api/bulk/2.0/accounts/exports
Content-Type: application/json
Request body
{
"name": "System Timestamps in UTC Export",
"fields": {
"companyName": "{{Account.Field(M_CompanyName)}}",
"createdDate": "{{Account.Field(M_DateCreated)}}",
"modifiedDate": "{{Account.Field(M_DateModified)}}"
},
"areSystemTimestampsInUTC": true,
"filter": "'{{Account.Field(M_DateCreated)}}' > '2016-09-01 13:46:20.975'"
}
Response
{
"name": "System Timestamps in UTC Export",
"fields": {
"companyName": "{{Account.Field(M_CompanyName)}}",
"createdDate": "{{Account.Field(M_DateCreated)}}",
"modifiedDate": "{{Account.Field(M_DateModified)}}"
},
"filter": "'{{Account.Field(M_DateCreated)}}' > '2016-09-01 13:46:20.975'",
"dataRetentionDuration": "PT12H",
"areSystemTimestampsInUTC": true,
"uri": "/accounts/exports/92",
"createdBy": "API.User",
"createdAt": "2020-10-30T00:31:10.4176409Z",
"updatedBy": "API.User",
"updatedAt": "2020-10-30T00:31:10.4176409Z"
}
linkUsers
The linkUsers
parameter is a boolean parameter that enables you to link users from a CRM to your Eloqua accounts during an account import.
If linkUsers
is set to true
one of the following CRM User ID fields is required in the Account import definition:
CRMOSCUserId
CRMSfdcUserId
CRMMSDUserId
CRMSODUserId
The statement formatting is:
{{Account.User.Field(<Field Name>)}}
Where <Field Name>
is the CRM User ID field.
Example
Create an Account Import definition, and link users using the field "Oracle Sales Cloud User ID" (CRMOSCUserId):
HTTP request
POST /api/bulk/2.0/accounts/imports
Content-Type: application/json
Request body
{
"name": "Import Accounts and link to Users",
"fields": {
"CompanyName": "{{Account.Field(M_CompanyName)}}",
"UserCRMIdLink": "{{Account.User.Field(CRMOSCUserId)}}"
},
"identifierFieldName": "CompanyName"
"linkUsers": "true"
}
Response
{
"linkUsers": true,
"name": "Import Accounts and link to Users",
"fields": {
"CompanyName": "{{Account.Field(M_CompanyName)}}",
"UserCRMIdLink": "{{Account.User.Field(CRMOSCUserId)}}"
},
"identifierFieldName": "CompanyName",
"isSyncTriggeredOnImport": false,
"dataRetentionDuration": "P7D",
"isUpdatingMultipleMatchedRecords": false,
"uri": "/accounts/imports/41",
"createdBy": "API.User",
"createdAt": "2020-10-29T18:33:18.8585154Z",
"updatedBy": "API.User",
"updatedAt": "2020-10-29T18:33:18.8585154Z"
}
updateRuleByField
Import definitions include an updateRuleByField
parameter, which specifies how Eloqua should handle updating records when you import a new value for an existing field by field. 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 following rule types are available:
-
always
: Always update. -
ifNewIsNotNull
: Update if the new value is not blank. -
ifExistingIsNull
: Update if the existing value is blank. -
useFieldRule
: Use the rule defined at the field level.
Example
Create a new contact import definition and set the update rule by field, for some fields.
HTTP request
POST /api/bulk/2.0/accounts/imports
Content-Type: application/json
Request body
{
"name": "updateRuleByField Import",
"fields": {
"EmailAddress": "{{Contact.Field(C_EmailAddress)}}",
"FirstName": "{{Contact.Field(C_FirstName)}}",
"LastName": "{{Contact.Field(C_LastName)}}",
"Company": "{{Contact.Field(C_Company)}}",
"Address1": "{{Contact.Field(C_Address1)}}",
"Address2": "{{Contact.Field(C_Address2)}}",
"City": "{{Contact.Field(C_City)}}",
"StateProvince": "{{Contact.Field(C_State_Prov)}}"
},
"identifierFieldName": "EmailAddress",
"updateRule": "always",
"updateRuleByField": {
"FirstName": "ifNewIsNotNull",
"LastName": "useFieldRule",
"Company": "ifExistingIsNull"
}
}
Response
{
"name": "updateRuleByField Import",
"updateRule": "always",
"fields": {
"EmailAddress": "{{Contact.Field(C_EmailAddress)}}",
"FirstName": "{{Contact.Field(C_FirstName)}}",
"LastName": "{{Contact.Field(C_LastName)}}",
"Company": "{{Contact.Field(C_Company)}}",
"Address1": "{{Contact.Field(C_Address1)}}",
"Address2": "{{Contact.Field(C_Address2)}}",
"City": "{{Contact.Field(C_City)}}",
"StateProvince": "{{Contact.Field(C_State_Prov)}}"
},
"updateRuleByField": {
"FirstName": "ifNewIsNotNull",
"LastName": "useFieldRule",
"Company": "ifExistingIsNull"
},
"identifierFieldName": "EmailAddress",
"isSyncTriggeredOnImport": false,
"dataRetentionDuration": "P7D",
"isUpdatingMultipleMatchedRecords": false,
"uri": "/contacts/imports/854",
"createdBy": "API.User",
"createdAt": "2022-02-24T23:48:28.2330000Z",
"updatedBy": "API.User",
"updatedAt": "2022-02-24T23:48:28.2330000Z"
}