Création d'actions
Une action spécifie la tâche que vous souhaitez que le processus exécute. Vous pouvez créer une nouvelle action pour votre projet à l'aide de la CLI de ThingWorx Flow.
Par exemple, les actions disponibles pour Gmail sont celles illustrées ci-dessous :
Pour ajouter une nouvelle action ou une nouvelle version de l'action à votre connecteur, procédez comme suit :
1. A l'invite de commande, exécutez les commandes suivantes :
a. cd <project root directory>
b. flow add action <name>
 |
Les noms d'action ne peuvent pas contenir de caractères spéciaux, à l'exception du tiret (-). Par exemple, servicename-action est un nom d'action.
|
L'exécution des commandes ci-dessus crée un dossier à l'emplacement suivant : <projectDir>\action\nom action.
◦ Le dossier comporte un sous-dossier nommé v1 (version 1).
◦ Le dossier v1 contient les fichiers suivants :
▪ Fichier action.json : contient les métadonnées (entrée et sortie) de l'action. Les informations affichées dans le formulaire de l'action sont définies dans ce fichier.
▪ Fichier index.js : contient la logique et l'implémentation du code de l'action.
Les options suivantes sont disponibles pour la commande add action :
|
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 : "."]
|
|
--logLevel, -1
|
Définit le niveau de consignation.
|
[par défaut : "info"]
|
|
-- artifactVersion, -v
|
Version de l'artefact à tester.
|
[par défaut : "v1"]
|
2. Définissez les propriétés d'entrée et de sortie dans le fichier action.json, puis ajoutez le code JavaScript voulu dans le fichier index.js.
Le fichier action.json renseigné se présente comme suit :
{
"_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"
}
Consultez le tableau ci-dessous pour obtenir une description des propriétés du fichier action.json.
|
Propriété
|
Définissez les propriétés du fichier JSON
|
||
|---|---|---|---|
|
name
|
Nom de l'action.
Dans l'action gmail-details-get, gmail correspond au nom du connecteur et details-get correspond au nom à proprement parler de l'action.
|
||
|
label
|
Etiquette à afficher pour l'action.
|
||
|
input
|
Schéma JSON pour le formulaire d'entrée. Reportez-vous à l'exemple de schéma d'entrée après le tableau.
Les types de champ d'entrée pris en charge sont : any, string, boolean, array et object.
Par ailleurs, le schéma d'entrée définit les mécanismes d'authentification pris en charge par l'action.
|
||
|
output
|
Définit le schéma de sortie que cette action peut renvoyer lors de son exécution.
Les types de clé de sortie pris en charge sont : String, Number, Boolean et Any.
|
||
|
version
|
Version des artefacts. Lorsqu'elle est créée à l'aide de la CLI de ThingWorx Flow, cette valeur ne doit pas être modifiée.
|
||
|
tags
|
Tableau de chaînes avec des valeurs déterminant sous quel groupe le connecteur s'affiche sur l'interface utilisateur. En règle générale, il s'agit du nom affiché du connecteur.
|
ThingWorx Flow prend en charge plusieurs schémas d'authentification. Par exemple, le code suivant montre les différents schémas d'authentification (aucun, base, OAuth) utilisés dans le connecteur 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
}
}
}
]
}
Le fichier index.js de l'action doit exporter un objet avec la méthode execute, comme illustré dans le code ci-après :
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'objet de connexion est disponible sous la forme d'une propriété sur l'objet d'entrée. Pour accéder à ces champs, utilisez des expressions telles que input.connection.user_name.
Si votre connecteur utilise OAuth, vous pouvez récupérer le jeton d'accès à l'aide de l'expression input.access_token.
La vidéo suivante montre la création d'une nouvelle action à l'aide de la CLI ThingWorx.
Par exemple, pour définir une nouvelle action nommée gmail-details-get pour votre compte Gmail, vous devez définir les propriétés d'entrée dans le fichier action.json.
Le mappage entre votre code de propriétés d'entrée et le formulaire de l'action qui apparaît sur votre canevas ThingWorx Flow est illustré ci-dessous.
Consultez le tableau ci-après pour obtenir une description des propriétés d'entrée :
Propriété | Définissez la propriété d'entrée comme suit | ||
|---|---|---|---|
title | Titre du formulaire utilisé pour accepter les entrées sur le canevas ThingWorx Flow. | ||
type(obligatoire) | L'objet de niveau supérieur doit toujours être de type object. | ||
properties | Collection d'entrées requises pour exécuter l'action. Chaque propriété correspond à un élément de l'interface utilisateur du formulaire résultant : zones de texte, listes déroulantes, boutons d'option, etc. Chaque entrée doit posséder les propriétés suivantes : title, type, minLength (facultatif), et description (facultatif), format, minValue, maxValue, pattern, minItems et maxItems (pour les tableaux), etc.
Vous pouvez ordonner les propriétés sur le formulaire de l'action à l'aide de l'élément propertyorder du schéma d'entrée. Afin de rendre un champ facultatif visible dans le formulaire de l'action, définissez la propriété du même nom sur "true" (visible=true). | ||
lookup | Chaque entrée peut posséder une propriété lookup spécifiant que le champ doit proposer une liste de valeurs recherchées par le lookup en question. Pour chaque lookup, vous devez spécifier les propriétés suivantes : • id : nom de la fonction. • service : nom de la fonction de lookup appelée lorsque vous cliquez sur la flèche du champ de lookup.
• auth : connexion ou OAuth. • searchable : lorsque cette propriété est définie sur "true", les mécanismes searbyById et searchByValue sont activés. • dependencies : tableau de chaînes. Spécifie les champs requis par le lookup. • onSelect : nom de la fonction de lookup appelée lors de la sélection d'un élément spécifique dans la liste affichée par le lookup. Typiquement utilisée pour gérer le schéma de formulaire. |
De même, vous devez définir les propriétés de sortie voulues dans le fichier action.json, puis exécuter le fichier index.js. Pour plus d'informations et pour obtenir des exemples, consultez l'
Annexe B : Didacticiel sur les connecteurs ThingWorx Flow.
Gardez les points suivants à l'esprit lors de la création d'actions :
• Types de champ d'entrée pris en charge : Any, String, Boolean, Array, Object.
• Types de clé de sortie pris en charge : String, Number, Boolean, Any.
• minLength marque le champ comme obligatoire.
• minItems marque un champ de tableau comme obligatoire.
• maxItems définit la limite maximale d'un champ de tableau.
• select2—{active:true} marque le champ comme champ select2.
• Format : utilisez date/datetime/time pour ajouter un sélecteur de date/date et heure/heure dans le champ d'entrée.
• ThingWorx Flow prend en charge les blocs oneOf.
• ThingWorx Flow prend actuellement en charge les $ref pour les références locales uniquement.
Consultez le tableau ci-après pour obtenir une description des propriétés de sortie :
Propriété | Définissez la propriété de sortie comme suit |
|---|---|
type(obligatoire) | L'objet de niveau supérieur doit toujours être de type object. |
properties | Utilisée pour définir les champs de sortie renvoyés par votre action, utilisables dans les actions suivantes. |
Voici un exemple de propriétés de sortie formatées :
{
"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
}
Pour plus d'informations sur les API utilisables dans les actions, consultez la section
SDK des connecteurs ThingWorx Flow.
Création d'une aide contextuelle
ThingWorx Flow offre un mécanisme permettant aux développeurs de connecteurs de fournir une aide contextuelle à une adresse URL.
Comme illustré ci-dessus, l'aide contextuelle se lance lorsque l'utilisateur clique sur 
sur la page de l'action.
sur la page de l'action.Pour l'aide contextuelle, une URL est fournie dans l'attribut href de l'élément 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'attribut href peut prendre la valeur de n'importe quelle URL fournissant de l'aide sur une action. De plus, si le site propose des pages d'aide multilingues, il est possible de prévoir une marque de réservation pour l'ID de langue. Le serveur ThingWorx Flow remplace la marque de réservation par la langue préférée de l'utilisateur. Le jeton locale peut être placé comme requis par le site.
Exemples :
Si la langue préférée de l'utilisateur est le Français, ThingWorx Flow construit l'URL réelle en remplaçant <%=locale%> par fr, pour un lien final du type :