W-9732906: differentiate system and user errors in sync flow

After this change, when an exception (Fault) is captured:

- if a CartValidationOutput exists treat the error as
a buyer user error: redirect back to the cart and let it show the error
banner. Example: "Insufficient quantity for the product with sku..."

- otherwise treat the error as a system error: show the intermediate (debug)
error screen and do not let the cart show the error banner.
Example "A cart id must be included to B2BSyncCheckInventory"

Note that non exception (Fault) error behavior is unchanged: show the
intermediate error screen and do not let the cart show the error
banner. Example "missing payment information"

Additional changes:
- update the apex classes to have examples of both system and buyer user
errors: specifically missing cartId, external service network failures,
and any non-explicitly handled exceptions are treated as system errors.

Author: patricksullivansf

examples/checkout-main/classes/B2BSyncCheckInventory.cls

@@ -6,8 +6,8 @@ global with sharing class B2BSyncCheckInventory {
         // Validate the input
         if (cartIds == null || cartIds.size() != 1) {
             String errorMessage = 'A cart id must be included to B2BSyncCheckInventory';
-            saveCartValidationOutputError(errorMessage, '');
-            throw new CalloutException (errorMessage);
+            // Sync non-user errors skip saveCartValidationOutputError
+            throw new IllegalArgumentException (errorMessage);
         }
 
         // Extract cart id and start processing
@@ -16,57 +16,45 @@ global with sharing class B2BSyncCheckInventory {
     }
 
     private static void startCartProcessSync(ID cartId) {
-        try {
-            // Get all SKUs and their quantities from cart items.
-            Map<String, Decimal> quantitiesFromSalesforce = new Map<String, Decimal>();
-            for (CartItem cartItem : [SELECT Sku, Quantity FROM CartItem WHERE CartId = :cartId AND Type = 'Product' WITH SECURITY_ENFORCED]) {
-                if (String.isBlank(cartItem.Sku)) {
-                    String errorMessage = 'The SKUs for all products in your cart must be defined.';
-                    saveCartValidationOutputError(errorMessage, cartId);
-                    throw new CalloutException(errorMessage);
-                }
-                quantitiesFromSalesforce.put(cartItem.Sku, cartItem.Quantity);
+        // Get all SKUs and their quantities from cart items.
+        Map<String, Decimal> quantitiesFromSalesforce = new Map<String, Decimal>();
+        for (CartItem cartItem : [SELECT Sku, Quantity FROM CartItem WHERE CartId = :cartId AND Type = 'Product' WITH SECURITY_ENFORCED]) {
+            if (String.isBlank(cartItem.Sku)) {
+                String errorMessage = 'The SKUs for all products in your cart must be defined.';
+                saveCartValidationOutputError(errorMessage, cartId);
+                throw new CalloutException(errorMessage);
             }
+            quantitiesFromSalesforce.put(cartItem.Sku, cartItem.Quantity);
+        }
 
-            // Stop checkout if there are no items in the cart
-            if (quantitiesFromSalesforce.isEmpty()) {
-                String errorMessage = 'Looks like your cart is empty.';
+        // Stop checkout if there are no items in the cart
+        if (quantitiesFromSalesforce.isEmpty()) {
+            String errorMessage = 'Looks like your cart is empty.';
+            saveCartValidationOutputError(errorMessage, cartId);
+            throw new CalloutException(errorMessage);        
+        }
+        
+        // Get all available quantities for products in the cart (cart items) from an external service.
+        Map<String, Object> quantitiesFromExternalService = getQuantitiesFromExternalService(cartId, quantitiesFromSalesforce.keySet());            
+        
+        // For each cart item SKU, check that the quantity from the external service
+        // is greater or equal to the quantity in the cart.
+        // If that is not true, set the integration status to "Failed".
+        for (String sku : quantitiesFromSalesforce.keySet()) {
+            Decimal quantityFromSalesforce = quantitiesFromSalesforce.get(sku);
+            Decimal quantityFromExternalService = (Decimal)quantitiesFromExternalService.get(sku);
+            if (quantityFromExternalService == null){
+                String errorMessage = 'The product with sku ' + sku + ' could not be found in the external system';
                 saveCartValidationOutputError(errorMessage, cartId);
-                throw new CalloutException(errorMessage);        
-            }
-            
-            // Get all available quantities for products in the cart (cart items) from an external service.
-            Map<String, Object> quantitiesFromExternalService = getQuantitiesFromExternalService(cartId, quantitiesFromSalesforce.keySet());            
-            
-            // For each cart item SKU, check that the quantity from the external service
-            // is greater or equal to the quantity in the cart.
-            // If that is not true, set the integration status to "Failed".
-            for (String sku : quantitiesFromSalesforce.keySet()) {
-                Decimal quantityFromSalesforce = quantitiesFromSalesforce.get(sku);
-                Decimal quantityFromExternalService = (Decimal)quantitiesFromExternalService.get(sku);
-                if (quantityFromExternalService == null){
-                    String errorMessage = 'The product with sku ' + sku + ' could not be found in the external system';
-                    saveCartValidationOutputError(errorMessage, cartId);
-                    throw new CalloutException(errorMessage);
-                } 
-                else if (quantityFromExternalService < quantityFromSalesforce){
-                    String errorMessage = 'Insufficient quantity for the product with sku ' + sku + ': ' 
-                               + quantityFromSalesforce + ' needed, but only '
-                               + quantityFromExternalService + ' available.';
-                    saveCartValidationOutputError(errorMessage, cartId);
-                    throw new CalloutException(errorMessage);
-                }
+                throw new CalloutException(errorMessage);
+            } 
+            else if (quantityFromExternalService < quantityFromSalesforce){
+                String errorMessage = 'Insufficient quantity for the product with sku ' + sku + ': ' 
+                           + quantityFromSalesforce + ' needed, but only '
+                           + quantityFromExternalService + ' available.';
+                saveCartValidationOutputError(errorMessage, cartId);
+                throw new CalloutException(errorMessage);
             }
-        } catch (CalloutException e) {
-            throw e;
-        } catch (Exception e) {
-            // For testing purposes, this example treats exceptions as user errors, which means they are displayed to the buyer user.
-            // In production you probably want this to be an admin-type error. In that case, throw the exception here
-            // and make sure that a notification system is in place to let the admin know that the error occurred.
-            // See the readme section about error handling for details about how to create that notification.
-            String errorMessage = 'An exception of type ' + e.getTypeName() + ' has occurred: ' + e.getMessage();
-            saveCartValidationOutputError(errorMessage, cartId);
-            throw new CalloutException(errorMessage);          
         }
     }
 
@@ -98,7 +86,7 @@ global with sharing class B2BSyncCheckInventory {
         }
         else {
             String errorMessage = 'There was a problem with the request. Error: ' + response.getStatusCode();
-            saveCartValidationOutputError(errorMessage, cartId);
+            // Sync non-user errors skip saveCartValidationOutputError
             throw new CalloutException(errorMessage);
         }
     }  
@@ -109,7 +97,7 @@ global with sharing class B2BSyncCheckInventory {
             // CartId: Foreign key to the WebCart that this validation line is for
             // Level (required): One of the following - Info, Error, or Warning
             // Message (optional): Message displyed to the user
-            // Name (required): The name of this CartValidationOutput record. For example CartId:BackgroundOperationId
+            // Name (required): The name of this CartValidationOutput record. For example CartId
             // RelatedEntityId (required): Foreign key to WebCart, CartItem, CartDeliveryGroup
             // Type (required): One of the following - SystemError, Inventory, Taxes, Pricing, Shipping, Entitlement, Other
             CartValidationOutput cartValidationError = new CartValidationOutput(
@@ -123,4 +111,4 @@ global with sharing class B2BSyncCheckInventory {
 
             insert(cartValidationError);
     }
-}
+}

examples/checkout-main/classes/B2BSyncCheckInventoryTest.cls

@@ -34,7 +34,7 @@ public class B2BSyncCheckInventoryTest {
         Test.stopTest();
     }
 
-    @isTest static void testWhenExternalServiceCallFailsAFailedStatusIsReturnedAndACartValidationOutputEntryIsCreated() {
+    @isTest static void testWhenExternalServiceCallFailsAFailedStatusIsReturnedAndACartValidationOutputEntryIsNotCreated() {
         // Because test methods do not support Web service callouts, we create a mock response based on a static resource.
         // To create the static resource from the Developer Console, select File | New | Static Resource
         StaticResourceCalloutMock mock = new StaticResourceCalloutMock();
@@ -51,7 +51,7 @@ public class B2BSyncCheckInventoryTest {
         List<Id> webCarts = new List<Id>{webCart.Id};
 
         String expectedErrorMessage = 'There was a problem with the request. Error: 404';
-        executeAndEnsureFailure(expectedErrorMessage, webCarts);
+        executeAndEnsureFailure(expectedErrorMessage, webCarts, false);
 
         Test.stopTest();
     }
@@ -68,7 +68,7 @@ public class B2BSyncCheckInventoryTest {
         List<Id> webCarts = new List<Id>{webCart.Id};
 
         String expectedErrorMessage = 'Looks like your cart is empty.';
-        executeAndEnsureFailure(expectedErrorMessage, webCarts);
+        executeAndEnsureFailure(expectedErrorMessage, webCarts, true);
 
         Test.stopTest();
 
@@ -94,7 +94,7 @@ public class B2BSyncCheckInventoryTest {
         insert cartItemWithNoSku;
 
         String expectedErrorMessage = 'The SKUs for all products in your cart must be defined.';
-        executeAndEnsureFailure(expectedErrorMessage, webCarts);
+        executeAndEnsureFailure(expectedErrorMessage, webCarts, true);
 
         Test.stopTest();
 
@@ -103,7 +103,7 @@ public class B2BSyncCheckInventoryTest {
     }
 
     // Executes the check inventory check and ensures an error is correctly triggered
-    static void executeAndEnsureFailure(String expectedErrorMessage, List<Id> webCarts) {
+    static void executeAndEnsureFailure(String expectedErrorMessage, List<Id> webCarts, Boolean userError) {
         try {
             B2BSyncCheckInventory.syncCheckInventory(webCarts);
 
@@ -115,8 +115,12 @@ public class B2BSyncCheckInventoryTest {
 
         // A new CartValidationOutput record with level 'Error' was created.
         List<CartValidationOutput> cartValidationOutputs = [SELECT Id, Message FROM CartValidationOutput WHERE Level = 'Error'];
-        System.assertEquals(1, cartValidationOutputs.size());
-        System.assertEquals(expectedErrorMessage, cartValidationOutputs.get(0).Message);
+        if (userError) {
+            System.assertEquals(1, cartValidationOutputs.size());
+            System.assertEquals(expectedErrorMessage, cartValidationOutputs.get(0).Message);
+        } else {
+            System.assertEquals(0, cartValidationOutputs.size());
+        }
     }
 
     // Inserts a cart item when we only know the cart id
@@ -144,4 +148,4 @@ public class B2BSyncCheckInventoryTest {
         CartItem cartItem = [SELECT Id FROM CartItem WHERE Name = 'TestProduct' LIMIT 1];
         delete cartItem;
     }
-}
+}

examples/checkout-main/classes/B2BSyncDelivery.cls

@@ -7,7 +7,7 @@ public class B2BSyncDelivery {
         // Validate the input
         if (cartIds == null || cartIds.size() != 1) {
             String errorMessage = 'A cart id must be included to B2BSyncDelivery';
-            saveCartValidationOutputError(errorMessage, '');
+            // Sync non-user errors skip saveCartValidationOutputError
             throw new CalloutException (errorMessage);
         }
 
@@ -42,14 +42,9 @@ public class B2BSyncDelivery {
                                                                   cartId);
                 i+=1;
             }
-        } catch (CalloutException e) {
-            throw e;
-        // For testing purposes, this example treats exceptions as user errors, which means they are displayed to the buyer user.
-        // In production you probably want this to be an admin-type error. In that case, throw the exception here
-        // and make sure that a notification system is in place to let the admin know that the error occurred.
-        // See the readme section about error handling for details about how to create that notification.
         } catch (DmlException de) {
-            // Catch any exceptions thrown when trying to insert the shipping charge to the CartItems
+            // To aid debugging catch any exceptions thrown when trying to insert the shipping charge to the CartItems
+            // In production you might want to hide these details from the buyer user.
             Integer numErrors = de.getNumDml();
             String errorMessage = 'There were ' + numErrors + ' errors when trying to insert the charge in the CartItem: ';
             for(Integer errorIdx = 0; errorIdx < numErrors; errorIdx++) {
@@ -58,10 +53,6 @@ public class B2BSyncDelivery {
                 errorMessage += ' , ';
             }
 
-            saveCartValidationOutputError(errorMessage, cartId);
-            throw new CalloutException (errorMessage);
-        } catch(Exception e) {
-            String errorMessage = 'An exception of type ' + e.getTypeName() + ' has occurred: ' + e.getMessage();
             saveCartValidationOutputError(errorMessage, cartId);
             throw new CalloutException (errorMessage);
         }
@@ -129,7 +120,7 @@ public class B2BSyncDelivery {
         }
         else {
             String errorMessage = 'There was a problem with the request. Error: ' + response.getStatusCode();
-            saveCartValidationOutputError(errorMessage, cartId);
+            // Sync non-user errors skip saveCartValidationOutputError
             throw new CalloutException (errorMessage);
         }
     }
@@ -201,7 +192,7 @@ public class B2BSyncDelivery {
             // CartId: Foreign key to the WebCart that this validation line is for
             // Level (required): One of the following - Info, Error, or Warning
             // Message (optional): Message displayed to the user
-            // Name (required): The name of this CartValidationOutput record. For example CartId:BackgroundOperationId
+            // Name (required): The name of this CartValidationOutput record. For example CartId
             // RelatedEntityId (required): Foreign key to WebCart, CartItem, CartDeliveryGroup
             // Type (required): One of the following - SystemError, Inventory, Taxes, Pricing, Shipping, Entitlement, Other
             CartValidationOutput cartValidationError = new CartValidationOutput(

examples/checkout-main/classes/B2BSyncDeliveryTest.cls

@@ -42,7 +42,7 @@ public class B2BSyncDeliveryTest {
     }
 
 
-    @isTest static void testWhenExternalServiceCallFailsAFailedStatusIsReturnedAndACartValidationOutputEntryIsCreated() {
+    @isTest static void testWhenExternalServiceCallFailsAFailedStatusIsReturnedAndACartValidationOutputEntryIsNotCreated() {
         // Because test methods do not support Web service callouts, we create a mock response based on a static resource.
         // To create the static resource from the the Developer Console, select File | New | Static Resource
         StaticResourceCalloutMock mock = new StaticResourceCalloutMock();
@@ -70,9 +70,8 @@ public class B2BSyncDeliveryTest {
 
         // A new CartValidationOutput record with level 'Error' was created.
         List<CartValidationOutput> cartValidationOutputs = [SELECT Id, Message FROM CartValidationOutput WHERE Level = 'Error'];
-        System.assertEquals(1, cartValidationOutputs.size());
-        System.assertEquals(expectedErrorMessage, cartValidationOutputs.get(0).Message);
+        System.assertEquals(0, cartValidationOutputs.size());
 
         Test.stopTest();
     }
-}
+}