How to copy or rename a space in Confluence

Still need help?

The Atlassian Community is here for you.

Ask the community

Currently, neither Confluence server nor Confluence cloud has a supported method of copying a space or changing space keys. The information on this page is provided for informational purposes only, and will not be directly supported by Atlassian. Should you wish to pursue possible workarounds in light of this limitation. This information is not actively maintained and should be thoroughly tested before applying to any production environments.

Purpose

For when you want to copy or rename a space in Confluence

Solutions

Solution 1: Use an add-on from the Atlassian Marketplace

There's no built in way to copy a space in Confluence; but there are a number of third party or unsupported plugins that should do the trick:

  1. Copy Space Plugin.
    The best option is to install the Copy Space Plugin.
    (warning) Note that this plugin is a Ship-It release, and although developed by an Atlassian developer it is not officially supported by Atlassian. Please read the notes about the plugin at https://ecosystem.atlassian.net/wiki/display/CPSP/Confluence+Copy+Space+Plugin.
    (warning) Note that copying a space can take a long time and may appear to time out when using this plugin (even when the copied space is created correctly). If this occurs, please ensure that your space has not been created before attempting to copy the space again.
    Read the developer's notes in the Atlassian blogs. Source code is available for modification from the Bitbucket repository: https://bitbucket.org/atlassianlabs/confluence-copy-space-plugin
  2. Copy Page Tree plugin which can be used to copy the pages from one space to another one.
  3. Space Tree Creator that allows copying a tree into space, along with some find and replace tools.
  4. Bob Swift CLI tool can also be used to copy a space using command line.



Solution 2: Manually Clone Or Rename A Space

Alternatively, it is possible to manually clone or rename a space by modifying an XML backup of the target space.


If you are renaming many spaces at once, it may be easier to export the full instance. Please note that in the case of a full site export, the exportDescriptor.properties file will not need to be altered, but you will need to change the space keys in:

<export_folder>/plugin-data/com.atlassian.activeobjects.confluence.spi/activeObjectsBackupRestoreProvider.pdata

Full site backups are known to be problematic when importing back into Confluence, so if you encounter any issues please attempt a space-by-space renaming.


Stage 1: Rename Space

Generate the XML backup and create a test instance

  1. Select a new, unique space key and name for the second space. Space keys may only consist of ASCII letters or numbers (A-Z, a-z, 0-9) and no empty spaces, special characters or underscore are allowed in the key. If we have one of the invalid characters in the space key, the re-import will fail with a stack trace.
  2. Clone your production Confluence instance to a test server on another computer now. (For instructions, see Restoring a Test Instance from Production.) You should now have a production server and test server both containing the same data and can avoid the risk of corrupting your production Confluence instance.
  3. On the test server, login as an administrator.
  4. Go to Space -> Space Tools -> Content Tools -> Export -> XML -> Next -> Full Export -> Export Space and export the target space as XMLincluding attachments.



  5. Save the space backup.

Edit the Entities.XML file

  1. Open the space backup file with a zip file editor and find the file entities.xml.
  2. Edit entities.xml in a text editor.
  3. Do a 'Search & Replace' on the old space name as shown below. Swap out Old Space Name and New Space Name for the actual names.

    Search For

    Replace With

    [CDATA[Old Space Name]

    [CDATA[New Space Name]

  4. Do a 'Search' for any occurrences of the old space name that occur in user content. You may wish to replace some or all of these references with the new space name. Replace Old Space Name and New Space Name with the actual names.

    Search For

    Old Space Name

  5. Do 'Search & Replaces' for each of the space key patterns as shown below. Note carefully that letter casing matters here: The placeholder variables OLDKEY/NEWKEY represent to keys in UPPER or MIXED-CASE and oldkey/newkey represent keys in all-lowercase.

    Search For

    Replace With

    Comment

    OLDKEY

    NEWKEY


    spaceKey=OLDKEY

    spaceKey=NEWKEY


    [OLDKEY:

    [NEWKEY:


    key=OLDKEY]

    key=NEWKEY]


    <spaceKey>OLDKEY</spaceKey>

    <spaceKey>NEWKEY</spaceKey>

      

    ri:space-key="OLDKEY"

    ri:space-key="NEWKEY"

    Perform this step if links within the renamed space should point to itself and not the original space key, otherwise skip

    ri:space-key=OLDKEY

    ri:space-key=NEWKEY

    Perform this step if links within the renamed space should point to itself and not the original space key, otherwise skip

    <ac:parameter ac:name="spaces">OLDKEY</ac:parameter>

    <ac:parameter ac:name="spaces">NEWKEY</ac:parameter>


    <ac:parameter ac:name="spaceKey">OLDKEY</ac:parameter>

    <ac:parameter ac:name="spaceKey">NEWKEY</ac:parameter>


    <property name="lowerDestinationSpaceKey"><![CDATA[NEWKEY]]></property>
    
    <property name="lowerDestinationSpaceKey"><![CDATA[newkey]]></property>
    

    Beware new key is used on both sides


    <property name="lowerKey">![CDATA[NEWKEY]]></property>
    
    <property name="lowerKey"><![CDATA[newkey]]></property>
    

    Beware new key is used on both sides


    spaceKey=OLDKEY

    spaceKey=NEWKEY


    spacekey=oldkey

    spacekey=newkey


  6. Save the modified entities.xml.
  7. Overwrite the original entities.xml in the space backup with the modified version.

Edit the exportDescriptor.properties file

  1. Also edit the exportDescriptor.properties file in a text editor
  2. Change the spaceKey value in the exportDescriptor.properties file to the new spaceKey

Restore to test instance for verification

  1. Login to the test instance as a Confluence administrator.
  2. Go to ->General Configuration -> Backup & Restore. Under 'Upload a zipped backup to Confluence', browse to select the modified space backup. Check the 'Build index' option and select 'Upload & Restore'.
  3. Once the restore process has completed, access the new space and test that you can access pages, embedded links and attachments. Any error in this step indicates that your search and replace was performed incorrectly and you should to retry from step 2.
Stage 2: Restore On Production
  1. Backup your production instance now.
  2. Login to the production instance as a Confluence administrator.
  3. Go to  -> General Configuration -> Backup & Restore. Under 'Upload a zipped backup to Confluence', browse to select to the modified space backup. Check the 'Build index' option and select 'Upload & Restore' If any data loss occurs as a result of using this workaround, immediately revert to the backup.
  4. Once the restore process has completed, access the new space and test that you can access pages, embedded links and attachments. If any error occurs during this step, revert to the site backup.
  5. If renaming a space, you can delete the old space by going to Space -> Space Tools -> Overview -> Delete Space. Click OK to remove the old space.
Stage 3: Rename Space References

Links in other spaces to the old space will remain unchanged. If you are renaming a space, you will need to change these links to point to the new space. Users who are copying a space can leave the links pointing to the original space by skipping this stage.

Changing these links depends on if you want to change every link, or only some. If not all links must be changed or you are unwilling to stop your production instance, this must be done by editing each page individually. If all links must be changed, follow the instructions below.

  1. Create a site XML backup including attachments from  -> General Configuration -> Backup & Restore.
  2. Save the site XML backup file.
  3. Stop the production instance.
  4. Create two copies of the site backup. Keep one copy as the original, unmodified backup, the other will be modified. Rename the backups so that it is clear which is being modified.
  5. Open the copy for modification and edit entities.xml.
  6. Do four 'Search & Replaces' on each of the references to the old space key as shown below. Swap out oldkey and newkey for the actual keys

    Search For

    Replace With

    [oldkey]

    [newkey]

    spaceKey=oldkey

    spaceKey=newkey

    [oldkey:

    [newkey:

    key=oldkey]

    key=newkey]

  7. Save the updated entities.xml back into the modified site XML backup file
  8. Start the production instance
  9. Import the modified site XML backup from  -> General Configuration -> Backup & Restore. If you have any problems, revert to the original unmodified backup and redo the links manually instead

Done.


Related

 Copy Space Template: There is a feature request being tracked at  CONF-4538 - Getting issue details... STATUS

Last modified on Feb 13, 2018

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.