This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision Next revision Both sides next revision | ||
en:software:tim:actionhandler:wordtemplatehandler [2016/05/20 09:37] jan.mayer [Parameter] |
en:software:tim:actionhandler:wordtemplatehandler [2020/05/15 09:10] Stefan Barth [Parameter] |
||
---|---|---|---|
Line 1: | Line 1: | ||
+ | ====== WordTemplateHandler ====== | ||
+ | ==== Description ==== | ||
- | =======WordTemplateHandler======== | + | This [[:en:software:tim:actionhandler|handler]] describe a Word document with variables taken from smartform variables. |
- | This [[en:software:tim:actionhandler|handler]] describe a Word document with variables taken from smartform variables. | + | |
- | The parameter "overwriteExisting" tells if an existing template can be overwritten (true) or a new template should be created. \\ | + | The parameter "overwriteExisting" tells if an existing template can be overwritten (true) or a new template should be created. |
- | In order for the handler to be able to create PDFs, the [[en:software:tim:openoffice_converter |Open Office Converters]] must be installed. | + | From [[:en:software:tim:changelog:tim37|Tim Version 3.7]] on, the variables from the [[:en:faq:variableshelper|VariablesHelper]] may be used.\\ |
- | \\ From [[en:software:tim:changelog:tim37|Tim Version 3.7]] on, the variables from the [[en:faq:variableshelper|VariablesHelper]] may be used.\\ | + | |
\\ | \\ | ||
The images attached to the instance may be placed into the Word document. For this, special variables must be present in the template.\\ | The images attached to the instance may be placed into the Word document. For this, special variables must be present in the template.\\ | ||
Individual images may be entered: $img{Image.jpg} <- Exact name of the entered imaged\\ | Individual images may be entered: $img{Image.jpg} <- Exact name of the entered imaged\\ | ||
- | Alternatively, all of the images attached to the instance may be entered: $img{addAllImages}\\ | + | Alternatively, all of the images attached to the instance may be entered: $img{addAllImages} |
- | <note> The WordTemplateHandler may also be built into the [[en:software:tim:Smartform]] as a button, on order to generate a Template if needed. More on this subject is found [[wordtemplatehandler#Integrating_the_Wordtemplatehandler_into_the_Smartform|here]]</note> | + | <note> The WordTemplateHandler may also be built into the [[:en:software:tim:smartform|Smartform]] as a button, on order to generate a Template if needed. More on this subject is found [[:en:software:tim:actionhandler:wordtemplatehandler#integrating_the_wordtemplatehandler_into_the_smartform|here]]</note> |
+ | |||
+ | ---- | ||
- | ------ | ||
==== Action Class ==== | ==== Action Class ==== | ||
+ | |||
<code> | <code> | ||
com.dooris.bpm.actionhandler.WordTemplateHandler | com.dooris.bpm.actionhandler.WordTemplateHandler | ||
</code> | </code> | ||
- | \\ | + | |
---- | ---- | ||
- | ==== Event Type ==== | + | |
+ | ==== Event Type ==== | ||
any | any | ||
- | ==== Action Name ==== | + | |
+ | ==== Action Name ==== | ||
any | any | ||
- | ==== Mandatory Fields ==== | + | |
+ | ==== Mandatory Fields ==== | ||
- | - | ||
+ | |||
---- | ---- | ||
- | ==== Parameter ==== | + | |
+ | ==== Parameter ==== | ||
=== template === | === template === | ||
- | The path to the template is entered here. It may be entered as an absolute or relative to the Externalfilepath in the loom.properties. | ||
- | > In order to rename the generated PDF, the name of the template itself may contain process variables. (see [[#Example]]) | ||
- | \\ === overwriteExisting (optional) === | ||
- | This may be either **true** or **false**. If the name is set to **true**, TIM overwrites the existing PDFs if the process runs again through a loop. If the PDF is still needed, the value must be set to **false**. | ||
- | > This value is set to **false** by default | ||
- | \\ === documentPrefix === | ||
- | The **documentPrefix** can be used to attach the entered value to the template name of of the PDF as a prefix. | ||
- | \\ === pdf (optional) === | ||
- | This value must first be set to **true** in order to TIM to generate a PDF. If the value is set to **false** or nothing is entered, TIM replaces the variables in the template and generates a Word file, which is then attached to the process. | ||
- | \\ === interpretNummbersAsBoolean === | ||
- | If this value is not set by the user, the default is **false**. If the value is set to true, process variables (with names beginning with "bool") are transformed as follows: | ||
- | ^ Variable name ^ Value ^ Result in PDF ^ | ||
- | ^ baa1 ^ true ^ true ^ | ||
- | ^ boolbaa1 ^ true ^ ja ^ | ||
- | ^ boolbaa1 ^ 1 ^ ja ^ | ||
- | ^ boolbbb1 ^ false ^ nein ^ | ||
- | ^ bobbb1 ^ 0 ^ 0 ^ | ||
- | ^ boolbbb1 ^ 0 ^ nein ^ | ||
- | \\ === interpretBooleanAsHuman === | + | The path to the template is entered here. It may be entered as an absolute or relative to the Externalfilepath in the loom.properties. > In order to rename the generated PDF, the name of the template itself may contain process variables. (see [[#example|Example]]) |
- | This is set to **false** by default. If this value is set to true, the values of all of the variables marked as **true** or **false** are replaced with the values **yes** or **no**, respectively. | + | |
- | > Available from Version 3.5 on! | + | == Special case: Resolving process variables in the document name == |
+ | |||
+ | Given the template parameter has the following value: **template=${SYS.PROCESSINSTANCE_NAME}_report.docx**. In the target folder the file will be searched accordingly. | ||
+ | |||
+ | - The wordTemplateHandler literally looks for the template **${SYS.PROCESSINSTANCE_NAME}_report.docx**. | ||
+ | - If it is unabled to find the respective document, the process variables in the document name will be resolved. | ||
+ | - Only now the wordTemplateHandler is looking for the template **8D-ProblemSolving_report.docx** (8D-ProblemSolving is the resolved value of SYS.PROCESSINSTANCE_NAME). | ||
+ | |||
+ | <note>This procedure strongly increases the performance of the wordTemplateHandler</note> <note important>Available from version 5.4</note> | ||
+ | |||
+ | === overwriteExisting (optional) === | ||
+ | |||
+ | This may be either **true** or **false**. If the name is set to **true**, TIM overwrites the existing PDFs if the process runs again through a loop. If the PDF is still needed, the value must be set to **false**. > This value is set to **false** by default \\ | ||
+ | |||
+ | === documentPrefix === | ||
+ | |||
+ | The **documentPrefix** can be used to attach the entered value to the template name of of the PDF as a prefix. | ||
+ | |||
+ | === pdf (optional) === | ||
+ | |||
+ | This value must first be set to **true** in order to TIM to generate a PDF. If the value is set to **false** or nothing is entered, TIM replaces the variables in the template and generates a Word file, which is then attached to the process. | ||
+ | |||
+ | === interpretNummbersAsBoolean === | ||
+ | |||
+ | If this value is not set by the user, the default is **false**. If the value is set to true, process variables (with names beginning with "bool") are transformed as follows: | ||
+ | |||
+ | ^Variable name^Value^Result in PDF| | ||
+ | ^baa1^true^true| | ||
+ | ^boolbaa1^true^yes| | ||
+ | ^boolbaa1^1^yes| | ||
+ | ^boolbbb1^false^no| | ||
+ | ^bobbb1^0^0| | ||
+ | ^boolbbb1^0^no| | ||
+ | |||
+ | === interpretBooleanAsHuman === | ||
+ | |||
+ | This is set to **false** by default. If this value is set to true, the values of all of the variables marked as **true** or **false** are replaced with the values **yes** or **no**, respectively. > Available from Version 3.5 on! | ||
---- | ---- | ||
- | \\ === target === | + | === target === |
- | Mit dem **target** Parameter kann der Dokumentenname im Zielordner festgelegt werden. Dabei können auch Prozessvariablen in den Namen integriert werden. | + | |
- | > **Wichtig:** eine Dateiendung wird nicht benötigt. | + | With the **target** parameter you can determine the document name. This approach is useful, if the document name should be different from the template name. The target parameter can contain process variables. > Consider you want to create a report in english and german. The word template in the resource folder has the following name **${SYS.PROCESSINSTANCE_NAME}_report_${language}**. With the target parameter you can change the name of the word file to e.g. **target=XY-Report_DE**. Therefore you can create word files with different names from the same word template. \\ \\ **Important:** no file extension is needed within the target parameter |
- | <code>target=${processInstanceId}_${processInstanceName}_report</code> | + | |
- | Für eine Instanz des **8D Problem Solving Prozesses** wird das Dokument z.B. unter dem Namen **1467_8D-RandomGmbH_report.docx** abgespeichert. | + | <code> |
- | \\ {{ :software:tim:actionhandler:wordtemplate-target.png?700 }} | + | target=${processInstanceId}_${processInstanceName}_report |
+ | </code> | ||
+ | |||
+ | \\ {{ :software:tim:actionhandler:wordtemplatehandler2.png?700 }}In this instance, the word document is saved as **1467_8D-ProblemSolving_report.docx** | ||
+ | |||
+ | === locale === | ||
+ | |||
+ | Diesem Parameter können alle von TIM unterschtützten Sprachen als Kürzel (z.B. de, en) übergeben werden. Dies führt dazu, dass von TIM generierte Wörter (z.B. Ja/Nein bei Boolean-Auswertungen) übersetzt werden. | ||
---- | ---- | ||
+ | |||
==== Example ==== | ==== Example ==== | ||
- | {{ :software:tim:actionhandler:wordtemplatehandler.png }} | + | |
- | \\ In this example, a PDF is attached after the activation of the wordTemplateHandler. It is composed as follows: | + | {{ :software:tim:actionhandler:wordtemplatehandler.png?700 }} \\ In this example, a PDF is attached after the activation of the wordTemplateHandler. It is composed as follows: |
<code> | <code> | ||
Änderungsabwicklung_E1_tim_123_test_1.pdf | Änderungsabwicklung_E1_tim_123_test_1.pdf | ||
Line 72: | Line 110: | ||
---- | ---- | ||
+ | |||
==== Integrating the Wordtemplatehandler into the Smartform ==== | ==== Integrating the Wordtemplatehandler into the Smartform ==== | ||
- | The Wordtemplatehandler can be integrated into the smartform as a link, a button, or an image so that participants can create a template at any time. For this, the following code must be integrated into the smartform: | + | |
- | <code html> | + | The Wordtemplatehandler can be integrated into the smartform as a link, a button, or an image so that participants can create a template at any time. For this, the following code must be integrated into the smartform: |
- | <button type="button" onbuttonclick="generateFileFromTemplate([{handler:'WordTemplateHandler',template:'pfad/zumTemplate.docx',pdf:false,attach:false,open:true,documentPrefix:'Prefix'}])"> | + | |
+ | <code html4strict> | ||
+ | <button type="button" onbuttonclick="generateFileFromTemplate([{handler:'WordTemplateHandler',template:'pfad/zumTemplate.docx',pdf:false,attach:false,open:true,documentPrefix:'Prefix'}])"/> | ||
</code> | </code> | ||
- | Further information can be found on [[en:software:tim:smartform:pdf_button|this page]]. | + | Further information can be found on [[:en:software:tim:smartform:pdf_button|this page]]. |
- | ----- | + | |
+ | ---- | ||
+ | |||
+ | ==== Document History ==== | ||
+ | |||
+ | With version 5.2 you can review the document history of a process instance via the system variable **${SYS:DOC_HISTORY}**. The document history displays which documents have been attached, edited or deleted. E.g. with the **wordTemplateHandler** you can save the document history to a word or pdf document (s. screenshot). | ||
+ | |||
+ | {{ :software:tim:actionhandler:documenthistory.png?700 }} | ||
+ | |||
+ | ---- | ||
+ | |||
+ | ==== Text in the Tempate ==== | ||
+ | |||
+ | Normally written text will be inherited, whereas variables, if marked as ${Variable ID} will be overwritten. The radio-buttons are an exception: You have to use the name instead of the ID. | ||
+ | |||
+ | ---- | ||
==== Potential problems ==== | ==== Potential problems ==== | ||
- | [[en:support:wordtemplatehandler|Typical Errors]] | + | |
+ | [[:en:support:wordtemplatehandler|Typical Errors]] | ||
+ | |||
+ | \\ | ||
+ |