Création de déclencheurs
Un déclencheur lance un processus donné lorsqu'un événement souscrit se produit sur le système connecté. Les déclencheurs permettent ainsi d'automatiser des processus métier complexes, éliminant la nécessité de les exécuter manuellement à chaque fois.
La capture d'écran suivante vous montre les déclencheurs disponibles que vous pouvez configurer dans vos projets.
Il existe deux types de déclencheurs :
• les déclencheurs d'interrogation ;
• les déclencheurs webhook.
Déclencheurs d'interrogation
Ces déclencheurs vérifient les mises à jour périodiquement, par interrogation à intervalles réguliers. Tous les déclencheurs d'interrogation sont marqués d'une icône d'horloge dans la liste des déclencheurs. Pour créer des déclencheurs d'interrogation, procédez comme suit :
1. A l'invite de commande, exécutez les commandes suivantes :
a. cd <user project root directory>
b. flow add trigger -p
Les options suivantes sont disponibles pour la commande add trigger :
Options | Description | Type de données |
|---|---|---|
--version | Affiche le numéro de version. | [booléen] |
--help | Affiche l'aide. | [booléen] |
--parentDir,-d | Répertoire parent du projet. | [par défaut : "."] |
--polling,-p | Indique qu'il s'agit d'un déclencheur d'interrogation. | [par défaut : faux] |
-- artifactVersion,-v | Version de l'artefact à créer. | [par défaut : "v1"] |
2. L'exécution de la commande add trigger crée un fichier de métadonnées trigger.json qui contient l'entrée et la sortie, et un fichier JavaScript index.js qui contient la logique du code. Ces fichiers sont créés dans le répertoire <projectDir>\trigger\poll\<nom déclencheur>\v1.
 | Par défaut, c'est un déclencheur webhook qui est créé. Utilisez l'option -p pour créer un déclencheur d'interrogation. |
Pour plus d'informations sur le formatage des schémas d'entrée et de sortie, consultez la note figurant à la rubrique
Création d'actions. Un schéma tronqué et simplifié vous est présenté ci-dessous.
Les options du fichier trigger.json sont décrites dans le tableau ci-dessous :
Options | Description |
|---|---|
type (obligatoire) | L'objet doit être de type objet JSON. |
title (obligatoire) | Etiquette de la liste pour autoriser la sélection du déclencheur. |
description | Brève description du déclencheur. |
properties | Permet de définir les champs du formulaire d'entrée pour la configuration du déclencheur. Contient les définitions suivantes : • Champs d'entrée à afficher dans la fenêtre de configuration du déclencheur. • Nom de l'événement à afficher dans la liste du service du déclencheur. |
Une définition de déclencheur commence par un jeu de propriétés communes, comme authentication et customFilters ainsi que toute autre propriété commune à tous les événements de déclencheur. Toutes les propriétés possèdent un type, un titre et une description. Les systèmes externes exposent généralement un certain nombre d'événements, qui doivent être représentés dans un bloc oneOf. Chaque objet à l'intérieur du oneOf correspond à événement unique. Si le système expose un seul événement, le bloc oneOf n'est pas obligatoire.
Le tableau oneOf contient un ou plusieurs événements. Chaque événement est un objet JSON. L'exemple ci-dessous s'applique à un service qui a deux événements, Evénement1 et Evénement2. Notez que chaque événement peut nécessiter un nombre et un type d'entrées différents.
[{
"type": "object",
"title": "Event1",
"description": "Event 1 description",
"properties": {
"event": {
"type": "string",
"title": "Trigger",
"enum": [
"Event1"
],
"propertyOrder": 2,
"options": {
"hidden": true
}
},
"input_for_event1": {
"title": "input for event 1 ",
"minLength": 1,
"type": "string",
"propertyOrder": 3,
"description": "input required by event 1"
}
}
},
{
"type": "object",
"title": "Event2",
"description": "Event 2 description",
"properties": {
"event": {
"type": "string",
"title": "Trigger",
"enum": [
"Event1"
],
"propertyOrder": 4,
"options": {
"hidden": true
}
},
"input_for_event2": {
"title": "input for event 2 ",
"minLength": 1,
"type": "string",
"propertyOrder": 5,
"description": "input required by event 2"
}
}
}
]
"type": "object",
"title": "Event1",
"description": "Event 1 description",
"properties": {
"event": {
"type": "string",
"title": "Trigger",
"enum": [
"Event1"
],
"propertyOrder": 2,
"options": {
"hidden": true
}
},
"input_for_event1": {
"title": "input for event 1 ",
"minLength": 1,
"type": "string",
"propertyOrder": 3,
"description": "input required by event 1"
}
}
},
{
"type": "object",
"title": "Event2",
"description": "Event 2 description",
"properties": {
"event": {
"type": "string",
"title": "Trigger",
"enum": [
"Event1"
],
"propertyOrder": 4,
"options": {
"hidden": true
}
},
"input_for_event2": {
"title": "input for event 2 ",
"minLength": 1,
"type": "string",
"propertyOrder": 5,
"description": "input required by event 2"
}
}
}
]
Chacun de ces événements doit avoir un schéma de sortie correspondant dans la propriété de sortie. Par exemple, s'il existe deux événements comme indiqué ci-dessus, la sortie doit avoir un schéma pour Evénement1 et Evénement2, comme illustré ci-après :
"output": {
"Event1": {
"type": "object",
"properties": {
"opfield1": {
"type": "string",
"title": "Output field 1"
},
"opfield2": {
"type": "string",
"title": "Output field 2"
}
}
},
"Event2": {
"type": "object",
"properties": {
"opfield3": {
"type": "string",
"title": "Output field 3"
},
"opfield4": {
"type": "string",
"title": "Output field 4"
}
}
}
}
"Event1": {
"type": "object",
"properties": {
"opfield1": {
"type": "string",
"title": "Output field 1"
},
"opfield2": {
"type": "string",
"title": "Output field 2"
}
}
},
"Event2": {
"type": "object",
"properties": {
"opfield3": {
"type": "string",
"title": "Output field 3"
},
"opfield4": {
"type": "string",
"title": "Output field 4"
}
}
}
}
Le fichier index.js des déclencheurs d'interrogation présente la structure suivante :
module.exports = Trigger
Trigger.execute = function (input, options, output) {
}
Trigger.validate = function (input, options, output) {
}
Trigger.activate = (input, options, output) {
}
Trigger.execute = function (input, options, output) {
}
Trigger.validate = function (input, options, output) {
}
Trigger.activate = (input, options, output) {
}
Le code de la méthode validate est similaire à celui de la méthode execute. Reportez-vous à l'exemple pour voir le code.
Les méthodes utilisées dans les déclencheurs d'interrogation sont les suivantes :
• Méthode execute : appelée périodiquement. L'intervalle de temps utilisé est configuré au niveau du serveur ThingWorx Flow. La méthode execute utilise les informations de connexion de l'entrée, puis se connecte au système externe et récupère les données voulues sur le serveur ThingWorx Flow. Elle peut utiliser les API de l'objet option pour mettre en cache les informations sur les objets récupérés et déterminer si de nouvelles informations sont disponibles.
L'objet options possède une propriété meta utilisée pour conserver les informations disponibles via les appels de la méthode execute.
Pour plus d'informations sur les API disponibles, consultez la section
SDK des connecteurs ThingWorx Flow.
La méthode setMeta de l'objet d'options peut être utilisée pour conserver des informations sur les exécutions actuelles ou précédentes dans la base de données. Par exemple, elle peut être utilisée pour stocker l'heure de dernière exécution de la méthode. Elle permet également de stocker les informations en vue du calcul du delta entre les résultats précédents et les nouveaux résultats. Le paramètre output est un rappel qui suit la convention "erreur en premier" du noeud. Si une erreur se produit, elle doit être renvoyée comme premier paramètre. Dans le cas contraire, le premier paramètre doit être nul et un résultat conforme à la sortie sera renvoyé comme deuxième paramètre.
• Méthode validate : appelée par le serveur ThingWorx Flow avant l'enregistrement du déclencheur dans la base de données. Si la validation échoue, le déclencheur n'est pas enregistré. Cette méthode peut être utilisée pour valider les entrées, la connectivité avec le service.
• Méthode activate : appelée lorsqu'un déclencheur existant est associé à un autre processus. Dans la plupart des cas, il suffit d'exécuter validate depuis celui-ci. Voici un exemple d'implémentation de la méthode activate :
function activate(input, options, output){
return output(null,true)
}
return output(null,true)
}
Pour accéder à l'événement sélectionné du déclencheur, utilisez la propriété "event" de l'objet d'entrée (input.event). L'objet document contient les champs d'entrée du formulaire. Le champ d'entrée contient les propriétés habituelles, telles que connection et access_token, et tous les autres champs du formulaire d'entrée. Par exemple, pour accéder à la propriété user_name qui fait partie de l'objet de connexion, utilisez une expression telle que document.input.connection.user_name.
Déclencheurs webhook
Il s'agit de déclencheurs orientés abonnement. Des abonnements sont créés pour les événements du système connecté et une URL webhook est appelée avec la charge utile de l'événement lorsque l'événement se produit sur le système connecté. Le système connecté doit prendre en charge les webhooks pour que ce type de déclencheur fonctionne. Les données voulues sont envoyées en temps réel au moteur ThingWorx Flow, ce qui permet à votre flux de s'exécuter dès que l'événement spécifié se produit sur l'application ou le service externe.
Vous pouvez créer des déclencheurs webhook à l'aide de la commande suivante :
flow add trigger
L'exécution de la commande entraîne la création des éléments suivants :
• un fichier de métadonnées trigger.json qui contient les entrées et la sortie ;
• un fichier JavaScript index.js qui contient la logique du code.
Ces fichiers sont créés dans le répertoire <projectDir>\trigger\webhook\<nom déclencheur>\v1. Le processus pour renseigner le fichier trigger.json pour un déclencheur webhook répond à la même logique que pour un déclencheur d'interrogation. En revanche, son code diffère sensiblement.
Le fichier index.js du déclencheur webhook présente la structure suivante :
module.exports = Trigger;
Trigger.execute = function execute(input, data, output) {
}
Trigger.activate = function execute(input, data, output) {
}
Trigger.register = function register(document, callback) {
}
Trigger.unregister = function unregister(document, callback) {
}
Trigger.execute = function execute(input, data, output) {
}
Trigger.activate = function execute(input, data, output) {
}
Trigger.register = function register(document, callback) {
}
Trigger.unregister = function unregister(document, callback) {
}
Les méthodes utilisées dans les déclencheurs webhook sont les suivantes :
• Méthode activate : peut avoir une implémentation NOP simple, comme suit :
function activate(input, options, output) {
return output(null, true);
}
return output(null, true);
}
• Méthode register : utilisée pour enregistrer l'URL webhook fournie par le serveur ThingWorx Flow auprès du service externe. La méthode register reçoit un objet document doté d'une propriété qui contient l'URL webhook. Les propriétés de l'objet document sont les suivantes :
◦ webhook_name : nom de l'objet webhook.
◦ webhook : URL webhook.
◦ input : objet d'entrée qui contient d'autres propriétés telles que connection, access_token et tous les autres champs du formulaire d'entrée du déclencheur.
La sortie de la méthode est stockée sur l'objet document sous la forme d'une propriété "hook_response". Dans de nombreux cas, cette hook_reponse contient l'ID du déclencheur fourni par le système cible. En général, cet ID est renvoyé au système cible lors d'une tentative d'annulation de l'enregistrement de webhook sur ce système.
• Méthode unregister : envoie une requête de désenregistrement qui supprime l'abonnement webhook créé lors de l'enregistrement avec la méthode register auprès des systèmes connectés. Utilisez document.hook_response et ses propriétés pour obtenir les informations qui peuvent être utilisées pour annuler l'enregistrement.
Après avoir créé le code complet voulu pour votre déclencheur, vous pouvez créer une authentification pour celui-ci.
• Méthode execute : s'utilise comme suit :
◦ Pour convertir les données de service du formulaire en un formulaire utilisable dans les flux ou en un formulaire correspondant au schéma de sortie défini.
◦ Dans certains cas, le service ne fournit pas suffisamment d'informations. Dans de tels cas, la méthode peut interroger le service pour obtenir des informations supplémentaires.
Pour plus d'informations et pour obtenir des exemples de déclencheurs, reportez-vous au
Didacticiel sur le SDK des connecteurs ThingWorx Flow.