Excel-Vorlagen-Aktion

Mit der Excelvorlagen-Aktion können aus einem Geschäftsprozess heraus Excel-Dateien auf Basis von Dokumentvorlagen erstellt werden. Die Verarbeitung erfolgt auf dem Massendaten-Server.

Alle Einstellungen des Excel-Assistenten (z. B. Vorlagenname, Suche, Betreff) können aus Prozessvariablen vorbelegt werden. Nach Start des Prozesses wird – je nach Konfiguration – der Excel-Assistent wie gewohnt über die Systemjobs in der Schnellstartleiste angezeigt. Der Anwender kann dort Einstellungen prüfen und ggf. anpassen. Alternativ kann die Ausführung vollständig im Hintergrund erfolgen, ohne dass ein Assistent angezeigt wird.

Der Prozess wird erst dann fortgesetzt, wenn die Excelverarbeitung abgeschlossen oder abgebrochen wurde.

Konfiguration

Vor der Ausführung prüft die Aktion zunächst ihre Konfiguration. Ist diese ungültig (z. B. Excelvorlage existiert nicht, Ausgangsentität existiert nicht), wird die Aktion nicht ausgeführt. Stattdessen werden alle fehlerhaften Konfigurationsparameter im Unterbereich „Massendatenprotokoll“ der Entität „Massendatenaktion“ dokumentiert. Anschließend wird der Prozess normal fortgesetzt.

So lassen sich Konfigurationsfehler im Nachgang erkennen und für künftige Ausführungen korrigieren. Für die Ausführung der Excelvorlagen-Aktion müssen bestimmte Prozessvariablen gesetzt sein.

Massendatenaktion-Variable

In dieser Prozessvariablen wird der Primärschlüssel des Protokollsatzes aus der Entität Massendatenaktion gespeichert. Über diesen Datensatz können im weiteren Prozessverlauf Details zur Excel-Erstellung ausgelesen werden.

Serveraktionen

Über die Serveraktion wird gesteuert, welche Schritte im Hintergrund ausgeführt werden und ob der Assistent angezeigt wird.

Varianten:

Assistent öffnen
- Der Assistent wird gemäß Konfiguration vorbelegt.
- Er erscheint dem Anwender über die Systemjobs in der Schnellstartleiste.
- Alle vorbelegten Eingaben können geändert, fehlende Eingaben ergänzt werden.
Suche ausführen und Assistent öffnen
- Zusätzlich wird die konfigurierte Suche direkt auf dem Massendaten-Server ausgeführt.
- Der Assistent öffnet sich mit bereits vorhandenem Suchergebnis.
- Der Anwender kann alle Werte wie gewohnt prüfen und anpassen.
Alle gewählten Aktionen ausführen und Assistent öffnen
- Der Assistent wird konfiguriert.
- Die Aktionen „Suche ausführen“ und „Excel-Dokument generieren“ werden bereits im Hintergrund ausgeführt.
- Öffnet der Anwender den Assistenten, findet er folgenden Zustand vor:
  - Suche wurde ausgeführt
  - Excel-Datei wurde generiert
  - Assistentenseite „Excel öffnen“ wird angezeigt
  - Falls „als Dokumentendatensatz“ aktiviert ist, folgen:
    - Seite zur Neuanlage eines Dokumentendatensatzes
    - Seite zur Verknüpfung des Dokumentendatensatzes
    - ggf. Rücktransfer-Seite:
      - Ist in der Excelvorlage ein Rücktransfer konfiguriert, wird der Anwender aufgefordert, die Exceldatei zu öffnen, um noch Änderungen vorzunehmen.
      - Anschließend können die Aktionen „Dokumentendatensatz anlegen“ und „Daten aus Excel nach CRM übertragen“ im Assistenten ausgeführt werden.
  - Abschließend die Assistentenseite „Ergebnis“
Alle gewählten Aktionen ausführen ohne Assistent
- Der Assistent wird intern konfiguriert, aber dem Anwender nicht angezeigt.
- Alle gewählten Aktionen werden direkt im Hintergrund ausgeführt.
- Der Prozess wird danach ohne Benutzereingriff fortgesetzt.
- Der Assistent wird nur dann angezeigt, wenn:
  - die generierte Exceldatei ein Makro enthält
    (Makros können nur clientseitig ausgeführt werden), oder
  - ein Rücktransfer in der Excelvorlage konfiguriert ist
    (der Anwender soll die Datei vor dem Rücktransfer noch bearbeiten können).

Vorlagenname

Der Name der verwendeten Excel-Dokumentvorlage. Diese Angabe ist Pflicht und bestimmt die Art der Verarbeitung.

Prüfkriterien:

Die Excel-Dokumentvorlage muss existieren und aktiv sein.
Die Vorlage muss auf der Generierungsvariante „NATIVE“ basieren.

GROOVY-Beispiel

GROOVY

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

Suche

Über diese Variable können Sie eine Suche als ISearch-Objekt vorbelegen.
Die Hauptsuche des Suchbehälters der Excelvorlage wird dabei durch die übergebene Suche ersetzt.

Ist die Prozessvariable leer, wird die in der Vorlage konfigurierte Hauptsuche unverändert verwendet.

Mögliche Werte:

nicht belegt (leer)
Objekt vom Typ ISearch

Zusätzliche Prüfkriterien für ISearch:

Entitätsname und Ergebnisfelder müssen mit der Hauptsuche des Suchbehälters der Excelvorlage übereinstimmen.

GROOVY-Beispiel

GROOVY

// Hauptsuche des Suchbehälters der Vorlage laden
ISearch search = DocumentUtils.getMainSearch("Name der Excelvorlage");

// Bedingung hinzufügen
SearchUtils.addSearchCondition(
    search,
    SearchUtils.createSearchCondition(
        "TradeKey.Customer",
        false,
        true,
        SearchUtils.EQUAL,
        LookupUtils.toLookup("S_BRA-CB")
    )
);

// Suche als Prozessvariable setzen
ProcessUtils.setVariable("search", search);

Sortierung der Datenmenge

Mit dieser Variable legen Sie die Sortierreihenfolge der Ergebnismenge fest. Die Sortierung wird in der generierten Exceldatei berücksichtigt.

Standardmäßig erfolgt die Sortierung aufsteigend. Über den Parameter sortOrderDescending kann eine absteigende Sortierung angegeben werden.

Das Sortierobjekt wird mit MassDataUtils.createSortOrder(String searchAliasName, String attributeName, boolean sortOrderDescending) erzeugt und hat den Typ ISortOrder.

Methoden von ISortOrder:

void addSortField(String searchAliasName, String attributeName)
weiteres Sortierfeld (aufsteigend) hinzufügen
void addSortField(String searchAliasName, String attributeName, boolean sortOrderDescending)
weiteres Sortierfeld mit expliziter Sortierrichtung hinzufügen

Mögliche Werte der Prozessvariablen:

leer / nicht belegt
Objekt vom Typ ISortOrder mit einer Liste von Sortierfeldern

Prüfkriterien für Sortierfelder:

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

GROOVY-Beispiel

GROOVY

// Sortierung über vier Felder konfigurieren
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 zur Prozessvariablen für die Massendatenaktion
ProcessUtils.setVariable("sortOrder", sortOrder);

Dokument anlegen

Steuert, ob die generierte Exceldatei als Dokumentendatensatz im CRM gespeichert wird.

Mögliche Werte:

false oder nicht belegt → es wird kein Dokumentendatensatz angelegt
true → es wird ein Dokumentendatensatz angelegt

Ist der Wert true, müssen zusätzlich folgende Variablen befüllt werden:

Ausgangsentität
Primärschlüssel Ausgangsentität
Dokumentenbetreff
(sofern als Serveraktion „Alle Aktionen ausführen ohne Assistent“ gewählt ist;
bei Varianten mit Assistent kann der Anwender den Betreff im Assistenten pflegen)

GROOVY-Beispiel

GROOVY

ProcessUtils.setVariable("createDocument", true);

Ausgangsentität

Entität des Elterndatensatzes, mit dem der Dokumentendatensatz verknüpft werden soll.

Pflichtfeld, wenn:

ein Dokumentendatensatz angelegt wird, oder
ein Rücktransfer konfiguriert ist.

Mögliche Werte:

leer / nicht belegt → nur zulässig, wenn kein Dokumentendatensatz erzeugt wird
Name einer existierenden Entität, die eine n:m-Relation zu Dokumenten besitzt

GROOVY-Beispiel

GROOVY

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

Primärschlüssel Ausgangsentität

Primärschlüssel des Elterndatensatzes, mit dem der Dokumentendatensatz verknüpft wird.

Pflichtfeld, wenn:

ein Dokumentendatensatz angelegt wird, oder
ein Rücktransfer konfiguriert ist.

Mögliche Werte:

leer / nicht belegt → nur zulässig, wenn kein Dokumentendatensatz erzeugt wird
gültiger Primärschlüssel eines Datensatzes der oben angegebenen Ausgangsentität

GROOVY-Beispiel

GROOVY

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

Dokumentenbetreff

Betreff des erzeugten Dokumentendatensatzes.

Pflichtfeld, wenn:

ein Dokumentendatensatz angelegt wird
und
die Serveraktion ohne Assistent ausgeführt wird.

Mögliche Werte:

leer / nicht belegt, wenn:
- kein Dokumentendatensatz erzeugt wird, oder
- eine Serveraktion mit Assistent verwendet wird (Betreff kann im Assistenten gepflegt werden)
beliebiger Text

GROOVY-Beispiel

GROOVY

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

Stichwort (optional)

Stichwort des erzeugten Dokumentendatensatzes.

Mögliche Werte:

leer / nicht belegt
beliebiger Text

GROOVY-Beispiel

GROOVY

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

Kategorie (optional)

Kategorie des erzeugten Dokumentendatensatzes.

Mögliche Werte:

leer / nicht belegt
gültiger Primärschlüssel einer Dokumentenkategorie

GROOVY-Beispiel

GROOVY

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

Verknüpfen mit allen Geschäftspartnern

Steuert, ob der erzeugte Dokumentendatensatz mit allen Geschäftspartnern des Elterndatensatzes verknüpft wird.

Mögliche Werte:

false oder nicht belegt → Es erfolgt keine automatische Verknüpfung mit Geschäftspartnern.
true → Verknüpfung mit allen Geschäftspartnern des Elterndatensatzes.

GROOVY-Beispiel

GROOVY

ProcessUtils.setVariable("linkCu", true);

Verknüpfen mit allen Ansprechpartnern

Steuert, ob der erzeugte Dokumentendatensatz mit allen Ansprechpartnern des Elterndatensatzes verknüpft wird.

Mögliche Werte:

false oder nicht belegt → Es erfolgt keine automatische Verknüpfung mit Ansprechpartnern.
true → Verknüpfung mit allen Ansprechpartnern des Elterndatensatzes.

GROOVY-Beispiel

GROOVY

ProcessUtils.setVariable("linkCoPe", true);

Ausführung

Beim Start der Massendatenaktion „Excelvorlage“ wird zunächst die Konfiguration aufgebaut und geprüft.

Ist die Konfiguration gültig, startet die Generierung der Exceldatei.
Je nach gewählter Serveraktion:
- werden Suche und ggf. weitere Schritte direkt auf dem Massendaten-Server ausgeführt,
- und der (teil-)vorbelegte Assistent wird dem Anwender über die Systemjobs in der Schnellstartleiste angeboten,
- oder alle Aktionen laufen komplett im Hintergrund.

Beispiele für das Verhalten des Assistenten:

Serveraktion „Suche ausführen und Assistent öffnen“
→ Assistent öffnet mit bereits ausgeführter Suche.
Serveraktion „Alle gewählten Aktionen ausführen und Assistent öffnen“
→ Assistent öffnet mit bereits ausgeführter Suche und generierter Exceldatei.
Serveraktion „Alle gewählten Aktionen ausführen ohne Assistent“
→ Vollständige Hintergrundverarbeitung.
→ Ausnahme: Anzeige der Seite „Excel öffnen“, wenn
- Makros in der Exceldatei enthalten sind oder
- ein Rücktransfer konfiguriert ist.

Wenn keine Makros ausgeführt werden müssen und kein Rücktransfer konfiguriert ist, kann die Excel-Generierung komplett unsichtbar im Hintergrund erfolgen.

Nach Abschluss des Assistenten oder nach der vollständigen Hintergrundverarbeitung wird der Prozess fortgesetzt.

Wurde das generierte Excel-Dokument als Dokumentendatensatz im CRM gespeichert, steht der Primärschlüssel im Feld ExportSubDir.MassDataTask des Massendaten-Tasks zur Verfügung.

Beispiel für die Nachverarbeitung

GROOVY

GROOVY

String massDataTaskPk = ProcessUtils.getVariable("massDataPk");

// Massendaten-Task laden
IContainer massDataTask = WorkSpaceScriptUtils.searchEntryForRead(massDataTaskPk, "MassDataTask");

// Ergebnisanzahl auslesen
int resultCount = WorkSpaceScriptUtils.getValue(massDataTask, "ResultCount.MassDataTask");

// Primärschlüssel des erzeugten Dokuments auslesen
String docPk = WorkSpaceScriptUtils.getValue(massDataTask, "ExportSubDir.MassDataTask");

// Prozessvariablen für die weitere Verarbeitung setzen
ProcessUtils.setVariable("resultCount", resultCount);
ProcessUtils.setVariable("docPk", docPk);

// Weitere Verarbeitung z. B. in einer Nachricht, Logikprüfungen, etc.

Fehlerfallbehandlung

Ist die Konfigurationsprüfung nicht erfolgreich, wird:

die Generierungsaktion nicht gestartet,
die Aktion sofort beendet,
jede Fehlkonfiguration im Unterbereich „Massendatenprotokoll“ der aktuellen „Massendatenaktion“ gespeichert.

Der Prozess selbst wird nicht abgebrochen, sondern normal fortgesetzt. Dadurch können Sie den BPM-Prozess anhand der Protokolleinträge später gezielt korrigieren.