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.
![](../../../__attachments/8096040/CRM-5404_Massendaten_Prozess_Alt.png?inst-v=01ce9f95-f40d-424e-a7da-0f3a4bad5824)
Für die einzelnen Probleme gab es meistens einen umständlichen Lösungsweg:
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.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.
Ein weiteres Problem ist die Datenhaltung im Prozess. Die Suchergebnismenge von 10000 als Prozess-Variable zu halten, belegt sehr viele Ressourcen des CRM-Systems.
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.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.
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.
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
![](../../../__attachments/8096040/bpm.palette.48x48.MassDataTask.png?inst-v=01ce9f95-f40d-424e-a7da-0f3a4bad5824)
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.
![](../../../__attachments/8096040/CRM-5404_Massendaten_Prozess_Neu.png?inst-v=01ce9f95-f40d-424e-a7da-0f3a4bad5824)
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.
![](../../../__attachments/8096040/20181031_MassDataActionConfig.png?inst-v=01ce9f95-f40d-424e-a7da-0f3a4bad5824)
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. Bestehende Prozess-Variablen kann man aber in der Massendatendaten-Aktion auslesen.
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.
![](../../../__attachments/8096040/CRM-5404_SerialletterConfig.png?inst-v=01ce9f95-f40d-424e-a7da-0f3a4bad5824)
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 istExport 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 Sortierfeldvoid 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 verwendetDocumentUtils.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 verwendetLookupVO
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 werdenSERIALEmployeeSales
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
![](../../../__attachments/8096040/FrageDialog.png?inst-v=01ce9f95-f40d-424e-a7da-0f3a4bad5824)
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.
![](../../../__attachments/8096040/Massendatenaktion.png?inst-v=01ce9f95-f40d-424e-a7da-0f3a4bad5824)
![](../../../__attachments/8096040/Massendatenprotokoll.png?inst-v=01ce9f95-f40d-424e-a7da-0f3a4bad5824)
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.
![](../../../__attachments/8096040/MassendatenAktionKonfigurieren.png?inst-v=01ce9f95-f40d-424e-a7da-0f3a4bad5824)
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.
![](../../../__attachments/8096040/image2023-4-17_6-18-57.png?inst-v=01ce9f95-f40d-424e-a7da-0f3a4bad5824)
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 angezeigtEs 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 Sortierfeldvoid 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.
![](../../../__attachments/8096040/image2023-4-17_14-46-4.png?inst-v=01ce9f95-f40d-424e-a7da-0f3a4bad5824)
![](../../../__attachments/8096040/image2023-4-17_14-48-17.png?inst-v=01ce9f95-f40d-424e-a7da-0f3a4bad5824)