Skip to main content

Migrate Links Pointing to Converted Spaces

If you have spaces linking to Scroll Versions or Scroll Translations managed spaces, and you later convert these spaces into Scroll Documents managed spaces, these links will remain unchanged.

If you want these links to point to the corresponding pages in the converted space instead, you can follow the steps outlined in this article.

Limitations

Please note that the REST resources in this article can only rewrite dynamic Confluence page links, written <ac:link>, created using Confluence's insert Link option. They cannot rewrite static web URLs copied from the browser or tiny links copied from Confluence's share function.

Prerequisites

Before you begin, ensure you meet the following prerequisites:

  • You are logged in as an admin user.

To prevent unwanted content loss

  • Test this procedure carefully in a test system before executing it in a production environment.

  • Review the converted space in the production environment before proceeding, ensuring it's the desired space for all links to point to.

  • Backup your Confluence site, there is no other option to role back changes.

How to Rewrite Links to Point to Page in a Converted Space

Follow the steps below to rewrite dynamic page links pointing to pages in Scroll Versions or Scroll Translations managed spaces, so they instead point to corresponding pages in the newly-converted, Scroll Documents managed space.

Before execution in a product environment

Before executing these steps in a production environment, ensure that:

  • Thorough testing is conducted in a test environment.

  • Your converted Scroll Documents space was reviewed and accepted.

  • The spaces have not been migrated to Cloud already as these resources can only be used on Server/Data Center.

  • You understand that the rewrite will affect all spaces with dynamic page links pointing to the source space of the converted Scroll Documents space, and these steps cannot be undone.

To rewrite links from other spaces so they point to the newly converted space you will follow a two-part process:

  1. Generate a report listing the pages that will be affected by the rewrite.

  2. Execute the actual rewrite.

1. Generate the report

To generate the report, follow the steps below:

  1. Run the conversion to Scroll Documents.

  2. Review the converted space and ensure that this is the final version.

  3. Navigate to the converted space and copy the space key, then save it in a secure location.

  4. Navigate to Space tools > Reorder pages.

  5. Find a page titled "Scroll Document Migration Information" with the current date prefix, for example, "2024-03-15 Scroll Documents Migration Information".

  6. Click on this page to navigate to the Confluence page view, then select page tools (•••) > Page information.

  7. Look at the URL bar and copy the numbers from pageId=15597729 , then save it somewhere.

  8. Now, we will begin by conducting a test run to provide you with a report of the pages that will be affected by this rewrite. To do this, paste the following URL next to the base URL in your browser: /rest/scroll-versions/1.0/rewritelinks/spaces/{convertedDocSpaceKey}/{pageIdOfScrollDocumentsMigrationInformationPage}

    1. Replace {convertedDocSpaceKey} with the space key you copied earlier.

    2. Replace {pageIdOfScrollDocumentsMigrationInfromationPage} with the numbers from the page id you copied earlier.

    3. Hit Enter.

    4. The browser window should display a message like this:
      {"id":"C0A8022B018E42E14EA22C8920D85CB9","clusterNo":-1,"started":false,"cancelled":false,"hasFailed":false,"finished":false,"failureMessage":null,"progress":0,"message":"The task 'Scroll Platform Rewrite Links Task' is currently queued.","resourceLocation":"/rest/scroll-versions/1.0/rewritelinks/task/C0A8022B018E42E14EA22C8920D85CB9"}

  9. Copy the URL from the end of the message. e.g. /rest/scroll-versions/1.0/rewritelinks/task/C0A8022B018E42E14EA22C8920D85CB9

  10. Paste this URL into your browser (next to the base URL, as before) and hit Enter.

  11. You should now receive a message indicating the status of the report task we've just initiated. If finished does not yet appear as true, copy and paste the full browser URL again until it shows a response like the following:{"id":"C0A8022B018E42E14EA22C8920D85CB9","clusterNo":-1,"startTimestamp":1710519045803,"completionTimestamp":1710519045900,"started":true,"cancelled":false,"hasFailed":false,"finished":true,"failureMessage":null,"progress":0,"message":"The task 'Scroll Platform Rewrite Links Task' is currently queued.","resourceLocation":"/download/export/scroll-platform-rewrite-links-result-C0A8022B018E42E14EA22C8920D85CB9.json"}

  12. Copy the download URL, e.g. /download/export/scroll-platform-rewrite-links-result-C0A8022B018E42E14EA22C8920D85CB9.json

  13. Paste this URL next to the base and press Enter. This action will initiate the download of the report.

In the report, you will find a result similar to the following:

CODE 
  "errors" : [ ],
  "asyncTaskId" : "C0A8022B018E42E14EA22C8920D85CB9",
  "dryRun" : true,
  "scmSpaceKey" : "STBC",
  "docSpaceKey" : "converted",
  "numberOfEditedPages" : 1,
  "editedPages" : [ "Links in page {spaceKey: 'LS1', title: 'Test', id: '15597694'} will be edited" ]
}

The dryRun attribute being set to true indicates that this is still the draft version of the process. No links have been rewritten yet.

In the report, you can review the number and specific pages that will undergo editing to have their links rewritten.

When you're ready, proceed to Part 2 of the process, which initiates the process of rewriting the links.

To start the process of rewriting the links, follow the steps below:

  1. Go through the previous report and confirm if you are comfortable with the links on these pages being rewritten to direct to the converted Scroll Documents space.

  2. Paste the URL /rest/scroll-versions/1.0/rewritelinks/spaces/{convertedDocSpaceKey}/{pageIdOfScrollDocumentsMigrationInfromationPage}?persist=true next to the base URL in your browser.
    (info) Note: By adding ?persist=true, you will ensure that the rewrite of the links takes effect.

    1. Replace {convertedDocSpaceKey} with the space key from the converted space.

    2. Replace {pageIdOfScrollDocumentsMigrationInfromationPage} with the page id number from the “Scroll Document Migration Information” page.

    3. Hit Enter.

  3. You should expect to receive a response similar to the following:
    {"id":"C0A8022B018E42F4A38339530E940CBE","clusterNo":-1,"started":false,"cancelled":false,"hasFailed":false,"finished":false,"failureMessage":null,"progress":0,"message":"The task 'Scroll Platform Rewrite Links Task' is currently queued.","resourceLocation":"/rest/scroll-versions/1.0/rewritelinks/task/C0A8022B018E42F4A38339530E940CBE"}

  4. Copy the URL with the task id from the end of the message, e.g. /rest/scroll-versions/1.0/rewritelinks/task/C0A8022B018E42F4A38339530E940CBE

  5. Paste the copied URL next to the base URL and then press Enter.

  6. You should now receive a response similar to the one below. If finished doesn't appear as true, please copy and paste the full browser URL again until it shows a response like the one below:
    {"id":"C0A8022B018E42F4A38339530E940CBE","clusterNo":-1,"startTimestamp":1710520314621,"completionTimestamp":1710520314765,"started":true,"cancelled":false,"hasFailed":false,"finished":true,"failureMessage":null,"progress":0,"message":"The task 'Scroll Platform Rewrite Links Task' is currently queued.","resourceLocation":"/download/export/scroll-platform-rewrite-links-result-C0A8022B018E42F4A38339530E940CBE.json"}

  7. Copy the download URL from the end of the message: /download/export/scroll-platform-rewrite-links-result-C0A8022B018E42F4A38339530E940CBE.json

  8. Paste the download URL next to the base URL and press Enter. A report should now display which pages contain rewritten links.

In the report, you should find a result similar to the following:

CODE 
{
  "errors" : [ ],
  "asyncTaskId" : "C0A8022B018E42F4A38339530E940CBE",
  "dryRun" : false,
  "scmSpaceKey" : "STBC",
  "docSpaceKey" : "converted",
  "numberOfEditedPages" : 1,
  "editedPages" : [ "Edited links in page {spaceKey: 'LS1', title: 'Test', id: '15597694'}" ]
}

"dryRun" : false indicates that this is the actual rewrite operation.

Just as in the first report, you can see how many pages were changed, and which specific pages had their links rewritten. Each edited page has now received a comment in its page history.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close