cumulusci-plus 5.0.0__py3-none-any.whl

cumulusci/tasks/metadata_etl/permissions.py

@@ -0,0 +1,167 @@
+import typing as T
+
+import pydantic
+
+from cumulusci.core.exceptions import TaskOptionsError
+from cumulusci.tasks.metadata_etl import MetadataSingleEntityTransformTask
+from cumulusci.utils.xml.metadata_tree import MetadataElement
+
+
+class IPRange(pydantic.BaseModel):
+    description: T.Optional[str]
+    start_address: pydantic.IPvAnyAddress
+    end_address: pydantic.IPvAnyAddress
+
+
+class IPNetwork(pydantic.BaseModel):
+    description: T.Optional[str]
+    network: pydantic.IPvAnyNetwork
+
+
+class AddIPRangesOptions(pydantic.BaseModel):
+    ranges: T.List[T.Union[IPRange, IPNetwork]]
+    replace: bool = False
+
+
+class AddIPRanges(MetadataSingleEntityTransformTask):
+    entity = "Profile"
+    task_options = {
+        "ranges": {
+            "description": "A list of IP ranges, specified as dicts with the keys 'description' (optional) and either 'start_address' and 'end_address' or 'network' (in CIDR notation).",
+            "required": True,
+        },
+        "replace": {
+            "description": "If True, replace all existing ranges. Otherwise, just add ranges. Default is False."
+        },
+    }
+
+    def _transform_entity(
+        self, metadata: MetadataElement, api_name: str
+    ) -> MetadataElement:
+        try:
+            opts = AddIPRangesOptions.parse_obj(self.options)
+        except pydantic.ValidationError as exc:
+            raise TaskOptionsError(f"Invalid options: {exc}")
+
+        if opts.replace:
+            # Remove existing ranges
+            for elem in metadata.findall("loginIpRanges"):
+                metadata.remove(elem)
+
+        for ip_range in opts.ranges:
+            if isinstance(ip_range, IPNetwork):
+                elem = metadata.append("loginIpRanges")
+                elem.append("description", text=ip_range.description or "")
+                elem.append(
+                    "startAddress", text=str(ip_range.network.network_address + 1)
+                )
+                elem.append(
+                    "endAddress", text=str(ip_range.network.broadcast_address - 1)
+                )
+            else:
+                elem = metadata.append("loginIpRanges")
+                elem.append("description", text=ip_range.description or "")
+                elem.append("startAddress", text=str(ip_range.start_address))
+                elem.append("endAddress", text=str(ip_range.end_address))
+
+        return metadata
+
+
+class AddPermissionSetPermissions(MetadataSingleEntityTransformTask):
+    entity = "PermissionSet"
+    task_options = {
+        "field_permissions": {
+            "description": "Array of fieldPermissions objects to upsert into permission_set.  Each fieldPermission requires the following attributes: 'field': API Name of the field including namespace; 'readable': boolean if field can be read; 'editable': boolean if field can be edited",
+            "required": False,
+        },
+        "class_accesses": {
+            "description": "Array of classAccesses objects to upsert into permission_set.  Each classAccess requires the following attributes: 'apexClass': Name of Apex Class.  If namespaced, make sure to use the form \"namespace__ApexClass\"; 'enabled': boolean if the Apex Class can be accessed.",
+            "required": False,
+        },
+        **MetadataSingleEntityTransformTask.task_options,
+    }
+
+    def _transform_entity(
+        self, metadata: MetadataElement, api_name: str
+    ) -> MetadataElement:
+        self._upsert_class_accesses(metadata, api_name)
+        self._upsert_field_permissions(metadata, api_name)
+        return metadata
+
+    def _upsert_class_accesses(self, metadata, api_name):
+        class_accesses = self.options.get("class_accesses")
+
+        if not class_accesses:
+            return
+
+        self.logger.info(f"Upserting class accesses for {api_name}")
+
+        for class_access in class_accesses:
+            if "apexClass" not in class_access:
+                raise TaskOptionsError(
+                    "class_access entries must contain the 'apexClass' key."
+                )
+
+            class_access["apexClass"] = self._inject_namespace(
+                class_access["apexClass"]
+            )
+
+            existing_permissions = metadata.findall(
+                "classAccesses", apexClass=class_access["apexClass"]
+            )
+
+            if len(existing_permissions):
+                # Permission exists: update
+                for elem in existing_permissions:
+                    elem.find("enabled").text = str(
+                        class_access.get("enabled", True)
+                    ).lower()
+            else:
+                # Permission doesn't exist: insert
+                elem = metadata.append("classAccesses")
+                elem.append("apexClass", text=class_access.get("apexClass"))
+                elem.append(
+                    "enabled", text=str(class_access.get("enabled", True)).lower()
+                )
+
+    def _upsert_field_permissions(self, metadata, api_name):
+        field_permissions = self.options.get("field_permissions")
+
+        if not field_permissions:
+            return
+
+        self.logger.info(f"Upserting Field Level Security for {api_name}")
+
+        for field_permission in field_permissions:
+            if "field" not in field_permission:
+                raise TaskOptionsError(
+                    "field_permissions entries must include the 'field' key."
+                )
+
+            field_permission["field"] = self._inject_namespace(
+                field_permission["field"]
+            )
+
+            existing_permissions = metadata.findall(
+                "fieldPermissions", field=field_permission["field"]
+            )
+
+            if len(existing_permissions):
+                # Permission exists: update
+                for elem in existing_permissions:
+                    elem.find("readable").text = str(
+                        field_permission.get("readable", True)
+                    ).lower()
+                    elem.find("editable").text = str(
+                        field_permission.get("editable", True)
+                    ).lower()
+            else:
+                # Permission doesn't exist: insert
+                element = metadata.append("fieldPermissions")
+                element.append("field", text=field_permission.get("field"))
+                element.append(
+                    "editable", text=str(field_permission.get("editable", True)).lower()
+                )
+                element.append(
+                    "readable", text=str(field_permission.get("readable", True)).lower()
+                )

cumulusci/tasks/metadata_etl/picklists.py

@@ -0,0 +1,221 @@
+from collections import defaultdict
+from typing import Dict
+from urllib.parse import unquote
+
+from cumulusci.core.exceptions import TaskOptionsError
+from cumulusci.core.utils import process_bool_arg, process_list_arg
+from cumulusci.tasks.metadata_etl import MetadataSingleEntityTransformTask
+from cumulusci.utils.xml.metadata_tree import MetadataElement
+
+
+class AddPicklistEntries(MetadataSingleEntityTransformTask):
+    entity = "CustomObject"
+    task_options = {
+        "picklists": {
+            "description": "List of picklists to affect, in Object__c.Field__c form.",
+            "required": True,
+        },
+        "entries": {
+            "description": "Array of picklist values to insert. "
+            "Each value should contain the keys 'fullName', the API name of the entry, "
+            "and 'label', the user-facing label. Optionally, specify `default: True` on exactly one "
+            "entry to make that value the default. Any existing values will not be affected other than "
+            "setting the default (labels of existing entries are not changed). "
+            "To order values, include the 'add_before' key. This will insert the new value "
+            "before the existing value with the given API name, or at the end of the list if not present.",
+            "required": True,
+        },
+        "record_types": {
+            "description": "List of Record Type developer names for which the new values "
+            "should be available. If any of the entries have `default: True`, they are also made "
+            "default for these Record Types. Any Record Types not present in the target org will be "
+            "ignored, and * is a wildcard. Default behavior is to do nothing."
+        },
+        **MetadataSingleEntityTransformTask.task_options,
+    }
+
+    def _init_options(self, kwargs):
+        self.task_config.options["api_names"] = "dummy"
+        super()._init_options(kwargs)
+
+        try:
+            if float(self.api_version) < 38.0:
+                raise TaskOptionsError("This task requires API version 38.0 or later.")
+        except ValueError:
+            raise TaskOptionsError(f"Invalid API version {self.api_version}")
+
+        if "picklists" not in self.options:
+            raise TaskOptionsError("The 'picklists' option is required.")
+
+        self.picklists = defaultdict(list)
+        for pl in process_list_arg(self.options["picklists"]):
+            try:
+                obj, field = pl.split(".")
+            except ValueError:
+                raise TaskOptionsError(
+                    f"Picklist {pl} is not a valid Object.Field reference"
+                )
+            if not field.endswith("__c"):
+                raise TaskOptionsError(
+                    "This task only supports custom fields. To modify "
+                    "Standard Value Sets, use the add_standard_value_set_entries task."
+                )
+
+            self.picklists[self._inject_namespace(obj)].append(
+                self._inject_namespace(field)
+            )
+
+        if not all(["fullName" in entry for entry in self.options["entries"]]):
+            raise TaskOptionsError(
+                "The 'fullName' key is required on all picklist values."
+            )
+
+        if (
+            sum(
+                1
+                for x in self.options["entries"]
+                if process_bool_arg(x.get("default", False))
+            )
+            > 1
+        ):
+            raise TaskOptionsError("Only one default picklist value is allowed.")
+
+        self.options["record_types"] = [
+            self._inject_namespace(x)
+            for x in process_list_arg(self.options.get("record_types", []))
+        ]
+
+        self.api_names = set(self.picklists.keys())
+
+    def _transform_entity(self, metadata: MetadataElement, api_name: str):
+        for pl in self.picklists[api_name]:
+            self._modify_picklist(metadata, api_name, pl)
+
+        return metadata
+
+    def _modify_picklist(self, metadata: MetadataElement, api_name: str, picklist: str):
+        # Locate the <fields> entry for this picklist.
+        field = metadata.find("fields", fullName=picklist)
+
+        if not field:
+            raise TaskOptionsError(f"The field {api_name}.{picklist} was not found.")
+
+        vsd = field.valueSet.find("valueSetDefinition")
+        if not vsd:
+            raise TaskOptionsError(
+                f"The picklist {api_name}.{picklist} uses a Global Value Set, which is not supported."
+            )
+
+        # Update each entry in this picklist, and also add to all record types.
+        for entry in self.options["entries"]:
+            self._add_picklist_field_entry(vsd, api_name, picklist, entry)
+
+            if self.options["record_types"]:
+                self._add_record_type_entries(metadata, api_name, picklist, entry)
+
+    def _add_picklist_field_entry(
+        self, vsd: MetadataElement, api_name: str, picklist: str, entry: Dict
+    ):
+        fullName = entry["fullName"]
+        label = entry.get("label") or fullName
+        default = entry.get("default", False)
+        add_before = entry.get("add_before")
+
+        if vsd.find("value", fullName=fullName):
+            self.logger.warning(
+                f"Picklist entry with fullName {fullName} already exists on picklist {picklist}."
+            )
+        else:
+            if add_before and vsd.find("value", fullName=add_before):
+                entry_element = vsd.insert_before(
+                    vsd.find("value", fullName=add_before), "value"
+                )
+            else:
+                entry_element = vsd.append("value")
+            entry_element.append("fullName", text=fullName)
+            entry_element.append("label", text=label)
+            entry_element.append("default", text=str(default).lower())
+
+        # If we're setting this as the default, unset all of the other entries.
+        if default:
+            for value in vsd.findall("value"):
+                default = value.find("default")
+                if default:
+                    default.text = (
+                        "false" if value.fullName.text != fullName else "true"
+                    )
+
+    def _add_record_type_entries(
+        self, metadata: MetadataElement, api_name: str, picklist: str, entry: Dict
+    ):
+        if "*" in self.options["record_types"]:
+            rt_list = metadata.findall("recordTypes")
+        else:
+            rt_list = [
+                metadata.find("recordTypes", fullName=record_type)
+                for record_type in self.options["record_types"]
+            ]
+
+        for rt_element in rt_list:
+            # Silently ignore record types that don't exist in the target org.
+            if rt_element:
+                self._add_single_record_type_entries(
+                    rt_element, api_name, picklist, entry
+                )
+
+    def _add_single_record_type_entries(
+        self, rt_element: MetadataElement, api_name: str, picklist: str, entry: Dict
+    ):
+        # Locate, or add, the root picklistValues element for this picklist.
+        picklist_element = rt_element.find(
+            "picklistValues", picklist=picklist
+        ) or rt_element.append("picklistValues")
+        if not picklist_element.find("picklist", text=picklist):
+            picklist_element.append("picklist", text=picklist)
+
+        # If this picklist value entry is not already present, add it.
+        default = str(process_bool_arg(entry.get("default", False))).lower
+        fullName = entry["fullName"]
+
+        # The Metadata API's behavior with picklist values in record types
+        # is to return partially URL-encoded values. Most punctuation appears
+        # to be escaped, but spaces and high-bit characters are not.
+        # To route around this, we compare the `unquote()`-ed
+        # value of each element, since we don't know in 100% of cases
+        # how to make our input look like what MDAPI returns.
+
+        # Note that this behavior is different from picklist values in value sets.
+        def find_matching_value(picklist, target):
+            return next(
+                filter(
+                    lambda x: unquote(x.fullName.text) == target,
+                    picklist.findall("values"),
+                ),
+                None,
+            )
+
+        values = find_matching_value(picklist_element, fullName)
+        if not values:
+            add_before = entry.get("add_before")
+            if add_before:
+                before_elem = find_matching_value(picklist_element, add_before)
+                if before_elem:
+                    values = picklist_element.insert_before(before_elem, "values")
+                else:
+                    values = picklist_element.append("values")
+            else:
+                values = picklist_element.append("values")
+
+            # The Metadata API does _not_ require us to perform its partial URL-encoding to deploy.
+            values.append("fullName", text=fullName)
+            values.append("default", text=str(default).lower())
+
+        # If this picklist value needs to be made default, remove any existing default.
+        if default:
+            # Find existing default and remove it, while setting our value as default
+            for value in picklist_element.values:
+                default = value.find("default")
+                if default:
+                    default.text = (
+                        "false" if value.fullName.text != fullName else "true"
+                    )

cumulusci/tasks/metadata_etl/remote_site_settings.py

@@ -0,0 +1,99 @@
+from typing import List, Optional
+
+import pydantic
+from pydantic import BaseModel
+
+from cumulusci.core.exceptions import TaskOptionsError
+from cumulusci.tasks.metadata_etl.base import BaseMetadataSynthesisTask
+
+REQUIRED_FIELD_ERR = "You must specify a value for RemoteSiteSetting.{} on all entries."
+RSS_DIR_NAME = "remoteSiteSettings"
+RSS_FILE_EXTENSION = "remoteSite"
+RSS_XML = """<?xml version="1.0" encoding="UTF-8"?>
+<RemoteSiteSetting xmlns="http://soap.sforce.com/2006/04/metadata">
+    <description>{description}</description>
+    <disableProtocolSecurity>{disable_protocol_security}</disableProtocolSecurity>
+    <isActive>{is_active}</isActive>
+    <url>{url}</url>
+</RemoteSiteSetting>"""
+
+
+class RemoteSiteSetting(BaseModel):
+    """Schema for the RemoteSiteSetting object"""
+
+    full_name: str
+    url: str
+    is_active: bool
+    description: Optional[str]
+    disable_protocol_security: Optional[bool]
+
+
+class RSSOptions(BaseModel):
+    """Defines the options for this task"""
+
+    records: List[RemoteSiteSetting]
+
+
+class AddRemoteSiteSettings(BaseMetadataSynthesisTask):
+    """Task for adding Remote Site Setting records to an org"""
+
+    entity = "RemoteSiteSetting"
+    task_docs = """
+
+        Example Usage
+        -----------------------
+
+        .. code-block::  yaml
+
+            task: add_remote_site_settings
+            options:
+                records:
+                    - full_name: ExampleRemoteSiteSetting
+                      description: Descriptions can be included optionally
+                      url: https://test.salesforce.com
+                      is_active: True
+
+    """
+    task_options = {
+        "records": {
+            "description": "Array of RemoteSiteSetting records to insert. "
+            "Each RemoteSiteSetting requires the keys: 'full_name', 'is_active', and 'url'. "
+            "'description' is optional, and defaults to an empty string. "
+            "'disable_security_protocol' is optional, and defaults to False.",
+            "required": True,
+        },
+    }
+
+    def _synthesize(self):
+        options: RSSOptions = self._get_options()
+        for rss in options.records:
+            content: str = self._get_rss_xml_content(rss)
+            filename: str = f"{rss.full_name}.{RSS_FILE_EXTENSION}"
+            self._create_rss_file(filename, content)
+        return
+
+    def _get_options(self) -> RSSOptions:
+        """Parse and return the options defined in RSSOptions"""
+        try:
+            return RSSOptions.parse_obj(self.options)
+        except pydantic.ValidationError as exc:
+            raise TaskOptionsError(f"Invalid options: {exc}")
+
+    def _get_rss_xml_content(self, rss: RemoteSiteSetting) -> str:
+        disable_protocol_security = rss.disable_protocol_security or False
+        is_active = rss.is_active or False
+        return RSS_XML.format(
+            url=rss.url,
+            is_active=is_active,
+            description=rss.description or "",
+            disable_protocol_security=disable_protocol_security,
+        )
+
+    def _create_rss_file(self, filename: str, content: str):
+        """Creates an xml file with given name and contents in self.deploy_dir/RemoteSiteSettings/"""
+        rss_dir = self.deploy_dir / RSS_DIR_NAME
+        rss_dir.mkdir(exist_ok=True)
+
+        filepath = rss_dir / filename
+        filepath.touch(exist_ok=False)
+        filepath.write_text(content, encoding="UTF-8")

cumulusci/tasks/metadata_etl/sharing.py

@@ -0,0 +1,138 @@
+from datetime import datetime
+
+from cumulusci.core.exceptions import CumulusCIException, TaskOptionsError
+from cumulusci.tasks.metadata_etl import MetadataSingleEntityTransformTask
+from cumulusci.tasks.salesforce import BaseSalesforceApiTask
+from cumulusci.utils.xml.metadata_tree import MetadataElement
+
+
+class SetOrgWideDefaults(MetadataSingleEntityTransformTask, BaseSalesforceApiTask):
+    entity = "CustomObject"
+    task_options = {
+        "org_wide_defaults": {
+            "description": "The target Organization-Wide Defaults, "
+            "organized as a list with each element containing the keys api_name, "
+            "internal_sharing_model, and external_sharing_model. This option must "
+            "be specified in YAML configuration and will not work if passed via the CLI. "
+            "NOTE: you must have External Sharing Model turned on in Sharing Settings to use the latter feature.",
+            "required": True,
+        },
+        "timeout": {
+            "description": "The max amount of time to wait in seconds",
+            "required": False,
+            "default": 600,
+        },
+        **MetadataSingleEntityTransformTask.task_options,
+    }
+
+    def _init_options(self, kwargs):
+        self.task_config.options["api_names"] = "dummy"
+        super()._init_options(kwargs)
+        self.api_names = {
+            self._inject_namespace(elem["api_name"])
+            for elem in self.options["org_wide_defaults"]
+        }
+        self.options["timeout"] = int(self.options.get("timeout", 600))
+
+        self.owds = {}
+        for elem in self.options["org_wide_defaults"]:
+            if "api_name" not in elem or (
+                "internal_sharing_model" not in elem
+                and "external_sharing_model" not in elem
+            ):
+                raise TaskOptionsError(
+                    "The object api_name and at least one of "
+                    "internal_sharing_model and external_sharing_model is required."
+                )
+
+            valid_sharing_models = [
+                "ControlledByParent",
+                "ControlledByCampaign",
+                "ControlledByLeadOrContact",
+                "FullAccess",
+                "ReadWriteTransfer",
+                "ReadWrite",
+                "Read",
+                "Private",
+                "ControlledByParent",
+                None,
+            ]
+            if (
+                elem.get("internal_sharing_model") not in valid_sharing_models
+                or elem.get("external_sharing_model") not in valid_sharing_models
+            ):
+                raise TaskOptionsError(
+                    f"The sharing model specified for {elem['api_name']} is not a valid option."
+                )
+
+            self.owds[self._inject_namespace(elem["api_name"])] = {
+                "internal_sharing_model": elem.get("internal_sharing_model"),
+                "external_sharing_model": elem.get("external_sharing_model"),
+            }
+
+    def _post_deploy(self, result):
+        if result == "Success":
+            super()._post_deploy(result)
+            self.logger.info("Waiting for sharing enablement to complete.")
+            self.time_start = datetime.now()
+            self._poll()
+            self.logger.info("Sharing enablement is complete.")
+
+    def _transform_entity(
+        self, metadata: MetadataElement, api_name: str
+    ) -> MetadataElement:
+        desired_internal_model = self.owds[api_name].get("internal_sharing_model")
+        desired_external_model = self.owds[api_name].get("external_sharing_model")
+
+        if desired_external_model:
+            external_model = metadata.find("externalSharingModel")
+            if not external_model:
+                external_model = metadata.append("externalSharingModel")
+            external_model.text = desired_external_model
+
+        if desired_internal_model:
+            internal_model = metadata.find("sharingModel")
+            if not internal_model:
+                internal_model = metadata.append("sharingModel")
+            internal_model.text = desired_internal_model
+
+        return metadata
+
+    def _poll_action(self):
+        elapsed = datetime.now() - self.time_start
+        if elapsed.total_seconds() > self.options["timeout"]:
+            raise CumulusCIException(
+                f'Sharing enablement not completed after {self.options["timeout"]} seconds'
+            )
+
+        for sobject in self.owds:
+            # The Tooling API requires that we use fully-qualified sObject names in namespaced scratch orgs.
+            # However, the Metadata API requires no namespaces in that context.
+            # Dynamically inject the namespace if required.
+            real_api_name = (
+                f"{self.project_config.project__package__namespace}__{sobject}"
+                if self.org_config.namespaced and sobject.count("__") == 1
+                else sobject
+            )
+
+            result = self.sf.query(
+                f"SELECT ExternalSharingModel, InternalSharingModel "
+                f"FROM EntityDefinition "
+                f"WHERE QualifiedApiName = '{real_api_name}'"
+            )
+            if result["totalSize"] == 1:
+                record = result["records"][0]
+                if (
+                    self.owds[sobject]["internal_sharing_model"]
+                    and record["InternalSharingModel"]
+                    != self.owds[sobject]["internal_sharing_model"]
+                ) or (
+                    self.owds[sobject]["external_sharing_model"]
+                    and record["ExternalSharingModel"]
+                    != self.owds[sobject]["external_sharing_model"]
+                ):
+                    return
+            else:
+                raise CumulusCIException("Unable to determine sharing model")
+
+        self.poll_complete = True