APACHE ANT SCRIPT
APACHE ANT is a command-line tool based on java use for transferring metadata components between two salesforce organization and local directory.
Steps for Installation:
1. Log into a Salesforce organization from your PC/LapTop.
2. Click on Setup at rightmost side of the page, On search box search Develop --> Tools --> Force.com Migration Tool.
3. Save the .zip file locally and extract it to the directory of your choice.
4. Copy the .jar file and paste it into your ant installation library(lib) directory. The lib directory is placed in the root folder of your Ant installation.
Steps to follow for using APACHE ANT:
- Enter credentials and connection information for source org in build.properties.
- Enter credentials and connection information for destination org in build.properties.
- Create retrieve targets in build.xml.
- Construct a project manifest in package.xml.5. Enter & run the command in terminal to retrieve metadata files from Salesforce. i.e. (ant retrieveUnpackaged )6. Enter & run the command in terminal to deploy metadata components you want. i.e. (ant deployUnpackaged)
- Enter & run the command in terminal to retrieve metadata files from Salesforce. i.e. (ant retrieveUnpackaged)6. Enter & run the command in terminal to deploy metadata components you want. i.e. (ant deployUnpackaged)
- Enter & run the command in terminal to deploy metadata components you want. i.e. (ant deployUnpackaged)
Steps & Commands required to retrieve and deploy components:
1. Open the terminal and follow the commands.
--> cd 'path of sample folder of Apache ANT where it has been extracted'
You will be redirected inside the sample folder.
--> ant retrieveUnpackaged
This command will retrieve components defined in package.xml from source organisation.
--> ant deployUnpackaged
This command will deploy the received components to the target organisation.
Creating a Project Manifest:
* The package.xml is a project manifest which consists of all components which you want to retrieve or deploy.* At a time only a single package can be retrieved or deploy.
List of elements which should be defined in package.xml are defined below:
- <fullName> - This element is not used for retrieval. It denotes the name of the server-side package in which deployment has to be done. If the field '<fullName>' field is removed while deployment, the components will not be assigned to a package, and will be in the unpackaged package.
- <types> - It consists of one or more than one '<members>' tags and single '<name>' tag which is used to list the metadata components of a certain type to retrieve or deploy.
- <members> - For each component one <members> element is defined. Either the value asterisk(*) can be defined in it which lists all the contents present in Name or you can list each member separately. It is a child element of <types>.
- <name> - It Contains the type of the component, for example StaticResource , CustomObject etc . For a single component, only one name can be defined. It is also a child element of <types>.
- <version> - The Metadata API version number of the files which are being retrieved or deployed. When deploying the components, all the files must be of the same version of the Metadata API.
Example of how we define elements in Package.xml:
<?xml version="1.0" encoding="UTF-8"?> <Package xmlns="http://soap.sforce.com/2006/04/metadata"> <types> <members>*</members> <name>StaticResource</name> </types> <version>34.0</version> </Package>
Note:- Few components cannot be retrieved by * (asterisk). In that case, we have to retrieve them by their API Name.
Example:
<?xml version="1.0" encoding="UTF-8"?> <Package xmlns="http://soap.sforce.com/2006/04/metadata"> <types> <members>Account.Sample__c</members> <name>CustomField</name> </types> <version>34.0</version> </Package>
Common Migration Issues:
There are some common issues that may come while migrating metadata. These issues can be grouped into three categories:
- Metadata
- Connectivity
- Testing and Code Coverage
Common Metadata Issues:
- Personal folders — Personal folders of Users for reports and documents are not visible in the Metadata API. For migrating reports and documents you must move them to a public folder.
- Retrieving custom fields on standard objects — We cannot retrieve custom fields on standard objects directly. To retrieve custom fields on standard objects we use API name, for example, we have a custom field name sample on Account:-
<types> <members>Account.sample__c</members> <name>CustomField</name> </types>
- Profiles or permission sets and field-level security — The retrieved contents of profile or permission set depend on other retrieved request contents. For example, field-level security for fields included in custom objects is returned at the same time as profiles or permission sets.
Common Connectivity Issues:
- Invalid username, password, security token; or user locked out — This indicates problems with your credentials specified in build.properties.
- Request timed out — While retrieving or deploying metadata, the request is sent asynchronously, which means that the response isn't returned immediately. Due to asynchronous calls, the server will process a deploy() to completion even if the Force.com Migration Tool times out. If the deployment fails after timing out, there is no way to retrieve the error message from the server. Because of this reason, you have to tune pollWaitMillis and maxPoll parameters while receiving errors for time out.
Testing and Code Coverage:
While deploying to a production org, every unit test in your org namespace is executed. Before you deploy Apex, these following things must be checked:
- At least 75% of your Apex code must be covered by unit tests with no errors.
- All the triggers must have some code coverage.
- The compilation of all classes and triggers should be complete successfully.
If you could also provide steps to Install Ant on a Ubuntu system then that would be just great.