Creazione di azioni
Un'azione specifica i task che si desidera eseguire attraverso il workflow. È possibile creare una nuova azione per il progetto utilizzando l'interfaccia della riga di comando di ThingWorx Flow.
Nell'immagine seguente vengono mostrate ad esempio le azioni in Gmail:
Per aggiungere una nuova azione o una nuova versione dell'azione al connettore, eseguire le operazioni descritte di seguito.
1. Dal prompt dei comandi, eseguire i comandi seguenti:
a. cd <project root directory>
b. flow add action <name>
 |
Il nome dell'azione non può contenere caratteri speciali eccetto un trattino (-). Ad esempio, servicename-action è un nome di azione.
|
L'esecuzione dei comandi precedenti crea una cartella nel percorso <DirProgetto>\action\action name.
◦ La cartella contiene una sottocartella denominata v1, vale a dire versione 1.
◦ La cartella v1 contiene i file descritti di seguito.
▪ File action.json - Contiene i metadati, ad esempio l'input e l'output dell'azione. Le informazioni che vengono visualizzate nel modulo dell'azione sono definite in questo file.
▪ File index.js - Contiene la logica e l'implementazione del codice dell'azione.
Per il comando di aggiunta azione 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: "."]
|
|
--logLevel, -1
|
Imposta il livello di registrazione.
|
[default: "info"]
|
|
-- artifactVersion, -v
|
Versione dell'elemento da testare.
|
[default: "v1"]
|
2. Impostare le proprietà di input e output nel file action.json, quindi aggiungere il codice JavaScript nel file index.js.
Di seguito vengono riportati il file action.json completo e la relativa descrizione:
{
"_id": "56b838816f724b0e259dae20",
"created_at": "2017-04-07T14:48:36.129Z",
"updated_at": "2017-04-07T14:48:36.129Z",
"uid": "actd47559da24fb85fae90b29099558e201cefa",
"name": "google-gmail-details-get",
"label": "Get Mail Details",
"input": {
"title": "Get Mail Details",
"type": "object",
"properties": {
"access_token": {
"title": "Authorize Gmail",
"type": "string",
"oauth": "gmail",
"minLength": 1
},
"id": {
"title": "Message ID",
"type": "string",
"minLength": 1,
"description": "Select/specify ID of the message of which details you wish to retrieve",
"lookup": {
"id": "g1",
"service": "gmail",
"auth": "oauth",
"enabled": true,
"searchable": true,
"dependencies": [
"access_token"
]
}
}
}
},
"output":
{
"title": "output",
"type": "object",
"properties": {
"id": {
"title": "id",
"type": "string",
"displayTitle": "ID"
},
"threadId": {
"title": "threadId",
"type": "string",
"displayTitle": "Thread ID"
},
"labelIds": {
"type": "array",
"title": "labelIds",
"displayTitle": "Label IDs",
"items": {
"type": "string"
}
},
"snippet": {
"title": "snippet",
"displayTitle": "Snippet",
"type": "string"
},
"historyId": {
"title": "historyId",
"displayTitle": "History ID",
"type": "string"
},
"internalDate": {
"title": "internalDate",
"displayTitle": "Internal Date",
"type": "string"
}
//schema truncated for clarity
},
"usage": {
"link": {
"href": "https://support.ptc.com/help/thingworx_hc/
thingworx_8_hc/activity/google-mail/get-mail-details",
"title": "Doc Link"
},
"html": "Fetch details of an email"
},
"version": "v1",
"icon": "gmail",
"act_type": "default",
"default_value": "",
"__v": 0,
"tags": [
"Gmail"
],
"category": "service"
}
"_id": "56b838816f724b0e259dae20",
"created_at": "2017-04-07T14:48:36.129Z",
"updated_at": "2017-04-07T14:48:36.129Z",
"uid": "actd47559da24fb85fae90b29099558e201cefa",
"name": "google-gmail-details-get",
"label": "Get Mail Details",
"input": {
"title": "Get Mail Details",
"type": "object",
"properties": {
"access_token": {
"title": "Authorize Gmail",
"type": "string",
"oauth": "gmail",
"minLength": 1
},
"id": {
"title": "Message ID",
"type": "string",
"minLength": 1,
"description": "Select/specify ID of the message of which details you wish to retrieve",
"lookup": {
"id": "g1",
"service": "gmail",
"auth": "oauth",
"enabled": true,
"searchable": true,
"dependencies": [
"access_token"
]
}
}
}
},
"output":
{
"title": "output",
"type": "object",
"properties": {
"id": {
"title": "id",
"type": "string",
"displayTitle": "ID"
},
"threadId": {
"title": "threadId",
"type": "string",
"displayTitle": "Thread ID"
},
"labelIds": {
"type": "array",
"title": "labelIds",
"displayTitle": "Label IDs",
"items": {
"type": "string"
}
},
"snippet": {
"title": "snippet",
"displayTitle": "Snippet",
"type": "string"
},
"historyId": {
"title": "historyId",
"displayTitle": "History ID",
"type": "string"
},
"internalDate": {
"title": "internalDate",
"displayTitle": "Internal Date",
"type": "string"
}
//schema truncated for clarity
},
"usage": {
"link": {
"href": "https://support.ptc.com/help/thingworx_hc/
thingworx_8_hc/activity/google-mail/get-mail-details",
"title": "Doc Link"
},
"html": "Fetch details of an email"
},
"version": "v1",
"icon": "gmail",
"act_type": "default",
"default_value": "",
"__v": 0,
"tags": [
"Gmail"
],
"category": "service"
}
Vedere la tabella seguente per le descrizioni delle proprietà nel file action.json.
|
Proprietà
|
Immettere le proprietà nel file JSON.
|
||
|---|---|---|---|
|
name
|
Nome dell'azione.
Nell'azione gmail-details-get, gmail è il nome del connettore e details-get è il nome dell'azione.
|
||
|
label
|
Etichetta visualizzata per l'azione.
|
||
|
input
|
Schema JSON per il modulo di input. Fare riferimento allo schema di input di esempio dopo la tabella.
I tipi di campo di input supportati sono any, string, boolean, array o object.
Lo schema di input definisce anche i meccanismi di autenticazione supportati dall'azione.
|
||
|
output
|
La proprietà definisce lo schema di output che questa azione può restituire quando viene eseguita.
I tipi di chiavi di output supportati sono String, Number, Boolean o Any.
|
||
|
version
|
Versione degli elementi. Quando viene creato tramite l'interfaccia della riga di comando di ThingWorx Flow, questo valore non deve essere modificato.
Per ulteriori informazioni, fare riferimento all'argomento Controllo delle versioni degli elementi del connettore.
|
||
|
tags
|
Matrice di stringhe con valori che determinano in quale raggruppamento visualizzare il connettore nell'interfaccia utente. In genere, è il nome visualizzato del connettore.
|
ThingWorx Flow supporta più schemi di autenticazione. Ad esempio, il codice riportato di seguito mostra i vari schemi di autenticazione (ad esempio Nessuna, Base e OAuth) nel connettore OData:
{
"type": "object",
"title": "Select an Authentication Scheme",
"oneOf": [
{
"type": "object",
"title": "None",
"id": "act1",
"properties": {
"odataUrl": {
"type": "string",
"title": "Odata Metadata Url",
"displayTitle": "Odata Metadata Url",
"minLength": 1,
"description": "Please provide the odata metadata url"
},
"entitySets": {
"type": "string",
"title": "Entity Set",
"minLength": 1
}
}
},
{
"type": "object",
"title": "Basic",
"id": "act2",
"properties": {
"connection": {
"title": "Odata Connection",
"type": "string",
"connection": "odata",
"minLength": 1
},
"entitySets": {
"type": "string",
"title": "Entity Set",
"minLength": 1
}
}
},
{
"type": "object",
"title": "OAuth",
"id": "act3",
"properties": {
"oauth": {
"title": "Odata OAuth",
"type": "string",
"oauth": "odata",
"minLength": 1,
"needUrl": true
},
"entitySets": {
"type": "string",
"title": "Entity Set",
"minLength": 1
}
}
}
]
}
"type": "object",
"title": "Select an Authentication Scheme",
"oneOf": [
{
"type": "object",
"title": "None",
"id": "act1",
"properties": {
"odataUrl": {
"type": "string",
"title": "Odata Metadata Url",
"displayTitle": "Odata Metadata Url",
"minLength": 1,
"description": "Please provide the odata metadata url"
},
"entitySets": {
"type": "string",
"title": "Entity Set",
"minLength": 1
}
}
},
{
"type": "object",
"title": "Basic",
"id": "act2",
"properties": {
"connection": {
"title": "Odata Connection",
"type": "string",
"connection": "odata",
"minLength": 1
},
"entitySets": {
"type": "string",
"title": "Entity Set",
"minLength": 1
}
}
},
{
"type": "object",
"title": "OAuth",
"id": "act3",
"properties": {
"oauth": {
"title": "Odata OAuth",
"type": "string",
"oauth": "odata",
"minLength": 1,
"needUrl": true
},
"entitySets": {
"type": "string",
"title": "Entity Set",
"minLength": 1
}
}
}
]
}
Il file index.js per l'azione deve esportare un oggetto con il metodo execute, come illustrato nel codice seguente:
module.exports = function () {
/*
This function will receive an input that conforms to the schema specified in
activity.json. The output is a callback function that follows node's error first
convention. The first parameter is either null or an Error object. The second parameter
of the output callback should be a JSON object that conforms to the schema specified
in activity.json
*/
this.execute = function (input, output) {
let outputData = {}
return output(null, outputData)
}
}
/*
This function will receive an input that conforms to the schema specified in
activity.json. The output is a callback function that follows node's error first
convention. The first parameter is either null or an Error object. The second parameter
of the output callback should be a JSON object that conforms to the schema specified
in activity.json
*/
this.execute = function (input, output) {
let outputData = {}
return output(null, outputData)
}
}
L'oggetto connection è disponibile come proprietà nell'oggetto input. Per accedere a questi campi, utilizzare espressioni quali input.connection.user_name.
Se il connettore utilizza OAuth, è possibile recuperare il token di accesso utilizzando l'espressione input.access_token.
Il video seguente illustra la creazione di una nuova azione utilizzando l'interfaccia della riga di comando di ThingWorx.
Ad esempio, per definire una nuova azione gmail-details-get per il proprio account Gmail, impostare la proprietà di input nel file action.json.
La figura riportata di seguito mostra la mappatura del codice delle proprietà di input e il modulo dell'azione che viene visualizzato nell'area di lavoro di ThingWorx Flow.
Vedere la tabella che segue per le descrizioni delle proprietà di input:
Proprietà | Immettere la proprietà di input come descritto di seguito | ||
|---|---|---|---|
title | Titolo del modulo utilizzato per accettare input nell'area di lavoro di ThingWorx Flow. | ||
type (obbligatoria) | Il tipo dell'oggetto di livello superiore deve sempre essere un object. | ||
properties | Raccolta di input necessari per eseguire l'azione. Ogni proprietà corrisponde ad un elemento dell'interfaccia utente nel modulo risultante: caselle di testo, elenchi a discesa, pulsanti di opzione e così via. Ogni input deve avere le seguenti proprietà: title, type, minLength (facoltativa) e description (facoltativa), format, minValue, maxValue, pattern, minItems, maxItems per il tipo di matrice e così via.
È possibile ordinare le proprietà sul modulo dell'azione utilizzando l'elemento propertyorder nello schema di input. Per rendere visibile un campo facoltativo nel modulo dell'azione, impostare questa proprietà su true. Ad esempio, visible=true | ||
lookup | Ogni input può avere una proprietà lookup che specifica che il campo deve essere completato con i valori cercati dalla ricerca descritta in precedenza. Per ogni lookup, è necessario specificare le proprietà seguenti: • id - Nome della funzione. • service - Nome della funzione di ricerca che viene chiamata quando si fa clic sulla freccia sulla ricerca.
• auth - Connessione o OAuth. • searchable - Se il valore è impostato su true, vengono attivati i meccanismi searbyById e searchByValue. • dependencies - Una matrice di stringhe, che specifica i campi che sono richiesti dalla ricerca. • onSelect - Nome della funzione di ricerca che viene chiamata quando si seleziona un elemento specifico nell'elenco visualizzato dalla ricerca. Viene in genere utilizzata per gestire lo schema del modulo. |
Analogamente, è necessario impostare le proprietà di output nel file action.json, quindi eseguire il file index.js. Per ulteriori informazioni ed esempi, fare riferimento all'Esercitazione B: esercitazione sull'SDK per i connettori di ThingWorx Flow.
Per la creazione di azioni, tenere presente quanto indicato di seguito.
• Tipi di campo di input supportati - Any, String, Boolean, Array, Object
• Tipi di campo di output supportati - String, Number, Boolean, Any
• minLength contrassegna il campo come obbligatorio.
• minItems contrassegna un campo della matrice come obbligatorio.
• maxItems imposta il limite massimo di un campo della.
• select2-{active:true} contrassegna il campo come campo select 2.
• Formato - date/datetime/time per aggiungere nel campo di input la selezione di date/date e time/time.
• ThingWorx Flow supporta oneOf.
• ThingWorx Flow attualmente supporta $ref che fa riferimento solo a locale.
Vedere la tabella che segue per le descrizioni delle proprietà di output:
Proprietà | Immettere la proprietà di output come descritto di seguito |
|---|---|
type (obbligatoria) | Il tipo dell'oggetto di livello superiore deve sempre essere un object. |
properties | Utilizzata per definire i campi di output restituiti dall'azione, che possono essere utilizzati nelle azioni successive. |
Per chiarezza, di seguito è riportato un esempio di proprietà di output formattata:
{
"title": "output",
"type": "object",
"properties": {
"id": {
"title": "id",
"type": "string",
"displayTitle": "ID"
},
"threadId": {
"title": "threadId",
"type": "string",
"displayTitle": "Thread ID"
},
"labelIds": {
"type": "array",
"title": "labelIds",
"displayTitle": "Label IDs",
"items": {
"type": "string"
}
},
"snippet": {
"title": "snippet",
"displayTitle": "Snippet",
"type": "string"
},
"historyId": {
"title": "historyId",
"displayTitle": "History ID",
"type": "string"
},
"internalDate": {
"title": "internalDate",
"displayTitle": "Internal Date",
"type": "string"
}
//schema truncated for clarity
}
"title": "output",
"type": "object",
"properties": {
"id": {
"title": "id",
"type": "string",
"displayTitle": "ID"
},
"threadId": {
"title": "threadId",
"type": "string",
"displayTitle": "Thread ID"
},
"labelIds": {
"type": "array",
"title": "labelIds",
"displayTitle": "Label IDs",
"items": {
"type": "string"
}
},
"snippet": {
"title": "snippet",
"displayTitle": "Snippet",
"type": "string"
},
"historyId": {
"title": "historyId",
"displayTitle": "History ID",
"type": "string"
},
"internalDate": {
"title": "internalDate",
"displayTitle": "Internal Date",
"type": "string"
}
//schema truncated for clarity
}
Per informazioni sull'SDK per le API che è possibile utilizzare nelle azioni, fare riferimento alla sezione SDK per i connettori di ThingWorx Flow.
Creazione di una guida contestuale
ThingWorx Flow dispone di un meccanismo per gli sviluppatori di connettori per fornire una guida contestuale per gli URL.
Come mostrato nell'immagine precedente, è possibile avviare la guida contestuale facendo clic sull'icona 
nella pagina dell'azione.
nella pagina dell'azione.Per la guida contestuale viene fornito un URL nell'attributo href dell'elemento usage.
"usage": {
"link": {
"href": "http://organization.com/help/topic",
"title": "connector:i18nkey-for-title"
},
"html": " connector:i18nkey-for-html"
}
"link": {
"href": "http://organization.com/help/topic",
"title": "connector:i18nkey-for-title"
},
"html": " connector:i18nkey-for-html"
}
L'attributo href può essere un qualsiasi URL assoluto che fornisce informazioni su un'azione. Inoltre, se il sito supporta pagine della guida specifiche della lingua, è prevista la possibilità di fornire un segnaposto per l'ID della lingua. Il server ThingWorx Flow sostituisce il segnaposto con la lingua preferita dall'utente. Il token locale può essere memorizzato nella posizione richiesta dal sito.
Alcuni esempi:
Se la lingua preferita dagli utenti è ad esempio il francese, ThingWorx Flow crea l'URL sostituendo <%=locale%> con fr: