Create an Implementation Project

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 why you should create a separate project for additional customizations.
• Describe how to configure CumulusCI to install additional packages.

Before attempting  the Hands-On Challenge at the end of this module, make sure you follow along and complete the same steps Tasha takes throughout this and the preceding modules in the Build Applications with CumulusCI trail.

AND do your steps in your Trailhead playground instead of in a sandbox like Tasha did. 

• CumulusCI Setup - steps and Hands-On Challenge
• Community Project Development with CumulusCI - steps
• Data Management with CumulusCI - steps
• CumulusCI for Managed Packages - steps and Hands-On Challenge

In this module, we continue the story of a collaborative community team developing an open source app with the potential to benefit thousands of food security organizations.  The team has created a managed package and now is working on the first implementation for Tasha's friend Maddie's organization, Hunger Northeast, including Salesforce.org's Nonprofit Success Pack (NPSP) and customizations specific to the needs of her organization.

Build a Sundae for Maddie’s Org

Maddie is excited to start using the new Food Bank managed package for her own food bank. It's a solid start and covers functionality that will be useful to her organization for tracking a good portion of their programmatic work. Along with the new managed package, they'll use Salesforce and Nonprofit Success Pack to track fundraising, relationships with constituents, and volunteers for the food bank. 

Maddie has some reporting needs that are specific to her organization that require customization. A meaningful portion of Hunger Northeast’s funding comes from a state agency that’s studying the benefits of a healthier diet among people who access food banks. The state provides funding for Hunger Northeast to include fresh, local produce in food bank shares. A requirement of this funding is Hunger Northeast needs to track details of each box that goes out. She’d like to add a checkbox to capture whether the share included local produce. She’ll add this to the Delivery Item object from the Food Bank managed package.

In order to meet all these needs, Maddie needs to customize, or build her own Salesforce sundae, including:

• The bowl (Force.com platform)
• The brownie (NPSP, an open source Salesforce.org product)
• The ice cream (the food bank managed package)
• Her own favorite toppings (the new checkbox)

Maddie and Tasha know they could simply start with the Nonprofit Success Pack trial, install the Food Bank managed package, and add the checkbox field, but Maddie is invested in gaining a deeper understanding of the Salesforce platform. She foresees that her requirements are likely to change over time and she’d like to have enough of an understanding to adapt her org or to work with a consulting partner in the future.

Maddie and Tasha realize they need to build a sundae-making machine—a new CumulusCI project to build orgs that suit her needs, just like Tasha used a CumulusCI project to build her package. That way, Maddie or anyone else working with Hunger Northeast can test without risking any part of their org.

As part of this new project, Tasha and Maddie will capture the post-install customizations needed for Maddie’s org in a new repository on GitHub that holds their CumulusCI project and serves as the source of truth for the org. This has multiple benefits, including:

• Maddie can quickly create a new scratch org for testing or experimentation that includes all the parts of her org’s sundae.
• She can review the history of changes to the components in the org.
• The food bank can share the configuration with a third-party partner for development without providing full access to Maddie’s production and sandbox orgs.
• If the customizations turn out to be relevant to other food banks, Maddie can easily share them with Tasha and Isabel and propose updates to the Food Bank managed package.

With these benefits in mind, Maddie decides to leverage CumulusCI to create her sundae-making machine.

Create Another Git Repository

Maddie’s org implementation will live in its own GitHub repository. To create it, she follows these steps. Follow along in GitHub desktop on your computer.

1. Open GitHub Desktop.
2. Select File→New Repository from the menu.
3. Enter the information for the repository below:
   1. Name: Food-Bank-Implementation
   2. Description: Maddie’s food bank org
   3. Local Path: Choose GitHub folder, or create a new one if you see a warning
   4. Git Ignore: None
   5. Licence: None
4. Click Create Repository.

Set Up CumulusCI

Now, set up CumulusCI for the implementation project, much like you did for the managed package project.

1. Make sure you’re in the Food-Bank-Implementation repository in GitHub Desktop.
2. Open your repository in your terminal by choosing Repository→Open in Visual Studio Code.
3. In the Terminal window, type: cci project init
4. Answer the series of prompts for information about your project as follows.
   1. Use default Project Name (press Return)
   2. Use default Package Name (press Return)
   3. Managed package project: n
   4. Use default API Version (press Return)
   5. Use default source format sfdx (press Return)
   6. This project extends NPSP:
      1. Answer y
      2. Then answer 2
   7. Accept the defaults for all remaining questions (press Return)

When you’re done, you should see the following line in your Terminal: Your project is now initialized for use with CumulusCI

1. In the VS Code Terminal, type the command: cci service connect devhub --project
2. When it prompts you to enter Username:, enter: CCIDevHub
   • You should login to the devhub that you created in the previous module.

This configures CumulusCI to use the special Dev Hub org that you created for this trail when you ask it to create scratch orgs for this project.

Add Dependency Packages

When Maddie set up her GitHub repository, she indicated her project was dependent on NPSP. Maddie’s implementation will also depend on the Food Bank managed package. Follow along as Maddie adds the managed package.

1. In GitHub Desktop, open your Food-Bank-Implementation repository by choosing Repository→Open in Visual Studio Code.
2. In the Side Bar, under the Food-Bank-Implementation header find cumulusci.yml and click it to open it in the Editor area of VS Code.
3. Find the list of dependencies. Add a line below the dependency on a SalesforceFoundation repository (the Nonprofit Success Pack) to point to the repository you created in Community Project Development with CumulusCI. On the new line, add - github: 'https://github.com/YourGitHubUsername/Food-Bank'

Be sure to type your actual GitHub username instead of YourGitHubUsername!

It should look something like this when you’re done:

    dependencies:
      - github: 'https://github.com/SalesforceFoundation/NPSP'
      - github: 'https://github.com/YourGitHubUsername/Food-Bank'

Installing NPSP as a dependency takes care of installing the NPSP managed package. Orgs with NPSP usually also have some unpackaged metadata for things like Opportunity record types, page layouts, and custom settings. NPSP’s config_managed flow does this additional configuration, and that flow is stored in the NPSP repo (shorthand for “repository”) on GitHub. Now you'll add a new dependency to your cumulusci.yml file.

Warning: Copy the code in these steps directly by selecting everything in the code block and pressing Command+c (macOS) or Ctrl+c (Windows). Do NOT use the on-screen Copy button for this update to your cumulusci.yml file, because using the button to copy will result in errors.

1. In the cumulusci.yml file, add a line to the end and make sure it’s not indented.
2. Add the source of the NPSP config_managed flow:

sources:
    npsp:
        github: https://github.com/SalesforceFoundation/NPSP

Before you add the new dependency, check to see what dependencies already exist.

Warning: Copy the code in these steps directly by selecting everything in the code block and pressing Command+c (macOS) or Ctrl+c (Windows). Do NOT use the on-screen Copy button for this update to your cumulusci.yml file, because using the button to copy will result in errors.

If you’re using Windows, the following command can sometimes show an error that starts with “Error: [Errno 2] No such file or directory...”. This is because CumulusCI has issues processing file paths longer than 260 characters. If you encounter this error, try moving the Food-Bank-Implementaion folder up a level or two in your file system.

1. In the Terminal window, enter: cci flow info dev_org
2. In the Terminal window, you should see two Tasks under the dependencies flow, and you want to add your new dependency after the first two. In your cumulusci.yml file, add a line below your new sources section and make sure your cursor isn’t indented.
3. Add the new flow as a third step under the dependencies flow by typing this:

flows:
    dependencies:
        steps:
            3:
                flow: npsp:config_managed

Finally, save the file and make sure your additional dependency was added.

1. In the Terminal window, enter: cci flow info dev_org

You should now see three steps in the dependencies flow:

Description: Deploy dependencies to prepare the org environment for the package metadata
1) task: update_dependencies [from current folder]
2) task: deploy_pre
3) flow: npsp:config_managed

See the New Dependency in a Scratch Org

See this new dependency in action by creating a scratch org for the Food-Bank-Implementation project! It may take up to 30 minutes for CumulusCI to create a scratch org, install, and configure the NPSP and food bank packages.

1. In GitHub Desktop, open your repository by choosing Repository→Open in Visual Studio Code.
2. Type this command: cci flow run dev_org --org dev
3. Once the flow has completed, open the scratch org in a browser by typing: cci org browser dev
4. Go to the Installed Packages page in Setup to verify that Nonprofit Success Pack and the food bank managed package are installed.

Commit Your Changes to GitHub

Before moving to the next step, make sure your new project is committed to GitHub.

1. Open GitHub Desktop and make sure that your Food-Bank-Implementation repository is selected under Current Repository.
2. You should see a list of changed files on the left-hand side of your screen. All of the files should be selected.
3. In the bottom left Summary field, enter a brief summary of your changes, such as Set up project.
4. Click Commit to main.

Next, publish the work to GitHub. You’ll need to have your work published for the next units.

1. On the right-hand side of your screen, locate the section Publish this repository to GitHub and click Publish repository. Because this is a test project, you may want to select Keep this code private, which means that other GitHub users won’t see your work.
2. Click Publish Repository.

Just like that, Maddie created a sundae-making machine and CumulusCI can construct most of the sundae for her org! She made sure the brownie (NPSP) will be added to the Salesforce org bowl first and the Food Bank ice cream flavor (the Food Bank app) will be added after the brownie is in the bowl. Next, she’ll add the special toppings that will customize the org for Hunger Northeast.

Resources

• Get Help: CumulusCI group on the Trailblazer Community