DATA CENTER AND SERVER | CLOUD

Quick Start Tutorial

Owned by Bernhard Doleschel
Last updated: Jul 20, 2023
3 min read

Starting for the first time

If you’re starting a Word export template from scratch, it’s best we first go through and understand the export template process.

Step 1 – Create a template

  • Create a blank Word document

  • Let’s start with some simple template code – copy the code below to your Word document:

    Requirements Project: [[$selectedProject.name]] [[$selectedProject.key]] Requirements Folders: [[\each $selectedProject]] [[\recurse $.folders]] [[$.numbering]] [[$.]] [[/recurse]] [[/each]]

  • After pasting the code to your Word document, click on Save

  • More interesting code can be found at QuickStart Export Code Snippets.

Step 2 – Upload a template

  • Go to your Jira

  • In the main navigation bar, select Requirements > Export Template Configuration (Administration section)

    • If you are unable to see this option, permissions may be restricted on template administration

    • Contact your Jira administrator to give you the correct permissions

  • On the top-right corner of the page, click on Add new template

  • In the dialog, fill in the template name and upload the file created from Step 1

  • Click on the Add button

Your template is now ready to be used!
Read more: Configuring Custom Export Templates

Step 3 – Generate a report

  • Go to your requirements project tree by selecting Requirements > <Your Project> in the main navigation bar
    If the desired project does not appear in the recent projects list, find it in View All Projects instead

  • Once you’re in the requirements project tree, find the Export button on the R4J navigation bar

  • Click on Export and select Export Template…

  • On the dialog that appears, choose the template uploaded from Step 2

  • Click Select

Your report should be successfully generated and downloaded automatically from your browser.
If you open the file, the code has turned into data!

Step 4 – Examine the data

To understand deeper, let’s examine the result of our template code.

The most important concepts of the Word export template language:

  1. Expressions always open and close with two brackets [[ like this ]].
    The “selected*” expressions are your access to the elements selected by the user in R4J.

  2. Statements, on the other hand, encloses a block of text [[\statement]] like this [[/statement]]
    → Support important controlling elements like (recursive) loops and formatting options

  3. Context Items enable you to access your requirements projects' data; they start with a dollar sign $ and allows property access by appending a period and property name

On the left side is the template code provided from Step 1.
On the right side are some descriptions to walk you through the code with the format as follows – Context-Item: Expected result

Sample template code

Requirements Project: [[$selectedProject.name]] [[$selectedProject.key]] Requirements Folders: [[\each $selectedProject]] [[\recurse $.folders]] [[$.numbering]] [[$.]] [[/recurse]] [[/each]]

Review

- : Renders text as it is Project : Renders the name of the project tree where you exported from Project : Renders the key of the project tree where you exported from - - : Renders text as it is Project : Opens data iteration for your project tree with the each statement Folders : Starts recursive iteration for each folder of your project with the recurse statement Folder : Renders the value for the property "numbering" and the default value for the Folder context item Folders : Closes the recursion Project : Closes the iteration

Sample result in Word export

Requirements Project: Project Sandcastle PS Requirements Folders: 1 User Stories 1.1 Timmy 1.2 Jenny 2 System Requirements 2.1 Functional Requirements 2.2 Non-Functional Requirements 3 Component Requirements 3.1 Supplies 3.2 Architecture 3.2.1 Towers 3.2.2 Moat 4 Test Cases

Now that you’re able to have some understanding on how the template code works, with a bit more work you’ll be able to create more complex templates! Start with our Sample Word Template Files to get familiar.