Migrating Existing Projects to Salesforce DX

Are you ready to move to Salesforce DX, but your source code is currently in a Developer Edition (DE) or Sandbox org? In this blog post, I describe the easy steps to convert existing source code to a Salesforce DX project.

I recently converted the latest version of the DreamHouse sample application to a Salesforce DX project, and I thought it would be helpful to document the process so you can use the same steps to convert your own projects to Salesforce DX. The end result for the the DreamHouse app is available in this repository, but the steps below are applicable to any project.

Step 1: Convert your project to Salesforce DX

1. Create an unmanaged package in your existing org, and include all the assets you want to move to your Salesforce DX project. You don’t need to upload the package, and you don’t have to worry about the 75% code coverage for this purpose.
2. If you haven’t already done so, authenticate with your hub org. Type the following command, then login with your hub org credentials and accept to provide access to Salesforce DX:

   sfdx force:auth:web:login -d -a myhuborg

3. Create a new Salesforce DX project:

   sfdx force:project:create -n myproject
   cd myproject
   

4. Authenticate with your developer edition org. Type the following command, then authenticate with your developer edition org credentials and accept to provide access to Salesforce DX:

   sfdx force:auth:web:login -a mydevorg

5. Export the unmanaged package metadata in a temporary directory. Type the following commands in the root folder of your Salesforce DX project:

   mkdir temp
   sfdx force:mdapi:retrieve -s -r ./temp -u mydevorg -p mypackage
   

   “mypackage” is the name of the unmanaged package you created in step 1. Afer executing this command, a file named unpackaged.zip is created in the temp directory.

6. Unzip unpackaged.zip using a zip file management utility or from the command line. For example, on a Mac, double-click unpackaged.zip in Finder or type the following command on the command line:

   unzip ./temp/unpackaged.zip -d ./temp/

7. Convert the source code to the Salesforce DX project structure:

   sfdx force:mdapi:convert -r ./temp

   You can delete the temp directory at this point.

8. Create a scratch org:

   sfdx force:org:create -s -f config/project-scratch-def.json -a  myscratchorg

   If you get an expired access/refresh token message, authenticate with your hub org again (step 2 above).

9. Push the code to your scratch org:

   sfdx force:source:push

10. Open the scratch org:

    sfdx force:org:open

11. Create a permission set to provide access to your project’s assets:
    • In Setup, type permission in the quick find box, click the Permission Sets link, and click New
    • Provide a name for your permission set and click Save
    • Add the required permissions
    • Click Manage Assignments and assign the permission set to the default user (User, User)

    For example, here are the permissions I added for the DreamHouse app:

    • Assigned Apps: I added the DreamHouse app
    • Object Settings: I added all available permissions (Tab settings, Object Permissions, and Field permissions) for all the custom objects used in DreamHouse: Broker__c, Property__c, Favorite__c and Bot_Command__c.
    • Apex Class Access: I added all the classes
    • Visualforce Page Access: I added all the Visualforce pages
    • In the Find Settings box, I typed the name of all the tabs used in DreamHouse (HeatMap, HeatMap demo, Einstein Vision, and Command Center), and I enabled access (checked Visible).
12. Pull the permission set

    sfdx force:source:pull

Step 2: Transfer sample data (Optional)

The Salesforce DX CLI also makes it easy to export sample data from your developer org and import it in your scratch orgs. It even preserves master-details relationships between records. As an example, here is how I did it for the DreamHouse app:

To export the data from my DE org, I ran the following command from the root folder of my Salesforce DX project:

sfdx force:data:tree:export -q "\
    SELECT Id, \
           Name, \
           Title__c, \
           Phone__c, \
           Mobile_Phone__c, \
           Email__c, Picture__c, \
           (SELECT Id, \
                   Name, \
                   Address__c, \
                   City__c, \
                   State__c, \
                   Zip__c, \
                   Price__c, \
                   Title__c, \
                   Beds__c, \
                   Baths__c, \
                   Location__Longitude__s, \
                   Location__Latitude__s, \
                   Picture__c, \
                   Thumbnail__c, \
                   Description__c \
            FROM Properties__r) \
    FROM Broker__c" \
    -u mydevorg --outputdir ./data --plan

After executing this command, the sample data files (Broker__cs.json, Property__cs.json, and Broker__c-Property__c-plan.json) are available in the data subfolder of my project which means that they will be part of the project when I put it under version control (step 3 below).

To import the data in my scratch org, I run the following command:

sfdx force:data:tree:import -u myscratchorg \
    --plan ./data/Broker__c-Property__c-plan.json

Step 3: Put your project under version control

We are done converting the project and transferring data. It’s time to put the project under version control. For example, using Github:

git init
git add . -A
git commit -m 'first commit'
git remote add origin https://github.com/yourname/your-repo.git
git push origin master

That’s it. It’s now easier than ever for other developers to work with you on the project. Using the migrated DreamHouse project as an example, all they have to do is:

1. Clone the repository. For example:

   git clone https://github.com/dreamhouseapp/dreamhouse-sfdx
   cd dreamhouse-sfdx
   

2. Create their own scratch org:

   sfdx force:org:create -s -f config/project-scratch-def.json -a myscratchorg

3. Push the app to their scratch org:

   sfdx force:source:push

4. Assign the permission set to the default user. For example:

   sfdx force:user:permset:assign -n dreamhouse

5. Import data in the scratch org. For example:

   sfdx force:data:tree:import -u myscratchorg \
       --plan ./data/Broker__c-Property__c-plan.json
   

6. Open the scratch org:

   sfdx force:org:open

Summary

Salesforce DX enables modern development workflows on the Salesforce platform. It makes team development, version control, and continuous integration easier than ever. Migrate your existing projects to Salesforce DX today using the easy steps described in this post and watch the pull requests come in!

Resources

• Trailhead Module: App Development with Salesforce DX
• Salesforce DX microsite