Cron (workflow/cron)

Mit dem Plugin workflow/cron lassen sich automatisierte Aufgaben einrichten, die vom System in einer bestimmten Abfolge ausgeführt werden. Eine einzelne Aktion wird Step bzw. Workflow-Step genannt, eine gesamte Abfolge von Aktionen ist ein Workflow. Ein Workflow besteht aus mindestens einem Step mit einer bestimmten Aktion und ist durch einen Namen gekennzeichnet.

Ein typischer Anwendungsfall ist der Bestellprozess nach einer Bestellung im Shop, bei dem eine Bestellbestätigung, Rechnung und Lieferschein erzeugt und versendet werden oder der Kunde über den Warenversand informiert wird.

Die Tabellen und Daten befinden sich in der Kachel "Workflow" und sind der Kachelgruppe "workflow" zugeordnet.

Zur Ausführung eines Workflows muss dieser als Datensatz in die Tabelle Workflow-Warteschlange überführt werden. Der Warteschlangen-Eintrag stellt somit die tatsächlich ausgeführte Instanz eines Workflows dar, während der Workflow selbst eher eine Art Vorlage und Konfiguration für den Ablauf und die Schritt-Einstellungen enthält.

Der Datensatz der Workflow-Warteschlange enthält (neben den Systemfeldern wie Sprache, Timestamps, Mandanten usw.) folgende Felder:

Feld	Beschreibung

Feld	Beschreibung
workflowQueueWorkflowID	Fremdschlüssel auf den ausgeführten Workflow aus der Tabelle workflow. Dieser Verweis stellt die Verbindung zur Konfiguration des Workflows mit dessen Steps her
workflowQueueID	Zusammen mit dem Identifier handelt es sich hierbei um eine ID zur eindeutigen Kennzeichnung der aktuellen WorkflowQueue-Instanz. Bei z.B. Shop-Workflows enthält dieses Feld die orderID oder die orderArticleID. Die semantische Bedeutung dieser ID ergibt sich aus dem Zusammenhang mit dem workflowQueueIdentifier, der eine Kennzeichnung enthält, um welche Art Workflow es sich handelt. Bei z.B. einer Shop-Bestellung wäre dies "shopOrder", oder "shopOrderArticle". Die Workflow-Warteschlange wird dadurch als Bestellung mit einer bestimmten Bestell-ID gekennzeichnet und kann dieser dadurch zugeordnet werden.
workflowQueueIdentifier	Siehe workflowQueueID
workflowQueueProcessing	Dieses Feld speichert den Ausführungszustand der Warteschlange. Wird dieser Workflow gerade ausgeführt enthält das Feld eine 1, andernfalls eine 0.
workflowQueueFinished	Wurde die gesamte WorkflowQueue erfolgreich ausgeführt steht in diesem Feld eine 1, andernfalls eine 0. WorkflowQueues mit 1 werden bei der Ausführung nicht mehr berücksichtigt und gelten als abgeschlossen.

Neben den aktuell ausgeführten Warteschlangen werden die aktuellen Workflow-Steps in der Tabelle workflowHistory erfasst.

Feld	Beschreibung

Feld	Beschreibung
workflowHistoryWorkflowStepID	Fremdschlüssel auf den gerade aktiven Workflow-Schritt (Tabelle workflowStep) einer Workflow-Warteschlange.
workflowHistoryStepDate	Enthält einen Timestamp (im UNIX-Format), zu dem der Workflow-Step gestartet wurde
workflowHistoryUserID	Enthält die DatensatzID auf den Benutzer, der den aktiven Workflow-Schritt gestartet hat
workflowHistoryUserType	Enthält den Tabellen-Identifier des Benutzers, der den aktiven Workflow-Schritt gestartet hat (z.B. shopUser im Fall eines Shop-Anwenders)

Zusammen mit der Tabelle workflowQueue enthält die workflowHistory somit alle notwendigen Informationen über die aktuell ausgeführten Workflows und dessen aktive Schritte.

Daher stellen die Tabellen in der Tabellengruppe "Cron" auch besondere Systemtabellen dar und sollten in der Regel nur von Technikern oder unter deren Aufsicht bearbeitet werden.

Die Tabelle "Workflow Historie" zeigt an welche Durchläufe für welche Workflows aktuell laufen, Fehler geworfen haben oder durchgelaufen sind.

Auf technischer Seite wird für die Verarbeitung und Taktung der Workflows ein Eintrag in der sogenannten Cron Tab benötigt, dieser sagt dem Server zu welcher Zeit und in welchem Rhythmus die Zeit-Steuerungs-Logik angestoßen werden soll.

Aufruf der Workflow Logik

php plugin/remote/brandbox/framework/src/entrypoint.php -endpoint=Cron -package=Workflow/Cron -host=your.host.com

Hinweis

Ein einmaliger Aufruf alle 5 Minuten bedeutet, dass alle 5 Minuten einmal geschaut wird ob ein Workflow Step in einem der Workflow Durchläufe verarbeitet werden kann. Sollte einer oder mehrere Steps als zur Verarbeitung bereit gefunden werden, wird pro Aufruf via Cron Tab nur ein einzelner Step bearbeitet. Das heißt im Umkehrschluss: um eine schnelle Bearbeitung von Durchläufen zu gewährleisten, sollten entweder mehrere Aufrufe (über mehrere Einträge im Cron Tab) stattfinden, oder die Taktrate im Cron Tab besonders niedrig eingestellt werden.

Workflow Steps

workflow/cron führt Schritte aus, indem es die runStep-Methode des workflowStep-Plugins aufruft. Die runStep-Methode wird in dem Interface workflow\cron\lib\stepInterface definiert.

Die runStep-Methode erhält:

stepResult: Datenaustauschobjekt
workflowQueue: Entiät
step: Entität
config: Array

Das Datenaustauschobjekt enthält lediglich zwei Eigenschaften.

isFinished entscheidet darüber ob ein Schritt erfolgreich war bzw. ausgeführt wurde.

message ist ein optionaler Wert, welcher in der UI ausgegeben wird, sofern befüllt. Wird message leer gelassen, wird eine Standardmeldung ausgegeben, abhängig davon ob isFinished true oder false ist.

Beispiel

Beispiel Step

/**
 * @param cron\lib\struct\StepResult $stepResult
 * @param cron\lib\entity\workflowQueue $workflowQueue
 * @param service\lib\entity\workflowStep $step
 * @param array $config
 */
public function runStep(cron\lib\struct\StepResult $stepResult, $workflowQueue, $step, $config) {
  $userID = $workflowQueue->workflowQueueID;
  $engineUser = $this->getEngineShopUser();
  $user = $engineUser->getShopUser($userID);

  $this->sendMailTemplate($config, $user);

  $stepResult->setIsFinished(true);
}