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

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.

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. 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.

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

Custom CSS

Introduction

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

How to

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.

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.

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.

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.

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.

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.

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.

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

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.

• 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

• 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.