Aktionen erstellen
Eine Aktion gibt die Aufgaben an, die der Workflow ausführen soll. Sie können eine neue Aktion für Ihr Projekt mit der ThingWorx Flow Befehlszeilenschnittstelle erstellen.
Beispielsweise werden die Aktionen in Gmail in der folgenden Abbildung dargestellt:
Gehen Sie wie folgt vor, um dem Konnektor eine neue Aktion oder eine neue Version der Aktion hinzuzufügen:
1. Führen Sie in der Eingabeaufforderung die folgenden Befehle aus:
a. cd <project root directory>
b. flow add action <name>
 |
Der Aktionsname darf keine Sonderzeichen mit Ausnahme eines Bindestrichs (-) enthalten. Beispielsweise ist "servicename-action" ein Aktionsname.
|
Durch Ausführen der obigen Befehle wird ein Ordner am folgenden Speicherort erstellt: <projectDir>\action\action name.
◦ Der Ordner hat einen Unterordner namens v1 (Version 1).
◦ Der Ordner v1 enthält die folgenden Dateien:
▪ Datei action.JSON – Enthält die Metadaten der Aktion, wie z.B. Eingabe und Ausgabe. In dieser Datei werden die im Aktionsformular angezeigten Informationen definiert.
▪ Datei index.js – Enthält die Logik und die Implementierung des Aktionscodes.
Folgende Optionen sind für den Befehl "add action" verfügbar.
|
Optionen
|
Beschreibung
|
Datentyp
|
|---|---|---|
|
--version
|
Zeigt die Versionsnummer an.
|
[Boolean]
|
|
--help
|
Zeigt die Hilfe an.
|
[Boolean]
|
|
--parentDir, -d
|
Das Elternverzeichnis für das Projekt.
|
[Standardwert: "."]
|
|
--logLevel, -1
|
Legt die Protokollebene fest.
|
[Standardwert: "info"]
|
|
-- artifactVersion, -v
|
Zu testende Artefaktversion.
|
[Standardwert: "v1"]
|
2. Legen Sie die Eingabe- und Ausgabeeigenschaften in der Datei action.json fest, und fügen Sie dann den JavaScript-Code zur Datei index.js hinzu.
Die fertige Datei action.json und ihre Beschreibung sind nachfolgend dargestellt:
{
"_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"
}
In der folgenden Tabelle finden Sie die Beschreibungen der Eigenschaften in der Datei action.json.
|
Eigenschaft
|
Geben Sie die Eigenschaften in die JSON-Datei ein.
|
||
|---|---|---|---|
|
name
|
Name der Aktion.
In der Aktion gmail-details-get ist gmail der Name des Konnektors und details-get der Name der Aktion.
|
||
|
label
|
Angezeigte Beschriftung für die Aktion.
|
||
|
input
|
JSON-Schema für das Eingabeformular. Ein Beispiel für das Eingabeschema finden Sie im Anschluss an die Tabelle.
Die unterstützten Eingabefeldtypen sind "any", "string", "boolean", "array" oder "object".
Das Eingabeschema definiert auch die Authentifizierungsmechanismen, die die Aktion unterstützt.
|
||
|
output
|
Die Eigenschaft definiert das Ausgabeschema, das diese Aktion zurückgeben kann, wenn sie ausgeführt wird.
Die unterstützten Ausgabeschlüsseltypen sind "string", "number", "boolean" oder "any".
|
||
|
version
|
Version der Artefakte. Bei Erstellung mit der ThingWorx Flow Befehlszeilenschnittstelle sollte dieser Wert nicht geändert werden.
Weitere Informationen finden Sie im Thema Versionsverwaltung von Konnektor-Artefakten.
|
||
|
tags
|
Ein Zeichenfolgen-Array mit Werten, die bestimmen, in welcher Gruppierung der Konnektor in der Benutzeroberfläche angezeigt wird. In der Regel ist dies der Anzeigenamen des Konnektors.
|
ThingWorx Flow unterstützt mehrere Authentifizierungsschemas. Beispiel: Der nachfolgende Code zeigt die unterschiedlichen Authentifizierungsschemata (None, Basic, OAuth) im OData-Konnektor:
{
"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
}
}
}
]
}
Die Datei index.js für die Aktion sollte ein Objekt mit der Methode execute, wie im nachfolgenden Code gezeigt, exportieren:
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)
}
}
Das Verbindungsobjekt steht als Eigenschaft für das Eingabeobjekt zur Verfügung. Verwenden Sie einen Ausdruck wie input.connection.user_name, um auf diese Felder zuzugreifen.
Verwendet der Konnektor OAuth, so können Sie das Zugriffs-Token mit dem Ausdruck input.access_token abrufen.
Das folgende Video zeigt die Erstellung einer neuen Aktivität mit der ThingWorx Befehlszeilenschnittstelle.
Um beispielsweise eine neue Aktion namens "gmail-details-get" für Ihr Gmail-Konto zu definieren, legen Sie die Eingabeeigenschaft in der Datei action.json fest.
Die Abbildung unten zeigt die Zuordnung Ihres Codes für die Eingabeeigenschaft und des Aktionsformulars, das in Ihrem ThingWorx Flow Zeichenbereich angezeigt wird.
In der folgenden Tabelle werden die Eingabeeigenschaften beschrieben:
Eigenschaft | Geben Sie die Eingabeeigenschaft wie unten beschrieben ein. | ||
|---|---|---|---|
title | Titel des Formulars, das verwendet wird, um Eingaben im ThingWorx Flow Zeichenbereich zu akzeptieren. | ||
type (erforderlich) | Der Typ des Objekts der obersten Ebene muss immer object sein. | ||
properties | Sammlung von Eingaben, die erforderlich sind, um die Aktion auszuführen. Jede Eigenschaft entspricht einem Benutzeroberflächenelement im resultierenden Formular: Textfelder, Dropdown-Menüs, Optionsfelder usw. Jede Eingabe muss die folgenden Eigenschaften haben: title, type, minLength (optional) und description (optional), format, minValue, maxValue, pattern, minItems, maxItems für Array-Typ usw.
Sie können die Eigenschaften im Aktionsformular mithilfe des propertyorder-Elements im Eingabeschema anordnen. Um ein optionales Feld im Aktionsformular sichtbar zu machen, legen Sie diese Eigenschaft auf "true" fest. Beispiel: visible=true | ||
lookup | Jede Eingabe kann eine lookup-Eigenschaft haben, die angibt, dass das Feld mit den Werten gefüllt werden soll, nach denen das oben beschriebene Lookup sucht. Für jedes lookup müssen Sie die folgenden Eigenschaften angeben: • ID – Name der Funktion. • service – Name der Lookup-Funktion, die aufgerufen wird, wenn Sie auf den Pfeil des Lookups klicken.
• auth – entweder "Connection" oder "OAuth". • searchable – Wenn der Wert auf "true" festgelegt wird, werden die Mechanismen "searbyById" und "searchByValue" aktiviert. • dependencies – Ein Zeichenfolgen-Array. Es gibt die Felder an, die für das Lookup erforderlich sind. • onSelect – Name der Lookup-Funktion, die bei Auswahl eines bestimmten Elements in der durch das Lookup angezeigten Liste aufgerufen wird. Dies wird in der Regel zur Verarbeitung des Formularschemas verwendet. |
Auf ähnliche Weise müssen Sie die Ausgabeeigenschaften der Datei action.json eingeben und dann die Datei index.js ausführen. Weitere Informationen und Beispiele finden Sie in Tutorial B: Tutorial zum SDK der ThingWorx Flow Konnektoren.
Beachten Sie beim Erstellen von Aktionen die folgenden Punkte:
• Unterstützte Eingabefeldtypen – any, string, boolean, array, object
• Unterstützte Ausgabeschlüsseltypen – string, number, boolean, any
• minLength kennzeichnet das Feld als erforderlich.
• minItems kennzeichnet ein Array-Feld als erforderlich.
• maxItems legt die Obergrenze für ein Array-Feld fest.
• select2 – {active:true} kennzeichnet das Feld als ein "select 2"-Feld.
• Format – date/datetime/time zum Hinzufügen einer date/date- und time/time-Auswahl im Eingabefeld.
• ThingWorx Flow unterstützt OneOf.
• ThingWorx Flow unterstützt derzeit $ref, das nur auf "local" verweist.
In der folgenden Tabelle werden die Ausgabeeigenschaften beschrieben:
Eigenschaft | Geben Sie die Ausgabeeigenschaft wie unten beschrieben ein. |
|---|---|
type (erforderlich) | Der Typ des Objekts der obersten Ebene muss immer object sein. |
properties | Wird zur Definition der Ausgabefelder verwendet, die von der Aktion zurückgegeben werden und in den nachfolgenden Aktionen verwendet werden können. |
Nachfolgend finden Sie ein Beispiel der Ausgabeeigenschaft, das zum besseren Verständnis formatiert wurde:
{
"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
}
Informationen zu einem SDK für APIs, die in Aktionen verwendet werden können, finden Sie im Abschnitt SDK der ThingWorx Flow Konnektoren.
Kontextbezogene Hilfe erstellen
ThingWorx Flow verfügt über einen Mechanismus, über den Konnektorentwickler kontextbezogene Hilfe für die URLs bereitstellen können.
Wie in der Abbildung oben dargestellt, kann die kontextbezogene Hilfe durch Klicken auf 
auf der Aktionsseite aufgerufen werden.
auf der Aktionsseite aufgerufen werden.Für die kontextabhängige Hilfe wird eine URL im Attribut href des usage-Elements bereitgestellt.
"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"
}
Das Attribut href kann eine beliebige absolute URL sein, die Hilfe für eine Aktion bereitstellt. Wenn die Website sprachspezifische Hilfeseiten unterstützt, gibt es außerdem die Möglichkeit, einen Platzhalter für die Sprach-ID anzugeben. Der ThingWorx Flow Server ersetzt den Platzhalter durch die Sprache, die vom Benutzer bevorzugt wird. Das Token locale kann je nach Erfordernis der Website platziert werden.
Hier einige Beispiele:
Wenn die bevorzugte Sprache des Benutzers beispielsweise Französisch ist, erzeugt ThingWorx Flow die URL, indem <%=locale%> durch fr ersetzt wird. Das Ergebnis ist der folgende Link: