Add Customizations Post Installation

The time estimate for completing the steps in this unit is just an estimate. Your own installation might take longer, depending on your system configuration and network speed.

Learning Objectives

• Explain how to create and capture customizations with CumulusCI.
• Describe how to test the customizations and make them available for others.

Maddie has completed the first two steps of constructing her sundae. Now, it’s time to add her own favorite toppings that include a custom field on the Delivery Item object to track if produce is local. She’ll do this directly in a Salesforce scratch org and use CumulusCI to capture her customizations, test them, and push them to Production.

Create a Custom Field

Follow along as Maddie works.

The first step is to create the customizations. Do this declaratively using the clicks-not-code interface in Salesforce. 

1. If you still have the dev scratch org you set up in the previous unit, Create an Implementation Project, open, skip to step 4.
2. Otherwise, start in GitHub Desktop. Make sure Current Repository is set to Food-Bank-Implementation and open this repository by choosing Repository→Open in Visual Studio Code.
3. Open your scratch org in a browser by entering this command in your VS Code Terminal: cci org browser dev
4. Open Setup.
5. Go to the Object Manager.
6. Click on the Delivery Item object from the Food Bank managed package.
7. Click Fields & Relationships in the sidebar.
8. Click the New button.
9. Choose Checkbox then the Next button.
10. Enter the details for the field:
    Field Label:Is Local Produce
    Field Name:Is_Local_Produce (accept the default)
11. Click the Next button and Next again to accept the default profiles.
12. Add the field to the Delivery Item page layout.
13. Click Save.

Capture the Field as Unpackaged Metadata

Use CumulusCI to capture the changes you made in the scratch org.

1. In GitHub Desktop, make sure Current Repository is set to Food-Bank-Implementation
2. Open this repository by choosing Repository→Open in Visual Studio Code.
3. Review the changes you made to make sure they include all the customizations you want to capture. In the VS Code Terminal window, Type in this command: cci task run list_changes --org dev
4. Scroll in the the Terminal window to review the changes you’ll capture. These should include your new field as well as the Delivery Items page layout because you added the new field to the page layout. If it all looks good, capture the changes by typing in this command in the VS Code Terminal: cci task run retrieve_changes --org dev -o exclude "Profile:"

When it’s done, go to GitHub desktop to view the changes.

With the changes all safe and sound in the Version Control System (GitHub Desktop, in this case), it’s safe to get rid of the dev scratch org that you used. Do this by entering this command in VS Code’s Terminal Window: cci org scratch_delete dev

Test the Changes

Before committing any changes to the main branch of a repository—or in this case the source of truth for Hunger Northeast’s Salesforce configuration—it’s important to test the work to make sure it’s ready for all users. To test that the newly captured metadata can be successfully deployed to a new org, Maddie will create a new QA scratch org. Follow along as she does this work.

1. In VS Code’s Terminal window enter the command to create a scratch org in a QA org: cci flow run qa_org --org qa
2. Once the scratch org’s been created (it’ll take 10-15 minutes), enter the command to open the scratch org in a browser: cci org browser qa
3. Take a look around the scratch org, and you should find the new Is Local Produce field on the Delivery Item object.

Commit and Merge Changes

Now that you’ve tested the additional config on your personal computer, add the customization to your GitHub repository. First, create a feature branch and add your changes to it:

1. Open your repository in GitHub Desktop. You should see your changes from the last module, which you pulled from the dev scratch org.
2. Select the tab named Current Branch: main.
3. Click New Branch, to create a new branch off of main.
4. Enter feature/local for the branch name and click Create Branch.
5. Select Bring my changes to feature/local. This tells GitHub Desktop that you want the changes you’ve already made to start out your new branch.
6. Click Switch Branch to make sure you’re on the new feature/local branch.

Publish the changes and the new feature branch in GitHub:

1. Enter a Commit Message and Description indicating what you've changed, perhaps something like Created new checkbox on the Delivery Item object to track local produce.
2. Click Commit to feature/local.
3. Publish the feature branch to GitHub by clicking Publish branch on the information pane that comes up after your commit is complete.
4. Once your branch is published, select Branch > Create Pull Request to create a new pull request for this change.
5. GitHub Desktop will automatically navigate you to the Open a pull request screen in your web browser.
6. Under the header Changes, add a line to describe what you did.
7. Click Create Pull Request.
8. On the next screen, click Merge pull request.
9. Click Delete branch to remove the branch we just merged.
10. Back in GitHub Desktop, choose Branch→Delete and confirm that you want to delete the branch feature/local.
11. GitHub Desktop automatically takes you back to the main branch. Choose Repository→Pull to bring down the changes you merged from feature/local on GitHub.

Lastly, in the GitHub menubar, choose Repository→Open in Visual Studio Code to open VS Code’s Terminal window, and delete your scratch org with this command: cci org scratch_delete qa

Resources

• Website: Salesforce Help, Create Custom Fields
• Trailhead: Add Custom Fields
• Get Help: CumulusCI group on the Trailblazer Community