deploy()

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.

Here are the deploy limits. Limits can change without notice.

Feature	Limit
Maximum compressed .zip folder size¹	Approximately 39 MB
Maximum uncompressed folder size²	Approximately 600 MB
Maximum number of files in AppExchange packages	35,000
Maximum number of files in packages	10,000

¹ Metadata API base-64 encodes components after they’re compressed. The resulting .zip file can't exceed 50 MB. Base-64 encoding increases the size of the payload by approximately 22%, so your compressed payload can't exceed approximately 39 MB before encoding.

² When using the Ant Migration Tool to deploy an unzipped project, all files in the project are compressed first. The maximum size of uncompressed components in an uncompressed project is 600 MB or less, depending on the files’ compression ratio. If the files have a high compression ratio, you can migrate a total of approximately 600 MB because the compressed size would be under 39 MB. However, if the components can't be compressed much, like binary static resources, you can migrate less than 600 MB.

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.

Deploy Components to an Org

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.

For API version 29.0 or later, here’s how to deploy (create or update) packaged or unpackaged components.

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, here’s how to deploy (create or update) packaged or unpackaged components.

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 isn’t completed quickly enough to be noted in the first result. If it’s completed, note the value in the id field returned, and skip the next step.
If the call isn’t complete, issue a checkStatus() call in a loop. In the loop, use 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. Therefore, use a longer wait time between iterations 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.

The deployment process locks write-access to resources getting deployed until deployment completes. During deployment, changes made to locked resources or related items can result in errors. Salesforce recommends deployments during off-peak usage time and limiting or postponing changes to your org while deployment is in progress.

Note

Check the Status of a Deployment

Check the status of a deployment using Metadata API or from Setup. You can check the status of deployments that are in progress or completed in the last 30 days.

To check the status of a deployment using Metadata API, see checkDeployStatus().

To check the status of a deployment from Setup, enter Deployment Status in the Quick Find box, then select Deployment Status.

When running a deployment, the Deployment Status page shows you the real-time progress of your current deployment. This page contains charts that provide a visual representation of the overall deployment progress. The first chart shows how many components have already been deployed out of the total and includes the number of components with errors. For example, the following chart indicates that 302 components were processed successfully out of 450 and there were 45 components with errors.

After all components have been deployed without errors, Apex tests start executing, if necessary or enabled. A second chart shows how many Apex tests have run out of the total number of tests and the number of errors returned. In addition, the chart shows the name of the currently running test. For example, in the following chart, 77 tests have completed execution out of a total of 120, and 1 test failed.

You can initiate multiple deployments, but only one deployment can run at a time. The other deployments remain in the queue waiting to be executed after the current deployment finishes. Queued deployments are listed under Pending Deployments and are not necessarily executed in the order in which they were submitted. To execute deployments in a particular order, submit them one at a time after the previous deployment has completed successfully.

Cancel a Deployment

Cancel a deployment using the Metadata API or from Setup. You can cancel a deployment while it’s in progress or in the queue.

To cancel a deployment using Metadata API, see cancelDeploy().

To cancel a deployment from Setup, enter Deployment Status in the quick find box, then select Deployment Status. Click Cancel next to the deployment you want to cancel. The deployment has the status of Cancel Requested until the cancellation completes. A canceled deployment is listed in the Failed section.

Permissions

Your client application must be logged in with the Modify Metadata Through Metadata API Functions or Modify All Data permission.

If a user requires access to metadata but not to data, enable the Modify Metadata Through Metadata API Functions permission. Otherwise, enable the Modify All Data permission.

Note

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	If files that are specified in package.xml aren’t in the `.zip` file, specifies whether a deployment can still succeed. Don’t set this argument for deployment to production orgs.
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. Don’t 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, sometimes it can qualify for deployment without rerunning tests. See deployRecentValidation(). If you change a field type from Master-Detail to Lookup or vice versa, the change isn’t supported when using the checkOnly option to test a deployment. This change isn’t supported for test deployments to avoid permanently altering your data. If a change that isn’t supported for test deployments is included in a deployment package, the test deployment fails and issues an error. If your deployment package changes a field type from Master-Detail to Lookup or vice versa, you can still validate the changes before you deploy to production. Perform a full deployment to another test sandbox. A full deployment includes a validation of the changes as part of the deployment process. A Metadata API deployment that includes Master-Detail relationships deletes all detail records in the Recycle Bin in the following cases. For a deployment with a new Master-Detail field, soft delete (send to the Recycle Bin) all detail records before proceeding to deploy the Master-Detail field, or the deployment fails. During the deployment, detail records are permanently deleted from the Recycle Bin and can’t be recovered. For a deployment that converts a Lookup field relationship to a Master-Detail relationship, detail records must reference a master record or be soft-deleted (sent to the Recycle Bin) for the deployment to succeed. However, a successful deployment permanently deletes any detail records in the Recycle Bin.
ignoreWarnings	boolean	Indicates whether deployments with warnings complete successfully (`true`) or not (`false`). Defaults to `false`. The DeployMessage object for a warning contains the following values: problemType—`Warning` problem—The text of the warning 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. Before 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` to retrieve whatever was 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. When you delete a roll-up summary field using Metadata API, the field isn't saved in the Recycle Bin. The field is purged even if you don’t set the `purgeOnDelete` deployment option to `true`.
rollbackOnError	boolean	Indicates whether any failure causes a complete rollback (`true`) or not (`false`). If `false`, whatever 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’re 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. Apex tests that run as part of a deployment always run synchronously and serially.
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: `NoTestRun`—No tests are run. This test level applies only to deployments to development environments, such as sandbox, Developer Edition, or trial organizations. This test level is the default for development environments. `RunSpecifiedTests`—Only the tests that you specify in the runTests option are run. Code coverage requirements differ from the default coverage requirements when using this test level. Each class and trigger in the deployment package must be covered by the executed tests for a minimum of 75% code coverage. This coverage is computed for each class and triggers individually and is different than the overall coverage percentage. `RunLocalTests`—All tests in your org are run, except the ones that originate from installed managed and unlocked packages. This test level is the default for production deployments that include Apex classes or triggers. `RunAllTestsInOrg`—All tests are run. The tests include all tests in your org, including tests of managed packages. If you don’t specify a test level, the default test execution behavior is used. See Running Tests in a Deployment. Apex tests that run as part of a deployment always run synchronously and serially. This field is available in API version 34.0 and later.

Response

AsyncResult

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.

Metadata API Developer Guide