Contents
1. Some variables do not render if I use styles on them in the Word templates
Problem
Inside the DOCX templates you can use all variables but ensure that you do not apply any styles to them. The reason is that a Word application can escape certain parts of the variable name with certain tags and the PDF app then will not be able to evaluate such a variable. For instance, $issue.key will be evaluated as a task's key, but if you apply a style to certain part of it ($issue.key) then the PDF application will keep this variable as is and will not substitute its value in the result document.
Solution
To fix this, cut an evaluating expression to the clipboard, paste it to any text editor like Notepad for instance, copy the pasted value and paste it back to the Word document. By doing that you will reset all unnecessary text styles.
Important notes:
- Disable the spell checking in your Word template before saving and attaching the document.
- Use "Clear formatting” (CTRL+SPACEBAR to reset style) for each expression you are evaluating within the docx template, because MS Word might set certain formats incorrectly.
- Do not apply formatting partially to such expressions. First you need to clear the old formats from the velocity expressions, then, if necessary, apply the new formats.
We plan to fix this inconvenience soon so, please, stay tuned.
2. Links issue: How to insert links not as plain text in Word, but as a hyperlink
Currently this is not possible but we plan to implement this feature so stay tuned.
3. Special variables ($fieldRenderer.renderFieldById("..."), $fieldRenderer.renderField("<name>” etc.) to use in the template
Use Notepad++ to change the template instead of MS Word for these variables to be working.
4. Encoding issue: how can I avoid "??" in the exported documents
Atlassian recommends UTF-8 or Unicode encoding, and case-insensitive collation. In most cases, problems are due to a misconfiguration in one of the Jira components.
Thus you should use the UTF-8 character encoding across the database, application server, and web application.
To do that:
- On the System info page of the admin console, check your System Encoding option, it should be "utf-8". This should fix the problem with encoding. You can change encoding via JAVA_OPTS variable or by adding the URIEncoding="UTF-8" attribute to the Connector tag in your server.xml of tomcat, or directly in the database.
- Ensure that the webwork.i18n.encoding property is set to "UTF-8" in the System info page of Jira admin. If the value of this property differs from UTF-8, perform the following changes:
- find webwork.i18n.encoding and set it to "UTF-8" in $JIRA_INSTALL/atlassian-jira/WEB-INF/classes/webwork.properties.
- jira-application.properties
- directly in the database:
- select id from the property entry where the property_key='webwork.i18n.encoding'.
- update propertystring set propertyvalue = 'UTF-8' where id in (select id from propertyentry where property_key='webwork.i18n.encoding').
- Ensure that in the System info page of Jira Administration, the file.encoding and sun.jnu.encoding properties are set to "UTF-8" as well.
To change them, set the environment variable JAVA_OPTS as:
export JAVA_OPTS=-Dfile.encoding=utf-8 -Dsun.jnu.encoding=UTF-8 $JAVA_OPTS - Restart Jira.
- Check conf/server.xml. Find where the Coyote HTTP Connector is defined (i.e. <Connector port="8090"/>).
- Add a URIEncoding="UTF-8" property to the connector: <Connector port="8090" URIEncoding="UTF-8"/>.
- If you are using mod_jk, apply the same URIEncoding parameter to the AJP connector and add the following option to your Apache mod_jk configuration:
<Connector port="8009" protocol="AJP/1.3" URIEncoding="UTF-8"/>.
That's it. Jira will use UTF-8 across all Jira components and the Easy Word PDF Issue Templates app will generate Word documents rendering the special characters correctly.