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

You can watch our video to see the Choose Label macro in action.

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

CAUTION: Mixing languages on a Confluence page results in undefined label suggestion behavior.

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 pressing L on the keyboard.
When the Labels dialog box appears, choose generated labels here.