This tutorial shows you some techniques on using the Force.com Ant Migration toolkit for deployment and Git for version control on your Salesforce Development. Why should you learn this? This is not for all, if you are small company with only one or two developers you can get away with using change sets. That said though, on traditional software development using version control this is a best practice. Some use cases for this are, developers can work on different sandboxes and merge changes without overwriting each ones work, have a backup of the orgs metadata, do versioning for all the development changes and rollback changes if needed or incorporate continuous integration for automated testing and deployment.

After this tutorial you should be familiar with the following concepts:

• Making changes to an org and retrieving the metadata
• Adding changes to the a local version control
• Pushing changes to remote repository
• Deploying the metadata
• Fixing deployment issues

There are 3 parts to this tutorial. The prequisites, setup and the build/deploy.

Prequisites – things you need to get started

• Access to a developer edition or sandbox org
• Any command line tool (for this tutorial I’m using the Terminal on Mac)
• Have Java JDK installed on your machine – download and install
  • After installing you may need to update the path on your machine to point to the Java bin directory
• Have Apache Ant installed on your machine – download here
  • Check out this earlier post on how to install and setup on a Mac
• Git installed – download here
• A remote repository – here are some options you can sign up for a free account at Github or Bitbucket.

Setup and configuration – Let’s get the ball rolling and configure everything.

1. Ready your org credentials
2. Download the Force.com Ant Migration Tool version that matches your org release.
3. Unzip the archive and and it should have the salesforce-ant.jar file and a sample folder
4. We won’t be using the sample but instead we would be using a modified version.You can clone or download from
   https://github.com/olopsman/salesforce-ant
5. Check the folder structure.
   
   On the main salesforce-ant folder. The build.xml file has the project details and target build instructions when Ant is called.
6. Go to the environment folder. Each file is named after the org. Rename the the xxxx.properties file to your org, then edit the file to enter your credentials.
   
   
7. Open the package folder to edit the package.xml. This file will contain the metadata you want to fetch from your org.
8. At this point you can check the setup for your Git setup is correct. Open the command line tool and navigated to the salesforce-ant folder. Add your remote repository by entering the command

   [code]git remote add origin <your remote url>[/code]

Build/Deploy – let’s start the retrieve and deploy.

1. Back on the command line tool and go to the salesforce-ant folder. To retrieve the data enter

   [code]ant -Denv=ci1 retrieve[/code]

2. The build.xml has special instructions that would download the metadata to temporary src copy folder and move the files to the final src folder and exclude some unwanted files that cannot be deployed.
3. Check the changes in the src folder, at this point you would like to take a snapshot of these files and put them on version control. On the command line execute the following.

   [code]git add .
   git commit -m "Custom messsage"
   git push origin master[/code]

4. To deploy to the target org fix replace the env with the org credentials. Run the following command

   [code]ant -Denv=ci2 deploy[/code]

5. Hopefully all is successful. If not you may need to tweak the build.xml or add additional metadata to the package.xml depending on your org configuration.Here is a video in action.

Not all is smooth sailing in the land of metadata deployment. Some metadata though cannot be migrated and we continue to encounter issues after another and is one of the pain points of doing metadata deployment. Here are my takeaways from the the setup to deployment.

Issue 1:

[code]Unable to locate tools.jar. Expected to find it in /Library/Internet Plug-Ins/JavaAppletPlugin.plugin/Contents/Home/lib/tools.jar[/code]

If you have existing Java SE Runtime installed instead of the Java SE Development Kit, when you run ant you would get the following output message on your console. This is because the JRE does not have the tools.jar that is only available on the JDK. Installing the JDK should remove that message.

Issue 2 :

[code]UNSUPPORTED_API_VERSION – Invalid Api version specified on URL[/code]

This means your instance or org has not been updated with the latest release and does not match the version of the Ant migration tool. Download and older version of the Ant migration tool to fix the issue.

Issue 3 :

[code]When Social Post is enabled on the org, the layout would&amp;amp;nbsp;be pulled from the Metadata but it cannot be deployed.
Error: layouts/SocialPost-Social Post Layout.layout — Error: Parent entity failed to deployWith&amp;amp;nbsp;build.xml[/code]

There are metadata that cannot be deployed. As part of the build.xml we create a temporary src copy folder and copies over to a final src folder. During the copy we have instructions to exclude copying certain files. At some instance the file is referenced in a profile and could cause the profile to fail on deploy, we have regex commands to remove the node element from copying as shown below.

[code]
<!– Remove unwanted metadata specified on this target –>
<target name="copyMetadata">
<echo>Copying source to ${srcDir} to exclude unwanted files</echo>
<delete dir="${srcDir}"/>
<mkdir dir="${srcDir}"/>
<copy todir="${srcDir}">
<fileset dir="${srcDirCopy}">
<exclude name="layouts/SocialPost-Social Post Layout.layout"/>
<exclude name="workflows/Reply.workflow"/>
<exclude name="workflows/SocialPost.workflow"/>
<exclude name="workflows/Question.workflow"/>
<exclude name="settings/Search.settings"/>
</fileset>
</copy>
<!– removes an element from profile –>
<replaceregexp match="&lt;layoutAssignments&gt;\s*&lt;layout&gt;SocialPost-Social Post Layout&lt;/layout&gt;\s*&lt;/layoutAssignments&gt;\s*" replace="" flags="gm" byline="false">
<fileset dir="${srcDir}/profiles" includes="*.profile"/>
</replaceregexp>
<delete dir="${srcDirCopy}"/>
</target>
[/code]

Issue 4 :

[code]flows/New_Customer_Flow-1.flow — Error: The version of the flow you’re updating is active and can’t be overwritten.Temporary workaround is to manually maintain&amp;amp;amp;nbsp;the flow name and version to the package.xml. The retrieveMetadata only fetches the flow version specified.[/code]

Deploying Flows is very trivial.

• You can deploy flows if they are inactive.
• You can deploy an active flow only if it is not active on the target org.
• You cannot deploy an active flow if is active on the target org.

One method is to manually call the version you want to retrieve and deploy. If you encounter an error that it is already active, delete the flow, flowDefinition and remove the line in the package.xml

Issue 5: Profiles has some attributes not yet on the target org. This is specially true when your org are on different releases. Similar to removing the layout from the profile, you need regex to read off the element string pattern in the profile to remove the element.

 

 

On my next tutorial I’ll show you how to dynamically create a package.xml, deploy files that has changed between two branches and using Jenkins to automate deployment.