Configure Metadata Deployment¶

CumulusCI’s deploy task uses the Metadata API to deploy metadata from the repository to a Salesforce org. deploy offers multiple sophisticated capabilities to suit the needs of your project.

Specifying the Deploying Package and Test Run Levels¶

Use the path option to specify the path to the metadata you wish to deploy. The metadata may be in either Metadata API or Salesforce DX source format. SFDX-format source will automatically be converted to Metadata API for deployment. This conversion takes place prior to application of transforms (below) and requires that the path be listed as a package directory in sfdx-project.json.

Set the test run level with the test_level option. Available values are NoTestRun, RunLocalTests, RunAllTestsInOrg, and RunSpecifiedTests. If you use RunSpecifiedTests, you must also supply a list of tests with the specified_tests option. This option accept a comma-separated value at the command line or a list in your cumulusci.yml markup.

Source Transforms¶

deploy allows you to specify transforms that run against your metadata before it is delivered to the Salesforce platform. Some of these transforms are built-in, and others you can specify in your cumulusci.yml to suit your project’s specific needs.

Specifying Transforms¶

Four of the deploy transformations are built-in, and controlled by task options (see below). Others, including the flexible find_replace transform, are specified by your customization in cumulusci.yml.

You can specify transforms to run everywhere deploy is invoked by using customization in your tasks section:

tasks:
    deploy:
        options:
            transforms:
                - transform: find_replace
                  options:
                      patterns:
                          - find: foo
                            replace: bar

You can also add a transform for just a specific flow step:

flows:
    my_flow:
        steps:
            1:
                task: deploy
                options:
                    transforms:
                        - transform: find_replace
                          options:
                              patterns:
                                  - find: foo
                                    replace: bar

or override the options in an out-of-the-box flow:

flows:
    deploy_packaging:
        options:
            deploy:
                transforms:
                    - transform: find_replace
                      options:
                          patterns:
                              - find: foo
                                replace: bar

To learn more about customization, see Configure CumulusCI. To discover the available transform options, consult the section for each transform in Configure Metadata Deployment.

Namespace Injection¶

The deploy task, like many others in CumulusCI, supports namespace injection. This strategy allows you to flexibly inject your package’s namespace into (or remove it from) your metadata to suit various deployment contexts. See Namespace Injection for more information about namespace injection.

In most cases, you don’t need to customize deploy options for namespace injection, as the task will automatically infer the appropriate strategy. If you do find an edge case where inference does not suit your needs, you can configure namespace injection using the following options.

namespace_inject: set to specify the namespace to inject against tokens.
namespace_strip: set to specify the namespace prefix to remove.
unmanaged: set to True to replace namespace tokens with the empty string.
namespaced_org: set to True to replace the special NAMESPACED_ORG tokens with the namespace. Note that the packaging org is considered a namespaced-org context.

Meta-XML Cleaning¶

deploy can automatically remove references (<packageVersions/> elements) to the versions of other managed packages from *-meta.xml files in your metadata. This cleaning is controlled by the clean_meta_xml option, which defaults to True.

Static Resource Bundling¶

For products that are in Metadata API source format, deploy, can automatically Static Resource content that is stored uncompressed in an alternate directory into the ZIP files expected by the platform. To use this capability, set the option static_resource_path to the path where you store unzipped Static Resource content. CumulusCI will ZIP each subdirectory and place the archives in the staticresources directory in the deployment bundle. You must include required -meta.xml files in the static_resource_path.

Feature-Parameter Cleaning for Unlocked Packages¶

Unlocked Packages do not support Feature Parameter metadata. When CumulusCI is building an Unlocked Package, this transform will automatically remove Feature Parameter metadata from the deployment bundle.

Find-and-Replace Variable Injection¶

CumulusCI allows you to specify arbitrary injections of data against tokens you define in your metadata. This capability is often used, for example, to inject secure keys or tokens from environment variables.

Configure injection with the find_replace transform in two ways - find and xpath.

Using the find parameter, it modifies the metadata for each occurrence of its value by utilizing the supplied replace parameter. For XML files, this adjustment exclusively affects the values within the XML elements, leaving the tags unchanged.
Using the xpath parameter, it exclusively modifies the content of the XML files within the specific element indicated by the provided xpath, replacing it with the specified replace parameter.

Note: The Find-and-Replace Injection only supports one of the two parameters find or xpath.

Injection with find parameter:

task: deploy
options:
    transforms:
        - transform: find_replace
          options:
              patterns:
                  - find: foo
                    replace: bar

Injection with xpath parameter:

task: deploy
options:
    transforms:
        - transform: find_replace
          options:
              patterns:
                  - xpath: /path/to/element
                    replace: bar

The xpath also supports the use of predicates such as - xpath: /path[1]/to/element[text()="some_text"]

To use an environment variable as the source of the value to replace, use the replace_env key. Note that it’s valid to use multiple runs of find_replace; they will be applied in sequence.

task: deploy
options:
    transforms:
        - transform: find_replace
          options:
              patterns:
                  - find: AUTH_TOKEN
                    replace_env: SECURE_ACCESS_KEY
                  - xpath: /path/to/AUTH_TOKEN
                    replace_env: SECURE_ACCESS_KEY

Find-and-Replace Id Injection¶

Some metadata components contain ID references. CumulusCI offers a way to insert the ID of an existing record from the target org directly into such components during a deployment. Specify a SOQL query with the replace_record_id_query option as follows:

Injection with find parameter:

task: deploy
options:
    transforms:
        - transform: find_replace
          options:
              patterns:
                  - find: special_string
                    replace_record_id_query: SELECT Id from Account WHERE name='Specific Account'
                    api: rest

Injection with xpath parameter:

task: deploy
options:
    transforms:
        - transform: find_replace
          options:
              patterns:
                  - xpath: /path/to/element
                    replace_record_id_query: SELECT Id from Account WHERE name='Specific Account'
                    api: rest

Available values for api include rest and tooling.

Find-and-Replace Current Username Injection¶

CumulusCI can replace a given token with the username of the current running user in the target Salesforce org. All that is needed is to specify a value for find or xpath and set inject_username: True:

Injection with find parameter:

task: deploy
options:
    transforms:
        - transform: find_replace
          options:
              patterns:
                  - find: special_string
                    inject_username: True

Injection with xpath parameter:

task: deploy
options:
    transforms:
        - transform: find_replace
          options:
              patterns:
                  - xpath: /path/to/element
                    inject_username: True

Find-and-Replace Org URL Injection¶

CumulusCI can replace a given token with the org URL of the target Salesforce org. All that is needed is to specify a value for find or xpath and set inject_org_url: True:

Injection with find parameter:

task: deploy
options:
    transforms:
        - transform: find_replace
          options:
              patterns:
                  - find: special_string
                    inject_org_url: True

Injection with xpath parameter:

task: deploy
options:
    transforms:
        - transform: find_replace
          options:
              patterns:
                  - xpath: /path/to/element
                    inject_org_url: True

Stripping Components with a `package.xml` Manifest¶

This transformation allows you to deploy a subset of a metadata directory based on a package.xml manifest by removing unwanted components. It will compare components available in the source folder with a provided package.xml file and delete/modify component files which are not found.

task: deploy
options:
    transforms:
        - transform: strip_unwanted_components
          options:
              package_xml: PACKAGE_XML_FILE_PATH

Configure Metadata Deployment¶

Specifying the Deploying Package and Test Run Levels¶

Source Transforms¶

Specifying Transforms¶

Namespace Injection¶

Meta-XML Cleaning¶

Static Resource Bundling¶

Feature-Parameter Cleaning for Unlocked Packages¶

Find-and-Replace Variable Injection¶

Find-and-Replace Id Injection¶

Find-and-Replace Current Username Injection¶

Find-and-Replace Org URL Injection¶

Stripping Components with a package.xml Manifest¶

Stripping Components with a `package.xml` Manifest¶