Getting Started - Cloud
- Victor Wang (Deactivated)
Step 1: Creating the template
Although the app is pretty simple to use once setup, there is several steps that you need to go through before you can get to that point.
First, create a template. Templates are just regular Microsoft Word files with “template keys” inside of it. Keys are the names you have given the issue fields (we will discuss this in more detail in a second). Enclose the keys with “$” to denote that they are keys and that they need to be replaced. The document MUST be in a .docx format. The app ONLY accepts .docx as of right now.
Here is an example of what a template file could look like.
Step 2: Setting the key and issue field mapping
Now you will need to go into the configuration page of the application. At the bottom, you will find a place to add key and issue field mappings. In the key field, you need to put the keys you used in your template. In the issue field, you will need to place the name of the issue field that you want the key to be replaced with.
Below is a list of issue fields that we support (You input the name of the field into the configuration):
Issue Field Name | Description |
|---|---|
issueId | the issue id |
issueKey | the issue key |
issueTypeId | the id of the issue type |
issueTypeName | the name of the issue type |
issueTypeDescription | the description of the issue type |
projectId | the project id |
projectKey | the project key |
projectName | the project name |
lastViewed | the last time the issue was viewed |
priorityName | the name of the priority level of the issue |
assignee | the assignee |
timeEstimate | the estimate of the time |
description | the issue description |
summary | the issue summary |
creatorDisplayName | the display name of the issue creator |
reporterDisplayName | the display name of the issue reporter |
Note: when inputting the issue field names, be careful of capitalisaton. It is case sensetive.
Here is an example of the key Issue Field mapping section in the global configurations:
Step 3: Fill in AWS configuration details
Follow this guide here to learn how to do this: Setting up AWS S3 - Cloud
Step 4: Upload document
Go to the first tab of the global configs and upload your document. If it shows up below, you should be good.
Congrats, you have now finished all the global configurations.
Step 5: Project Configuration
To get to the project configurations, first enter a Jira project and click on the project settings tab on the bottom of the left sidebar panel.
Now scroll to the bottom of the new left side bar again. You should see DocGen option available there. Click on it to get to the project configuration for DocGen.
Here you can select which templates should be displayed at which issue status. You can choose to always display all templates by clicking the checkbox on the top and hitting confirm. You can also choose to display certain templates at certain statuses by first selecting a status and then selecting 1 or more templates. Then click add to add the list of mappings. Don’t forget to still hit confirm.
For starters, it is probably easier to just always display all templates. So click that if you’re not too sure about this. You can find a page with more info on this here: Project Configurations - Cloud
Step 6: Templating a file
Go to an issue you have created. If you don’t have any issues, then create one. Make sure the issue is in the correct status for the templates to appear. If you had selected you want all templates to always appear, you do not have to worry about this.
Amongst the issue fields, you should see the DocGen panel. This panel is where you generate the document using the template. Simply select your template from the dropdown and hit generate. It should take no more than a few seconds for the template to generate. Beside the button, a link should appear. Click that link to download the document. A copy of the document should also be saved in your S3 bucket as a backup.
This is what the final example should look like if everything has been done correctly.
Congratulations!! You now have to app setup and you can begin templating documents.