CumulusCI’s Metadata Transformations

Today’s post covers one of the most powerful and underutilized features of CumulusCI: Metadata Transformations. CumulusCI contains a set of tasks designed to manipulate existing metadata in an org to handle situations where deploying static metadata risks overwriting customizations in the org.

I think of these transformations as Metadata ETL, or Extract/Transform/Load. In the metadata context, this means retrieving metadata from the org (extract), transforming it locally, then deploying it back (load).

Consider the example of an ISV who wants to create automation to ensure a required standard value set entry exists in the target org. Since they don’t know what standard value set entries are currently in the org, simply deploying the field’s static metadata risks removing custom value set entries created by the org’s admin. The ISV doesn’t care about all the value set entries, just that the one their product requires is there.

Doing this safely without a Metadata Transformation is really only possible through documentation and manual admin intervention. That’s both cumbersome for your users and introduces risk of human error.

CumulusCI’s add_value_set_entries task to the rescue! With the following added to your project’s cumulusci.yml file, you can automate adding a value set entry if one doesn’t already exist, ensuring the target org meets the dependencies of the ISV product without risking the removal of other value set entries.

With this custom task defined, it can be run with the command cci task run ensure_quote_status_values. More importantly, this is portable automation that can be used throughout Cumulus Suite tools such as MetaDeploy to create a customer facing installer that handles the complexity of settting up dependencies, installing a package, and configuring the package to make a product.

Metadata Transformation Tasks

You can get a list of all Metadata Transformation tasks by running cci task list and looking at the Metadata Transformations section of the output.

• activate_flow: Activates Flows identified by a given list of Developer Names
• add_fields_to_field_set: Adds specified fields to a given field set.
• add_page_layout_fields: Adds specified Fields or Visualforce Pages to a Page Layout.
• add_page_layout_related_lists: Adds specified Related List to one or more Page Layouts.
• add_permission_set_perms: Adds specified Apex class access and Field-Level Security to a Permission Set.
• add_picklist_entries: Adds specified picklist entries to a custom picklist field.
• add_profile_ip_ranges: Adds (or optionally replaces) IP Login Ranges to the specified Profiles.
• add_record_action_list_item: Adds the specified ‘Record’ context Lightning button/action to the provided page layout.
• add_remote_site_settings: Adds the specified RemoteSiteSettings records to an org.
• add_standard_value_set_entries: Adds specified picklist entries to a Standard Value Set.
• assign_compact_layout: Assigns the Compact Layout specified in the ‘value’ option to the Custom Objects in ‘api_names’ option. create_permission_set Creates a Permission Set with specified User Permissions and assigns it to the running user.
• set_duplicate_rule_status: Sets the active status of Duplicate Rules.
• set_field_help_text: Sets specified fields’ Help Text values.
• set_organization_wide_defaults: Sets the Organization-Wide Defaults for specific sObjects, and waits for sharing recalculation to complete. update_metadata_first_child_text Updates the text of the first child of Metadata with matching tag. Adds a child for tag if it does not exist.

Custom Metadata Transformation Tasks

CumulusCI contains a set of base Python classes for writing your own Metadata Transformations. Writing custom task classes is a bit beyond the scope of this post, but check out the CumulusCI’s Task Framework article for more background.

To illustrate the power of CumulusCI’s base classses for Metadata Transformations, check out the entire source code implementation for the set_duplicate_rule_status task:

Conclusion

Metadata Transformations offer a powerful option for ISVs to deliver complete products instead of just packages. For more background on why you would want to do that, check out the post A Product is More Than a Package

If you’re an ISV or work in environments that require breaking out of the change set model of sandbox -> production to a model of source -> many different orgs, Metadata Transformations are worth understanding.

Want to learn more or discuss? Grab some time to chat at https://calendly.com/muselab

Resources

• CumulusCI’s Metadata ETL Documentation