Criar uma etapa

Neste guia, explicamos como criar uma etapa que os usuários podem adicionar a um fluxo no Google Workspace Flows.

Uma etapa é uma única etapa em uma sequência de tarefas de um fluxo. As etapas não podem iniciar um fluxo.

Por exemplo, considere uma etapa que faz aritmética. Ele pede ao usuário dois valores e uma operação matemática. Em seguida, ele executa a operação matemática nos valores e gera o resultado.

Um usuário configura a etapa da calculadora como parte de um fluxo.

Figura 1:um usuário configura a etapa da calculadora como parte de um fluxo.

Para criar uma etapa, configure-a no arquivo de manifesto do complemento, escreva a lógica do aplicativo no código do complemento do Google Workspace e implante e teste a etapa. Durante o período Alfa, não publique um complemento que estenda os fluxos.

Definir a etapa

Para configurar uma etapa, defina-a no arquivo de manifesto e escreva a lógica do aplicativo dela em código.

Definir a etapa no arquivo de manifesto

No arquivo de manifesto, appsscript.json:

  1. Defina onConfigFunction e onExecuteFunction como os nomes das funções correspondentes no código do complemento. Neste exemplo, as funções são chamadas de onConfigCalculate() e onExecuteCalculate().
    • O onConfigFunction configura e define a etapa. Se necessário, coleta dados dos usuários necessários para executar a etapa, como o endereço para enviar um e-mail. No exemplo deste guia, pedimos dois valores e uma operação matemática.
    • onExecuteFunction executa a etapa. Se os dados foram coletados dos usuários, eles serão transmitidos para essa função. Se aplicável, retorna uma saída. No exemplo deste guia, ele gera o resultado de um cálculo matemático.

  2. Defina as entradas e saídas necessárias, o que permite que a etapa colete dados e os envie para etapas posteriores. Neste exemplo, peça ao usuário dois valores e uma operação matemática definida em inputs[]. Gere o resultado calculado conforme definido em outputs[].

    Para saber mais sobre entradas e saídas, consulte Variáveis de entrada e Variáveis de saída. Para garantir que os fluxos sejam executados sem erros, valide as variáveis de entrada.

Confira o arquivo de manifesto para a etapa "Calculator":

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"
          }
        }
      ]
    }
  }
}

Em seguida, escreva o código de suporte definindo a etapa no código.

Definir a etapa no código

No código do aplicativo, faça o seguinte:

  1. Escreva a onConfigFunction, chamada de onConfigCalculate() neste exemplo. Quando os usuários adicionam a etapa a um fluxo, eles podem configurar aspectos da etapa no criador de fluxos. Para coletar as informações necessárias do usuário, o onConfigFunction define um card de configuração.

    As fichas de informações são os elementos básicos das interfaces de usuário em complementos. Os cards são compatíveis com um layout definido, elementos interativos da interface, como botões, e mídia avançada, como imagens. Os cards são a maneira de receber dados de um usuário para que a etapa seja executada, como um endereço de e-mail para enviar uma mensagem.

    O OnConfigFunction retorna um objeto RenderActions que contém um card. Este card define a interface em que os usuários definem os dados da etapa. Neste exemplo, o onConfigFunction cria um card que pede ao usuário dois valores e uma operação matemática.

  2. Escreva o onExecuteFunction chamado onExecuteCalculate() neste exemplo. Quando sua etapa é executada em um fluxo, o OnExecuteFunction é executado. Todos os valores de entrada definidos pelo usuário durante a configuração, conforme definido em onConfigurationFunction, são transmitidos para OnExecuteFunction.

    Escreva OnExecuteFunction() para que ele execute de forma síncrona a tarefa usando as entradas fornecidas. Lembre-se de que OnExecuteFunction() precisa retornar todas as saídas definidas no manifesto do fluxo. Caso contrário, um erro vai ocorrer.

Este exemplo de código inclui uma função de suporte, outputVariables(), que cria e envia as variáveis fornecidas como saída da etapa.

Sua etapa está pronta para teste.

Confira o código da etapa "Calculadora":

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

Teste sua etapa

Para testar a etapa, configure uma implantação de teste para seu complemento, adicione a etapa a um fluxo e execute o fluxo.

  1. Configure uma implantação de teste para seu complemento:

    1. Abra o projeto de script no editor do Apps Script.
    2. Clique em Implantar > Testar implantações.
    3. Clique em Instalar.
    4. Na parte de baixo, clique em Concluído.

    Você pode permitir que outros usuários testem o complemento compartilhando o projeto do Apps Script com a conta deles (é necessário ter acesso de edição). Em seguida, peça para os usuários seguirem as etapas anteriores.

    Depois de instalado, o complemento fica disponível imediatamente no Flows. Talvez seja necessário atualizar o Flow antes que o complemento apareça. Você também precisa autorizar o uso do complemento.

    Para saber mais sobre implantações de teste, consulte Instalar um complemento não publicado.

  2. Abra "Fluxos".

  3. Crie um fluxo que inclua sua etapa:

    1. Clique em Novo fluxo.
    2. Selecione como o fluxo começa. Ao testar uma etapa, é recomendável escolher um gatilho que você possa acionar sozinho, como enviar um e-mail para você mesmo. Se a etapa exigir uma variável de entrada, configure-a como parte da saída do iniciador.
    3. Clique em Adicionar etapa. Selecione a etapa criada ou atualizada, chamada Calcular.
    4. Configure a etapa. Para a etapa de cálculo, escolha dois valores e uma operação matemática. A etapa é salva automaticamente.
    5. Para testar a saída da etapa, adicione outra. Por exemplo, para adicionar uma saída a uma mensagem de e-mail, você pode adicionar a etapa Enviar uma mensagem do Gmail. Em Mensagem, clique em Variáveis e selecione a saída da etapa. Para a etapa de cálculo, selecione Variáveis > Etapa 2: resultado calculado > Resultado calculado. A variável aparece como um ícone no campo Mensagem.
    6. Clique em Ativar. Seu fluxo está pronto para ser executado.

  4. Execute o fluxo ativando o início dele. Por exemplo, se o fluxo começar quando você receber um e-mail, envie um e-mail para si mesmo.

  5. Verifique se o fluxo é executado conforme o esperado. Para verificar os registros, acesse a guia Atividade do criador de fluxos. Para saber como criar registros personalizados na guia "Atividade", consulte Registros de atividades.