Deploy Metadata Using Salesforce Metadata API

HomeMagulan Duraipandian

Deploy Metadata Using Salesforce Metadata API

Magulan Duraipandian

Mastering Salesforce Deployment: A Step-by-Step Guide to Using the Metadata API

Introduction

In the world of Salesforce DevOps, moving metadata between environments is a daily necessity. While Change Sets are useful for simple moves, developers and architects often turn to the Salesforce Metadata API for robust, automated, and complex deployments.

Whether you are building a custom CI/CD pipeline or simply want to understand the mechanics of how Salesforce moves code, interacting directly with the API gives you granular control. In this guide, we will walk through the exact steps to deploy an Apex Class using raw API requests.

Step 1: Authenticate and Obtain Your Access Token

Before you can touch the metadata, you need a valid session. The Metadata API requires authentication via OAuth 2.0.

To begin, you must perform a POST Request to the Salesforce token endpoint. This will return the access_token required for subsequent headers.

Request Endpoint:

https://{Your_Org_Domain}.my.salesforce.com/services/oauth2/token

Note: Ensure you replace {Your_Org_Domain} with your actual domain and pass the necessary body parameters (client_id, client_secret, username, password, etc.) depending on your flow.

Step 2: Define Your Manifest (package.xml)

The heart of any Metadata API deployment is the package.xml file. This manifest tells Salesforce exactly what components you intend to add, update, or delete.

For this example, we are deploying a single Apex Class named HelloWorld.

Sample package.xml:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>HelloWorld</members>
        <name>ApexClass</name>
    </types>
    <version>65.0</version>
</Package>

Step 3: Organize Your Folder Structure

Salesforce expects a specific directory structure for deployment. You cannot simply upload the file; it must reside in a folder that corresponds to its metadata type.

For an Apex Class, you must:

  1. Create a root folder.
  2. Inside that, create a folder named “classes”.
  3. Place your HelloWorld.cls (and HelloWorld.cls-meta.xml) inside the classes folder.
  4. Place the package.xml at the root level (outside the classes folder).

Step 4: Create the Deployment Package

Once your folder structure is correct, you need to compress the assets.

Zip both the package.xml file and the classes folder (and its contents). This .zip file acts as the payload for your API request.

Step 5: Initiate the Deployment

Now that you have your authenticated token and your zipped package, it is time to deploy. This is done via a POST Request to the metadata deployment endpoint.

Request Endpoint:

https://{Your_Org_Domain}.my.salesforce.com/services/data/v65.0/metadata/deployRequest

The API will process the zip file. If the format is correct, Salesforce will queue the deployment and return an ID (e.g., 0AfHo...). You will need this ID for the next step.

Step 6: Check Deployment Status

Metadata deployments are asynchronous. You won’t get the final success or failure result immediately in the POST response. Instead, you must poll the server to check the status of your specific deployment ID.

Request Endpoint:

https://{Your_Org_Domain}.my.salesforce.com/services/data/v65.0/metadata/deployRequest/0AfHo00000wAX9GKAW?includeDetails=true

This GET Request will return the status (e.g., InProgress, Succeeded, Failed). When includeDetails=true, the response contains a DeployDetails object, which populates with information crucial for monitoring and troubleshooting

Salesforce Article:

https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_rest_deploy.htm

Leave a Reply