Leveraging Confluence APIs

Atlassian Confluence is an excellent platform to collaborate and share knowledge with teams. Often this is not a favorite tool for most teams since they have limited time to update documents and also find it a passive way for documentation. We cannot get rid of documentation completely even in the agile world- we still need documentation for various purposes like referencing. While there are dedicated technical writers in teams who are responsible for documentation, and they do justice to their roles; but what if this documentation activity is made interesting for developers too. There are scenarios where developers can take the lead to publish documents in Confluence and that too in automated manner.

BUT, is this achievable – Confluence documentation?

Well, APIs are available for rescue. We can create Python scripts that run on a schedule and update required changes or create new documents in Confluence as needed. This Python script leverages Confluence APIs and it is easy to build it too. Let us take a look at some of the important Confluence APIs –

Sr No	Purpose	API
1	Create a new Confluence page	https://<confluenceurl>/rest/api/content?title=<pagename>
2	Update existing Confluence page	https:// <confluenceurl> /rest/api/content/<pageID>?expand=body.storage
3	Retrieve Confluence contents and page details	https://<confluenceurl>/rest/api/content?title=<pagename>

Let us assume we need to update an existing page called ‘Custom page’ in Confluence. The following Python script will achieve the target –

“sample.py”

#python script to update Confluence page using API

import requests

header = {‘content-type’: ‘application/json‘}

payload=‘{“type”:”page”,”title”:”Custom Page”,”version”:{“number”:2},”body”:{“storage”:{“value”:”Welcome Page”,”representation”:”storage”}}}’

response = requests.put(“https://<confluence_url>/rest/api/content/121212?expand=body.storage”,auth=(‘username’, ‘password’),data=payload,headers=header,verify=False)

print(response)

The above script does the following –

First, it imports the module called ‘requests‘ to allow PUT requests that calls the respective Confluence API for the page with ID 121212 (replace this with your page id that needs to be updated). It then sets in the header mentioning the request type which in our case is ‘application/json’ and then defines the payload. Lastly, it executes the API call by passing the header and payload values with username and password details. To check on the final output, we setup the print command to display the response result. If it is 200, then it indicates that the API call was successful else there is an error.

Key things to note while running the above Python script–

• Confluence URL = Do update that, it should point to your Confluence server location.
• Version number = For our example, we have a page named “Custom Page”; its current version is “1”. The Python script if successful will update the page as well as its version number (as stated in the script). Hence, before running the script; do increment the version number. Like we have mentioned version number as “2” in the payload variable.
• Page ID = The page id is important to mention in this API; each Confluence page has a unique ID. If in case you do not know this ID; then you can leverage the API (as mentioned in row 3 of above table) that retrieves the ID based on the page title.

I found this so simple and leveraged this method to automate few tasks that made my life easy 🙂 Just prepare the data points and parcel it in the payload object; of course keeping in mind that the version number of the page is also incremented every time a fresh execution is done. This version increment can also be automated…… Additionally, you can add HTML objects as well or data from a different source that needs to be populated in Confluence (all through the ‘payload’ object). For example, you need to extract data from BitBucket, perform some analysis on that data and publish the output in Confluence.

This was my experience so far on automating Confluence documentation and saving time. Are there any use cases you have identified that helped you automate documentation ?? Please do share !!

Quick references- Getting started with Python in Eclipse IDE