Massendaten-Aktion

Massendaten-Verarbeitung

Bisherige Problemstellungen

Die bisherige Verarbeitung von großen Datenmengen hatte einige Beschränkungen und zwang den Prozess-Ersteller dazu, die Probleme durch einen speziellen Aufbau von einem Prozess oder mehreren Prozessen zu lösen.

Für die einzelnen Probleme gab es meistens einen umständlichen Lösungsweg:

1. Suchergebnisgrenze von 10000
   Die maximale Anzahl an Suchergebnissen ist im Standard auf 10000 begrenzt. Dies hat gute Gründe, da viele Daten auch viele Ressourcen des Systems benötigen. Um dieses Problem zu umgehen wurde zyklisch die Suche erneut ausgeführt und speziell eingeschränkt, um schon bearbeitete Daten heraus zu filtern.

   1. Ein Problem besteht in parallelen Datenbank-Transaktionen und zwischenzeitlichen Datenbank-Änderungen, die dazu führen, dass einige Sätze evtl. mehrmals durch den Prozess bearbeitet werden.

   2. Ein weiteres Problem ist die Datenhaltung im Prozess. Die Suchergebnismenge von 10000 als Prozess-Variable zu halten, belegt sehr viele Ressourcen des CRM-Systems.

2. Transaktionsgrenzen werden überschritten
   Die Verarbeitung von Daten inkl. Nachschlagefeldern und Relationen benötigt je nach Datenmodell einige Zeit. Zusätzlich kann die Kommunikation mit externen Systemen die Laufzeit bremsen. Wurde die Blockgröße für die Verarbeitung zu groß gewählt, so wurde die Standard-Transaktionszeit von 5min überschritten. Mit dem Transaktionsunterbrechenden Zwischenereignis kann die verfügbare Transaktionszeit für eine Blockverarbeitung auf bis zu 24h erhöht werden.

   1. Ein Grundlegendes Problem des Transaktionsunterbrechenden Zwischenereignisses ist das Verhalten im Fehlerfall. Hier bleibt der Prozess fehlerhaft im System und kann nur noch durch den Administrator abgebrochen werden. Eine Wiederaufnahme der Verarbeitung ist nicht möglich.

   2. Um dieses Problem zu umgehen, wurden die Prozesse getrennt. Der externe Prozess ruft die Verarbeitungsprozesse zyklisch immer wieder auf. Das Problem hierbei ist, dass dadurch viele Prozessinstanz-Leichen entstehen können, die die Ressourcen des CRM-Systems blockieren. 

3. Die Laufzeit und der Speicherverbrauch steigen mit der Transaktionslänge
   Je mehr Daten in einer Transaktion verarbeitet werden, umso länger benötigt das System für die Verarbeitung der einzelnen Datensätze. Hierfür wurde die Blockverarbeitung eingeführt. Die Blockgröße basiert auf Erfahrungswerte und muss in jedem neuen Prozess wieder neu modelliert werden.

Massendaten-Aktion

Zur Lösung der oben genannten Probleme wurde edie Massendaten-Aktion in BPM eingeführt. Dieses Element ist für BPM ein transaktionsunterbrechendes Ereignis, ersetzt die Skript-Aktion zur Datenverarbeitung und übernimmt dabei automatisch die Aufgaben zur Massenverarbeitung. Der gezeigte Prozess bereitet die Massendatenverarbeitung vor, indem die zu Grunde liegende Suche erstellt wird. Es ist möglich, eine im System gespeicherte Suche zu verwenden, eine neue Suche in der Skript-Aktion zu erstellen oder zu verändern, oder die Suche aus der BPM Suchmaske, angepasst durch den Anwender, zu verwenden. Die Suche muss als Prozess-Variable vom Typ ISearch hinterlegt sein.

Die Massendaten-Aktion unterbricht die Prozess-Ausführung und reiht einen Hintergrundjob auf dem Massendatenserver ein. Ist kein Massendatenserver in den Systemeinstellungen hinterlegt, wird der eigene Server zur Abarbeitung verwendet. Die Abarbeitung über die Massendatenserver-Logik stellt sicher, dass die Aktion auch dann fortgesetzt wird, wenn der Applikationsserver zwischenzeitlich neu gestartet wurde. Der aktuelle Zustand der Aktion kann über die Entität Auftragswarteschlange und Massendatenaktion im Admin-Menü eingesehen werden. Die Beschreibung enthält die ID der Prozessinstanz und den Typ PROCESS_MASSDATA.

Ausführung auf dem Massendatenserver mit Suche

Vor der Verarbeitung der Daten durch das Skript wird die Suche ohne Einschränkung der Ergebnisanzahl (TopCount) ausgeführt und selektiert nur den Primärschlüssel aus dem Suchergebnis in eine temporäre Tabelle. Im Skript steht der Primärschlüssel für jeden einzelnen Datensatz aus dem Suchergebnis unter der Prozess-Variable massDataEntryPk zur Verfügung. Die Variable massDataEntryContainer ist ein leerer IContainer mit diesem Primärschlüssel. Das Suchergebnis kann über eine mit WorkSpaceScriptUtils.createSearchOrder() erzeugte Suchreihenfolge sortiert werden. Die Felder in der Suchreihenfolge müssen dabei als Suchergebnisfelder in der Suche definiert sein.

Bei der Anlage von neuen gespeicherten Suchen via CURSOR-BPM wird als Default für den Top-Count immer "-1" eingetragen. Der Prozess-Ersteller kann dann bei Bedarf diesen Default-Wert manuell abändern.

Das Skript wird nun pro Datensatz in einer eigenen Transaktion ausgeführt, solange bis alle Daten aus temporären Tabelle verarbeitet wurden. Sind für die Verarbeitung gesonderte Rechte von Nöten, kann ein spezieller technischer Benutzer für die Massendaten-Aktion hinterlegt werden.

Die Zwischenergebnisse zur Verarbeitung werden in der Entität Massendatenaktion festgehalten und können über das Admin-Menü im CRM-System eingesehen werden. Es ist nicht möglich Prozess-Variablen in der Massendatenaktion zu erzeugen oder zu verändern, da die Aktion außerhalb der Prozess-Engine abläuft. Im Betreff 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 bei der Verarbeitung im Skript Fehler auf, so wird für den einen Datensatz die Transaktion zurückgerollt und ein Eintrag in die Tabelle Massendatenprotokoll geschrieben. Das Massendatenprotokoll ist im Unterbereich zur Massendatenaktion zu finden. Dort kann zu jedem fehlerhaften Datensatz die zugehörige Fehlermeldung eingesehen werden. Es ist möglich die gesamte Verarbeitung der Massendaten-Aktion mit dem ersten auftretenden Fehler abzubrechen. Alle bis dahin verarbeiteten Datensätze bleiben mit ihren Änderungen erhalten.

Wurden alle Sätze der temporären Tabelle über das Skript verarbeitet, endet der Systemjob in der Auftragswarteschlange und setzt automatisch den Prozess fort. Im Anschluss kann die Verarbeitung der Massendaten-Aktion im Prozess ausgewertet werden. Der Primärschlüssel der Entität Massendatenaktion wird in die definierte Variable geschrieben. Daraufhin können besonders die fehlerhaften Datensätze nachverfolgt werden. Ein Protokoll zu allen erfolgreich verarbeiteten Datensätzen steht dem Prozess nicht zur Verfügung, da die Datenmenge zu groß werden kann. Hierfür müssten eigene Kriterien in den Datensätzen ausgewertet werden. 

Beispiel für die Nachverarbeitung

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

Es gibt Anwendungsfälle, in denen eine Massendatenverarbeitung mit nicht persistenten CRM-Daten benötigt wird, da die Daten aus externen Quellen stammen. Anstatt die Daten per Suche zu ermitteln, werden die Daten aus der externen Quelle gelesen und für den Prozess als IContainer-Daten aufbereitet und der Massendatenaktion zur Verarbeitung zur Verfügung gestellt. Jeder IContainer benötigt hierfür einen eindeutigen Primärschlüssel. Ist dieser leer, wird ein neuer Primärschlüssel vom System generiert. 

// Hilfsmethode um die IContainer-Daten für die Massendatenaktion einzulesen
List<List<IContainer>> containers = readContainerData(...);
String massDataTaskPk = MassDataUtils.createMassData(containers);
 
// Hilfsmethode um die zusätzlich IContainer-Daten einzulesen
List<IContainer> additionalContainers = readAdditionalContainerData(...);
MassDataUtils.appendMassData(massDataTaskPk, additionalContainers);
 
// Zuordung zu einer Prozessvariablen vom Typ Primärschlüssel für weitere Verwendung innerhalb der Massendatenaktion
ProcessUtils.setVariable("massDataTaskPk", massDataTaskPk);

In der Skriptaktion vor der Massendatenverarbeitung werden die IContainer-Daten der Skript-Klasse MassDataUtils übergeben, welche eine Massendatenaktion im CRM erstellt, eine dazugehörige temporäre Tabelle in der Datenbank erzeugt und die IContainer-Daten dort ablegt. Dabei ist es möglich die externen Daten auch in Blöcken zu lesen, um den Speicherverbrauch zur Laufzeit gering zu halten. Die Verarbeitung der Daten in der Massendatenaktion findet in der Reihenfolge statt, in der die Daten in die Tabelle geschrieben wurden.

Wichtig

Die IContainer-Daten sollte in großer Stückzahl auf keinen Fall als Prozessvariable gespeichert werden, da dies die Performanz und Laufzeitumgebung der Prozesse maßgeblich beeinträchtigen kann!

In der Massendatenaktion entfällt nun die Definition der Suche bzw. der Suchreihenfolge. In der Massendatenaktion selbst stehen neben dem evtl. generierten Primarschüssel in der Variable massDataEntryPk auch der zuvor zwischengespeicherte IContainer als Variable massDataTaskContainer zur Verfügung.

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

...

Die weitere Verarbeitung wird pro Datensatz in einer eigenen Transaktion abgearbeitet. Sollte eine IContainer-Variable aus der Datenbank nicht wiederhergestellt werden können, wird dies als Fehlereintrag zur Massendatenaktion in den Massendatenprotokollen festgehalten, ebenso wenn es zu einem Fehler im Verarbeitungsskript kommen sollte.

Ausführung auf dem Massendatenserver mit IContainer-Liste

Werden zur Verarbeitung pro Hauptdatensatz weitere Datensätze benötigt, können zusätzliche IContainer-Variablen als Liste zusammengestellt werden. Es ist auch möglich, pro Schritt unterschiedliche Datensätze zu bearbeiten, auch wenn eine gleichbleibende Datensatzkonstellation für die Wartbarkeit des Prozesses ratsamer ist.

// Hilfsmethode um die IContainer-Listen-Daten für die Massendatenaktion einzulesen
List<List<IContainer>> containers = readContainerData(...);
String massDataTaskPk = MassDataUtils.createMassData(containers);
 
// Hilfsmethode um die zusätzlich IContainer-Listen-Daten einzulesen
List<List<IContainer>> additionalContainers = readAdditionalContainerData(...);
MassDataUtils.appendMassData(massDataTaskPk, additionalContainers);
 
// Zuordung zu einer Prozessvariablen vom Typ Primärschlüssel für weitere Verwendung innerhalb der Massendatenaktion
ProcessUtils.setVariable("massDataTaskPk", massDataTaskPk);

Für die Verarbeitung in der Massendatenaktionen stehen die IContainer-Daten nun als Liste in der Variable massDataTaskContainerList zur Verfügung. Die Reihenfolge der IContainer-Daten bleibt hierbei stabil für jeden einzelnen Schritt (innere Liste) und für den gesamten Lauf (äußere Liste).

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

...

Serienbriefaktion

Serienbriefe können nun aus dem Prozess erstellt werden, die auf dem Massendaten-Server verarbeitet werden. In der Massendaten-Aktion können alle Einstellungen des Serienbrief-Wizards, z.B. der Vorlagenname, eine Suche, der Betreff usw. aus Prozess-Variablen vorbelegt werden.

Nach Start des Prozesses wird der Serienbriefassistent wie gewohnt dem Anwender über die Systemjobs in der Schnellstartleiste angezeigt. Der Anwender kann gegebenenfalls noch weitere Anpassungen vornehmen. Die Konfiguration kann aber auch derart gestaltet werden, dass keine Anzeige des Assistenten erfolgt und die Serienbrieferstellung komplett im Hintergrund abläuft.

Der Prozess wird erst fortgesetzt, wenn die Verarbeitung abgeschlossen ist bzw. abgebrochen wurde.

Konfiguration

Vor der Ausführung erfolgt zunächst eine Prüfung der Konfiguration. Ist diese nicht gültig. z.B. die hinterlegte Serienbriefvorlage existiert nicht o.ä. wird die Serienbriefaktion nicht ausgeführt. Stattdessen werden alle fehlerhaften Konfigurationsparameter der Serienbriefaktion im Unterbereich "Massendatenprotokoll" der Entität "Massendatenaktion" festgehalten und der Prozess anschließend fortgesetzt. Fehler lassen sich somit im Nachhinein feststellen und für zukünftige Aktionen korrigieren. Für die Ausführung der Serienbrief-Aktion müssen zwingend die nachfolgenden Variablen vorgegeben sein.

Massendatenaktion-Variable

Die Variable in der der Primärschlüssel aus dem Protokollsatz aus der Entität Massendatenaktion hinterlegt wird. Aus dem Datensatz können im Prozessfortgang Informationen zur Serienbrieferstellung ausgelesen werden.

Serveraktionen

In wie weit Aktionen im Assistenten oder der gesamte Assistent im Hintergrund abgearbeitet werden kann über die Auswahl der Serveraktion gesteuert werden:

• Assistent öffnen
  Der Assistent wird gemäß den Vorgaben konfiguriert und wie gewohnt dem Anwender über die Systemjobs in der Schnellstartleiste angezeigt. 
  Bestehende Eingaben können durch den Anwender geändert und fehlende Eingaben noch ergänzt werden.

• Suche ausführen und Assistent öffnen
  Der Assistent wird gemäß den Vorgaben konfiguriert und die Suche wird direkt ausgeführt. Der Assistent mit bereits vorliegendem Suchergebnis wird wie gewohnt dem Anwender über die Systemjobs in der Schnellstartleiste angezeigt. Bestehende Eingaben können durch den Anwender geändert und fehlende Eingaben noch ergänzt werden.

• Alle gewählten Aktionen ausführen und Assistent öffnen
  Der Assistent wird gemäß den Vorgaben konfiguriert und die gewählten Aktionen werden direkt ausgeführt. 
  Der Assistent mit den bereits ausgeführten Aktionen wird wie gewohnt dem Anwender über die Systemjobs in der Schnellstartleiste angezeigt.
  Noch nicht ausgeführte Aktionen (z.B. Aktivitätengenerierung oder Dokumentenexport) können durch den Anwender nachträglich noch ausgeführt werden.
  Zu den möglichen Aktionen gehören:

  • Ausführung der Suche (immer)

  • Generierung der Dokumente (immer)

  • Generierung der Protokoll- und Erinnerungsaktivität
    erfolgt nur wenn die zugeordnete Prozessvariable "Protokollaktivität" bzw. "Erinnerungsaktivität" mit einer Aktivität vorbelegt ist

  • Export der Dokumente 
    erfolgt nur wenn die zugeordnete Prozessvariable "Exportunterverzeichnis" vorbelegt ist

• Alle gewählten Aktionen ausführen ohne Assistent ausführen
  Der Assistent wird gemäß den Vorgaben konfiguriert und die gewählten Aktionen werden direkt ausgeführt. Es erfolgt keine Anzeige des Assistenten. Der Prozess wird nach Ausführung direkt fortgesetzt.

Vorlagenname

Die Serienbriefvorlage bestimmt die Art der Serienbrief-Verarbeitung

• Serienbrief mit Einzeldokumenten:
  Hier können die bestehenden Serienbriefvorlagen verwendet werden. Das Attribut "Einzeldokumente generierbar" muss hierbei aktiviert sein!

• Serienbrief für Massendaten:
  Hier werden spezielle "native" Vorlagen des Vorlagentyps "Massendaten" benötigt.

Prüfkriterien

• Die Dokumentvorlage muss existieren und aktiv sein.

• Der Dokumentvorlagentyp muss den oben genannten Kriterien genügen.
  

ProcessUtils.setVariable("docTemplateName", "SERIENBRIEF BLANKO (Beispiel)");

Suche

Die Suche kann als ISearch Objekt vorbelegt werden. Die Hauptsuche des Suchbehälters der Serienbriefvorlage wird durch die übergebene Suche ersetzt.
Ist die zugehörige Prozessvariable nicht belegt, so wird der unveränderte Suchbehälter aus der Serienbriefvorlage verwendet

Prüfkriterien
Mögliche Werte der Prozessvariablen

• leer bzw. nicht belegt 

• Objekt des Typs ISearch
  Entitätsname und die Suchergebnisfelder der Suche müssen mit denen der Hauptsuche des Suchbehälters aus der Serienbriefvorlage übereinstimmen.
  

//Laden der Hauptsuche des Suchbehälters
ISearch search = DocumentUtils.getMainSearch("SERIENBRIEF BLANKO (Beispiel)");
SearchUtils.addSearchCondition(search, SearchUtils.createSearchCondition("TradeKey.Customer", false, true, SearchUtils.EQUAL, LookupUtils.toLookup("S_BRA-CB")));
 
ProcessUtils.setVariable("search", search);

Sortierung der Datenmenge

Die Sortierreihenfolge für die Selektionsergebnismenge kann als ISortOrder Objekt beim Serienbrief vorgegeben werdem. Die Sortierung wird beim Export der Einzeldokumente berücksichtigt, so dass beispielsweise eine Sortierung nach PLZ zwecks Versandoptimierung möglich ist.
Die Sortierung erfolgt im Standard immer aufsteigend, kann aber mit Hilfe des optionalen Parameters sortOrderDescending auch absteigend erfolgen.
Erzeugt wird das Objekt mit Hilfe der Methode MassDataUtils.createSortOrder(String searchAliasName, String attributeName, boolean sortOrderDescending).
Folgende Methoden stehen in dem Rückgabeobjekt ISortOrder zur Verfügung

• void addSortField(String searchAliasName, String attributeName)
  Erweitern der Sortierung um ein zusätzliches Sortierfeld

• void addSortField(String searchAliasName, String attributeName, boolean sortOrderDescending)
  Erweitern der Sortierung um ein zusätzliches Sortierfeld mit angegebener Sortierrichtung (absteigend / aufsteigend)

Prüfkriterien
Mögliche Werte der Prozessvariablen

• leer bzw. nicht belegt 

• Objekt des Typs ISortOrder
  Dieses enthält die Liste der Sortierfelder. Für die Sortierfelder gelten folgende Prüfkriterien.

  • Der Suchaliasname muss in dem der Dokumentvorlage zugeordneten Suchbehälter existieren.

  • In der zum Suchaliasnamen zugehörigen Suche muss der Feldname (AttributeName) vorhanden sein. Ist der Feldname mehrfach vorhanden, so wird der erste gefundene Feldname als Sortierfeld verwendet.
    

// Konfiguration einer Sortierung über vier Felder
ISortOrder sortOrder = MassDataUtils.createSortOrder("ADR", "ZIPKey.Address", true);
sortOrder.addSortField("GP", "Name1.Customer");
sortOrder.addSortField("Ansprech", "LastName.ContactPerson");
sortOrder.addSortField("Ansprech", "FirstName.ContactPerson", true);
 
// Zuordung zu einer Prozessvariablen vom Typ Object für weitere Verwendung innerhalb der Massendatenaktion 'Serienbrief'
ProcessUtils.setVariable("sortOrder", sortOrder);

Dokumentenbetreff 

Betreff der erzeugten Dokumentensätze

Prüfkriterien
Wenn die Generierung der Dokumente direkt ausgeführt wird (Serveraktion = "Alle ausgewählten Aktionen ausführen"), muss dieser Parameter gefüllt sein. Ansonsten erfolgt die Eingabe des Betreffs über den Assistenten, da dieses Feld nicht leer sein darf.

ProcessUtils.setVariable("docSubject", "Änderung AGB");

Ausgabeformat 

Das Ausgabeformat der Dokumente ist auswählbar. Der Standard wird durch die Vorlage vorgegeben.

Prüfkriterien
Mögliche Werte der Prozessvariablen

• leer bzw. nicht belegt 
  Es wird das Ausgabeformat der Dokumentvorlage verwendet

• DocumentUtils.DOC_SAVEFORMAT_DOC

• DocumentUtils.DOC_SAVEFORMAT_DOCX

• DocumentUtils.DOC_SAVEFORMAT_PDF
  

ProcessUtils.setVariable("saveFormat", DocumentUtils.DOC_SAVEFORMAT_PDF);

Protokoll-/Erinnerungsaktivität

Die zu erzeugende Protokoll- bzw. Erinnerungsaktivität kann vorkonfiguriert werden. Es können die Felder der Assistentenseite zur Aktivitätenerfassung vorbelegt werden. Hierzu gehören die Felder 

• "Betreff" (Subject.Activity)

• "Text" (Text.Activity)

• "Beginnt am" (StartDate.Activity)

• "Priorität" (Priority.Activity)

• "Anlass" (ContactReason.Activity)

• "Ergebnis" (ContactResult.Activity)

• "Art" (ActTypeKey.Activity)

Bleibt die entsprechende Prozessvariable leer, wird keine Aktivität generiert.

Prüfkriterien
Mögliche Werte der Prozessvariablen

• leer bzw. nicht belegt

• IContainer des Typs Aktivität 

  • AttributeValue "Priorität" (Priority.Activity), "Anlass" (ContactReason.Activity), "Ergebnis" (ContactResult.Activity), "Art" (ActTypeKey.Activity)

    • leer bzw. nicht vorhanden
      Es wird der hinterlegte Defaultwert des Feldes verwendet

    • LookupVO
      Der Pk des LookupVO wird auf Gültigkeit geprüft

  • AttributeValue "Betreff" (Subject.Activity)
    Wenn die Generierung der Aktivitäten direkt ausgeführt wird (Serveraktion = "Alle ausgewählten Aktionen ausführen"), muss dieser Parameter gefüllt sein. Ansonsten erfolgt die Eingabe des Betreffs über den Assistenten, da dieses Feld nicht leer sein darf.

  • AttributeValue "Beginnt am" (StartDate.Activity)

    • leer bzw. nicht vorhanden
      Es wird der hinterlegte Defaultwert verwendet (aktueller Zeitstempel plus 3 Tage/individuelle Zeitspanne)

    • Date, Timestamp 

  • Weitere Felder aus der Aktivität, z.B. FreeText1.Activity.
    Hinweise: 

    • Pk und Felder aus dem TableTail (z.B. CreateUser) werden ignoriert.

    • Im Falle von Entitätsnachschlagefeldern wird einfach der Pk der Entität übergeben.

    • Im Falle von Schlüsselnachschlagefeldern muss ein LookupVO (z.B. per LookupUtils.toLookup(...)) erstellt werden.
      

IContainer activityAC = WorkSpaceScriptUtils.createEmptyEntry("Activity", "actPk1");
WorkSpaceScriptUtils.setValue(activityAC, "Subject.Activity", "Änderung AGB");
WorkSpaceScriptUtils.setValue(activityAC, "Text.Activity", "<html><body>Serienbrief für geänderte AGBs</body></html>");
WorkSpaceScriptUtils.setValue(activityAC, "Priority.Activity", LookupUtils.toLookup("S_PRIOR-C"));
WorkSpaceScriptUtils.setValue(activityAC, "ActTypeKey.Activity", LookupUtils.toLookup("S_ACTTYPE-DO"));

WorkSpaceScriptUtils.setValue(activityAC, "FreeText1.Activity", "Sein Lieblingsgericht ist Malzbierbraten");
WorkSpaceScriptUtils.setValue(activityAC, "FreeNumber1.Activity", 123);
WorkSpaceScriptUtils.setValue(activityAC, "FreeDate1.Activity", DateUtils.parseDate("04.05.2020", "dd.MM.yyyy"));
WorkSpaceScriptUtils.setValue(activityAC, "Outbound.Activity", "testpkCaOut");
WorkSpaceScriptUtils.setValue(activityAC, "IsInbound.Activity", true);
WorkSpaceScriptUtils.setValue(activityAC, "OutbChannel.Activity", "P-C0OUTBCHANNEL");
// error case for example
// WorkSpaceScriptUtils.setValue(activityAC, "FirstName.ContactPerson", "Traudel");

ProcessUtils.setVariable("protocolActivity", activityAC);

Mitarbeiterzuordnung

Zu der zu erzeugende Protokoll- bzw. Erinnerungsaktivität kann die Mitarbeiterzuordnung vorkonfiguriert werden.

Prüfkriterien
Mögliche Werte der Prozessvariablen

• leer bzw. nicht belegt
  Es wird die Defaultzuordnung für Mitarbeiter verwendet. Der aktuelle Mitarbeiter wird als "delegiert von" mit der Beziehung "Empfänger" der Aktivität zugeordnet.

• Liste von IContainer des Typs Mitarbeiter

  • Alle Listeneinträge müssen vom Typ IContainer sein

  • Die Entität des IContainer muss Employee sein

  • Der Primärschlüssel des IContainer muss gefüllt und gültig sein:

    • Zu dem angegebenen Primärschlüssel gibt es einen aktiven Mitarbeitersatz ODER

    • Der angegebene Primärschlüssel ist eine Mitarbeitervariable, die im Mapping der Vorlage enthalten ist.
      Folgende Mitarbeitervariablen können im Mapping einer Vorlage verwendet werden

      • SERIALEmployeeSales

      • SERIALEmployeeKey

      • SERIALEmployeeQuote

      • SERIALEmployeeExtra1

      • SERIALEmployeeExtra2

  • AttributeValue "Beziehungstyp Mitarbeiter" (RELATIONTYPEKEYEM.Employee)
    Mögliche Werte: 

    • leer bzw. nicht belegt
      Es wird die Defaultbeziehung "Empfänger" verwendet.

    • LookupVO
      Der Pk des LookupVO wird auf Gültigkeit geprüft

  • AttributeValue "Delegiert von" (DelegatedByFlag.Employee) 
    Das Flag darf in der Liste der Mitarbeiter insgesamt nur einmal verwendet werden.

  • AttributeValue "Delegiert an" (DelegatedToFlag.Employee) 
    Das Flag darf in der Liste der Mitarbeiter insgesamt nur einmal verwendet werden.
    

// Alternative vollständige Variante - Beispiel mit 3 Mitarbeitern
IContainer employeeACDelBy = WorkSpaceScriptUtils.createEmptyEntry("Employee", "employee1");
WorkSpaceScriptUtils.setValue(employeeACDelBy, "RelationTypeKeyEm.Employee", LookupUtils.toLookup("ACTIVITY_EM_ROLE_TYPE-TO"));
WorkSpaceScriptUtils.setValue(employeeACDelBy, "DelegatedByFlag.Employee", true);

IContainer employeeACDelTo = WorkSpaceScriptUtils.createEmptyEntry("Employee", "SERIALEmployeeSales");
WorkSpaceScriptUtils.setValue(employeeACDelTo, "RelationTypeKeyEm.Employee", LookupUtils.toLookup("ACTIVITY_EM_ROLE_TYPE-TO"));
WorkSpaceScriptUtils.setValue(employeeACDelTo, "DelegatedToFlag.Employee", true);

IContainer employeeAC = WorkSpaceScriptUtils.createEmptyEntry("Employee", "employee3");
WorkSpaceScriptUtils.setValue(employeeAC, "RelationTypeKeyEm.Employee", LookupUtils.toLookup("ACTIVITY_EM_ROLE_TYPE-BCC"));

List<IContainer> employeeList = new ArrayList<>(3);
employeeList.add(employeeACDelBy);
employeeList.add(employeeACDelTo);
employeeList.add(employeeAC);
 
ProcessUtils.setVariable("protocolActivityEmployees", employeeList);

Exportunterverzeichnis

Vorbelegung des Unterverzeichnisses, in dem die generierten Serienbriefdokumente exportiert werden. Genauer gesagt - die Einzeldokumente werden automatisiert in ein separates Unterverzeichnis pro Anwender und Serienbriefaktion kopiert.
Ist kein Unterverzeichnisname angegeben, so ist eine direkte Ausführung ohne Assistent nicht möglich. Der Assistent öffnet sich in diesem Fall automatisch.

ProcessUtils.setVariable("exportSubDir", "AGB_2017_02");

Ausführung

Mit Start der Massendatenaktion "Serienbrief" wird zunächst eine Konfiguration für die Serienbriefaktion erstellt und geprüft. Sofern die Prüfung erfolgreich war, wird die Serienbriefaktion gestartet. Je nach gewählter Serveraktion werden vorab bereits einige Aktionen auf dem Massendatenserver ausgeführt und das Ergebnis wie gewohnt dem Anwender über die Systemjobs in der Schnellstartleiste angezeigt. 

Einige Beispiele zur Anzeige des Assistenten in Abhängigkeit der gewählten Serveraktion

• "Suche ausführen und Assistent öffnen"
  

  

• Serveraktion "Alle gewählten Aktionen ausführen und Assistent öffnen" bei nicht konfiguriertem Exportunterverzeichnis
  

  

Der Anwender kann nun gegebenenfalls noch weitere Anpassungen vornehmen. Weitere Aktionen wie z.B. der Dokumentenexport könnten gestartet werden.
Die Konfiguration kann aber auch derart gestaltet werden, dass keine Anzeige des Assistenten erfolgt und die Serienbrieferstellung komplett im Hintergrund abläuft.

Mit Fertigstellen des Assistenten oder nach Abarbeitung aller Aktionen im Hintergrund (ohne Assistent) wird der Prozess fortgesetzt. Die Nachbearbeitung im Prozess könnte wie folgt aussehen.

Beispiel für die Nachverarbeitung

String massDataTaskPk = ProcessUtils.getVariable("massDataPk");
IContainer massDataTask = WorkSpaceScriptUtils.searchEntryForRead(massDataTaskPk, "MassDataTask");
String exportDir = WorkSpaceScriptUtils.getValue(massDataTask, "ExportSubDir.MassDataTask");
int resultCount = WorkSpaceScriptUtils.getValue(massDataTask, "ResultCount.MassDataTask");
ProcessUtils.setVariable("resultCount", resultCount);
ProcessUtils.setVariable("exportDir", exportDir);
 
// z.B. Weiterverarbeitung der Prozessvariablen 'resultCount' und 'exportDir' in einer Nachricht oder Mail
 

Fehlerfallbehandlung

Sofern die Prüfung der Konfiguration nicht erfolgreich war, wird die Serienbriefaktion nicht gestartet, sondern sogleich beendet. Alle Fehlkonfigurationen werden in dem Unterbereich "Massendatenprotokoll" zur aktuellen "Massendatenaktion" gespeichert. Somit ist eine Korrektur des BPM-Prozesses im Nachgang recht einfach möglich. 
Der Prozess wird in einem solchen Fehlerfall nicht abgebrochen, sondern fortgesetzt.

Serienmailaktion

Serienmails können nun ebenfalls wie die Serienbriefe aus dem Prozess erstellt werden, die auf dem Massendaten-Server verarbeitet werden. In der Massendaten-Aktion können alle Einstellungen des Serienmail-Assistenten, z.B. der Vorlagenname, eine Suche usw. aus Prozess-Variablen vorbelegt werden.

Nach Start des Prozesses wird der Serienmail-Assistent wie gewohnt dem Anwender über die Systemjobs in der Schnellstartleiste angezeigt. Der Anwender kann gegebenenfalls noch weitere Anpassungen vornehmen kann. Die Konfiguration kann aber auch derart gestaltet werden, dass keine Anzeige des Assistenten erfolgt und die Serienmailerstellung komplett im Hintergrund abläuft.

Der Prozess wird erst fortgesetzt, wenn die Verarbeitung abgeschlossen ist bzw. die abgebrochen wurde.

Konfiguration

Vor der Ausführung erfolgt zunächst eine Prüfung der Konfiguration. Ist diese nicht gültig. z.B. die hinterlegte Serienmailvorlage existiert nicht o.ä. wird die Serienmailaktion nicht ausgeführt. Stattdessen werden alle fehlerhaften Konfigurationsparameter der Serienmailaktion im Unterbereich "Massendatenprotokoll" der Entität "Massendatenaktion" festgehalten und der Prozess anschließend fortgesetzt. Fehler lassen sich somit im Nachhinein feststellen und für zukünftige Aktionen korrigieren.

Vorbedingung bzw. Prüfkriterien

Es muss für den aktuellen Anwender eine Mailkonfiguration zugreifbar sein, die eine serverseitige Groupwareanbindung enthält. Diese kann hinterlegt sein, als

• benutzerspezifische Mailkonfiguration für den Web Client

• systemspezifische Mailkonfiguration, (wenn benutzerspezifische Mailkonfiguration für den Web Client nicht greift)

• Systemweite Mailkonfiguration für die Serienmail

Ist dies nicht der Fall, gilt die Konfiguration als ungültig und die Serienmailaktion wird nicht ausgeführt. Für die Ausführung der Serienmail-Aktion müssen zwingend die nachfolgenden Variablen vorgegeben sein.

Massendatenaktion-Variable

Die Variable in der der Primärschlüssel aus dem Protokollsatz aus der Entität Massendatenaktion hinterlegt wird. Aus dem Datensatz können im Prozessfortgang Informationen zur Serienmailerstellung ausgelesen werden.

Serveraktionen

In wie weit Aktionen im Assistenten oder der gesamte Assistent im Hintergrund abgearbeitet werden kann über die Auswahl der Serveraktion gesteuert werden:

• Assistenten öffnen
  Der Assistent wird gemäß den Vorgaben konfiguriert und wie gewohnt dem Anwender über die Systemjobs in der Schnellstartleiste angezeigt. 
  Bestehende Eingaben können durch den Anwender geändert und fehlende Eingaben noch ergänzt werden.

• Suche ausführen und Assistent öffnen
  Der Assistent wird gemäß den Vorgaben konfiguriert und die Suche wird direkt ausgeführt. Der Assistent mit bereits vorliegendem Suchergebnis wird wie gewohnt dem Anwender über die Systemjobs in der Schnellstartleiste angezeigt. Bestehende Eingaben können durch den Anwender geändert und fehlende Eingaben noch ergänzt werden.

• Alle gewählten Aktionen ausführen und Assistent öffnen
  Der Assistent wird gemäß den Vorgaben konfiguriert und alle Aktionen werden direkt ausgeführt. 
  Der Assistent mit den bereits ausgeführten Aktionen wird wie gewohnt dem Anwender über die Systemjobs in der Schnellstartleiste angezeigt. 
  Es wird die letzte Seite des Assistenten mit einer Zusammenfassung der Serienmailaktion angezeigt.
  Zu den ausgeführten Aktionen gehören:

  • Ausführung der Suche (immer)

  • Versenden der Mails (immer)

  • Generierung der Aktivitäten mit zugehöriger msg-Datei als Dokument (immer)

• Alle gewählten Aktionen ausführen ohne Assistent ausführen
  Der Assistent wird gemäß den Vorgaben konfiguriert und alle Aktionen werden direkt ausgeführt. Es erfolgt keine Anzeige des Assistenten. Der Prozess wird nach Ausführung direkt fortgesetzt.

Vorlagenname

Name der Serienmailvorlage, die in der Serienmailaktion verwendet wird.

Prüfkriterien

• Dokumentvorlage muss existieren und aktiv sein.

• Dokumentvorlage vom Typ Serienmail 
  

ProcessUtils.setVariable("docTemplateName", "SERIENMAIL");

Suche

Die Suche kann als ISearch Objekt vorbelegt werden. Die Hauptsuche des Suchbehälters der Serienmailvorlage wird durch die übergebene Suche ersetzt. 
Ist die zugehörige Prozessvariable nicht belegt, so wird der unveränderte Suchbehälter aus der Serienmailvorlage verwendet

Prüfkriterien
Mögliche Werte der Prozessvariablen

• leer bzw. nicht belegt 

• Objekt des Typs ISearch
  Entitätsname und die Suchergebnisfelder der Suche müssen mit denen der Hauptsuche des Suchbehälters aus der Serienmailvorlage übereinstimmen.
  

//Laden der Hauptsuche des Suchbehälters
ISearch search = DocumentUtils.getMainSearch("SERIENMAIL");
SearchUtils.addSearchCondition(search, SearchUtils.createSearchCondition("TradeKey.Customer", false, true, SearchUtils.EQUAL, LookupUtils.toLookup("S_BRA-CB")));
 
ProcessUtils.setVariable("search", search);

Mail-Betreff

Betreff der zu versendenden Serienmail

Prüfkriterien

Wenn die Generierung der Mails direkt ausgeführt wird (Serveraktion = "Alle ausgewählten Aktionen ausführen (mit oder ohne Assistent)"), muss dieser Parameter gefüllt sein. Ist der Parameter leer, so muss die Eingabe des Betreffs im Assistenten durch den Anwender erfolgen, da dieses Feld in einer Mail nicht leer sein darf.

ProcessUtils.setVariable("mailSubject", "Rückwirkender Preisnachlass");

Mail-Text

Haupttext der zu versendenden Serienmail

Prüfkriterien

• Wenn die Generierung der Mails direkt ausgeführt wird (Serveraktion = "Alle ausgewählten Aktionen ausführen (mit oder ohne Assistent)"), muss dieser Parameter gefüllt sein. Ist der Parameter leer, so muss die Eingabe des Texts im Assistenten durch den Anwender erfolgen, da dieses Feld in einer Mail nicht leer sein darf.

• Wenn ein Text hinterlegt ist, so muss dieser html formatiert sein (mit html-Tag beginnen und enden).
  

ProcessUtils.setVariable("mailBody", "<html><body>Wir freuen uns, Ihnen mitzuteilen, rückwirkend einen Rabatt in Höhe von 50% zu gewähren.</body></html>");

Mail-Priorität

Priorität der zu versendenden Serienmail.

Prüfkriterien
Mögliche Werte der Prozessvariablen  (Groß- und Kleinschreibung wird nicht berücksichtigt)

• leer bzw. nicht belegt
  Es wird der Defaultwert "Normal" verwendet.

• Low

• Normal

• High
  

ProcessUtils.setVariable("mailPrio", "High");
ProcessUtils.setVariable("mailPrio", "HIGH");

Generiere Einzelaktivitäten

Legt fest, ob pro Mailausgang eine einzelne Aktivität generiert werden soll oder lediglich eine Aktivität für die gesamte Serienmailaktion.

ProcessUtils.setVariable("multipleActivities", true);

Interne Dokumente

Liste der internen Dokumente, die an die Serienmail angehängt werden.

Prüfkriterien
Mögliche Werte der Prozessvariablen  (Groß- und Kleinschreibung wird nicht berücksichtigt)

• leer bzw. nicht belegt
  Es werden keine internen Dokumente, an die Serienmail gehängt.

• Liste von Primärschlüsseln für Dokumente

  • Alle Einträge in der Liste müssen vom Typ String sein.

  • Zu jedem Eintrag ist ein aktiver Dokumentendatensatz verfügbar.

  • Der gefundene Dokumentendatensatz ist aktuell nicht in Bearbeitung, also nicht ausgeliehen.
    

List documentPks = new ArrayList();
documentPks.add("M1be0hpk70MAS2Do");
documentPks.add("M1be0hpk70MAS1Do");
ProcessUtils.setVariable("internalDocuments", documentPks);

Externe Dokumente

Liste der externen Dokumente, die an die Serienmail angehängt werden.

Prüfkriterien
Mögliche Werte der Prozessvariablen  (Groß- und Kleinschreibung wird nicht berücksichtigt)

• leer bzw. nicht belegt
  Es werden keine externen Dokumente, an die Serienmail gehängt.

• Liste von vollständig qualifizierten Dateinamen

  • Alle Einträge in der Liste müssen vom Typ String sein.

  • Zu jedem Eintrag ist eine Datei vorhanden

  • Der Massendaten-Applikationsserver hat Zugriff auf alle Dateien der Liste
    

List documentFiles = new ArrayList();
documentFiles.add("c:\\Temp\\2307.txt ");
documentFiles.add("c:\\Temp\\Eclipse.jpg");
ProcessUtils.setVariable("externalDocuments", documentFiles);

Typ der Mailkonfiguration

Die Wahl der Mailkonfiguration kann wie folgt gesteuert werden:

• Benutzerspezifische Mailkonfiguration (ausschließlich)
  Die im Mitarbeiter hinterlegte Mailkonfiguration (Feld "Groupware Web Client" ("WebGroupwareKey.Employee")) wird verwendet.
  

  

  
  Prüfkriterien: 

  • Die dort hinterlegte Mailkonfiguration darf nicht leer sein 

  • In der Mailkonfiguration wird die serverseitige Groupwareanbindung verwendet.
    

• Systemweite Mailkonfiguration für Serienmails (ausschließlich)
  Die in den Systemeinstellungen hinterlegte Mailkonfiguration wird verwendet. 
  

  

  
  Prüfkriterien: 

  • Die dort hinterlegte Mailkonfiguration darf nicht leer sein 

  • In der Mailkonfiguration wird die serverseitige Groupwareanbindung verwendet.
    

• Benutzerspezifische Mailkonfiguration (bevorzugt)
  Die im Mitarbeiter hinterlegte Mailkonfiguration wird bevorzugt verwendet. Ist diese leer oder nicht für die serverseitige Groupwareanbindung konfiguriert, so wird die systemweite Mailkonfiguration für Serienmails verwendet
  Prüfkriterien: 

  • Die Mailkonfiguration darf nicht leer sein 

  • In der Mailkonfiguration wird die serverseitige Groupwareanbindung verwendet.
    

• Systemweite Mailkonfiguration für Serienmails (bevorzugt)
  Die in den Systemeinstellungen hinterlegte Mailkonfiguration wird bevorzugt verwendet. Ist diese leer oder nicht für die serverseitige Groupwareanbindung konfiguriert, so wird die im Mitarbeiter hinterlegte Mailkonfiguration (Feld "Groupware Web Client" ("WebGroupwareKey.Employee")) verwendet.
  Prüfkriterien: 

  • Die Mailkonfiguration darf nicht leer sein 

  • In der Mailkonfiguration wird die serverseitige Groupwareanbindung verwendet.

Das Hinterlegen einer festen Mailkonfiguration ist nicht möglich. Zur Laufzeit kann einer der vier verfügbaren Optionen per Variable gesetzt werden. 

Ausführung

Die Ausführung der Serienmailaktion erfolgt analog zu der der Serienbriefaktion. Im Falle der Nachbearbeitung kann auf die Größe der Selektionsergebnismenge zurückgegriffen werden. Darüber hinaus stehen kaum nennenswerte Information über die Serienmailaktion für die Weiterverarbeitung zur Verfügung.

Excelvorlagenaktion

Vorlagenbasierte Exceldateien können nun ebenfalls aus dem Prozess erstellt werden, die auf dem Massendaten-Server verarbeitet werden. In der Massendaten-Aktion können alle Einstellungen des Excel-Wizards, z.B. der Vorlagenname, eine Suche, der Betreff usw. aus Prozess-Variablen vorbelegt werden.

Nach Start des Prozesses wird der Excelassistent wie gewohnt dem Anwender über die Systemjobs in der Schnellstartleiste angezeigt. Der Anwender kann gegebenenfalls noch weitere Anpassungen vornehmen. Die Konfiguration kann aber auch derart gestaltet werden, dass keine Anzeige des Assistenten erfolgt und die Excelvorlagenerstellung komplett im Hintergrund abläuft.

Der Prozess wird erst fortgesetzt, wenn die Verarbeitung abgeschlossen ist bzw. abgebrochen wurde.

Konfiguration

Vor der Ausführung erfolgt zunächst eine Prüfung der Konfiguration. Ist diese nicht gültig. z.B. die hinterlegte Excelvorlage existiert nicht oder die angegebene Ausgangsentität existiert nicht  o.ä., so wird die Aktion nicht ausgeführt. Stattdessen werden alle fehlerhaften Konfigurationsparameter der Serienbriefaktion im Unterbereich "Massendatenprotokoll" der Entität "Massendatenaktion" festgehalten und der Prozess anschließend fortgesetzt. Fehler lassen sich somit im Nachhinein feststellen und für zukünftige Aktionen korrigieren.
Für die Ausführung der Excelvorlagen-Aktion müssen zwingend die nachfolgenden Variablen vorgegeben sein.

Massendatenaktion-Variable

Die Variable in der der Primärschlüssel aus dem Protokollsatz aus der Entität Massendatenaktion hinterlegt wird. Aus dem Datensatz können im Prozessfortgang Informationen zur Excelerstellung ausgelesen werden.

Serveraktionen

In wie weit Aktionen im Assistenten oder der gesamte Assistent im Hintergrund abgearbeitet werden kann über die Auswahl der Serveraktion gesteuert werden:

• Assistent öffnen
  Der Assistent wird gemäß den Vorgaben konfiguriert und wie gewohnt dem Anwender über die Systemjobs in der Schnellstartleiste angezeigt. 
  Bestehende Eingaben können durch den Anwender geändert und fehlende Eingaben noch ergänzt werden.

• Suche ausführen und Assistent öffnen
  Der Assistent wird gemäß den Vorgaben konfiguriert und die Suche wird direkt ausgeführt. Der Assistent mit bereits vorliegendem Suchergebnis wird wie gewohnt dem Anwender über die Systemjobs in der Schnellstartleiste angezeigt. Bestehende Eingaben können durch den Anwender geändert und fehlende Eingaben noch ergänzt werden.

• Alle gewählten Aktionen ausführen und Assistent öffnen
  Der Assistent wird gemäß den Vorgaben konfiguriert und die Aktionen Suche und Excel-Dokument generieren werden direkt ausgeführt. 
  Der Assistent mit den bereits ausgeführten Aktionen wird wie gewohnt dem Anwender über die Systemjobs in der Schnellstartleiste angezeigt.
  Folgende Situation findet man beim Öffnen des Assistenten vor:

  • Ausgeführte der Suche

  • Generierte Excel-Datei

  • Öffnen der Exceldatei
    Es wird die Assistentenseite zum Öffnen der Exceldatei angezeigt 

  • Es folgen die Seite (wenn die Option "als Dokumentendatensatz aktiviert ist") 

    • Anzeige der Seite für die Neuanlage des Dokumentendatensatz

    • Anzeige der Seite für die Verknüpfung des Dokumentendatensatzes  

    • Rücktransfer der Daten 
      Ist ein Rücktransfer in der Excelvorlage konfiguriert, so wird der Anwender immer aufgefordert, die Exceldatei zu öffnen um noch Änderungen vor dem Rücktransfer vornehmen zu können.
      Anschließend können die Aktionen "Dokumentendatensatz anlegen" und "Transfer von Daten aus Excel nach CRM" im Assistenten aufgerufen werden.

  • Anzeige der Assistentenseite "Ergebnis"

• Alle gewählten Aktionen ausführen ohne Assistent ausführen
  Der Assistent wird gemäß den Vorgaben konfiguriert und die gewählten Aktionen werden direkt ausgeführt. Der Prozess wird nach Ausführung direkt fortgesetzt.
  Im Idealfall erfolgt keine Anzeige des Assistenten, außer das Öffnen der Exceldatei ist erforderlich. Unter folgenden Bedingungen wird die Assistentenseite zum Öffnen der Exceldatei angezeigt:

  • Die generierte Exceldatei enthält ein Makro.
    Hintergrund: Die Ausführung des Makros kann nur auf dem Client erfolgen.

  • In der Excelvorlage ist der Rücktransfer der Daten konfiguriert.
    Hintergrund: Der Anwender kann somit noch Änderungen an der Exceldatei vor dem Rücktransfer ins CRM vornehmen. 

Vorlagenname

Der Excelvorlage ist erforderlich und bestimmt die Art der Verarbeitung

Prüfkriterien

• Die Excel-Dokumentvorlage muss existieren und aktiv sein

• basiert auf der Generierungsvariante "NATIVE"
  

ProcessUtils.setVariable("docTemplateName", "Name der Excelvorlage");

Suche

Die Suche kann als ISearch Objekt vorbelegt werden. Die Hauptsuche des Suchbehälters der Serienbriefvorlage wird durch die übergebene Suche ersetzt.
Ist die zugehörige Prozessvariable nicht belegt, so wird der unveränderte Suchbehälter aus der Serienbriefvorlage verwendet

Prüfkriterien
Mögliche Werte der Prozessvariablen

• leer bzw. nicht belegt 

• Objekt des Typs ISearch
  Entitätsname und die Suchergebnisfelder der Suche müssen mit denen der Hauptsuche des Suchbehälters aus der Serienbriefvorlage übereinstimmen.
  
  

//Laden der Hauptsuche des Suchbehälters
ISearch search = DocumentUtils.getMainSearch("Name der Excelvorlage");
SearchUtils.addSearchCondition(search, SearchUtils.createSearchCondition("TradeKey.Customer", false, true, SearchUtils.EQUAL, LookupUtils.toLookup("S_BRA-CB")));
 
ProcessUtils.setVariable("search", search);

Sortierung der Datenmenge

Die Sortierreihenfolge für die Selektionsergebnismenge kann als ISortOrder Objekt beim Serienbrief vorgegeben werden. Die Sortierung wird bei der Ausgabe in der Exceldatei berücksichtigt.
Die Sortierung erfolgt im Standard immer aufsteigend, kann aber mit Hilfe des optionalen Parameters sortOrderDescending auch absteigend erfolgen.
Erzeugt wird das Objekt mit Hilfe der Methode MassDataUtils.createSortOrder(String searchAliasName, String attributeName, boolean sortOrderDescending).
Folgende Methoden stehen in dem Rückgabeobjekt ISortOrder zur Verfügung

• void addSortField(String searchAliasName, String attributeName)
  Erweitern der Sortierung um ein zusätzliches Sortierfeld

• void addSortField(String searchAliasName, String attributeName, boolean sortOrderDescending)
  Erweitern der Sortierung um ein zusätzliches Sortierfeld mit angegebener Sortierrichtung (absteigend / aufsteigend)

Prüfkriterien
Mögliche Werte der Prozessvariablen

• leer bzw. nicht belegt 

• Objekt des Typs ISortOrder
  Dieses enthält die Liste der Sortierfelder. Für die Sortierfelder gelten folgende Prüfkriterien.

  • Der Suchaliasname muss in dem der Dokumentvorlage zugeordneten Suchbehälter existieren.

  • In der zum Suchaliasnamen zugehörigen Suche muss der Feldname (AttributeName) vorhanden sein. Ist der Feldname mehrfach vorhanden, so wird der erste gefundene Feldname als Sortierfeld verwendet.
    

// Konfiguration einer Sortierung über vier Felder
ISortOrder sortOrder = MassDataUtils.createSortOrder("ADR", "ZIPKey.Address", true);
sortOrder.addSortField("GP", "Name1.Customer");
sortOrder.addSortField("Ansprech", "LastName.ContactPerson");
sortOrder.addSortField("Ansprech", "FirstName.ContactPerson", true);
 
// Zuordung zu einer Prozessvariablen vom Typ Object für weitere Verwendung innerhalb der Massendatenaktion 'Serienbrief'
ProcessUtils.setVariable("sortOrder", sortOrder);

Dokument anlegen

Die generierte Exceldatei als Dokumentendatensatz im CRM speichern

Prüfkriterien

Mögliche Werte der Prozessvariablen

• nein bzw. nicht belegt - es wird kein Dokumentendatensatz erzeugt

• ja  - es wird ein Dokumentendatensatz erzeugt
  Es müssen die folgenden Dokumentvariablen befüllt werden:

  • Ausgangsentität

  • Primärschlüssel Ausgangsentität

  • Dokumentenbetreff (Sofern als Server-Aktion "Alle Aktionen ausführen ohne Assistent" gewählt ist. Ansonsten kann der Anwender den Wert immer über den Assistenten pflegen)
    

ProcessUtils.setVariable("createDocument", true);

Ausgangsentität 

Der Dokumentendatensatz muss mit einem anderen Datensatz (Elterndatensatz) verknüpft werden. Es wird die Entität des Elterndatensatzes angegeben

Prüfkriterien
Wenn das Anlegen eines Dokuments oder der Rücktransfer konfiguriert ist, muss dieser Parameter gefüllt werden.

Mögliche Werte der Prozessvariablen

• leer, nicht belegt - nur gültig wenn kein Dokumentendatensatz erzeugt wird

• Name einer existierenden Entität, die eine n:m-Relation zu Dokumenten besitzt
  

ProcessUtils.setVariable("parentEntity", "Activity");

Primärschlüssel Ausgangsentität 

Der Dokumentendatensatz muss mit einem anderen Datensatz (Elterndatensatz) verknüpft werden. Es wird der Primärschlüssel des Elterndatensatzes angegeben.

Prüfkriterien
Wenn das Anlegen eines Dokuments oder der Rücktransfer konfiguriert ist, muss dieser Parameter gefüllt werden.

Mögliche Werte der Prozessvariablen

• leer, nicht belegt - nur gültig wenn kein Dokumentendatensatz erzeugt wird

• Primärschlüssel eines existierenden Datensatzes aus der obigen Entität
  

ProcessUtils.setVariable("parentPk", "othknp1e195610mAc");

Dokumentenbetreff 

Betreff des erzeugten Dokumentendatensatzes

Prüfkriterien
Wenn das Anlegen eines Dokuments konfiguriert ist, muss dieser Parameter gefüllt werden.

Mögliche Werte der Prozessvariablen

• leer, nicht belegt - nur gültig wenn:

  • kein Dokumentendatensatz erzeugt wird

  • oder als Server-Aktion mit Assistent gewählt ist. In einem solchen Fall kann der Anwender den Wert über den Assistenten pflegen

• beliebiger Text
  

ProcessUtils.setVariable("docSubject", "Kalkulation");

Stichwort 

Stichwort des erzeugten Dokumentendatensatzes    (optionaler Parameter)

Prüfkriterien
Mögliche Werte der Prozessvariablen

• leer, nicht belegt 

• beliebiger Text
  

ProcessUtils.setVariable("headword", "meine Stichworte");

Kategorie 

Kategorie des erzeugten Dokumentendatensatzes    (optionaler Parameter)

Prüfkriterien
Mögliche Werte der Prozessvariablen

• leer, nicht belegt 

• gültiger Primärschlüssel einer Dokumentenkategorie
  

ProcessUtils.setVariable("category", "EB-DOCCAT");

Verknüpfen mit allen Geschäftspartnern 

Der erzeugte Dokumentendatensatz soll mit allen Geschäftspartnern des Elterndatensatzes verknüpft werden.

Prüfkriterien
Mögliche Werte der Prozessvariablen

• false bzw. nicht belegt 
  Der erzeugte Dokumentendatensatz wird mit keinem Geschäftspartner des Elterndatensatzes verknüpft.

• true
  Der erzeugte Dokumentendatensatz wird mit allen Geschäftspartnern des Elterndatensatzes verknüpft.
  

ProcessUtils.setVariable("linkCu", true);

Verknüpfen mit allen Ansprechpartnern 

Der erzeugte Dokumentendatensatz soll mit allen Ansprechpartnern des Elterndatensatzes verknüpft werden.

Prüfkriterien
Mögliche Werte der Prozessvariablen

• false bzw. nicht belegt 
  Der erzeugte Dokumentendatensatz wird mit keinem Ansprechpartner des Elterndatensatzes verknüpft.

• true
  Der erzeugte Dokumentendatensatz wird mit allen Ansprechpartnern des Elterndatensatzes verknüpft.
  

ProcessUtils.setVariable("linkCoPe", true);

Ausführung

Mit Start der Massendatenaktion "Excelvorlage" wird zunächst eine Konfiguration für die Aktion erstellt und geprüft. Sofern die Prüfung erfolgreich war, wird die Generierungsaktion gestartet. Je nach gewählter Serveraktion werden vorab bereits einige Aktionen auf dem Massendatenserver ausgeführt und das Ergebnis wie gewohnt dem Anwender über die Systemjobs in der Schnellstartleiste angezeigt. 

Einige Beispiele zur Anzeige des Assistenten in Abhängigkeit der gewählten Serveraktion

• "Suche ausführen und Assistent öffnen"
  

  

  
  
  

• Serveraktion "Alle gewählten Aktionen ausführen und Assistent öffnen"
  

  

  
  
  

• Serveraktion "Alle gewählten Aktionen ausführen ohne Assistent" bei generierter Exceldatei mit Makro oder Rücktransfer
  

  

Die Konfiguration kann aber auch derart gestaltet werden, dass keine Anzeige des Assistenten erfolgt und die Excel-Generierung komplett im Hintergrund abläuft, sofern keine Makros in der generierten Exceldatei ausgeführt werden und kein Rücktransfer konfiguriert ist.

Mit Fertigstellen des Assistenten oder nach Abarbeitung aller Aktionen im Hintergrund (ohne Assistent) wird der Prozess fortgesetzt.
Falls das generierte Excel-Dokument als Dokumentendatensatz im CRM gespeichert wurde, steht der Dokumenten Primärschlüssel im Feld "ExportSubDir.MassDataTask" zur Verfügung. Die Nachbearbeitung im Prozess könnte wie folgt aussehen.

Beispiel für die Nachverarbeitung

String massDataTaskPk = ProcessUtils.getVariable("massDataPk");
IContainer massDataTask = WorkSpaceScriptUtils.searchEntryForRead(massDataTaskPk, "MassDataTask");
int resultCount = WorkSpaceScriptUtils.getValue(massDataTask, "ResultCount.MassDataTask");  
String docPk = WorkSpaceScriptUtils.getValue(massDataTask, "ExportSubDir.MassDataTask");
ProcessUtils.setVariable("resultCount", resultCount);  
ProcessUtils.setVariable("docPk", docpk);
 
// z.B. Weiterverarbeitung der Prozessvariablen 'docPk' und 'resultCount' in einer Nachricht o.ä.

Fehlerfallbehandlung

Sofern die Prüfung der Konfiguration nicht erfolgreich war, wird die Generierungsaktion nicht gestartet, sondern sogleich beendet. Alle Fehlkonfigurationen werden in dem Unterbereich "Massendatenprotokoll" zur aktuellen "Massendatenaktion" gespeichert. Somit ist eine Korrektur des BPM-Prozesses im Nachgang recht einfach möglich. 
Der Prozess wird in einem solchen Fehlerfall nicht abgebrochen, sondern fortgesetzt.