Choose Label Macro
Using the Choose Label macro, you can add labels and generate suggested labels to a page if they are not present. You can use some predefined variables, overwrite variables, or add user-specific custom variables.
Walkthrough
Watch our video to see the Choose Label macro in action.
Using the Choose Label Macro
When you edit or create a page in Confluence, you can use ScriptRunner for Confluence to choose labels for a page:
Select Insert, and then select Other Macros.
Select the Choose Label macro from the provided list.
Complete the following fields as needed:
Field Description Type Default Required Tip Title
Specify a title for the macro which is displayed above the macro.
string
none
no
N/A
Labels
Specify the labels using a comma-separated list.
string
none
yes
Labels must obey naming restrictions imposed by Atlassian. Certain characters (:, ;, ., ,, ?, &, [, ], (, ), #, ^, *, @, !, ', `, spaces) are not allowed.
Some restricted characters are modified when possible to allow successful application of labels.
Descriptions
Specify label descriptions using a comma-separated list. If this field is left empty, the description of each label is the same as the label. If populated, the length of the description and label field must match.
string
none
no
None
Button Text
Specify custom text for the Add Label button.
string
Add Label
no
N/A
Multiselect
Allow multiple labels to be added at the same time.
boolean
false
no
Without Multiselect enabled, the macro is hidden after the first label is added.
With Multiselect enabled, the macro is hidden once all the labels are added. Several labels can be added at one time. Generated suggested labels are not taken into consideration when hiding the macro.
Show Suggested Labels on the Macro
Allow the system to suggest labels on the macro based on the content of the page.
boolean
false
no
Label suggestions only start working once at least 100 words are added to the page. Label suggestions become more accurate as more words are added, with good suggestions arising at over 500 words.
Supported languages are English, German, Dutch, and Danish.
Show Suggested Labels on Label Dialog
Shows the suggested labels on the label dialog.
boolean
false
no
Label suggestions only start working once at least 100 words are added to the page. Label suggestions become more accurate as more words are added, with good suggestions arising at over 500 words.
Supported languages are English, German, Dutch, and Danish.
Mixing languages on a Confluence page results in undefined label suggestion behavior.
4. Click Save, and the macro appears on the page.
When the page where the macro is located is opened, the Choose Label macro is shown and only the applicable labels are shown. If all the provided labels are already present on the page, the macro is not shown.
Macro Configuration Tips
Use Provided Variables as Labels
ScriptRunner provides several variables that you can use to add specific labels. To use them, add the variables to the Labels field as you would any standard label.
$username - Username of the person who created and/or edited the page.
$fullname - The full name of the person who created and/or edited the page.
$year - The year when the page was created and/or edited.
$month - The month when the page was created and/or edited.
$day - The day when the page was created and/or edited.
$parent - The parent title of the current page.
Once you save the macro and the page loads, variable labels load with the correct data. The added labels can be seen on the bottom right of the page.
Use the Generated Label Suggestions Feature
Tick the Show Suggested Labels on the Macro checkbox on the Edit 'Choose Label' Macro dialog.
Choose the suggestions that you want.
Click Save, and the rendered macro appears on the page.
Choose Suggested Generated Labels
Tick the Show Suggested Labels on Label Dialog checkbox on the Edit 'Choose Label' Macro dialog.
Click Save.
Open the Labels dialog by doing one of the following:
When you are in edit mode on the page, select the Label icon (the tag by the file path, pictured below).
When you are on the page not in edit mode, by press "L" on the keyboard.
When the Labels dialog box appears, choose generated labels here.
