Learn About Tasks and Flows to Customize CumulusCI
Learning Objectives
- Utilize CumulusCI tasks and flows.
- Explain how to change built-in flows.
- Describe the benefits of CumulusCI tasks and flows.
Before Tasha can start adding data to her scratch orgs, she gets hands-on with the tools CumulusCI uses to run her automation and create her scratch orgs: flows and tasks.
An Introduction to Tasks and Flows
In CumulusCI, a task is a single, discrete job that can be run in a Salesforce org or a CumulusCI project. A task might push metadata, insert data, update settings, assign a permission set, create a package release, or many other operations. CumulusCI comes with a huge library of tasks to perform common operations.
A flow is an ordered sequence of tasks. In CumulusCI, flows combine a series of tasks to accomplish something that might take a lot of effort—like setting up an org. dev_org is a flow Tasha’s already familiar with.
CumulusCI Flows are not related to the automation functionality of Lightning Flow—although CumulusCI can deploy Lightning Flows to your orgs!
What makes CumulusCI so powerful and flexible is that Tasha and her colleagues can define new tasks and flows, and modify existing ones, by editing a simple text file: cumulusci.yml, which lives in her project’s repository.
The cumulusci.yml file defines the configuration of CumulusCI in any project. It’s a set of nested, indented sections for components used to get a scratch org up and ready to use and explore. Let’s take a tour of Tasha’s cumulusci.yml file to learn more about how this works.
A Deeper Dive on Tasks
The flows and tasks in this unit are for demonstration purposes. Do not update your cumulusci.yml file with these examples. You'll modify your cumulusci.yml file in the next unit.
First, let’s look at the tasks portion of her file. In CumulusCI, every task has a name, and comes with a set of options. CumulusCI comes with a large set of tasks that projects use to define their flows, and each project can have its own tasks and options.
When Tasha looks at her cumulusci.yml file, her tasks section starts with something like this:
tasks: robot: options: suites: robot/Food-Bank/tests options: outputdir: robot/Food-Bank/results
CumulusCI builds this simple customization for each project: the built-in robot task will run a very simple browser automation test, and it’s customized with a path that applies to this project. If Tasha needs to change the options for other tasks in her project, she’ll work with entries like this. And someday, she might even create new tasks to define more ways to automate her project’s work!
CumulusCI comes with lots of tasks that are used to build flows. Tasha doesn’t see them all listed here—the tasks portion of her cumulusci.yml file is for her customizations—but she can find a list of every task available by running the command cci task list.
In the long list of tasks available to her project, Tasha notices a set of tasks under the heading “Data Operations”: extract_dataset, load_dataset, and generate_dataset_mapping. That sounds like just what she needs to add data to her application! But before she starts building her dataset, she needs to explore how to add new tasks to the flows she uses to create Salesforce orgs.
A Deeper Dive on CumulusCI Flows
Like tasks, CumulusCI comes with a wide variety of flows that are sequences of tasks (and other flows) that build a Salesforce org in a particular way. In other words, the flow is the recipe that builds the org sundae. Also like tasks, flows can be modified to suit the needs of the project. Tasha can add tasks, remove tasks, or change the tasks that are already there.
Tasha’s cumulusci.yml doesn’t have any flows in it yet, because Tasha and her team haven’t customized their project’s flows so far. Tasha’s already worked with the dev_org flow in some of her earlier CumulusCI work, and she knows she wants to change the “recipe” of that flow to add the dataset she’s going to build.
Tasha starts investigating how the dev_org flow works by typing the cci flow info dev_org command. This command shows her a list of all the tasks and other flows that make up the dev_org flow. Tasha zeros in on one called config_dev. This flow configures a scratch org for development use.
Tasha would like to add the task load_dataset to config_dev and needs to see where her task will fit in with the order of operations. To look at the steps included in the specific CumulusCI flow she’d like to customize, Tasha uses the cci flow info config_dev command to see the steps in the config_dev flow. This is what she sees:
Description: Configure an org for use as a dev org after package metadata is deployed 1) task: deploy_post [from current folder] 2) task: update_admin_profile
The config_dev flow starts with two steps. The first is deploy_post, that deploys any unpackaged metadata found in the unpackaged/post directory (Tasha doesn’t have any in her project yet). The second step is update_admin_profile, and that automatically grants the System Administrator profile access to all of the project’s objects and fields.
Tasha customizes the config_dev flow in her project by adding a third step for her load_dataset task. Adding this step under config_dev in the flows section of cumulusci.yml tells CumulusCI, "run the load_dataset task after doing the first two tasks every time config_dev is used to build a scratch org." Here’s what this looks like in the cumulusci.yml file:
flows: config_dev: steps: 3: task: load_dataset
The indentation within the code is important.
Because cumulusci.yml is part of the project’s repository, changes that Tasha makes are committed to Git and her feature branches. Reviewers can test her changes, and once merged to master, the new step becomes part of the project’s automation for everyone to use.
Summing It Up: The Value of Tasks and Flows
Customizing flows by composing other flows and tasks is an incredibly powerful way for Tasha and her team to tailor CumulusCI automation to the specific needs of their project. By customizing the built-in config_dev and config_qa flows, Tasha can make sure all of the development and QA orgs that are built for the Food Bank project not only include all of her metadata, but also perform additional setup steps—like loading the dataset she needs to ensure her scratch orgs tell the story of the application. Customizing saves time for Tasha’s team members, eliminating manual steps and chances of setup errors, and ensuring that every scratch org the team builds is ready to use as soon as they log in.