Space Hierarchy & Breadcrumbs

Space hierarchy and Breadcrumbs plugin for Confuence can be used for following purpose:

    • Creating Space hierarchy (Parent-Child relationship, grouping similar spaces)
    • Breadcrumbs at top pages which provides easy navigation between spaces in hierarchy

Creating Space Hierarchy

Space hierarchy can be created by setting parent child relation between spaces. As soon as plugin is installed 'Hivestone' section is created under Space Admin section. Hivestone section provides 'Set Parent space' capability. After installing plugin Space Admin section will create Hivestone section as shown in image:

Hivestone Space Hierarchy

Creating sample space hierarchy - If we have a space named 'Continents' with spacekey 'continents' and there is another space named 'North America' with spacekey 'northamerica'. Similarly space having name 'USA' with spacekey 'usa' and space having name 'Canada' with spacekey 'canada'. If Space Admin->Hivestone->Set parent space of 'North America' is set to 'continents' and that of 'USA' and 'Canada' is set to 'northamerica' following hierarchy will be created (Continents and North America part)

Above hierarchy will be displayed at any place where 'Space Hierarchy' macro is used and spacekey 'continents' is provided as parameter to macro. Home page of space 'Continents' is good place to insert 'Space Hierarchy' macro for above case. Following similar steps we can create multilevel hierarchy structure. Example multilevel hierarchy could be like this:

Rest apis are also provided to update the Patent space setting and get the children space of provided space. Apis included in plugin are

    • <Base URL>/rest/hcms_space_hier/1.0/space_settings/parent-fetch/space-key/{space-key} (GET)
    • <Base URL>/rest/hcms_space_hier/1.0/space_settings/children-fetch/space-key/{space-key} (GET)
    • <Base URL>/rest/hcms_space_hier/1.0/space_settings/parent-save (POST with data space-key and parent)

Breadcrumbs at top of pages

Breadcrumbs at top of pages could be displayed using 'hivestonebreadcrumb' macro which comes along with Space Hierarchy & Breadcrumbs plugin. To apply this macro globally General Configurations-> Look and Feel section could be used. {hivestonebreadcrumb} could be provide in header section.

In case some Theme is applied globally then Configure Theme link could be used to insert the macro in header of each page.

Breadcrumbs will appear at top of each page as shown in image

Best part of plugin is that it does not impact the performance of Confluence server instance which maybe the case with other available plugins.

FAQ

Q. I want to see the each and every hierarchy of my Confluence site. How to do this?

Ans. It can be done using following steps-

    • Set Parent Space of every root space of every hierarchy as 'dashboard'. In above explained example set parent space of 'Continents' and 'Hivestone' as 'dashboard'.
    • Now use 'Space Hierarchy' macro and provide 'dashboard' as parameter to macro.
    • Wherever you will use above macro with dashboard as parameter whole hierarchy will start appearing as macro output.

Q. I have got list of spaces with parent and child relationship. Can I insert this information in Space Hierarchy & Breadcrumbs plugin programatically without going through each space settings?

Ans. Yes, Space Hierarchy & Breadcrumbs macro provides open rest API to get and set parent child relationship. We have provided 3 api's to get and set relationship information.

  • <Base URL>/rest/hcms_space_hier/1.0/space_settings/parent-fetch/space-key/{space-key} (GET)
  • <Base URL>/rest/hcms_space_hier/1.0/space_settings/children-fetch/space-key/{space-key} (GET)
  • <Base URL>/rest/hcms_space_hier/1.0/space_settings/parent-save (POST with data space-key and parent)

Perl, python or java can be used to feed the information in system using above apis.

Sample Perl script to do above operations would look like this:

use RPC::XML;
use RPC::XML::Client;
use HTTP::Request::Common qw(POST);
use LWP::UserAgent;
use HTTP::Cookies;
use LWP::Simple;
use Data::Dumper;

$ua =LWP::UserAgent->new;
my $cookie = new HTTP::Cookies( ignore_discard => 1 );
$ua->cookie_jar( $cookie );

#Provide Confluence Wiki Base URL

our $server = "http://confluence.hivestone.com";

#$map_file should have list of parent and child spaces. 
#Each line should contain one entry.
#Each line should contain either - Space_Name_of_Parent,Space_Name_of_Child
#or line should contain - Space_key_of_parent,Space_Key_of_Child
#
our $map_file = "Subspace_Parent_Child_Hierarchy.txt";

#If file has space names then $file_has_space_names should be 1
#If file has space keys then $file_has_space_names should be 0
our $file_has_space_names = 1;

print "#####################################################################\n";
print "This script updates the space hierarchy as per parent child \nrelationship provided in file '$map_file' \n\n";
print "Confluence Wiki Base URL as provided is '$server'\n\n";
print "#####################################################################\n\n";
print "Please provide Username for login to Wiki:";
our $username = <STDIN>;
chomp($username);
print "Please provide password for '$username':";
our $password = <STDIN>;
chomp($password);
our %space_Name_Key_Map;
our @parent_child_relationships ;

my $URLPrefix="$server/rest/hcms_space_hier/1.0/space_settings";

open(FILE,"$map_file") || print "Unable to read $map_file \n";
@parent_child_relationships = <FILE> ;
close(FILE);
my $relationship_count = $#parent_child_relationships + 1 ;

print "Total parent child relationships provided in '$map_file': $relationship_count \n";

my $rpcserver="$server\/rpc\/xmlrpc";
our $client = RPC::XML::Client->new($rpcserver);
$token = login_to_wiki();

if($file_has_space_names == 1){
    &get_spaces_namekeymap();
}

&create_space_hierarchy();

sub login_to_wiki() {
  # Connect to wiki
 my $response = $client->send_request('confluence2.login', $username, $password);
 if (undef == $response) {
  my $msg = "Undefined response from wiki server while trying to login to Confluence.\n";
  print $msg;
  print LOGFILEH $msg;
  $response = $client->send_request('confluence2.login', $username, $password); # Try again
  if (undef == $response) {
   die "Quitting..\n";
  }

 }
 my $newToken = $response->value;
 return $newToken;
}


sub get_spaces_namekeymap () {

 print "Getting space information from Wiki\n";
 $response=$client->send_request("confluence2.getSpaces",$token);
 #print Dumper($response) ;

 my @spaceSummaries=@{$response->value};
         
 my $space_count = 0;
 my $spaceKey = "";
 my $spaceName = "";
 foreach $spaceSummary(@spaceSummaries)
 {
  $spaceKey = $spaceSummary->{key} ;
  $spaceName = $spaceSummary->{name};
  $space_Name_Key_Map{$spaceName} = $spaceKey;
  #print "KEY::$spaceKey, NAME::$spaceName \n";
  $space_count += 1;
 }
 print "Total Wiki spaces Visible to you: $space_count\n\n";
}

sub create_space_hierarchy() {

    foreach $relation (@parent_child_relationships) {
 my @array = split(",", $relation);
 my $parent = $array[0];
 $parent = &trim($parent);
 my $child = $array[1];
 $child = &trim($child);
 my $parent_key = "";
 my $child_key = "";
 if($file_has_space_names == 1){
     if(exists $space_Name_Key_Map{$parent} ){
         $parent_key = $space_Name_Key_Map{$parent} ;
            }else{
         print "No space found for provided parent Space Name '$parent' \n";
         next;
            }
     if(exists $space_Name_Key_Map{$child} ){
         $child_key = $space_Name_Key_Map{$child} ;
            }else{
         print "No space found for provided child Space name '$child' \n";
         next;
            }
        }else{
     $parent_key = $parent;
     $child_key = $child;
 }
 my $status  = &setParent($parent_key,$child_key);
 if($status == 1){
     print "  Setting parent of '$child':$child_key as '$parent':$parent_key - SUCCESS\n";
        }else{
     print "  Setting parent of '$child':$child_key as '$parent':$parent_key - FAIL\n";
 }

 #####Check the parent space
 #&getParent($child_key);
 
 #####Check the chldren spaces
 #&getChildren($parent_key);
    }
}

sub getParent($) {
    my($spacekey) = @_ ;
    #Get parent space of given space
    my $Get_from_url = "$URLPrefix/parent-fetch/space-key/$spacekey";
    my $request=HTTP::Request->new (GET => "$Get_from_url");
    $request->authorization_basic("$username","$password");
    my $response = $ua->request($request);
    #print Dumper($response);
    #print "Request status: ";
    #print $response->is_success;
    #print "\nResponse Message: $response->{_content}";
}

sub getChildren($) {
    my($spacekey) = @_;
    #Get child space of given space
    $Get_from_url = "$URLPrefix/children-fetch/space-key/$spacekey";
    my $request=HTTP::Request->new (GET => "$Get_from_url");
    $request->authorization_basic("$username","$password");
    $response = $ua->request($request);
    #print Dumper($response);
    print "Response Message: $response->{_content}";
}

sub setParent($$) {
    my($parent_spacekey, $spacekey) = @_ ;
    #Set parent space of given space
    my $POSTFROMURL="$URLPrefix/parent-save";
    my $post_data="space-key=$spacekey&parent=$parent_spacekey";
    my $request=HTTP::Request->new (POST => "$POSTFROMURL");
    $request->authorization_basic("$username","$password");
    $request->header("X-Atlassian-Token" => "no-check"); #This may be required if there is some configuration issue
    $request->content($post_data);
    my $response = $ua->request($request);
    #print Dumper($response);
    #print "Response status: ";
    #print $response->is_success ;
    #print "\nResponse Code: $response->{_rc} \n";

    return $response->is_success ;
}

sub trim() {
  my ($name) = @_;
  $name =~ s/^\s+//;
  $name =~ s/\s+$//;
  return $name;
}



Credits

Our customers play and important role in making our solution better. Thanks to everyone who provided feedback, suggestions and reported some issues.

Atlassian Marketplace Link of this plugin - Space Hierarchy & Breadcrumbs