Cómo definir una variable dinámica

En esta guía, se explica cómo crear una variable dinámica.

Cuando sea posible, una variable se debe definir de forma estática en el archivo de manifiesto como una variable de entrada, una variable de salida o un recurso personalizado. Sin embargo, algunas situaciones requieren una variable que solo se puede definir cuando el usuario configura el agente, ya que la naturaleza de la entrada varía. Por ejemplo, la cantidad de preguntas y respuestas (y su contenido) de un formulario de Google no se puede determinar hasta que se selecciona un formulario específico durante la configuración del agente.

Las variables dinámicas tienen en cuenta estos casos, ya que te permiten definir una entrada que produce un conjunto dinámico de salidas en el archivo de manifiesto y en el código del paso.

Define la variable de salida en el archivo de manifiesto

En el archivo de manifiesto, sigue estos pasos:

  • En inputs[], especifica una variable de entrada que acepte un valor de entrada dinámico.

  • En outputs[], especifica una variable de salida que devuelva un conjunto dinámico de variables de salida. Asigna a este resultado un dataType de "workflowResourceDefinitionId": "dynamic_resource_id".

  • Define un recurso personalizado para controlar la variable dinámica. Especifica workflowResourceDefinitions con "resourceType": "DYNAMIC" y "providerFunction": "onDynamicProviderFunction". El id debe coincidir con el workflowResourceDefinitionId establecido en outputs[]. Para obtener más información sobre los recursos personalizados, consulta Cómo definir un recurso personalizado.

  • Establece dynamicResourceDefinitionProvider en el nombre de una función correspondiente en el código del paso, en este ejemplo onDynamicDefinitionFunction(), que define y devuelve una tarjeta de configuración que acepta un valor de entrada dinámico y devuelve un recurso personalizado.

JSON

"flows": {
  "workflowElements" : [{
    "id": "getDynamicVariable",
    "state": "ACTIVE",
    "name": "Get Dynamic Variable",
    "description": "Get Dynamic Variable",
    "workflowAction": {
    "inputs": [
      {
          "id": "dynamic_resource_input",
          "description": "Dynamic Resource Input",
          "cardinality": "SINGLE",
          "dataType": {
            "basicType": "INTEGER"
          }
       }
      ],
      "outputs": [
        {
          "id": "dynamic_resource_output",
          "description": "Dynamic Data",
          "cardinality": "SINGLE",
          "dataType": {
            "resourceType": {
              "workflowResourceDefinitionId": "resource_definition_1"
            }
          }
        }
      ],
      "onConfigFunction": "onDynamicVariableConfigFunction",
      "onExecuteFunction": "onDynamicVariableExecuteFunction"
    }
  }],
  "workflowResourceDefinitions": [{
    "id": "resource_definition_1",
    "name": "Dynamic Resource",
    "providerFunction": "onDynamicProviderFunction",
    "resourceType" : "DYNAMIC"
  }],
  "dynamicResourceDefinitionProvider" : "onDynamicDefinitionFunction",
}

Cómo definir la variable de salida en el código

El código del paso incluye estas funciones:

  • onDynamicVariableConfigFunction(), que compila y devuelve una tarjeta de configuración con un widget de entrada dinámico. El nombre de esta función debe coincidir con el valor de onConfigFunction() en el archivo de manifiesto. El nombre del widget de entrada dinámica debe coincidir con el id establecido en el archivo de manifiesto. Este widget de entrada dinámica permite a los usuarios establecer una variable dinámica cuando configuran su paso, como elegir un formulario de Google.
  • onDynamicVariableExecuteFunction(), que devuelve los datos de la variable dinámica como resultado cuando se ejecuta el paso. El nombre de esta función debe coincidir con el valor de onExecuteFunction() en el archivo de manifiesto. La clave de variableData en returnOutputVariablesAction debe coincidir con la variable de salida id establecida en el archivo de manifiesto. El recurso dinámico se encuentra en el objeto del evento en e.workflow.resourceFieldsDefinitionRetrieval. La entrada no puede hacer referencia a variables porque todas las entradas de un recurso dinámico deben estar disponibles en el momento de la configuración.
  • onDynamicDefinitionFunction(), que recupera los datos de las variables dinámicas del objeto de evento, específicamente resourceFieldsDefinitionRetrieval, y devuelve resourceFieldsDefinitionRetrievedAction, que proporciona el nombre de las variables de salida para los pasos posteriores y los selectores para que onDynamicProviderFunction() pueda proporcionar el valor correspondiente a cada variable de salida. El resourceId debe coincidir con el id de un elemento en el array workflowResourceDefinitions[] establecido en el archivo de manifiesto.

  • onDynamicProviderFunction(), que proporciona un valor para cada variable de salida usando selectores como claves a través del acceso a resourceId y workflowResourceDefinitionId.

Apps Script

function onDynamicVariableConfigFunction() {
  let section = CardService.newCardSection()
    .addWidget(
      CardService.newTextInput()
        .setFieldName("dynamic_resource_input")
        .setTitle("Dynamic Resource Input")
        .setHint("Input a Integer value between 1 and 3\(inclusive\) for corresponding number of output variables")
    );

  const card = CardService.newCardBuilder()
    .addSection(section)
    .build();

  return card;
}

function onDynamicDefinitionFunction(e) {
  console.log("Payload in onDynamicDefinitionFunction: ", JSON.stringify(e));
  var input_value = e.workflow.resourceFieldsDefinitionRetrieval.inputs.dynamic_resource_input.integerValues[0];

  let resourceDefinitions = AddOnsResponseService.newDynamicResourceDefinition()
    .setResourceId("resource_definition_1")
    .addResourceField(
      AddOnsResponseService.newResourceField()
        .setSelector("question_1")
        .setDisplayText("Question 1")
    );

  if (input_value == 2 || input_value == 3) {
    resourceDefinitions = resourceDefinitions
      .addResourceField(
        AddOnsResponseService.newResourceField()
          .setSelector("question_2")
          .setDisplayText("Question 2")
      );
  }
  if (input_value == 3) {
    resourceDefinitions = resourceDefinitions
      .addResourceField(
        AddOnsResponseService.newResourceField()
          .setSelector("question_3")
          .setDisplayText("Question 3")
      );
  }

  let workflowAction = AddOnsResponseService.newResourceFieldsDefinitionRetrievedAction()
    .addDynamicResourceDefinition(resourceDefinitions);

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

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

  return renderAction;
}

function onDynamicVariableExecuteFunction(e) {
  console.log("Payload in onDynamicVariableExecuteFunction: ", JSON.stringify(e));

  let workflowAction = AddOnsResponseService.newReturnOutputVariablesAction()
    .setVariableDataMap({
      "dynamic_resource_output": AddOnsResponseService.newVariableData()
        .addResourceReference("my_dynamic_resource_id")
    });

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

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

  return renderAction;
}

function onDynamicProviderFunction(e) {
  console.log("Payload in onDynamicProviderFunction: ", JSON.stringify(e));

  // resourceId == "my_dynamic_resource_id"
  var resourceId = e.workflow.resourceRetrieval.resourceReference.resourceId;
  // workflowResourceDefinitionId == "resource_definition_1"
  var workflowResourceDefinitionId = e.workflow.resourceRetrieval.resourceReference.resourceType.workflowResourceDefinitionId;

  const workflowAction = AddOnsResponseService.newResourceRetrievedAction()
    .setResourceData(
      AddOnsResponseService.newResourceData()
        .addVariableData("question_1", AddOnsResponseService.newVariableData().addStringValue("Answer 1"))
        .addVariableData("question_2", AddOnsResponseService.newVariableData().addStringValue("Answer 2"))
        .addVariableData("question_3", AddOnsResponseService.newVariableData().addStringValue("Answer 3"))
    );

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

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

  return renderAction;
}