WordTemplateHandler

Beschreibung

Dieser ActionHandler befüllt ein Word-Dokument mit Werten aus der Smartform.

Hierzu wird eine Word-Dokumentvorlage erstellt und mit Prozessvariablennamen als Platzhalter angereichert. Bei Ausführung des Händler wird ein Word- bzw. PDF-Dokument erstellt und die Prozessvariablen mit Werten aus bspw. der Smartform ersetzt.

Der Parameter "overwriteExisting" gibt an, ob bereits erzeugte Dokumente überschrieben werden dürfen (true) oder ob ein neues Dokument erstellt werden soll. Variablen aus https://tim-doc.atlassian.net/wiki/spaces/eng/pages/227969642 können auch mit diesem ActionHandler verwendet werden.

Es ist ebenfalls möglich den Dokumentennamen durch Prozessvariablen anzureichern, indem Sie die Prozessvariable als Platzhalter im Dokumentennamen mit angeben.

Es ist möglich, individuelle Bilder aus einem Vorgang in das Word-Dokument einzufügen. Hierzu werden spezielle Variablen in der Vorlage benötigt. Es kann ein einzelnes Bild mit dem genauen Namen des Bildes eingefügt werden, zum Beispiel: $img{bild.jpg}. Es ist aber auch möglich, alle an den Vorgang angehängten Bilder einzufügen: $img{addAllimages}.

Der WordTemplateHandler kann auch über einen Button in der https://tim-doc.atlassian.net/wiki/spaces/eng/pages/228002614 bereitgestellt werden, um bei Bedarf ein Dokument zu generieren. Weitere Informationen finden Sie unter hier.

Klasse

com.dooris.bpm.actionhandler.WordTemplateHandler

Parameter

Parameter	Standardwert	Beschreibung	Gültige Beispiele

Parameter	Standardwert	Beschreibung	Gültige Beispiele
`template` MANDATORY		Hier wird der Pfad und der Name der Vorlage angegeben, damit der ActionHandler im Ressourcenordner danach suchen kann. Dieser Pfad kann auch absolut oder relativ zum externen Dateipfad in den loom.properties angegeben werden. Um das generierte Dokument umzubenennen, kann der Name der Word-Vorlage selbst Prozessvariablen enthalten. Sonderfall: Auflösen von Prozessvariablen im Vorlagennamen Als Vorlagenname wird bpsw. folgender Parameter eingegeben: `template`=`${SYS. PROCESSINSTANCE_NAME}_report.docx`. Im Zielverzeichnis wird die Datei gesucht. Der WordTemplateHandler sucht wörtlich nach der Vorlage mit dem Dateinamen `${SYS. PROCESSINSTANCE_NAME}_report.docx`. Wenn das entsprechende Dokument nicht gefunden werden kann, werden die Prozessvariablen `${SYS. PROCESSINSTANCE_NAME}` im Dokumentnamen aufgelöst. Erst jetzt sucht der WordTemplateHandler nach der Vorlage `8D-ProblemSolving_report.docx` (8D-ProblemSolving ist der aufgelöste Wert von `${SYS. PROCESSINSTANCE_NAME}`). Um auf den Abschnitt "Ressourcen" unter "Administration" zuzugreifen, besuchen Sie bitte: `Rollen`	`${processInstanceId}_8D-report.docx`
`overwriteExisting`	`false`	Dieser Parameter wird verwendet, um zu entscheiden, ob die Dokumente überschrieben werden sollen, wenn bspw. der Prozess eine Schleife ausführt. Wenn das Original weiterhin benötigt wird, sollte der Wert `false` verwendet werden.	`true`
`documentPrefix`		Der hier festgelegte Wert wird bei Erzeugung des Dokuments immer am Anfang des Dokumentennamens hinzugefügt.	`myDocumentPrefix`
`pdf`	`false`	Wenn dieser Parameter `false`oder nicht angegeben ist, ersetzt das System die Variablen in der Vorlage und erstellt ein Word-Dokument, das an den Prozess angehängt wird. Um anstelle eines Word-Dokuments ein PDF-Dokument zu erstellen, sollte dieser Wert `true` sein.	`true`
`removeEmptyTableRows`	`false`	Wenn der Wert auf `true` gesetzt wird, werden alle Tabellenzeilen im docx-Dokument gelöscht, wenn die Variable in der ersten Spalte fehlt oder leer ist. Dadurch können unschöne Leerzeilen bei Verwendung von dynamischen Inhalten (DOMRepeater) vermieden werden.	`true`
`interpretNummbersAsBoolean`	`true`	Der Wert 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: ja) boolbaa1 → 1 (Im Dokument: ja) bobbb1 → `false`(Im Dokument: `false`) boolbbb1 → `false`(Im Dokument: nein) boolbbb1 → 0 (Im Dokument: nein)
`interpretBooleanAsHuman`	`false`	Dieser Parameter wird verwendet, um zu entscheiden, ob die booleschen Variablen (`true`und `false`) durch “ja” oder “nein” ersetzt werden sollen. Setzen Sie diese Variable auf `true` werden boolesche Variablen in “ja” oder “nein” umgewandelt.
`target`		Dieser Parameter wird verwendet, um den Dokumentennamen im Zielordner zu bestimmen. Diese Vorgehensweise ist sinnvoll, wenn der Name des erstellten Word-Dokuments vom Vorlagennamen abweichen soll. Der Zielparameter kann Prozessvariablen enthalten. Angenommen, der Benutzer möchte zwei Dokumente auf Englisch und Deutsch generieren. 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 in z.B. `target=XY-Report_DE`. Hierdurch können Word-Dateien mit unterschiedlichen Namen aus derselben Word-Vorlage erstellen. Die Dateierweiterung ist innerhalb des target-Parameters nicht erforderlich.	`target=${processInstanceId}_${processInstanceName}_report`
`locale`	`"de"`	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. boolesches Ja/Nein) übersetzt werden.

Beispiel:

Nachfolgend wird die Implementierung des WordTemplateHandlers anhand eines Beispiels erklärt.

Zuerst wird ein Word-Dokument als Vorlage benötigt. Die Vorlage enthält zwei Variablen (${employee_name}, ${employee_id}). Diese beiden Variablen werden ebenfalls als Eingabefelder in der Smartform des Prozessbeispiels verwendet.

Damit die Variablen bei Ausführung des WordTemplateHandlers mit den Inhalten aus dem Smartform überschrieben werden, müssen die Variablen in Word in ein Textfeld (Formularsteuerelement) eingetragen werden.

Die Variable ${employee_name} wird im Feld Standardtext in den Optionen für Textformularfelder eingetragen. Die Optionen werden per Doppelklick auf das grau hervorgehobenen Textfeld in Word geöffnet.

Nachdem beide Variablen als Textformularfelder eingegeben wurde, sieht das Word-Dokument wie folgt aus:

Das Word-Dokument wird unter dem Namen${employee_name}.docx gespeichert. Der ActionHandler ersetzt die Variable im Dokumentennamen durch den Mitarbeiternamen, der im Smartform angegeben wurde.

Damit die Vorlage vom WordTemplateHandler verwendet werden kann, sollte diese anschließend in der "Administration" in den “Ressourcen” hochgeladen werden:

Über den Button “Datei(en) hochlanden” wird das Dokument in den Ressourcen hochgeladen.

Anschließend kann der WordTemplateHandler im Prozessablauf eingerichtet werden. Es soll für jeden Mitarbeiter nach dem Start eines Vorgangs ein Word-Dokument generiert werden, welches den Mitarbeiternamen und die Mitarbeiter-ID enthält. Hierzu wird der WordTemplateHandler auf der ersten Aufgabe im Prozessmodell implementiert.

Parameter	Beschreibung	Beispiel

Parameter	Beschreibung	Beispiel
`template`	Hier wird der Namen der Word-Vorlage angegeben, die in den Ressourcenordner hochgeladen wurde. Nachdem der Prozess gestartet wurde, sucht der ActionHandler die Vorlage mit diesem Namen und erstellt ein neues Dokument mit den Informationen aus dem Smartform und legt es im Reiter “Dokumente” zu Ihrem Vorgang ab.	${employee_name}.dox

Zu guter Letzt wird eine Smartform benötigt, das zwei Eingabefelder mit den Variablen employee_name und employee_id enthält.

Nachdem Sie den Prozess mit seiner Smartform veröffentlicht haben, starten Sie diesen Prozess und geben beim Start den Namen und die ID des Mitarbeiters an.

Nach dem Start des Vorgangs wird automatisch ein neues Word-Dokument generiert, wobei die Variablen ${employee_name} und ${employee_id} durch “John Doe” und “000123“ ersetzt werden. Im Reiter “Dokumente” des Vorgangs kann auf das gerade erzeugte Word-Dokument zugegriffen werden.

Durch Anklicken kann des Dokuments als auch über Anklicken des Aktions-Buttons kann das Dokument heruntergeladen und geöffnet werden.

Die Variablen im Dokument als auch im Dokumentennamen wurden mit den Werten aus der Smartform ersetzt.

Den WordTemplateHandler in eine HTML-Smartform integrieren

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

<button type="button" onbuttonclick="generateFileFromTemplate([{handler:'WordTemplateHandler',template:'pfad/zumTemplate.docx',pdf:false,attach:false,open:true,documentPrefix:'Prefix'}])">ButtonName</button>

In dem Attribut „onbuttonclick“ wird definiert welche Funktionen/Parameter der Handler ausführen soll. Siehe dazu den Abschnitt “Parameter” weiter oben.

Dokumentenverlauf

Die Verlauf von Dokumenten an einem Vorgang kann über die Systemvariable ${SYS:DOC_HISTORY} ausgegeben werden. Der Verlauf zeigt, welche Dokumente dem Vorgang angehängt, bearbeitet oder gelöscht wurden. Mit dem WordTemplateHandler kann der Dokumentenverlauf in einem Word- oder PDF-Dokument gespeichert werden (s. Screenshot).

Wichtig für HTML-Smartforms

Texte, die nicht in Textformularfeldern angegeben werden, bleiben erhalten. Damit Variablen mit den Inhalten aus dem HTML-Formular überschrieben werden, muss in den Textformularfeldern die ID der Variable ${Variablen-ID} verwendet werden. Eine Ausnahme bilden Radio-Buttons. Hier muss anstelle der Variablen-ID der Variablen-Name ${Variablen-Name} verwendet werden.