This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Troubleshooting Strategies

This article covers issues and how to diagnose them.

1: Get the Confluence Storage Format

2: Get the SharePoint Storage Format

Confluence migrations to SharePoint, as migrations in general, are rarely without issues.

WikiTraccs has been tested with Confluence instances of different versions and different ages and has been hardened against common issues. Some recurring issues like broken page content (from past migrations) or inaccessible external images are gracefully handled.

But what if something appears broken nevertheless?

This page shows how such issues can be diagnosed and which data WikiTraccs creates to help diagnosing a Confluence to SharePoint migration that appears stuck.

The easiest way for you is to put all information in a zip file and send it via email to contact -at- wikitransformationproject.com. I’ll take a look.

My goal is to identify the issue, replicate it in a test environment and make adjustments so that the issue can never occur again.

WikiTraccs grows with every Confluence migrated, since each one is unique. My goal is to make this as painless for you as possible. You can help me helping you by providing as much information as possible to replicate the issue in a test environment, so I don’t have to bother you with more questions.

Of course you can also look at the log files. If there are connectivity issues, or authentication issues the error messages are usually pretty clear, hinting in the right direction.

Which information is available to diagnose issues?

WikiTraccs logs detailed information about everything that it’s doing.

Note

Please include as much of this information as possible when getting in touch. Every bit can help analyzing the situation and providing guidance.

Here’s an overview of what is available and helpful for diagnosing issues, more details follow further down.

What?	Where can I find it?	Why does it help?
Common log files	in `WikiTraccs.GUI\logs` or `WikiTraccs.Console\logs` (depending on whether you are running `WikiTraccs.GUI.exe` or `WikiTraccs.Console.exe`)	Contains detailed information about the whole migration process, including warnings and errors
Progress log files	in `WikiTraccs.GUI\logs\<date-folder>` or `WikiTraccs.Console\logs\<date-folder>` (depending on whether you are running `WikiTraccs.GUI.exe` or `WikiTraccs.Console.exe`)	Contains information about migrated and yet-to-be-migrated pages; see Monitoring Confluence to SharePoint Migration Progress for details
SharePoint Site Pages library	every target site for the migration contains information about migrated pages	Shows detailed information for every page migrated; see Measuring page migration success for details
Confluence page storage format	for any open Confluence page choose View Storage Format; note that the Confluence Source Editor plugin has to be installed for this option to be present	Shows the page as WikiTraccs sees it; page structure and macros can be seen, analyzed and reproduced through a technical lens
Confluence page IDs and page titles of missing pages	open the page properties in Confluence for pages that did not migrate to SharePoint and look at the browser address bar - you see the page ID there; and the page title is the page title	the log files contain any errors that hinder migration and page IDs and titles help finding the right places in the log files

Note

Log files can contain information relating to source and target environments, as well as content.

Examples are:

Confluence source site URL
Sharepoint target site URLs
image URLs
user names, email addresses, and IDs (e.g. when user mappings fail)
snippets of content (e.g. when macro transformations fail)

Replace any content you aren’t willing to disclose before sending those files.

Common log files

Common log files cover information about the whole Confluence to SharePoint migration.

Where can I find those logs?

In WikiTraccs.GUI\logs or WikiTraccs.Console\logs (depending on whether you are running WikiTraccs.GUI.exe or WikiTraccs.Console.exe).

Why are those files useful?

Common log files are useful to troubleshoot all issues, but are essential in root cause analysis when it’s still unclear where the issue originates.

The log file names follow this pattern:

<date>-WikiTraccs.Console.log
<date>-WikiTraccs.GUI<date>.log

For each day new log files are created. Here’s a sample logs folder:

Note

Make sure to choose the right date when sending log files.

The <date>-WikiTraccs.GUI...txt (note the GUI part) log file is created when using WikiTraccs.GUI, for example when testing connections and filling the space inventory. This file is useful to troubleshoot connectivity and authentication issues.

The <date>-WikiTraccs.Console...txt log file is created as soon as a migration starts and WikiTraccs.GUI opens the WikiTraccs.Console console window. Or when using WikiTraccs.Console standalone. This file is useful to troubleshoot issues that happen while migrating.

Progress log files

Progress log files conver the page migration state for all spaces that are part of the migration.

Why are those files useful?

Progress log files are helpful for troubleshooting issues around Confluence pages that are expected to be migrated but are not.

They are in detail covered in Monitoring Confluence to SharePoint Migration Progress.

SharePoint Site Pages library and page metadata

Once pages have been migrated you should scroll through the Site Pages library to see if there is anything of interest.

Why are screenshots useful?

Screenshots of this view can help diagnosing issues with single pages.

This is described in detail in Measuring page migration success.

Specific issues and how to diagnose them

We’ll look at real-world issues and how to diagnose them.

Assume the following migration scenario:

source environment: Confluence 6 at http://localhost:8090/confluence, one space 7SE has been selected for migration in the space inventory
target environment: SharePoint Online site https://contoso.sharepoint.com/sites/arc42-template
the migration is done via WikiTraccs.GUI

The migration is finished when the console window looks like this:

There is nothing left to migrate, the console window can be closed by pressing Ctrl+C.

Issue: Some pages are not migrated from Confluence to SharePoint

The progress log files should tell us more.

But first we look at a successful migration result, to establish a baseline.

Case 1: A successful migration of all pages

There should be 4 log files after successfully migrating one Confluence space:

Of the four files, the first two were created before starting the migration. The last two files were created after having finished the migration.

Note

Keep an eye on the file’s timestamp to read them in the right order.

Here’s the content of the […]aggregated-info.txt file that was created before migrating the Confluence space to SharePoint:

Source Confluence Site: http://localhost:8090/confluence/
Target SharePoint Site: https://contoso.sharepoint.com/sites/arc42-template
Space Key: 7SE
Blog posts included in migration and calculation: no
Confluence page count for space space 7SE: 32
Migrated SharePoint pages that correspond to found Confluence pages in space 7SE: 0
Migrated SharePoint pages overall for space 7SE: 0
Pages yet to be migrated for space 7SE: 32

This shows that WikiTraccs was able to retrieve information about 32 pages in this space and all have yet to be migrated.

Here’s the content of the second […]aggregated-info.txt file that was created after migrating the Confluence space to SharePoint:

Source Confluence Site: http://localhost:8090/confluence/
Target SharePoint Site: https://contoso.sharepoint.com/sites/arc42-template
Space Key: 7SE
Blog posts included in migration and calculation: no
Confluence page count for space space 7SE: 32
Migrated SharePoint pages that correspond to found Confluence pages in space 7SE: 32
Migrated SharePoint pages overall for space 7SE: 32
Pages yet to be migrated for space 7SE: 0

This time there are 32 migrated pages and there are none left to be migrated.

Success. Now we make it more complicated.

Case 2: Pages appear missing

Pages can appear missing when the migration account is not permitted to view all pages.

Here’s an example where a parent page of two child pages has been view-restricted to only the admin account:

Now, when using another Confluence account as migration account, this account won’t see those three pages.

Thus (after deleting all previously created SharePoint pages and starting a new migration) the […]aggregated-info.txt file looks like this:

Source Confluence Site: http://localhost:8090/confluence/
Target SharePoint Site: https://heinrichulbricht.sharepoint.com/sites/arc42-template
Space Key: 7SE
Blog posts included in migration and calculation: no
Confluence page count for space space 7SE: 29
Migrated SharePoint pages that correspond to found Confluence pages in space 7SE: 0
Migrated SharePoint pages overall for space 7SE: 0
Pages yet to be migrated for space 7SE: 29

Only 29 pages are reported for the space that has in fact 32 pages. But 3 of those cannot be seen by the migration account.

The solution in this case is simple: use a migration account that can access all pages that should be migrated.

Case 3: Pages are missing, even after checking permissions

This could be anything, but it should be visible in the log files.

Please send me the log files and page IDs and ideally page titles of pages you’d expect to migrate from Confluence to SharePoint. This information should help to locate any errors related to those pages in the log files.

Please send information via email to contact -at- wikitransformationproject.com.

Issue: The progress bar in WikiTraccs.GUI is stuck

This is caused by pages that have been migrated before and have been updated in Confluence since. It should only happen when migrating the same space at least twice.

The pages that need to be updated can be seen in the progress log files.

The “update mode” feature request is tracked here: Add update mode for already migrated pages.

Technically everything is correct. You need to delete the SharePoint files you want to update, before starting another migration to have them created again.

Issue: The migrated Confluence page doesn’t look good in SharePoint (visual check)

The layout is off? Content is missing? Macros are missing?

There are probably thousands of special cases that can affect the Confluence page migration to SharePoint, hundreds of which are already handled by WikiTraccs.

If there is something wrong with the resulting page please use the options under Contact to get in touch.

Important note about missing macros

Many macros cannot be represented in SharePoint. So they are expected to be missing.

Here’s a primer on what to expect regarding macros: What about those Confluence Macros?

Here’s a list of macros and how they are handled by WikiTraccs: Known Confluence Macros.

Please open a support ticket with a feature request for macros you’d like to see migrated from Confluence to SharePoint. Please also include a description of your use case and a basic idea or mockup of how the migration result in SharePoint should look like.

Please provide the following for your request to be properly handled:

Confluence version
a screenshot of the source Confluence page
a screenshot of the SharePoint page, with the unexpected parts highlighted
the storage format of the source Confluence page - see Get the Confluence Storage Format for instructions on how to get that
the page ID and title of the source Confluence page
SharePoint page metadata for the affected page, like WT: Text Transferred Percent, WT: Failed Transformations and (most important) WT: Transformation Log (a screenshot is fine, see next section for a sample)

Please report issues via email to contact -at- wikitransformationproject.com.

Issue: The SharePoint page metadata shows Transformation Errors and/or a Text Transferred value that is not equal to 100%

WikiTraccs tracks its migration success per page. It has hundreds of transformation rules built-in.

If WikiTraccs discoveres a new layout or macro it cannot handle, it’ll raise a flag by counting the Transformation Errors or potentially missing text.

Here’s a sample screenshot of such an issue, where certain XML tags caused problems, leading to text being skipped:

Note

Please check the affected pages. Sometimes there is one type of macro causing issues technically for many pages, but it doesn’t make a difference visually. So while it would be nice for WikiTraccs to be less error-y in its messaging the migration result is fine.

Please add information about whether you’ve got a blocking issue or whether you are just raising awareness, when getting in touch.

To diagnose those issues the same information as in the previous section Issue: The migrated Confluence page doesn’t look good in SharePoint is needed. The most important part is the storage format because this hopefully allows to replicate and isolate the issue in a test environment.

Please report issues via email to contact -at- wikitransformationproject.com.

1 - Get the Confluence Storage Format

This article covers how to get the storage format of a Confluence page.

The Confluence Storage Format is the technical under-the-hood view of a Confluence page. It’s what WikiTraccs “sees” and transforms when performing the Confluence to SharePoint migration.

Note

You can learn more about the Confluence storage format in Atlassian’s documentation: How to retrieve Confluence Storage Format.

How to view the storage format for a Confluence page? See your options below.

Option 1: Configure WikiTraccs.GUI to save the storage format to disk

WikiTraccs knows the storage format of each page it migrates from Confluence to SharePoint.

The storage format by default is only kept in memory and not persisted to a file.

Here’s how to tell WikiTraccs to store the storage format of every page to a file:

Variant 1: Enable via config file in WikiTraccs.GUI

In WikiTraccs.GUI, go to Settings -> Configure Transformation -> Migration and select the Save page storage XML to disk option.

Variant 2: Enable via config file appsettings.json

Note

Below instructions assume that you did not create appsettings.json before. However, if the file is already present, the additional configuration option needs to be added at the right place. Have a look at the Settings page for documentation of the correct format.

Open the WikiTraccs.GUI folder (this is the folder where WikiTraccs.GUI.exe is stored as well)
Create an empty file appsettings.json inside the WikiTraccs.GUI folder

Open the appsettings.json file in a text editor and put the following text in there:

{
    "CustomSettings": {
        "Debug": {
            "SaveTransformationInputToDisk": true
        }
    }
}

Save appsettings.json
If WikiTraccs.GUI is open: close it and any other (console) windows it opened
Open WikiTraccs.GUI and start a migration

Note

When you need to get the storage format of a page that has already been migrated before, you have to delete the already existing page in SharePoint first. Otherwise WikiTraccs won’t migrate this page again.

Where can I find the exported storage format XML?

After following instructions of one of above variants, WikiTraccs now stores the storage format for every newly migrated page in a file, in the attachment registry.

The attachment registry is a folder where attachments from Confluence are downloaded to, while migrating. You can find it in the AppData folder of your local user account.

The attachment registry path for a Confluence page looks like C:\Users\<username>\AppData\Local\WikiTraccs\<confluenceuserkey>\<confluencebaseurl>\Attachments\<pageid>.

Here’s an example screenshot:

Attachment registry path for Confluence page 118587415.

Note

The screenshot above uses the app Everything from voidtools to locate the storage format file. It provides instant search results and is perfect for finding those files and folders by page ID.

The storage format for a page is stored in a file that is named like xhtml_before-<spacekey>-<pageid>.xml.

Now you can access the storage format for every page that is part of your Confluence to SharePoint migration.

Note

Not using WikiTraccs.GUI? You can also configure WikiTraccs.Console to store the storage format to file. Just use the appsettings.json in the WikiTraccs.Console folder.

Option 2: Use an app to view the storage format

Note

This option is only available when the Confluence Source Editor plugin has been installed.

Here’s the Atlassian documentation on how to view the storage format: How to retrieve Confluence Storage Format

It boils down to this:

Open a page, choose the three-dot-menu, and choose "View Storage Format".

A new browser window will open, showing the storage format.

Option 3: Use the REST API to view the storage format

You can also use the Confluence REST API to view the storage format of a single page in the browser.

You need two pieces of information to do that:

your Confluence base address (examples: https://confluence.contoso.com, https://www.contoso.com/confluence)
the page ID of the page to get the storage format for (example: 123212321)

Using above information you now build the REST API address using this pattern:

CONFLUENCEBASEADDRESS/rest/api/content/REPLACEWITHPAGEID?expand=body.storage,version,container,history,history.lastUpdated,contributors,restrictions,permissions,ancestors&status=current

So, using the Confluence base address https://confluence.contoso.com and page ID 123212321 the address would look like this:

https://confluence.contoso.com/rest/api/content/123212321?expand=body.storage,version,container,history,history.lastUpdated,contributors,restrictions,permissions,ancestors&status=current

Paste this whole address into the address bar of a browser where you are already logged in to Confluence. This should show textual information about the page (in JSON format). It should contain the text "body":{"storage":{"value":".

When sending information to support, please provide the whole content shown by the browser.

2 - Get the SharePoint Storage Format

This article covers how to get the storage format of a SharePoint page.

The SharePoint Storage Format is the technical under-the-hood view of a SharePoint page. It’s what WikiTraccs creates when performing the Confluence to SharePoint migration.

Use the REST API to view the storage format

You can use the SharePoint REST API to view the storage format of a single page in the browser.

You need the following information to do that:

your SharePoint site address (example: https://contoso.sharepoint.com/sites/it-support)
the page item ID of the page to get the storage format for (example: 33)
the title of the Site Pages library, in the site’s default language (examples: Site Pages (for English, note the space!), Websiteseiten (for German))

Note

You can figure out the page item ID by adding the ID column to any view of the Site Pages library.

Using above information you now build the REST API address using this pattern:

SITEADDRESS/_api/web/lists/GetByTitle('SITEPAGESLIBRARYTITLE')/items(PAGEITEMID)

So, using example data from above the address would look like this:

https://contoso.sharepoint.com/sites/it-support/_api/web/lists/GetByTitle('Site Pages')/items(33)

Paste this whole address into the address bar of your browser where you are already logged in to SharePoint Online. This should show textual information about the page (in XML format). It should contain the text <d:CanvasContent1>.

When sending information to support, please provide the whole content shown by the browser.

Note about Site Pages Library title localization

Figuring out the title of the Site Pages library can be tricky when you are viewing the SharePoint site in a language that is not the default site language. The default site language is the language the site has been created in. When using the wrong title you’ll get the error List ‘…’ does not exist at site with URL. Ask the site owner for the site’s default language and use the localized title that matches this language instead.

Cannot figure out the library title?

If you cannot figure out the right title of the Site Pages library, you can use its ID instead.

The address changes slightly and looks like this:

https://contoso.sharepoint.com/sites/it-support/_api/web/lists/GetById('d0dce654-b0b6-4cf6-b305-a83544aa5e10')/items(33)

The ID of the Site Page library is unique across site languages. To get the ID, open the Library Settings of the Site Pages library. Look at the browser address bar, which shows something like /_layouts/15/listedit.aspx?List=%7Bd0dce654-b0b6-4cf6-b305-a83544aa5e10%7D. The ID is enclosed in %7B and %7D, or { and }. Here it is d0dce654-b0b6-4cf6-b305-a83544aa5e10.

Troubleshooting Strategies

How should you handle migration issues related to SharePoint pages created by WikiTraccs?

Which information is available to diagnose issues?

Note

Note

Common log files

Where can I find those logs?

Why are those files useful?

Note

Progress log files

Why are those files useful?

SharePoint Site Pages library and page metadata

Why are screenshots useful?

Specific issues and how to diagnose them

Issue: Some pages are not migrated from Confluence to SharePoint

Case 1: A successful migration of all pages

Note

Case 2: Pages appear missing

Case 3: Pages are missing, even after checking permissions

Issue: The progress bar in WikiTraccs.GUI is stuck

Issue: The migrated Confluence page doesn’t look good in SharePoint (visual check)

Important note about missing macros

Issue: The SharePoint page metadata shows Transformation Errors and/or a Text Transferred value that is not equal to 100%

Note

1 - Get the Confluence Storage Format

Note

Option 1: Configure WikiTraccs.GUI to save the storage format to disk

Variant 1: Enable via config file in WikiTraccs.GUI

Variant 2: Enable via config file appsettings.json

Note

Note

Where can I find the exported storage format XML?

Note

Note

Option 2: Use an app to view the storage format

Note

Option 3: Use the REST API to view the storage format

2 - Get the SharePoint Storage Format

Use the REST API to view the storage format

Note

Note about Site Pages Library title localization

Cannot figure out the library title?