Creazione di trigger
Un trigger avvia un workflow quando nel sistema connesso si verifica un evento sottoscritto. Il trigger consente di automatizzare processi aziendali complessi e di evitare quindi di eseguire ogni volta il workflow manualmente.
Ad esempio, la figura seguente mostra un elenco di trigger che possono essere creati dal progetto.
Sono disponibili i due tipi di trigger riportati di seguito.
• Trigger polling
• Trigger webhook
Trigger polling
Questi trigger controllano periodicamente la disponibilità di aggiornamenti a intervalli regolari. Tutti i trigger polling sono contrassegnati da un'icona a forma di orologio nell'elenco dei trigger. Per creare trigger polling, attenersi alla procedura descritta di seguito.
1. Dal prompt dei comandi, eseguire i comandi seguenti:
a. cd <user project root directory>
b. flow add trigger -p
Per il comando di aggiunta trigger sono disponibili le opzioni seguenti:
Opzioni | Descrizione | Tipo di dati |
|---|---|---|
--version | Visualizza il numero di versione. | [booleano] |
--help | Visualizza la guida. | [booleano] |
--parentDir,-d | Directory padre del progetto. | [default: "."] |
--polling,-p | Indica che si tratta di un trigger polling. | [default: false] |
-- artifactVersion,-v | Versione dell'elemento da creare. | [default: "v1"] |
2. L'esecuzione del comando di aggiunta di trigger crea un file di metadati trigger.json, che contiene input e output, e un file JavaScript index.js, che contiene la logica del codice. Questi file vengono creati nella directory <DirProgetto>\trigger\poll\<nometrigger>\v1
 | Per default, viene creato un trigger webhook. Utilizzare l'opzione -p per creare un trigger polling. |
Per informazioni sulla formattazione dello schema di input e di output, fare riferimento alla nota nell'argomento
Creazione di azioni. Di seguito viene mostrata parte di uno schema semplificato.
Le opzioni nel file trigger.json sono descritte nella tabella seguente:
Opzioni | Descrizione |
|---|---|
type(required) | Il tipo di oggetto più esterno deve essere un oggetto. |
title (required) | Etichetta dell'elenco per consentire la selezione del trigger. |
description | Breve descrizione del trigger. |
properties | Utilizzata per definire i campi del modulo di input per la configurazione del trigger. Contiene le definizioni seguenti: • i campi di input da visualizzare nella finestra di configurazione del trigger • il nome dell'evento da visualizzare nell'elenco dei servizi di trigger. |
Una definizione di trigger inizia con un insieme di proprietà comuni, ad esempio authentication e customFilters, e prosegue con tutte le altre proprietà che sono comuni a tutti gli eventi di trigger. Tutte le proprietà dispongono di proprietà type, title e description. I sistemi esterni espongono in genere vari eventi. Gli eventi devono essere rappresentati in un blocco oneOf. Ogni oggetto all'interno del blocco oneOf corrisponde a un singolo evento. Se un sistema espone un singolo evento, l'utilizzo del blocco oneOf non è necessario.
La matrice oneOf contiene uno o più eventi. Ogni evento è un oggetto JSON. L'esempio riportato di seguito si applica a un servizio con 2 eventi Event1 e Event2. Ogni evento può richiedere un numero e un tipo di input diversi.
[{
"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"
}
}
}
]
Per ciascuno di questi eventi deve essere presente uno schema di output corrispondente nella proprietà output. Ad esempio, se sono presenti 2 eventi come mostrato in precedenza, l'output deve avere due schemi, uno per Event1 e uno per Event2 come nel codice seguente:
"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"
}
}
}
}
Il file index.js per i trigger polling presenta la struttura seguente:
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) {
}
Il codice per il metodo validate è simile al metodo execute. Fare riferimento all'esempio per vedere il codice.
Di seguito vengono descritti i metodi utilizzati nei trigger polling.
• Metodo execute - Chiamato periodicamente. L'intervallo è una configurazione del server ThingWorx Flow. Il metodo execute utilizza le informazioni di connessione ottenute tramite l'input, quindi si connette al sistema esterno e recupera i dati dal server ThingWorx Flow. Può utilizzare le API dell'oggetto options per memorizzare nella cache le informazioni sugli oggetti recuperati per determinare se sono disponibili nuove informazioni.
L'oggetto options include una proprietà meta utilizzata per mantenere le informazioni che sono disponibili nelle chiamate al metodo execute.
Per ulteriori informazioni sulle API comunemente disponibili, fare riferimento alla sezione
SDK per i connettori di ThingWorx Flow.
Il metodo setMeta dell'oggetto options può essere utilizzato per mantenere le informazioni sulle esecuzioni correnti o precedenti nel database. Ad esempio, può essere utilizzato per memorizzare la data e l'ora dell'ultima volta in cui è stato eseguito il metodo. Può essere anche utilizzato per memorizzare le informazioni per calcolare un valore delta tra i risultati precedenti e correnti. Il parametro output è un callback che segue la convenzione di utilizzare un oggetto errore come primo argomento della funzione del nodo. Se si verifica un errore, l'errore deve essere restituito come primo parametro. In caso contrario, il primo parametro deve essere un valore null e viene restituito un risultato conforme all'output come secondo parametro.
• Metodo validate - Chiamato dal server ThingWorx Flow prima di salvare un trigger nel database. Se la convalida non riesce, il trigger non viene salvato. Questo metodo può essere utilizzato per convalidare gli input, ad esempio una connettività con il servizio.
• Metodo activate - Chiamato quando un trigger esistente viene associato a un altro workflow. Nella maggior parte dei casi è sufficiente eseguire la convalida dal metodo. Di seguito è riportata un'implementazione di esempio del metodo activate:
function activate(input, options, output){
return output(null,true)
}
return output(null,true)
}
Per accedere all'evento selezionato del trigger, utilizzare la proprietà "event" dell'oggetto input (input.event). L'oggetto document contiene i campi di input del modulo. Il campo di input contiene le proprietà usuali come connection e access_token e tutti gli altri campi del modulo di input. Ad esempio, per accedere alla proprietà user_name che fa parte dell'oggetto connection, utilizzare un'espressione come la seguente: document.input.connection.user_name
Trigger webhook
Si tratta di trigger basati sulle sottoscrizioni. Le sottoscrizioni vengono create sugli eventi nel sistema connesso e un URL di webhook viene chiamato con il payload dell'evento quando l'evento si verifica nel sistema connesso. Per funzionare, il sistema connesso deve supportare i webhook per questo tipo di trigger. Invia i dati al motore di ThingWorx Flow in tempo reale, che consente al flusso di essere eseguito non appena l'evento specificato si verifica in un servizio o un'applicazione esterna.
È possibile creare trigger webhook utilizzando il comando seguente:
flow add trigger
L'esecuzione del comando crea i file descritti di seguito.
• Un file di metadati trigger.json che contiene input e output.
• Un file JavaScript index.js che contiene la logica del codice.
Questi file vengono creati nella directory <DirProgetto>\trigger\webhook\<nometrigger>\v1. Il processo per completare il file trigger.json per un trigger webhook è simile a quello per un trigger polling. Tuttavia, il codice differisce in modo significativo.
Il file index.js per i trigger webhook presenta la struttura seguente:
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) {
}
Di seguito vengono descritti i metodi utilizzati nei trigger webhook.
• Metodo activate - Può avere un'implementazione semplice senza opzioni come mostrato di seguito:
function activate(input, options, output) {
return output(null, true);
}
return output(null, true);
}
• Metodo register - Utilizzato per registrare l'URL del webhook fornito dal server ThingWorx Flow con il servizio esterno. Il metodo register riceve un oggetto document con una proprietà che contiene l'URL del webhook. Per l'oggetto document sono disponibili le proprietà seguenti:
◦ webhook_name - Nome dell'oggetto webhook.
◦ webhook - URL del webhook.
◦ input - Oggetto input contenente altre proprietà, ad esempio connection, access_token e tutti gli altri campi del modulo di input del trigger.
L'output del metodo viene memorizzato nell'oggetto document come proprietà "hook_response". In molti casi la proprietà hook_reponse contiene l'ID del trigger specificato dal sistema di destinazione. In genere, questo ID viene inviato nuovamente al sistema di destinazione quando si tenta di annullare la registrazione del webhook.
• Metodo unregister - Invia una richiesta di annullamento della registrazione che rimuove la sottoscrizione al webhook creata quando è stata eseguita la chiamata di registrazione ai sistemi connessi. Utilizzare document.hook_response e le relative proprietà per ottenere informazioni che possono essere utilizzate per annullare la registrazione.
Dopo aver scritto il codice completo per il trigger, è possibile procedere alla creazione di un'autenticazione per il trigger.
• Metodo execute - Utilizzarlo per le finalità indicate di seguito.
◦ Per convertire i dati del servizio dal modulo in un modulo adatto per l'utilizzo nei flussi oppure in un modulo che corrisponde allo schema di output definito.
◦ In alcuni casi, il servizio non fornisce informazioni sufficienti. In questi casi, il metodo può eseguire un'interrogazione sul servizio per ottenere informazioni aggiuntive.