Introduction

This text is about automating the interaction with Atlassian Confluence, a commercial product widely used in the corporate world for publishing documentation or other content that needs sharing with a certain team, department or throughout the whole organization. This product is usually integrated with the other Atlassian tools such as Bamboo or JIRA.

By “automating the interaction” I understand document publishing; one may extract data from other components of the system using automated tools and may want this data published in a nice format (if possible). This is indeed possible through the REST interface that Atlassian provides for all its products. The REST functionality does not cover all the features or functions, though, but it’s enough for our scenario. The reference for the Confluence Cloud version can be found here. Please note that the interface may be a bit different between versions, so please check the API reference for your particular Confluence version.

Now that we have the tools and the method, let’s get to the implementation – and obviously, to some code.

Prerequisites

First, I advise that one should create the document through the classical way of the “Create” button in the interface. The document CAN be created with REST calls but one needs to provide the “page key” and the “parent page id”, which can be easily retrieved through the interface. Once the document is created, one must make note of the “page key” and the “page id”.

The “page key” is visible in the URL, e.g.:

The “page id” becomes visible when editing the page, e.g.:

Document Retrieval

All the code below assumes a certain map is defined, containing the credentials and the document identification:

confluence_data = { "server": "xxx", "user": "xxx", "pass": "xxx", "page_key": "xxx", "page_id": "xxx" }

One cannot update a document in Confluence without incrementing the version (an integer value). This means that the document must first be retrieved (as JSON, in our scenario here) in order to get the current version – and then increment it:

import requests
import json

def confluence_retrieve(confluence_data):
    url = 'https://' + confluence_data['user'] + ':' + confluence_data['pass'] + '@' + confluence_data['server'] + '/confluence/rest/api/content/' + confluence_data['page_id']
    headers = { 'X-Atlassian-Token' : 'no-check', 'content-type': 'application/json' }
    response = requests.get(url, headers=headers, verify=False)
    return int(response.json()[u'version'][u'number'])

Document Update

The update process has a few steps:

• Get the document formatted with the proper representation accepted by Confluence (details below);

• Generate a new version (increment the old version);

• Compose the payload (JSON in this scenario, one may also use XML);

• Issue the PUT request and – let’s say it – “hope for the best”.

def confluence_update(confluence_data, new_title, new_content):
    old_version = confluence_retrieve(confluence_data)
    new_version = old_version + 1

    url = 'https://' + confluence_data['user'] + ':' + confluence_data['pass'] + '@' + confluence_data['server'] + '/confluence/rest/api/content/' + confluence_data['page_id']
    data = { "id": confluence_data['page_id'], "type": "page", "title": new_title, "space": { "key": confluence_data['page_key'] }, "body": { "storage": { "value": new_content, "representation": "wiki" } },
"version": { "number": str(new_version) } }
    headers = { 'X-Atlassian-Token' : 'no-check', 'content-type': 'application/json' }
    response = requests.put(url, headers=headers, data=json.dumps(data), verify=False)
    return

There are a few content representations accepted by Confluence:

• plain: plain text, as provided, not formatted in any particular way.

• wiki: the Confluence wiki markup. This is not the wiki markup from Wikipedia but a different format. This is the easiest to use in order to get nicely formatted documents.

• storage: a html document, the way it’s supposed to be shown in the browser.

Conclusion

Automated document updating is a very powerful tool for distributing up to date information, e.g. service versions or usage patterns. With a growing infrastructure this may be the only way to go in order to offer a sub-linear scaling of the support services relative to infrastructure size. That’s it for today, thank you for your read!