Ant Migration Tool Guide

Ant Migration Tool
Installing the Ant Migration Tool
Using the Ant Migration Tool
Entering Salesforce Connection Information
Constructing a Project Manifest
Creating Retrieve Targets
Retrieving Unpackaged Components
Retrieving Managed or Unmanaged Packages
Retrieving Components in Bulk
Retrieving Metadata from a Salesforce Organization
Editing Metadata
Deleting Files from an Organization
Deploying Changes to a Salesforce Org
Checking the Status of a Task
Common Migration Issues
PDF

Newer Version Available

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

Retrieving Components in Bulk

The Ant Migration Tool is retired with Spring ’24. The tool continues to function for future API versions but isn’t updated with new functionality and isn’t supported. To manage metadata changes, switch to Salesforce CLI for a modern, supported developer experience.

Note

This target is the optimal way to download a large number of components of a single metadata type, such as custom reports, into a set of local files. The following parameters may be set for each <sf:bulkRetrieve> target:

Field Description
username Required if sessionId isn’t specified. The Salesforce username used for login. The username associated with this connection must have the Modify Metadata through Metadata API Functions permission.
password Required if sessionId isn’t specified. The password you use to log in to the organization associated with this project. If you are using a security token, paste the 25-digit token value to the end of your password.
sessionId Required if username and password aren’t specified. The ID of an active Salesforce session or the OAuth access token. A session is created after a user logs in to Salesforce successfully with a username and password. Use a session ID for logging in to an existing session instead of creating a new session. Alternatively, use an access token for OAuth authentication. For more information, see Authenticating Apps with OAuth in the Salesforce Help.
serverurl Optional. The Salesforce server URL (if blank, defaults to login.salesforce.com). To connect to a sandbox instance, change this value to test.salesforce.com.
retrieveTarget Required. The root of the directory structure into which the metadata files are retrieved.
metadataType Required. The name of the metadata type to be retrieved; for example, CustomObject for custom objects, or Report for custom reports. For a full list of allowed values, see Component Types.
containingFolder Optional. If the metadata is contained in a folder, this parameter should be the name of the folder from which the contents are retrieved.
batchSize Optional, defaults to 10. The number of items to retrieve while doing multi-part retrieve.
apiVersion Optional. The Metadata API version to use for the retrieved metadata files. The default is 65.0.
maxPoll Optional. Defaults to 200. The number of times to poll the server for the results of the retrieve request. The clients waits for two seconds after the first poll attempt. The wait time is doubled for each successive poll attempt up to maximum of 30 seconds between poll attempts.
unzip Optional. Defaults to true. If set to true, the retrieved components are unzipped. If set to false, the retrieved components are saved as a zip file in the retrieveTarget directory.

To retrieve custom report components in bulk, specify a target in the build.xml file using <sf:bulkRetrieve>.

1<target name="bulkRetrieve">
2  <sf:bulkRetrieve
3    username="${sf.username}"
4    password="${sf.password}"
5    sessionId="${sf.sessionId}"
6    serverurl="${sf.serverurl}"
7    metadataType="Report"
8    retrieveTarget="retrieveUnpackaged"/>
9</target>