Group renames
- Kyle McEwan
Renamed Space Groups retain permissions (all or current Space based on rename scope) and user membership that were present prior to renaming. The previous Group name will only be removed once CSUM has validated that all data has been transferred to the new Space Group name successfully.
Confluence does not have a built in method to allow the renaming of a Group once it has been created. Space Groups present within CSUM can be renamed from within CSUM.
How to rename a Space Group
To rename a Space Group you must first select an existing Group, pressing a Group name in the list of Space Groups will select the Group, once selected the Group name will be highlighted. To rename the selected Group, press the Rename Group button above the Group membership section.
Upon pressing Rename Group a pop-up window will appear where you can define the new name for the Space-Group, the name will be prefixed and suffixed with the preconfigured prefix and suffix that has been configured with CSUM.
Enter the new name for the Space Group within the New Name text field and then ensure that you have chosen the correct Rename action scopes to perform with this rename.
The Rename action scopes to be decided are Transfer permissions, Cleanup Space permissions and Cleanup Page permissions.
Once you are sure you are ready to perform the Group Rename, press the Rename button to rename the Group. The pop-up window will close once the renaming process has completed, the newly renamed Group will then be shown in the list of Space Groups within CSUM.
Rename action scopes
There are 3 different Rename action scopes and the maximum scope that can be chosen for these values are determined in your main CSUM config by your system admin, as shown below:
Transfer permissions
The Transfer permissions Rename action scope is related to which Permissions will be transferred from the original Group to the new group. This relates to Space and Page permissions and the maximum available scope is determined by the Allow Global scoped Space group renames select shown above in your CSUM config.
For example, when your system admin sets this value to NO in your CSUM config, the option to Transfer permissions at a Global scope is removed, as shwon below:
When this is set to Local for a rename, then only Space permissions and Page permissions for Pages within the current Space will be transferred if they exist for the original Group, to the new Group.
If this is set to Global for a rename, then every Space and Page permission belonging to the original group will be transferred to the new group
Cleanup Space permissions
The Cleanup Space permissions Rename action scope is related to which Space permissions will be removed during the Group rename for the original group. The maximum available scope is determined by the Maximum cleanup Space permissions scope select shown above in your CSUM config.
When this is set to Off for a rename, then we will not search through any Spaces in your instance to remove the Space permissions for the original group. This will be a LOW Potential performance impact but will lead to all Space permissions to remian for the original group in Spaces where it was present prior to the rename. They will appear with the Group not found text as the Group no longer exists, as shown below:
When this is set to Local for a rename then we will only search through the current Space to remove the Space permissions for the original group. This will also be a LOW Potential performance impact but will lead to all Space permissions to remian for the original group in all Spaces where it was present prior to the rename, other than the current Space.
When this is set to Global for a rename then we will search through every Space in your instance to remove the Space permissions for the original group. This will be a MEDIUM Potential performance impact but will lead to no Space permissions to remian for the original group in all Spaces where it was present prior to the rename.
Cleanup Page permissions
The Cleanup Page permissions Rename action scope is related to which Page permissions will be removed during the Group rename for the original group. The maximum available scope is determined by the Maximum cleanup Page permissions scope select shown above in your CSUM config.
When this is set to Off for a rename, then we will not search through any Pages in your instance to remove the Page permissions for the original group. This will be a LOW Potential performance impact but will lead to all Page permissions to remian for the original group in Pages where it was present prior to the rename. They will appear with the Group not found text as the Group no longer exists, similar to as shown in the prior screenshot above.
When this is set to Local for a rename then we will only search through the current Spaces Pages to remove the Page permissions for the original group if they exist. This will be a MEDIUM Potential performance impact but will lead to all Page permissions to remian for the original group in all Pages in Spaces where it was present prior to the rename, other than the current Spaces Pages.
When this is set to Global for a rename then we will search through every Page in every Space in your instance to remove the Page permissions for the original group if they exist. This will be a HIGH Potential performance impact but will lead to no Page permissions to remian for the original group in all Pages for every Space where it was present prior to the rename.
Potential performance impact
The potential performance impact shows the potential perfomance impact that the chosen scope for each Rename action scope could have on your rename.
For example, if you select to perform the Global Cleanup Page permissions then the Potential performance impact for this will turn to HIGH, as seen below:
The reason this will appear as HIGH is due to the need for us to search through every single Page in your instance and remove any permissions for the original group, if they exist. The more Pages that you have in your instances, the more of a performance impact this could have on your rename, leading it to take a larger amount of time to complete.
Rename actions to scope summary table
Rename action to scope | Scope | Potential performance impact | Action that will occur |
|---|---|---|---|
Transfer permissions | Local | LOW | Transfer Space and Page permissions from the original Group to the new Group for only the current Space |
Transfer permissions | Global | HIGH | Transfer Space and Page permissions from the original Group to the new Group for all the current Space |
Cleanup Space permissions | Off | LOW | Remove Space permissions for the original Group for no Spaces |
Cleanup Space permissions | Local | LOW | Remove Space permissions for the original Group for only the current Space |
Cleanup Space permissions | Global | MEDIUM | Remove Space permissions for the original Group for all Spaces |
Cleanup Page permissions | Off | LOW | Remove Page permissions for the original Group for no Pages in any Spaces |
Cleanup Page permissions | Local | MEDIUM | Remove Page permissions for the original Group for only the current Spaces Pages |
Cleanup Page permissions | Global | HIGH | Remove Page permissions for the original Group for all Pages in all Spaces |
Renaming a Group to an existing Group
Since CSUM version 3.1.16
If you attempt to rename a Space Group to the name of another existing Space Group then a warning prompt will appear informing you that you can continue or cancel the Space Group rename.
If you continue, the Space Group to be renamed will be merged with its permissions transferred into the existing Space Group which already has the entered new name and the Space Group with has been renamed will then be removed on completion. However, if you press cancel then the Space Group rename will not take place.
Rename tasks activity
You can now view the last activity of a Group rename task in the Tasks tab. If a rename has been inactive for more than 15 minutes, if you attempt this rename again, the first task will be cancelled and the new rename task will be queued to try and finish this Group rename.
You can now also see the initial Group name, the new Group name as well as the Rename action scopes for which an existing Group rename task had been given from the above mentioned Tasks tab, within a Group renames tasks individual information. As shown below:
While a Space Group has a rename task in the queue or currently running, you can not modify this Group until the rename has finished, whether successfully or not.
Group Rename Recovery steps
Potential problems and their solutions
If a rename has not completed successfully or is taking a very long time and you have not cleaned up any of the original Groups Space or Page permissions. If the rename is still currently running, go to the Tasks tab and cancel the rename in progress before renaming the new group back to the original group. This should revert back everything back to the original state.
However, if you cleaned up any of the Space for Page permissions of the original group during the rename, then these may be lost even when reverting the new group back to the original group and will need to be added again.
Why scope Group renames?
When a Group rename Transfers permissions Globally, we have to check every Space and Page within your instance in order to correctly transfer Original Group permissions to the new Group, if they exist. This can take a very long time and could significantly negatively impact performance.
The Locally scoped Group rename will only check permissions for the original Group within the Space in which the original Group is based within as well as the Pages within this Space, assigning these to the new Group. This significantly reduces the negative impact on performance.
Therefore if the group being renamed only has Space and Page permissions related to the current Space, a Local rename should be sufficient and therefore decrease the potential performance that the Group rename could have. But BEWARE of the risks, which will be mentioned in the section below.
Warnings
Specific warnings
Transferring permissions Locally may decrease the Potential performance impact of the Group rename, however, the new Group will not keep any Space or Page permissions for any Spaces or Pages other than for the current Space. If these are required, they will need to be added again in the future.
If Cleanup Space or Page permissions is set to off, then beware there will be remaining Space or Page permissions for the original Group that will need to be removed manually, if desired in the future.
If you Cleanup Space or Page permissions Globally, then beware that if the rename does not manage to complete successfully, if you attempt to revert the new Group back to the original Group that Permissions may have been lost on the way and need to be added again if required.