SpaceSync - Confluence Copy Tools

Python scripts to copy Confluence pages, folders, and hierarchies between spaces while preserving structure, attachments, and relationships. Features include single/multiple page copy, recursive folder copy, and detailed progress tracking with JSON export. Robust error handling ensures smooth operations.

If you need to send confluence data to an external entity (clients, partners, consultants...). You can creata a new space and create a guest user that has a read-only access to the target space, and then share it.

Advanced users only : You can even schedule a cron job to update the copied pages regularly.

📋 Prerequisites

Clone the repository

git clone git@github.com:HakimTaoufik/spacesync.git
cd spacesync

Configuring the Python virtual environment

python3 -m venv .venv
source .venv/bin/activate
pip install requests python-dotenv

Generate an API key

Generate an API key at https://id.atlassian.com/manage-profile/security/api-tokens

Click on Create API token, and give it a name like API_token. IMPORTANT : For security reasons, make your API key expire one month from now.

Environment Setup

Rename the .env.example file in the project directory to .env and complete it with your Confluence credentials:

CONFLUENCE_URL="https://company.atlassian.net"
CONFLUENCE_LOGIN="your-email@company.com"
CONFLUENCE_PASSWORD="your-api-token"

Important: Make sure the values stay between quotation marks.

📁 Main tutorial

Start with running space_browser.py with the following command :

python space_browser.py

You will be prompted to specify the space key of the source space (the space you want to copy pages from) and the target space (the space where the copies will be placed). In Confluence, each space is uniquely identified by its space key, which is typically a short, uppercase string visible in the URL or space settings. To find the space key, navigate to the space's home page in Confluence. Click on the three-dot menu (⋯) and select Space settings. The space key will be displayed in the settings.

For example, the space titled "Administrative & Legal" has the space key AL.

You can also see the space key in the URL link of the space home page in your browser : https://company.atlassian.net/wiki/spaces/AL/overview We can see the space key AL in the URL.

Interactive Process:

1. Enter source space key to analyze
2. System builds complete space structure with all pages and folders

   You can ignore the errors and warnings that you will see when the script searches through the source space.

3. Interactive menu displays hierarchical structure with selection checkboxes
4. Manually select/deselect pages and folders using their IDs
   • If you want to select indiviudal pages, select 1, and then copy the ID of the page you want to copy. Copying files preserve the folder hierarchy.
   • If you want to copy a folder and everything inside it, select 2, and then copy the folder ID.
   • Select 6 when you finish selecting the pages, and proceed with the copy.
   • There are more options to select all, clear selections, or exit without copying.
5. Type in the target space key.
6. Confirm operation and monitor progress
7. Review comprehensive results and verify that everything was copied correctly.

🔄 Automated Synchronization

For keeping your copied content up-to-date, SpaceSync supports automated synchronization using cron jobs. This allows you to:

• Schedule regular updates of copied pages and folders
• Maintain synchronized copies for external sharing or backup purposes
• Automate content distribution to multiple target spaces
• Keep documentation current without manual intervention

This is particularly useful when sharing content with external parties (clients, partners, consultants) where you need the shared space to stay current with your source content.

📊 Console Output

All scripts provide detailed console output including:

• Configuration summary
• Progress indicators with emojis
• Success/failure counts
• Detailed results for each item
• Error messages with context

⚠️ Important Notes

Permissions

• You need write access to the target space
• You need read access to source pages and attachments
• API token must have appropriate permissions

Performance Considerations

• Large folders may take significant time to copy
• Network speed affects attachment transfer
• Consider running during off-peak hours for large operations

Space Keys vs Space IDs

• Always use Space Keys (e.g., "MYSPACE") not Space IDs
• Space Keys are visible in URLs and are more stable
• Space IDs are internal numeric identifiers

Limitations

• Cannot copy pages you don't have permission to read
• Some macros may not copy perfectly (depends on macro type)
• Page restrictions are not copied (pages will inherit target space permissions)
• Draft pages are not designed to be copied

🔍 Troubleshooting

Common Issues

"Authentication failed"

• Check your API token is correct and active
• Verify email address matches your Confluence account
• Ensure CONFLUENCE_URL is correct (include https://)

"Page not found"

• Verify page ID is correct
• Check you have read permissions to the source page
• Ensure page hasn't been deleted or moved

"Space not found"

• Use Space Key (not Space ID, and not the Space name)
• Verify target space exists
• Check you have write permissions to target space

"Attachment upload failed"

• Check attachment size limits
• Verify you have upload permissions
• Network issues may cause timeouts