Deployment Tool Usage

Here's how to make use of the deployment tool

Step 1. Install it.

Currently the deployment tool is embedded within the JDBC driver. You have to install that first. We've added some new commands to the JDBC driver.

Step 2. Write a script to create a deployment file

There are only a few commands. Here's an example script that illustrates most of them:

dep start;
dep add ApexClass UpgradeController;
dep add ApexClass UpgradeControllerTest;
dep add CustomObject UpgradeOptions__c;
dep add CustomField Account.UpgradeOption__c;
dep drop ApexPage SomeObsoletePage;
dep commit;
dep package to 'c:/tmp/';

Now connect to the Salesforce instance that contains these components, and run the script. Upon completion you will have a zip file containing the items defined in the script.

Step 3: Deploy the deployment file

You can now connect the JDBC driver to the instance of Salesforce that you want to deploy the package to, and run the following command, pointing it at the "zip" file you defined when you originally created the package:

dep upload package from 'c:/tmp/' to 'c:/tmp/deploy.log';

The log file is where deployment logs are written, which can be useful when tracking down the deployment problems that are so common with Salesforce deployments -- no matter what tool you use.

Monitor the deployment by examining the log file you defined, or from within Salesforce by viewing the Setup | Deployment | Monitor Deployments page.

The deploy "upload" command actually takes an optional parameter, not shown above, that can be placed before the "from" keyword. It has the following values

Parameter Meaning
checkonly Don't actually do a deployment, just check to see if it would work
alltests Run all tests in the target environment
runtests Only run the tests that you are currently deploying. This option is not available when deploying to a production environment
ignore_errors Attempt to deploy, even though Salesforce may report errors
ignore_warnings Attempt to deploy, even though Salesforce may report warnings
status <jobid> If the Salesforce network connection fails for some reason you can reconnect, resume logging, and see the final status by using STATUS option and the jobid shown at the top of the log file.
dep upload package checkonly from 'c:/tmp/' to 'c:/tmp/deploy.log';

The zip file generated by the deployment tool can also be deployed using the Salesforce "ant" tool if you prefer.

If you need to "tweak" the code prior to deployment, you can edit the zip file using something like Total Commander, or unzip, edit, and rezip file, or you can explore the "patch" commands, as described in the next section.

Patching (Advanced Feature)

Salesforce development can sometimes force the use of hard-coded values, such as object ids, in places like Workflow. These object ids will need to be different in every environment you deploy to, and relying on humans to remember to manually change such values is tedious and unreliable. Stuntbyte's "patching" facility gives you a clean way to handle this issue.

Patch Definition

In the code below we define some "patch variables" that represent the values that are required in various deployment environments. eg: a "special user" id in dev, uat and prod. These names are completely arbitrary.

dep start;
-- Define "special_user" in each environment
dep patch var dev.special_user=00590000000dQVo;
dep patch var uat.special_user=00590000000bWXy;
dep patch var prod.special_user=00590000000kPBa;
-- Define the objects that should have the "special_user" replacement
-- applied to them.
-- Note that this example is illustrating the available options, and the
-- use of "*" will over-ride any more granular replacement rules! 
dep patch rule replace special_user in ApexClass LoginChecker;
dep patch rule replace special_user in CustomField AnObject__c.AColumn__c;
dep patch rule replace special_user in *;
-- The definitions above are static. From here down the script varies
-- according to your individual deployment
-- Indicate where you are deploying from, and to:
dep patch apply from dev to uat;

-- Continue with a normal deployment script
dep add ...
dep add ...
dep commit
dep package...
dep upload...


How do I know what types of components can be deployed?

The types of components supported are defined here (except that these pages incorrectly state 'CustomLabels' is a component type -- actually it's singular, 'CustomLabel' -- yes, we have reported the problem, years ago).

You can also use your SQL tool to browse the "deployment" schema.

How do I know what names to use with the deployment?

These are generally the "developer name" used when the object was created, but the guaranteed way to figure it out is by accessing the "deployable" table that exists for each type. eg:

SELECT Identifier from deployable.CustomTab

NOTE: The "deployable" schema tables are internal to the JDBC driver and don't make use of the Salesforce query engine, consequently the only supported WHERE clause is "WHERE Identifier LIKE", and the LIKE expression isn't exhaustive :-)