Using the Confluence REST API to bulk add a label to one or more attachments

Still need help?

The Atlassian Community is here for you.

Ask the community


Platform notice: Server and Data Center only. This article only applies to Atlassian products on the Server and Data Center platforms.

Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.

*Except Fisheye and Crucible

Purpose

Using the REST API can be helpful in automating certain operations within Confluence.

However, going through the User Interface (UI) could be rather impractical depending on the number of target attachment files.

This document provides a step-by-step procedure on how to use the Confluence REST API to add a label to one or multiple attachment, provided you have the target attachments CONTENTID.

The suggested solution is provided as a set of bash commands using curl and jq to run the REST API call and manipulate json output.
You may use this example to create an automation tool on your preferred coding language.

This document is provided as-is, what means that Atlassian Support won't provide assistance on modifying this example to fit your use case.
However, we will definitely support you if a REST API call isn't working as it should.
See Atlassian Support Offerings for additional information.


Solution

The solution is broken down into a unit testing and process that is then extended in a single shell script to handle multiple attachments.

Define environment variables

These variables will be used along with the subsequent commands.

Some notes about these variables:

  • Make sure the user performing these changes has the appropriate Space Permissions and, if applicable, Page Restrictions. Note that Confluence REST API follows the same permissions/restrictions when the user is performing similar operations from the UI (browser).
  • The CONTENTID of the target attachment should be known. For instance, the query below can help retrieve the CONTENTID for the current attachments in the Confluence site 

    Retrieve current attachments definition from the database
    SELECT * FROM CONTENT WHERE CONTENTTYPE='ATTACHMENT' and CONTENT_STATUS='current';


USER_NAME=<username> # the user must have the necessary permissions on the target page and space where the attachment is located
USER_PASSWORD=<user password>
CONFLUENCE_BASE_URL=<Confluence Base URL>
LABEL_NAME=<the_label_to_add_to_attachment>


Add a label to one attachment

First, we will validate the model by adding the label to one attachment.  This is accomplished by sending a POST request to the /rest/api/content/<CONTENTID>/label API method.

The results of this API call are filtered to get the last label added to the attachment which should be the name of the label. This indicates that the operation succeeded. Let's assume in our example we have retrieved the CONTENTID for our attachment which is 2654214



curl -u $USER_NAME:$USER_PASSWORD -X POST -H "Content-Type: application/json" -d '{"prefix": "global", "name": "'"${LABEL_NAME}"'"}' \
 "${CONFLUENCE_BASE_URL}/rest/api/content/2654214/label" 2>/dev/null \
 | jq -r '.results[-1].name'


Extending the logic in Shell Script for multiple attachments

The shell script below includes the single step highlighted above into a FOR loop.

By creating a text file named target_attachment_id.txt and loading it with a list of attachment CONTENTIDs, you can bulk add a specific label to multiple attachments.

You may use this as an example to create an automation tool that fits your requirements and in your preferred coding language.

USER_NAME=<username> # the user must have the necessary permissions on the target page and space where the attachment is located
USER_PASSWORD=<user password>
CONFLUENCE_BASE_URL=<Confluence Base URL>
LABEL_NAME=<the_label_to_add_to_attachment>

for CONTENT_ID in $(cat target_attachment_id.txt); do
 #######
 # add label attachment to the targeted content and capture the label name added
 #######

LABEL_ADDED=$(curl -u $USER_NAME:$USER_PASSWORD -X POST -H "Content-Type: application/json" -d '{"prefix": "global", "name": "'"${LABEL_NAME}"'"}' \
 "${CONFLUENCE_BASE_URL}/rest/api/content/${CONTENT_ID}/label" 2>/dev/null \
 | jq -r '.results[-1].name')

 if [ ${LABEL_ADDED} = ${LABEL_NAME} ]; then
    echo "Label ${LABEL_NAME} added to content ${CONTENT_ID}"
 else
    echo "Failed to add label to content ${CONTENT_ID}"
 fi
 done

(info) Note that the shell script makes the strong assumption that the latest label added on the attachment is the label you try to add. If not, a simple message will display that the label failed to be added, but that can be because the label is already present!

See Also

Confluence Server REST API

Confluence REST API Documentation

Using the Confluence REST API to upload an attachment to one or more pages

  




Last modified on Sep 27, 2022

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.