Overview

All Confluence Spaces have a sidebar, in which you’ll find the page hierarchy as well as any useful links that the Space Administrator has seen fit to add. 

Unfortunately Atlassian provide no clearly documented way of programmatically adding links to the sidebar of a Space.   That doesn’t mean it’s not possible, but rather that Atlassian haven’t seen fit to document how it may be accomplished.

Approach

The question now facing us is “how are links added to a sidebar when using the Confluence web interface?” If we can answer that question, we can programmatically replicate it.

This question is answered over the course of three steps:

1. We first add a shortcut to the sidebar of a Space, using the main Confluence interface.  When we do this, we can watch the network traffic that is generated by this request, and tease it apart to determine the actions we must take to replicate it.

2. By inspecting the Network Traffic, we can extract the CURL request that was sent to the Confluence server. From the CURL request, we can extract the target link:

https://<confluenceURL>/rest/ia/1.0/link

This is the link that the Confluence web interface uses to communicate the desired change to the Confluence server.

3. We then need the format of the data that was POSTed to this link.  If we copy the POST data from the network inspection tab, we get the following JSON data:

{"spaceKey":"<SpaceKey>","customTitle":"http://msn.com","url":"http://msn.com"}

This is the JSON that we need to submit as the body of the POST request.  It has three elements: the target Space Key, the title of the link, and the URL.  You’ll need to fill in your own Space Key.

Note that the JSON includes the Space Key; many requests to the Atlassian REST API are direct calls to a page or Space, but in this instace we’re calling the generic /link/ URL.

The Code

90% of this code is focused around authenticating against Confluence. The actual call to the REST API is the last two lines; we first define the JSON to be passed to the API, and then make the POST call to the URL we discovered in the original CURL request.

$login = Get-Credential
#Rather than hard-coding credentials or using a read-host, get the credentials using a proper credential prompt

$PlainUsername = $login.GetNetworkCredential().UserName
#Convert the resulting login name to a useable string

$PlainPassword = $login.GetNetworkCredential().Password
#Convert the resulting password to a useable string without exposing it during the script execution

$pair = ($PlainUsername+':'+$plainPassword)
#Turn the username and password strings into a pair that can be converted to base64

$bytes = [System.Text.Encoding]::ASCII.GetBytes($pair)
$base64 = [System.Convert]::ToBase64String($bytes)
$basicAuthValue = "Basic $base64"
$headers = @{ Authorization = $basicAuthValue }
#Establish the credentials used to authenticate against JIRA

[String] $body ='{"spaceKey":"<SpaceKey>","customTitle":"TestURL2","url":"http://google.com"}'
#Define the body of the JSON to be passed to the URL
Invoke-RestMethod -Uri ("https://<confluenceURL>/rest/ia/1.0/link") -Method POST -Headers $headers -ContentType "application/json" -body $body

 

The Result

If successful, you’ll get a result that looks similar to this:

id         : 4399
title      : TestURL2
url        : http://google.com
position   : 0
styleClass : external_link
hidden     : False
canHide    : False

This is easily confirmed by going to the Space in question and checking the sidebar for the new Shortcut.