CumulusCI Documentation

CumulusCI provides tools to manage data as part of project automation. You can define datasets (collections of data) within your repository to automate extracting data from orgs, storing snapshots in version control, and loading that data into other orgs.

Data operations are executed using the Bulk and REST APIs. CumulusCI offers two levels of data management:

1. High-level Sample Datasets: Easy-to-use tasks for managing primary sample datasets used in scratch org configuration flows.
2. Low-level Datasets: Generic Extract, Transform, and Load (ETL) tasks for any data.

The cci command is the primary entrypoint for interacting with CumulusCI. After installation, you can use it in any terminal (VS Code integrated terminal, macOS Terminal.app, Windows cmd.exe, or Linux terminals) to manage tasks, flows, plans, orgs, and services.

To see all available top-level commands, run cci.

CumulusCI Flow is a branching strategy designed for agile Salesforce releases. It relies on automated merging to reduce merge conflicts and ensure continuous integration across complex branch hierarchies.

Key components include:

• Main Branch: The source of truth for production.
• Feature Branches (feature/*): Isolated branches for development. They receive automatic updates from main.
• Parent/Child Hierarchy: Uses __ to denote relationships, allowing large features to be broken down into sub-tasks while maintaining a single integration point (the Parent).
• Release Branches: Long-lived branches for specific releases that can automatically propagate changes to future release branches.

CumulusCI supports continuous integration via GitHub Actions. To use this functionality, your repository must already be a configured CumulusCI project containing a cumulusci.yml file and working locally.

You can implement CI using two main approaches:

1. Reusable Workflows: High-level, pre-defined pipelines (e.g., for 1GP or 2GP projects) that handle dependencies between jobs automatically.
2. Job-Based Actions: Granular building blocks that allow you to construct custom workflows by specifying individual CumulusCI flows or tasks.

In CumulusCI, an org is a named configuration in the keychain tailored for a specific purpose (e.g., dev, qa, beta).

CumulusCI uses these configurations to generate scratch orgs on demand. A scratch org is only physically created the first time you attempt to use a configuration. If a scratch org expires or is deleted, the configuration remains in the keychain and can be used to recreate a new org immediately.

Metadata ETL (Extract, Transform, and Load) is a suite of functionality in CumulusCI used to automate targeted transformations of metadata already existing in an org.

Instead of storing and deploying static unpackaged metadata (which can become out-of-sync or cause destructive overwrites), Metadata ETL allows you to:

1. Extract existing metadata from the target org.
2. Transform it to include desired changes while preserving existing customizations.
3. Load the modified metadata back into the org.

Key Use Case: Standard Value Sets Standard Value Sets (e.g., Opportunity.StageName) are not packageable and deploying them as static files is dangerous because it is an overwrite operation that deactivates existing values. Using Metadata ETL ensures you only add or modify specific entries without wiping out existing ones.

In 2GP packaging, there is no packaging org to host unpackaged metadata (e.g., files in unpackaged/pre or unpackaged/post). CumulusCI provides two modes for handling this:

1. Default (Ignore): Unpackaged metadata is ignored. Dependencies must be satisfied via other means, such as scratch org configuration.
2. Automatic Unlocked Package Creation: CumulusCI can automatically create and upload unlocked packages containing the unpackaged metadata from dependency projects. This is useful for testing complex legacy projects but is not recommended for production because it requires distributing those extra unlocked packages alongside your main package.

To enable this behavior, set create_unlocked_dependency_packages: true on the create_package_version task in your cumulusci.yml.

While most CumulusCI Actions can run in parallel because they use independent scratch orgs, First-generation package uploads should be serialized to avoid conflicts with the packaging org.

To ensure serialization in GitHub Actions, set the concurrency key to packaging at the job level. This is independent of your environment configuration.

jobs:
  upload:
    concurrency: packaging
    # ... rest of job

If you attempt to use a page object keyword for a page that hasn't been explicitly defined in your code, the PageObjects library will attempt to use a generic implementation.

Common generic types include:

• Detail: Matches URLs like <host>/lightning/r/<object_name>/<object_id>/view.
• Home: Matches URLs like <host>/lightning/o/<object_name>/home.
• Listing: Matches URLs like <host>/lightning/o/<object_name>/list.
• New: Refers to the "New Object" modal.

Example of using generic objects:

*** Test Cases ***
Example test which uses generic page objects
    ## Go to the custom object home page, which should
    ## redirect to the listing page
    Go To Page  Home  Island__c

    ## Verify that the redirect happened
    Current Page Should Be  Listing  Island__c

Low-level datasets are used for generic ETL operations and consist of two main components:

1. Definition File: A YAML file specifying the sObjects, fields, and the order for extraction or loading.
2. Storage Location: Typically a SQL database (like a SQLite file in the repository) or a SQL script file.

Dataset Resolution Logic:

• By default, datasets are stored in the datasets/ folder.
• When load_dataset is called without path options, it looks for a dataset matching the org shape. For a dev org, it looks for datasets/dev/dev.mapping.yml and datasets/dev/dev.dataset.sql.
• If no matching directory is found, it falls back to datasets/mapping.yml and datasets/dataset.sql.
• If the default_dataset_only option is set to True, the task ignores path options and defaults, looking only for a dataset directory that matches the org shape name.