Choose Label

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:

  1. Select Insert, and then select Other Macros.

  2. Select the Choose Label macro from the provided list.

  3. Complete the following fields as needed:

    FieldDescriptionTypeDefaultRequiredTip

    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

  1. Tick the Show Suggested Labels on the Macro checkbox on the Edit 'Choose Label' Macro dialog.

  2. Choose the suggestions that you want.

  3. Click Save, and the rendered macro appears on the page.

Choose Suggested Generated Labels

  1. Tick the Show Suggested Labels on Label Dialog checkbox on the Edit 'Choose Label' Macro dialog.

  2. Click Save.

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


  4. When the Labels dialog box appears, choose generated labels here.

On this page