Bulk API Developer Guide

Introduction to Bulk API
Quick Start
Plan Bulk Data Loads
Prepare Data Files
Load Binary Attachments
Request Basics
Work with Jobs
Work with Batches
Bulk Query
Reference
Sample Client Application Using Java
Map Data Fields
Glossary
PDF

Newer Version Available

This content describes an older version of this product. View Latest

Map Data Fields

To use Bulk API to import data that was exported directly from Microsoft Outlook, Google Contacts, and other third-party sources, map data fields in any CSV import file to Salesforce data fields. The CSV import file does not need to be Bulk API–compatible.

For example, you might have a CSV import file that includes a field called Number that you want to map to the standard Salesforce field AccountNumber. When you add a batch job using Bulk API, data from your Number field is imported into (or updates) the AccountNumber field in Salesforce.

To add a batch job that maps data fields to Salesforce data fields:
  1. Create a transformation spec (spec.csv) that defines data field mappings. (This is different from the CSV import file that contains your data.)
  2. Create a new job that specifies an object and action, just as you would for any other Bulk API job.
  3. Upload the transformation spec.
  4. Send data to the server in batches.

Create a Transformation Spec That Defines Mappings

The transformation spec (spec.csv) provides the instructions for how to map the data in your import file to Salesforce data fields.

The spec.csv file contains four fields:

Field Description
Salesforce Field The Salesforce field you want to map to.
Csv Header The field in your import file you want to map.
Value A default value.
Bulk API uses this value in two instances:
  • When there is no value present in the import file for the field specified in the Csv Header field
  • When there is no value defined for the Csv Header field in the spec.csv file

This field is optional.
Hint Tells Bulk API how to interpret data in the import file.
Bulk API can use this value to do two things:
  • Interpret Java format strings for date and time fields
  • Define what is true using regular expressions for boolean fields

This field is optional.

Here is a sample spec.csv file:

This spec.csv file tells Bulk API to:

  • Map the Full Name field in the import file to the LastName and FirstName fields in Salesforce.
  • Map the Job Title field in the import file to the Title field in Salesforce.
  • Map the Lead Source field in the import file to the LeadSource field in Salesforce, and use Import as the default value when no values are present are in the import file.
  • Use Imported from XYZ.csv as the default value for the Description field in Salesforce.
  • Map the Date of Birth field in the import file to the Birthdate field in Salesforce, and use the dd MM yy format to convert Date of Birth field formats into an acceptable format for Bulk API.

The corresponding contents of the import file might look like this:

The corresponding request body after transformation looks like this:

Upload the Transformation Spec

To upload the transformation spec, send a POST request to this URI:

Considerations

  • Transformation specs must be CSV files. XML and JSON files are not supported.
  • Transformation specs (spec.csv files) must use UTF-8 encoding. CSV import files do not need to use UTF-8 encoding. (You can specify the encoding in the Content-Type header.)
  • Transformation specs are not persistent; their scopes are limited to the current job.