Editors Note: This post is part of a “Guest” series entitled Enterprise Architecture with Force.com. Our guest blogger, Greg Cook, is a managing partner of CloudPremise and currently holds all seven Salesforce certifications.

In my recent article on Environment Management I explained some of the intricacies related to managing the Salesforce1 Platform metadata. However, regardless of the number of environments you maintain, there are some critical techniques necessary for managing a Salesforce1 Enterprise deployment.

For the purposes of this article, “deployment” will be defined as the steps necessary for completing a smooth roll-out of new functionality into your production org.  It does NOT include some of the user-adoption related issues like training and support (which are just as important if not MORE). Let’s look at a successful migration and the people, tools, and processes necessary for complete a “flawless” enterprise deployment.


The following roles are necessary for executing a smooth deployment.  Understand that these are “roles” and not “resources,” and that some people might wear multiple hats.  In large projects there might be multiple people in these roles.  In smaller projects there might be one person playing ALL of these roles:

  1. Environment Manager – I recommend a dedicated technical administrator whose responsibility is “Environment Integrity.”  I have heard many different names describing this role (build master, deployment manager, configuration management engineer, etc.). However regardless of the name, there is a very important concept: Developers shouldn’t have the privileges or responsibilities to deploy their own code into Production! Call me old-fashioned, however my urgency around this principle not only includes any necessary compliance requirements; it also includes taking the time to PLAN, REHEARSE, and EXECUTE your deployments.  When Salesforce developers deploy their own code it often leads to cowboy coding practices, which is exactly the thing we are trying to avoid.  The environment manager will actually execute the steps outlined in the deployment plan, including manual configuration steps, and utilizing the source control and deployment tools.
  2. Release Manager – The release manager is the functional counter-part to the environment manager.  The release manager is the owner of the release calendar and the necessary flow of information between the technical teams and the users (the Communication Plan).  The release manager is also responsible for building and distributing a thorough set of release notes.
  3. Development Team – As features are designed and built in the development environments, developers are responsible for documenting their deployment steps AS THEY BUILD.  Successful deployments start during development.  If you wait to define your deployment steps until testing is complete, you are most likely going to have a very painful migration.
  4. Business Stakeholder(s) – Business stakeholders need to have visibility and authority in the release process.
  5. IT Stakeholder(s) – Internal IT stakeholders, such as technical architects, project managers, and the change management team, need to be fully aware of any Salesforce deployments.


The tools listed below range between sophisticated software and simple documents – however all are vital components of your deployment strategy.

  1. Release Calendar – This document maintains a record of all upcoming changes to your Salesforce environment.  It should include details on sandbox activity (planned refreshes, features moving to test, etc.), as well as Salesforce release details (Pre-Release Sandbox Upgrades, Production Updates, etc.).  It should be used to communicate with stakeholders as well and manage any necessary deployment moratoriums.  The release manager should own and maintain this document.
  2. Configuration Workbook – Complex Salesforce environments need living design documentation.  I call this the configuration workbook.  This can be a wiki, shared spreadsheet, or complex configuration management tool.  Regardless of your method, developers, architects, admins, and environment managers should have a place where they can maintain details about each component of the Salesforce environment.  The configuration workbook can be used to track the lifecycle of components (proposed, designing, testing, released, retired), and should be maintained throughout the development and deployment activities.
  3. Deployment Package – A deployment package contains all of the components necessary for executing a migration to a new environment.  It typically consists of multiple components including the deployment manifest, deployment plan, and release notes.
  4. Deployment Manifest – A deployment manifest is a catalog (list) of all of the components to be migrated through the API.  A change-set is also considered a deployment manifest.  If you are using the ANT Migration toolkit, the manifest is your package.xml file.  It can also be a simple spreadsheet.
  5. Deployment Plan – The deployment plan should list the deployment manifest(s) necessary for migration, as well as any and all manual steps.  The deployment plan should be constructed by the development team and executed by your environment manager.
  6. Release Notes – A successful deployment should include a functional description of the new and changed functionality.  These release notes should be built during the development process and distributed as part of the release by the release manager.
  7. Communication Plan – Another key element of a deployment is an effective communication plan.  This can come via email, blog, or even Chatter.  Business and IT stakeholders must have continual transparency to release timelines in order to plan accordingly.  The release manager should be responsible for the communication plan.
  8. Source Control Tool – Source control should play an active role in your deployment process.  At a minimum, code should be versioned in the source control repository.  Sophisticated teams can use branching, merging, and continuous integration techniques to manage their code and configuration as well.  You can even include most of the documents in this list in your source control repository for versioning.
  9. Deployment Tool – Teams should decide on a specific tool (or tools) for deployment.  The obvious options are Salesforce Change Sets, Eclipse IDE or the ANT Migration tool.  However there are numerous third-party tools that can aid in this process.  Whatever the tool, ensure your team’s consistent and disciplined use of the same tool throughout all of your deployments.
  10. Data Loading Tool – Data loading is a critical aspect of deployments.  Tools for loading data can also be used to automate some processes or manual changes as well (i.e. user/profile changes, etc.).
  11. Metadata Comparison Tool – Having a good tool to analyze differences between orgs can be very helpful.  Verify and understand any differences between orgs as you migrate between them.
  12. Web Browser Testing Tool – Typically, Salesforce deployments can’t be completed 100% through the Metadata API or change sets.  However you can record and replay your manual deployment steps with a tool like Selenium or QTP to achieve 100% automation.
  13. Change Window – This is not a tool but more of a concept. The change window is a critical aspect of your deployment strategy to ensure predictability and trust.  Deployments to production should only occur during an approved change window that both business and IT stakeholders have agreed upon.


A flawless deployment depends on the correct planning, rehearsal, and execution of the following steps (at a minimum!):

  1. Plan

    1. Add the release date(s) to the release calendar using your specific project methodology and business requirements.  Validate your targeted release dates against internal moratoriums and Salesforce’s own release calendar.  (I would NOT recommend planning a large release around Salesforce’s own release dates.  Give things a couple weeks to stabilize.)
    2. Choose a deployment tool. (My preference is the ANT Migration Tool but there are many options here.) The important thing about your deployment tool is to be consistent in its use as you migrate your features through each environment.
    3. Plan to create your deployment package AS you develop.  Changes that can be automated through the API should be listed in the deployment manifest.  Changes that cannot be automated should be documented with detailed instructions in your deployment plan.
    4. Agree to formal Quality criteria for your release.  For example, agree that Zero Critical Defects will be allowed in order to release, while High Priority Defects are allowed in the release with business stakeholder approval, and perhaps 15% or lower Low Priority Defects are allowed in order to release.  Whatever the criteria is, formally document and agree upon this with your stakeholders.  On large projects this criteria is vital to maintaining a viable release date.
    5. Decide on your environment migration path.  You can see my earlier post here on a recommended environment plan.  Regardless of your path, determine which environment will be your “from” environment. (For example, System Test Full Sandbox or Staging Developer Pro Sandbox, etc.)
    6. Determine your Formal Go/No-Go governance methodology.  Who needs to approve the deployment from the business side?  Who from IT?  What formal processes must be followed (Architecture Review Board, ITIL change management process, etc.) in your organization?
    7. Determine your communication plan. Who from the business needs to be informed of the upcoming release?  How far in advance?  Who in IT needs to be informed and on what recurrence?  What about your users?  How will success (or failure) be communicated?  Plan this in advance to ensure appropriate visibility of the Salesforce changes.
    8. If you are working with Salesforce’s Customers For Life program, communicate your release plans with your CFL team.  They can provide timely notifications to both you and Salesforce internally.
  2. Rehearse (Rehearsal for production deployment begins as soon as development and configuration start on the release):

    1. Add any necessary information to the deployment plan and/or deployment manifest AS EACH FEATURE IS DEVELOPED.  It is imperative that production deployment is considered as you build the feature.  For example: if the feature requires an Apex trigger, add it to the deployment manifest; if the feature requires manual changes to the security model, add those instructions to the deployment plan.
    2. Create the appropriate release notes that can be compiled by the release manager AS EACH FEATURE IS DEVELOPED.
    3. Add relevant information to your design docs and configuration workbook AS EACH FEATURE IS DEVELOPED.  This documentation is vital for maintaining complex environments with numerous parallel projects.
    4. Version both your code and your configuration using source control tools.  Utilize branching and merging as necessary based upon your team-specific workflow.  Have developers document the feature number when they check in their code.
    5. Before migrating features out of each development environment, your developers should have built their own feature-specific deployment packages.  Their code should be listed in a feature-specific deployment manifest.  Their manual instructions should be listed in a feature-specific deployment plan.  Their feature-specific release notes should ALREADY be written.
    6. As the feature is migrated into a test environment, take note of any and all issues during the deployment.  Adjust your feature-specific deployment manifest and deployment plans accordingly.
    7. Apex tests should pass in ALL environments.  Use continuous integration or schedule all tests to execute on a nightly basis (in each environment).  Waiting to deal with automated testing and code coverage until near the actual production migration is a recipe for disaster.
    8. As the features migrate “upstream” through your test environments toward your production org, the feature-specific deployment plans and deployment manifests should be combined by the environment manager into the release-specific deployment package.  The environment manager should be responsible for migrating the entire deployment package through your test and staging environments.
    9. As the features migrate “upstream” through the test environments towards your production org, the feature-specific release notes should be consolidated by the release manager.
    10. If you would like to automate the ENTIRE release, including manual steps, create a deployment script (or set of scripts) using a web browser testing tool like Selenium.
    11. Complete a mock-deployment into your staging environment.  This should be repeated as necessary to fully ensure that the deployment plan and deployment manifest are comprehensive.  This staging environment should be an EXACT replica of your production org.  Refresh a new sandbox if necessary to ensure the environments are identical.
    12. Validate your final mock-deployment is successful via smoke-testing and simulated transactions.
  3. Execute

    1. Validate that the necessary approvals are obtained by both the business and IT stakeholders as per your Go/No-Go Governance methodology.
    2. Start your change window, including notifying any appropriate parties.
    3. Freeze all changes to production.  If necessary, lock-out any delegated admins to ensure your org metadata will NOT be changing without your knowledge.
    4. Lock users out of the system.  This can be done by changing their profiles or temporarily freezing them.  Use data loader tools or Apex scripts to automate this process.  (Just don’t lock yourself out!)
    5. Validate your deployment package in production, including Running All Tests.
    6. Backup Salesforce Metadata.  This can be done by creating a new sandbox (or refreshing an old one).  This can also be done using the Metadata API and a source control tool.  Regardless of your approach, this provides you with a safety net to fall back on in case of issues.
    7. Back up Salesforce data.  Depending on the scope and impact of the release, it might be appropriate to back up all data.  This can be done on a scheduled basis by Salesforce (once per week) or a nightly batch process completed by your own data loading tool. Depending on how long this process takes, it might be impractical to do this during your change window.  However try to have a backup completed as close to your change window as possible.
    8. Complete any necessary “pre-migration tasks” outlined in your deployment plan.  These will be any manual steps necessary to “receive” your deployment package.  (These can even be automated with a web-browser testing tool like Selenium.)
    9. Deploy your deployment package to production using your deployment tool of choice.
    10. Complete any necessary “post-migration tasks” outlined in your deployment plan.  These will be any manual steps necessary to provision the release that are NOT supported by the Metadata API.  (These can even be automated with a web-browser testing tool like Selenium.)
    11. Repeat steps 8-10 as necessary to deploy your entire release as per your deployment plan.
    12. Complete a metadata comparison between your “from” environment and your production org.  Make sure any differences are clearly understood or addressed.  You can use a tool like Beyond CompareWinDiff, or even custom Perl/Python scripts.
    13. Load Data.  Once the metadata is stable, any necessary data conversions or integrations can be activated.  Closely monitor the initial transactions to ensure system integrity.
    14. Smoke test the functionality in production.  Regardless of the technical discipline used on the deployment, manually validate that the deployment was successful (so your users won’t be the first ones to do so).
    15. Re-extract all metadata and tag your release in source control.  A release becomes an important milestone to mark your code should you ever need to fall back to an old version.
    16. Unlock users, allowing them back into the system. (Automatically with data loader tools or Apex scripts.)
    17. Close your change window, including notifying any appropriate parties.
    18. Send a notification of the release to the appropriate users and stakeholders as per your communication plan.
    19. Distribute your release notes to any appropriate users.
    20. Update your configuration workbook documentation to indicate the new features are “deployed.”
    21. Refresh any necessary sandboxes and/or make your deployed package available to your sandboxes.

As you can see – there are a lot of people, tools, and processes necessary for supporting a smooth roll-out.  Plan accordingly, rehearse your plan, and follow this criteria in order to ensure your enterprise deployments become predictable and flawless.  (And if the above list is not enough to keep you busy, make sure you have a good plan for training and support.  All of these functions are just as critical to a good deployment and user adoption.)

For more help on executing flawless deployments, consider bringing on a Salesforce Certified Technical Architect (CTA).  CTAs have the technical platform knowledge combined with Application Lifecycle Management experience to help your organization get started.

Get the latest Salesforce Developer blog posts and podcast episodes via Slack or RSS.

Add to Slack Subscribe to RSS