cancelDeploy()

Syntax

CancelDeployResult = metadatabinding.cancelDeploy(string id)

Usage

Use the cancelDeploy() operation to cancel a deployment in your organization started by the deploy() operation, which includes deployments started by the Lightning Platform Migration Tool and the Lightning Platform IDE. The deployment can be in a queue waiting to get started, or can be in progress. This operation takes the ID of the deployment you want to cancel and returns a CancelDeployResult object. When the deployment is in the queue and hasn’t started yet, calling cancelDeploy() cancels the deployment immediately. When the deployment has started and is in progress, sometimes it doesn’t get canceled immediately, so call checkDeployStatus() to check the status of the cancellation.

Cancel a deployment using these steps.

1. Obtain the ID of the deployment you want to cancel. For example, you can obtain the ID from the deploy() call in the AsyncResult object id field. Alternatively, you can obtain the ID in the Salesforce user interface from Setup by entering Deployment Status in the Quick Find box, selecting Deployment Status, and then noting the ID of a deployment started by the API.
2. Issue a cancelDeploy() call to start the cancellation process. This call returns a CancelDeployResult object.
3. Check the value in the done field of the returned CancelDeployResult. If the done field value is true, the deployment has been canceled and you’re done. If the done field value is false, the cancellation is in progress. To check the cancellation status, follow these steps.
   1. Call checkDeployStatus() using the deployment ID you obtained earlier.
   2. In the returned DeployResult object, check the status field. If the status is Canceling, the cancellation is still in progress, and repeat steps a and b. Otherwise, if the status is Canceled, the deployment has been canceled and you’re done.

The deploy() operation throws these API faults.

INVALID_ID_FIELD with the message Invalid deploy ID

The specified ID argument doesn't correspond to a valid deployment.

INVALID_ID_FIELD with the message Deployment already completed

The specified deployment has already completed.

Version

Available in API version 30.0 and later.

Permissions

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

Arguments

Response

CancelDeployResult

Sample Code—Java

This sample shows how to cancel a deployment. The sample calls cancelDeploy() by passing it a given deployment ID. Next, it checks whether the cancellation has completed, and if not, calls checkDeployStatus in a loop.

public void cancelDeploy(String asyncId) throws Exception {
    // Issue the deployment cancellation request  
    CancelDeployResult result = metadataConnection.cancelDeploy(asyncId);
    
    // If the deployment cancellation completed, write a message to the output.
    if (result.isDone()) {
        System.out.println("Your deployment was canceled successfully!");
    }
    else {
        // The deployment cancellation is still in progress, so get a new status 
        DeployResult deployResult = metadataConnection.checkDeployStatus(asyncId, false);
    
        // Check whether the deployment is done. If not done, this means 
        // that the cancellation is still in progress and the status is Canceling.        
        while (!deployResult.isDone()) {
            // Assert that the deployment status is Canceling
            assert deployResult.getStatus() == DeployStatus.Canceling;
            // Wait 2 seconds
            Thread.sleep(2000);
            // Get the deployment status again
            deployResult = metadataConnection.checkDeployStatus(asyncId, false);
        }
        
        // The deployment is done. Write the status to the output.
        // (When the deployment is done, the cancellation should have completed
        // and the status should be Canceled. However, in very rare cases,  
        // the deployment can complete before it is canceled.) 
        System.out.println("Final deploy status = >" + deployResult.getStatus());
    }
}