feat(ingest/salesforce): helpful error messages on failure (#11266)

metadata-ingestion/src/datahub/ingestion/source/salesforce.py

@@ -8,6 +8,7 @@ from typing import Any, Dict, Iterable, List, Optional
 import requests
 from pydantic import Field, validator
 from simple_salesforce import Salesforce
+from simple_salesforce.exceptions import SalesforceAuthenticationFailed
 
 import datahub.emitter.mce_builder as builder
 from datahub.configuration.common import (
@@ -285,9 +286,20 @@ class SalesforceSource(Source):
                     **common_args,
                 )
 
-        except Exception as e:
+        except SalesforceAuthenticationFailed as e:
             logger.error(e)
-            raise ConfigurationError("Salesforce login failed") from e
+            if "API_CURRENTLY_DISABLED" in str(e):
+                # https://help.salesforce.com/s/articleView?id=001473830&type=1
+                error = "Salesforce login failed. Please make sure user has API Enabled Access."
+            else:
+                error = "Salesforce login failed. Please verify your credentials."
+                if (
+                    self.config.instance_url
+                    and "sandbox" in self.config.instance_url.lower()
+                ):
+                    error += "Please set `is_sandbox: True` in recipe if this is sandbox account."
+            raise ConfigurationError(error) from e
+
         if not self.config.api_version:
             # List all REST API versions and use latest one
             versions_url = "https://{instance}/services/data/".format(
@@ -314,8 +326,17 @@ class SalesforceSource(Source):
         )
 
     def get_workunits_internal(self) -> Iterable[MetadataWorkUnit]:
+        try:
             sObjects = self.get_salesforce_objects()
-
+        except Exception as e:
+            if "sObject type 'EntityDefinition' is not supported." in str(e):
+                # https://developer.salesforce.com/docs/atlas.en-us.api_tooling.meta/api_tooling/tooling_api_objects_entitydefinition.htm
+                raise ConfigurationError(
+                    "Salesforce EntityDefinition query failed. "
+                    "Please verify if user has 'View Setup and Configuration' permission."
+                ) from e
+            raise e
+        else:
             for sObject in sObjects:
                 yield from self.get_salesforce_object_workunits(sObject)
 
@@ -596,9 +617,9 @@ class SalesforceSource(Source):
 
         TypeClass = FIELD_TYPE_MAPPING.get(fieldType)
         if TypeClass is None:
-            self.report.report_warning(
-                sObjectName,
-                f"Unable to map type {fieldType} to metadata schema",
+            self.report.warning(
+                message="Unable to map field type to metadata schema",
+                context=f"{fieldType} for {fieldName} of {sObjectName}",
             )
             TypeClass = NullTypeClass
 
@@ -696,6 +717,8 @@ class SalesforceSource(Source):
             )
         )
 
+        customFields: Dict[str, Dict] = {}
+        try:
             sObject_custom_fields_response = self.sf._call_salesforce(
                 "GET", sObject_custom_fields_query_url
             ).json()
@@ -705,7 +728,16 @@ class SalesforceSource(Source):
                     sObject=sObjectName
                 )
             )
-        customFields: Dict[str, Dict] = {
+
+        except Exception as e:
+            error = "Salesforce CustomField query failed. "
+            if "sObject type 'CustomField' is not supported." in str(e):
+                # https://github.com/afawcett/apex-toolingapi/issues/19
+                error += "Please verify if user has 'View All Data' permission."
+
+            self.report.warning(message=error, exc=e)
+        else:
+            customFields = {
                 record["DeveloperName"]: record
                 for record in sObject_custom_fields_response["records"]
             }