Note from the author

"The script files are pretty crude, I know. I just hope the functionality will make up for the coding style, at least until people have time to clean it all up and actually create a nice-looking class or module out of this." -- Marty

How do I use the scripts?

In short, you will run the scripts from the command line, and then use Workbench to deploy the final package.

Prerequisites

You should be comfortable with:

• Downloading files
• Running commands in the Command Prompt (Windows) or the shell (*nix)
• Modifying the contents of .zip files

You'll also need to have on your computer:

• Ruby. If you're on Windows, make life simple and run RailsInstaller.
• Savon. You can install this using gem install. These video instructions may also help.
• The scripts. Look in the scripts folder in the repo.

Step 1. Retrieve profiles and permission sets

Tip: Here are video instructions for clarification.

Start by logging into your source and destination orgs and downloading the Partner API and Metadata API WSDL's.

1. In Setup, open App Setup > Develop > API, or Setup > Develop > API depending on which Setup UI you're using
2. Right-click Generate Partner WSDL, then click Save As... Save the file to the same directory where your scripts are located.
3. Right-click Generate Metadata WSDL, then click Save As... Again, save the file to the same directory where your scripts are located.

Tip: Add a qualifier like "-sandbox" or "-production" to the filenames, to distinguish between the two sets of WSDL's from two orgs.

When you're done, you should have something like the following new files in your script folder:

• metadata-29.0-sandbox.wsdl
• metadata-29.0-production.wsdl
• partner-29.0-sandbox.wsdl
• partner-29.0-production.wsdl

Tip: You'll need your security token as well (unless you're in a trusted IP range), so make sure you have your token before proceeding.

Retrieve the profiles and permission sets using Ruby:

1. Open a command line where you can run ruby. If you used RailsInstaller on Windows, open the shortcut called "Command Prompt with Ruby and rails".
2. Change to the directory where the scripts and WSDL's are stored
3. Run the following commands

> ruby retrieve_profiles_and_permissionsets.rb partner-29.0-sandbox.wsdl metadata-29.0-sandbox.wsdl
> ruby retrieve_profiles_and_permissionsets.rb partner-29.0-production.wsdl metadata-29.0-production.wsdl

Follow the on-screen instructions to enter your credentials.

Tip: Your password will be displayed in plain text, so be careful!

Each time you run the script, you'll get a .zip file in the same folder containing metadata for all profiles and permission sets, from the org to which you connected.

Step 2. Remove profiles that you don't want to migrate

Tip: Here are video instructions for clarification.

Edit the .zip file you retrieved from the source org (not the destination org!), and go into the profiles folder. Delete the profiles you don't want to deploy, leaving only the ones you do want to deploy. Repeat for the permission sets in the permissionsets folder.

Step 3. Prepare remaining profiles and permission sets for migration

Tip: Here are video instructions for clarification.

For profiles, run the following command:

> ruby prepare_profiles.rb your-source-org-package.zip your-destination-org-package.zip

Make sure you put the parameters in order! This is important for generating the correct deployment package. If you switch up the order, you'll end up with a bad package.

Repeat for permission sets, using the other "prepare" script:

> ruby prepare_permissionsets.rb your-source-org-package.zip your-destination-org-package.zip

Step 4. Deploy usisng Workbench

1. Log into Workbench.
2. Hover over the "migration" menu, then click Deploy
3. Deploy the two packages you just prepared. The order doesn't matter.

When deploying, the recommended options to select are:

• Rollback on Error
• Single Package
• Run All Tests

Step 5. Complete manual migration tasks

With API 29.0, the prepared packges should consistently deploy the following:

• Field permissions (including fields from managed packages)
• Object permissions (including objects from managed packages)
• User permissions (System Permissions and App Permissions)
• Visualforce page access settings
• Apex class access settings
• Record type visibility settings
• Page layout assignments

Important! For each category of settings above, the absence of components in the destination org may impact what's actually deployed.

For example: If the "Partner Account Layout" is assigned to the "Partner Relationship Manager" profile in your sandbox org, but the layout doesn't exist in Production, this assignment will not be included in the deployment package.

For tab visibilities and app assignments, you should double-check each of these manually. The reason is that Salesforce does not consistently produce expected metadata output (in API 29.0) for those two categories, so it's safer to complete this part of the migration manually.

To help you, you can try using the following JavaScript hacks. The hacks do require Enabled Profile List Views and Enable Enhanced Profile User Interface to be marked in Setup > App Setup > Customimze > User Interface.

• compilePermissionSetTabSettings.js
• compileProfileAssignedApps.js
• compileProfileTabVisibilities.js

Don't forget to asasign users to the new profiles and permission sets! You can do this with Salesforce Data Loader.