Therefore™ Referenz

Mit der Aktivität "Funktion aufrufen" können Sie Therefore™ Online anpassen. Sie wird wie alle anderen automatischen Workflow-Aktivitäten verwendet. Wenn Sie die Aktivität ausführen, wird eine HTTP(S) POST-Anfrage an den festgelegten URL gesendet. Dieser "Anfrage-URL" ist das einzige Pflichtfeld in der Konfiguration.

Das folgende Diagramm zeigt, wie die verschiedenen Komponenten miteinander interagieren.

Wenn die Therefore™ Workflow Engine die Aktivität "Funktion aufrufen" ausführt, wird eine HTTPS POST-Anfrage an die betreffende Funktion gesendet. Wenn der Aufruf erfolgreich ist, wird die Funktion ausgeführt und sie ruft wahrscheinlich über die Web-API den Therefore™-Server auf, um Dokumente, Indexdaten oder andere zusätzliche Informationen abzurufen, die sie für ihre Zwecke benötigt.

Bei der aufgerufenen Funktion kann es sich um eine Azure-Funktion, einen Webdienst oder eine beliebige ausführbare Datei handeln, die auf HTTPS POST-Anfragen reagieren kann. Die aufgerufene Funktion muss jedoch ein JSON-Objekt zurückliefern, das die Zeichenfolge "TheError" sowie entweder den Booleschen Wert "TheRoutingDone" oder die Ganzzahl "TheRetryAfterMin" enthält. Wenn die Funktion von Therefore™ entwickelt wurde, kann sie im Therefore™ Online-Azure-Abonnement gehostet werden.

Aus Sicherheitsgründen müssen von Kunden entwickelte Funktionen in ihrem eigenen Azure-Abonnement oder in ihrer eigenen Infrastruktur ausgeführt werden. Wie im Diagramm gezeigt, sind alle Verbindungen zwischen Therefore™ und der aufgerufenen Funktion HTTPS POST-Anfragen und (Web-) API-Aufrufe. Kundencode wird weder vom Serverdienst noch in der Therefore™ Online-Umgebung ausgeführt. Beim Ausführen von Web-API-Aufrufen gelten wie normal alle Zugriffsrechtprüfungen. Der mit der HTTPS-Anfrage bereitgestellte Zugriffstoken gilt nur für die aktuelle Workflow-Instanz. Aufgrund dieser Architektur ist das Anpassen von Workflows für den Gebrauch in Therefore™ Online sicher.

Bei der aufgerufenen Funktion kann es sich um eine Azure-Funktion, einen Webdienst oder eine beliebige Anwendung handeln, die öffentlich verfügbar ist und von einer HTTPS-Anfrage ausgelöst werden kann. Verbindlich sind dabei lediglich die folgenden Rückgabeparameter, welche die Funktion als JSON-Antwort senden muss:

•TheError: Verbindlicher Zeichenfolgewert. Wenn die Zeichenfolge nicht leer ist, wird sie im Workflow-Verlauf angezeigt. Die Instanz wird als fehlerhaft markiert, es sei denn, es wurde ein weiterer Versuch zu einem späteren Zeitpunkt angefordert.

•TheRetryAfterMin: Optionaler Ganzzahlwert. Kann verwendet werden, um einen erneuten Versuch von Therefore™ anzufordern.

Wenn der Parameter auf einen Wert größer als Null eingerichtet ist, verhält sich die "Funktion aufrufen" wie eine Warten-Aktivität und sendet eine neue Anfrage, nachdem die angegebene Anzahl von Minuten verstrichen ist (ungefähr). Wenn "TheError" gesetzt ist, wird dies als Warnung behandelt und es führt nicht dazu, dass die Workflow-Instanz als fehlerhaft markiert wird.

•TheRoutingDone: Verbindlicher Boolescher Wert, es sei denn, "TheRetryAfterMin" ist eingerichtet.

Kann auf "true" eingerichtet werden, um anzuzeigen, dass das Weiterleiten der Workflow-Instanz bereits über die Web-API-Funktion “FinishCurrentWorkflowTask” erfolgt ist. Wenn der Parameter auf "false" eingerichtet ist, leitet Therefore™ die Workflow-Instanz zur nächsten Aktivität weiter. Wenn "TheRetryAfterMin" eingerichtet ist, erfolgt die Weiterleitung noch nicht, d. h. der Parameter ist in diesem Fall optional. Bei jedem Funktionsaufruf sendet Therefore™ die folgenden Parameter mit der HTTPS-Anfrage als JSON an die Funktion:

•TheWebAPIUrl: Enthält die Servereinstellung "URL für Web-API", die auf der Registerkarte "XML Web Service" oder in den erweiterten Einstellungen konfiguriert werden kann. Wenn Sie Therefore™ Online verwenden, wird diese Einstellung bereits korrekt konfiguriert sein, aber sie kann auch leer sein.

•TheTenant: Der Name des aktuellen Mandanten. Wird leer sein, wenn das System nicht für Mehrfachmandanten eingerichtet ist.

•TheAccessToken: Ein JWT-Token, der für eine Verbindung zu Therefore™ über die Web-API verwendet werden kann.

Der Token gibt dem Benutzer "$TheWFSystem" Zugriff auf das Dokument bzw. die Akte, das/die mit der aktuellen Workflow-Instanz verknüpft ist, sowie Zugriff auf die aktuelle Workflow-Instanz und den Workflow-Token selbst. Mit den gewährten Zugriffsrechten ist es möglich, Änderungen am verknüpften Dokument, an der verknüpften Akte oder an mit der Akte verknüpften Dokumenten vorzunehmen. Die gewährten Zugriffsrechte gestatten auch das Weiterleiten der Workflow-Instanz an eine andere Aktivität. Es können jedoch keine neuen Dokumente oder Akten erstellt oder Abfragen ausgeführt werden. Außerdem können die Akte bzw. das Dokument, die mit der Workflow-Instanz verknüpft sind, oder die Workflow-Instanz selbst nicht gelöscht werden.

•TheInstanceNo: Die Instanznummer der aktuellen Workflow-Instanz.

•TheTokenNo: Die Tokennummer der aktuellen Workflow-Instanz.

•TheCaseNo: Die Nummer der mit der aktuellen Workflow-Instanz verknüpften Akte. Dieser Parameter ist nur für Akten-Workflows verfügbar.

•TheDocNo: Die Nummer des mit der aktuellen Workflow-Instanz verknüpften Hauptdokuments. Dieser Parameter ist nur für Dokument-Workflows verfügbar.

•TheSettings: JSON-Objekt (als Zeichenfolge übergeben) mit allen konfigurierten benutzerdefinierten Funktionseinstellungen.

Dies kann leer sein oder verwendet werden, um zusätzliche Parameter an die aufgerufene Funktion zu übergeben. Name und Wert der einzelnen Einstellungen können frei gewählt werden, aber Namen müssen entsprechend der JSON-Spezifikation eindeutig sein. Alle Werte werden als Zeichenfolgewerte behandelt und müssen, wenn erforderlich, innerhalb der Funktion konvertiert werden.

Wenn ein Funktionsschlüssel für Azure-Funktionen konfiguriert ist, enthält die HTTPS-Anfrage diese als "x-functions-key" in der Anfragekopfzeile.

Jegliche zusätzlichen Informationen müssen über die Therefore™ Web-API abgerufen werden. Dies kann entweder über den bereitgestellten JWT-Token oder durch Angabe eines Benutzernamens und eines Kennworts geschehen, wenn zusätzliche Rechte erforderlich sind. Beim Gebrauch von Azure-Funktionen können Anmeldeinformationen als "WebAPIUser" und "WebAPIPassword" in den Anwendungseinstellungen bereitgestellt werden. Wenn diese Einstellungen fehlen, verwendet die Funktion standardmäßig den JWT-Token.

Beachten Sie beim Schreiben einer Funktion, dass eine Antwort in unter 4 Minuten gesendet werden muss, da sonst eine Zeitüberschreitung für den Funktionsaufruf eintritt. Erwägen Sie außerdem, den Parameter "TheError" zu verwenden, um Ausnahmen zurückzuliefern und die Fehlerbehandlung zu vereinfachen.

Es gibt so gut wie keine Beschränkungen für die Anpassung.

Beim Gebrauch von Azure-Funktionen sind einige Beschränkungen von Azure selbst zu beachten. Diese gelten z. B. beim Laden von Abhängigkeiten aufgrund der PaaS (Platform as a Service)-Umgebung oder der Ausführungszeit (HTTPS-Timeout von 230 Sekunden) und anderen Implikationen, die das Ausführen Ihres Codes in Azure hat.

Die Timeout-Beschränkung könnte umgangen werden, indem Sie eine asynchrone Funktion schreiben, die eine Wiederholungsanfrage an Therefore™ sendet. Auf diese Weise könnte die Ausführung als getrennte Hintergrundaktivität fortgesetzt werden und die Ausgabe/Antwort wird bei der nächsten Wiederholungsanfrage an Therefore™ zurückgeliefert.

Aufgrund der Abhängigkeitsbeschränkungen in Azure kann die Therefore™-API nicht verwendet werden und Sie müssen anstelle dessen die Web-API verwenden. Diese Beschränkung könnte umgangen werden, indem Sie die von HTTPS ausgelöste Funktion anstelle dessen auf einem Computer mit einer Therefore™-Installation ausführen. Dabei ist die einzige Voraussetzung, dass der Computer von außerhalb erreichbar sein muss.