Manage & use ARN custom variables
- Annu
- Anand Inamdar
- Sujeet Pathak
All the custom variables created in ARNR are global in nature. It means, irrespective of the projects they are created from, all non-deleted custom variables will be visible across all the projects. However, they can be edited only from the project where they are created. (Similar to global templates).
Add custom variables
Click on the Custom variable tab >> Click on Create.
This opens up the pop-up that shows up below the fields.
Below fields are available in the Add Variable popup
Column Name | Details |
|---|---|
Variable name | Name of the custom variable. cv_will be the prefix to the custom variable. The variable name does not accept any spaces. |
Variable description | This description serves as the visible help text for customer variables. It appears when users select the variable's value while manually triggering the rule or previewing the template. |
Variable type | Type of the custom variable. Available field types are Single choice, Number, Date picker, short text & multiple choices. |
Options | This field will appear when variable type is Single choice or multiple choices type of fields. |
Default value | The default value of the custom variable. Read the below section - Manage & use ARN custom variables | How default value of custom variables work |
Edit custom variable
As shown in the below image click on the pencil icon to edit the variable.
On Edit custom variable pop-up except for the Variable type other fields can be edited (only if the variable is not used).
If the variable is already used in one or more templates/release pages/widgets then the system does not allow updating the variable name.
If the variable is not created from the current project, then custom variable is not editable the following info message is displayed.
Delete custom variable
On the custom variable listing tab, Delete icon is displayed. Clicking on the Delete icon against that custom variable allows the deletion of custom variables only if it is currently not being used by any of the templates, release pages & widgets. In this case below message is displayed. Popup shows the list of templates, release pages & widgets where the custom variable is used.
System allows to create maximum 5 custom variables per project.
Using custom variables
Custom variables can be used globally despite the projects that are created. These custom variables can be used in templates, release pages and widgets.
Use custom variables in templates
On the template builder, notice +Custom variables option. This opens up below pop-up. select the variable and click on Insert. The value for these custom variables will be added on the template preview page.
You can also notice that the Custom variable option is available in JQL macro that is available on the Confluence page as a template. Read about JQL macro here.
Use custom variables in release pages
In release pages, these custom variables can be added within the JQL, Title, and Subtitle. Please note, that within release pages, custom variables can be used when you are using manual and webhook triggers. For automated triggers, custom variables cannot be used.
Use custom variables in widgets
In widgets, these custom variables can be added within the JQL, Title, and Subtitle. Please note, in widgets, custom variables can be used when you are using manual triggers and webhook. For automated triggers, custom variables cannot be used.
Use custom variables in Webhook
When in any rule. the webhook trigger is used, one can add the custom variable and pass the value within the webhook so system fetches relevant issues with the given value within the associated Jira custom field/s. Below is an example of a webhook URL with custom variables.
How default value of custom variables work?
While creating custom variables, ARNR allows you to select a default value for that custom variable. This value can be used in JQL validations and also on the template or rule preview screens. The default value input will be based on the Feild type of the custom variable. For eg. if the type of custom variable is short text, then you can add only short text as default value of the custom variable. The below table explains this in more detail -
Custom variable type | Default value input |
|---|---|
Short text | Single line text as default value |
Date | Set date as default value |
Number | Numeric value as default value |
Select list (Single choice) | In this case, you can add multiple options under the custom variable and user can select one as it is a single-choice type field. To define a default value, you can select select on of the given choices as a default value. |
Select list (multiple choices) | Use this field when you want to add multi select options under the custom variable and user can select one or more options. To define a default value, you can select mulptiple options as a default value. |
Once the custom varaibale is set and added to your JQL, JQL will be validated, at the same time, the default value of the custom field is also validated. In the preview, you can check the output that displays the default value of the custom varaiable.
Example -
There are around 20+ JQL sections in a single ARNR template where you have to define an issue key. This issue is different in every release. In this case, it is a very difficult and error-prone task to change the hard-coded issue key by editing every JQL from the template before publishing release notes for each release either through UI or through source code.
Considering this use case, here is how this default value option in the custom variable will help you-
Create a custom variable such as [cv_issue_key] in ARNR (variable type - Short text) and set the default value for this custom variable that is your Jira issue key, eg. AR-1234 (this should be an actual non-deleted Jira issue)
Now in JQL add issuekey = [cv_issue_key]. When you form such a JQL in ARNR, the system will use its default value for JQL validation in the background and hence you will be able to save the JQL with validated JQL. Do this for all your JQL sections within your template.
Now, whenever you want to generate the release notes, just preview the template/ run the rule, and you will be asked for input against the custom variable. Here, enter the current Jira issue ID for which you want to generate the report. Your input Jira issue ID shall get replaced in all the JQL sections of your template and generate the output accordingly.
This way, instead of updating the Jira issue key in every JQL section before each execution, you just have to run the template/rule and provide the issue key as input.
Use case 1 - Customer Specific release notes
Let us assume, within Jira there is a custom field called Customer. Within Jira, certain issues are created for customers, and the Customer name field is updated accordingly. When the issue is completed/done, the respective customer/s should be informed about the same by sending them release notes.
In this case, below are the steps -
Create a custom variable called cv_customerName
Create a release notes template (any relevant type). Add above custom variable in the template/other relevant content like JQL sections.
Now Create a rule and add a relevant trigger. For this example, let us assume that the manual trigger is used.
Now manually run the rule, while running the rule, system asks for the value to be added in cv_customerName. Select the customer name (as the custom variable field type is a single select field). And click on publish.
This replaces the customer variable within template with selected customer name. Also, since it is used in JQL, it fetches issues that are associated with selected customer names within Jira’s custom field.
Below image is a preview of the email template that shows the custom variable got replaced with selected customer name.
Also check this video - https://youtu.be/p3Jtw9pQSqE?feature=shared
Few more use cases in brief
Component/Feature-wise release notes - pass value of the component field in the JQL via custom variable. So, one template for all the components.
Date-wise reports - Features released in last quarter. Pass value of date-related fields in the JQL via custom variable.
Priority wise report - generate separate reports for high/medium/low priority issues using a single template
Estimate wise reports - generate reports for issues having story point estimates higher than a certain limit