Attività di log ed errori

Questa guida spiega come scrivere log ed errori personalizzati che aiutano a risolvere i problemi relativi a un passaggio del flusso che non viene eseguito nella scheda Attività dei flussi.

Per impostazione predefinita, la scheda Attività registra il nome del passaggio eseguito come definito nel file manifest. Per aiutarti a capire cosa è successo durante l'esecuzione di un passaggio, devi scrivere anche log personalizzati per il passaggio. Se gli utenti riscontrano un comportamento inatteso durante l'esecuzione del passaggio, i log possono aiutarli a capire cosa è successo.

Una voce di log utile ha due attributi:

  • Un chip contenente un link ipertestuale alla risorsa creata o aggiornata dal passaggio. Ad esempio, se il passaggio crea un documento Google, utilizza il chip per collegarti al documento Google creato.
  • Un messaggio di errore dettagliato che descrive il motivo per cui un passaggio non è stato eseguito e come risolvere il problema.

Il seguente esempio di codice mostra come il onExecuteFunctionCreateDocument() di un passaggio può registrare un'esecuzione riuscita e un errore nella scheda Attività:

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);
  }
}