Creating documents with an external editor

Document templates are created directly in a text editor that supports the selected file format (i.e. docx, rtf or txt). Create your document by inserting the appropriate tags between $$ symbols. 

Supported formats:

• Microsoft Word 2007. We also support all newer versions, including 2010, 2011, 2013 and 2014.
• Rich Text Format. RTF format is used in many editors such as Microsoft Wordpad.
• Pure Text File Format. The text files may be generated by different programs. We support many file formats based on the text format (eg. HTML, XML).

Uploading templates to Jira

While uploading a template to Jira such attributes as listed below, you must define: 

• Template name which will be visible to the user and the system administrator. 
• File name that will be created by our plugin based on a template. This name can contain tags that will be parsed later on. 
• Issue types in which the template will be used (not applicable for a file generation in the workflow).
• Statuses in which the template will be available (not applicable for a file generation in the workflow).
• Projects in which the template will be available (not applicable a for file generation in the workflow). 

Creating files from templates

A Jira user can create files by selecting the "Generate Attachment" option in the "More Actions" menu. Please note that only those templates that has selected appropriate type of issue, actual status or project will be available. File that has been generated on the basis of a template is automatically attached to the issue in JIRA.

"Export Templates" is a similar function - you can find it in the "More Actions" menu on view issue page. It allows you to generate a file and immediately saves it on your computer without attaching it to the issue. All restrictions on the templates are respected.

Basic tags

The main idea of the system is to parse defined pieces of text (called "tags"). Tags reflect such issue fields as summary, description or assignee. For example if you want to use an issue summary in your document, you should insert the $$summary$$ tag that will add a proper content to the document.

While adding a new template, a full list of tags is available on the screen.

Custom Fields

Apart from typical Jira fields, the Automated Attachments plugin gives you the opportunity to use custom fields. They are used similarly to ordinary tags. Each user field (all standard types provided by Jira are supported) can be added to the document template simply by using the tag $$customfield_xxxxx$$ where "xxxxx" is a field ID (e.g. you can use the tag $$customfield_10001$$ for a custom field with the ID = 10001). If you want to know how to obtain the user ID field, please click here.

Using expressions in tags

Some solutions require more sophisticated parsing mechanism. In order to meet these expectations we have created an advanced mechanism for separating fragments of JIRA issue fields. For instance: if the field stores the user's email address, and you want to use only the domain name, you can do that through this mechanism, as in the following example.

Example:

If the field (customfield_10001)contains john.doe@mycompany.com, and you want to insert only a domain name into the document, you just need to use the tag $$customfield_10001[@][1:2][:]$$.

Testing tags

Sometimes it is necessary to verify how your tag will be parsed before you create a template. You can do it using the testing tags mechanism available in the plugin Options menu. Just enter your issue key and the tag you want to check.

Backup & restore

The plugin configuration is automatically backed up and restored. It is included into the Jira backup/restore functionality. Remember though, that the templates are stored in the file system on the Jira server and they have to be (like the issue attachments) backed up separately. The directory containing your template is located in the JIRA_HOME/data/attachment-generator. Do not forget to backup the contents of this directory.

Retrieving templates from Jira

The Automated Attachments plugin allows you to download a template that was previously uploaded to the server. Therefore you do not need to keep local copies of your templates and wonder which ones are up-to-date.

Changing File Encoding

Our add-on supports various file text encodings. In the plugin options you can set one of many encoding formats.

Error handling

Rarely the system cannot generate a file (e.g. when a template file has been removed from the Jira server). In order to deal with such situations we have prepared an error handling mechanism which helps administrators find the root cause of the issue and eliminate it.