Add Demonstration Data to Your Org

Learning Objectives

• Add a set of record data.
• Automate deploying captured record data to scratch orgs.

With a working knowledge of CumulusCI tasks and flows in her toolkit, Tasha sits down to create the automation she needs to flesh out the story of her application. 

Designing and Creating Demonstration Data

Tasha is thinking through what data would make a demo come to life. She’s getting input from the volunteers she’s enlisted to test out new versions of the application about the records they create, and imagining what might make a new user feel at home. 

Working in a scratch org, Tasha builds out the dataset: a carefully chosen set of Accounts, Deliveries, and Delivery Items that look natural and show off how a food bank can use the application. She uses a CumulusCI task to capture the data she’s created into the repository, and then makes changes to her cumulusci.yml file to automate adding the data to every new scratch org she builds. Finally, she creates a new feature branch and Pull Request to share her work with the community.

Follow along with Tasha as she creates the dataset.

Capture a Dataset

1. Create a new feature branch to store the changes. In GitHub Desktop, choose Current Branch→New Branch, and name the branch feature/demo-data.
2. Create a dev org to work in. Open VS Code (via Repository→Open in Visual Studio Code in GitHub Desktop).
3. Create a new terminal in VS Code (Terminal→New Terminal).
4. In the new terminal, enter the following command: cci flow run dev_org --org dev
5. CumulusCI needs to know what information, in which objects and which fields to capture. Start by creating a mapping file to teach CumulusCI what data you’re interested in: cci task run generate_dataset_mapping --org dev
6. If you’d like, review the mapping.yml file that CumulusCI created by clicking on mapping.ymlin the Explorer to open the file in the Editor panel. The mapping file defines the fields the data should go into and the order to load the data into the objects. Fields you added in the current project are automatically included as well as a selection of required fields on related standard objects.
   1. You might notice Account Name is included in your file. Though that’s not a field you customized in your config, it’s referenced as a lookup field on your new Deliveries object. CumulusCI only pulls in the one required Account Name field, and you can add other Account fields later if you want to capture more information about the organizations involved in the deliveries.
7. Open the dev org in a browser to start creating data with this command: cci org browser dev
8. Think about what Accounts, Deliveries, and Delivery Items a real food bank using this package might create, and how you might use those records to demonstrate the application’s functionality. Create some records in the dev org, making sure to create at least one record in each object you may want to highlight in a demo.
   1. Since we have a Custom Tab for Deliveries, you can navigate to the tab to create your records, and then add Delivery Items from the related list.
9. Return to the terminal to capture the data changes you made. CumulusCI’s dataset tasks capture or load all of the data defined in the mapping file at once. To capture the created data using the mapping file, run the command: cci task run extract_dataset --org dev

Congratulations, you captured your first dataset! It’s time to add a new task to the flows for QA and Dev scratch orgs. So far, we’ve used the dev_org flow to create development orgs; shortly, we’ll use the qa_org flow to build orgs for quality assurance and testing.

Add a New Task to the QA Org Flow

CumulusCI will write test data to the default dataset file, called datasets/sample.sql, using the mapping file to identify which objects and fields to capture. If you wish, navigate to the sample.sql file in the Side Bar pane in VS Code. You should be able to see, even if you don’t know SQL, that CumulusCI has captured the data you added.

Here’s how to modify the dev_org and qa_org flows in your cumulusci.yml file.

1. Review the flows as they are now to determine where you want to add this task. See all of the flows and tasks included in the qa_org flow; type this command: cci flow info qa_org
2. Loading the data is something that should happen at the end of the configuration tasks. Therefore, focus in on the config flow—where the new task will reside—by typing this command: cci flow info config_qa

This command shows you two config tasks already exist, one for finishing up any post-installation tasks and another to make sure the Administrator profile is updated to take advantage of any post-installation configurations. You want to add your new task after the first two tasks because loading sample data is the last thing you want to do after getting an org ready. Add these new steps directly in your project’s cumulusci.yml configuration 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. Open the cumulusci.yml file in the Editor in the VS Code Side Bar. Add a new line at the end of the file and make sure it’s not indented.
2. Add the following customizations:

flows:
    config_qa:
        steps:
            3:
                task: load_dataset
    config_dev:
        steps:
            3:
                task: load_dataset

Press Command+s (macOS) or Ctrl+s (Windows) to save your changes to the cumulusci.yml file.

Make sure the listings include your modifications to config_qa and config_dev: 

1. In VS Code Terminal, type this command to check the QA org flow: cci flow info qa_org
2. Type this command to check the Dev org flow: cci flow info dev_org

In the config_dev and config_qa flows, you should now see load_dataset as the third task in each flow.

Now the tasks have been added, take your demo data for a test drive in a fresh QA scratch org. 

Test Your Demo Data in a QA Scratch Org

1. Run the qa_org flow to create a scratch org: cci flow run qa_org --org qa
2. When the org finishes building, open it in your web browser to make sure the changes are included in your new scratch org. In VS Code Terminal, type this command: cci org browser qa

If you’re able to see your sample data, publish the changes to GitHub:

1. In GitHub Desktop, on the feature/demo-data feature branch, make a commit with the summary Add demo dataset. Click Commit to feature/demo-data.
2. Publish the feature branch to GitHub by clicking Publish branch on the information pane that comes up after your commit is complete.
3. When the information pane updates after publishing, click Create Pull Request to create a new Pull Request for this change.
4. GitHub Desktop will automatically navigate you to the Open a pull request screen in your web browser.
5. Under the header Changes, add a line to describe what you did: Add demo dataset.
6. Click Create Pull Request.
7. On the next screen, click Merge pull request. Click Confirm merge.
8. Click Delete branch to remove the branch we just merged.
9. Return to GitHub Desktop.
10. Verify that Current Branch is feature/demo-data
11. In the GitHub Desktop menubar, select Branch→Delete and confirm that you want to delete the branch feature/demo-data
12. GitHub Desktop automatically takes you back to the master branch as your Current Branch.
13. Select Repository→Pull from the menu to bring down the changes you merged from feature/demo-data on GitHub. Your repository will refresh.

Great work! You’ve added data to help bring your application to life and tell its story throughout the development lifecycle. Remember to clean up your scratch orgs before you leave.

1. In the GitHub Desktop menubar, choose Repository→Open in Visual Studio Code to open VS Code’s Terminal window, and delete your scratch orgs.
2. To remove your dev scratch org, type this command: cci org scratch_delete dev
3. Remove the second scratch org with this command: cci org scratch_delete qa

Summing It Up: Data Management with CumulusCI

Creating datasets that tell the story of the application helps Tasha and her colleagues at every stage of their process as they collaborate to make the best food bank package possible. By customizing their CumulusCI flows to add data into every org they create, they ensure that developers, testers, potential users, and other stakeholders always have a fully-rounded, immersive experience of the application. Data make the org sundae one to remember. 

Resources

• Website: CumulusCI Help, Automating Data Operations
• Get Help: CumulusCI group on the Trailblazer Community