Knowledge Management exists to support an organization’s larger efforts.   That is, it serves to further the larger goals of the organization; Knowledge Management is not the final goal, and rarely is captured knowledge an end unto itself. Unless an organization exists solely to capture information in something like an archival effort, there is almost certainly a larger organizational goal.

It follows that the Knowledge Management team must have strong insight into how the rest of an organization works.  Knowledge ebbs and flows, and the team must be able to both capture information, as well as make it available in an appropriate and timely manner.    

What is appropriate when it comes to access to knowledge? Not all information is destined to be made available to all work units.  It can reasonably be said that there is a hierarchy of sensitivity, and some information meets the criteria to be protected.  The Knowledge Management team must strive strike a balance between total access to information, and creating information silos.

All of that to say, the Knowledge Management team must have insight at every level of an organization.  It must be able to not only ingest and digest data, but must also have

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

 

If I wanted to perform a search of Jira using Groovy and ScriptRunner, I might make use of the SearchRequestService.  This class contains many useful methods, most of them having to do with filters. 

A great many of these take a JiraServiceContext as an argument.  For example, these are the parameters of the createFilter() method:

  	createFilter(JiraServiceContext serviceCtx, SearchRequest request) 

At this point you might start to wonder what a “Jira Service Context” is, and for good reason. Atlassian has once again failed to document exactly what they want, or how to provide it. There is nothing in any of the documentation about what exactly this argument is.  The arguement has it’s own page in the documentation, but that contains no useful information on actually implementing or understanding this parameter.

This is a recurring theme with Atlassian and their APIs.   Rarely is the official documentation helpful or complete; instead we must rely on the kindness of strangers on the internet who post code snippets.  That’s one of the major reasons I started posting the Groovy code that I wrote for Atlassian products; the vendor sure isn’t providing any help, and hopefully what I write will be of help

 

Overview

It’s surprisingly difficult to simply return a list of administrators for a Jira project.    I had to hunt for a relatively simple way to accomplish this.  In the end I found a snippet to build on, written by Mark Markov and located here on the Atlassian forums.

I initially got frustrated because I was looking to return all of the administrators using the libraries that deal with permissions.  Permissions and roles are two very different things in Jira; permissions are set up using a permission scheme, and applied to more than one Jira Project.  Roles and Users are specific to each Project.

Returning the users in a Projec role requires the use of several libraries.   Outlined below are two pieces of Groovy code for accomplishing this.  The first returns all users in a given role, across all of the projects in Jira.  The second returns the users in a role for an explicitly defined project.

The Code (Return all jira users in a role)

As always, we start by declaring our imports.   The foundation of any Jira or Confluence Groovy script is the Component Accessor. We’ll also need the Project Manager and the Project Role Manager

Overview

This script retrieves all the members of a supplied Confluence group, and then retrieves the timestamp of the last time that user logged in to Confluence.

The Code

As you can see from the code below, we’re working with three classes.  The usual Component Locator, the Login Manager, and the Group Manager.

After telling the Component Locator to fetch the Login Manager and Group Manager, we feed the name of a group to the getGroup() method of the Group Manager.  This returns a group as an object.

We also need to define an array that will hold our results. This is because the ScriptRunner console doesn’t easily provide output; you can’t simply throw in a System.out.println().   If you try to use the log as output, it truncates after 300 results.  Instead we need to add the results to an array, and then return the array at the end.

The group object we created is passed to the getMemberNames() method of the group manager, which unsurprisingly returns the names of group members.

Next a for-each statement takes each user in the group and uses the getLoginInfo of the Login Manager to get the login information of each user.

Finally, within

Overview

There are two types of permissions at the Space level in Confluence: Space permissions, and Page permissions.

Page permissions are much simpler than Space permissions, for the simple reason that there are only TWO types of Page permission: VIEW and EDIT.

Getting Permissions From a Page

Simply retrieving the permissions of a Page is pretty simple. As you can see in the code below, you need only fill in a view variables: the page ID, and the type of Permission you’d like review.

 import com.atlassian.confluence.pages.PageManager
import com.atlassian.sal.api.component.ComponentLocator
import com.atlassian.sal.api.component.ComponentLocator
import com.atlassian.confluence.pages.PageManager
import com.atlassian.confluence.security.ContentPermission
import com.atlassian.confluence.user.UserAccessor


def userAccessor = ComponentLocator.getComponent(UserAccessor)
def pageManager = ComponentLocator.getComponent(PageManager)
//Define the user accessor and the page manager

def currentPage = pageManager.getPage(83591282)
//Use the page manager to get a specific page

def editPermissions = currentPage.getContentPermissionSet(ContentPermission.VIEW_PERMISSION)
//Define the type of permissions to be returned

editPermissions.getUserKeys().each{names -> 
//For each person with the type of permissions
    
      log.warn(userAccessor.getUserByKey(names).getName())
    //Take the user key and user it to fetch the name of the associated user
}
 

 

The page ID of any Confluence page is available under Page Information, under the ellipses in the top-right corner:

In this case the Page ID is 83591282.  The other piece of information that the

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

Here’s some code that explores one of the basic tenets of programmatically managing Confluence: retrieving a

list of administrators for a given Space.

On it’s own this code doesn’t do much, but it is foundational to many more complicated solutions that you may be asked to code.

 import com.atlassian.confluence.security.SpacePermissionManager
import com.atlassian.confluence.spaces.SpaceManager
import com.atlassian.sal.api.component.ComponentLocator
//Import the libraries

def spacePermissionManager = ComponentLocator.getComponent(SpacePermissionManager)
def spaceManager = ComponentLocator.getComponent(SpaceManager)
//Invoke the Space Manager by telling the Component Locator to retrieve it for us

def sourceSpace = spaceManager.getSpace("<Space Key>")
//Tell the Space Manager which space we're querying
def admins = []
//Define the list of admins as an array

spaceManager.getSpaceAdmins(sourceSpace).each{ permission ->
admins.add(permission.name)
//For each administrator that the Space Manager returns from the target space, add that name to the array

//Do something else with the names
}

return admins
//Print the list of administrators.
 

 

As you can see, the bulk of the code is just structural, and is similar to other scripts you may have created.  The key is using the Space Manager to fetch the details about the target Space, and then parsing those details for the information you need.