Salesforce.

com: Salesforce Spring '07

Apex Data Loader User Guide

Copyright 2000-2007 salesforce.com, inc. All rights reserved. Salesforce.com and the no software logo are registered trademarks, and AppExchange, Success On Demand, and The Business Web are trademarks of salesforce.com, inc. All other trademarks mentioned in this document are the properties of their respective owners.

Table of Contents

Table of Contents
Data Loader..........................................................................................................................................................................................? What is the Apex Data Loader?................................................................................................................................................3 Installing the Apex Data Loader...............................................................................................................................................4 Configuring the Apex Data Loader..........................................................................................................................................5 Inserting, Updating, or Deleting Data.......................................................................................................................................7 Exporting Data..........................................................................................................................................................................9 Supported Data Types.............................................................................................................................................................10 Defining Field Mappings........................................................................................................................................................11 Reviewing Output Files..........................................................................................................................................................12 Using the Command Line Interface........................................................................................................................................12 Running in Batch Mode..........................................................................................................................................................13 Uninstalling the Apex Data Loader........................................................................................................................................22 Data Loader Third-Party Licenses..........................................................................................................................................22

Table of Contents

ii

What is the Apex Data Loader?

What is the Apex Data Loader?

Available in: Enterprise, Unlimited, and Developer Editions

The Apex Data Loader is a client application for the bulk import or export of data. Use it to insert, update, delete, or extract Salesforce records. The Apex Data Loader can move data into or out of any type of record. When importing data, it reads, extracts, and loads data from comma separated values (CSV) files. When exporting data, it outputs CSV files. The Apex Data Loader offers the following key features: An easy-to-use wizard interface An alternate command line interface A batch mode interface with database connectivity Support for large files with up to millions of rows Drag-and-drop field mapping Support for all objects, including custom objects Detailed success and error log files in CSV format A built-in CSV file viewer Platform independence, by virtue of being written in Java

To get started, see the following topics: Installing the Apex Data Loader on page 4 When to Use the Apex Data Loader on page 3

For usage instructions, see the following topics: Configuring the Apex Data Loader on page 5 Inserting, Updating, or Deleting Data on page 7 Exporting Data on page 9 Using the Command Line Interface on page 12 Running in Batch Mode on page 13 Note: In previous versions, the Apex Data Loader has been known as the "AppExchange Data Loader" and the "Sforce Data Loader."

See Also:
Supported Data Types Importing Attachments with the Apex Data Loader User guide: Apex Data Loader User Guide

When to Use the Apex Data Loader

Available in: Enterprise, Unlimited, and Developer Editions

Installing the Apex Data Loader

The Apex Data Loader complements the web-based import wizards that are accessible from the Setup menu in the online application. Refer to the following guidelines to determine which method of importing best suits your business needs: Use the Apex Data Loader when: You need to load 50,000 or more records. You need to load into an object that is not yet supported by web-based importing. You want to schedule regular data loads, such as nightly imports. You want to be able to save multiple mapping files for later use. You want to export your data for backup purposes.

Use web-based importing when: You are loading less than 50,000 records. The object you need to import is supported by the web-based import wizards. You want to prevent duplicates by uploading records according to account name and site, contact email address, or lead email address.

See Also:
Installing the Apex Data Loader

Installing the Apex Data Loader

Available in: Enterprise, Unlimited, and Developer Editions

User Permissions Needed To access the page to download the Apex Data Loader: To use the Apex Data Loader: "Modify All Data" The appropriate user permission for the operation you are doing, for example, "Create" on accounts to insert new accounts

System Requirements To use the Apex Data Loader, you need: Windows 2000, Windows XP, Linux, or another operating system that supports Java. Windows users can run the Apex Data Loader wizards, while non-Windows users can run the application from the command line. 90 MB free disk space. 256 MB available memory. Java JRE 1.5 or later.

Installation Procedure Caution: Over time, multiple versions of the Apex Data Loader client application have been available for download. Different versions have different entries in the Add or Remove Programs dialog in your Windows Control Panel. Some versions were released with earlier product names such as "AppExchange Data Loader" or "Sforce Data Loader."

Configuring the Apex Data Loader

You can run different versions at the same time on one computer. However, if a particular version is installed on your computer, do not install the same version again as long as that version is present. The latest version is Apex Data Loader 9. If you have previously installed Apex Data Loader 9 and want to install it again, first remove it from your computer by using the Add or Remove Programs dialog in the Windows Control Panel. 1. 2. 3. 4. 5. 6. 7. 8. 9. In the online application, click Setup Data Management Apex Data Loader. Click Download the Apex Data Loader and save the installer to your PC. Double-click the downloaded file to launch the InstallShield wizard. Click Next. Accept the license agreement and click Next. Accept the default installation directory, or click Change... to choose another directory. Click Next. Click Install. Click Finish. To start the Apex Data Loader, double-click the Apex Data Loader icon on your desktop, or choose Start All Programs salesforce.com Apex Data Loader 9.0 Apex Data Loader. Tip: If you experience login issues in the command line interface after upgrading to a new version of the Apex Data Loader, please try re-encrypting your password to solve the problem. For information on the password encryption utility, see Encrypting From the Command Line on page 21.

See Also:
What is the Apex Data Loader? When to Use the Apex Data Loader Configuring the Apex Data Loader Uninstalling the Apex Data Loader Data Loader Third-Party Licenses

Configuring the Apex Data Loader

Available in: Enterprise, Unlimited, and Developer Editions

Optionally, use the Settings menu to change the default operation settings of the Apex Data Loader. 1. Choose Settings Settings. 2. Edit the fields as desired: Field
Batch Size

Description In a single insert, update, upsert, or delete operation, records moving to or from Salesforce will be processed in increments of this size. The maximum value is 200. We recommend a value between 50 and 100. Enable this option to insert blank mapped values as null values during data operations. Note that when you are

Insert Null Values

Configuring the Apex Data Loader

Field

Description updating records, this option will instruct the Apex Data Loader to overwrite any existing data in mapped fields.

Assignment Rule

Specify the ID of the assignment rule to use for inserts, updates, and upserts. This option only applies to cases and leads. The assignment rule will override Owner values in your CSV file. Enter the URL of the Salesforce server with which you want to communicate. For example, if you are loading into a Salesforce Sandbox, change the URL appropriately. Compression enhances the performance of the Apex Data Loader and is turned on by default. You may want to disable compression if you need to debug the underlying SOAP messages. To turn off compression, enable this option. Specify for how many seconds the Apex Data Loader will wait to receive a response back from the server. In a single export or query operation, records will be returned from Salesforce in increments of this size. The maximum value is 2,000. Larger values may improve performance, but will use up more memory on the client. Enable this option to generate a success file when exporting data. This option forces files to be opened in UTF-8 encoding, even if they were saved in a different format. This option forces files to be written in UTF-8 encoding. Check this option to support the date formats dd/MM/yyyy and dd/MM/yyyy HH:mm:ss. The host name of the proxy server, if applicable. The proxy server port. The username for proxy server authentication. The password for proxy server authentication. The name of the Windows domain used for NTLM authentication. If your last operation failed, you can use this setting to begin where the last successful operation finished.

Server Host

Compression

Timeout

Query Request Size

Generate success files for exports

Read all CSVs with UTF-8 encoding

Write all CSVs with UTF-8 encoding Use European Date Format

Proxy Host Proxy Port Proxy Username Proxy Password Proxy NTLM domain

Start at row

Inserting, Updating, or Deleting Data

3. Click OK to save your settings.

See Also:
Inserting, Updating, or Deleting Data Exporting Data

Inserting, Updating, or Deleting Data

Available in: Enterprise, Unlimited, and Developer Editions

User Permissions Needed To insert records: To update records: To upsert records: To delete records: "Create" on the record "Edit" on the record "Create" or "edit" on the record "Delete" on the record

The insert, update, upsert, and delete wizards allow you to add new records, modify existing records, or delete existing records. Note that "upsert" is a combination of inserting and updating - if a record in your file matches an existing record, the existing record will be updated with the values in your file. If no match is found, then the record is created as new. 1. Start the Apex Data Loader by choosing Start Programs salesforce.com Apex Data Loader 9.0 Apex Data Loader. 2. Click Insert, Update, Upsert, or Delete. These commands can also be found in the File menu. 3. Enter your Salesforce username and password. Click Log in to log in. After your login completes successfully, click Next. (Until you log out or close the program, you will not be asked to log in again.) 4. Choose an object. If your object name does not display in the default list, check Show all objects to see a complete list of the objects that you can access. The objects will be listed by localized label name, with developer name noted in parentheses. For object descriptions, see the Apex Web Services Developers Guide. 5. Click Browse... to select your CSV file. 6. Click Next. After the object and CSV file are initialized, click OK. 7. If you are performing an upsert: a. Your CSV file must contain a column of ID values for matching against existing records. The column may be either an external ID (a custom field with the "External ID" attribute), or Id (the Salesforce record ID). From the drop-down list, select which field to use for matching. If the object has no external ID fields, Id will automatically be used. For more information on external IDs, see "Custom Field Attributes" in the Salesforce online help. Click Next to continue. b. If your file includes the external IDs of an object that has a relationship to your chosen object, enable that external ID for record matching by selecting its name from the drop-down list. If you make no selection here, you can use the related object's Id field for matching by mapping it in the next step. Click Next to continue. 8. Define how the columns in your CSV file map to Salesforce fields. Click Choose an Existing Map to select an existing field mapping, or click Create or Edit a Map to create a new map or modify an existing map. See Defining Field Mappings on page 11 for details. 9. Click Next. 10. For every operation, the Apex Data Loader generates two unique CSV log files; one filename starts with "success," while the other starts with "error." Click Browse... to specify a directory for these files. 11. Click Finish to perform the operation, and then click Yes to confirm.

Inserting, Updating, or Deleting Data

12. As the operation proceeds, a progress information window reports the status of the data movement. 13. After the operation completes, a confirmation window will summarize your results. Click View Successes to view your success file, click View Errors to open your errors file, or click OK to close. See Reviewing Output Files on page 12 for more information. Tip: If you are updating or deleting large amounts of data, review Performing Mass Updates on page 8 and Performing Mass Deletes on page 9 for tips and best practices.

See Also:
Exporting Data Configuring the Apex Data Loader Supported Data Types Recycle Bin in the Salesforce online help

Importing Attachments with the Apex Data Loader

You can use the Apex Data Loader to import attachments to Salesforce. 1. If you are migrating attachments from a source Salesforce organization to a target Salesforce organization, begin by requesting a weekly data export for the source organization. On the Schedule Export page, make sure to select the Include Attachments... checkbox, which causes the file Attachment.csv to be included in your export. You can use that file in the next step. For more information on the weekly export service, see "Exporting Backup Data" in the Salesforce online help. 2. Confirm that the CSV file you intend to use for attachment importing contains the following columns (each column represents a Salesforce field):
ParentId - the Salesforce ID of the parent record. Name - the name of the attachment file, such as myattachment.jpg. IsPrivate - "0" if the attachment is not private; "1" if it is private. OwnerId - the Salesforce ID of the record owner. Body - the Salesforce ID of the attachment.

3. Edit the values in the Body column so they contain the full filename of the attachments as they exist on your computer. For example, if an attachment with the ID "123456789" is located on your computer at C:\Export, then set the value as C:\Export\123456789. For reference, see this sample CSV file. 4. Proceed with an insert or upsert operation; see Inserting, Updating, or Deleting Data on page 7. At the Select data objects step, make sure to select the Show all Salesforce objects checkbox, and the Attachment object name in the list. Note: If your CSV file includes a column of pure attachment ID values, you can use a Microsoft Excel formula field to prepend the directory path in front of the ID value.

See Also:
Inserting, Updating, or Deleting Data

Performing Mass Updates

To update a large number of records at one time, we recommend the following steps:

Exporting Data

1. Obtain your data by performing an export of the objects you wish to update, or by running a report. See Exporting Data on page 9, or view the Salesforce online help for information on running reports. Make sure your report includes the record ID. 2. As a backup measure, save an extra copy of the generated CSV file. 3. Open your working file in a CSV editor such as Excel, and update your data. 4. Launch the Apex Data Loader and follow the update wizard. Note that matching will be done according to record ID. See Inserting, Updating, or Deleting Data on page 7. 5. After the operation, review your success and error log files. See Reviewing Output Files on page 12. 6. If you made a mistake, use the backup file to update the records to their previous values.

See Also:
Overview of Reports in the Salesforce online help

Performing Mass Deletes

To use the Apex Data Loader to delete a large number of records at one time, we recommend the following steps: 1. As a backup measure, export the objects you wish to delete, being sure to select all fields. (See Exporting Data on page 9.) Save an extra copy of the generated CSV file. 2. Next, export the objects you wish to delete, this time using only the record ID as the desired criteria. 3. Launch the Apex Data Loader and follow the delete wizard. Map only the ID column. See Inserting, Updating, or Deleting Data on page 7. 4. After the operation, review your success and error log files. See Reviewing Output Files on page 12.

Exporting Data
Available in: Enterprise, Unlimited, and Developer Editions

User Permissions Needed To export records: "Read" on the records

You can use the Apex Data Loader export wizard to extract data from any Salesforce object. 1. Start the Apex Data Loader by choosing Start Programs salesforce.com Apex Data Loader 9.0 Apex Data Loader. 2. Click Export. This command can also be found in the File menu. 3. Enter your Salesforce username and password. Click Log in to log in. After your login completes successfully, click Next. (Until you log out or close the program, you will not be asked to log in again.) 4. Choose an object. If your object name does not display in the default list, check Show all objects to see a complete list of objects that you can access. The objects will be listed by localized label name, with developer name noted in parentheses. For object descriptions, see the Apex Web Services Developers Guide. 5. Click Browse... to select the CSV file to which the data will be exported. You can enter a new filename to create a new file or choose an existing file. If you select an existing file, the contents of that file will be replaced. Click Yes to confirm this action, or click No to choose another file. 6. Click Next.

Supported Data Types

7. Create a SOQL query for the data export. SOQL is the Sforce Object Query Language that allows you to construct simple but powerful query strings. Similar to the SELECT command in SQL, SOQL allows you to specify the source object (such as account), a list of fields to retrieve, and conditions for selecting rows in the source object. See the a. Choose the fields you want to export. b. Optionally, select conditions to filter your data set. If you do not select any conditions, all the data to which you have read access will be returned. c. Review the generated query and edit if necessary. For more information on SOQL, see the Apex Web Services Developers Guide. 8. Click Finish, then click Yes to confirm. 9. As the operation proceeds, a progress information window reports the status of the data movement. 10. After the operation completes, a confirmation window will summarize your results. Click View Extraction to view the CSV file, or click OK to close. See Reviewing Output Files on page 12 for details. Note: The Apex Data Loader currently does not support the extraction of attachments. As a workaround, we recommend that you use the weekly export feature in the online application to export attachments.

See Also:
Inserting, Updating, or Deleting Data Configuring the Apex Data Loader

Supported Data Types

Available in: Enterprise, Unlimited, and Developer Editions

Base64 String path to file (converts the file to the base64 array)

Boolean True values (case insensitive) = "yes", "y", "true", "on", "1" False values (case insensitive) = "no", "n", "false", "off ", "0"

Date Formats We recommend you specify dates in the format yyyy-MM-ddTHH:mm:ss.SSS+/-HHmm, where:
yyyy is the four-digit year MM is the two-digit month (01-12) dd is the two-digit day (01-31) HH is the two-digit hour (00-23) mm is the two-digit minute (00-59) ss is the two-digit seconds (00-59) SSS is the three-digit milliseconds (000-999) +/-HHmm is the Zulu (UTC) time zone offset

A compete list of supported date formats follows:

10

Defining Field Mappings

yyyy-MM-dd'T'HH:mm:ss.SSS'Z' yyyy-MM-dd'T'HH:mm:ss.SSS Pacific Standard Time yyyy-MM-dd'T'HH:mm:ss.SSSPacific Standard Time yyyy-MM-dd'T'HH:mm:ss.SSS PST yyyy-MM-dd'T'HH:mm:ss.SSSPST yyyy-MM-dd'T'HH:mm:ss.SSS GMT-08:00 yyyy-MM-dd'T'HH:mm:ss.SSSGMT-08:00 yyyy-MM-dd'T'HH:mm:ss.SSS -800 yyyy-MM-dd'T'HH:mm:ss.SSS-800 yyyy-MM-dd'T'HH:mm:ss yyyy-MM-dd HH:mm:ss yyyyMMdd'T'HH:mm:ss yyyy-MM-dd MM/dd/yyyy HH:mm:ss MM/dd/yyyy Note: In the Settings dialog of the user interface, you can select the Use European date format box to enable date formats that begin with the day rather than the month. These formats aredd/MM/yyyy and dd/MM/yyyy HH:mm:ss. If your computers locale is east of Greenwich Mean Time (GMT), we recommend that you change your computer setting to GMT in order to avoid date adjustments when inserting or updating records. A knowledge base solution for this issue is available in the Salesforce Help & Training window; search for "data loader date."

Double ID A Salesforce ID is a case-sensitive 15-character or 18-character alphanumeric string that uniquely identifies a particular record. Standard double string

Integer Standard integer string

String All valid XML strings; invalid XML characters are removed.

See Also:
Inserting, Updating, or Deleting Data Importing Attachments with the Apex Data Loader

Defining Field Mappings

Available in: Enterprise, Unlimited, and Developer Editions

11

Reviewing Output Files

At the Mapping Dialog window of the Apex Data Loader, you associate Salesforce fields with the columns of your CSV file. 1. To automatically match fields with columns, click Auto-Match Fields to Columns.The Apex Data Loader will automatically populate the list at the bottom of the window, based on the similarity of field and column names. 2. To manually match fields with columns, click and drag fields from the list of Salesforce fields at the top to the list of CSV column header names at the bottom. 3. Optionally, click Save Mapping to save this mapping for future use. Specify a name for the SDL file. If you select an existing file, the contents of that file will be replaced. Click Yes to confirm this action, or click No to choose another file. 4. Click OK to use your mapping for the current operation.

See Also:
Inserting, Updating, or Deleting Data

Reviewing Output Files

Available in: Enterprise, Unlimited, and Developer Editions

After every import or export, the Apex Data Loader generates two unique CSV log files; one filename starts with "success," while the other starts with "error." During every export, the Apex Data Loader saves extracted data to a CSV file that you specify in the wizard. The Apex Data Loader has a built-in CSV file viewer with which you can open these files. To view log files: 1. Choose View CSV from the View menu of the Apex Data Loader. 2. Specify a number of rows to view. Each row in the CSV file corresponds to one Salesforce record. The default is 1000. 3. To view a CSV file of your choice, click Open CSV. To view the last success log file, click Open Success. To view the last error log file, click Open Error. 4. The CSV file will open in a new window. Optionally, click Open in External Program to open the file in the associated external program, such as Microsoft Office Excel. The "success" file contains all records that were successfully loaded. In it, there is a column for newly generated record IDs. The "error" file contains all records that were rejected from the load operation. In it, there is a column that describes why the load failed. 5. Click Close to return to the CSV Chooser window, and then click OK to exit the window.

See Also:
Inserting, Updating, or Deleting Data Exporting Data

Using the Command Line Interface

Available in: Enterprise, Unlimited, and Developer Editions

For operations such as nightly scheduled loads and extractions, you may prefer to run Apex Data Loader from the command line. From the command line, the following calls are supported:

12

Running in Batch Mode

java jar DataLoader.jar com.salesforce.lexiloader.process.ProcessRunner with DataLoader.jar in the classpath

Type -help at the command line to view tips and instructions. You can set the following option:
-Dsalesforce.config.dir=CONFIG_DIRECTORY

The Apex Data Loader will run whatever operation, file, or map is specified in the configuration file that you specify. If you do not specify a configuration directory, the current directory is used. By default, Apex Data Loader configuration files are installed at the following location:
C:\Program Files\salesforce.com\Apex Data Loader 9.0\conf

The batch process configuration file is process-conf.xml. If you use process-conf.xml, setting process.name to the name of a process specifies a process to run. Otherwise, the config.properties file will be used for parameter settings. For more information on batch mode, see Running in Batch Mode on page 13. If you want to implement enhanced logging, use a copy of log-conf.xml. You can change parameters at runtime by giving <param>=<value> as program arguments. For example:
java -Xms256m -Xmx256m -Dsalesforce.config.dir=c:\config jar DataLoader.jar process.operation=inserts

where process.operation=insert will change the configuration at runtime. Note: These topics only apply to version 8.0 and later. If you have an earlier version of the Apex Data Loader, see the following blog post for command line instructions: http://blog.sforce.com/sforce/2005/06/sforce_data_loa.html Tip: If you experience login issues in the command line interface after upgrading to a new version of the Apex Data Loader, please try re-encrypting your password to solve the problem. For information on the password encryption utility, see Encrypting From the Command Line on page 21.

See Also:
Running in Batch Mode What is the Apex Data Loader?

Running in Batch Mode

On the Windows 2000 and Windows XP platforms, you can run the Apex Data Loader in batch mode from the command line. See the following topics: Understanding Installed Directories and Files on page 14 Spring Framework Overview on page 15 Running Individual Batch Processes on page 15 Configuring Batch Processes on page 16 Configuring Database Access on page 16 SQL Configuration on page 17 Mapping Columns on page 19 Command Line Operations on page 20 Data Access Objects on page 20 Encrypting From the Command Line on page 21

13

Running in Batch Mode

Note: If you have used the batch mode from the command line with a version earlier than 8.0, see Upgrading Your Batch Mode Interface on page 14.

See Also:
Using the Command Line Interface What is the Apex Data Loader?

Upgrading Your Batch Mode Interface

The batch mode interface in versions 8.0 and later of the Apex Data Loader are not backwards-compatible with earlier versions. If you are using a version earlier than 8.0 to run batch processes, your options are as follows: Maintain the old version for batch use Do not uninstall your old version of the Apex Data Loader. Continue to use that version for batch processes. You will not be able to take advantage of newer features such as database connectivity, but your integrations will continue to work. Optionally, install the new version alongside the old version and dedicate the old version solely to batch processes. Generate a new config.properties file from the new GUI If you originally generated your config.properties file from the graphical user interface, use the new version to set the same properties and generate a new file. Use this new file with the new batch mode interface. For more information, see Running in Batch Mode on page 13. Manually update your config.properties file If your old config.properties file was created manually, then you need to manually update it for the new version. For more information, see Understanding Installed Directories and Files on page 14.

Understanding Installed Directories and Files

In versions 8.0 and later, installing the Apex Data Loader creates several directories under the installation directory. The following directories are involved in running the program from the command line: bin directory Contains the batch files encrypt.bat for encrypting passwords and process.bat for running batch processes. These batch files can only be executed on a Windows platform. However, the commands they contain will be similar for other platforms. For information on running the Apex Data Loader from the command line on any platform, see Using the Command Line Interface on page 12. conf directory The default configuration directory. Contains the configuration files config.properties, Loader.class, and log-conf.xml. The config.properties file that is generated when you modify the Settings dialog in the graphical user interface is located at C:\Documents and Settings\<your Windows username>\Application Data\salesforce.com\Apex Data Loader 9.0. You can copy this file to the conf installation directory to use it for batch processes. samples directory Contains three subdirectories of sample files for reference.

14

Running in Batch Mode

File Path Convention The file paths provided in these topics start one level below the installation directory. For example, \bin means C:\Program Files \salesforce.com\Apex Data Loader 9.0\bin, provided you accepted the default installation directory. If you installed the program to a different location, please substitute that directory path as appropriate.

See Also:
Running in Batch Mode

Spring Framework Overview

The Apex Data Loader configuration files are based on the Spring Framework, which is an open source full-stack Java/J2EE application framework. The Spring Framework allows you to use XML files to configure beans. Each bean represents an instance of an object; the parameters correspond to each object's setter methods. A typical bean has the following attributes:
id

Uniquely identifies the bean to XmlBeanFactory, which is the class that gets objects from an XML configuration file.
class

Specifies the implementation class for the bean instance. For more information on the Spring Framework, see the official documentation and the support forums. Note that salesforce.com cannot guarantee the availability or accuracy of external web sites.

See Also:
Running in Batch Mode

Running Individual Batch Processes

To start an individual batch process use\bin\process.bat, which requires the following parameters: A configuration directory The default is \conf. To use an alternate directory, create a new directory and add the following files to it: If your process is not interactive, copy process-conf.xml from \samples\conf. If your process requires database connectivity, copy database-conf.xml from \samples\conf. Copy config.properties from \conf.

A process name The name of the ProcessRunner bean from \samples\conf\process-conf.xml. Process Example
process ./conf accountMasterProcess

15

Running in Batch Mode

Note: You can configure external process launchers such as the Microsoft Windows XP Scheduled Task Wizard or a UNIX cron job to run processes on a schedule.

See Also:
Configuring Batch Processes Running in Batch Mode Spring Framework Overview Running in Batch Mode

Configuring Batch Processes

Use \samples\conf\process-conf.xml to configure your Apex Data Loader processes, which are represented by ProcessRunner beans. A process should have ProcessRunner as the class attribute and the following properties set in the configuration file:
name

Sets the ProcessRunner name, which is also used as the nongeneric thread name and for configuration backing files (see below).
configOverrideMap

A property of type map where each entry represents a configuration setting: the key is the setting name; the value is the setting value. The configuration backing file stores configuration parameter values from the last run and is used to load default configuration parameters.The settings in configOverrideMap take precedence over those in the configuration backing file.The configuration backing file is managed programmatically and does not require any manual edits. For the names and descriptions of available process configuration parameters, see Data Loader Process Configuration Parameters.

See Also:
Running Individual Batch Processes Spring Framework Overview Running in Batch Mode

Configuring Database Access

When running the Apex Data Loader in batch mode from the command line, use \samples\conf\database-conf.xml to configure database access objects.

DatabaseConfig Bean
The top-level database configuration object is the DatabaseConfig bean, which has the following properties:
sqlConfig

The SQL configuration bean for the data access object that interacts with a database.
dataSource

The bean that acts as database driver and authenticator. It must refer to an implementation of javax.sql.DataSource such as org.apache.commons.dbcp.BasicDataSource.

16

Running in Batch Mode

DatabaseConfig Example
<bean id="AccountInsert" class="com.salesforce.lexiloader.dao.database.DatabaseConfig" singleton="true"> <property name="sqlConfig" ref="accountInsertSql"/> </bean>

See Also:
Data Access Objects SQL Configuration Configuring Batch Processes Spring Framework Overview Running in Batch Mode

DataSource
The DataSource bean sets the physical information needed for database connections. It typically has the following properties, at minimum:
driverClassName

The fully qualified name of the implementation of a JDBC driver.

url

The string for physically connecting to the database.

username

The username for logging in to the database.

password

The password for logging in to the database. Depending on your implementation, additional information may be required. For example, use org.apache.commons.dbcp.BasicDataSource when database connections are pooled. DataSource Example
<bean id="oracleRepDataSource" class="org.apache.commons.dbcp.BasicDataSource" destroy-method="close"> <property name="driverClassName" value="oracle.jdbc.driver.OracleDriver"/> <property name="url" value="jdbc:oracle:thin:@myserver.internal.salesforce.com:1521:TEST"/> <property name="username" value="test"/> <property name="password" value="test"/> </bean>

SQL Configuration
When running the Apex Data Loader in batch mode from the command line, sqlConfig contains configuration parameters for accessing specific data in the database. As shown in the code samples below, queries and inserts are different but very similar. The bean must be of type com.salesforce.lexiloader.dao.database.SqlConfig and have the following properties:
sqlString

The SQL code to be used by the data access object.

17

Running in Batch Mode

The SQL can contain replacement parameters that make the string dependent on configuration or operation variables. Replacement parameters must be delimited on both sides by "@" characters. For example, @process.lastRunDate@.
sqlParams

A property of type map that contains descriptions of the replacement parameters specified in sqlString. Each entry represents one replacement parameter: the key is the replacement parameter's name, the value is the fully qualified Java type to be used when the parameter is set on the SQL statement. Note that "java.sql" types are sometimes required, such as java.sql.Date instead of java.util.Date. For more information, see the official JDBC API documentation.
columnNames

Used when queries (SELECT statements) return a JDBC ResultSet. Contains column names for the data outputted by executing the SQL. The column names are used to access and return the output to the caller of the DataReader interface. SQL Query Bean Example
<bean id="accountMasterSql" class="com.salesforce.lexiloader.dao.database.SqlConfig" singleton="true"> <property name="sqlString"/> <value> SELECT distinct '012x00000000Ij7' recordTypeId, accounts.account_number, org.organization_name, concat (concat(parties.address1, ' '), parties.address2) billing_address, locs.city, locs.postal_code, locs.state, locs.country, parties.sic_code from ar.hz_cust_accounts accounts, ar.hz_organization_profiles org, ar.hz_parties parties, ar.hz_party_sites party_sites, ar.hz_locations locs where accounts.PARTY_ID = org.PARTY_ID and parties.PARTY_ID = accounts.PARTY_ID and party_sites.PARTY_ID = accounts.PARTY_ID and locs.LOCATION_ID = party_sites.LOCATION_ID and (locs.last_update_date > @process.lastRunDate@ OR accounts.last_update_date > @process.lastRunDate@ </value> </property> <property name="columNames"> <list> <value>recordTypeId</value> <value>account_number</value> <value>organization_name</value> <value>billing_address</value> <value>city</value> <value>postal_code</value> <value>state</value> <value>country</value> <value>sic_code</value> </list> ....</property> <property name="sqlParams"> <map> <entry key="process.lastRunDate" value="java.sql.Date"/>

18

Running in Batch Mode

</map> </property> </bean>

SQL Insert Bean Example

<bean id="partiesInsertSql" class="com.salesforce.lexiloader.dao.database.SqlConfig" singleton="true"> <property name="sqlString"/> <value> INSERT INTO REP.INT_PARTIES ( BILLING_ADDRESS, SIC_CODE) VALUES (@billing_address@, @sic_code@) </value> </property> <property name="sqlParams"/> <map> <entry key="billing_address" value="java.lang.String"/> <entry key="sic_code" value="java.lang.String"/> </map> </property> </bean>

See Also:
Configuring Database Access Data Access Objects Spring Framework Overview Running in Batch Mode

Mapping Columns
When running the Apex Data Loader in batch mode from the command line, you must create a properties file that maps values between Salesforce and data access objects. 1. Create a new file. 2. Observe the following syntax: On each line, pair a data source with its destination. Put the data source on the left, an equals sign (=) as a separator, and the destination on the right. Data sources can be either column names or constants. Surround constants with double quotation marks, as in "sampleconstant". Values without quotation marks are treated as column names. Destinations must be column names. You may map constants by surrounding them with double quotation marks, as in "United States"=BillingCountry.

3. In your configuration file, use the parameter process.mappingFile to specify the name of your mapping file. Column Mapping Example for Data Insert The Salesforce fields are on the right.
SLA__C=SLA__c BILLINGCITY=BillingCity SYSTEMMODSTAMP= OWNERID=OwnerId CUSTOMERPRIORITY__C=CustomerPriority__c ANNUALREVENUE=AnnualRevenue

19

Running in Batch Mode

DESCRIPTION=Description BILLINGSTREET=BillingStreet SHIPPINGSTATE=ShippingState

Column Mapping Example for Data Export The Salesforce fields are on the left.
Id=account_number Name=name Phone=phone

See Also:
Configuring Batch Processes Running in Batch Mode

Command Line Operations

When running the Apex Data Loader in batch mode from the command line, several operations are supported. An operation represents the flow of data between Salesforce and an external data source such as a CSV file or a database. See the following list of operation names and descriptions.
Extract

Uses a Salesforce Object Query Language (SOQL) string to export a set of records from Salesforce, then writes the exported data to a data source. For more information about SOQL, visit the Apex Developer Network.
Insert

Loads data from a data source into Salesforce as new records.

Update

Loads data from a data source into Salesforce, where existing records with matching ID fields will be updated.
Upsert

Loads data from a data source into Salesforce, where existing records with a matching custom external ID field will be updated; records without matches will be inserted as new records.
Delete

Loads data from a data source into Salesforce, where existing records with matching ID fields will be deleted.

See Also:
Data Access Objects Running in Batch Mode

Data Access Objects

When running the Apex Data Loader in batch mode from the command line, several data access objects are supported. A data access object allows access to an external data source outside of Salesforce. They can implement a read interface (DataReader), a write interface (DataWriter), or both. See the following list of object names and descriptions.

20

Running in Batch Mode

csvRead Allows the reading of a comma or tab-delimited file. There should be a header at the top of the file that describes each column. csvWrite Allows writing to a comma or tab-delimited file. A header will be outputted at the top of the file based on the column list provided by the caller. databaseRead Allows the reading of a database. Use database-conf.xml to configure database access. For more information, see Configuring Database Access on page 16. databaseWrite Allows writing to a database. Use database-conf.xml to configure database access. For more information, see Configuring Database Access on page 16.

See Also:
Command Line Operations Running in Batch Mode

Encrypting From the Command Line

When running the Apex Data Loader in batch mode from the command line, you must encrypt the following configuration parameters:
sfdc.password sfdc.proxyPassword

Use the utility described below to perform encryption. Using the Encryption Utility The Apex Data Loader offers an encryption utility to secure passwords specified in configuration files. To use the encryption utility: 1. Run \bin\encrypt.bat. 2. At the command line, follow the prompts provided to execute the following actions: Generate a key Key text is generated onscreen from the text you provide. Carefully copy the key text to a key file, omitting any leading or trailing spaces. The key file can then be used for encryption and decryption. Encrypt text Generates an encrypted version of a password or other text. Optionally, you can provide a key file for the encryption. In the configuration file, make sure that the encrypted text is copied precisely and the key file is mentioned.

21

Uninstalling the Apex Data Loader

Verify encrypted text Given encrypted and decrypted versions of a password, verifies whether the encrypted password provided matches its decrypted version. A success or failure message will be printed to the command line.

See Also:
Configuring Batch Processes Running in Batch Mode

Uninstalling the Apex Data Loader

Available in: Enterprise, Unlimited, and Developer Editions

To uninstall the Apex Data Loader client application: 1. Go to Start Control Panel Add or Remove Programs. 2. Select the program Apex Data Loader 9. 3. Click Remove. The uninstaller will remove the program from your computer.

See Also:
Installing the Apex Data Loader

Data Loader Third-Party Licenses

Available in: Enterprise, Unlimited, and Developer Editions

The following third-party licenses are included with the installation of the Apex Data Loader: Technology Axis Ant Apache Jakarta Commons BeanUtils Apache Commons Collections Apache Commons Database Connection Pooling (DBCP) Apache Commons Logging Version Number 1.1 1.6 3.1 1.2.1 1.0.3 License http://www.apache.org/licenses/LICENSE-1.1 http://www.apache.org/licenses/LICENSE-1.1 http://jakarta.apache.org/commons/license.html http://jakarta.apache.org/commons/license.html http://jakarta.apache.org/commons/license.html http://jakarta.apache.org/commons/license.html http://www.apache.org/licenses/LICENSE-2.0.html http://www.eclipse.org/org/documents/epl-v10.html http://www.opensymphony.com/quartz/license.action

Apache Commons Object Pooling 1.2 Library Apache Log4j Eclipse SWT 1.2.8 3.063

OpenSymphony Quartz Enterprise 1.5.1 Job Scheduler

22

Data Loader Third-Party Licenses

Technology Rhino JavaScript for Java Spring Framework

Version Number 1.6R2 1.2.6

License http://www.mozilla.org/MPL/MPL-1.1.txt http://www.apache.org/licenses/LICENSE-2.0.txt

Note: salesforce.com is not responsible for the availability or content of third-party Web sites.

See Also:
Installing the Apex Data Loader

23

Index

Index
A
Apex Data Loader about 3 batch files 14 batch mode 13 column mapping 19 command line interface 12 command line operations 20 configuring 5 configuring batch processes 16 importing attachments 8 installed files 14 installing 4 password encryption 21 sample files 14 Spring Framework 15 starting batch processes 15 Apex Data Loader (continued) system requirements 4 third-party licenses 22 uninstalling 22 when to use 3 AppExchange Data Loader See Apex Data Loader 3

D
Data Loader See Apex Data Loader 3

S
Sforce Data Loader See Apex Data Loader 3 Spring Framework, see Apex Data Loader 15

24