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 that is executed
// for the list of parameters see the table below 
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 that is executed
//  for the list of parameters see the table below 
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 returns true, if the user clicks "Abbrechen/Cancel"
  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');

// The following call returns a process object with the transferred ID.
// If the process object already exists, it is returned, otherwise a new one is created.
// For each unique ID one line is created in the list of background activities.
let process = background.get('eine-eindeutige-ID');

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

// If the process object has been used before and has already been closed, it can be reset to its original state.
​​​​​​// (This is only necessary if the same ID is used.)
if (process.isDone() || process.isCanceled()) {
  process.restart();

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

// Now something can be set.
process.status = 'Bearbeite Schritt 123...';
process.progress = 60; // progress is optional and only possible if a percentage progress can be calculated.

// When the process is finished, it can be completed manually with
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';

  // create local copy of process.data
  let processData = {
    total: countTo,
    currentDuration: 0,
    startTime: Date.now(),
  };

  try {
    for (let progress = 0; progress <= countTo && !process.isCanceled(); ++progress) {
      let currentTime = Date.now();
      processData.currentDuration = currentTime - processData.startTime;

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

      process.progress = (progress / countTo) * 100;

      process.status =
        'cancelable:' +
        cancelable +
        ' canceled:' +
        process.isCanceled() +
        ' (' +
        processData.currentDuration +
        ' ms elapsed)';

      java.lang.Thread.sleep(1);
    }

    // set the updated data
    process.data = processData;
    process.status = 'finished - cancelable: ' + cancelable + ' canceled: ' + process.isCanceled();
  } finally {
    process.done();
  }
});

Illustration der Hintergrundaktivitäten zum lauffähigen Beispiel

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();