Handle errors

This guide explains how to manage Workspace Studio errors that occur when a step runs. Errors are displayed on the Activity tab.

When an error occurs, you can specify whether the step should:

  • Return an actionable error: Append a button to the error log that directs the user to the step's configuration card, letting them modify their inputs to resolve the error. To mark an error as actionable, return AddOnsResponseService.ErrorActionability.ACTIONABLE. To mark an error as unactionable, return AddOnsResponseService.ErrorActionability.NOT_ACTIONABLE.
  • Retry the step after an error: The flow attempts to run the step again up to five times before halting. To mark an error as one that can be retried, return AddOnsResponseService.ErrorRetryability.RETRYABLE. To mark an error that can't be retried, return AddOnsResponseService.ErrorRetryability.NOT_RETRYABLE.

You can also create custom error logs with chips, hyperlinks, and styled text to provide users with more detailed context about the error.

Return an actionable error

The following example builds a step that asks a user for a negative number. If the user enters a positive number, the step returns an actionable error on the Activity tab that prompts the user to correct their input.

The following manifest file defines the step's inputs, outputs, and the functions to call for configuration and execution.

JSON

{
  "timeZone": "America/Toronto",
  "dependencies": {},
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "Retry Errors Example",
      "logoUrl": "https://www.gstatic.com/images/icons/material/system/1x/pets_black_48dp.png",
      "useLocaleFromApp": true
    },
    "flows": {
      "workflowElements": [
        {
          "id": "handle_error_action",
          "state": "ACTIVE",
          "name": "Handle Error Action",
          "description": "To notify the user that some error has occurred",
          "workflowAction": {
            "inputs": [
              {
                "id": "value1",
                "description": "The input from the user",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "STRING"
                }
              }
            ],
            "outputs": [
              {
                "id": "output_1",
                "description": "The output",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "STRING"
                }
              }
            ],
            "onConfigFunction": "onConfiguration",
            "onExecuteFunction": "onExecution"
          }
        }
      ]
    }
  }
}

The following code builds the configuration card and handles the execution logic, including error handling.

Apps Script

/**
 * Returns a configuration card for the step.
 * This card contains a text input field for the user.
 */
function onConfiguration() {
  let section = CardService.newCardSection()
    .addWidget(CardService.newTextInput()
      .setFieldName("value1")
      .setId("value1")
      .setTitle("Please input negative numbers!"));
  const card = CardService.newCardBuilder().addSection(section).build();
  return card;
}

/**
 * Gets an integer value from variable data, handling both string and integer formats.
 * @param {Object} variableData The variable data object from the event.
 * @return {number} The extracted integer value.
 */
function getIntValue(variableData) {
  if (variableData.stringValues) {
    return parseInt(variableData.stringValues[0]);
  }
  return variableData.integerValues[0];
}

/**
 * Executes the step.
 * If the user input is a positive number, it throws an error and returns an
 * actionable error message. Otherwise, it returns the input as an output variable.
 * @param {Object} e The event object.
 */
function onExecution(e) {
  try {
    var input_value = getIntValue(e.workflow.actionInvocation.inputs["value1"]);
    if (input_value > 0) {
      throw new Error('Found invalid positive input value!');
    }

    // If execution is successful, return the output variable and a log.
    const styledText_1 = AddOnsResponseService.newStyledText()
      .setText("Execution completed, the number you entered was: ")
      .addStyle(AddOnsResponseService.TextStyle.ITALIC)
      .addStyle(AddOnsResponseService.TextStyle.UNDERLINE)

    const styledText_2 = AddOnsResponseService.newStyledText()
      .setText(input_value)
      .setFontWeight(AddOnsResponseService.FontWeight.BOLD)

    const workflowAction = AddOnsResponseService.newReturnOutputVariablesAction()
      .setVariableDataMap(
        {
          "output_1": AddOnsResponseService.newVariableData()
            .addStringValue(input_value)
        }
      )
      .setLog(AddOnsResponseService.newWorkflowTextFormat()
        .addTextFormatElement(
          AddOnsResponseService.newTextFormatElement()
            .setStyledText(styledText_1)
        ).addTextFormatElement(
          AddOnsResponseService.newTextFormatElement()
            .setStyledText(styledText_2)