Confluence CLI for bulk actions like deleting or publishing pages

Today I needed to remove a number of pages from our Confluence documentation site. To do it via the web interface would have taken a long time. Instead, I used Bob Swift’s Confluence CLI tool. It is simple to use and powerful in capability, and you can run it from your own computer. Ideal for bulk deletion of pages and other mass documentation admin tasks!

The pages that I wanted to remove were a set of transcripts from our developer IRC chat. We had an automated process that generated the transcripts and added them to Confluence regularly for a certain period. There was therefore quite a large number of them. Then we stopped generating the transcripts, and those that were on the wiki became out of date and irrelevant. I needed to remove the parent page that introduced the transcripts, and all the child pages that represented individual IRC sessions. Enter the CLI.

My environment

I’m using the following setup:

  • My desktop PC is running Windows 7, and I executed the CLI commands from a command window on this machine.
  • The Confluence server is running Confluence 3.5.
  • I used version 2.2.0 of the CLI.

Note that you need Confluence administrator permissions to use the CLI.

Using the Confluence CLI

1. Make sure that the remote API is enabled on your Confluence site. Go to Confluence admin > General Configuration and make sure the following option is enabled: Remote API (XML-RPC & SOAP).

2. At this point, I recommend that you change your password on Confluence, because soon you will enter the password to a text file on your computer, where it will be visible for anyone to see unless you encrypt the file.

3. Download the CLI distribution from the Atlassian Plugin Exchange: https://plugins.atlassian.com/plugin/details/284.

4. Unzip the distribution into a directory on your computer. This will give you a directory called confluence-cli-x.x.x, where “x.x.x” is the version of the CLI that you downloaded. For example, mine is called confluence-cli-2.2.0.

5. Open a text editor and edit the batch file called confluence.bat (on Windows) or confluence.sh (on a Mac) which you will find in the above directory. Now you will specify the address of your Confluence server, and the username and password that the CLI will use to access that server.

My computer is running Windows 7. This is the content of the confluence.bat file before I did anything to it:

@echo off

rem remember the directory path to this bat file

set dirPath=%~dp0

rem need to reverse windows names to posix names by changing \ to /

set dirPath=%dirPath:\=/%

rem remove blank at end of string

set dirPath=%dirPath:~0,-1%

rem – Customize for your installation, for instance you might want to add default parameters like the following:

rem java -jar “%dirPath%”/lib/confluence-cli-2.2.0.jar –server http://my-server –user automation –password automation %*

java -jar “%dirPath%”/lib/confluence-cli-2.2.0.jar %*

rem Exit with the correct error level.

EXIT /B %ERRORLEVEL%

I commented out this line:

rem java -jar “%dirPath%”/lib/confluence-cli-2.2.0.jar %*

And added this line:

java -jar “%dirPath%”/lib/confluence-cli-2.2.0.jar –server https://my.confluence.com –user myname –password secret %*

Hehe, my password isn’t actually “secret”. You will need to substitute the correct values for https://my.confluence.com and myname too.

This is the content after I have added the details of the server and user:

@echo off

rem remember the directory path to this bat file

set dirPath=%~dp0

rem need to reverse windows names to posix names by changing \ to /

set dirPath=%dirPath:\=/%

rem remove blank at end of string

set dirPath=%dirPath:~0,-1%

rem – Customize for your installation, for instance you might want to add default parameters like the following:

rem java -jar “%dirPath%”/lib/confluence-cli-2.2.0.jar –server http://my-server –user automation –password automation %*

rem java -jar “%dirPath%”/lib/confluence-cli-2.2.0.jar %*

java -jar “%dirPath%”/lib/confluence-cli-2.2.0.jar –server https://my.confluence.com –user myname –password secret %*

rem Exit with the correct error level.

EXIT /B %ERRORLEVEL%

6. Save the batch file.

7. Open a command window and go to the directory (cd) where you unzipped the CLI distribution. For example: C:\>cd confluence-cli-2.2.0

8. Execute the batch file (see examples below), passing the relevant parameters to perform the action you need done. The CLI documentation lists all the parameters available and gives examples of the actions you can perform.

As mentioned at the beginning of this post, I wanted to delete a specific page and all its child pages. The pages were on our production documentation site. But first, being a cautious soul, I tested the CLI on a staging server, and instructed it to delete just one page. The page name is “atlassiandev_log-2010-03-15”.

This is the command I ran. (Remember that my batch file is configured to address the correct server with a valid username and password.)

confluence –action removePage –space “DOCS” –title “atlassiandev_log-2010-03-15”

This was the result:

C:\Atlassian\confluence-cli-2.2.0>confluence –action removePage –space “DOCS” –title “atlassiandev_log-2010-03-15”

Removed page ‘atlassiandev_log-2010-03-15’ from space ‘DOCS’.

C:\Atlassian\confluence-cli-2.2.0>

To make ultra sure, I went to my Confluence site and had a look at the trash bin for the space. (Go to Space Admin > Trash.) Yep, just the one page, and it was the one I expected. (I had craftily purged the trash bin before running the CLI command, so that I knew exactly what should be in there.)

Next I was ready to delete the parent page and all its child pages. In fact, this command will remove all descendents of the parent page, including its children and their children, and so on. The parent page is “IRC Chat Transcripts”.

confluence –action removePage –space “DOCS” –title “IRC Chat Transcripts” –descendents

This was the result:

C:\Atlassian\confluence-cli-2.2.0>confluence –action removePage –space “DOCS” –title “IRC Chat Transcripts” –descendents

Removed page ‘IRC Chat Transcripts’ from space ‘DOCS’.

C:\Atlassian\confluence-cli-2.2.0>

Hmm. Interesting. The message mentioned only the title of the parent page. I hopped back to my online view of the space’s trash bin, and all the expected pages had been deleted. Excellent!

Now I was ready to try it on the production server. I adjusted the server URL and my password in the batch file, then ran the same command as above. Yaayyy! It worked.

9. When all is done, change your password on Confluence again.

10. Have a chocolate.

Other scenarios

My requirement was fairly simple, but typical of the mass-processing a document administrator may need to do. The CLI documentation includes some useful examples and a list of all the available actions and parameters.

A scenario that springs to mind is publishing and removing pages on release date. In the scenario that I described above, all I needed was one line to remove a page and its descendents. To perform a series of actions, you can set up a number of lines in the batch file and then run it to do all the processing at one time. This may be very useful on release date. For example, you may want to delete a number of individual pages and publish other pages by removing page restrictions (permissions). Add the commands to the batch file during the documentation development cycle, then run the file on release date.

Thank you Bob

Thank you to Bob Swift for the awesome Confluence CLI! And thanks to Scott for pointing it out to me.

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 20 October 2011, in Confluence, technical writing, wiki and tagged , , , , , , , , , . Bookmark the permalink. 3 Comments.

  1. Thanks for writing this Sarah. I just discovered the joys of CLI last week, and have been happily using it to assist us in migrating from Confluence 2.10 to Confluence 3.5.13. Examples: converting from Space Labels to Space Categories, splitting up a space into multiple spaces, and copying spaces. Works like a charm, and is well worth having in your toolbox!

  1. Pingback: Content re-use and automated publishing via Confluence Command Line Interface « ffeathers

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: