Metadata API Developer Guide
jNewer Version Available
deploy()
Uses file representations of components to create, update, or delete those components in an Salesforce org.
Syntax
Usage
Use this call to take file representations of components and deploy them into an org by creating, updating, or deleting the components they represent.
In API version 29.0, Salesforce improved the deployment status properties and removed the requirement to use checkStatus() after a deploy() call to get information about deployments. Salesforce continues to support the use of checkStatus() when using deploy() with API version 28.0 or earlier.
For API version 29.0 or later, deploy (create or update) packaged or unpackaged components using the following steps.
- Issue a deploy() call to start the asynchronous deployment. An AsyncResult object is returned. Note the value in the id field and use it for the next step.
- Issue a checkDeployStatus() call in a loop until the done field of the returned DeployResult contains true, which means that the call is completed. The DeployResult object contains information about an in-progress or completed deployment started using the deploy() call. When calling checkDeployStatus(), pass in the id value from the AsyncResult object from the first step.
For API version 28.0 or earlier, deploy (create or update) packaged or unpackaged components using the following steps.
- Issue a deploy() call to start the asynchronous deployment. 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 first result. If it is completed, note the value in the id field returned and skip the next step.
- 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 deploy() call in the previous step. Check the AsyncResult object which is returned until the done field contains true. The time taken to complete a deploy() call depends on the size of the zip file being deployed, so a longer wait time between iterations should be used as the size of the zip file increases.
- Issue a checkDeployStatus() call to obtain the results of the deploy() call, using the id value returned in the first step.
To track the status of deployments that are in progress or completed in the last 30 days, from Setup, enter Deployment Status in the Quick Find box, then select Deployment Status.
You can cancel a deployment while it’s in progress or in the queue by clicking Cancel next to the deployment. The deployment then has the status Cancel Requested until the deployment is completely canceled. A canceled deployment is listed in the Failed section.
The package.xml file is a project manifest that lists all the components that you want to retrieve or deploy. You can use package.xml to add components. To delete components, add another manifest file. See Deleting Components from an Organization.
Arguments
| Name | Type | Description |
|---|---|---|
| zipFile | base64 | Base 64-encoded binary data. Client applications must encode the binary data as base64. |
| deployOptions | DeployOptions | Encapsulates options for determining which packages or files are deployed. |
DeployOptions
The following deployment options can be selected for this call:
| Name | Type | Description |
|---|---|---|
| allowMissingFiles | boolean | Specifies whether a deploy succeeds, even if files that are specified in package.xml are not in the .zip file. |
| autoUpdatePackage | boolean | If a file is in the .zip
file but not specified in package.xml,
specifies whether the file is automatically added to the package. A
retrieve() is issued with the updated
package.xml that includes the .zip file. Do not set this argument for deployment to production orgs. |
| checkOnly | boolean | Defaults to false. Set to true to perform a test deployment (validation) of components without saving the components in the target org. A validation enables you to verify the results of tests that would be generated in a deployment, but doesn’t commit any changes. After a validation finishes with passing tests, it might qualify for deployment without rerunning tests. See deployRecentValidation(). |
| ignoreWarnings | boolean |
Indicates whether a warning
should allow a deployment to complete successfully (true) or not (false). Defaults to false. The DeployMessage object for a warning contains the following values:
If a warning occurs and ignoreWarnings is set to true, the success field in DeployMessage is true. If ignoreWarnings is set to false, success is set to false and the warning is treated like an error. This field is available in API version 18.0 and later. Prior to version 18.0, there was no distinction between warnings and errors. All problems were treated as errors and prevented a successful deployment. |
| performRetrieve | boolean | Indicates whether a retrieve() call is performed immediately after the deployment (true) or not (false). Set to true in order to retrieve whatever was just deployed. |
| purgeOnDelete | boolean |
If true, the deleted components in the
destructiveChanges.xml manifest file
aren't stored in the Recycle Bin. Instead, they become immediately eligible for
deletion. This field is available in API version 22.0 and later. This option only works in Developer Edition or sandbox orgs; it doesn't work in production orgs. |
| rollbackOnError | boolean | Indicates whether any failure causes a complete rollback (true) or not (false). If false, whatever set of actions can be performed without errors are performed, and errors are returned for the remaining actions. This parameter must be set to true if you are deploying to a production org. The default is false. |
| runAllTests | boolean | (Deprecated and only available in API version 33.0 and earlier.) This field defaults to false. Set to true to run all Apex tests after deployment, including tests that originate from installed managed packages. |
| runTests | string[] | A list of Apex tests to run during deployment. Specify the class name, one name
per instance. The class name can also specify a namespace with a dot
notation. For more information, see Running a Subset of Tests in a Deployment. To use this option, set testLevel to RunSpecifiedTests. |
| singlePackage | boolean | Indicates whether the specified .zip file points to a directory structure with a single package (true) or a set of packages (false). |
| testLevel | TestLevel (enumeration of type string) | Optional. Specifies which tests are run as part of a deployment.
The test level is enforced regardless of the types of components that are present in the
deployment package. Valid values are:
If you don’t specify a test level, the default test execution behavior is used. See Running Tests in a Deployment. This field is available in API version 34.0 and later. |
Response
Sample Code—Java
This sample shows how to deploy components in a zip file. See the retrieve() sample code for details on how to retrieve a zip file.