Add Demonstration Data to Your Org
- 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.
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.
- Create a new feature branch to store the changes. In GitHub Desktop, choose Current Branch→New Branch, and name the branch
- Create a dev org to work in. Open VS Code (via Repository→Open in Visual Studio Code in GitHub Desktop).
- Create a new terminal in VS Code (Terminal→New Terminal).
- In the new terminal, enter the following command:
cci flow run dev_org --org dev
- 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
- If you’d like, review the
mapping.ymlfile 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.
- 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.
- Open the dev org in a browser to start creating data with this command:
cci org browser dev
- 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.
- 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.
- 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.
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
qa_org flows in your
- 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_orgflow; type this command:
cci flow info qa_org
- 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:
- Open the
cumulusci.ymlfile 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.
- 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
Make sure the listings include your modifications to
- In VS Code Terminal, type this command to check the QA org flow:
cci flow info qa_org
- Type this command to check the Dev org flow:
cci flow info dev_org
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.
- Run the
qa_orgflow to create a scratch org:
cci flow run qa_org --org qa
- 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:
- In GitHub Desktop, on the
feature/demo-datafeature branch, make a commit with the summary
Add demo dataset. Click Commit to feature/demo-data.
- Publish the feature branch to GitHub by clicking Publish branch on the information pane that comes up after your commit is complete.
- When the information pane updates after publishing, click Create Pull Request to create a new Pull Request for this change.
- GitHub Desktop will automatically navigate you to the Open a pull request screen in your web browser.
- Under the header Changes, add a line to describe what you did:
Add demo dataset.
- Click Create Pull Request.
- On the next screen, click Merge pull request. Click Confirm merge.
- Click Delete branch to remove the branch we just merged.
- Return to GitHub Desktop.
- Verify that Current Branch is feature/demo-data
- In the GitHub Desktop menubar, select Branch→Delete and confirm that you want to delete the branch feature/demo-data
- GitHub Desktop automatically takes you back to the master branch as your Current Branch.
- Select Repository→Pull from the menu to bring down the changes you merged from feature/demo-data on GitHub. Your registry 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.
- In the GitHub Desktop menubar, choose Repository→Open in Visual Studio Code to open VS Code’s Terminal window, and delete your scratch orgs.
- To remove your dev scratch org, type this command:
cci org scratch_delete dev
- Remove the second scratch org with this command:
cci org scratch_delete qa
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.