Bulk API Developer's Guide

Introduction
Quick Start
Planning Bulk Data Loads
Preparing Data Files
Loading Binary Attachments
Request Basics
Working with Jobs
Working with Batches
Bulk Query
Reference
Sample Client Application Using Java
Sample Bulk Query Using cURL
Mapping Data Fields
Glossary
PDF

Newer Version Available

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

Mapping 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:

1Salesforce Field,Csv Header,Value,Hint
2Name,Full Name,,
3Title,Job Title,,
4LeadSource,Lead Source,Import,
5Description,,Imported from XYZ.csv,
6Birthdate,Date of Birth,,dd MM yy

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:

1Full Name,Job Title,Lead Source,Date of Birth,Comment
2"Cat, Tom",DSH,Interview,10 Feb 40,likes Jerry
3Jerry Mouse,House Mouse,,10 Feb 40,likes Tom

The corresponding request body after transformation looks like this:

1LastName,FirstName,Title,LeadSource,Description,Birthdate
2Cat,Tom,DSH,Interview,Imported from XYZ.csv,1940-02-10Z
3Mouse,Jerry,House Mouse,Import,Imported from XYZ.csv,1940-02-10Z

Upload the transformation spec

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

1https://instance_name—api.salesforce.com/services/async/APIversion/job/jobid/spec

Considerations

  • Transformation specs must be CSV files. XML 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.