Creare un passaggio

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

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. Esegue quindi l'operazione matematica sui valori e restituisce il risultato.

La scheda del passaggio del calcolatore di Workspace Studio che mostra due campi di input numerico e un menu a discesa per le operazioni aritmetiche.
Figura 1: un utente configura il passaggio della calcolatrice come parte 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, quindi esegui il deployment e testa il passaggio.

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 si chiamano 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, specifica due valori e un'operazione matematica.
    • onExecuteFunction esegue il passaggio. Se sono stati raccolti dati dagli utenti, questi vengono passati a questa funzione. Se applicabile, restituisce un output. Nell'esempio di questa guida, restituisce il risultato di un calcolo matematico.

  2. Imposta gli input e gli 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 della calcolatrice:

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": "calculatorDemo",
          "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"
          }
        }
      ]
    }
  }
}

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

Definisci il passaggio nel codice

Nel codice dell'applicazione, procedi nel seguente modo:

  1. Scrivi onConfigFunction, chiamata onConfigCalculate in questo esempio. Quando gli utenti aggiungono il passaggio a un flusso, possono configurare gli aspetti del passaggio nel builder di flussi. 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 i pulsanti e rich media come le 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 una scheda. Questa scheda definisce l'UI 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, chiamata onExecuteCalculate in questo esempio. Quando il passaggio viene eseguito in un flusso, viene eseguito onExecuteFunction. Tutti i valori di input impostati dall'utente durante la configurazione come definiti in onConfigFunction vengono passati a onExecuteFunction.

    Scrivi onExecuteFunction in modo che esegua in modo sincrono la sua attività utilizzando gli input forniti. 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 crea e invia le variabili fornite come output dal passaggio.

Il passaggio è pronto per il test.

Ecco il codice per il passaggio della calcolatrice:

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 input fields are configured to let the user select outputs from previous
 * steps as input values using the `hostAppDataSource` property.
 */
function onConfigCalculate() {
  const firstInput = CardService.newTextInput()
  .setFieldName("value1")
  .setTitle("First Value")
  .setHostAppDataSource(
    CardService.newHostAppDataSource()
      .setWorkflowDataSource(
        CardService.newWorkflowDataSource()
          .setIncludeVariables(true)
      )
  );
  const secondInput = CardService.newTextInput()
    .setFieldName("value2")
    .setTitle("Second Value").setHostAppDataSource(
      CardService.newHostAppDataSource()
        .setWorkflowDataSource(
          CardService.newWorkflowDataSource()
            .setIncludeVariables(true)
        )
    );
  const selectionInput = CardService.newSelectionInput()
    .setTitle("operation")
    .setFieldName("operation")
    .setType(CardService.SelectionInputType.DROPDOWN)
    .addItem("+", "+", false)
    .addItem("-", "-", true)
    .addItem("x", "x", false)
    .addItem("/", "/", false);

  const sections = CardService.newCardSection()
    .setHeader("Action_sample: Calculate")
    .setId("section_1")
    .addWidget(firstInput)
    .addWidget(selectionInput)
    .addWidget(secondInput)

  var card = CardService.newCardBuilder()
    .addSection(sections)
    .build();

  return 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(variableDataMap) {
const workflowAction = AddOnsResponseService.newReturnOutputVariablesAction()
  .setVariableDataMap(variableDataMap);

const hostAppAction = AddOnsResponseService.newHostAppAction()
  .setWorkflowAction(workflowAction);

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

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

  const variableDataMap = { "result": AddOnsResponseService.newVariableData().addIntegerValue(calculatedValue) };

  return outputVariables(variableDataMap);
}

Testa il passaggio

Per testare il passaggio, configura un deployment di test per il componente aggiuntivo, aggiungi il passaggio a un flusso e poi 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 > Deployment di test.
    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 di Apps Script con il loro account (è necessario 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 Flussi prima che venga visualizzato il componente aggiuntivo. Devi anche autorizzare il componente aggiuntivo prima di utilizzarlo.

    Per saperne 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 la modalità di avvio del flusso. Quando testi un passaggio, è consigliabile scegliere un comando iniziale che puoi impostare tu stesso, ad esempio inviarti un'email. Se il passaggio richiede una variabile di input, configura la variabile di input come parte dell'output del punto di partenza.
    3. Fai clic su Aggiungi passaggio. Seleziona il passaggio che hai creato o aggiornato, chiamato 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, aggiungi un altro passaggio. Ad esempio, per aggiungere l'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 impostando il punto di partenza del flusso. Ad esempio, se il flusso inizia quando ricevi un'email, inviati un'email.

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