cumulusci-plus 5.0.0__py3-none-any.whl

cumulusci/tasks/apex/anon.py

@@ -0,0 +1,157 @@
+from cumulusci.core.exceptions import (
+    ApexCompilationException,
+    ApexException,
+    SalesforceException,
+    TaskOptionsError,
+)
+from cumulusci.core.utils import process_bool_arg, determine_managed_mode
+from cumulusci.tasks.salesforce import BaseSalesforceApiTask
+from cumulusci.utils import in_directory, inject_namespace
+from cumulusci.utils.http.requests_utils import safe_json_from_response
+
+
+class AnonymousApexTask(BaseSalesforceApiTask):
+    """Executes anonymous apex from a file or string."""
+
+    task_docs = """
+    Use the `apex` option to run a string of anonymous Apex.
+    Use the `path` option to run anonymous Apex from a file.
+    Or use both to concatenate the string to the file contents.
+    """
+
+    task_options = {
+        "path": {"description": "The path to an Apex file to run.", "required": False},
+        "apex": {
+            "description": "A string of Apex to run (after the file, if specified).",
+            "required": False,
+        },
+        "managed": {
+            "description": (
+                "If True, will insert the project's namespace prefix.  "
+                "Defaults to False or no namespace."
+            ),
+            "required": False,
+        },
+        "namespaced": {
+            "description": (
+                "If True, the tokens %%%NAMESPACED_RT%%% and %%%namespaced%%% "
+                "will get replaced with the namespace prefix for Record Types."
+            ),
+            "required": False,
+        },
+        "param1": {
+            "description": (
+                "Parameter to pass to the Apex. Use as %%%PARAM_1%%% in the Apex code. "
+                "Defaults to an empty value."
+            ),
+            "required": False,
+        },
+        "param2": {
+            "description": (
+                "Parameter to pass to the Apex. Use as %%%PARAM_2%%% in the Apex code. "
+                "Defaults to an empty value."
+            ),
+            "required": False,
+        },
+    }
+
+    def _validate_options(self):
+        super()._validate_options()
+
+        if not self.options.get("path") and not self.options.get("apex"):
+            raise TaskOptionsError(
+                "You must specify either the `path` or `apex` option."
+            )
+
+    def _run_task(self):
+        apex = self._process_apex_from_path(self.options.get("path"))
+        apex += self._process_apex_string(self.options.get("apex"))
+
+        apex = self._prepare_apex(apex)
+        self.logger.info("Executing anonymous Apex")
+        result = self.tooling._call_salesforce(
+            method="GET",
+            url=f"{self.tooling.base_url}executeAnonymous",
+            params={"anonymousBody": apex},
+        )
+        self._check_result(result)
+        self.logger.info("Anonymous Apex Executed Successfully!")
+
+    def _process_apex_from_path(self, apex_path):
+        """Process apex given via the --path task option"""
+        if not apex_path:
+            return ""
+        if not in_directory(apex_path, self.project_config.repo_root):
+            raise TaskOptionsError(
+                "Please specify a path inside your project repository. "
+                f"You specified: {apex_path}"
+            )
+        self.logger.info(f"Processing Apex from path: {apex_path}")
+        try:
+            with open(apex_path, "r", encoding="utf-8") as f:
+                apex = f.read()
+        except IOError:
+            raise TaskOptionsError(f"Could not find or read file: {apex_path}")
+        return apex
+
+    def _process_apex_string(self, apex_string):
+        """Process the string of apex given via the --apex task option"""
+        apex = ""
+        if apex_string:
+            self.logger.info("Processing Apex from '--apex' option")
+            # append a newline so that we don't clash if
+            # apex was also given via the --path option
+            apex = "\n" + apex_string
+        return apex
+
+    def _prepare_apex(self, apex):
+        # Process namespace tokens
+        namespace = self.project_config.project__package__namespace
+        managed = determine_managed_mode(
+            self.options, self.project_config, self.org_config
+        )
+        if "namespaced" in self.options:
+            namespaced = process_bool_arg(self.options["namespaced"])
+        else:
+            namespaced = bool(namespace) and namespace == self.org_config.namespace
+
+        _, apex = inject_namespace(
+            "",
+            apex,
+            namespace=namespace,
+            managed=managed,
+            namespaced_org=namespaced,
+        )
+
+        # This is an extra token which is not handled by inject_namespace.
+        apex = apex.replace(
+            "%%%NAMESPACED_RT%%%", namespace + "." if namespaced else ""
+        )
+
+        # Process optional parameter token replacement
+        param1 = self.options.get("param1") or ""
+        apex = apex.replace("%%%PARAM_1%%%", param1)
+        param2 = self.options.get("param2") or ""
+        apex = apex.replace("%%%PARAM_2%%%", param2)
+
+        return apex
+
+    def _check_result(self, result):
+        # anon_results is an ExecuteAnonymous Result
+        # https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/sforce_api_calls_executeanonymous_result.htm
+        anon_results = safe_json_from_response(result)
+
+        # A result of `None` (body == "null") with a 200 status code means that a gack occurred.
+        if anon_results is None:
+            raise SalesforceException(
+                "Anonymous Apex returned the result `null`. "
+                "This often indicates a gack occurred."
+            )
+        if not anon_results["compiled"]:
+            raise ApexCompilationException(
+                anon_results["line"], anon_results["compileProblem"]
+            )
+        if not anon_results["success"]:
+            raise ApexException(
+                anon_results["exceptionMessage"], anon_results["exceptionStackTrace"]
+            )

cumulusci/tasks/apex/batch.py

@@ -0,0 +1,180 @@
+""" a task for waiting on a Batch Apex job to complete """
+from datetime import datetime
+from typing import Optional, Sequence
+
+from cumulusci.core.exceptions import SalesforceException
+from cumulusci.tasks.salesforce import BaseSalesforceApiTask
+from cumulusci.utils import parse_api_datetime
+
+COMPLETED_STATUSES = ["Completed", "Aborted", "Failed"]
+STOPPED_STATUSES = ["Aborted"]
+FAILED_STATUSES = ["Failed"]
+
+
+class BatchApexWait(BaseSalesforceApiTask):
+    """BatchApexWait polls an org until the latest batch job or queueable job
+    for an apex class completes or fails."""
+
+    name = "BatchApexWait"
+    original_created_date = None
+
+    task_options = {
+        "class_name": {
+            "description": "Name of the Apex class to wait for.",
+            "required": True,
+        },
+        "poll_interval": {
+            "description": "Seconds to wait before polling for batch or queueable job completion. "
+            "Defaults to 10 seconds."
+        },
+    }
+
+    def _run_task(self):
+        self.poll_interval_s = int(self.options.get("poll_interval", 10))
+
+        self._poll()  # will block until poll_complete
+
+        self.logger.info("Job is complete.")
+
+        summary = self.summarize_subjobs(self.subjobs)
+        failed_batches = self.failed_batches(self.subjobs)
+        job_aborted = summary["AnyAborted"]
+        job_failed = summary[
+            "AnyFailed"
+        ]  # note that a failed sub-job is different than a failed batch
+
+        # per https://help.salesforce.com/articleView?id=code_apex_job.htm&type=5
+        if job_aborted:
+            raise SalesforceException("Job was aborted by a user.")
+        elif job_failed:
+            raise SalesforceException("Job experienced a system failure.")
+        elif failed_batches:
+            self.logger.info("There have been some batch failures.")
+            raise SalesforceException(
+                f"There were batch errors: {repr(failed_batches)}"
+            )
+        elif not summary["CountsAddUp"]:
+            self.logger.info("The final record counts do not add up.")
+            self.logger.info("This is probably related to W-1132237")
+            self.logger.info(repr(summary))
+
+        if len(self.subjobs) > 1:
+            subjob_summary = f" in {len(self.subjobs)} sub-jobs"
+        else:
+            subjob_summary = ""
+
+        self.logger.info(
+            f"{self.options['class_name']} took {summary['ElapsedTime']} seconds to process {summary['TotalJobItems']} batches{subjob_summary}."
+        )
+
+    def failed_batches(self, subjobs: Sequence[dict]):
+        failed_batches = []
+        for subjob in subjobs:
+            if subjob["NumberOfErrors"]:
+                failed_batches.append(
+                    {
+                        key: value
+                        for key, value in subjob.items()
+                        if key
+                        in {
+                            "Id",
+                            "Status",
+                            "ExtendedStatus",
+                            "NumberOfErrors",
+                            "JobItemsProcessed",
+                            "TotalJobItems",
+                        }
+                    }
+                )
+        return failed_batches
+
+    def _poll_action(self):
+        # get batch status
+
+        if not self.original_created_date:
+            query_results = self.tooling.query(self._batch_query(date_limit=None))
+            if not query_results["records"]:
+                raise SalesforceException(f"No {self.options['class_name']} job found.")
+            self.original_created_date = parse_api_datetime(
+                query_results["records"][0]["CreatedDate"]
+            )
+        else:
+            query_results = self.tooling.query(
+                self._batch_query(date_limit=self.original_created_date)
+            )
+
+        self.subjobs = query_results["records"]
+        current_subjob = self.subjobs[0]
+
+        summary = self.summarize_subjobs(self.subjobs)
+
+        if len(self.subjobs) > 1:
+            subjob_info = f" in {len(self.subjobs)} sub-jobs."
+        else:
+            subjob_info = ""
+
+        self.logger.info(
+            f"{self.options['class_name']}: "
+            f"Job: {current_subjob['Id']} "
+            f"{summary['JobItemsProcessed']} of {summary['TotalJobItems']} "
+            f"({summary['NumberOfErrors']} failures)" + subjob_info
+        )
+
+        self.poll_complete = summary["Completed"]
+
+    def summarize_subjobs(self, subjobs: Sequence[dict]):
+        def reduce_key(valname: str, summary_func):
+            return summary_func(subjob[valname] for subjob in subjobs)
+
+        rc = {
+            "JobItemsProcessed": reduce_key("JobItemsProcessed", sum),
+            "TotalJobItems": reduce_key("TotalJobItems", sum),
+            "NumberOfErrors": reduce_key("NumberOfErrors", sum),
+            "Completed": all(
+                subjob["Status"] in COMPLETED_STATUSES for subjob in subjobs
+            ),
+            "AnyAborted": any(
+                subjob["Status"] in STOPPED_STATUSES for subjob in subjobs
+            ),
+            "AnyFailed": any(subjob["Status"] in FAILED_STATUSES for subjob in subjobs),
+        }
+        rc["Success"] = rc["NumberOfErrors"] == 0
+        rc["ElapsedTime"] = self.elapsed_time(subjobs)
+        rc["CountsAddUp"] = rc["JobItemsProcessed"] == rc["TotalJobItems"]
+        return rc
+
+    def elapsed_time(self, subjobs: Sequence[dict]):
+        """returns the time (in seconds) that the subjobs took, if complete"""
+        completed_dates = [
+            subjob["CompletedDate"] for subjob in subjobs if subjob.get("CompletedDate")
+        ]
+        if completed_dates:
+            most_recently_completed = max(completed_dates)
+            completed_date = parse_api_datetime(most_recently_completed)
+        else:
+            completed_date = datetime.now()
+        created_date = parse_api_datetime(
+            min(subjob["CreatedDate"] for subjob in subjobs)
+        )
+        td = completed_date - created_date
+        return td.total_seconds()
+
+    def _batch_query(self, date_limit: Optional[datetime] = None):
+        if not date_limit:
+            limit = " LIMIT 1 "
+            date_clause = "  "
+        else:
+            limit = " "
+            date_clause = f" AND CreatedDate >= {date_limit.isoformat()}Z "
+
+        query = (
+            "SELECT Id, ApexClass.Name, Status, ExtendedStatus, TotalJobItems, "
+            "JobItemsProcessed, NumberOfErrors, CreatedDate, CompletedDate "
+            "FROM AsyncApexJob "
+            "WHERE JobType IN ('BatchApex','Queueable') "
+            + f"AND ApexClass.Name='{self.options['class_name']}' "
+            + date_clause
+            + " ORDER BY CreatedDate DESC "
+            + limit
+        )
+        return query