Définir une variable dynamique

Ce guide explique comment créer une variable dynamique.

Dans la mesure du possible, une variable doit être définie de manière statique dans le fichier manifeste en tant que variable d'entrée, variable de sortie ou ressource personnalisée. Toutefois, certaines situations nécessitent une variable qui ne peut être définie que lorsque l'utilisateur configure l'agent, car la nature de l'entrée varie. Par exemple, le nombre de questions et de réponses (et leur contenu) pour un formulaire Google Forms ne peut être déterminé qu'une fois qu'un formulaire spécifique est sélectionné lors de la configuration de l'agent.

Les variables dynamiques tiennent compte de ces cas en vous permettant de définir une entrée qui produit un ensemble dynamique de sorties dans le fichier manifeste et dans le code de l'étape.

Définir la variable de sortie dans le fichier manifeste

Dans le fichier manifeste, procédez comme suit :

  • Dans inputs[], spécifiez une variable d'entrée qui accepte une valeur d'entrée dynamique.

  • Dans outputs[], spécifiez une variable de sortie qui renvoie un ensemble dynamique de variables de sortie. Attribuez à ce résultat un dataType de "workflowResourceDefinitionId": "dynamic_resource_id".

  • Définissez une ressource personnalisée pour gérer la variable dynamique. Spécifiez workflowResourceDefinitions avec "resourceType": "DYNAMIC" et "providerFunction": "onDynamicProviderFunction". Le id doit correspondre au workflowResourceDefinitionId défini dans outputs[]. Pour en savoir plus sur les ressources personnalisées, consultez Définir une ressource personnalisée.

  • Définissez dynamicResourceDefinitionProvider sur le nom d'une fonction correspondante dans le code de l'étape, dans cet exemple onDynamicDefinitionFunction(), qui définit et renvoie une fiche de configuration acceptant une valeur d'entrée dynamique et renvoyant une ressource personnalisée.

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

Définir la variable de sortie dans le code

Le code de l'étape inclut les fonctions suivantes :

  • onDynamicVariableConfigFunction(), qui crée et renvoie une fiche de configuration avec un widget d'entrée dynamique. Le nom de cette fonction doit correspondre à la valeur de onConfigFunction() dans le fichier manifeste. Le nom du widget d'entrée dynamique doit correspondre à l'id défini dans le fichier manifeste. Ce widget d'entrée dynamique permet aux utilisateurs de définir une variable dynamique lors de la configuration de leur étape, par exemple en choisissant un formulaire Google.
  • onDynamicVariableExecuteFunction(), qui renvoie les données de la variable dynamique en sortie lorsque l'étape s'exécute. Le nom de cette fonction doit correspondre à la valeur de onExecuteFunction() dans le fichier manifeste. La clé de variableData dans returnOutputVariablesAction doit correspondre à la valeur id de la variable de sortie définie dans le fichier manifeste. La ressource dynamique se trouve sur l'objet d'événement à e.workflow.resourceFieldsDefinitionRetrieval. L'entrée ne peut pas faire référence à des variables, car toutes les entrées d'une ressource dynamique doivent être disponibles au moment de la configuration.
  • onDynamicDefinitionFunction(), qui récupère les données de variables dynamiques à partir de l'objet d'événement, en particulier resourceFieldsDefinitionRetrieval, et renvoie resourceFieldsDefinitionRetrievedAction, qui fournit le nom des variables de sortie pour les étapes ultérieures, ainsi que les sélecteurs afin que onDynamicProviderFunction() puisse fournir la valeur correspondante à chaque variable de sortie. Le resourceId doit correspondre au id d'un élément du tableau workflowResourceDefinitions[] défini dans le fichier manifeste.

  • onDynamicProviderFunction(), qui fournit une valeur pour chaque variable de sortie à l'aide de sélecteurs comme clés en accédant à resourceId et à 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;
}