Serienbriefaktion

Grundlagen

Serienbriefe können direkt aus einem BPM-Prozess heraus erstellt und auf dem Massendaten-Server verarbeitet werden. Hierfür wird eine Massendaten-Aktion vom Typ „Serienbrief“ verwendet.

In der Massendaten-Aktion können alle Einstellungen des Serienbrief-Assistenten aus Prozessvariablen vorbelegt werden, z. B.:

Vorlagenname
Suche
Betreff
Ausgabeformat
Aktivitäten-Konfiguration
Exportunterverzeichnis usw.

Nach Start des Prozesses wird der Serienbrief-Assistent wie gewohnt als Systemjob in der Schnellstartleiste angezeigt. Der Anwender kann – je nach Konfiguration – noch Anpassungen vornehmen.
Die Konfiguration kann auch so gestaltet werden, dass kein Assistent angezeigt wird und die Serienbrieferstellung vollständig im Hintergrund abläuft.

Der BPM-Prozess wird immer erst fortgesetzt, wenn die Serienbriefverarbeitung abgeschlossen oder abgebrochen wurde.

Konfiguration und Validierung

Vor der eigentlichen Ausführung erfolgt eine Prüfung der Konfiguration der Serienbrief-Massendatenaktion.

Ist die Konfiguration ungültig (z. B. nicht vorhandene Serienbriefvorlage), wird die Serienbriefaktion nicht ausgeführt. Alle fehlerhaften Konfigurationsparameter werden im Unterbereich „Massendatenprotokoll“ der Entität „Massendatenaktion“ protokolliert.

Anschließend wird der Prozess normal fortgesetzt. Fehler lassen sich damit im Nachhinein nachvollziehen und für zukünftige Aktionen korrigieren.

Für die Ausführung der Serienbrief-Aktion müssen bestimmte Pflichtvariablen gesetzt sein, u. a. die Massendatenaktions-Variable, Vorlagenname und – je nach Serveraktion – weitere Parameter.

Massendatenaktion-Variable

In einer definierten Prozessvariablen wird der Primärschlüssel des Protokollsatzes aus der Entität Massendatenaktion gespeichert. Aus diesem Datensatz können im weiteren Prozessverlauf Informationen zur Serienbrieferstellung ausgelesen werden (z. B. Ergebnisanzahl, Exportverzeichnis).

Serveraktionen (Steuerung des Assistenten)

Über die Serveraktion wird gesteuert, in welchem Umfang der Serienbrief-Assistent und seine Aktionen im Hintergrund ausgeführt werden und dem Anwender angezeigt werden.

Folgende Serveraktionen stehen zur Verfügung:

Assistent öffnen
- Der Assistent wird gemäß den Vorgaben vorkonfiguriert.
- Er erscheint wie gewohnt als Systemjob in der Schnellstartleiste.
- Voreinstellungen können vom Anwender geändert und fehlende Eingaben ergänzt werden.
Suche ausführen und Assistent öffnen
- Der Assistent wird vorkonfiguriert und die Suche wird direkt ausgeführt.
- Der Assistent öffnet sich mit einem bereits vorhandenen Suchergebnis.
- Voreinstellungen können weiterhin geändert bzw. ergänzt werden.
Alle gewählten Aktionen ausführen und Assistent öffnen
- Der Assistent wird vorkonfiguriert und alle gewählten Aktionen werden direkt auf dem Massendatenserver ausgeführt.
- Der Assistent öffnet sich mit bereits durchgeführten Aktionen als Systemjob.
- Noch nicht ausgeführte Aktionen (z. B. Aktivitätengenerierung, Dokumentenexport) können vom Anwender nachträglich gestartet werden.
Zu den möglichen Aktionen gehören u. a.:
- Ausführung der Suche (immer)
- Generierung der Dokumente (immer)
- Generierung von Protokoll- und Erinnerungsaktivität
  - nur, wenn die zugehörigen Prozessvariablen „Protokollaktivität“ bzw. „Erinnerungsaktivität“ mit einer Aktivität vorbelegt sind
- Export der Dokumente
  - nur, wenn die Prozessvariable „Exportunterverzeichnis“ vorbelegt ist
Alle gewählten Aktionen ausführen ohne Assistent öffnen
- Der Assistent wird im Hintergrund konfiguriert und alle gewählten Aktionen werden vollständig im Hintergrund ausgeführt.
- Es erfolgt keine Anzeige des Assistenten.
- Nach Abschluss der Serienbrieferstellung wird der Prozess direkt fortgesetzt.

Vorlagenname (Serienbriefvorlage)

Die Serienbriefvorlage bestimmt die Art der Serienbriefverarbeitung. In einer Prozessvariablen (z. B. docTemplateName) wird der Name der gewünschten Dokumentvorlage hinterlegt.

Es werden zwei Typen unterschieden:

Serienbrief mit Einzeldokumenten
- Verwendung bestehender Serienbriefvorlagen.
- Das Attribut „Einzeldokumente generierbar“ muss in der Vorlage aktiviert sein.
Serienbrief für Massendaten
- Verwendung spezieller, „nativer“ Vorlagen des Vorlagentyps „Massendaten“.

Prüfkriterien

Die Dokumentvorlage muss existieren und aktiv sein.
Der Dokumentvorlagentyp muss den o. g. Kriterien entsprechen.

Beispiel:

GROOVY

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

Suche

Die für den Serienbrief verwendete Suche kann über eine Prozessvariable vom Typ ISearch vorbelegt werden. In diesem Fall wird die Hauptsuche des Suchbehälters der Serienbriefvorlage durch die übergebene Suche ersetzt.

Ist die Prozessvariable nicht belegt, wird die unveränderte Hauptsuche aus der Vorlage verwendet.

Prüfkriterien – mögliche Werte der Prozessvariablen

leer / nicht belegt
Objekt des Typs ISearch

Für eine gültige ISearch-Instanz gilt: Entitätsname und Suchergebnisfelder müssen mit denen der Hauptsuche aus dem zur Vorlage gehörenden Suchbehälter übereinstimmen.

Beispiel:

GROOVY

// 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 der Ergebnisdaten kann über eine Prozessvariable vom Typ ISortOrder vorgegeben werden.
Die Sortierung beeinflusst u. a. die Reihenfolge der Einzeldokumente, z. B. Sortierung nach PLZ zur Versandoptimierung.

Standardmäßig wird aufsteigend sortiert.
Über den Parameter sortOrderDescending kann eine absteigende Sortierung definiert werden.

Erzeugt wird das ISortOrder-Objekt über:

GROOVY

ISortOrder MassDataUtils.createSortOrder(String searchAliasName,
                                         String attributeName,
                                         boolean sortOrderDescending)

Weitere Sortierfelder können hinzugefügt werden:

void addSortField(String searchAliasName, String attributeName)
void addSortField(String searchAliasName, String attributeName, boolean sortOrderDescending)

Prüfkriterien – mögliche Werte der Prozessvariablen

leer / nicht belegt
- Es wird die Standardsortierung (falls vorhanden) verwendet.
Objekt des Typs ISortOrder

Für jedes Sortierfeld gilt:

Der Suchaliasname muss im Suchbehälter der Dokumentvorlage vorhanden sein.
In der zugehörigen Suche muss das angegebene Attribut (Feldname) vorhanden sein. Ist das Feld mehrfach vorhanden, wird das erste Vorkommen verwendet.

Beispiel:

GROOVY

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

// Zuordnung zu einer Prozessvariablen für die Serienbrief-Massendatenaktion
ProcessUtils.setVariable("sortOrder", sortOrder);

Dokumentenbetreff

Der Betreff der erzeugten Dokumente wird in einer Prozessvariable (z. B. docSubject) hinterlegt.

Prüfkriterien

Wenn die Dokumentgenerierung direkt ausgeführt wird (Serveraktion = „Alle gewählten Aktionen ausführen …“), muss der Betreff gesetzt sein (Pflichtfeld).
Andernfalls kann der Betreff im Assistenten eingegeben werden.

Beispiel:

GROOVY

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

Ausgabeformat

Das Ausgabeformat der Serienbriefdokumente kann über eine Prozessvariable (z. B. saveFormat) gesteuert werden.

Prüfkriterien – mögliche Werte der Prozessvariablen

leer / nicht belegt → das Ausgabeformat aus der Dokumentvorlage wird verwendet.
DocumentUtils.DOC_SAVEFORMAT_DOC
DocumentUtils.DOC_SAVEFORMAT_DOCX
DocumentUtils.DOC_SAVEFORMAT_PDF

Beispiel:

GROOVY

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

Protokoll-/Erinnerungsaktivität

Die zu erzeugende Protokoll- bzw. Erinnerungsaktivität kann über eine Prozessvariable (z. B. protocolActivity bzw. reminderActivity) vorkonfiguriert werden. Dabei können die Felder der Aktivitätenerfassungsseite im Assistenten vorbefüllt werden, z. B.:

Betreff (Subject.Activity)
Text (Text.Activity)
Beginnt am (StartDate.Activity)
Priorität (Priority.Activity)
Anlass (ContactReason.Activity)
Ergebnis (ContactResult.Activity)
Art (ActTypeKey.Activity)
weitere Felder wie FreeText1.Activity, FreeNumber1.Activity, FreeDate1.Activity etc.

Bleibt die zugehörige Prozessvariable leer, wird keine Aktivität erzeugt.

Prüfkriterien – mögliche Werte der Prozessvariablen

leer / nicht belegt → es wird keine Aktivität erzeugt.
IContainer des Typs Aktivität

Für den Inhalt des IContainer:

Attribute „Priorität“, „Anlass“, „Ergebnis“, „Art“:
- leer / nicht vorhanden: es wird der Defaultwert des Feldes verwendet
- LookupVO: der Primärschlüssel im Lookup wird auf Gültigkeit geprüft
Attribut „Betreff“ (Subject.Activity):
- Bei direkter Aktivitätenerzeugung (Serveraktion = „Alle gewählten Aktionen ausführen …“) muss der Betreff gesetzt sein.
- Andernfalls kann der Betreff im Assistenten eingegeben werden.
Attribut „Beginnt am“ (StartDate.Activity):
- leer / nicht vorhanden: Default (z. B. aktueller Zeitstempel + definierte Zeitspanne)
- Date oder Timestamp sind zulässig.

Weitere Hinweise:

Primärschlüssel und Felder aus dem TableTail (z. B. CreateUser) werden ignoriert.
Bei Entitätsnachschlagefeldern wird der Primärschlüssel der Zielentität übergeben.
Bei Schlüsselnachschlagefeldern ist ein LookupVO (z. B. via LookupUtils.toLookup(...)) erforderlich.

Beispiel:

GROOVY

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

// Zuordnung zur Prozessvariablen
ProcessUtils.setVariable("protocolActivity", activityAC);

Mitarbeiterzuordnung

Die Mitarbeiterzuordnung der zu erzeugenden Protokoll- bzw. Erinnerungsaktivität kann über eine Prozessvariable (z. B. protocolActivityEmployees) vorkonfiguriert werden.

Prüfkriterien – mögliche Werte der Prozessvariablen

leer / nicht belegt → es wird die Defaultzuordnung verwendet: Der aktuelle Mitarbeiter wird als „delegiert von“ mit Beziehung „Empfänger“ zugeordnet.
Liste von IContainer des Typs Mitarbeiter (Employee):
- Alle Listeneinträge müssen IContainer mit Entität Employee sein.
- Der Primärschlüssel muss gefüllt und gültig sein:
  - Entweder existiert ein aktiver Mitarbeitersatz mit diesem Primärschlüssel
  - oder der Primärschlüssel ist eine Mitarbeitervariable, die im Mapping der Vorlage verwendet wird, z. B.:
    - SERIALEmployeeSales
    - SERIALEmployeeKey
    - SERIALEmployeeQuote
    - SERIALEmployeeExtra1
    - SERIALEmployeeExtra2
- Attribut „Beziehungstyp Mitarbeiter“ (RelationTypeKeyEm.Employee):
  - leer / nicht belegt: es wird die Defaultbeziehung „Empfänger“ verwendet
  - LookupVO: Primärschlüssel wird geprüft
- Attribut „Delegiert von“ (DelegatedByFlag.Employee):
  - Darf in der Liste insgesamt nur einmal gesetzt sein.
- Attribut „Delegiert an“ (DelegatedToFlag.Employee):
  - Darf in der Liste insgesamt nur einmal gesetzt sein.

Beispiel (drei Mitarbeiter):

GROOVY

// Mitarbeiter 1: "delegiert von"
IContainer employeeACDelBy = WorkSpaceScriptUtils.createEmptyEntry("Employee", "employee1");
WorkSpaceScriptUtils.setValue(employeeACDelBy, "RelationTypeKeyEm.Employee", LookupUtils.toLookup("ACTIVITY_EM_ROLE_TYPE-TO"));
WorkSpaceScriptUtils.setValue(employeeACDelBy, "DelegatedByFlag.Employee", true);

// Mitarbeiter 2: "delegiert an" mit Mitarbeitervariable aus dem Mapping
IContainer employeeACDelTo = WorkSpaceScriptUtils.createEmptyEntry("Employee", "SERIALEmployeeSales");
WorkSpaceScriptUtils.setValue(employeeACDelTo, "RelationTypeKeyEm.Employee", LookupUtils.toLookup("ACTIVITY_EM_ROLE_TYPE-TO"));
WorkSpaceScriptUtils.setValue(employeeACDelTo, "DelegatedToFlag.Employee", true);

// Mitarbeiter 3: weiterer Empfänger (z. B. BCC)
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

Das Exportunterverzeichnis gibt an, in welchem Unterordner die Einzeldokumente der Serienbrieferstellung abgelegt werden. Technisch werden die Dokumente in ein benutzerspezifisches Unterverzeichnis pro Serienbriefaktion exportiert.

Ist kein Unterverzeichnisname angegeben, ist eine vollständige Hintergrundausführung ohne Assistent nicht möglich. In diesem Fall wird der Assistent automatisch geöffnet.

Beispiel:

GROOVY

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

Ausführung und Nachverarbeitung im Prozess

Mit Start der Massendatenaktion „Serienbrief“ wird zunächst die Konfiguration erstellt und geprüft.
Bei erfolgreicher Prüfung wird die Serienbriefaktion gestartet. Je nach gewählter Serveraktion:

werden bereits Teilschritte im Hintergrund auf dem Massendatenserver ausgeführt (Suche, Dokumentgenerierung, Export, Aktivitäten) und
der Assistent entsprechend vorkonfiguriert angezeigt oder komplett unterdrückt.

Beispiele für eine Assistent-Anzeige:

Serveraktion „Suche ausführen und Assistent öffnen“
Serveraktion „Alle gewählten Aktionen ausführen und Assistent öffnen“ bei nicht konfiguriertem Exportunterverzeichnis

Der Anwender kann im Assistenten – falls sichtbar – Anpassungen vornehmen und ggf. weitere Aktionen starten (z. B. Export).

Ist die Konfiguration so gewählt, dass kein Assistent verwendet wird, erfolgt die gesamte Serienbrieferstellung im Hintergrund.

Nach Abschluss des Assistenten (bei sichtbarer Ausführung) oder der Hintergrundverarbeitung (bei unsichtbarer Ausführung) wird der BPM-Prozess fortgesetzt.

Beispiel für eine Nachverarbeitung im Prozess

GROOVY

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

// Beispiel: Weiterverarbeitung von 'resultCount' und 'exportDir',
// z. B. in einer Nachricht oder E-Mail

Fehlerfallbehandlung

Schlägt die Konfigurationsprüfung der Serienbrief-Massendatenaktion fehl, wird die Serienbriefaktion nicht gestartet, sondern direkt beendet. Alle Fehlkonfigurationen werden im Unterbereich „Massendatenprotokoll“ zur aktuellen Massendatenaktion gespeichert. Der BPM-Prozess selbst wird nicht abgebrochen, sondern fortgesetzt.

Dadurch ist eine nachträgliche Analyse und Korrektur der BPM-Konfiguration gut möglich, ohne den Prozesslauf generell zu blockieren.