Getting Started - Server
- Gary Xin (Deactivated)
By and far, the features of the server version and the cloud version of DocGen are the same. However, this starter guide will still go through all the features regardless, given that minute differences can still be confusing.
Step 1: Creating the template
Template files should all be in the “.docx” format, as the app currently does not accept any other formats. Otherwise, the files themselves are regular Word files.
All values that users want replaced should be enclosed in a pair of $ symbols to denote that they are keys to be replaced; for instance, to get the summary field of the issue, your key might look like this: $summary$
Below is an example of what a basic template might look like.
Then, simply upload the template on the Global Config page.
Step 2: Mapping from keys to issue fields
After installing the application, there should now be a new configuration field found under the Manage apps tab in Administration, called Global Config. Here you’ll find the configuration settings for key-field replacements.
The keys should be only the value between the “$” symbols in the templates, as the app automatically assumes the key will be enclosed within them. Below is a list of the fields currently supported by DocGen.
Issue Field Name | Description |
|---|---|
Issue Key | The issue key - e.g. TEST-3 |
Assignee | The assignee of the issue |
Description | The description of the issue |
Summary | The summary of the issue |
Created | The date the issue was created |
Creator | The display name of the creator of the issue |
Due Date | The date the issue should be resolved by, if applicable; otherwise “None” |
Parent Key | The key of the parent issue if applicable; otherwise “None” |
Project Key | The key of the project - e.g. TEST |
Project Name | The name of the project - e.g. Test Project |
Reporter | The display name of the reporter of the issue |
Status | The status the issue is currently in |
Custom fields are also supported, but only certain types - namely those easily converted to strings, such as single line text boxes, multi-line text boxes, etc. To use a custom field, simply enter in the ID of said field, such as 10012, in the field-select box, and select it as a new value.
Step 3: Project Configuration
After setting up word replacements and having uploaded templates, you can then choose what statuses you want these templates to show up on. These conditions are entirely customizable; you can choose between different workflows within the project, and arbitrarily assign templates to any statuses at will.
Just as in the cloud version, click on the project settings icon in the bottom left of the project view.
Then, scroll down the list of project settings till you see a section labeled DocGen, just as in the Manage Apps screen.
And here you can associate templates to specific workflows and statuses. Note that the displayed statuses will change according to the workflow selected, and you can swap between workflows while still keeping statuses selected.
Step 4: Generating the templates
Now, after setting everything up, you should now be able to select the appropriate templates when issues are in the assigned statuses.
All that’s left is to click the “Generate” button, and download the filled-out template!