Hintergrundaktivitäten konfigurieren

Hintergrundaktivitäten sind laufende oder abgeschlossene Prozesse in agorum core. Solche Hintergrundaktivitäten laufen etwa, wenn ein Benutzer einen ZIP-Anhang entpackt. Sie können die Hintergrundaktivitäten verfolgen und feststellen, welchen Fehler das System meldet.

Typische Anwendungsfälle stellen etwa Migrationen oder Änderungen von großen Datensätzen dar. Die Funktion ist somit für große Datenmengen optimiert.

Sie konfigurieren Hintergrundaktivitäten mithilfe der JavaScript-Bibliothek background. Sie ist als Werkzeug für beliebige Aktivitäten gedacht, die überwacht werden sollen.

• Die JavaScript-Bibliothek background wird sowohl für manuell gestartete Skripte als auch für etwa CronJobs oder Tasks verwendet, um den Status/Fortschritt von länger laufenden Aktivitäten zu beobachten und diese ggf. abbrechen zu können.
• Mit der JavaScript-Bibliothek kann auch ein Aktiver Ordner überwacht werden (wie viele Elemente sind gerade noch abzuarbeiten, wie lange dauert das aktuelle Element schon).
• Ein Skript, das die JavaScript-Bibliothek background verwendet, muss in keinem bestimmten Ordner liegen, um zu funktionieren.

Verwendung

let background = require('/agorum/roi/customers/agorum.composite/js/lib/background');

// Callback, der ausgeführt wird
// Parameter siehe nachfolgende Tabelle
background(process => {
    process.name = 'Name des laufs';  
    process.status = 'Initialisiere Daten';
    process.progress = 0;
    process.cancelable = true;
});

Den Hintergrundprozess für einen bestimmten Benutzer starten

let background = require('/agorum/roi/customers/agorum.composite/js/lib/background');
let objects = require('common/objects');

// Callback, der ausgeführt wird
// Parameter siehe nachfolgende Tabelle
background(process => {
    process.name = 'Name des laufs';  
    process.status = 'Initialisiere Daten';
    process.progress = 0;
    process.cancelable = true;
}, objects.find('user:demo'));

aguila.fork(() => {
  background(process => {
    process.name = 'Name des laufs';  
    process.status = 'Initialisere Daten';
    process.progress = 0;

    // throw new Error('Test Error');
    doSomething(process);
  });
});

Parameter

Hat das System den Callback (siehe Codebeispiel) abgearbeitet / ausgeführt und das Ende der Klammer erreicht, markiert das System den Prozess in den Hintergrundaktivitäten als abgeschlossen. Ein grauer Haken erscheint.

background(bt => {
  bt.name = 'Name des Laufs';  
  bt.status = 'Initialisiere Daten';
  bt.progress = 0;

  doSomething(bt);
});

function doSomething(bt) {
  // ...

  // isCanceled liefert true, wenn vom Benutzer "Abbrechen" gedrückt wurde
  while (bedingung && !bt.isCanceled()) {
    bt.status = 'Bearbeite xyz';
    bt.progress = 50;
  }
}

Verwendung im manuellen Modus, ohne interne Funktion

Die Hintergrundanzeige können Sie verwenden, ohne dass diese eine feste Schleifenfunktion enthält. Das ist für verstreut laufende Hintergrundprozesse nützlich, etwa innerhalb eines Workflows über mehrere Prozessknoten hinweg.

• Mit der Funktion background.get([ID]) erzeugt das System ein neues Prozessobjekt oder gibt ein vorhandenes zurück.
• Das System erzeugt automatisch eine eindeutige ID, wenn Sie bei ID keinen Parameter übergeben.
• Die ID kann ein beliebiger String sein, etwa die ID eines Tokens.

Den Hintergrundprozess für einen bestimmten Benutzer starten

Sie können mit der Funktion background.get([ID], [USER-OBJECT]) einen Hintergrundprozess für einen bestimmten Benutzer starten.

Das System verwendet den aktuellen Benutzer der Sitzung, wenn Sie den Parameter user nicht mitgegeben.

Beispiel

let background = require('/agorum/roi/customers/agorum.composite/js/lib/background');
let objects = require('common/objects');

// Der folgende Aufruf gibt ein Prozess-Objekt mit der übergebenen ID zurück.
// Ist das Prozess-Objekt bereits vorhanden, dann wird dieses geliefert, ansonsten ein neues angelegt.
// Pro eindeutiger ID wird eine Zeile in der Hintergrundansicht erstellt.
let process = background.get('eine-eindeutige-ID');

// let process = background.get('eine-eindeutige-ID', objects.find('user:demo'));

// Wenn das Prozess-Objekt zuvor schon einmal verwendet wurde und bereits beendet ist, kann dieses wieder auf den Ursprungszustand
​​​​​​// zurückgesetzt werden. (Dies ist nur notwendig, wenn immer wieder mit derselben ID gearbeitet wird.)
if (process.isDone() || process.isCanceled()) {
  process.restart();

​​​​​​  process.name = 'Bearbeite xyz';
  process.cancelable = true;
}

// Nun kann irgendetwas gesetzt werden
process.status = 'Bearbeite Schritt 123...';
process.progress = 60; // progress ist optional und auch nur dann möglich, wenn ein prozentualer Fortschritt berechnet werden kann.

// Wenn der Vorgang fertig ist, kann dieser manuell abgeschlossen werden mit
process.done();

Komplett lauffähiges Beispiel

/* global sc */
let aguila = require('common/aguila');
let background = require('/agorum/roi/customers/agorum.composite/js/lib/background');

let process= background.get('test-background');
process.restart();
background.show();

aguila.fork(() => {
  let cancelable = true;
  
  let countTo = 6000;

  process.cancelable = cancelable;
  process.name = 'Test process';
  process.status = 'count';

  // Sie können bei Bedarf im Prozess-Objekt auch noch weitere als JSON serialisierbare Daten speichern, die Sie an anderer
  // Stelle verwenden können. Dabei darf es sich nicht um lebende Objekte handeln, da diese serialisiert werden. Beispiele für ungültige Objekte: Date, agorum core-Objekte
  process.data = {
    total: countTo,
    current: 0
  };
  
  try {
    for (let progress = 0; progress <= countTo && !process.isCanceled(); ++progress) {
      let prog = progress/countTo * 100;

      if (process.isCanceled()) {
        progress = countTo;
      }

      process.data.current = progress;
      
      process.status = 'cancelable:' + cancelable + ' canceled:' + process.isCanceled() + ' (' + process.data.current + ')';
      java.lang.Thread.sleep(1);
    } 

    process.status = 'finished - cancelable: ' +  cancelable + ' canceled: ' + process.isCanceled();
  }
  finally {
    process.done();
  }
});

Das bei get() zurückgegebene Prozessobjekt besitzt folgende Parameter:

data = {};

Hintergrundaktivitäten mit queries

Oftmals werden für die Verarbeitung im Hintergrund Suchen verwendet, um eine gewisse Menge an betroffenen Objekten zu verarbeiten. Um diese häufig verwendete Art zu vereinfachen, existiert ein vereinfachter Aufruf in der background-Bibliothek.

Beispiel

let metadata = require('common/metadata');
let background = require('/agorum/roi/customers/agorum.composite/js/lib/background');

// example, that runs as background task: searches all objects with tag=test and changes it to test2
background
  .query('ag_tags_ci:test')
  .name('Test query')
  .forEach(obj => {
    // do something with the object
    metadata({
      ag_tags: ['test2'],
    }).save(obj);
  });

• Die Funktion background.query nimmt als Parameter eine beliebige agorum core search-Query an. Die dadurch gefundenen Objekte werden im Aufruf forEach als Parameter übergeben. Zusätzlich kann mit der Funktion name eine Bezeichnung für die Hintergrund-Aufgabe mitgegeben werden.
• Die Funktion kümmert sich um das Transaktions-Handling (alle 10 Sekunden).
• Die Aktivität ist cancelable (abbrechbar).
• Ausgegeben wird ein Fortschritt sowie wie viele von wie vielen Objekten verarbeitet wurden.

Hintergrundaktivitäten manuell öffnen

1. Klicken Sie oben rechts neben Ihrem Profilbild auf  .
2. Wählen Sie Zeige Hintergrundaktivitäten.
   
   Ergebnis: Das System zeigt laufende, fehlerhafte und abgeschlossene Hintergrundaktivitäten. 

Darstellung der Hintergrundaktivitäten

Zustände der Hintergrundaktivität

Hintergrundaktivität per JavaScript aufrufen

let background = require('/agorum/roi/customers/agorum.composite/js/lib/background');
background.show();