build.properties

Today, we will make our build.properties file a little bit more suited to an enterprise org by creating parameters for two environments, Stage and Production. This will allow us to test our changes in a lower environment before applying them to the full organization. This is useful for automating lengthy deployments. If you are using a developer environment, you can specify sf.username and sf.password here.

Additionally, we will specify a retrieval package, retrievepkg, and a deployment package, deploypkg, which will allow us to easily copy our changes to multiple environments.

# build.properties
#

# Specify the login credentials for the desired Salesforce organization

sf.usernameStage = USERNAME
sf.passwordStage = PASSWORD

sf.usernameProd = USERNAME
sf.passwordProd = PASSWORD

#sf.pkgName = <Insert comma separated package names to be retrieved>

sf.pkgNameRetrieve = retrievepkg
sf.pkgNameDeploy = deploypkg

# Use 'https://login.salesforce.com' for production or developer edition (the default if not specified).
# Use 'https://test.salesforce.com for sandbox.
#sf.serverurl = https://test.salesforce.com

sf.testurl = https://test.salesforce.com
sf.loginurl = https://login.salesforce.com

sf.maxPoll = 20

# If your network requires an HTTP proxy, see http://ant.apache.org/manual/proxy.html for configuration.
#

package.xml

In order to retrieve the metadata for an object as it relates to a profile, we must retrieve the object as well as the profiles. We can specify this in our package.xml file according to the Salesforce documentation. In order to retrieve a standard or custom object, we will name the component using the CustomObject tag, and declare the specific object using the members tag. In order to retrieve a standard or custom field, we would name the component using the CustomField tag, and declare the field using the members tag.

The example given in the Salesforce documentation is as follows:

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>Case.EngineeringReqNumber__c</members>
        <name>CustomField</name>
    </types>
    <types>
        <members>Account</members>
        <name>CustomObject</name>
    </types>
    <version>47.0</version>
</Package>

This example is easily modified. For this tutorial, we will be retrieving the Case object metadata and the Profile metadata to modify CRUDE permissions on the Case object for each profile. Our package.xml file will be:

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>Case</members>
        <name>CustomObject</name>
    </types>
    <types>
        <members>*</members>
        <name>Profile</name>
    </types>
    <version>47.0</version>
</Package>

build.xml

Lastly, we will build our build.xml file. Similar to the last tutorial, we will have a retrieve action, but we will also have a deploy action so that we can deploy our changes. For a step by step walkthrough of each line of code, please see my previous tutorial here. Note that we are specifying the login parameters as sf.usernameStage and sf.passwordStage so that we can test this in a lower environment first. If you are using a developer org, you can use sf.username and sf.password here.

<project name="Another Salesforce Blog" default="test" basedir="." xmlns:sf="antlib:com.salesforce">

    <property file="build.properties"/>
    <property environment="env"/>
    <!-- Setting default value for username, password and session id properties to empty string 
         so unset values are treated as empty. Without this, ant expressions such as ${sf.username}
         will be treated literally.
    -->
    <condition property="sf.usernameStage" value=""> <not> <isset property="sf.usernameStage"/> </not> </condition>
    <condition property="sf.passwordStage" value=""> <not> <isset property="sf.passwordStage"/> </not> </condition>
    <condition property="sf.sessionId" value=""> <not> <isset property="sf.sessionId"/> </not> </condition>
    <taskdef resource="com/salesforce/antlib.xml" uri="antlib:com.salesforce">
        <classpath>
            <pathelement location="C:\ant\ant-salesforce.jar" />        	
        </classpath>
    </taskdef>
    <!-- Retrieve Profiles  -->
    <target name="retrieveProfiles">
      <mkdir dir="retrieveProfiles"/>
      <!-- Retrieve the contents into another directory -->
      <sf:retrieve username="${sf.usernameStage}"
                   password="${sf.passwordStage}"
                   sessionId="${sf.sessionId}"
                   serverurl="${sf.loginurl}"
                   maxPoll="${sf.maxPoll}"
                   retrieveTarget="retrieveProfiles"
                   unpackaged="retrievepkg/package.xml"/>
    </target>

    <!-- Deploy Profiles  -->
    <target name="deployProfiles">
      <!-- Upload the contents of the specified package -->
      <sf:deploy username="${sf.usernameStage}"
                 password="${sf.passwordStage}"
                 sessionId="${sf.sessionId}"
                 serverurl="${sf.loginurl}"
                 maxPoll="${sf.maxPoll}"
                 deployRoot="${sf.pkgNameDeploy}"
                 singlePackage="true"
                 rollbackOnError="true"/>
    </target>
</project>