retrieve()

Syntax

Usage

Use this call to retrieve file representations of components in an organization.

In API version 31.0 and later, the process of making a retrieve() call has been simplified. You no longer have to call checkStatus() after a retrieve() call to obtain the status of the retrieve operation. Instead, make calls to checkRetrieveStatus() only. If the retrieve operation is in progress, call checkRetrieveStatus() again until the retrieve operation is completed. The checkStatus() call is still supported in versions API version 30.0 or earlier, but is not available in API version 31.0 and later.

For API version 31.0 or later, retrieve packaged or unpackaged components by using the following steps.

1. Issue a retrieve() call to start the asynchronous retrieval. An AsyncResult object is returned. Note the value in the id field and use it for the next step.
2. Issue a checkRetrieveStatus() call and pass in the id value from the AsyncResult object from the first step. Check the value of the done field of the returned RetrieveResult. If it is true, this means that the call is completed and proceed to the next step. Otherwise, repeat this step to call checkRetrieveStatus() again until the done field is true.
3. Retrieve the zip file (zipFile field) and other desired fields from RetrieveResult that was returned by the final call to checkRetrieveStatus() in the previous step.

For API version 30.0 or earlier, retrieve packaged or unpackaged components by using the following steps.

1. Issue a retrieve() call to start the asynchronous retrieval. An AsyncResult object is returned. If the call is completed, the done field contains true. Most often, the call is not completed quickly enough to be noted in the result. If it is completed, note the value in the id field returned and skip the next step.
2. If the call is not complete, issue a checkStatus() call in a loop using the value in the id field of the AsyncResult object, returned by the retrieve() call in the previous step. Check the AsyncResult object returned until the done field contains true. The time taken to complete a retrieve() call depends on the size of the zip file being deployed, so use a longer wait time between iterations as the size of the zip file increases.
3. Issue a checkRetrieveStatus() call to obtain the results of the retrieve() call, using the id value returned in the first step.

For examples of manifest files, see Sample package.xml Manifest Files.

Permissions

Your client application must be logged in with the “Modify All Data” permission.

Arguments

Response

AsyncResult

Sample Code—Java

This sample shows how to retrieve components into a zip file. See the deploy() sample code for details on how to deploy a zip file.