Category: Confluence

I admit, this one is a very specific use case.  But I had a reason to create the script, so maybe someone will find it useful.  I also got to use the .collect method in a useful way!

This script identifies all of the pages that are linked from a target page.  It then compares that list of links to a list of all the pages in the Space.

By doing this, it identifies any pages in the Space that aren’t linked on the target page.  This could be useful if you had a wiki or something, and wanted to know which pages weren’t linked on the front page.

One interesting thing I discovered while doing this is the outgoingLinks method of the page class.   Instead of having to use regex to find the URLs on a page, I simply had to call this method and all of the urls were returned for me.

 

 import com.atlassian.confluence.pages.PageManager
import com.atlassian.confluence.spaces.SpaceManager
import com.atlassian.sal.api.component.ComponentLocator

def pageManager = ComponentLocator.getComponent(PageManager)
def spaceManager = ComponentLocator.getComponent(SpaceManager)

def targetSpace = spaceManager.getSpace("<Space Key>")
def spacePages = pageManager.getPages(targetSpace, true)
def targetPage = pageManager.getPage(<page ID as Long>)

def outgoingLinks = targetPage.outgoingLinks.collect { link -> 

link.toString().minus("ds:")
}

spacePages.each {
  page ->
…

I am entirely self-taught when it comes to ScriptRunner and Groovy.   Everything I’ve learned has been through trial and error, and Googling different permutations of words until I find a solution.

A great deal of the information out there assumes that you already know how to work with ScriptRunner, Groovy, and Jira or Confluence.   I found this to be terrifically frustrating when I first started, as I did not have the requisite knowledge to make use of the information that I was finding.  I didn’t have the skills to put it into context, never mind making use of it in the specific use case to which I was trying to apply it.

For that reason, I’m going back to the beginning.  I’m starting an ongoing series of blog posts about how to get started with ScriptRunner for both Jira and Confluence.  You need to learn to walk before you can run, so for that reason I am calling this series the ScriptWalker series.

Not only will this hopefully be a resource for persons just starting out with ScriptRunner, but it will also force me to be sure that I can teach what I’m doing. In the end, that will make

…

In my previous post I explored how to access the Confluence Cloud Space Permissions API endpoint. 

This Python script extends that, and gives a user a permission set in all Spaces in Confluence. This could be useful if you wanted to give one person Administrative rights on all Spaces in Confluence, for example.

Note that the user must first have READ/SPACE permission before any other permissions can be granted.

 from requests.models import Response
import requests
import json
  
headers = {
    'Authorization': 'Basic <Base-64 encoded username and password>',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
}
  
userID = '<user ID (not name)>'
  
  
url='https://<url>.atlassian.net/wiki/rest/api/space/'
resp = requests.get(url, headers=headers)
data = json.loads(resp.text)
  
  
for lines in data["results"]:
  url="https://<url>.atlassian.net/wiki/rest/api/space/"+lines["key"] + '/permission'
  
  dictionary = {"subject":{"type":"user","identifier": userID},"operation":{"key":"read","target":"space"},"_links":{}}
  
  data = data=json.dumps(dictionary)
    
  try:
      response = requests.post(url=url, headers=headers, data=data)
      print(response.content)
  except:
    print("Could not add permissions to Space " + lines["key"])
…

There’s a great deal of information on the internet about managing Confluence Space permissions with scripts, and how there’s no REST endpoint for it, and how it’s basically impossible.

This is incorrect.

There’s also a lot of information about using the JSONRPC or XMLRPC APIs to accomplish this.   These APIs are only available on Server/DC. In the Cloud they effectively don’t exist, so this is yet more misinformation.

So why all the confusion?

There’s a lot of outdated information out there that floats around and doesn’t disappear even after it stops being correct or relevant. This is one of the major struggles I had when I started learning how to write scripts to interact with Jira and Confluence.    Much of the information used to be relevant, but five or six or ten years later it only serves to distract people looking for a solution. That’s one of the major reasons I started this blog in the first place.

Specific to this instance, another reason for confusion is that the documentation for the REST API does outline an endpoint for Confluence Space permission management, but it includes some very strict limitations that could easily be misinterpreted.

The limitation is this: the

…

This script examines the membership of every group in Confluence.  It returns information in three groups:

  • The Confluence user directories
  • Information about each group in Confluence
  • Information about each user in Confluence

The output looks like the blob below.  As noted, the information is divided into three sections. Formatting is provided by the script:

 

Directory Info

Directory name: Confluence Internal Directory

Group Info

confluence-administrators has 1 members. 1 of those members are active and 0 of those members are inactive
confluence-users has 2 members. 1 of those members are active and 1 of those members are inactive

User Info

Group: confluence-administrators. Username: admin. User account is active. User is in directory: Confluence Internal Directory
Group: confluence-users. Username: admin. User account is active. User is in directory: Confluence Internal Directory
Group: confluence-users. Username: slaurin. User account is inactive. User is in directory: Confluence Internal Directory

 

 

And here is the code:

 import com.atlassian.user.GroupManager
import com.atlassian.confluence.user.DisabledUserManager
import com.atlassian.crowd.manager.directory.DirectoryManager

def disUse = ComponentLocator.getComponent(DisabledUserManager)

def userAccessor = ComponentLocator.getComponent(UserAccessor)
def groupManager = ComponentLocator.getComponent(GroupManager)

def directoryManager = ComponentLocator.getComponent(DirectoryManager)

def activeUsers = 0
def inactiveUsers = 0

def groups = groupManager.getGroups()
def groupInfoStringBuffer = ["<h1>Group Info</h1>"]
def userInfoStringBuffer =
…

You can easily remove all permissions from a Confluence DC Space, or a Confluence Cloud Space.  Confluence Server, though? You’re out of luck.

Imagine you migrated from Confluence Cloud to Confluence Server, and you wanted to remove all permissions on a Space (except  for maybe “View Space”).  That’s a whole lot of manually clicking, unless you script it.  You’re going to need ScriptRunner for this.

The script below takes two inputs: a Space key, and a username.  It needs the username of someone on the Space with Admin access, because Confluence will not let you remove EVERYONE  with admin access from the Space.

Someone gets left behind.

 

Okay so it takes those two pieces of information as variables.  It then makes use of two arrays. The first array is a prescribed selection of the permissions you’d like removed from the Space. Want to let everyone keep the View Space permission type? Take it out of the List!
The second array is generated by the script. It’s a list of every username and group name with some kind of permission on the Space.

We then nest two loops, and iterate through the permission types and usernames.  For each permission type,

…

Overview

There may come a day where you need to script the migration of permissions from one Confluence Space to another.

The permissions of a Confluence Space can be retrieved and treated as collection of objects.  This allows us to easily pass them on to a source page as a new set of permissions.

The Code

We’re using the Soap Service to affect change in the permissions of a Space.  After using the ComponentLocator to declare the SpaceSoapService, we retrieve the source Space as an object.  We do the same for the destination source.

The permissions of the source Space are then extracted.  This is not a single object, but rather a collection of objects.

We iterate through each of the permission objects.  Each object is a collection of attributes.  We need to determine if the permissions object relates to a single user, or a group.  Every type of permission gets it’s own object.

Permissions objects associated with a group look like so:

 [CREATEATTACHMENT,89948111,confluence-space-admins,null,null]

The first attribute is the permission type.  The second is the permission ID. The third element is the group with which this permission is associated, and this is where the format of the permissions object differs

…

 

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

…

Overview

This piece of code does several things. It returns all of the Keys for all of the Spaces in Confluence.  For each Space, it retrieves the associated categories (labels). For those Spaces with a certain category or label, it then performs some permissions management.

 

Space Key Retrieval

Let’s start with retrieving all of the Keys.  This actually starts with retrieving all of the information about all of the Spaces, with spaceManager.getAllSpaces().  Of course before we do that, we need to build the structure of the program.  Here’s the bare minimum required to work with getAllSpaces(): 

 import com.atlassian.sal.api.component.ComponentLocator
import com.atlassian.confluence.spaces.SpaceManager

def spaceManager = ComponentLocator.getComponent(SpaceManager)

def spaceKeys = spaceManager.getAllSpaces()

spaceKeys.each{ space ->
return space.key
}

As always, we need to start by telling the Component Manager what to fetch for us.   We then define a collection of data about all of the Spaces in Confluence. Finally, we can do something with that information.  If I wanted to do something with the Key of each Space, I would work with space.key.

 

Working With SPACE Keys

Now that we have a list of Keys, we can do something with that information. In this case we’re searching for Spaces with a

…

Here’s a chart of the types of permissions that may be granted to a user or group on a Confluence Space.

These values would be useful in conjunction with a script that did something like setting permissions on a Confluence Space.

“Delete Own” is undocumented by Atlassian, but maps to a value of “REMOVEOWNCONTENT”. 

“Restrictions – Add/Delete” is referenced as “Pages – Restrict” in the Atlassian documentation, which is neither clear nor helpful.

 

     

Name Description Programmatic Value    
   
   
         
View View all content in the space VIEWSPACE    
         
Pages – Create Create new pages and edit existing ones EDITSPACE    
         
Pages – Export Export pages to PDF, Word EXPORTPAGE    
         
Restrictions – Add/Delete Set page-level permissions SETPAGEPERMISSIONS    
         
Pages – Remove Remove pages REMOVEPAGE    
         
News – Create Create news items and edit existing ones EDITBLOG    
         
News – Remove Remove news REMOVEBLOG    
         
Comments – Create
…