Start tracking your progress
Trailhead Home
Trailhead Home

Develop and Test Changes Locally

Learning Objectives

After completing this unit, you’ll be able to:

  • Create a branch and commit changes to a source control repository.
  • Authorize a sandbox using Salesforce Extensions for VS Code.
  • Retrieve changes from a sandbox.

Set Up a Code Repository

The Zephyrus Relocation Services development team hosts their code and reviews their work in GitHub. Previously, a team member could accidentally overwrite someone’s changes by deploying a change set right over an existing change set. Now they commit changes to the source repository to identify and merge any customization conflicts before they continue.

Important

Important

The main goal of this module is to demonstrate the org development model workflow. This module doesn’t have a hands-on challenge. However, we understand that trailblazers don’t tend to sit on the sidelines. If you try the steps demonstrated in this module, we provide guideposts (notes) when your instructions differ from Ella and Juan’s. Keep your sandboxes for “real” development work. Before you begin, sign up for a Developer Edition org or Trailhead playground to use in place of each sandbox.

Create the Source Control Repository

The repository is where Juan organizes the source files for the development project. Juan then creates a Salesforce DX project and adds it to the repo.

  1. Create an empty GitHub repo.
  2. Name the repo something descriptive to reflect its purpose. Because this in an internal development project, Juan creates a private repository using Zephyrus’s enterprise account called language-courses.

Create a Salesforce DX Project

  1. Open VS Code.
  2. From the menu, select View | Command Palette.
  3. In the command palette search box, enter sfdx project.
  4. Select SFDX: Create Project.
  5. Use the same name as your GitHub repo, then click Enter.
  6. Click Create Project.
  7. Create a .gitignore file to ignore hidden directories:
    1. Hover over the title bar for the DX project. then click the New File icon.
    2. Enter .gitignore.
    3. In the text editor, indicate to ignore these two hidden files:
      .sfdx
      .vscode

Add Project Files to the Repo in GitHub

Note

Note

We’re using GitHub Enterprise 2.14.6 in these steps.

  1. In Windows Explorer or Finder, open the Salesforce DX project folder.
    Make sure your file manager shows hidden files and folders.
    • If you’re using macOS Sierra or a higher version, open Finder, then select command + shift + .(dot) on your keyboard.
    • On Windows, in the Control Panel, select Folder Options. Click Show hidden files and folders.
  2. In GitHub, under Quick Setup, click uploading an existing file.The GitHub Quick Setup banner, where you can click "uploading an existing file" to get started seeding the repo with files.
  3. From your file manager, drag the directories and project files (but not .sfdx or .vscode) to GitHub.
    • .gitignore
    • sfdx-project.json
    • README.md
    • config/project-scratch-def.json
    Screenshot that shows the GitHub Code tab with an area in the middle where you can drag project files. At the bottom, you add a comment before you commit the changes.

    GitHub doesn’t allow you to add empty directories, so the force-app folder isn’t imported. But that’s okay. Ella creates it manually when she needs it.

  4. Click Commit directly to the master branch.

Create Customizations for New Requirements

Calvin has met with the Sales team to gather new requirements for the next release. The Sales team wants to be notified when a language course is added or changed, and they want to know who is teaching each course.

Juan thinks this request is a great way to for the team to get comfortable with the org development model. Although it can handle far more complex development scenarios, this simple set of steps can help the team understand the model workflow.

Ella’s assignment is to create a custom object for language course instructor and to link it to the course record. Juan creates a trigger that sends a notification email to the Sales team alias. These are the steps:

Create the Custom Object

First, Ella clones the GitHub repo and creates her own branch.

  1. Go the repo you want to clone, for example, https://github.com/zephyrus/language-courses.
    Note

    Note

    This repo doesn’t exist. It’s meant for illustrative purposes only. If you plan to follow along, substitute the sample repo you created in these steps. Also, you’ll be simulating the work of two developer personas, Juan and Ella. We suggest creating two separate parent directories to keep their development work separate. For example, if you’re doing Ella’s development work, you clone the repo in an org-dev-ella folder. When you’re doing Juan’s development work, you clone the repo in an org-dev-juan folder.

    1. Click Clone or download.
    2. Copy the HTTPS URL.
  2. From the command palette in VS Code, select Git: Clone.
  3. In Repository URL, paste the URL to the repo, then click Enter. Ella clones the repo that Juan created: https://github.com/zephyrus/language-courses.git.
  4. On your local file system, navigate to the place you want to put the GitHub repo, then click Select Repository Location.
  5. Click Open Repository.
  6. From the command palette, select Git: Create Branch.
  7. Enter your branch name. Ella calls her branch ella-custom-object. Now she’s working in her own branch.

Authorize and Log In to the Sandbox

Next, Ella authorizes (logs in) to her Developer sandbox using VS Code.

Note

Note

If you’re following along, use a Developer Edition org or Trailhead Playground. In step 3, select Project Default to use login.salesforce.com as the login URL.

  1. From the command palette search box, enter sfdx authorize.
  2. Select SFDX: Authorize an Org.
  3. Select Sandbox for the login URL (test.salesforce.com).
  4. Enter an alias for the sandbox—for example, dev_sandbox.
  5. Log in with the sandbox username and password.

Create the Custom Object

Then, Ella creates the Language Instructor custom object in her Developer sandbox.

  1. From Setup, click the Object Manager tab.
  2. Click Create | Custom Object in the top-right corner.
  3. For Label, enter Language Course Instructor. Notice that the Object Name and Record Name fields auto-fill.
  4. For Plural Label, enter Language Course Instructors.
  5. Check the box for Launch New Custom Tab Wizard, then click Save.
  6. Select your desired tab style (Ella chooses Presenter), and click Next until you can save the object.

Define the Custom Field

Next, Ella defines the custom object field on the Language Course object that references the Language Course Instructor object.

Note

Note

If you’re following along, Ella created the Language Course object in Develop and Test Changes Locally in the Change Set Development Model module. This module assumes this object already exists in Ella’s Developer sandbox. Create this custom object before continuing.

  1. From Setup, go to Object Manager | Language Course.
  2. Click Fields & Relationships. Notice that some fields are already there, including a name field.
  3. Click New.
  4. For data type, select Master-Detail Relationship, then click Next.
  5. From Related To, select Language Course Instructor, then click Next.
  6. Fill out the following:
    • Field Label: Course Instructor
    • Description: Teacher for the language course
  7. Click Next until you can save the field.

Track the Changes in a Change List

Ella creates a change list for the project to capture her changes.

Metadata Entity Object Change Type (Create, Update, Delete) Details
CustomObject Language_Course_Instructor__c Create Object to capture the name of the person teaching the course
CustomField Course_Instructor__c Create Master-detail relationship with Language_Course__c custom object

Retrieve the Changes from the Developer Sandbox (Beta)

Note

Note

As a beta feature, the non-source-tracked org commands are a preview and aren’t part of the “Services” under your master subscription agreement with Salesforce. Use this feature at your sole discretion, and make your purchase decisions only on the basis of generally available products and features. Salesforce doesn’t guarantee general availability of this feature within any particular time frame or at all, and we can discontinue it at any time. This feature is for evaluation purposes only, not for production use. It’s offered as is and isn’t supported, and Salesforce has no liability for any harm or damage arising out of or in connection with it. All restrictions, Salesforce reservation of rights, obligations concerning the Services, and terms for related Non-Salesforce Applications and Content apply equally to your use of this feature. You can provide feedback and suggestions for the non-source-tracked org commands in the Salesforce DX Trailblazer Community.

Ella retrieves the changes from the sandbox to her local DX project. Because Ella tracks her changes along the way, she knows what to retrieve from her Developer sandbox.

Because Ella retrieves only a few components from her sandbox, she decides to use the Terminal in VS Code to run the Salesforce CLI force:source:retrieve command. Based on the default directory specified in the DX project, the CLI places source in the force-app folder. Because you can’t add an empty folder in GitHub, Ella creates the force-app folder in the DX project on her local file system.

  1. In the DX project on the local file system, create a force-app folder.
  2. In the VS Code Terminal, run the CLI command to retrieve the new custom object and custom field:
    sfdx force:source:retrieve --metadata CustomObject:Language_Course_Instructor__c,CustomField:Language_Course__c.Course_Instructor__c

    Ella uses --metadata instead of --sourcepath because --sourcepath can retrieve only files that already exist on the file system. The custom object appears in the force-app/main/default/objects directory.

    In VS Code, the left side shows the new directory structure created after the source:retrieve command: force-app/main/default/objects. The right side shows the Terminal window where the command was run as well as the resulting CLI output.

Commit the Changes to the Source Control Repository

Ella commits her changes to the repo, then creates a pull request to inform Juan that her changes are ready to review.

  1. In VS Code, select the Source Control icon Source Control icon.
  2. Enter a commit comment, then click the Commit icon Commit icon.
  3. Click Yes to add and commit the files.
  4. From the VS Code command palette, select Git: Push To.
  5. Select the origin repository.

Review the Code

Note

Note

If you’re following along, you can skip this section.

  1. Create a pull request. In the GitHub repo, click Compare & pull request.
  2. Assign reviewers. Ella assigns Juan to review and approve her changes.
  3. Enter a comment for your reviewers.
  4. Click Create pull request.

After Juan reviews and approves the code, Ella merges the pull request. Juan knows that he can begin his trigger work.

Create the Trigger

The trigger notifies the Sales team when a course is updated or a new course is added. A trigger is a piece of Apex code that executes before or after records of a particular type are inserted, updated, or deleted from the Lightning Platform database.

Juan clones the GitHub repo that contains the new custom object, creating his own branch. Juan creates his trigger and its corresponding test in VS Code.

Deploy the Project Repo to the Developer Sandbox

First, Juan deploys Ella’s changes to his Developer sandbox so that both their environments are in sync.

Note

Note

If you’re following along, perform these steps in the folder you created for Juan’s development work, such as org-dev-juan. Use a new Developer Edition org or Trailhead playground for Juan’s Developer sandbox.

  1. Clone the GitHub repo.
  2. In VS Code, select Git: Create Branch, then provide a name for the branch. Juan names his branch juan_apex_trigger.
  3. Select SFDX: Authorize an Org.
  4. Select Sandbox for the login URL (test.salesforce.com).
  5. Enter an alias for the sandbox—for example, dev_sandbox.
  6. Log in with the sandbox username and password.
  7. Deploy Ella’s changes to his developer sandbox. Right-click the objects folder, then select SFDX: Deploy Source to Org. Alternately, Juan can run the Salesforce CLI command in the Terminal.
    sfdx force:source:deploy --metadata CustomObject:Language_Course_Instructor__c, \
    CustomField:Language_Course__c.Course_Instructor__c

Develop the Trigger

  1. In the juan_apex_trigger branch in VS Code, create the directory to put the trigger.
    1. Expand the force-app folder.
    2. Right click default, then select New Folder.
    3. Enter triggers.
  2. Right-click the triggers folder, then click SFDX: Create Apex Trigger.
  3. Enter LanguageCourseTrigger for the trigger name.

    Enter the code for the trigger:

    trigger LanguageCourseTrigger on Language_Course__c (after insert, after update, after delete) {
    // <write your own notification code>
    }
  4. Save the file.
  5. Create a test for the trigger called TestLanguageCourseTrigger. As a seasoned developer, Juan makes sure that code coverage requirements are met.

Deploy the Changes to the Developer Sandbox

Juan deploys the trigger to validate and compile it, and then tests that it’s working correctly with the new object.

  1. In the VS Code Terminal, right-click the triggers folder, then select SFDX: Deploy Source to Org.

    Alternately, Juan can run the CLI command from the Terminal.

    sfdx force:source:deploy --sourcepath force-app/main/default/triggers
    In VS Code, the left side shows the new directory structure created after the source:deploy command for the trigger: force-app/main/default/triggers. The right side shows the Terminal window where the command was run as well as the resulting CLI output.
  2. Juan verifies that he captured all the changes and they work in the sandbox.
  3. Juan adds his changes to the change list.
Metadata Entity Object Change Type (Create, Update, Delete) Details
CustomObject Language_Course_Instructor__c Create Object to capture who is teaching the course
CustomField Course_Instructor__c Create Master-detail relationship with Language_Course__c custom object
ApexTrigger LanguageCourseTrigger Create Emails Sales team when Language_Course__c object is created, updated, or deleted
ApexClass TestLanguageCourseTrigger Create Apex test coverage for the trigger

Commit the Changes to the Source Control Repository

Juan commits his changes to the repo, then creates a pull request. Ella performs the code review.

Plan the Next Release

Juan and Ella follow the same process for future customizations. If they develop customizations in VS Code, such as Juan’s trigger work, they deploy them to their Developer sandboxes for validation and testing.

They use Setup for everything else, so they can take advantage of builders and wizards and declarative interfaces. And then they retrieve those changes from the sandbox to their local file systems. They commit their changes to source control, create a pull request, and request a code review before merging their changes to the master branch.

retargeting