task(connector-exception): Add a possibility to pass custom variables…

… to the ConnectorException (#2356)

* task(connector-exception): Add a possibility to pass custom variable to the ConnectorException

* task(connector-exception): Add a UT

* feat(detailed-connector-exception): Add tests

connector-runtime/connector-runtime-core/src/main/java/io/camunda/connector/runtime/core/outbound/ConnectorJobHandler.java

@@ -97,9 +97,15 @@ protected static Map<String, Object> exceptionToMap(Exception exception) {
     }
     if (exception instanceof ConnectorException connectorException) {
       var code = connectorException.getErrorCode();
+      var errorVariables = connectorException.getErrorVariables();
+
       if (code != null) {
         result.put("code", code);
       }
+
+      if (errorVariables != null) {
+        result.put("errorVariables", errorVariables);
+      }
     }
     return Map.copyOf(result);
   }

connector-runtime/connector-runtime-core/src/test/java/io/camunda/connector/runtime/core/outbound/ConnectorJobHandlerTest.java

@@ -34,6 +34,7 @@
 
 import com.fasterxml.jackson.core.JsonProcessingException;
 import io.camunda.connector.api.error.ConnectorException;
+import io.camunda.connector.api.error.ConnectorExceptionBuilder;
 import io.camunda.connector.api.error.ConnectorRetryExceptionBuilder;
 import io.camunda.connector.api.outbound.OutboundConnectorFunction;
 import io.camunda.connector.runtime.core.ConnectorHelper;
@@ -806,6 +807,64 @@ void shouldCreateBpmnError_UsingExceptionCodeAndRawContext() {
       assertThat(result.getErrorMessage()).isEqualTo("Message: exception message");
     }
 
+    @Test
+    void shouldCreateBpmnError_UsingExceptionCodeAndErrorVariables() {
+      // given
+      var errorExpression =
+          "if error.code != null then "
+              + "{ \"errorType\": \"bpmnError\", \"code\": error.code, \"message\": \"Message: \" + error.message, \"variables\": error.errorVariables} "
+              + "else {}";
+      var jobHandler =
+          newConnectorJobHandler(
+              context -> {
+                throw new ConnectorExceptionBuilder()
+                    .errorCode("1013")
+                    .message("exception message")
+                    .errorVariables(Map.of("foo", "bar"))
+                    .build();
+              });
+      // when
+      var result =
+          JobBuilder.create()
+              .withErrorExpressionHeader(errorExpression)
+              .executeAndCaptureResult(jobHandler, false, true);
+      // then
+      assertThat(result.getErrorCode()).isEqualTo("1013");
+      assertThat(result.getVariables()).isEqualTo(Map.of("foo", "bar"));
+      assertThat(result.getErrorMessage()).isEqualTo("Message: exception message");
+    }
+
+    @Test
+    void shouldCreateBpmnErro2r_UsingExceptionCodeAndErrorVariables() {
+      // given
+      var jobHandler =
+          newConnectorJobHandler(
+              context -> {
+                throw new ConnectorExceptionBuilder()
+                    .errorCode("1013")
+                    .message("exception message")
+                    .errorVariables(Map.of("foo", "bar"))
+                    .build();
+              });
+      // when
+      var result = JobBuilder.create().executeAndCaptureResult(jobHandler, false, false);
+      // then
+      assertThat(result.getVariables())
+          .isEqualTo(
+              Map.of(
+                  "error",
+                  Map.of(
+                      "code",
+                      "1013",
+                      "errorVariables",
+                      Map.of("foo", "bar"),
+                      "message",
+                      "exception message",
+                      "type",
+                      "io.camunda.connector.api.error.ConnectorException")));
+      assertThat(result.getErrorMessage()).isEqualTo("exception message");
+    }
+
     @Test
     void shouldCreateBpmnError_UsingExceptionWithBpmnErrorFunction() {
       // given

connector-sdk/core/src/main/java/io/camunda/connector/api/error/ConnectorException.java

@@ -17,14 +17,21 @@
 package io.camunda.connector.api.error;
 
 import java.io.Serial;
+import java.util.Map;
 
-/** Unchecked exception indicating issues with a connector. */
+/**
+ * Unchecked exception indicating issues with a connector.
+ *
+ * @see ConnectorExceptionBuilder
+ */
 public class ConnectorException extends RuntimeException {
 
   @Serial private static final long serialVersionUID = 1L;
 
   protected String errorCode;
 
+  protected Map<String, Object> errorVariables;
+
   public ConnectorException(Throwable cause) {
     super(cause);
   }
@@ -73,10 +80,34 @@ public ConnectorException(String errorCode, String message, Throwable cause) {
     this.errorCode = errorCode;
   }
 
+  /**
+   * Constructs a new exception with the specified error code, message, cause, and error variables.
+   *
+   * @param errorCode the error code to populate
+   * @param message the message detailing what went wrong
+   * @param cause the cause (which is saved for later retrieval by the {@link #getCause()} method).
+   *     (A <code>null</code> value is permitted, and indicates that the cause is nonexistent or
+   *     unknown.)
+   * @param errorVariables the error variables to populate
+   * @see ConnectorExceptionBuilder
+   */
+  ConnectorException(
+      String errorCode, String message, Throwable cause, Map<String, Object> errorVariables) {
+    this(errorCode, message, cause);
+    this.errorVariables = errorVariables;
+  }
+
   /**
    * @return the error code
    */
   public String getErrorCode() {
     return errorCode;
   }
+
+  /**
+   * @return the error variables
+   */
+  public Map<String, Object> getErrorVariables() {
+    return errorVariables;
+  }
 }

connector-sdk/core/src/main/java/io/camunda/connector/api/error/ConnectorExceptionBuilder.java

@@ -0,0 +1,52 @@
+/*
+ * Copyright Camunda Services GmbH and/or licensed to Camunda Services GmbH
+ * under one or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information regarding copyright
+ * ownership. Camunda licenses this file to you under the Apache License,
+ * Version 2.0; you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.camunda.connector.api.error;
+
+import java.util.Map;
+
+public class ConnectorExceptionBuilder {
+
+  private String errorCode;
+  private String message;
+  private Throwable cause;
+  private Map<String, Object> errorVariables;
+
+  public ConnectorExceptionBuilder errorCode(String errorCode) {
+    this.errorCode = errorCode;
+    return this;
+  }
+
+  public ConnectorExceptionBuilder message(String message) {
+    this.message = message;
+    return this;
+  }
+
+  public ConnectorExceptionBuilder cause(Throwable cause) {
+    this.cause = cause;
+    return this;
+  }
+
+  public ConnectorExceptionBuilder errorVariables(Map<String, Object> errorVariables) {
+    this.errorVariables = errorVariables;
+    return this;
+  }
+
+  public ConnectorException build() {
+    return new ConnectorException(errorCode, message, cause, errorVariables);
+  }
+}