Merge pull request #2704 from magento-commerce/kh_nq-errors

GraphQL: Update output for closing/deleting NQs
magento · Dec 22, 2021 · f628c4d · f628c4d
2 parents 5a74b54 + ef05d88
commit f628c4d
Show file tree

Hide file tree

Showing 4 changed files with 271 additions and 103 deletions.
diff --git a/src/_data/toc/graphql.yml b/src/_data/toc/graphql.yml
@@ -763,6 +763,10 @@ pages:
           url: /graphql/interfaces/wishlist-item-interface.html
           exclude_versions: ["2.3"]
 
+    - label: Unions
+      url: /graphql/unions.html
+      exclude_versions: ["2.3"]
+
     - label: Payment methods
       children:
 

diff --git a/src/guides/v2.4/graphql/mutations/close-negotiable-quotes.md b/src/guides/v2.4/graphql/mutations/close-negotiable-quotes.md
@@ -18,24 +18,38 @@ This mutation requires a valid [customer authentication token]({{page.baseurl}}/
 
 ## Example usage
 
-The following example closes the specified negotiable quote. The response includes a list of all the company negotiable quotes.
+The following example contains an invalid `quote_uids` value, causing a FAILURE status.
 
 **Request:**
 
 ```graphql
-mutation{
-  closeNegotiableQuotes(input: {quote_uids: ["FYGOCooAxSJnMdxI9v0cMI5EBaTPtwrr"]} ){
-    closed_quotes {
-      uid
-      name
-      status
+mutation {
+  closeNegotiableQuotes(
+    input: {
+      quote_uids: ["xyz"]
     }
-    negotiable_quotes {
-      total_count
-      items {
-        uid
-        name
-        status
+  ) {
+    result_status,
+    operation_results {
+      ...on NegotiableQuoteUidOperationSuccess{
+        __typename
+        quote_uid
+      }
+      ...on CloseNegotiableQuoteOperationFailure{
+        __typename
+        quote_uid
+        errors {
+          __typename
+          ...on ErrorInterface{
+            message
+          }
+          ...on NoSuchEntityUidError{
+            uid
+          }
+          ...on NegotiableQuoteInvalidStateError {
+            message
+          }
+        }
       }
     }
   }
@@ -48,33 +62,20 @@ mutation{
 {
   "data": {
     "closeNegotiableQuotes": {
-      "closed_quotes": [
+      "result_status": "FAILURE",
+      "operation_results": [
         {
-          "uid": "FYGOCooAxSJnMdxI9v0cMI5EBaTPtwrr",
-          "name": "New request",
-          "status": "SUBMITTED"
+          "__typename": "CloseNegotiableQuoteOperationFailure",
+          "quote_uid": "xyz",
+          "errors": [
+            {
+              "__typename": "NoSuchEntityUidError",
+              "message": "Could not find a quote with the specified UID.",
+              "uid": "xyz"
+            }
+          ]
         }
-      ],
-      "negotiable_quotes": {
-        "total_count": 3,
-        "items": [
-          {
-            "uid": "kw6mLEvl6vjjPNsjtJqwpamv5o0iT1bc",
-            "name": "Discount request",
-            "status": "ORDERED"
-          },
-          {
-            "uid": "xCA4wSZEHsb5QbFiKfoq5k1Dk8vIPBgb",
-            "name": "April 22 request",
-            "status": "SUBMITTED"
-          },
-          {
-            "uid": "FYGOCooAxSJnMdxI9v0cMI5EBaTPtwrr",
-            "name": "New request",
-            "status": "CLOSED"
-          }
-        ]
-      }
+      ]
     }
   }
 }
@@ -90,16 +91,73 @@ Attribute | Data Type | Description
 
 ## Output attributes
 
-The `CloseNegotiableQuotesOutput` output object contains the following attribute.
+The `CloseNegotiableQuotesOutput` output object contains the following fields.
 
 Attribute | Data Type | Description
 --- | --- | ---
-`closed_quotes` | [NegotiableQuote] | An array containing the negotiable quotes that were just closed
+`closed_quotes` | [NegotiableQuote] | Deprecated. Use `operation_results` instead. An array containing the negotiable quotes that were just closed
 `negotiable_quotes (filter NegotiableQuoteFilterInput, pageSize = 20 Int, currentPage = 1 Int)` | NegotiableQuotesOutput | A list of negotiable quotes that the customer can view
+`operation_results` | [CloseNegotiableQuoteOperationResult!]! | An array of closed negotiable quote UIDs and details about any errors
+`result_status` | BatchMutationStatus | The status of the request to close one or more negotiable quotes. The possible values are SUCCESS, FAILURE, and MIXED_RESULTS
 
 The `negotiable_quotes` attribute takes the following arguments.
 
 {% include graphql/negotiable-quotes-input.md %}
+
+### CloseNegotiableQuoteOperationResult attributes {#CloseNegotiableQuoteOperationResult}
+
+The [`CloseNegotiableQuoteOperationResult` union]({{page.baseurl}}/graphql/unions.html) provides details about the result of a request to close a negotiable quote. To return these details, specify fragments on the `CloseNegotiableQuoteOperationFailure` and `NegotiableQuoteUidOperationSuccess` objects. Specify the `__typename` attribute to distinguish the object types in the response.
+
+### CloseNegotiableQuoteOperationFailure attributes {#CloseNegotiableQuoteOperationFailure}
+
+The CloseNegotiableQuoteOperationFailure type contains details about a failed close operation on a negotiable quote. It contains the following fields.
+
+Attribute | Data Type | Description
+--- | --- | ---
+`errors` | [CloseNegotiableQuoteError!]! | An array of errors encountered while attempting close the negotiable quote
+`quote_uid` | ID! | The unique ID of a `NegotiableQuote` object
+
+### CloseNegotiableQuoteError attributes {#CloseNegotiableQuoteError}
+
+The `CloseNegotiableQuoteError` union type contains one or more of the following data types, all of which implement `ErrorInterface`.
+
+*  `InternalError`
+*  `NegotiableQuoteInvalidStateError`
+*  `NoSuchEntityUidError`
+
+#### InternalError attributes {#InternalError}
+
+The `InternalError` object contains an error message if an internal error occurred.
+
+Attribute | Data Type | Description
+--- | --- | ---
+`message` | String! | The returned error message
+
+#### NegotiableQuoteInvalidStateError attributes {#NegotiableQuoteInvalidStateError}
+
+The `NegotiableQuoteInvalidStateError` object contains an error message indicating that an operation was attempted on a negotiable quote in an invalid state.
+
+Attribute | Data Type | Description
+--- | --- | ---
+`message` | String! | The returned error message
+
+#### NoSuchEntityUidError attributes {#NoSuchEntityUidError}
+
+The `NoSuchEntityUidError` object contains an error message when an invalid UID was specified.
+
+Attribute | Data Type | Description
+--- | --- | ---
+`message` | String! | The returned error message
+`uid` | ID! | The specified invalid unique ID of an object
+
+### NegotiableQuoteUidOperationSuccess attributes {#NoSuchEntityUidError}
+
+The `NegotiableQuoteUidOperationSuccess` object contains details about a successful operation on a negotiable quote. It implements the `NegotiableQuoteUidNonFatalResultInterface`, which defines the following field
+
+Attribute | Data Type | Description
+--- | --- | ---
+quote_uid | ID! @doc(description: "The unique ID of a `NegotiableQuote` object
+
 ### NegotiableQuote attributes {#NegotiableQuote}
 
 {% include graphql/negotiable-quote.md %}
diff --git a/src/guides/v2.4/graphql/mutations/delete-negotiable-quotes.md b/src/guides/v2.4/graphql/mutations/delete-negotiable-quotes.md
@@ -27,35 +27,41 @@ deleteNegotiableQuotes(
 
 ## Example usage
 
-The following example deletes the specified negotiable quote. The response includes a list of all the company negotiable quotes.
+The following example deletes the specified negotiable quote.
 
 **Request:**
 
 ```graphql
-mutation{
-  deleteNegotiableQuotes(input:
-  {
-    quote_uids: ["FYGOCooAxSJnMdxI9v0cMI5EBaTPtwrr"]
-  }){
-    negotiable_quotes {
-     items {
-      uid
-      name
-      created_at
-      buyer {
-        firstname
-        lastname
+mutation {
+  deleteNegotiableQuotes(
+    input: {
+      quote_uids: ["R1chDMgmh6PXGz2AjXMTBaiE68wTydRH"]
+    }
+  ) {
+    result_status,
+    operation_results {
+      ...on NegotiableQuoteUidOperationSuccess{
+        __typename
+        quote_uid
       }
-      status
-      updated_at
-      prices {
-        grand_total {
-          value
-          currency
+      ...on DeleteNegotiableQuoteOperationFailure{
+        __typename
+        quote_uid
+        errors {
+          __typename
+          ...on ErrorInterface{
+            message
+          }
+          ...on NoSuchEntityUidError{
+            uid
+            message
+          }
+          ...on NegotiableQuoteInvalidStateError {
+            message
+          }
         }
       }
     }
-    }
   }
 }
 ```
@@ -66,44 +72,13 @@ mutation{
 {
   "data": {
     "deleteNegotiableQuotes": {
-      "negotiable_quotes": {
-        "items": [
-          {
-            "uid": "kw6mLEvl6vjjPNsjtJqwpamv5o0iT1bc",
-            "name": "Discount request",
-            "created_at": "2021-04-20 19:01:38",
-            "buyer": {
-              "firstname": "Taina",
-              "lastname": "Garofalo"
-            },
-            "status": "ORDERED",
-            "updated_at": "2021-04-21 18:29:28",
-            "prices": {
-              "grand_total": {
-                "value": 110.95,
-                "currency": "USD"
-              }
-            }
-          },
-          {
-            "uid": "xCA4wSZEHsb5QbFiKfoq5k1Dk8vIPBgb",
-            "name": "April 22 request",
-            "created_at": "2021-04-22 15:59:47",
-            "buyer": {
-              "firstname": "Taina",
-              "lastname": "Garofalo"
-            },
-            "status": "SUBMITTED",
-            "updated_at": "2021-04-23 18:21:44",
-            "prices": {
-              "grand_total": {
-                "value": 208.8,
-                "currency": "USD"
-              }
-            }
-          }
-        ]
-      }
+      "result_status": "SUCCESS",
+      "operation_results": [
+        {
+          "__typename": "NegotiableQuoteUidOperationSuccess",
+          "quote_uid": "R1chDMgmh6PXGz2AjXMTBaiE68wTydRH"
+        }
+      ]
     }
   }
 }
@@ -115,20 +90,76 @@ The `DeleteNegotiableQuotesInput` object contains the following attribute.
 
 Attribute | Data Type | Description
 --- | --- | ---
-`quote_uids` | [ID!]! | An array of unique IDs indicating which items to remove from the negotiable quote
+`quote_uids` | [ID!]! | An array of unique IDs indicating which quotes to delete
 
 ## Output attributes
 
-The `DeleteNegotiableQuotesOutput` output object contains the following attribute.
+The `DeleteNegotiableQuotesOutput` output object contains the following fields.
 
 Attribute | Data Type | Description
 --- | --- | ---
-`negotiable_quotes (filter NegotiableQuoteFilterInput, pageSize = 20 Int, currentPage = 1 Int)` | NegotiableQuotesOutput | A list of negotiable quotes that the customer can view
+`negotiable_quotes(filter NegotiableQuoteFilterInput, pageSize = 20 Int, currentPage = 1 Int)` | NegotiableQuotesOutput | A list of negotiable quotes that the customer can view
+`operation_results` | [DeleteNegotiableQuoteOperationResult!]! | An array of deleted negotiable quote UIDs and details about any errors
+`result_status` | BatchMutationStatus | The status of the request to delete one or more negotiable quotes. The possible values are SUCCESS, FAILURE, and MIXED_RESULTS
 
-This attribute takes the following arguments.
+The `negotiable_quotes` field takes the following arguments.
 
 {% include graphql/negotiable-quotes-input.md %}
 
+### DeleteNegotiableQuoteOperationResult attributes {#DeleteNegotiableQuoteOperationResult}
+
+The [`DeleteNegotiableQuoteOperationResult` union]({{page.baseurl}}/graphql/unions.html) provides details about the result of a request to delete a negotiable quote. To return these details, specify fragments on the `DeleteNegotiableQuoteOperationFailure` and `NegotiableQuoteUidOperationSuccess` objects. Specify the `__typename` attribute to distinguish the object types in the response.
+
+### DeleteNegotiableQuoteOperationFailure attributes {#DeleteNegotiableQuoteOperationFailure}
+
+The DeleteNegotiableQuoteOperationFailure type contains details about a failed delete operation on a negotiable quote. It contains the following fields.
+
+Attribute | Data Type | Description
+--- | --- | ---
+`errors` | [DeleteNegotiableQuoteError!]! | An array of errors encountered while attempting delete the negotiable quote
+`quote_uid` | ID! | The unique ID of a `NegotiableQuote` object
+
+### DeleteNegotiableQuoteError attributes {#DeleteNegotiableQuoteError}
+
+The `DeleteNegotiableQuoteError` union type contains one or more of the following data types, all of which implement `ErrorInterface`.
+
+*  `InternalError`
+*  `NegotiableQuoteInvalidStateError`
+*  `NoSuchEntityUidError`
+
+#### InternalError attributes {#InternalError}
+
+The `InternalError` object contains an error message if an internal error occurred.
+
+Attribute | Data Type | Description
+--- | --- | ---
+`message` | String! | The returned error message
+
+#### NegotiableQuoteInvalidStateError attributes {#NegotiableQuoteInvalidStateError}
+
+The `NegotiableQuoteInvalidStateError` object contains an error message indicating that an operation was attempted on a negotiable quote in an invalid state.
+
+Attribute | Data Type | Description
+--- | --- | ---
+`message` | String! | The returned error message
+
+#### NoSuchEntityUidError attributes {#NoSuchEntityUidError}
+
+The `NoSuchEntityUidError` object contains an error message when an invalid UID was specified.
+
+Attribute | Data Type | Description
+--- | --- | ---
+`message` | String! | The returned error message
+`uid` | ID! | The specified invalid unique ID of an object
+
+### NegotiableQuoteUidOperationSuccess attributes {#NegotiableQuoteUidOperationSuccess}
+
+The `NegotiableQuoteUidOperationSuccess` object contains details about a successful operation on a negotiable quote. It implements the `NegotiableQuoteUidNonFatalResultInterface`, which defines the following field
+
+Attribute | Data Type | Description
+--- | --- | ---
+quote_uid | ID! | The unique ID of a `NegotiableQuote` object
+
 ### NegotiableQuote attributes {#NegotiableQuote}
 
 {% include graphql/negotiable-quote.md %}