Log activity and errors

This guide explains how to write custom logs and error messages that help troubleshoot a flow step that fails to run in the flows Activity tab.

By default, the Activity tab logs the name of the step that runs as defined in its manifest file. To help you understand what happened during a step run, you should write custom logs for your step, too. If users encounter unexpected behavior while running your step, your logs can help them understand what happened.

A helpful log entry has two attributes:

  • A chip containing a hyperlink to the resource that was created or updated by the step. For example, if your step creates a Google Doc, use the chip to link to the created Google Doc.
  • A detailed error message describing why a step failed to run and how to resolve the issue.

The following code sample shows how a step's onExecuteFunctionCreateDocument() can log a successful run and an error to the Activity tab:

Apps Script

// A helper method to return host app actions
function returnActionHelper(action) {
  let hostAppAction = AddOnsResponseService.newHostAppAction()
    .setWorkflowAction(action);

  let renderAction = AddOnsResponseService.newRenderActionBuilder()
    .setHostAppAction(hostAppAction)
    .build();

  return renderAction;
}

function createDocument() {
  let randomInt = Math.floor(Math.random() * 2)
  console.log("The random generated integer is: ", randomInt);
  if (randomInt == 0) {
    console.log("Mock document creation failed.");
    return false;
  } else if (randomInt == 1) {
    console.log("Mock document creation succeeded.");
    return true;
  }
}

function onExecuteFunctionCreateDocument(e) {

  // true if the document is successfully created, false if something goes wrong.
  var successfulRun = createDocument();

  // If successful, return an activity log linking to the created document.
  if (successfulRun == true) {
    let logChip = AddOnsResponseService.newTextFormatChip()
      .setTextFormatIcon(
        AddOnsResponseService.newTextFormatIcon()
          .setMaterialIconName("edit_document")
      )
      .setUrl("https://docs.google.com/document/d/{DOCUMENT}")
      .setLabel("{NAMEOFDOCUMENT}");

    const workflowAction = AddOnsResponseService.newReturnOutputVariablesAction()
      // Set the user-facing error log
      .setLog(
        AddOnsResponseService.newWorkflowTextFormat()
          .addTextFormatElement(
            AddOnsResponseService.newTextFormatElement()
              .setText("Created Google Doc")
          )
          .addTextFormatElement(
            AddOnsResponseService.newTextFormatElement()
              .setTextFormatChip(logChip)
          )
          .addTextFormatElement(
            AddOnsResponseService.newTextFormatElement()
              .setText("Created doc detailing how to improve product.")
          )
      );

    returnActionHelper(workflowAction);
  }
  // Otherwise, return an activity log containing an error explaining what happened and how to resolve the issue.
  else {
    let errorChip = AddOnsResponseService.newTextFormatChip()
      .setTextFormatIcon(
        AddOnsResponseService.newTextFormatIcon()
          .setMaterialIconName("document")
      )
      .setLabel("{NAMEOFDOCUMENT}");

    const workflowAction = AddOnsResponseService.newReturnElementErrorAction()
      .setErrorActionability(AddOnsResponseService.ErrorActionability.NOT_ACTIONABLE)
      .setErrorRetryability(AddOnsResponseService.ErrorRetryability.NOT_RETRYABLE)
      // Set the user-facing error log
      .setErrorLog(
        AddOnsResponseService.newWorkflowTextFormat()
          .addTextFormatElement(
            AddOnsResponseService.newTextFormatElement()
              .setText("Failed to create Google Doc.")
          )
          .addTextFormatElement(
            AddOnsResponseService.newTextFormatElement()
              .setTextFormatChip(errorChip)
          )
          .addTextFormatElement(
            AddOnsResponseService.newTextFormatElement()
              .setText("Unable to create Google Document because OAuth verification failed. Grant one of these authorization scopes and try again: https://www.googleapis.com/auth/documents, https://www.googleapis.com/auth/drive, https://www.googleapis.com/auth/drive.file")
          )
      );

    returnActionHelper(workflowAction);
  }
}