Creare un passaggio

Questa guida spiega come creare un passaggio che gli utenti possono aggiungere a un flusso in Google Workspace Flows.

Un passaggio è un singolo passaggio nella sequenza di attività di un flusso. I passaggi non possono avviare un flusso.

Ad esempio, considera un passaggio che esegue operazioni aritmetiche. Chiede all'utente due valori e un'operazione matematica. Quindi esegue l'operazione matematica sui valori e restituisce il risultato.

Un utente configura il passaggio del calcolatore nell'ambito di un flusso.

Figura 1: un utente configura il passaggio del calcolatore nell'ambito di un flusso.

Per creare un passaggio, configuralo nel file manifest del componente aggiuntivo, scrivi la logica dell'applicazione nel codice del componente aggiuntivo di Google Workspace e implementa e testa il passaggio. Durante il test alpha, non pubblicare un componente aggiuntivo che estende i flussi.

Definisci il passaggio

Per configurare un passaggio, definiscilo nel file manifest e scrivi la logica dell'applicazione nel codice.

Definisci il passaggio nel file manifest

Nel file manifest, appsscript.json:

  1. Imposta onConfigFunction e onExecuteFunction sui nomi delle funzioni corrispondenti nel codice del componente aggiuntivo. In questo esempio, le funzioni vengono chiamate onConfigCalculate() e onExecuteCalculate().
    • onConfigFunction configura il passaggio. Se necessario, raccoglie i dati degli utenti necessari per eseguire il passaggio, ad esempio l'indirizzo a cui inviare un'email. Nell'esempio di questa guida, chiediamo due valori e un'operazione matematica.
    • onExecuteFunction esegue il passaggio. Se i dati sono stati raccolti dagli utenti, vengono passati a questa funzione. Se applicabile, restituisce un output. Nell'esempio di questa guida, restituisce il risultato di un calcolo matematico.

  2. Imposta input e output obbligatori, che consentono al passaggio di raccogliere i dati e inviarli ai passaggi successivi. In questo esempio, chiedi all'utente due valori e un'operazione matematica definita in inputs[]. Restituisci il risultato calcolato come definito in outputs[].

    Per saperne di più su input e output, consulta Variabili di input e Variabili di output. Per assicurarti che i flussi vengano eseguiti senza errori, convalida le variabili di input.

Ecco il file manifest per il passaggio Calcolatore:

JSON

{
  "timeZone": "America/Los_Angeles",
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "Calculator",
      "logoUrl": "https://www.gstatic.com/images/branding/productlogos/calculator_search/v1/web-24dp/logo_calculator_search_color_1x_web_24dp.png",
      "useLocaleFromApp": true
    },
    "flows": {
      "workflowElements": [
        {
          "id": "actionElement",
          "state": "ACTIVE",
          "name": "Calculate",
          "description": "Asks the user for two values and a math operation, then performs the math operation on the values and outputs the result.",
          "workflowAction": {
            "inputs": [
              {
                "id": "value1",
                "description": "value1",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "INTEGER"
                }
              },
              {
                "id": "value2",
                "description": "value2",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "INTEGER"
                }
              },
              {
                "id": "operation",
                "description": "operation",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "STRING"
                }
              }
            ],
            "outputs": [
              {
                "id": "result",
                "description": "Calculated result",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "INTEGER"
                }
              }
            ],
            "onConfigFunction": "onConfigCalculate",
            "onExecuteFunction": "onExecuteCalculate"
          }
        }
      ]
    }
  }
}

Successivamente, scrivi il codice di supporto definendo il passaggio nel codice.

Definisci il passaggio nel codice

Nel codice dell'applicazione:

  1. Scrivi onConfigFunction, denominato onConfigCalculate() in questo esempio. Quando gli utenti aggiungono il passaggio a un flusso, possono configurare gli aspetti del passaggio nel builder del flusso. Per raccogliere le informazioni richieste dall'utente, onConfigFunction definisce una scheda di configurazione.

    Le schede sono gli elementi di base per le interfacce utente nei componenti aggiuntivi. Le schede supportano un layout definito, elementi UI interattivi come pulsanti e contenuti multimediali avanzati come immagini. Le schede consentono di ottenere da un utente i dati necessari per l'esecuzione del passaggio, ad esempio un indirizzo email per l'invio di un'email.

    OnConfigFunction restituisce un oggetto RenderActions che contiene una scheda. Questa scheda definisce l'interfaccia utente in cui gli utenti impostano i dati del passaggio. In questo esempio, onConfigFunction crea una scheda che chiede all'utente due valori e un'operazione matematica.

  2. Scrivi onExecuteFunction denominato onExecuteCalculate() in questo esempio. Quando il passaggio viene eseguito in un flusso, viene eseguito OnExecuteFunction. Qualsiasi valore di input impostato dall'utente durante la configurazione, come definito in onConfigurationFunction, viene passato a OnExecuteFunction.

    Scrivi OnExecuteFunction() in modo che esegua in modo sincrono la sua attività utilizzando gli input forniti. Ricorda che OnExecuteFunction() deve restituire tutti gli output definiti nel manifest del flusso, altrimenti si verifica un errore.

Questo esempio di codice include una funzione di supporto, outputVariables(), che costruisce e invia le variabili fornite come output del passaggio.

Il passaggio è pronto per il test.

Ecco il codice per il passaggio Calcolatore:

Apps Script

/**
 * Generates and displays a configuration card for the sample calculation step.
 *
 * This function creates a card with input fields for two values and a drop-down
 * for selecting an arithmetic operation. The card also includes a "Save"
 * button to save the step configuration for the workflow.
 *
 * The input fields are configured to let the user select outputs from previous
 * workflow steps as input values using the `hostAppDataSource` property.
 */
function onConfigCalculate() {
  var card = {
    "sections": [
      {
        "header": "Step example: Calculate",
        "widgets": [
          {
            "textInput": {
              "name": "value1",
              "label": "First value",
              "hostAppDataSource" : {
                "workflowDataSource" : {
                  "includeVariables" : true
                }
              }
            }
          },
          {
            "selectionInput": {
              "name": "operation",
              "label": "Operation",
              "type": "DROPDOWN",
              "items": [
                {
                  "text": "+",
                  "value": "+",
                },
                {
                  "text": "-",
                  "value": "-",
                },
                {
                  "text": "x",
                  "value": "x",
                },
                {
                  "text": "/",
                  "value": "/",
                }
              ]
            }
          },
          {
            "textInput": {
              "name": "value2",
              "label": "Second value",
              "hostAppDataSource" : {
                "workflowDataSource" : {
                  "includeVariables" : true
                }
              }
            }
          }
        ]
      }
    ]
  };
  return {
    "action": {
      "navigations": [{
        "push_card": card
      }]
    }
  };
}

/**
 * Returns output variables from a step.
 *
 * This function constructs an object that, when returned, sends the
 * provided variable values as output from the current step.
 * The variable values are logged to the console for debugging purposes.
 */
function outputVariables(variableValues) {
  var renderAction =  {
    "hostAppAction" : {
      "workflowAction" : {
        "returnOutputVariablesAction" : {
          "variables" : variableValues
        }
      }
    }
  };
  console.log("renderAction: " + JSON.stringify(renderAction));
  return renderAction;
}

/**
 * Executes the calculation step based on the inputs from a flow event.
 *
 * This function retrieves input values and the operation from the flow event,
 * performs the calculation, and returns the result as an output variable.
 * The function logs the event for debugging purposes.
 */
function onExecuteCalculate(event) {
  console.log("output: " + JSON.stringify(event));
  var calculatedValue = 0;
  var value1 = event.workflow.actionInvocation.inputs["value1"].integerValues[0];
  var value2 = event.workflow.actionInvocation.inputs["value2"].integerValues[0];
  var operation = event.workflow.actionInvocation.inputs["operation"].stringValues[0];

  if (operation == "+") {
    calculatedValue = value1 + value2;
  } else if (operation == "-") {
    calculatedValue = value1 - value2;
  } else if (operation == "x") {
    calculatedValue = value1 * value2;
  } else if (operation == "/") {
    calculatedValue = value1 / value2;
  }
  return outputVariables([{
    "variableId": "result",
    "variableData": {
        "integerValues": [
          calculatedValue
        ]
      },
  }]);
}

Testare il passo

Per testare il passaggio, configura un deployment di test per il componente aggiuntivo, aggiungi il passaggio a un flusso ed esegui il flusso.

  1. Configura un deployment di test per il componente aggiuntivo:

    1. Apri il progetto di script nell'editor di Apps Script.
    2. Fai clic su Deployment > Verifica deployment.
    3. Fai clic su Installa.
    4. In basso, fai clic su Fine.

    Puoi consentire ad altri utenti di testare il componente aggiuntivo condividendo il progetto Apps Script con il loro account (è richiesto l'accesso in modifica). Quindi, chiedi agli utenti di seguire i passaggi precedenti.

    Una volta installato, il componente aggiuntivo è immediatamente disponibile in Flussi. Potresti dover aggiornare Flows prima che il componente aggiuntivo venga visualizzato. Devi anche autorizzare il componente aggiuntivo prima di utilizzarlo.

    Per scoprire di più sui deployment di test, consulta Installare un componente aggiuntivo non pubblicato.

  2. Apri Flussi.

  3. Crea un flusso che includa il passaggio:

    1. Fai clic su Nuovo flusso.
    2. Seleziona come inizia il flusso. Quando testi un passaggio, è consigliabile scegliere un trigger che puoi attivare tu stesso, ad esempio inviarti un'email. Se il passaggio richiede una variabile di input, configura la variabile di input come parte dell'output dello starter.
    3. Fai clic su Aggiungi passaggio. Seleziona il passaggio che hai creato o aggiornato, denominato Calcola.
    4. Configura il passaggio. Per il passaggio di calcolo, scegli due valori e un'operazione matematica. Il passaggio viene salvato automaticamente.
    5. Per testare l'output del passaggio, aggiungine un altro. Ad esempio, per aggiungere un output a un messaggio email, puoi aggiungere il passaggio Invia un messaggio di Gmail. In Messaggio, fai clic su Variabili e seleziona l'output del passaggio. Per il passaggio di calcolo, seleziona Variabili > Passaggio 2: risultato calcolato > Risultato calcolato. La variabile viene visualizzata come chip nel campo Messaggio.
    6. Fai clic su Attiva. Il flusso è pronto per essere eseguito.

  4. Esegui il flusso attivando il comando iniziale del flusso. Ad esempio, se il tuo flusso inizia quando ricevi un'email, invia un'email a te stesso.

  5. Verifica che il flusso venga eseguito come previsto. Controlla i log visitando la scheda Attività del generatore di flussi. Per scoprire come creare log personalizzati nella scheda Attività, consulta Log delle attività.