Understanding retrieve

Use the retrieveCode target to retrieve classes and triggers from your sandbox or production organization. During the normal deploy cycle, you would run retrieveCode prior to deploy, in order to obtain the correct directory structure for your new classes and triggers. However, for this example, deploy is used first, to ensure that there is something to retrieve.

To retrieve classes and triggers from an existing organization, use the retrieve ant task as illustrated by the sample build target ant retrieveCode:

<target name="retrieveCode">
   <!-- Retrieve the contents listed in the file codepkg/package.xml into the codepkg directory -->
   <sf:retrieve username="${sf.username}" password="${sf.password}" 
        serverurl="${sf.serverurl}" retrieveTarget="codepkg" unpackaged="codepkg/package.xml"/>
</target>

The file codepkg/package.xml lists the metadata components to be retrieved. In this example, it retrieves two classes and one trigger. The retrieved files are put into the directory codepkg, overwriting everything already in the directory.

The properties for the retrieve task are as follows:

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. A session is created after a user logs in to Salesforce successfully with a username and password. Use a session ID for logging into an existing session instead of creating a new session.
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 35.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.
Previous
Next