Description

  • The Choose Label macro provides the user with predefined options for adding labels and generated suggested labels to a page if they are not already present. We now allow the use of some predefined variables. Additionally through ScriptRunner for Confluence we also allow the user to overwrite these variables, or add user specified custom variables.

Usage

  • Click Insert > Other Macros.

macro browser

  • Select the Choose Label macro from the provided list.

choose label macro list

  • Complete the desired fields.

Parameter Description Type Default Required

Title

Specify a title for the macro which will be displayed above the macro.

string

none

no

Labels

Specify the labels using a comma separated list. Supplied variable labels are $username, $fullname, $year, $month, $day $parent (parent title of the current page).

string

none

yes

Descriptions

A comma separated list of descriptions that can be applied to labels. If left empty, the description of each label will be the same as the label. If populated the length of the description and label fields must match.

string

none

no

Button text

Specify custom text for the add label button.

string

"Add Label"

no

Multiselect

Allow multiple labels to be added at the same time.

boolean

false

no

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

Show suggested labels on label dialog

Shows the suggested labels on the label dialog.

boolean

false

no
Note

Without the "Multiselect" option selected, the macro will be hidden after the first label is added. With "Multiselect" enabled the macro will be hidden once all the labels are added, additionally several labels can be added at one time. Generated suggested labels are not taken into consideration when hiding the macro.
Note

Labels must obey naming restrictions imposed by Atlassian. The following characters are not allowed (:, ;, ,, ., , ?, &, [, ], (, ), #, ^, *, @, !, ' ' spaces ), and will be modified where possible to allow successful application of labels.
Note

Label suggestions will 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 over 500 words. Supported languages are English, German, Dutch and Danish.
Note

Mixing languages on a Confluence page results in undefined label suggestion behaviour.

  • The macro will then appear on the page.

choose label macro pic

  • The next time the page where the macro is located is opened the choose label macro will be shown. Only the applicable labels will be shown. If all the "Provided labels" are already present on the page, the macro is not shown.

  • Please see example 3 below for more information on the "Show suggested labels on the label dialog" option.

Examples

Example one

  • To use the provided variables as labels simply add any supported variable as you would any normal label using the Choose Label macro.

choose label macro config example

The rendered macro will then appear on the page.

choose label macro render example
Note

The $year variable resolves to 2016 and if chosen 2016 will be added as a label on the bottom right of the page. Multiple selections can be made.

Example two

  • To use the generated label suggestions feature simply tick the "Show suggested labels on the macro" checkbox. The macro will then make best effort label suggestions based on the page content.

choose label macro config example2

The rendered macro will then appear on the page.

choose label macro render example2

Example three

  • To suggest generated labels to the user on the Confluence label dialog, simply tick the "Show suggested labels on label dialog" checkbox.

choose label macro config example2

  • Open the Confluence label dialog by clicking the pencil icon on the bottom right of the page, or by pressing "l" on the keyboard.

open labels dialog

  • The suggested labels are located above the text input field and clickable. Clicking a suggested label will add it to the page, as can be seen below with the label named "bug"

choose label macro render example3

For how-to questions please ask on Atlassian Answers where there is a very active community. Adaptavist staff are also likely to respond there.

Ask a question about ScriptRunner for JIRA, for for Bitbucket Server, or for Confluence.