Force.com Migration Tool Guide
jNewer Version Available
Creating Retrieve Targets
The build.xml file specifies a series of commands to be executed by Ant. Within the build.xml file are named targets that process a series of commands when you run Ant with a target name. The following parameters may be set for each <sf:retrieve> target:
| Field | Description |
|---|---|
| username | Required if sessionId isn’t specified. The Salesforce username for login. The username associated with this connection must have the “Modify All Data” permission. Typically, this is only enabled for System Administrator users. |
| password | Required if sessionId isn’t specified. The password you use to log into 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 to test.salesforce.com. |
| retrieveTarget | Required. The root of the directory structure into which the metadata files are retrieved. |
| packageNames | Required if unpackaged is not specified. A comma-separated list of the names of the packages to retrieve. You must specify either packageNames or unpackaged, but not both. |
| apiVersion | Optional. The Metadata API version to use for the retrieved metadata files. The default is 38.0. |
| pollWaitMillis | Optional. Defaults to 10000. The number of milliseconds to wait between attempts when polling for results of the retrieve request. The client continues to poll the server up to the limit defined by maxPoll. |
| maxPoll | Optional. Defaults to 200. The number of times to poll the server for the results of the retrieve request. The wait time between successive poll attempts is defined by pollWaitMillis. |
| singlePackage | Optional. Defaults to true. This must be set to false if you are retrieving multiple packages. If set to false, the retrieved zip file includes an extra top-level directory containing a subdirectory for each package. |
| trace | Optional. Defaults to false. Prints the SOAP requests and responses to the console. Note that this will show the user's password in plain text during login. |
| unpackaged | Required if packageNames is not specified. The path and name of a file manifest that specifies the components to retrieve. You must specify either unpackaged or packageNames, but not both. |
| 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. |
Retrieving Components in Bulk
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 for login. The username associated with this connection must have the “Modify All Data” permission. Typically, this is only enabled for System Administrator users. |
| password | Required if sessionId isn’t specified. The password you use to log into 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 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 38.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>