ExcelTemplateHandler

Beschreibung

Dieser Actionhandler ist ab Version v7.14 verfügbar und erlaubt es dem Benutzer Exceldokumente und -templates mit den Werten der Prozessvariablen aus einem Formular zu erstellen und zu benutzen.

Variablen aus System Variables können ebenfalls in diesem Actionhandler verwendet werden.

Um dem Dokument basierend auf den Variablen einen Namen zu geben, kann man die gewünschte Variable als Dokumentenname zusätzlich zum Dokumenteninhalt pflegen.

Es ist möglich Bilder aus der Prozessinstanz in das Worddokument einzufügen. Hierfür werden spezielle Variablen im Template benötigt.Ein einzelnes Bild kann mit dem exakten Bildnamen eingefügt werden z.B. $img{bild.jpg}. Es ist auch möglich alle Bilder einzufügen, die einer Instanz anhängen: $img{addAllimages}.

Der ExcelTemplateHandler kann auch in den HTML Forms als Button installiert werden, um ein Template zu generieren, wenn dies notwendig ist. Mehr Informationen finden Sie hier.

Class

com.dooris.bpm.actionhandler.ExcelTemplateHandler

Parameter

Parameter	Default value	Description	Valid examples

Parameter	Default value	Description	Valid examples
`template` mandatory		Dieser Parameter wird benutzt, um den Pfad zum Template festzulegen, damit der ActionHandler danach im resources Order suchen kann. Um die erstellte Datei umzubenennen kann das Template selbst eine Prozessvariable enthalten. Vorausgesetzt das Template, Parameter hat die folgenden Werte: `template`=`${SYS.PROCESSINSTANCE_NAME}_report.xlsx`. Im Zielordner wird die Datei entsprechend gesucht. Der ExcelTemplateHandler sucht nach dem Template `${SYS.PROCESSINSTANCE_NAME}_report.xlsx`. Wenn es nicht möglich ist, das jeweilige Dokument zu finden, wird die Prozessvariable `SYS.PROCESSINSTANCE_NAME` als Dokumentenname benutzt. Nur dann wird der ExcelTemplateHandler nach dem Template suchen `8D-ProblemSolving_report.xlsx` (8D-ProblemSolving ist der herangezogene Name aus `${SYS.PROCESSINSTANCE_NAME}`). Um auf den Abschnitt ‘Resources’ in der 'Administration' zuzugreifen, schauen Sie bitte nach: `Roles`	`${processInstanceId}_8D-report.xlsx` The handler supports .xlsx and .xlsm file extensions
`overwriteExisting`	`false`	Dieser Parameter wird verwendet, um zu entscheiden, ob die Dokumente überschrieben werden sollen, wenn der Prozess durch eine Schleife ausgeführt wird. Wenn das ursprüngliche Template benötigt wird, sollte der Parameter `false` sein.	`true`
`documentPrefix`		Der documentPrefix kann so verwendet werden, dass erstellte Dokumente immer den angegebenen Wert vor dem Vorlagennamen haben.	`mydocumentprefix`
`removeEmptyTableRows`	`false`	Wenn der Wert auf true gesetzt ist, werden alle Tabellenzeilen im xlsx-Template gelöscht, wenn die Variable in der ersten Spalte fehlt oder leer ist. Dadurch können unschöne leere Zeilen in dynamischen Inhalten vermieden werden (DOMRepeater).	`true`
`interpretNumbersAsBoolean`	`false`	Es kann entweder true oder false sein. Wenn dieser Wert auf true gesetzt ist, werden Prozessvariablen (die mit "bool" beginnen) wie folgt geändert: baa1 → true (Im Dokument: true) boolbaa1 → true (Im Dokument:: yes) boolbaa1 → 1 (Im Dokument:: yes) bobbb1 → false (Im Dokument: false) boolbbb1 → false (Im Dokument: no) boolbbb1 → 0 (Im Dokument:: no)	`true`
`interpretBooleanAsHuman`	`false`	Dieser Parameter wird genutzt, um zu entscheiden, ob ein Boolean (true oder false) mit “Ja oder Nein“ ausgetauscht werden sollte. Wird diese Variable zu `true` gesetzt, werden Booleans zu “Ja und Nein” geändert	`true`
`target`		Dieser Parameter wird verwendet, um den Dokumentnamen im Zielordner zu bestimmen. Diese Vorgehensweise ist nützlich, wenn der Name des erstellten Word-Dokuments vom Vorlagennamen abweichen soll. Der Zielparameter kann Prozessvariablen enthalten. Angenommen, der Benutzer möchte zwei Berichte in Englisch und Deutsch erstellen. Die Word-Vorlage im Ressourcenordner hat den folgenden Namen: `${SYS.PROCESSINSTANCE_NAME}_report_${language}`. Mit dem target-Parameter kann nun der Name des Word-Dokuments geändert werden, z.B. `target=XY-Report_DE`. Daher kann der Benutzer Excel-Dateien mit unterschiedlichen Namen aus derselben Excel-Vorlage erstellen. Die Dateierweiterung ist innerhalb des Zielparameters nicht erforderlich.	`target=${processInstanceId}_${processInstanceName}_report`
`locale`	`en`	Mit diesem Parameter können alle vom System unterstützten Sprachen in Kurzform angegeben werden (z.B. `en`, `de`). Dies führt dazu, dass alle vom System generierten Wörter (z.B. boolean Yes/No) übersetzt werden.	`de`

Aufbau

Um den Action Hander einzurichten, sind die folgenden Schritte erforderlich:

Richten Sie den Prozess ein
1. Erstellen oder Hochladen eines einfachen Workflows
2. Formular Importieren
Laden Sie die Vorlage in den Mandantenadministratorressourcen hoch.

Nach dem Setup sollten Sie Folgendes sehen können:

Beispiel 1: Ein einfaches Template erstellen

Wählen Sie den Prozess aus,
Laden Sie die Bilder in den Dokumenten hoch (laden Sie mindestens ein Bild mit dem Namen "im1.png" und ein weiteres hoch)
Starten Sie eine neue Instanz mit dem unten gezeigten Template

Die generierte Datei befindet sich in der Rubrik Dokumente zusammen mit den Bildern. Die generierte Datei sollte wie folgt aussehen:

Im obigen Beispiel haben wir aufgenommen:

Substitution von Variablen,
Formattierung anhand von Bedingungen
Hinzufügen einzelner Bilder nach Namen und aller Bilder
Benutzung von Excel-Funktionen
Präfix des Dokuments,
Ziel des Dokuments,
Interpretieren von Zahlen als boolesch, humane Auswertung eines Boolean und Übersetzung

Die Variablen müssen mit denen in der Excel-Vorlage übereinstimmen.

Aufrufen der Ausführung von ExcelTemplateHandler über eine REST-Schnittstelle

Der ExcelTemplateHandler kann über die REST-API mit dem folgenden Endpunkt aufgerufen werden.

POST: [your server url here]/tim/api/templates

{
    // Mandatory params
    "processInstanceId": [YOUR PI ID HERE],
    "template": [YOUR TEMPLATE PATH HERE],

    //Optional params
    "target": "",
    "documentPrefix": "",
    "locale": "",
    "overwriteExisting": false,
    "interpretNumbersAsBoolean": false,
    "interpretBooleanAsHuman": false,
    "removeEmptyTableRows": false,
    "open": false
}

Einbinden des ExcelTemplateHandlers in ein HTML-Formular

Der ExcelTemplateHandler kann als Link, Button oder Bild in ein HTML-Formular eingebunden werden, so dass die Teilnehmer jederzeit eine Vorlage erstellen können. Dazu muss folgender Code in das Formular eingebunden werden:

<button type="button" onbuttonclick="generateFileFromTemplate([{handler:'ExcelTemplateHandler',template:'temp.xlsx',attach:false,open:true,documentPrefix:'Prefix'}])">Generate Excel template</button>

Das Attribut "onbuttonclick" definiert, welche Funktionen/Parameter der Handler ausführen soll. Weitere Informationen finden Sie in den Abschnitten "Parameter" oben.

Wichtig bei der Verwendung von HTML-Formularen

Normalerweise wird geschriebener Text vererbt, während Variablen überschrieben werden, wenn sie als ${Variable-ID} markiert sind. Um Variablen mit Inhalten aus dem HTML-Formular zu überschreiben, müssen Sie die ID der Variablen, z. B.${Variable-ID}, in den Textformularfeldern verwenden. Eine Ausnahme von dieser Regel gilt für Optionsfelder, bei denen Sie den Variablennamen wie ${Variable-Name} anstelle der Variablen-ID verwenden sollten.