ARNR Specific macros (Confluence helper app macros)
JQL section macro
Either use the shortcut command (/JQL or /ARNR) to find the macro or use + icon in the Confluence editor to search the macro with options JQL/ARNR. Once the Macro appears, click on it.
Now this will open the Insert JQL Section pop-up. Here you can add a JQL section in any other type of ARNR template. You can also use all the options like fields and Layout here same as you use in JQL section within any other type of ARNR templates.
Since this JQL works as a Confluence macro there are some differentiating factors when compared with JQL section of other types of templates. Thus, in this documentation, we are separately describing the JQL section in detail.
First of all ler talk of the differences of JQL sections in other ARNR templates vs JQL section macro in the new Confluence editor template -
JQL section in ARNR templates | JQL section via JQL macro in Confluence template |
|---|---|
Section tab has the wyswyg editor | No wyswyg editor |
JQLs are automatically validated | Manual JQL validation needed |
Supports Stats function | Separate macro available for Stats. Bar chart function is not available yet. |
Supports variable function available with JQL section | Separate macro available for Variables, you can copy variables from macro /directly type variables in JQL sections |
Supports Custom variables function | You can use custom variables in the Confleunce template that are created in ARNR app via the available Custom variable macro within JQL section. Read Manage & use ARN custom variables |
Please note, if you have not added a token within Helper app configurations, the JQL will not auto-populate and you will have to manually update the JQL. Since it could be error-prone we strongly recommend completing the setup as mentioned in Checklist.
There are three tabs in JQL section macro -
Sections
Fields
Layout
Section
Below are the fields in the section tab -
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
Validate JQL - Select any project from the dropdown and click on validate. This ensures the proper data fetching and project validation when Confluence template is executed.
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 fields like display as link or text, Hide field label variable when the field value is empty, etc.
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.
Adjust column width when using Table layout
As shown in below image, navigate to the Layout tab in the Insert/Edit JQL section pop-up. Click on icon beside Table option, add the column width % for each column (fields selected in the Fields tab), and Insert.
Based on configurations, table is created on the Confluence page. This way, the user can decide the column width depending on the content being added to the given table.
By default, all the selected fields will have equally distributed column width %
When configuring column width %, if the total goes beyond 100%, the horizontal scroll is added to the table on published Confluence page.
Layout
Table layout
This layout is fairly straightforward & does not need any additional configurations. All the fields that you select in Fields tab will shown as columns of the table. You can manage the column width to ensure each column take necessary space to display text properly.
Sequestial layout
Selecting sequential 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 the 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 first screenshot below will generate data that looks like the one in the second screenshot added below -
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.
AI generator macro
In the Confleunce page that you want to create as template, type search for the AI generator macro from the Confluence macro section or using / as a shortcut. Refer to below image -
fields in AI generator macro
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 ARNRR 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.
Validate JQL - Select any project just to validate the JQL you have added.
Where to fetch issue data from? - Read detailed description AI 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 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.
Variable macro
For variables, you can use variable macro. simply type /variables or use the + icon and search for a macro called Variables - Automated Release notes for Jira (ARNR) in the template.
Search for the relevant variable. Copy to use anywhere in JQL, template title, etc.
Limitations
Images/videos directly added to the confluence side templates are not supported on the published page yet
You cannot preview the template output before executing the Rule Action
Following fields only support 'Display as text' -
Issue type
Status
Priority
SLA fields
Some of the visual elements within the wiki renderer field such as lozenge/status, code block, etc are not fully supported.
Date macro
As shown in the below image, one can search for a Date macro. Click on Date macro displayed with ARNR app name.
Once the macro is launched, you can use variables related to dates like releaseDate, startDate, sprintStartDate, etc. Selected variable will be replaced by the actual date from within Jira when release notes are published.
Please feel free to share any queries or feedback on our Support portal.
Status macro
Status macro is add different statuses in the customizable release notes. You can just add the title of the status or select a variable from the dropdown so the status is replaced by the actual value of a selected variable. Then choose color coding and utilize them to show release statuses, sprint statuses, issue statuses, etc.
Stats macro
With this macro, now you can stats similar to the ones you can add to ARNR templates.
Once clicked on the macro, below pop-up is displayed -
Add Macro Title, Once the JQL is added it needs to be validated. If it is not validated, needs to correct and get validated. ( A trick here is that you may want to paste the same JQL in Jira and get it corrected!). Use the correct function to show stats. If needed, numbers can be displayed as links to the underlying issues using Display as link option.
Filters/Jira issues macro
This macro allows to users add Jira issues/filter macro along with ARNR variables with the JQL. To search this macro on your Confluence page/template type /Jira issues and notice the pop-up shows Jira issues/filters - Automated release notes for Jira (ARNR) macro.
Once you click on it, it loads a pop-up as below -
Below are the fields -
Title - Add the title of the filter
JQL - Specify the JQL to retrieve issues to be published on the Confluence page. You can also use ARNR variables in the JQL.
Project - This dropdown field appears if the project variable is used in JQL. Select the relevant project and validate JQL
Validate JQL - This button appears when you add a JQL
Maximum issues - Mention the maximum number of issues to be displayed on a listing page
Select the fields (columns) - Select the columns to be displayed
Select the output format - Select whether the output format should be Table or Total count of the retrieved issues via configured JQL.
Output for Table format
Output for total count format
In the template page, you can add variables using the variables macro explained above so that when the release notes are published, these variables are replaced by their actual values.
On this page |
|---|