Customising templates with visual builder

Templates can be customised with the help of following elements:

  1. Static text - This is the text that is rendered as it is in the final release notes document generated by ARN

  2. Output variables - These are some of the important data points regarding different Jira entities such as Project, Version, User & so on. These are replaced with actual values at the time of final release notes document generation

  3. JQL sections - These are the configurable sections that determine which Jira issues are pulled into the final release document, what attributes (default as well as custom) for those issues are included & how the result should be laid out. This is the gist of ARN’s template visual builder

  4. Stats - These are almost similar to the JQL sections, only difference being they end up showing a number of instead of actual Jira issues

Output variables

In order to make the templates generic, output variables are used. Majority of these output variables are available across all template types, however there are a few that will be specific to a given template type. Relevant information is highlighted at appropriate places below:

List of supported output variables

Project
projectName
projectld
projectKey

Version
version Name
versionDesc
release Date
versionld
versionURL
startDate

Sprint
sprintName
sprintId
sprintGoal
sprintStartdate
sprintEnddate
sprintCompletedate
sprintState

Date & Time
timestamp
currentDate
currentDatetime

Users
userName
userEmail

Confluence
confluence URL

releasePageURL (only available in ‘Release page notification’ template type)

Above variables are available in below template types & fields -

  • Email

    • Email subject

    • Email body

  • PDF

    • Content

  • Confluence

    • Page title

    • Page content

  • JSON

    • Content

  • HTML

    • Content

  • Markdown

    • Content

  • JSD announcement

    • Announcement subject

    • Announcement message

JQL section

JQL section is the core of ARN release notes templates. Each JQL section represents a group of issues in Jira. Within the JQL section, you can provide additional configurations for each of the results.

We tweak Jira’s JQL a bit in ARN, so that it supports input variables such as [versionId], [versionName], [projectId], [sprintId], [sprintName]. You can always increase the number of input variables by simply appending 1, 2 & so on to their names.

e.g. if you need to create a template that generates release notes from 3 versions, simply use following inputs variables in the JQL - [versionId], [versionId1], [versionId2]. In this case, the template can accept 3 different versions as inputs.

Read more about the possibilities of JQL here.

There are a few variants of the JQL section. All of those are explained below. Variant 1 is the most common one.

This variant of JQL section creator/editor is available in -

  • Email

    • Email body

  • PDF

    • PDF content

  • Confluence

    • Page content

  • HTML

    • Content

  • Markdown

    • Content

Introduction

JQL determines what issues from Jira to include in the release notes. Note that by using variables in the JQL, we have tweaked it a little bit to suit ARN’s use case.

Issue fields selector dictates what information is shown in the release notes for the selected issues. You can choose default as well as custom fields from the dropdown.

Field customisation

Furthermore, each issue field that you’ve chosen to be a part of release notes can be further customised. Click on the already added field (or the gear icon beside it) & that will reveal the additional settings available for the field. e.g. clicking on issue key reveals following.

Grouping

JQL section can return results grouped by any available field. You can add up to two fields in ‘group by’ configuration. When two ‘group by’ fields are added, issues returned by JQL will be grouped by second ‘group by’ field within each group created by first 'group by' field.

This group by field can be further configured by clicking on the left hand ‘Group by’ selection.

Grouping by Cascade Field

A field type ‘Select List (Cascade)’ stores two values for an issue parent field and child field.
If you add this custom field as ‘group by’ field, by default ‘Parent’ field will be considered as ‘group by' field.
You can also use the child field as second level group by field. Just go to customize field option and check the option “Use child field as second level 'group by' field.”
Note, when you check this option, you cannot add second group by field. Also, if another group by field is already added then you cannot use child field as group by field.

Customizing ‘Group by’ fields layout

There are two approaches to customize ‘Group by' fields.

New ‘Group by’ WYSWYG editor

New templates will see a new flexible way to customize ‘Group by’ fields and their layout. This editor can be accessed by clicking on customize option in ‘Group by’ section. Just like sequential layout editor, you can include field variables & apply customizations.

Make sure {JQL_results} variable is added at the end which will be replaced by the Table/Sequential layout of the Jira issues data fetched by the JQL.

 

Please note : This change is applicable only for the new templates and older templates will continue to show earlier 'custom CSS' approach. Even if you clone old template or copy the source code of old template into a new template, it will still show the earlier ‘Custom CSS’ approach.

So, you will have to create new template to use new 'Group by’ WYSWYG editor.

For older templates

Apply custom CSS styling to the label & value of Group by field. In this approach the group by field layout is hardcoded and cannot be modified.

This variant of JQL section creator/editor is available in -

  • JSON

    • Content

Introduction

JQL determines what issues from Jira to include in the release notes.

Issue fields selector dictates what information is shown in the release notes for the selected issues. You can choose default as well as custom fields from the dropdown.

Field customisation

JSON is a view-less, structured format & thus the customisation options are limited. One can modify the JSON structure, labels & ARN will echo the changes.

Grouping

Grouping is not possible within this variant of the JQL sections.

JSD announcement template builder does not support JQL sections.

JSD announcements is essentially an HTML text along with a title. To cater to this specific behaviour, ARN provides simple visual builder for JSD announcement type of templates.

Both, announcement subject & message fields, allow for variables to be added to them.

Stats