Skip to main content
Skip table of contents

Upgrade to Scroll Documents' New Data Model

To advance Scroll Documents as a full-fledged solution for technical communication on Confluence Cloud, we have introduced a new data model with our latest changes to the app (May 2021).

The new data model will prepare Scroll Documents for more advanced content management, version, variants and multi-language support.

How am I affected?

The new data model does not change how you use or experience the app. It does, however, change the way documents are created and managed under the hood.

As a result, you will not be able to interact with your existing documents and versions until you use our migration tool to convert all your documents and versions to the new format.

Please note: Any documents that were created before 2019-07-15 and are still using the old legacy format, will not be available for this migration.

Convert Documents with the Migration Tool

The migration is done only once, for all documents in your entire instance (not per space).

You will need to be a Confluence admin with read and edit permissions on all documents and document versions in order to access all documents in your instance, and thus run the migration.

Initiate the migration process from Confluence administration console:

  1. Open your Confluence instance that contains Scroll Documents

  2. Select the cog icon (Settings) in the top-right Confluence navigation

  3. From the sidebar, select Migration (under the section Scroll Documents).
    You will find a list of all your documents in your instance that need to be migrated:

    Migration tool with a migration that has not been started yet

    The list is organized by Confluence spaces.

  4. Click Start Migration to start converting all your documents, including all its versions. To convert only selected documents, click ‘Alt’ and hold your mouse for 5 seconds. Additional ‘Migrate’ buttons will appear next to each document that you can click to start the process for one document.

  5. The Status column will show the progress and result of your document’s conversion:

    Migration tool with a migration in progress
  6. The migration is finalized when all statuses have changed to either ‘Migrated’ or an error status:

    Migration tool with a finalized migration

All documents with the status Migrated will be visible and usable in their corresponding locations, along with their different versions.

Clicking the document title will navigate you to the root page of the document, from where you can start interacting with the document and its versions again.

Troubleshoot Common Problems

Migration fails for some document(s)

Migrating to the new data model using the migration tool might fail for some documents.

You can identify which documents were not successfully migrated to the new data model by checking the Status column. A failed document migration will not impact successfully migrated documents.

Click the Migration failed status to see details of the error. These details might already help you identify and solve the problem.

If you need further support, please download the status report from the Migration Tool screen (linked in the error message on top of the page)and reach out to help@k15t.com.

Known reasons

Some of the known issues and reasons for why a document migration fails are:

  • You have more than 100 read requests per instance

  • You have more than 100 read confirmations per read request.

This read request limitation is due to a Confluence bug that affects the use of the REST API. Documents with these characteristics cannot be migrated.

I keep seeing a migration message even after successfully migrating all documents

After a successful migration, all your documents listed the migration tool will show the status Migrated. The Document Library will go back to normal again and show your migrated document(s).

Even after a successful migration, you might still see the following message in the document library:

| Some of your documents have not been converted to the new format yet.

In those cases, please check and purge your space trash for deleted documents:

  1. Open Space setting > Content Tools > Trash

  2. Click Purge all to purge all pages in the trash or purge only the pages that belonged to a document.

  3. Confirm.

To identify the exact pages that belonged to a document, navigate to any page in your Confluence instance and run the following code in your browser’s developer console:

CODE
fetch('/wiki/rest/api/content/search?expand=space,container&limit=200&cql=type+%3D+%27ac%3Ak15t-scroll-document-versions-for-confluence%3Adocument%27').then((r) => r.json()).then((r) => { for(const d of r.results) d.status === 'trashed' && console.log(`${d.space.name} (${d.space.key}): ${d.container.title}`) }).catch((e) => { console.error(e); })

The console will output the page title along with the space where the page is located.

Need further help?

If you are unable to proceed with your migration or have any other concerns, please download the status report from the Migration Tool screen (linked in the error message on top of the page) and reach out to help@k15t.com. We are more than happy to help.

JavaScript errors detected

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

If this problem persists, please contact our support.