For getting started with Metadata API, you should have the infrastructure setup as a Java application using:
- WSC – Web Service Connector jar
- Enterprise Jar – Which you convert using Enterprise WSDL available from API section.
- Metadata Jar – Which you convert using Metadata WSDL available from API section.
- Partner Jar – Which you convert using Partner WSDL available from API section.
- Setting the classpath using all the above jars.
However, if you want to only work with File Based Metadata API, then WSC is sufficient. But if you want to explore CRUD Metadata API then Enterprise, Metadata jars are required.
Asynchronous Calls
When an Asynchronous call is issued, the results are not immediately returned, as Salesforce returns an AsyncResult Object for each component and we have to loop until the status value in AsyncResult indicates from Queue to completed or error state. Calls in Bulk API are also asynchronous.
The Result Objects corresponding to Asynchronous calls are as:
- AyncResult – For all the File based operations (retrieve and deploy) as well as all the CRUD calls (create, update and delete).
- DeployResult – Contains the information about success or failure of the associated deploy() call.
- RetrieveResult – Contains the information about the success or failure of the associated retrieve() call.
File Based / Declarative Metadata calls
The available calls are:
- retrieve(): This call retrieves XML file representations of components in an organization.
- deploy(): This call deploys XML file representations of components to create, update, or delete those components in an organization.
Syntax:
- retrieve() :
AsyncResult = metadatabinding.retrieve(RetrieveRequest restrieveRequest)
- deploy():
AsyncResult = metadatabinding.deploy(base64 zipFile, DeployOptions deployOptions)
In case you are using deploy() of Declarative Metadata Calls (File Based Metadata API), then you have the control to stop / cancel the existing deployment (in case you feel the deployment is taking long time or you don’t feel the components to be deployed are of concern) using:
cancelDeploy(String Id)
or
If you go to the Setup->DeploymentStatus, there you can find the ongoing, success or error of any deploying / deployed components. You may click Cancel button in case you want to dismiss the deployment as:
This is the snapshot of the deployment in progress:
Following is the snapshot of Viewing further details of the deployment process:
CRUD Asynchronous Metadata calls
Use the CRUD-based metadata calls to create, update, or delete setup and configuration components for your organization or application. These configuration components include custom objects, custom fields, and other configuration metadata.
The available calls are:
- create() – Salesforce returns an AsyncResult object for each component you tried to create. The AsyncResult object is updated with status information as the operation moves from a queue to completed or error state.
- update() – Updates one or more components in your organization asynchronously.
- delete() – Deletes one or more components in your organization asynchronously.
The above methods are Deprecated from API version 28.0 onwards to 30.0. And removed from API version 31.0 onwards.
Syntax:
- create():
AsyncResult[] = metadatabinding.create(Metadata[] metadata);
- update():
AsyncResult[] = metadataConnection.update(UpdateMetadata[] metadata);
- delete():
AsyncResult[] = metadataConnection.delete(Metadata[] metadata);
Checkout the typical example on Github for dealing with Objects, Profiles, RecordTypes and Layouts Asynchronously here Metadata Java Asynchronous calls.
Synchronous Calls
A call that executes Synchronously and returns only when the operation completes.
In Salesforce the Result Objects of Metadata API like:
- SaveResult – For getting the result from create and update synchronous calls.
- UpsertResult – For getting the result from upsert synchronous call.
- DeleteResult – For getting the result of delete synchronous call.
- ReadResult – For getting the result of read synchronous call.
The available calls are:
- createMetadata() – Adds one or more components in your organization synchronously.
- updateUpdate() – Updates one or more components in your organization synchronously.
- deleteMetadata() – Deletes one or more components in your organization synchronously.
- upsertMetadata() – Upserts one or more components in your organization synchronously.
- readMetadata() – Reads one or more components in your organization synchronously.
- renameMeatadata() – Renames one or more components in your organization synchronously.
Syntax:
- createMetadata():
SaveResult[] = metadatabinding.createMetadata(Metadata[] metadata);
- updateMetadata():
SaveResult[] = metadataConnection.updateMetadata(Metadata[] metadata);
- deleteMetadata():
DeleteResult[] = metadataConnection.deleteMetadata(String metadataType, String[] fullNames);
- upsertMetadata():
UpsertResult[] = metadataConnection.upsertMetadata(Metadata[] metadata);
- readMetadata():
ReadResult = metadataConnection.readMetadata(String metadataType, String[] fullNames);
- renameMetadata():
SaveResult = metadataConnection.renameMetadata(String metadataType, String oldFullName, String newFullName);
Checkout the typical example on Github for dealing with Objects, Profiles, RecordTypes and Layouts Synchronously here Metadata Java Synchronous calls.
Some other useful Result Objects:
- DescribeMetadataResult – This is used while working with Declarative Metadata and contains information about the organization. It is used in conjunction with describeMetadata() call.
- CancelDeployResult – cancelDeploy() is used to stop the ongoing deployment to target Salesforce instance. Which ultimately returns CancelDeployResult which contains information about a deployment cancellation—whether the cancellation completed and the deployment ID.
- Error – It represents an error that occurred during a synchronous CRUD (createMetadata(), updateMetadata(), or deleteMetadata()) operation.
Error Handling:
We may struck into some errors while dealing with Metadata API, some are the scenarios which can be utilized for better handling:
- Failed Authentication – As Metadata API uses Metadata or Enterprise WSDL, there contains an Exception Code for most of the errors we encounter during Authentication while communicating to the target Salesforce instance. Some examples are Failed to Send request to https://login.salesforce.com/services/c/29.0 and INVALID_LOGIN – Invalid username, password, security token; or user locked out.
- Errors with Asynchronous calls – After obtaining AsyncResult object, we may parse for statusCode field for the associated component.
- Errors with CRUD Synchronous calls – After obtaining appropriate result object, we get the array of errors returned by errors field of the respective object. And, we iterate over these errors of type Error object to obtain the statusCode out of it.
- Errors with deploy() – We analyze the problem and success field of DeployMessage object for the associated component.
- Errors with retrieve() – We analyze the problem field of RetrieveMessage object for the associated component.
- INVALID_SESSION_ID – Sessions automatically expire after the amount of time specified in the Security Controls setup area of the Salesforce application
(default two hours). When our session expires, the exception code INVALID_SESSION_ID is returned. If this happens, we must invoke the login() call again.
Utility Calls:
- checkStatus() – Checks the status of asynchronous metadata calls create(), update(), or delete(), or the declarative metadata call retrieve(). But this call is removed as of API version 31.0. Instead we use checkDeployStatus or checkRetrieveStatus for deploy() and retrieve() calls respectively.
- describeMetadata() – It includes the information regarding Apex classes and triggers, custom objects, custom fields on standard objects, tab sets that define an app, and many other components.
- listMetadata() – This call retrieves property information about metadata components in your organization. Data is returned for the components that match the criteria specified in the queries parameter.
Main difference between the Synchronous and Asynchronous calls are:
- CRUD Metadata Calls: Introduction of new methods for Upsert, Rename and Read which we had to earlier do with the help of retrieve() declarative call.
- File / Declarative Metadata Calls: The methods like checkStatus is replaced with checkDeployStatus or checkRetrieveStatus for deploy() and retrieve() calls respectively.
- In Synchronous Calls, the results are returned in a single call, whereas in Asynchronous calls, results are not immediately returned in one call.
- Also, calls executes synchronously means that the calls returns only when the operation completes.
- The Line of code is significantly reduced (in Asynchronous calls we have to check status in a loop until the operation is completed) in Synchronous calls.
- Simplicity and reduction of overhead while performing Synchronous calls.
For more details checkout the reference guide Metadata API Developer’s Guide.