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 ou de sortie. Toutefois, certaines situations nécessitent une variable qui ne peut être définie que lorsque l'utilisateur configure le flux, 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 pas être déterminé tant qu'un formulaire spécifique n'est pas sélectionné lors de la configuration du flux.

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": "STRING"
          }
       }
      ],
      "outputs": [
        {
          "id": "dynamic_resource_output",
          "description": "Dynamic Data",
          "cardinality": "SINGLE",
          "dataType": {
            "resourceType": {
              "workflowResourceDefinitionId": "dynamic_resource_id"
            }
          }
        }
      ],
      "onConfigFunction": "onDynamicVariableConfigFunction",
      "onExecuteFunction": "onDynamicVariableExecuteFunction"
    }
  }],
  "workflowResourceDefinitions": [{
    "id": "dynamic_resource_id",
    "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 flux, 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. Le variableId de returnOutputVariablesAction doit correspondre au id de la variable de sortie défini dans le fichier manifeste. La ressource dynamique se trouve sur l'objet d'événement de flux à l'adresse 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 la variable dynamique à partir de l'objet d'événement de flux, plus précisément resourceFieldsDefinitionRetrieval, et renvoie resourceFieldsDefinitionRetrievedAction, qui fournit les données au format JSON utilisable comme sortie pour les étapes ultérieures. Le resourceId doit correspondre au id d'un élément du tableau workflowResourceDefinitions[] défini dans le fichier manifeste.

  • onDynamicProviderFunction(), qui récupère la variable dynamique de l'objet d'événement de flux à e.workflow.resourceRetrieval.resourceReference.resourceId et renvoie le JSON en tant que sortie pour les étapes ultérieures.

Apps Script

function onDynamicVariableConfigFunction() {
  var card = {
    "sections": [
      {
        "widgets": [
          {
            "textInput": {
              "name": "dynamic_resource_input",
              "label": "Dynamic Resource Input",
            }
          },
        ]
      }
    ]
  };
  return {
    "action": {
      "navigations": [{
        "push_card": card
      }]
    }
  };
}

function onDynamicVariableExecuteFunction(){
  var dynamic_resource_id = uuidv4();
  return {
    "hostAppAction": {
      "workflowAction": {
        "returnOutputVariablesAction": {
          "variableValues": [{
            "variableId": "dynamic_resource_output",
            "variableData": {
              "resourceReferences" : [ dynamic_resource_id ]
            }
          }]
        }
      }
    }
  };
}

function onDynamicDefinitionFunction(e) {
  var input_value = e.workflow.resourceFieldsDefinitionRetrieval.inputs.dynamic_resource_input.stringValues[0];
  // input_value == "dynamic_resource_input"

  return {
    "hostAppAction": {
      "workflowAction": {
        "resourceFieldsDefinitionRetrievedAction": {
          "dynamicResourceDefinitions": [{
            "resourceId": "dynamic_resource_id",
            "fields": [{
                "selector":  "question_1",
                "displayText": "Question 1"
            },{
                "selector":  "question_2",
                "displayText": "Question 2"
            },{
                "selector":  "question_3",
                "displayText": "Question 3"
            }]
          }]
        }
      }
    }
  };
}

function onDynamicProviderFunction(e) {
  var resourceId = e.workflow.resourceRetrieval.resourceReference.resourceId;
  // resourceId == uuidv4();

  var workflowResourceDefinitionId = e.workflow.resourceRetrieval.resourceReference.resourceType.workflowResourceDefinitionId;
  // workflowResourceDefinitionId == "dynamic_resource_id"

  return {
    "hostAppAction": {
      "workflowAction": {
        "resourceRetrievedAction": {
          "resourceJson": JSON.stringify({
            "question_1": "Answer 1",
            "question_2": "Answer 2",
            "question_3": "Answer 3",
          })
        }
      }
    }
  };
}