Trigger erstellen
Ein Trigger startet einen Workflow, wenn ein abonniertes Ereignis im verbundenen System auftritt. Dies ermöglicht es Ihnen, komplexe Geschäftsprozesse zu automatisieren, ohne den Workflow jedes Mal manuell ausführen zu müssen.
Die folgende Abbildung zeigt beispielsweise eine Liste von Triggern, die von Ihrem Projekt aus erstellt werden können.
Es gibt zwei Arten von Triggern:
Abruf-Trigger
Sie prüfen in regelmäßigen Abständen, ob Aktualisierungen vorliegen. Alle Abruf-Trigger sind in der Trigger-Liste mit einem Uhrsymbol gekennzeichnet. Gehen Sie wie folgt vor, um Abruf-Trigger zu erstellen:
1. Führen Sie in der Eingabeaufforderung die folgenden Befehle aus:
a. cd <user project root directory>
b. flow add trigger -p
Folgende Optionen sind für den Befehl "add trigger" 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: "."] |
--polling,-p | Gibt an, dass dies ein Abruf-Trigger ist. | [Standardwert: false] |
-- artifactVersion,-v | Version des zu erstellenden Artefakts. | [Standardwert: "v1"] |
2. Durch Ausführen des Befehls "add trigger" werden die Metadatendatei trigger.json, die Eingaben und Ausgaben enthält, sowie eine JavaScript-Datei namens index.js, welche die Codelogik enthält, erstellt. Diese Dateien werden im Verzeichnis <projectDir>\trigger\poll\<triggername>\v1 erstellt.
 | Standardmäßig wird der Webhook-Trigger erstellt. Verwenden Sie die Option -p, um einen Abruf-Trigger zu erstellen. |
Informationen zum Formatieren des Eingabe- und Ausgabeschemas finden Sie im Hinweis im Thema Aktionen erstellen. Nachfolgend ist ein abgeschnittenes und vereinfachtes Schema dargestellt.
Die Optionen in der Datei trigger.json werden in der folgenden Tabelle beschrieben:
Optionen | Beschreibung |
|---|---|
type (erforderlich) | Der Typ des äußersten Objekts muss ein Objekt sein. |
title (erforderlich) | Beschriftung der Liste, um die Auswahl des Triggers zu ermöglichen |
description | Kurze Beschreibung des Triggers |
Eigenschaften | Wird verwendet, um die Eingabeformular-Felder für die Trigger-Konfiguration zu definieren. Enthält die folgenden Definitionen: • Eingabefelder, die im Trigger-Konfigurationsfenster angezeigt werden sollen • Ereignisname, der in der Liste der Trigger-Dienste angezeigt werden soll |
Eine Trigger-Definition beginnt mit einer Reihe allgemeiner Eigenschaften wie "authentication" und "customFilters" sowie allen anderen Eigenschaften, die allen Trigger-Ereignissen gemeinsam sind. Alle Eigenschaften haben die Eigenschaften Typ, Titel und Beschreibung. Externe Systeme stellen in der Regel eine Reihe von Ereignissen bereit; die Ereignisse müssen in einem oneOf-Block dargestellt werden. Jedes Objekt innerhalb des oneOf entspricht einem einzelnen Ereignis. Wenn ein System ein einzelnes Ereignis anzeigt, ist der oneOf-Block nicht erforderlich.
Das Array oneOf enthält eines oder mehrere Ereignisse. Jedes Ereignis ist ein JSON-Objekt. Das nachfolgende Beispiel trifft auf einen Dienst mit zwei Ereignissen, Event1 und Event2, zu. Beachten Sie, dass für jedes Ereignis u.U. eine unterschiedliche Anzahl und ein unterschiedlicher Typ von Eingaben erforderlich ist.
[{
"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"
}
}
}
]
Für jedes dieser Ereignisse sollte ein entsprechendes Ausgabeschema in der Ausgabeeigenschaft vorhanden sein. Bei 2 Ereignissen, wie im obigen Beispiel, sollte die Ausgabe ein Schema für Event1 und Event2 enthalten:
"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"
}
}
}
}
Die Datei index.js für Abruf-Trigger hat die folgende Struktur:
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) {
}
Der Code für die validate-Methode ähnelt dem der execute-Methode. Sie können sich den Code im Beispiel ansehen.
Die folgenden Methoden werden in Abruf-Triggern verwendet:
• execute-Methode: Regelmäßige Abrufe. Das Intervall ist eine Konfiguration des ThingWorx Flow Servers. Die execute-Methode verwendet die Verbindungsinformationen aus der Eingabe, stellt dann eine Verbindung zum externen System her und ruft Daten vom ThingWorx Flow Server ab. Sie kann die APIs des options-Objekts zum Zwischenspeichern von Informationen über die abgerufenen Objekte verwenden, um zu bestimmen, ob neue Informationen verfügbar sind.
Das options-Objekt hat eine meta-Eigenschaft, die verwendet wird, um Informationen beizubehalten, die aufrufübergreifend für die execute-Methode verfügbar sind.
Weitere Informationen zu allgemein verfügbaren APIs finden Sie im Abschnitt SDK der ThingWorx Flow Konnektoren.
Die Methode setMeta des Optionsobjekts kann verwendet werden, um Informationen zu aktuellen oder vorherigen Ausführungen in der Datenbank beizubehalten. Beispielsweise kann der Zeitpunkt, zu dem die Methode zuletzt ausgeführt wurde, gespeichert werden. Es kann auch verwendet werden, um Informationen zur Berechnung eines Deltas zwischen den vorherigen und den aktuellen Ergebnissen zu speichern. Der Ausgabeparameter ist ein Callback, der die "Error-first"-Konvention des Knotens befolgt. Wenn ein Fehler auftritt, muss er als der erste Parameter zurückgegeben werden. Oder, der erste Parameter muss NULL sein, und ein Ergebnis, das dem Ausgabeschema entspricht, wird als zweiter Parameter zurückgegeben.
• validate-Methode – Wird vom ThingWorx Flow Server aufgerufen, bevor ein Trigger in der Datenbank gespeichert wird. Wenn die Validierung fehlschlägt, wird der Trigger nicht gespeichert. Diese Methode kann verwendet werden, um die Eingaben zu validieren, z.B. Konnektivität mit dem Dienst.
• activate-Methode: Wird aufgerufen, wenn ein bestehender Trigger einem anderen Workflow zugeordnet wird. In den meisten Fällen ist es ausreichend, die Validierung von diesem aus auszuführen. Eine Beispiel-Implementierung der activate-Methode sieht wie folgt aus:
function activate(input, options, output){
return output(null,true)
}
return output(null,true)
}
Verwenden Sie die Eigenschaft "event" des Eingabeobjekts (input.event ), um auf das ausgewählte Ereignis für den Trigger zuzugreifen. Das Dokumentobjekt enthält die Eingabefelder aus dem Formular. Das Eingabefeld enthält die herkömmlichen Eigenschaften wie "connection" und "access_token" sowie weitere Felder aus dem Eingabeformular. Verwenden Sie einen Ausdruck wie z.B. document.input.connection.user_name, um auf die Eigenschaft "user_name" zuzugreifen, die Teil des Objekts "connection" ist.
Webhook-Trigger
Dies sind Abonnement-basierte Trigger. Abonnements werden für Ereignisse im verbundenen System erstellt, und eine Webhook-URL wird mit der Ereignis-Payload aufgerufen, sobald das Ereignis im verbundenen System eintritt. Das verbundene System muss Webhooks unterstützen, damit diese Art von Triggern funktioniert. Der Trigger sendet Daten in Echtzeit an die ThingWorx Flow Engine. So kann der Fluss ausgeführt werden, sobald das angegebene Ereignis in einer externen Anwendung oder einem Dienst auftritt.
Sie können Webhook-Trigger mithilfe des folgenden Befehls erstellen:
flow add trigger
Durch Ausführen des Befehls wird Folgendes erstellt:
• Eine Metadatendatei trigger.json – Enthält Eingaben und Ausgaben.
• Eine JavaScript-Datei index.js – Enthält die Codelogik.
Diese Dateien werden im Verzeichnis <projectDir>\trigger\webhook\<triggername>\v1 erstellt. Der Prozess zum Fertigstellen der Datei trigger.json für einen Webhook Trigger ist ähnlich dem Prozess für einen Abruf-Trigger. Der Code unterscheidet sich jedoch beträchtlich.
Die Datei index.js für den Webhook-Trigger hat die folgende Struktur:
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) {
}
Die folgenden Methoden werden in Webhook-Triggern verwendet:
• activate-Methode: Kann eine einfache No-Op-Implementierung wie folgt haben:
function activate(input, options, output) {
return output(null, true);
}
return output(null, true);
}
• register-Methode: Wird verwendet, um die vom ThingWorx Flow Server bereitgestellte Webhook-URL beim externen Dienst zu registrieren. Die register-Methode erhält ein Dokumentobjekt mit einer Eigenschaft, die die Webhook-URL enthält. Das Dokumentobjekt hat die folgenden Eigenschaften:
◦ webhook_name: Der Name des Webhook-Objekts
◦ webhook: Die Webhook-URL
◦ input: Das Eingabeobjekt, das weitere Eigenschaften (z.B. connection, access_token) sowie weitere Felder aus dem Trigger-Eingabeformular enthält
Die Ausgabe für diese Methode wird im Dokumentobjekt als Eigenschaft "hook_response" gespeichert. Diese hook_reponse enthält in vielen Fällen die ID des Triggers, der vom Zielsystem bereitgestellt wurde. Für gewöhnlich wird diese ID zurück ans Zielsystem gesendet, wenn versucht wird, die Registrierung des Webhooks mit dem System aufzuheben.
• unregister-Methode: Sendet eine Anfrage zur Aufhebung der Registrierung, die das Webhook-Abonnement entfernt, das durch den Registrierungs-Call an die verbundenen Systemen erstellt wurde. Verwenden Sie document.hook_response und dessen Eigenschaften, um Informationen abzurufen, die zur Aufhebung der Registrierung verwendet werden können.
Nachdem Sie den vollständigen Code für den Trigger geschrieben haben, können Sie mit dem Erstellen einer Authentifizierung für den Trigger fortfahren.
• execute-Methode: Verwenden Sie diese wie folgt:
◦ Zum Konvertieren von Dienstdaten aus dem Format in ein Format, die für die Verwendung in Flüssen geeignet ist, oder in ein Format, das dem definierten Ausgabeschema entspricht.
◦ In einigen Fällen liefert der Dienst keine ausreichenden Informationen. In solchen Fällen können die Methode zusätzliche Informationen beim Dienst anfragen.
Weitere Informationen und Beispiele zu Triggern finden Sie im Tutorial zum SDK der ThingWorx Flow Konnektoren.