Getting started with Salesforce DX – Salesforce Developer Experience

Important : At time of writing this post, Salesforce DX is in pilot phase. Mostly any product in Salesforce goes from Pilot to Beta and then Generally available. There is no guarantee that if this product is released, it would work like exactly same as written in this post.

Table of Content

• What are Scratch Orgs
• Setting up SalesforceDX
• Authorize Salesforce Instance to be used with SFDX
• Create Scratch Org
• Move code to and from Scratch Org
• List of existing Orgs in SFDX
• Open Salesforce Org from SFDX
• Run Test Classes
• Setup Log Level
• Create Skeleton Workspace
• Generate Password for Scratch Org
• Enable Person Account
• Deploy and Retrieve metadata from Sandbox

If we already have Salesforce Metadata API, Force.com IDE and other tools then why do we need one more tool like Salesforce DX ?

In tools like Changeset, Metadata API or Force.com IDE, source of truth is Sandbox. Although we can setup process and continuous integration (CI) to use some source code management (SCM) like Git or SVN. However these kind of setup takes time, expertise and lot of effort.

Salesforce DX not only solves above problem but

• Ability to consider SCM as source of truth
• Use any favorite IDE or any SCM
• Powerful CLI to help minimizing complexity of setting up CI
• Updated Force.com IDE to support Salesforce DX if you are not comfortable with CLI
• and most important, spin off Scratch Orgs within minutes through script to quickly work on POC or package based development

What are scratch Orgs ?

Salesforce DX can be enabled for any Salesforce instance and they are known as Developer Hub. One Developer Hub can have multiple Scratch Orgs. Scratch Orgs are temporary Salesforce org which can be created quickly and metadata can be deployed from SCM. These kind of Orgs can be used by developers to perform quick proof of concept or build and test packages. Once package is build and saved back on SCM, scratch org can be destroyed easily.

If we already have developer orgs or sandboxes, why do we need scratch orgs ?

Because of compliance of most of clients, we cannot move their code to developer org to perform some POC or package development, so developer org is out of questions anyway.

Now, lets focus on Sandboxes. Use of sandboxes are mostly for end to end testing, integration testing, UAT or training. Sandboxes mostly represents either replica of production or future state of production which might be undergoing through User acceptance testing (UAT). When we refresh Sandbox, we don’t get options on which metadata needs to be copied. Assume situation, there is defect on production and we need to go back to time and check how system was behaving previously. Typical rollback scenario for sandboxes. We might have metadata stored somewhere, but we need to perform many iterations of destructive.xml to delete components from Sandbox. In this case, we can quickly spin off scratch org from source code and perform analysis of historical code.

This is just one example, there are many scenario and specifically for appexchange development companies.

I think, we had lots of talk and ready to roll now.

Setting up Salesforce DX

Install Heroku CLI and then run below command

heroku plugins:install salesforcedx

Other way to install SalesforceDX during pilot is to installer from here (Currently this URL is working however its location is not official). Once downloaded, install it. After installation make sure git command is working from command line.

In Salesforce DX, source of truth is source control. so we need a repository for demo. For this blog post, let’s consider this repository. Run below command to clone this repository

git clone https://github.com/forcedotcom/sfdx-simple
cd sfdx-simple

Authorize Salesforce DX to login to Developer Hub Org

Below command will set org as default Developer Hub Org and will set its alias as my-devhub-org. It will open Salesforce login page in default browser for OAuth flow, where we need to login to Developer Hub org and authorize Salesforce DX.

sfdx force:auth:web:login --setdefaultdevhubusername --setalias my-devhub-org

Creating Scratch Org

To create a scratch org in Salesforce DX, we need to have workspace-scratch-def.json . Best place is to place it in config folder. This file already exists in Git repository we cloned initial however we would need to update it with our FirstName, lastName, Email and Org preferences. All supported preferences are listed here in Metadata documentation.

You can find official documentation on sample scratch org definition file and possible configuration values and features.

Below is sample of file

workspace-scratch-def.json

{
"Company": "Shivasoft",
"Country": "US",
"LastName": "Zaa",
"Email": "jitendra.Zaa@shivasoft.in",
"Edition": "Developer",
"OrgPreferences" : {
"S1DesktopEnabled" : true
}
}

Edition of Org can be Professional, developer or enterprise.

Once workspace-scratch-def.json created in config folder, run below command to create a scratch org. New scratch would be named as jitendra2_scratch and it can be configured by passing parameter to –setalias

Note : At a time of writing this post, scratch orgs auto deleted after 7 days however it may change when product goes GA.

sfdx force:org:create --setdefaultusername -f config/workspace-scratch-def.json --setalias jitendra2_scratch

Moving code to Scratch Org

To move code, we need to define sfdx-workspace.json which contains path of source code needed to be pushed. Below is sample file

simple sfdx-workspace.json

{
  "PackageDirectories": [
    {
      "Path": "force-app"
    }
  ],
  "Namespace": "",
  "SourceApiVersion": "39.0"
}

sfdx-workspace.json with some more options

{
"Namespace" : "AcmeIncExample",
"SfdcLoginUrl" : "https://login.salesforce.com",
"SourceApiVersion": "39.0"
"PackageDirectories" : [
{ "Path" : "helloWorld", "Default": true},
{ "Path" : "unpackaged" },
{ "Path" : "utils" }
]
}

Run below command to push metadata to default scratch org

sfdx force:source:push
or
sfdx force:source:push --targetusername my-scratch-org@bar.com

Get metadata changes from Scratch Org or Pull changes

We can also get metadata changes done in scratch Org either from UI or deployment. It will only pull if metadata changes, not the whole Org.

sfdx force:source:pull
or
sfdx force:source:pull -u org_alias

Getting list of all existing Orgs

Before creating scratch org, you may want to know about the existing orgs and their aliases. We can run below command

sfdx force:org:list

Open Salesforce Org from sfdx

Below command can be used to open Org from sfdx command line

sfdx force:org:open
or
sfdx force:org:open -u org_alias

Running Test classes using Salesforce DX

To run test classes using Salesforce DX , use below command

sfdx force:apex:test:run

Above command will return job Id, use that ID and run next command for status

sfdx force:apex:test:report -i JOBID_FROM_ABOVE_COMMAND

Setting up log Levels

Salesforce DX logs are generated at USER_Home_DIR/.sfdx/sfdx.log. We can set it either with each command or globally. By default only Error logs are recorded but we can change log level. To set log level with each command, we can use –loglevel DEBUG. To set log level globally we can use

//windows
set SFDX_LOG_LEVEL=DEBUG
//Or in unix
Export SFDX_LOG_LEVEL=DEBUG

Currently below log levels are supported

1. ERROR
2. WARN
3. INFO
4. DEBUG
5. TRACE

Creating skeleton workspace

We can automatically generate skeleton workspace using CLI which will create folder structure and json files with default value.

sfdx force:workspace:create --workspacename mywork

OR

sfdx force:workspace:create --workspacename mywork --defaultpackagedir myapp

Above command will create below folder structure

Password for scratch Orgs

When we create a scratch org using sfdx CLI, it does not display password and uses OAuth internally to communicate with scratch org. If we need to login to scratch org from non sfdx CLI, then we would need to generate a password. Below command can be used to generate password.

sfdx force:user:password:generate

Message :

Successfully set the password "26y271a" for user scratchorg1495650731268@shivasoft.in. You can see the password again by running "force:org:describe".

If we want to see password in future, then use below command

force:org:describe

Enable Person Account

Make sure below steps are completed in Salesforce Hub instance before running below sfdx script

1. Create Record Type on Account
2. Make sure OWD setting for contact is Controlled by Parent.

Below code in project-scratch-def.json file would create a Person Account

{
    "orgName": "Person Account Scratch Org",
    "edition": "Enterprise",
    "features": ["PersonAccounts"]
}

Retrieve and Deploy code in Sandbox using SFDX

This blog post goes in detail, however, below is quick command

Retrieve Metadata from Sandbox

sfdx force:mdapi:retrieve -r ./mdAPIZip -u jzaa1 -k src/package.xml

Deploy Metadata to Sandbox

--deploy zip file
sfdx force:mdapi:deploy   -f ../mdAPIZip/unpackaged.zip -u jzaa1 -w 10
or
--deploy traditional file structure
sfdx force:mdapi:deploy  -d ../mdAPIZip/unpackaged -u jzaa1 -w 10