Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Background

Every organization has its unique approach to utilizing Jira. Due to its flexibility and extensive structure, there is no single prescribed method for its use. Thus, that is where we thought of making ARN flexible enough to suit any type of approach for publishing release notes and reports for its users.

The following components are fundamental to nearly all types of ARN templates. These elements, functions, and macros enable the creation of diverse release notes and reports. If any component does not apply to a certain type of template, relevant warnings are mentioned there.

Issue Scope

Tip

Comming soon! We will soon update this page once the feature is available!

(Output) Variables

Excerpt
nameVariables

These are the data points used to bring the values from Jira to your release notes content. The variables will be replaced by actual values for given data points. Some examples are projectName, fixVersion, userName, etc.

When you use such variables, upon execution of the template, variables are replaced with actual values.

List of supported output variables

Variables (Users)

Syntax

  • userName

  • userEmail

  • versionDriver

  • versionApprovers

  • [userName]

  • [userEmail]

  • [versionDriver]

  • [versionApprovers]

Variables (Project)

Syntax

  • projectName

  • projectld

  • projectKey

  • [projectName]

  • [projectld]

  • [projectKey]

variables (Version)

Syntax

  • version Name

  • versionDesc

  • release Date

  • versionld

  • versionURL

  • startDate

  • [version Name]

  • [versionDesc]

  • [release Date]

  • [versionld]

  • [versionURL]

  • [startDate]

Variables (Sprint)

Syntax

  • sprintName

  • sprintId

  • sprintGoal

  • sprintStartdate

  • sprintEnddate

  • sprintCompletedate

  • sprintState

  • [sprintName]

  • [sprintId]

  • [sprintGoal]

  • [sprintStartdate]

  • [sprintEnddate]

  • [sprintCompletedate]

  • [sprintState]

Variables (Date & Time)

Syntax

  • timestamp

  • currentDate

  • currentDatetime

  • timestamp

  • currentDate

  • currentDatetime

Variables (Confluence)

Syntax

  • confluenceURL

  • confluencePageId

  • [confluenceURL]

  • [confluencePageId]

    • This variable works similarly to the Confluence URL variable. For example - There are two actions in the rule. First action has to be Confluence action, second action could be any template action like Email, PDF, etc. that has the [ConfluencePageId] variable. When the first action is executed, its page ID is parsed in the second action and the id variable is replaced with the page ID created from the first action

releasePageURL (only available in Release page notification and LinkedIn announcement template type)

  • [releasePageURL]


Custom variables

Excerpt
nameCustom variables

Apart from the default variables that are typically the default fields, users may want to create custom fields and fetch that data to release notes. In such a case one can map the ARN custom variables with their Jira fields and bring the values of those fields to release notes.

All the custom variables created in ARN are global. It means, that irrespective of the projects they are created from, all non-deleted custom variables will be visible across all the projects.

In below image, notice the way ARN custom variable is used.

CV example.png

When executing the template, this is how the preview will asks for the value of the custom fields.

CV example output.png

This just one simple use case, Read how to Manage & use ARN custom variables with more examples.


JQL section

Excerpt
nameJQL section introduction

Introduction to JQL section

This section plays a crucial role in ARN templates. JQL dictates the appearance of your content and determines the data to be included in release notes and reports. It serves as the central hub for all information intended for end users.

There are three tabs on Add/Edit JQL section pop-up -

  • Section

  • Fields

  • Layout

Excerpt
nameJQL section - section tab

Section

In the section tab you will find below fields to define the content that will be posted in the release notes.

  • Title - This text will be shown as a section header in the generated email or page.

  • Description - This fields can contain the description of your given JQL section.

  • JQL - This field is where you add the JQL to fetch the relevant issues to your release notes

  • Hide section (checkbox) - Check if you wish to hide the JQL section when given JQL does not return any Jira issues

  • Message - When the checkbox is unchecked, write a message that needs to be displayed when no issues are returned from the given JQL.

Excerpt
nameJQL section Fields tab

Fields

This tab is to display what all Jira issue fields/custom fields that are to be added to your release notes. If the Table layout is selected then these fields are added as columns. You can add the numbered columns

In the case of the sequential layout, selected fields will be listed in the sequence you have added them.

As shown in the below image, ⚙️ icon in front of each selected field would show some extra settings for the field like header style, Entry Style, display as link or text, etc.

ARN fields.png

Read how to Save release notes without Jira fields using issue properties.

Custom CSS

Excerpt
nameCustom CSS for release notes

Introduction

To further customise the release notes that ARN generates, it is possible to configure custom CSS within different templates.

How to

Note that custom CSS can be applied only when the layout of the template is Tabular. Sequential layout does not support applying custom CSS as it already uses a WYSWYG editor.

Open any one of the above-mentioned template types & click on any JQL section to open it in Edit mode or start to Create a new one. Make sure the layout/format is set to Table.

Custom CSS can be applied for any of the selected columns, listed in the left-hand section of the Fields tab. Click on the gear icon beside any column name & it will reveal a couple of free text fields where custom CSS can be added.

Header styles refer to the styling applied to the table header for that specific column whereas Entry styles CSS attributes are applied to all the data points generated within that column.

If the JQL section data is grouped by a specific column, it is possible to apply custom CSS to that data as well. Just click on the Gear icon beside Group by option. It shows the custom CSS options.

Note

Gear icon beside Group by option will show the WYSWYG editor if you are creating a new template from scratch. Custom CSS options are available only if you are using ARN defulat templates by cloning them.

Info

For example read this to know how to control width of table columns - https://amoeboids.atlassian.net/wiki/spaces/ARN/pages/126255121/FAQs#How-to-control-width-of-table-columns-within-generated-release-notes%3F

Layout

Excerpt
nameTable layout

Table layout

This layout is fairly straightforward & does not need any additional configurations. All the fields that are selected (from Feilds tab as shown in the above image), will be displayed as table columns from left to right. Below is a sample screenshot of the generated release notes in tabular format.

table.png

In this example you can see coulmn in the table like Priority, Key, Status, Issue type, and Summary. At the left top corner of tble notice the Task issue type icon which means the table is grouped by the issue type. This way using different customisation you can define the way of displaying issues from the given release.

Excerpt
nameSequential layout

Sequential layout

Selecting equential layout presents the selected fields (from the Fields tab) in a sequenced format. The desired layout needs to be designed within the area highlighted below.

seq1.jpg

Here, the design is simply a sequence of available variables. These variables are displayed based on what fields you have chosen on the Fields tab.

seq2.png

Any fields that you have selected to be used, can be arranged in any order you wish. For every field that is configured under Fields tab on the left, there will be two variables on the right. One that will fetch the field value & other to fetch its display label. e.g. for Priority field, there are two variables - {priority} & {priorityLabel}.

Required condition is, you have to add fields & their configurations before they can be used in the Layout section. The layout created will be repeated for every issue that is returned by your section JQL. For example, layout in the above screenshot will generate data that looks like the below screenshot.

seq3.png

In below image check the check box called Hide field label variable when the field value is empty. If this is checked, and if the JQL does not fetch any data in the field value against a particular issue, then it hides the field variable and you can make sure that the release notes do not look like an incomplete piece of information.

sequencial layout.png
Info

If you are using Priority, Status, Issue type in your layout - the generated Email/PDF could be a bit misaligned because these issue fields are images.

To avoid this, modify the field configuration for these fields - and check the box Display as text.

How Group by function work?

Tip

Somenew enhancements for Group by function are in the making 🛠️ 🏗️. We will soon update here! Stay tuned!

How to sort 'Group-by’ fields in a JQL section

Excerpt
nameGroup by option in layouts

The Order by clause in JQLs respects the sorting of Group by fields as well. This means that groups created by the Group by fields in the JQL section can be ordered in the desired sequence. Additionally, you can now choose where to place orphan elements of the respective Group by field. This update provides greater flexibility and control over the organization of your data.

Here is an example:

  • There is JQL section with the Components field as a group-by field.

grp by.png
  • So the Jira issue data returned by this JQL section will be grouped by the value of their component.

  • If you want those groups to appear in a certain order (ascending or descending), then you should include the group-by field (Components field in this case) in the Order by clause of the JQL like this

compo.png
  • This will automatically order the groups created by the Group-by’ field in the order defined in the JQL.

  • You can include multiple fields in the order by clause of the JQL and the order of all such fields will be honored in the output of that JQL section.

Orphan elements

  • Now if there are any Jira issues where the value of the Components field is blank, such issues are called orphans.

    • By default, the orphan issues are placed at the bottom of the group.

    • However, you can choose to place them at the top of the group.

    • Navigate to the field customization menu of the concerned group by field to choose where the orphan issues should be placed.

orph.png

Stats & charts

Excerpt
nameIntro to Stats and charts

Introduction

ARN provides Stats & charts macro to make release notes more insightful for you & your team. To put it simply, Stats feature comes up with a number that corresponds to the count of issues that are returned by the configured JQL & chart feature lets you include a simple bar chart showing the count of issues returned by configured JQL aggregated over values of specific Jira field.

Excerpt
nameStats and charts

Stats

Clicking on Stats & charts would open a pop-up where the system accepts a JQL. And a return value. Return value identifies what kind of data will have to be extracted from the Jira issues that the JQL returns.

statsncharts.png

Typical use cases may include, informing the audience about

  • Issue distribution based on priority, type, assignee, etc

  • Time spent on different kinds of issues

  • Story point distribution across different issue types

Currently, the system can return a number of issues the stored JQL retrieves. So a typical use of this would look something like the image below.

Note that you can also optionally display the number as a link that leads back to Jira.

Sample stats generated with ARN:

Excerpt
nameCharts

Charts - bar chart

Clicking on Stats & charts would open a pop-up, select the type as Bar chart. Below are the fields you have to to add or edit while creating a Bar chart.

Setting name

Default value

Possible values

Details

Title

NA

Any chart title

Chart title, this is displayed to the end user

Type

If creating Bar chart Bar chart option should be pre-selected

  • Stats

  • Bar chart

Select the relevant option based on whether you are creating a bar chart or want to generate stats

JQL

NA

Any JQL

Add the relevant JQL to fetch Jira issues

X-axis

Different Jira issue fields

Any one default field from the dropdown

Define the Jira issue field that should be displayed on the x-axis.

For eg. You want to generate the bar chart that shows number issues assigned to users. Select Assignee for the X-axis so it shows the names of the users and on Y-will have numbers by default

Aggregate type

Count

Count

It is Count by default

Series color

#2596be

Any color code

Show chart title

Yes

  • Yes

  • No

When set to Yes, the value entered in ‘Title’ of the Stats and Charts macro will be printed at the top of the chart that is generated. The users can leave it empty.

X-axis title

NA

Name of the Jira issue field selected in X-axis field

The name of the selected Jira issue field in X-axis field will be displayed here

X-axis label position

Horizontal

  • Horizontal

  • Slanted

  • Vertical

Values for chart will be positioned based on selected option

Show X-axis label tick

Yes

  • Yes

  • No

Y-axis title

Count of issues

Any text input as Y-axis title

Since we only support Count as an aggregation type, Number of issues is the default value of this field

The user can leave it empty, if empty Y-axis title will not be displayed

Y-axis label format

Whole number

  • Whole number

  • Decimal

Font CSS

Add the CSS to specify font

Add the CSS to specify the font

Y-axis grid lines

Dotted

  • Dotted

  • Solid

  • None

Selected grid line will be displayed. For None, there will be no grid lines

Show X and Y axis line

Yes

  • Yes

  • No

Show Y-axis label tick

Yes

  • Yes

  • No

Charts and stats.png

Once this setup is saved, bar chart place holder image will be inserted into the template. Users can resize this image to resize the designated area for the bar chart within the template.

No of issues returned by the JQL will be aggregated against the unique value of the selected Jira field and a bar chart will be included within the area designated within the template.

Below image shows how the final chart will be rendered in preview/output when release notes.

chart11.png


Highlight contributors of release notes using 'Users' macro

Excerpt
nameUsers macro

This is a custom plugin called Users to ARN template that highlights your team members as contributions who led to the success of the release. This simple yet interesting plugin allows you to recognize your team members and give them credit of the release’s success.

How to use the User macro/plugin?

This plugin is by default added at the end of the template.

users.png

Click on it and edit given fields below -

  • Titile (not visible to end users) - Add the title for example Contributors, Heroes, etc. It is only for your reference and not visible in the output. For the output, you can of course add the text or emojis as needed before this plugin in the main template body.

  • JQL - The system will first fetch the Jira issues that are returned by the JQL and then look for the value of the field selected in the Jira fields (explained below).

  • Jira fields - This field shows the drop-down list of User picker (single user) type and User picker (multiple users) type fields. Then the system looks for the users within the configured user picker field against those Jira issues.

    • Now, system forms the list of unique users returned in the above step. The list will contain only the display names of these users returned by Jira APIs. Users names are displayed comma-separated manner.

Users1.png

Below image shows the sample output preview of the email.

users output.png

AI generator

Excerpt
nameAI generator macro

ARN templates now feature an AI-powered summary of the issues retrieved by a given JQL. This enables you to swiftly share a concise overview of the content included in the release notes or release notes report you're preparing. The process is as straightforward as adding a JQL section but with an AI element.

Steps

While customising any of the above templates, you will notice an option called +AI generator in the template editor.

AI templates.png

Clicking on this +AI generator opens up a pop-up with the below fields -

AI fields.png
  • Title - This title will show up in release notes for the summary generated using this feature

  • Prompt - Give a prompt to AI based on what content needs to be generated as a summary. You can input a maximum of 500 characters as a prompt.

    • +Variables - You can use ARN variables so those will be replaced with relevant values from the associated Jira issues

  • JQL - Detail out the JQL so system retrieves the relevant Jira issues. System will look for the Jira issye fields that you have specified below and it will consider that selected field for the issues retrieved as per the JQL.

  • Where to fetch issue data from? - Read detailed description https://amoeboids.atlassian.net/wiki/spaces/ARN/pages/3801612289/Generator+for+AI-powered+release+notes#Feilds-in-the-AI-generator.

When you select 'Use a Jira issue Field' it list down all Jira issue fields of the below type -

  • Summary (default Jira field)

  • Short text (Plain text only)

  • Hide section - Check this option if you wish to hide this AI-generated section when there are no issues retrieved from the given JQL.

  • Message - If you uncheck, Hide section option above then define the message you want to show when there are no issues retrieved from the JQL.

Once you are done with specifying all the above fields, click on Insert. You can check the preview to check what content AI has generated. You edit the content manually or update the prompt based on the given content and what you were expecting as a result.

ai eg.png
Note

Currently this AI generator macro is available for specified ARN templates at the top of this documentation. We are actively working to cover all other remaining macros.

Table of contents (TOC)

Expand

TOC.png

This macro is availble in the PDF template to add the table of contents. Clicking on this macro opens up the below pop-up with some fields -

Field name

Details

Title

Add the title of the TOC macro

Minimum heading level

The minimum heading level to report in the TOC. For example, '3' will list headings from 'h3.' onwards, but not 'h1.' or 'h2.'

Maximum heading level

The maximum heading level to report in the TOC. For example, '4' will list headings up to 'h4.', but not from 'h5.' onwards.

Layout

The TOC will be displayes in list of column view when selected Default or Column respectively.

Bullet style

  • Select the bullet style to be applicable for list in TOC

  • In the case of the Column layout, this setting will be disabled with no option selected

Leader style

  • Select the leader that you want for the points listed in TOC. Below is an example of dotted leader style

Leader style.png
  • In the case of the ‘Column’ layout, this setting is disabled with no option selected.

Add page break after TOC

  • When checked, a compulsory page break gets inserted after the TOC in the final output

On this page

Table of Contents
maxLevel6
minLevel2
outlinefalse
stylesquare
typelist
printablefalse

Iframe
scrollingauto
srchttps://form.typeform.com/to/loItQqk5#url=xxx
width350
frameborderhide
alignmiddle
height250