OBSS Confluence Redirect Plugin

OBSS Confluence Redirect Plugin is an open-source Confluence plugin developed to assist organizations migrating from Confluence Server to Confluence Cloud. One of the key challenges during this transition is the lack of built-in redirection support for legacy Confluence Server page URLs — this plugin solves that problem by introducing a customizable redirection mechanism.

🚀 Features

• Redirects old Confluence Server page URLs to their corresponding Cloud URLs.
• Allows administrators to manage and define redirect mappings.

🛠 Use Cases

• Maintain backward compatibility with bookmarks or shared links.
• Improve user experience by automatically guiding users to updated content locations.

📦 Installation

You can manually install the plugin by uploading the .jar file to your Confluence Server instance.

1. Download the latest version of the plugin from the Releases page.
2. Go to Manage apps in your Confluence Server administration panel.
3. Click Upload app and select the downloaded .jar file.
4. After installation, the plugin will be available in your instance.

📌 This plugin is designed to run on Confluence Server/Data Center and is not needed in Cloud.

🔁 Redirecting a Page

1. Create a redirection rules file
   In your Confluence home directory, create a file named confluence-redirect-plugin-redirection-rules.csv.
   This file should contain the mapping definitions that specify which Server pages should redirect to which target URLs.
   Example format:

   source_page_id	target_page_url	automatically_redirect
   123456	https://obss.tech	0 or 1

2. Add the redirect macro to the pages
   Edit the Confluence Server pages you want to redirect and insert the redirect macro provided by the plugin.
   This macro will:

   • Look up the page ID in the mapping-rules file.
   • Display a redirection message to the user.
   • Optionally perform an automatic redirect, based on the value of the automatically_redirect field.

✅ With the steps you've completed so far, you are now able to redirect any Confluence Server page to any target URL of your choice.

If you want to automatically redirect all migrated pages to their new Confluence Cloud versions, based on your CCMA migration data, continue with the following optional steps.

🧩 Generating the Redirection Rules File from CCMA's Migration Data (Optional)

When migrating from Confluence Server to Cloud using Atlassian's Confluence Cloud Migration Assistant (CCMA), the tool does not provide a built-in way to export data mappings between server resources and their corresponding cloud ones.

To address this limitation, OBSS Cloud Migration Tools offers a mechanism to help you reconstruct and define these mappings.

1. Create raw the Data Mappings File

   CCMA provides support for migrating plugin data in addition to your standard content. If you include the Confluence Redirect Plugin in your app assesment list, we will be able to; Automatically generate a raw mapping file that includes all resource mappings (e.g., page IDs, attachment IDs) discovered during migration.

   ⚠️ Note:
   Atlassian does not currently provide an official way to export complete Server-to-Cloud mappings. Therefore, this method should be considered a workaround. For it to work, you must enable development mode for CCMA. To enable development mode, follow the official guide from Atlassian: Enable dev mode for CCMA

2. Built Redirection Rules File from Raw Data Mappings File

   To transform the raw mapping file into a redirection rules file, you can use the confluence_redirect_plugin_rule_generator.py script provided in this repository.

   This script will:

   • Parse the raw export file generated during migration.
   • For each migrated page, automatically generate the correct Cloud URL.
   • Output a ready-to-use confluence-redirect-plugin-mapping-rules.csv file in the exact format expected by the Confluence Redirect Plugin with appropriate redirection behavior.

   🛠 Requirements:

   • Python 3 must be installed.
   • The user executing the script must have read access to the migrated Confluence spaces in order to resolve Cloud URLs successfully.
   • See the scripts folder for usage instructions and configuration.

   🔧 Example Usage:

   python scripts/confluence_redirect_plugin_rule_generator.py  \
    --server localhost:8080/confluence \
    --username admin \
    --password admin \
    --cloud https://your-cloud-instance.atlassian.net \
    --output out/confluence-redirect-plugin-rules.csv \
    raw-mappings-file-path
   

   ✅ Once you complete these steps, all necessary redirection rules for your migrated pages will be created.

You can then copy the resulting confluence-redirect-plugin-mapping-rules.csv file into your Confluence Server home directory, allowing the plugin to manage redirection behavior centrally.

➕ Injecting Redirect Macros Automatically (Optional)

Up to this point, you have successfully generated redirection rules for all migrated pages.
Now, to make these redirections functional, each corresponding Confluence Server page must include the redirect macro.

Instead of adding the macro manually to each page, you can use the provided confluence_server_macro_injector.py script to automate this process.

This script will:

• Connects to your Confluence Server instance via REST API.
• Automatically injects the redirect macro into each page.

🛠 Requirements:

• Python 3 must be installed.
• The user executing the script must have write access to the migrated Confluence spaces in order to resolve Cloud URLs successfully.
• See the scripts folder for usage instructions and configuration.

🔧 Example Usage:

    python confluence_server_macro_injector.py \
    --base-url "http://localhost:8080/confluence" \
    --username "admin" \
    --password "admin" \
    --file "page_ids_to_inject.txt" \
    --macro "<ac:structured-macro ac:name='redirect'></ac:structured-macro>"

💬 Feedback and Contributions

We welcome contributions and suggestions! Feel free to open an issue or submit a pull request.

📄 License

This project is licensed under the MIT License.

👥 Maintainers

Developed and maintained by the team at OBSS.

---