Massendaten-Verarbeitung

Grundlagen

Die Massendaten-Aktion ist ein spezielles Element im technischen Modell und dient der performanten Verarbeitung großer Datenmengen. Sie ist ein transaktionsunterbrechendes Ereignis und ersetzt in diesem Kontext die klassische Skript-Aktion zur Datenverarbeitung, übernimmt aber zusätzlich automatisch die Aufgaben der Massenverarbeitung.

Ein typischer Prozess bereitet die Massendatenverarbeitung vor, indem zunächst die Grundlage (Suche oder Datenmenge) erstellt wird. Anschließend übernimmt die Massendaten-Aktion die asynchrone Abarbeitung im Hintergrund.

Funktionsweise und Hintergrundjob

Beim Erreichen der Massendaten-Aktion im Prozess wird die Prozessausführung wird unterbrochen und ein Hintergrundjob auf dem Massendatenserver in die Auftragswarteschlange eingereiht.

Ist in den Systemeinstellungen kein Massendatenserver hinterlegt, nutzt das System den aktuellen Applikationsserver.

Die Abarbeitung über die Massendatenserver-Logik stellt sicher, dass die Aktion auch dann zu Ende geführt wird, wenn der Applikationsserver zwischendurch neu gestartet wird.

Der aktuelle Zustand der Massendaten-Aktion kann über folgende Entitäten eingesehen werden:

• Auftragswarteschlange

• Massendatenaktion (im Admin-Menü)

In der Beschreibung des Auftrags findet sich u. a.:

• die ID der Prozessinstanz

• der Typ PROCESS_MASSDATA

Ausführung auf dem Massendatenserver mit Suche

In diesem Szenario werden die zu verarbeitenden Datensätze über eine Suche ermittelt.

Vorbereitung der Suche

Die Suche kann auf unterschiedliche Weise bereitgestellt werden:

• vorhandene, im System gespeicherte Suche verwenden

• neue Suche in einer vorgelagerten Skript-Aktion erstellen oder anpassen

• Suche über die BPM-Suchmaske, ggf. durch den Anwender angepasst

Die Suche muss als Prozessvariable vom Typ ISearch hinterlegt sein.

Bei neuen gespeicherten Suchen, die über CURSOR-BPM angelegt werden, wird für den Top-Count standardmäßig „-1“ gesetzt (d. h. keine Begrenzung). Dieser Wert kann bei Bedarf manuell angepasst werden.

Ablauf auf dem Massendatenserver

1. Vor dem Skriptlauf wird die Suche ohne Einschränkung der Ergebnisanzahl (TopCount) ausgeführt.

2. Dabei wird nur der Primärschlüssel der Treffer in eine temporäre Tabelle geschrieben.

3. Für jeden Datensatz stellt die Massendaten-Aktion im Skript folgende Prozessvariablen bereit:

   • massDataEntryPk: Primärschlüssel des aktuell verarbeiteten Datensatzes

   • massDataEntryContainer: leerer IContainer mit diesem Primärschlüssel (zur optionalen Befüllung)

Das Suchergebnis kann über eine mit WorkSpaceScriptUtils.createSearchOrder() erzeugte Suchreihenfolge sortiert werden. Die verwendeten Felder müssen dabei als Suchergebnisfelder in der Suche definiert sein.

Transaktionsverhalten und Berechtigungen

Das Skript wird pro Datensatz in einer eigenen Transaktion ausgeführt, bis alle Einträge der temporären Tabelle verarbeitet wurden. Falls besondere Berechtigungen für die Verarbeitung nötig sind, kann für die Massendaten-Aktion ein technischer Benutzer hinterlegt werden.

Protokollierung und Fehlerbehandlung

Laufende Informationen und Zwischenergebnisse werden in der Entität Massendatenaktion gespeichert und können im Admin-Menü eingesehen werden.

In der Massendatenaktion können keine neuen Prozessvariablen angelegt oder verändert werden, da die Abarbeitung außerhalb der Prozess-Engine erfolgt. Bestehende Prozessvariablen können jedoch ausgelesen werden. Im Betreff der Massendaten-Aktion wird der Name des Prozesses vermerkt. Für jeden erfolgreich verarbeiteten Datensatz wird die Ergebnisanzahl erhöht; der aktuelle Status wird im Protokolltext festgehalten.

Treten Fehler im Skript auf:

• Die Transaktion für den jeweiligen Datensatz wird zurückgerollt.

• Es wird ein Eintrag in die Tabelle Massendatenprotokoll geschrieben.

• Das Massendatenprotokoll ist im Unterbereich zur Massendatenaktion zu finden; dort können die Fehlermeldungen zu jedem betroffenen Datensatz eingesehen werden.

• Optional kann die Massendaten-Aktion so konfiguriert werden, dass die Verarbeitung beim ersten Fehler abbricht.

• Bereits erfolgreich verarbeitete Datensätze behalten ihre Änderungen.

Fortsetzung des Prozesses

Sind alle Datensätze der temporären Tabelle verarbeitet, endet der Systemjob in der Auftragswarteschlange. Der ursprüngliche Prozess wird automatisch fortgesetzt. Der Primärschlüssel der Entität Massendatenaktion wird in eine definierte Prozessvariable geschrieben. Damit können v. a. die fehlerhaften Datensätze gezielt nachverfolgt werden.

Ein vollständiges Protokoll über alle erfolgreich verarbeiteten Datensätze wird dem Prozess nicht zur Verfügung gestellt, da die Datenmenge zu groß sein kann. Falls eine Auswertung der Erfolgsfälle benötigt wird, muss dies über eigene Kriterien oder Kennzeichnungen in den Datensätzen abgebildet werden.

Beispiel für eine Nachverarbeitung im Prozess (Auswertung der Massendatenaktion)

IContainer massDataTask = WorkSpaceScriptUtils.searchEntryForRead(massDataTaskPk, "MassDataTask");
int resultCount = WorkSpaceScriptUtils.getValue(massDataTask, "ResultCount.MassDataTask");

ISearch search = SearchUtils.createSearch(
    "MassDataLog",
    SearchUtils.createSearchCondition(
        "MassDataTaskKey.MassDataLog",
        false,
        false,
        SearchUtils.EQUAL,
        LookupUtils.toLookup(massDataTaskPk)
    )
);
SearchUtils.addSearchCondition(
    search,
    SearchUtils.createSearchCondition(
        "ShortAbstract.MassDataLog",
        false,
        true,
        SearchUtils.NO_CONDITION
    )
);
SearchUtils.addSearchCondition(
    search,
    SearchUtils.createSearchCondition(
        "EntryPk.MassDataLog",
        false,
        true,
        SearchUtils.NO_CONDITION
    )
);

List<IContainer> massDataLogs = WorkSpaceScriptUtils.searchForRead(search);
int errorCount = massDataLogs.size();

if (errorCount == 0) {
  ScriptUtils.info("All fine: Execute mass data script for " + resultCount + " contact persons");
} else {
  ScriptUtils.error("Failure: mass data script fails for " + errorCount + " contact persons");
}

Ausführung auf dem Massendatenserver mit IContainer

In manchen Szenarien werden Massendaten nicht über CRM-Suchen, sondern aus externen Quellen bereitgestellt.
In diesem Fall werden die Daten als IContainer-Objekte für die Massendaten-Aktion vorbereitet.

Vorgehen:

1. Externe Daten werden gelesen und in eine Liste von IContainer überführt.

2. Jeder IContainer benötigt einen eindeutigen Primärschlüssel:

   • Ist kein Primärschlüssel gesetzt, wird vom System ein neuer Primärschlüssel generiert.

3. Die IContainer-Daten werden der Hilfsklasse MassDataUtils übergeben, die:

   • eine Massendatenaktion im CRM anlegt

   • eine entsprechende temporäre Tabelle erstellt

   • die IContainer-Daten darin ablegt

Daten können auch in Blöcken übergeben werden, um den Speicherverbrauch niedrig zu halten.
Die Abarbeitung in der Massendaten-Aktion erfolgt in der Reihenfolge, in der die Daten in die Tabelle geschrieben wurden.

Beispiel für die Vorbereitung in einer Skript-Aktion

// Hilfsmethode, um die IContainer-Daten für die Massendatenaktion einzulesen
List<IContainer> containers = readContainerData(...);
String massDataTaskPk = MassDataUtils.createMassData(containers);

// Hilfsmethode, um zusätzliche IContainer-Daten nachzuladen
List<IContainer> additionalContainers = readAdditionalContainerData(...);
MassDataUtils.appendMassData(massDataTaskPk, additionalContainers);

// Zuordnung zu einer Prozessvariablen vom Typ Primärschlüssel
// für die weitere Verwendung innerhalb der Massendatenaktion
ProcessUtils.setVariable("massDataTaskPk", massDataTaskPk);

Große Mengen an IContainer-Daten sollten nicht als Prozessvariablen gespeichert werden. Dies würde die Performance und die Laufzeitumgebung der Prozesse stark beeinträchtigen.

In der Massendaten-Aktion entfällt in diesem Szenario die Definition einer Suche bzw. Suchreihenfolge. In der Massendaten-Aktion stehen dann pro Datensatz folgende Prozessvariablen zur Verfügung:

• massDataEntryPk: Primärschlüssel (ggf. generiert)

• massDataEntryContainer: der zuvor zwischengespeicherte IContainer

Skriptbeispiel in der Massendaten-Aktion

// Verarbeitung in der Massendaten-Aktion
IContainer container = ProcessUtils.getVariable("massDataEntryContainer");
// ... weitere Verarbeitung

Die Verarbeitung erfolgt – wie auch bei der Suche – pro Datensatz in einer eigenen Transaktion.
Kann ein IContainer nicht mehr aus der Datenbank wiederhergestellt werden oder tritt ein Fehler im Skript auf, wird der Fehler in den Massendatenprotokollen zur entsprechenden Massendatenaktion festgehalten.

Ausführung auf dem Massendatenserver mit IContainer-Liste

In manchen Fällen werden pro Hauptdatensatz weitere, abhängige Datensätze benötigt (z. B. ein Objekt plus zugehörige Detaildatensätze). Hierfür können Listen von IContainer-Objekten verwendet werden.

Struktur:

• äußere Liste: alle Schritte / Datensätze der Massendaten-Aktion

• innere Liste: alle zu einem Schritt gehörenden IContainer-Datensätze

Beispiel zur Vorbereitung

// Hilfsmethode, um die IContainer-Listen-Daten für die Massendatenaktion einzulesen
List<List<IContainer>> containers = readContainerData(...);
String massDataTaskPk = MassDataUtils.createMassData(containers);

// Hilfsmethode, um zusätzliche IContainer-Listen-Daten einzulesen
List<List<IContainer>> additionalContainers = readAdditionalContainerData(...);
MassDataUtils.appendMassData(massDataTaskPk, additionalContainers);

// Zuordnung zu einer Prozessvariablen vom Typ Primärschlüssel
// für die weitere Verwendung innerhalb der Massendatenaktion
ProcessUtils.setVariable("massDataTaskPk", massDataTaskPk);

In der Massendaten-Aktion stehen die Daten dann über die Prozessvariable massDataEntryContainerList zur Verfügung:

// Verarbeitung in der Massendaten-Aktion
List<IContainer> containers = ProcessUtils.getVariable("massDataEntryContainerList");
// ... weitere Verarbeitung

Die Reihenfolge der IContainer-Daten bleibt innerhalb eines Schritts (innere Liste) stabil und über alle Schritte der Massendaten-Aktion (äußere Liste) hinweg erhalten.

Für eine gute Wartbarkeit des Prozesses ist eine konstante Datensatzkonstellation pro Schritt empfehlenswert, auch wenn technisch unterschiedliche Kombinationen möglich sind.

Aktualisierung der Nachrichten auf dem Hauptserver

2026.3

Werden durch die Massendaten-Verarbeitung auf dem Hauptserver asynchron neue Benachrichtigungen angelegt oder Prozesse mit Benutzeraktionen (mittels ProcessUtils.startProcess) gestartet, muss der Nachrichten-Cache auf dem Hauptserver geleert werden, damit diese ohne größere Zeitverzögerung dem Anwender angezeigt werden.

Hierfür gibt es in der Massendaten-Aktion die Konfigurationsmöglichkeit “Nachrichten aktualisieren”, die in diesem Fall aktiviert werden muss.