Worker im agorum core support tool verwenden

Mit einem Worker suchen und verarbeiten Sie Dateien automatisch. Was der Worker genau mit den Dateien machen soll, können Sie anpassen. Der Worker stimmt sich zeitlich selbst ab und fragt laufend das System ab.

Unterschied zwischen Worker und CronJob

Unser Entwicklungsteam zieht einen CronJob einem Worker vor, da ein Worker das System laufend mit Suchanfragen belastet. Ein CronJob wird dagegen zeitlich eingetaktet. Sie können diesen etwa einmal pro Stunde laufen lassen. Der CronJob führt dann intern eine Query aus, ähnlich wie es der Worker machen würde.

Wann sollten Sie einen Worker verwenden?
Wenn es zeitnah passieren soll und / oder wenn mehrere Threads parallel arbeiten können /sollen.

Wann sollten Sie einen CronJob verwenden?
Wenn es nicht zeitkritisch ist und es in Ordnung ist, dass die Abarbeitung sequenziell passiert.

Voraussetzungen

Sie müssen folgende Voraussetzungen erfüllen, um Worker verwenden zu können:

Sie können in JavaScript programmieren.
Sie kennen die undefined>agorum core smart search.
Sie kennen die wichtigsten JavaScript-Bibliotheken von agorum core, etwa common-objects.

Damit die Worker performant laufen, achten Sie auf folgende Punkte:

Globale Variablen könnten bereits aus vorherigen Durchläufen belegt sein.
Konstanten (const) dürfen nicht auf der obersten Ebene definiert werden, da diese sonst bei nachfolgenden Durchläufen als Neudefinition gewertet werden.
Mit require() eingebundene externe Skripte werden pro Kontext nur einmal geladen, auch wenn sie sich geändert haben.
Wird ein externes Skript verändert, muss der Worker per Schaltfläche Reset worker zurückgesetzt werden, damit sich die Änderungen auswirken.

Speicherort der Worker

Das System speichert die erstellten Worker automatisch in der MetaDB unter einem bestimmten Pfad.

So finden Sie die Worker:

Öffnen Sie links in der Seitenleiste Administration und dann MetaDB.
Öffnen Sie den Pfad:
```
/MAIN_MODULE_MANAGEMENT/workers
```

Anzahl an Workern und Systemressourcen

Hinweis: Die Anzahl an Worker ist abhängig von Ihren Systemressourcen. In der Regel reicht ein Thread pro Worker aus.

Anwendungsfälle

Anbei finden Sie drei mögliche Anwendungsfälle für einen Einsatz.

Nachträgliche Anpassung an Updates im System

Seit Wochen, Monaten oder auch Jahren werden Dokumente im System abgelegt. Doch wie bei jedem Digitalisierungsprozess werden eines Tages zwei neue Workflows etabliert:

Workflow für Fragebögen
Workflow für Feedbackbögen

Damit das System unterscheiden kann, für welches Dokument welcher Workflow greifen soll, wird ein neues Metadatum gesetzt.

Dieses neue Metadatum greift für alle neu im System abgelegten Dokumente. Doch die Benutzer wünschen sich, dass sie auch alte Dokumente mit dem neuen Workflow bearbeiten können. Da diesem das notwendige Metadatum fehlt, wird ein temporären Worker erstellt. Dieser sucht nach diesen Frage- und Feedbackbögen und setzt je das dazu passende Metadatum.

Sobald der Worker durchgelaufen ist, können unsere Benutzer die neuen Workflows auf die alten Dokumente anwenden.

Nachträgliche Ablage

Rechnungen sollen für das Finanzamt in einer dazu passenden Ordnerstruktur verlinkt werden. Anstatt Dokumente im Ablageprozess zu verlinken, können Sie auch einen Worker bauen, der nach diesen Rechnungen sucht und diese verlinkt.

Falsch angelegte Dokumente

Über Tage oder Monate hinweg werden Ordner und Dokumente mit einem falschen Namen oder einem falschen Metadatum abgelegt. Nach diesen fehlerhaften Einträgen kann gesucht und das zutreffende Objekt entsprechend abgeändert werden.

Einen Worker öffnen

Öffnen Sie links in der Seitenleiste Weitere Apps und dann support tool.
Wählen Sie links im Menü Workers.

Ergebnis: Zwei weitere Einträge (Actions und Sub Statistics) erscheinen. Über diesen Bereich können Sie Worker konfigurieren, starten, stoppen, löschen sowie Statistiken und Logs einsehen.

Eintrag „Actions“

Hier haben Sie die Möglichkeit, zwei verschiedene Worker zu erstellen:

QueryScript-Worker
Ein QueryScript-Worker findet in gut 95 % der Fälle Verwendung. Mit diesem bauen Sie eine Suchfunktion anhand von Metadaten auf. Diese Suche erkennt zu bearbeitende Dateien und reicht diese an ein JavaScript weiter.

So erstellen Sie einen QueryScript-Worker

ScriptWorker
Ein ScriptWorker wird selten verwenden. Bei diesem reicht die Suche nach Metadaten nicht aus, um die zu bearbeitenden Dateien zu finden. Stattdessen verwendet ein ScriptWorker ein JavaScript, um die gewünschten Objekte zu finden. Diese werden wiederum zur Bearbeitung an ein JavaScript weitergereicht.

So erstellen Sie einen ScriptWorker

Eintrag „SubStatictis“

Öffnen Sie den Bereich SubStatistics, finden Sie in weiteren Untereinträgen Folgendes:

Ihre selbst erstellten Worker
Im Standard mitgelieferte Worker
Dazugehörige Logausgaben

Die mitgelieferten Worker dienen zur allgemeinen Funktion des Systems, etwa der MetadataInheritor, der für die Vererbung von Metadaten benötigt wird.

Eintrag SubStatistics

Achtung: Systemschäden durch Löschen der im Standard mitgelieferten Worker. Entfernen Sie die bereits enthaltenen Worker nicht, da das System ansonsten nicht mehr ordnungsgemäß funktioniert. Erstellen Sie eigene Worker, anstatt die mitgelieferten zu löschen. Zur Unterscheidung können Sie etwa im JavaScript einen Kommentar setzen, aus dem hervorgeht, dass Ihr Unternehmen diesen Worker erstellt hat.

Worker zeitlich aufeinander abstimmen

Worker, egal ob QueryScript-Worker oder Script-Worker, suchen in regelmäßigen Zeitabständen nach Ihrem eigenen Arbeitsvorrat. Haben diese Worker viel zu tun, prüfen diese in schnellen Zeiteinheiten nach neuen Objekten, die bearbeitet werden müssen. Fiel dieser Arbeitsvorrat mehrmals leer aus, kann es bis zu 10 Sekunden dauern, ehe der Worker seine Suche erneut startet.

Einen Worker von einem Testsystem in ein Produktivsystem überführen

Sie können Worker direkt mit der export.yml exportieren.

Einen Worker pausieren

Setzen Sie die Threadanzahl (Concurrency) auf 0.

Einen Worker löschen / aktualisieren /bearbeiten

Sobald Sie einen eigenen Worker erstellt haben, bekommt dieser wie oben beschrieben einen eigenen Funktionsbereich. Öffnen Sie ihn und scrollen Sie ganz nach unten, sodass Sie sich unterhalb des (letzten) JavaScriptes befinden. Dort finden Sie drei Schaltflächen:

Schaltfläche „Update worker script“

Nehmen Sie Änderungen im Skript oder bei den Einstellungen im agorum core support tool vor, speichern Sie mit dieser Schaltfläche Ihre Änderungen. Das System führt einen Reset des Skripts durch, sodass der Worker mit dem neuen Skript läuft.

Ausgeschlossen ist eine Namensänderung. In diesem Fall erstellen Sie einen neuen Worker und löschen den aktuellen.

Schaltfläche „Reset worker“

Wenn ein JavaScript ausgeführt wird, wird es kompiliert, bevor es startet. Damit der Kompiler nicht jedes Mal ausgeführt wird, wird das kompilierte Skript gecacht und gestartet.

Die Schaltfläche löscht den Cache für dieses Skript, sodass das Skript anschließend neu geladen wird. Damit werden auch require-Verweise auf ein anderes Skript aus dem Cache gelöscht und bei erneutem Ausführen wieder neu kompiliert.

Wird der Worker zurückgesetzt, wird auch der aktuell verwendete JavaScript-Kontext verworfen.

Schaltfläche „Stop and remove worker“

Diese Schaltfläche stoppt den Worker und löscht ihn anschließend.

QueryScriptWorker

Dieser Worker führt regelmäßig eine Suche nach Metadaten aus und übergibt das Ergebnis pro gefundenem Objekt an ein JavaScript. Jeder Aufruf des Skripts wird in einer Transaktion abgearbeitet.

Einen QueryScriptWorker erstellen

Öffnen Sie links in der Seitenleiste Weitere Apps und dann support tool.
Wählen Sie links im Menü Workers > Actions > QueryScript.
Passen Sie die Einstellungen des Workers an.
Speichern Sie den angelegten Worker und testen Sie, ob der Worker die gewünschte Funktion ausführt.

Ein Worker kann etwa wie folgt aufgebaut werden:

Einen QueryScriptWorker erstellen

Einstellungen des QueryScriptWorkers

Einstellung	Beschreibung	Beispiel
Name	Definiert den Namen des Workers.	–
Concurrency	Definiert die Anzahl der verwendeten Threads. Setzen Sie den Wert auf 0, ist dieser Worker inaktiv.	–
Hidden Objects	Definiert, dass der Worker auch versteckte Objekte wie die Historie und Versionierung bearbeitet.	–
Query	Definiert, welche Objekte durch den Worker bearbeitet werden sollen. Die Suche bauen Sie anhand der undefined>agorum core smart search und der Nutzung von etwa Wichtige Metadaten auf. Anhand von Metadaten und ggf. bestimmte Metadatenwerte fangen Sie somit Objekte ab.	*Nach dem Ordner incoming* suchen inpath:${ID:/agorum/roi/Files/incoming} Hinweis:** Sie können auch Metadaten ausschließen, um einen Endlos-Loop zu vermeiden. Hierfür können Sie eine NOT-Formulierung anlegen, etwa: identifier: kundenakte acmf_kundenname:* NOT acmf_kundennamerl:* Metadaten werden hierbei oft als eine Art Status eingesetzt. Tipp: Kopieren Sie eine Query vorab in das agorum core information center, um zu überprüfen, dass Sie die gewünschten Objekte finden. Schreiben Sie Metadaten stets klein.
Properties	Definiert, welche Attribute / Metadaten des durch die Query gefundenen Objekts der Worker an das JavaScript übergibt. Im Standard reicht die UUID, da Sie mit dieser auf alle weiteren Eigenschaften der Objekte zugreifen. Mehrere Attribute trennen Sie mit einem Semikolon (;).	uuid Erklärung Hier wird die uuid des Objekts an das Workerscript übergeben. In dem JavaScript verwenden Sie diese durch den Aufruf data.uuid.
JavaScript	Fügt das JavaScript ein.	–
Save as a new worker	Speichert den Worker.	–

JavaScript-Beispiel zum QueryScriptWorker

In dem folgenden Beispiel wird ein JavaScript für einen QueryScriptWorker gezeigt, der ein Objekt aus einem Ordner herausnimmt und in einen anderen Ordner ablegt. Zum Einsatz kommt die JavaScript-Bibliothek common-objects.

/* global sc, data */ 
let objects = require('common/objects');

// Objekt anhand der UUID finden 
let object = objects.tryFind(data.uuid);

// Ausgabeordner für die Objekte 
let target = objects.find('/agorum/roi/Files/done');

// Überprüfen, ob das Objekt noch da ist    
if (object) {     
  // Etwas mit dem Objekt machen...   

  // Objekt aus dem Ordner "incoming" herausnehmen, sodass es nicht mehr in diesem Ordner zu finden ist    
  // remove from all parents     
  objects.remove(object);          

  // Objekt in den Ordner "done" ablegen     
  objects.add(object, [ target ]);   
}

ScriptWorker

Beim ScriptWorker wird der Arbeitsvorrat durch ein frei definierbares Skript produziert, dem Producer. Es können daher nicht nur Suchanfragen abgearbeitet werden, sondern etwa auch der Inhalt von Ordnern oder Einträge in einer CSV-Datei.

Einen ScriptWorker erstellen

Öffnen Sie links in der Seitenleiste Weitere Apps und dann support tool.
Wählen Sie links im Menü Workers > Actions > ScriptWorker.
Passen Sie die Einstellungen des Workers an.
Speichern Sie den angelegten Worker und testen Sie, ob der Worker die gewünschte Funktion ausführt.

Einen ScriptWorker erstellen

Einstellungen des ScriptWorkers

Einstellung	Beschreibung
Name	Definiert den Namen des Workers.
Concurrency	Definiert die Anzahl der verwendeten Threads. Setzen Sie den Wert auf 0, ist dieser Worker inaktiv.
Producer	Beim ScriptWorker wird der Arbeitsvorrat durch ein frei definierbares Skript produziert. Definieren Sie an dieser Stelle, welche Objekte das System wiederfinden soll, bevor diese dem Consumer-Skript überreicht werden. Als Rückgabewert des Producers wird ein Array erwartet, dessen Elemente den aktuellen Arbeitsvorrat darstellen. Ein Element kann entweder eine ID oder ein JavaScript-Objekt sein, das mindestens die Eigenschaft "id" besitzt. Diese Elemente werden durch das Worker-Framework aufgeteilt und einzeln als Parameter data an die Consumer-Threads übergeben. Der Wert von id wird außerdem vom Worker-Framework verwendet, um Duplikate automatisch auszufiltern.
Consumer	Definiert im Consumer-Skript, was Sie mit den gefundenen Objekten umsetzen möchten. Dieses Skript entspricht dem JavaScript-Feld des QueryWorkers.
JavaScript	Fügt das JavaScript ein.
Save as a new worker	Speichert den Worker.

limit und idle im Producer

Dem Producer werden vom Worker-Framework zwei Parameter übergeben.

Parameter	Beschreibung
limit (number)	Definiert, wie viele Elemente erzeugt werden. Der Wert ist unter anderem von der konfigurierten Threadanzahl und der aktuellen Länge der Warteschlange abhängig. Bei diesem Wert handelt es sich um einen Richtwert. Darüber hinaus gelieferte Elemente werden nicht verworfen. Es empfiehlt sich folgender Ansatz für die beste Performance: Sind insgesamt weniger als <limit>-Elemente vorhanden, werden alle Elemente zurückgegeben. Sind insgesamt gleich viel oder mehr als <limit>-Elemente vorhanden, werden mindestens <limit>-Elemente zurückgegeben, aber der Wert wird nicht stark überschritten. Gehören die Elemente etwa zu zusammenhängenden Stapeln, sollte der letzte Stapel noch vollständig zurückgegeben und erst danach gestoppt werden.
idle (boolean)	Definiert, dass seit dem letzten Aufruf des Producers keine weiteren Elemente verarbeitet wurden. Dieser Parameter kann für Optimierungen, die diese Information benötigen, eingesetzt werden, um etwa gewisse Schritte zu überspringen.

Parameter

Beschreibung

limit (number)

Definiert, wie viele Elemente erzeugt werden.

Der Wert ist unter anderem von der konfigurierten Threadanzahl und der aktuellen Länge der Warteschlange abhängig.
Bei diesem Wert handelt es sich um einen Richtwert. Darüber hinaus gelieferte Elemente werden nicht verworfen.

Es empfiehlt sich folgender Ansatz für die beste Performance:

Sind insgesamt weniger als <limit>-Elemente vorhanden, werden alle Elemente zurückgegeben.
Sind insgesamt gleich viel oder mehr als <limit>-Elemente vorhanden, werden mindestens <limit>-Elemente zurückgegeben, aber der Wert wird nicht stark überschritten. Gehören die Elemente etwa zu zusammenhängenden Stapeln, sollte der letzte Stapel noch vollständig zurückgegeben und erst danach gestoppt werden.

idle (boolean)

Definiert, dass seit dem letzten Aufruf des Producers keine weiteren Elemente verarbeitet wurden.

Dieser Parameter kann für Optimierungen, die diese Information benötigen, eingesetzt werden, um etwa gewisse Schritte zu überspringen.

Die Parameter idle und limit werden nicht eingestellt, sondern vorgegeben. Daran kann sich das Producer-Skript orientieren, wenn es darum geht, wie viele Arbeitseinheiten es erzeugen sollte, damit die Consumer-Threads weiterhin beschäftigt sind.

Beispiel für die Abarbeitung der Elemente eines Ordners mithilfe des Fileworkflows

Producer
Der Producer erzeugt ein Array aus den ersten <limit>-Objekten im Ordner /agorum/roi/Files/Eingang. Das Producer-Skript wird jedes Mal im selben JavaScript-Kontext aufgerufen.

/* global sc, limit, idle */

let objects = require('common/objects');

objects.find('/agorum/roi/Files/Eingang').items().slice(0, limit).map(item => ({
  id: item.ID,
  object: item
}));

Consumer
Der Consumer ruft für das übergebene Objekt den Fileworkflow auf.

/* global sc, data */

let workflows = require('common/workflows');

workflows.start('FileWorkflow2', data.object);