The Web API Extension for the projectdoc Toolbox can be employed to make bulk changes to documents. Since there is no safety net, these actions need to be take with care. This tip introduces a way to conduct this task.
Bulk changes on Confluence pages are usually conducted via the Confluence REST API. Using cURL, a bookmarklet, userscript, or any other form of REST client will do the trick. The Web API Extension for the projectdoc Toolbox provides additional REST services to access projectdoc documents and spaces. There are also services to access a particular property value or services to create documents from descriptors.
In case you use the REST API make sure that you do not delete valuable information. Usually you need recent backup and test your scripts on a copy of your production environment. The following tip shows how to lower the risk of unintentional data loss. A backup will be still required, but the changes of needing it are reduced. 
In this Tip you will learn by an example, how to define a search to find the documents you want to bulk change, define this change, apply it to a test document and finally do the real change.
In our example we assume, that some documents of Doctype Category which all have a property Type with value Type1 already exist.
The goal is to change all these documents to have value Type2 for the property Type, instead of having the value Type1.
Prerequisites
There are a number of options to access the Web API. For this tip two tools may be a valid choice, depending on using the change one time or multiple times. In case it is a one-shot, you could use the REST API Browser. In case you need it multiple times or consider to share the call, you could use cURL as part of a shell script.
Both approaches require the Web API Extension (available on the Atlassian Marketplace, version 6.2.0) for the projectdoc Toolbox
Choosing the first option, using the REST API Browser from Confluence, please make sure you are using the latest version 3.2.3 (or later; see our blog post Resolved: REST API Browser showing API documentation again! for details).
Point your browser to: https://myserver.example.com/confluence/plugins/servlet/restbrowser#/resource/projectdoc-1-document
Uncheck "Show only public APIs" and insert "projectdoc" in the search box on the top left side to see all projectdoc REST-API calls we provide.
Choosing the seconf option prefer to use cURL (version 7.18, or later) and jq (version jq-1.5-1 or later). cURL is used in command lines or scripts to transfer data. jq is a lightweight and flexible command-line JSON processor.
Using cURL in combination with netrc is a very easy and quite secure way to handle your credentials for Confluence. The following netrc configuration (~/.netrc) for linux systems allows to run the authentication without providing credentials on the command line (for more information and other options we recomend the tip: REST Login to Confluence with cURL).
machine www.example.com
login jane.doe
password XmysecretpasswordX
Protect your credentials!
.netrc file should only be readable and writable for you (-rw------- 1 jane.doe example 1356 Jan 21 08:44 /home/jane.doe/.netrc)
In the following steps this tip pretends that you have chosen the second option using cURL
.
Cautious Approach using the REST API
Since using the Web API does not provide a way to undo unintended changes, we provide a way to double check the implication of your actions.
In this example we show how to
- determine the documents you want to apply changes
- prepare the change
- apply the changes to one test document
- apply the changes to all documents
Let us start by defining a query searching for documents of Doctype Category containing a property named Type with value Type1.
curl -s -n -G "https://www.example.com/confluence/rest/projectdoc/1/document.json?select=Name,Type&from=MYEXAMPLE&max-hit-count=100&expand=property&max-result=100" \ --data-urlencode "where=$<Doctype>=[category] AND $<Type>=[Type1]" | jq .
Short explanation:
- The options
-s -n -Gstand for silent, use .netrc and use HTTP GET method - Followed by the URL to your Confluence server and the REST service for documents
- The query path may contain all parameters that do not need to be URL-encoded directly to the URL, that is: the parameter values do not contain a reserved chars:
";" | "/" | "?" | ":" | "@" | "&" | "=" | "+" | "$" | "," - Each parameter that contains a value needed to be encoded use the option "
--data-urlencode" (may be more than one)
in the example above its just one: the where condition (read here more on Search Tips) - Last but not least pipe "
|" the result tojqto receive a formatted result
(the punctuation mark "." followed after a whitespace followingjq: "jq ." is mandatory!)
Explanation:
- The result is starting with some general information about the
sizeand theid-list, which we will need later - In this example the query has two documents with id 128816586 and id 128816588 as query result and for each document two properties Name and Type are returned
Check! Check! Check!
Double and triple check the result set!
Make sure it is correct, as the changes in step 4 will be applied to the documents in this result set!
We recommend to apply the changes now to one single test document. Preferable this step could be executed in a test environment.
So create a text document, fetch its page id e.g. by viewing the Page Information and copying the pageid from the URL part (e.g. confluence/pages/viewpage.action?pageId=43647697) or use Copy Page ID (one of our Bookmarklets).
Start by preparing the HTTP query string
querystring=$(urlencode -m id-list=12345678)"&"$(urlencode -m new-version=true)"&"$(urlencode -m comment=Changed using the WEB-API) echo $querystring
Explanation:
- The code above is written for bash
- The code is using the
urlencodecommand provided by most Linux systems (/usr/bin/urlencode) - The $() expressions start a subshell and evaluates
urlencodecommand inline - Fill in the page id of the Confluence test page as value of
id-list - Keep all spaces and do not add aditional spaces besides the spaces in the comment value
- The echo command allows you to validate the query string
Apply the change to the test page
curl -n --header "Content-Type: application/json" \
-X PATCH "https://www.example.com/confluence/rest/projectdoc/1/document.json?"${querystring} \
--data-binary @document.json
Explanation:
- Change the URL to your Confluence server
- The file "
document.json" contains the change to apply to the documents. This is the document you created in step 3
The name of the file in the file system must not contain the "@" symbol! It is only necessary for cURL.
Check the result in Confluence regarding the change in the test page.
