Work with Labels

HAPI makes it easier for you to add, replace, and remove labels! You can search for the labels based on different criteria, like labels in a space, labels created by a certain user, etc.

Add labels

Using HAPI, you can add one or multiple labels designated in the script.

Add a label to a specific page in a space

To add a label to a page in a space, use a script like this Script Console: 

Pages.search("space = DS and title = '2023 Page 2'").each { page ->
    page.addLabels("new")
}

After running this script, the 2023 Page 2 in the Demonstration Space (DS) has the new label: 

Pages.search("space = SPACEKEY and title = 'THE TITLE'").each { page ->
    page.addLabels("label-1")
}

Add labels to pages in a space created by a specific user

To add labels to pages in a space created by a user, use a script like this in the Script Console: 

Pages.search("space = DS and creator = admin").each { page ->
    page.addLabels("label-1", "label-2")
}

After running the script, any page created by the admin user in the Demonstration Space (DS) will have the labels label-1 and label-2. 

Pages.search("space = SPACEKEY and creator = USERNAME").each { page ->
    page.addLabels("label-1", "label-2")
}

Remove labels

Using HAPI, you can remove one or multiple labels designated in the script.

Remove a label from all pages in a space

To remove a label from all pages in a space, use a script like this in the Script Console: 

Pages.search("space = DS").each { page ->
    page.removeLabels("new")
}

After running this script, the named label (new) is removed from the Demonstration Space (DS). The results also list the pages that were updated.

Pages.search("space = SPACEKEY").each { page ->
    page.removeLabels("label")
}

Remove a label added by a specific user

To remove multiple labels from pages created by a user, use a script like this in the Script Console: 

Pages.search("creator = user4").each { page ->
    page.removeLabels("label-2")
}

After running this script, label-2 labels will be removed from pages created by user4. The results show you what pages were updated.

Pages.search("creator = USERNAME").each { page ->
    page.removeLabels("label-1", "label-2")
}

Replace labels

Using HAPI, you can replace labels designated in the script.

Replace labels on a page

To rename labels on a page, use a script like this in the Script Console:

Pages.search("space = DS").each { page ->
    page.replaceLabel {
        from = "new" //This is the existing label
        to = "old" //This is the new label you want to add
    }
}

The label new on pages in the Demonstration Space (DS) will be replaced with the label old.

Pages.search("space = SPACEKEY").each { page ->
    page.replaceLabel {
        from = "label-1"
        to = "label-2"
    }
}

Update labels

Using HAPI, you can update labels by adding, removing, replacing, setting, and clearing labels designated in the script.

Add, replace, and remove labels in the same script

To add, rename, and remove labels to pages in a space, use a script like this: 

Pages.search("space = DS").each { page ->
    page.updateLabels {
        add("one", "two", "three")
        replace("one", "ten") //One will be replaced with ten
        remove("ten")
    }
}

After you run the script, the Demonstration Space (DS) pages will get the one, two, and three labels added. Then, one is replaced with ten. Then, the script removes the label ten. Ultimately, you are left with the labels two and three on each page. Since the old label was preexisting and not removed in the script, it still exists.

Pages.search("space = SPACEKEY").each { page ->
    page.updateLabels {
        add("label1", "label2", "label3")
        replace("label1", "label4")
        remove("label4")
    }
}

Remove all labels in a space

To remove all labels from pages in a space, use a script like this in the Script Console: 

Pages.search("space = DS").each { page ->
    page.updateLabels {
        clear()
    }
}

After running this script, your space will no longer have labels. The results show you what pages were updated.

Pages.search("space = SPACEKEY").each { page ->
    page.updateLabels {
        clear()
    }
}

Remove all labels and then add a label to all pages in a space

To completely remove all labels from a space and then add a new label to pages in the space, use a script like this:

Pages.search("space = DS").each { page ->
    page.updateLabels {
        set("completed")
    }
}

After running the script, pages in the space will all have the label completed as the only label.

Pages.search("space = SPACEKEY").each { page ->
    page.updateLabels {
        set("label")
    }
}

Related pages

• HAPI Script Format Help
• CQL Guide
• Search for Pages Using HAPI
• Work with Labels Using HAPI