JavaScript-Bibliothek agorum.task/js/task

Mithilfe dieser JavaScript-Bibliothek können Sie einmalige oder wiederkehrende Aufgaben planen und ausführen.

Die Bibliothek verhält sich ähnlich wie ein CronJob innerhalb von agorum core, mit dem Unterschied, dass das System den Task auch ausführt, wenn das System zum Ausführungszeitpunkt nicht läuft. In diesem Fall startet der Task zum nächstmöglichen Zeitpunkt.
Sie können zudem einen Task zu einem Startzeitpunkt in der Zukunft planen.
Einmalige sowie regelmäßige Ausführungen sind möglich.
Das System startet keine parallel zueinander laufenden Tasks.

Beispiel zum parallel laufenden Task
Ein Task benötigt 10 Minuten zur Bearbeitung, wird aber laut Skript jede Minute gestartet. Das System startet den nächsten Task erst, wenn der vorhergehende beendet ist. Dadurch können Sie mit try-catch Fehler / Probleme abfangen, und der agorum task läuft stabiler durch als etwa Worker.

Verwendung

Diese Bibliothek binden Sie stets am Anfang eines Skripts ein:

let task = require('/agorum/roi/customers/agorum.task/js/task');

agorum.task einrichten

Öffnen Sie den Ordner js in Ihrem Konfigurationsprojekt:

Eigene Dateien/Administration/customers/<Konfigurationsprojekt>/js

Erstellen Sie den Ordner task:

Eigene Dateien/Administration/customers/<Konfigurationsprojekt>/js/task

Erstellen Sie dort eine JavaScript-Datei und benennen Sie diese beliebig.
Programmieren Sie in diesem Skript die Aufgabe des agorum.task.

Beispiel: Ausgaben für das Log ausgeben (siehe Funktionen):
```
module.exports = {
  run: () => {
    console.log('mein task: ' + new Date());
  }
};
```

Öffnen Sie den Ordner deploy/<pre|post> Ihres Konfigurationsprojekts:

Eigene Dateien/Administration/customers/<Konfigurationsprojekt>/deploy/<pre|post>

Erstellen Sie dort eine JavaScript-Datei.

Definieren Sie den Startzeitpunkt, die CronTime und welches Skript für diesen agorum.task gestartet werden soll:

let task = require('/agorum/roi/customers/agorum.task/js/task');

//task.id('<eindeutiger-name-des-tasks>').cron('* * * * *').post('require(\'/agorum/roi/customers/<Konfigurationsprojekt>/js/task/<JavaScript-Datei>\').run();');

//Beispiel
task.id('testprojekt123.test.task').cron('* * * * *').post('require(\'/agorum/roi/customers/testprojekt123/js/task/test-task\').run();');

Klicken Sie auf RUN, um den agorum.task zu registrieren.

Ergebnis: Je nachdem, welche Einstellungen Sie vorgenommen haben (siehe Funktionen), startet der agorum.task automatisch.
Tipp: in dem hier vorgestellten Beispiel wird eine Konsolenausgabe erzeugt:
```
console.log('mein task: ' + new Date());
```
Diese Ausgabe erscheint im support tool unter Base System > Schaltfläche „Show Log“.

Anzeige von console.log() im support tool

agorum.task ändern

Öffnen Sie den Ordner js/task in Ihrem Konfigurationsprojekt:

Eigene Dateien/Administration/customers/<Konfigurationsprojekt>/js/task

Ändern Sie die JavaScript-Datei für den agorum.task nach Bedarf.
Hinweis: Wenn Sie den Namen des Tasks ändern, müssen Sie den Task mit dem alten Namen im Workspace löschen:
```
Eigene Dateien/Administration/workspace/agorum.task/tasks
```

Öffnen Sie den Ordner deploy/<pre|post> Ihres Konfigurationsprojekts:

Eigene Dateien/Administration/customers/<Konfigurationsprojekt>/deploy/<pre|post>

Überprüfen Sie die Einstellungen für die Ausführung dieses agorum.task:

let task = require('/agorum/roi/customers/agorum.task/js/task');

//task.id('<eindeutiger-name-des-tasks>').cron('* * * * *').post('require(\'/agorum/roi/customers/<Konfigurationsprojekt>/js/task/<JavaScript-Datei>\').run();');

//Beispiel
task.id('testprojekt123.test.task').cron('* * * * *').post('require(\'/agorum/roi/customers/testprojekt123/js/task/test-task\').run();');

Klicken Sie auf RUN, um den agorum.task neu zu registrieren.

Laufende agorum.tasks einsehen

Welche agorum.tasks gerade aktiv sind, können Sie im Workspace einsehen.

Achtung: Datenverlust bei Änderung eines agorum.tasks im Workspace. Änderungen an dieser Stelle werden durch ein Update des Systems wieder überschrieben. Ändern Sie niemals einen agorum.task im Workspace, sondern passen Sie den agorum.task im entsprechenden Konfigurationsprojekt an.

Öffnen Sie als Super-Administrator roi folgenden Pfad:
```
Eigene Dateien‎/Administration‎/workspace‎/agorum.task‎/tasks‎
```
Ergebnis: Alle aktiven agorum.tasks erscheinen.

In der Objekt-Info des jeweiligen agorum.tasks können Sie etwa den nächsten Startzeitpunkt oder den vorgegebenen Cron-Zeitplan einsehen.

agorum.task im Workspace sichtbar

Fehlermeldungen einsehen

Läuft Ihr agorum.task in einen Fehler, erscheinen diese Fehler im agorum core support tool unter Base System:

Fehler im agorum core support tool einsehen

Funktionen

id

Initialisiert die Task-Bibliothek für die Einrichtung des Tasks.

Syntax

let aTask = task.id('<eindeutiger-name-des-tasks>');

Parameter

Parameter	Beschreibung	Pflicht	Default-Wert
id	Definiert die ID des Tasks. Die ID muss systemweit eindeutig sein. Stellen Sie das Präfix des Projekts voran. Beispiel ihr.projekt.name.name-des-tasks	ja	–

Parameter

Beschreibung

Pflicht

Default-Wert

Definiert die ID des Tasks.

Die ID muss systemweit eindeutig sein.
Stellen Sie das Präfix des Projekts voran.

Beispiel
ihr.projekt.name.name-des-tasks

–

Beispiel

let task = require('/agorum/roi/customers/agorum.task/js/task');

let aTask = task.id('agorum.sample.task1');

Rückgabewerte

Sie erhalten eine Instanz des Tasks zurück, mit der Sie alle weiterführenden Funktionen aufrufen können.

Verwendung

Diese Funktion verwenden Sie zur Initialisierung.

Exceptions

Zu dieser Funktion existieren keine Exceptions.

time

Definiert optional ein Datum, ab wann dieser Task das erste Mal laufen soll.

Geben Sie kein Datum an oder lassen den Aufruf von time weg, läuft der Task sofort.

Syntax

aTask = aTask.time(new Date('2022-12-31'));

Parameter

Parameter	Beschreibung	Pflicht	Default-Wert
date	Definiert ein date-Objekt, d. h. ab wann der Task das erste Mal laufen soll.	nein	new Date()

Beispiel

let task = require('/agorum/roi/customers/agorum.task/js/task');

let aTask = task.id('agorum.sample.task1').time(new Date('2022-12-31'));

Rückgabewerte

Sie erhalten eine Instanz des Tasks zurück, mit der Sie alle weiterführenden Funktionen aufrufen können.

Verwendung

Diese Funktion verwenden Sie zum Setzen eines ersten Ausführungszeitpunkts für den Task.

Exceptions

Zu dieser Funktion existieren keine Exceptions.

cron

Definiert das Intervall, mit dem das System diesen Task ausführt.

Lassen Sie cron weg, führt das System den Task nur einmal aus und löscht ihn.

Syntax

aTask = aTask.cron('* * * * *);

Parameter

Parameter	Beschreibung	Pflicht	Default-Wert
schedule	Definiert das Ausführungsintervall, mit dem das System den Task ausführt. Die Angabe ist analog zu bekannten Crontabs (siehe Wikipedia-Suche nach Cron). Das System setzt das Intervall zurück und führt den Task nur einmalig aus, wenn der Wert null ist.	nein	null

Beispiel

let task = require('/agorum/roi/customers/agorum.task/js/task');

// Beispiel: Task ab dem 31.12.2022 ausführen und dann immer jede Minute
let aTask = task.id('agorum.sample.task1').time(new Date('2022-12-31')).cron('* * * * *');

Rückgabewerte

Sie erhalten eine Instanz des Tasks zurück, mit der Sie alle weiterführenden Funktionen aufrufen können.

Verwendung

Diese Funktion verwenden Sie zum Setzen eines Ausführungsintervalls.

Exceptions

Zu dieser Funktion existieren keine Exceptions.

post

Erstellt/ ändert die Einstellungen des definierten Tasks und gibt die JavaScript-Funktion mit, die dieser Task ausführen soll.

Der Task ist eingerichtet und wird vom System verarbeitet, sobald das System post aufruft.

Syntax

aTask.post('JavaScript-Code');

Parameter

Parameter	Beschreibung	Pflicht	Default-Wert
script	Definiert den JavaScript-Code, den der Task ausführt.	ja	–

Beispiel

let task = require('/agorum/roi/customers/agorum.task/js/task');

// Beispiel 1: Task erstellen und ab dem 31.12.2022 immer minütlich laufen lassen
task.id('agorum.sample.task1').time(new Date('2022-12-31')).cron('* * * * *').post('require(\'irgendeine-lib\').run();');

// Beispiel 2: Task erstellen und ab sofort minütlich laufen lassen
task.id('agorum.sample.task1').cron('* * * * *').post('require(\'irgendeine-lib\').run();');

// Beispiel 3: Task erstellen und einmalig ab sofort laufen lassen.
task.id('agorum.sample.task1').post('require(\'irgendeine-lib\').run();');

Der JavaScript-Code kann ein beliebiger agorum core-JavaScript Code sein.
Geben Sie diesen Code als String an.
Lagern Sie den Code in eine separate JavaScript-Datei aus, die Sie über require laden und ausführen, wie in den obigen Beispielen dargestellt.

Beispiel für require

// Datei /agorum/roi/customers/<Konfigurationsprojekt>/js/task/my-task.js
module.exports = {
  run: () => {
    // Etwas tun ...
  }
};

Rufen Sie den Task folgendermaßen auf:

let task = require('/agorum/roi/customers/agorum.task/js/task');

task.id('agorum.sample.task1').post('require(\'/agorum/roi/customers/agorum.sample/js/task/my-task\').run();');

Requiern Sie stets den vollständigen Pfad zur JavaScript-Datei.

Rückgabewerte

Diese Funktion liefert keine Rückgabewerte zurück.

Verwendung

Diese Funktion verwenden Sie, um den Task zu erstellen oder zu ändern und letztlich zu speichern, sodass das System diesen ausführen kann.

Exceptions

Zu dieser Funktion existieren keine Exceptions.

cancel

Löscht einen vorhandenen Task.

Syntax

task.id('eine-task-id').cancel();

Parameter

Zu dieser Funktion existieren keine Parameter.

Rückgabewerte

Diese Funktion liefert keine Rückgabewerte zurück.

Verwendung

Diese Funktion verwenden Sie, um einen vorhandenen Task abzubrechen.

Exceptions

Das System wirft eine Exception, wenn der Task mit der ID im System nicht existiert.