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
`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:

Use case 1: Create a simple template

Select the process,
Upload the images in documents (upload at least an image called “im1.png” and another one )
Start a new instance with the below template

The generated file can be found in the documents section together with the images. The generated file should look like:

In the above example we have included:

Variable substitution,
Conditional formatting,
Adding single images by name, and all images
Using excel functions,
Document prefix,
Document target,
Interpreting number as boolean, boolean as human and translation

The variables must be the same as in the Excel template.

Calling the execution of ExcelTemplateHandler from a REST api call endpoint

The ExcelTemplateHandler can be called from rest api using the below endpoint

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
}

Integrating the ExcelTemplateHandler into a HTML-Form

The ExcelTemplateHandler can be integrated into a HTML-Form as a link, a button, or an image so that the participants can create a template at any time. For this, the following code must be integrated into the form:

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

The "onbuttonclick" attribute defines which functions/parameters the handler should execute. See Parameters sections above.

Important when using HTML-Forms

Normally written text will be inherited, whereas variables will be overwritten if marked as ${Variable-ID}. To overwrite variables with content from the HTML form, you must use the variable's ID, such as ${Variable-ID}, within the text form fields. An exception to this rule applies to radio buttons, where you should use the variable name, like ${Variable-Name}, instead of the variable ID.