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

Return to the regular view of this page.

Migration Waves

This article shows how to define and use migration waves.

1: Include/Exclude Filters

You can assign waves to your content selectors in the Space Inventory.

When starting a migration, you can optionally specify the waves to migrate.

Note

Migration wave configuration is optional. When using WikiTraccs.GUI, leave the Waves & filters text box empty to tell WikiTraccs to not care about waves.

Tip

The same field also supports filters for spaces and content IDs (note: starting with WikiTraccs v1.33.0). If you want to combine wave selection with ad-hoc filters, have a look at Include/Exclude Filters.

What are waves?

In the context of WikiTraccs, waves are labels that you assign to selectors in the Space Inventory.

Those labels can be:

numbers such as 1, 2, or 100
names such as pilot, review, or archive

When starting a migration you can tell WikiTraccs which of those waves it should migrate.

Using waves you can prepare a multi-wave migration where each wave is assigned the same label.

Let’s look at an example:

Wave 1: Project Teams and Miscellaneous

Space “Project Alpha” should be migrated to site “/sites/ProjectAlpha”
Space “Project Beta” should be migrated to site “/sites/ProjectBeta”
Space “Miscellaneous” should be migrated to site “/sites/Miscellaneous”

Wave 2: Client-Facing and Support Departments

Space “Marketing” should be migrated to site “/sites/Marketing”
Space “Sales” should be migrated to site “/sites/Sales”
Space “Customer Service” should be migrated to site “/sites/CustomerService”

Wave 3: Core Operational Departments

Space “HR” should be migrated to site “/sites/HR”
Space “Finance” should be migrated to site “/sites/Finance”
Space “IT” should be migrated to site “/sites/IT”

How to configure waves?

When configuring what to migrate in the Space Inventory, you use the WT_Setting_Waves column to assign a wave it belongs to.

Here’s what the Space Inventory list might look like:

WT_In_CfSpaceName	WT_In_CfSpaceKey	Wt_Setting_RequestTransformation	WT_Setting_Waves	WT_Setting_TargetSiteRootUrl
Project Alpha	PALPHA	x	1	https://contoso.sharepoint.com/sites/ProjectAlpha
Project Beta	PBETA	x	1	https://contoso.sharepoint.com/sites/ProjectBeta
Miscellaneous	MISC	x	1	https://contoso.sharepoint.com/sites/Miscellaneous
Marketing	MRKT	x	2	https://contoso.sharepoint.com/sites/Marketing
Sales	SALES	x	2	https://contoso.sharepoint.com/sites/Sales
Customer Service	SERVICE	x	2	https://contoso.sharepoint.com/sites/CustomerService
HR	HR	x	3	https://contoso.sharepoint.com/sites/HR
Finance	FIN	x	3	https://contoso.sharepoint.com/sites/Finance
IT	IT	x	3	https://contoso.sharepoint.com/sites/IT

Note: Other columns have been omitted for brevity.

With this configuration everything is prepared for a 3-wave migration.

What's a wave number?

Wave numbers are supposed to be:

whole numbers
equal to or larger than 1

Wave numbers don’t have to be consecutive. For example using 100, 200, and 300 (instead of 1, 2, and 3) is fine.

What's a wave name?

Wave names are also supported (note: starting with WikiTraccs v1.33.0).

Wave names are not case-sensitive. For example, pilot, Pilot, and PILOT all refer to the same wave.

Wave names:

must not contain spaces
must not contain commas
must not contain hyphens
must not contain *
must not contain :
must not contain ;
must not contain #
must not contain +

Examples: pilot, review, archive2026

How to choose waves to migrate?

In WikiTraccs.GUI you can enter wave clauses into the Waves & filters text box right above the Start transformation button:

Note

Selecting waves is optional. Leave the Waves & filters text box empty to migrate all selectors that have a check mark set in the Wt_Setting_RequestTransformation column of the Space Inventory.

Tip

The same input field also supports filter clauses (note: starting with WikiTraccs v1.33.0). Use those when you want to include or exclude specific spaces or content IDs in addition to the selected waves. For details and examples, see Include/Exclude Filters.

You can choose multiple waves to migrate.

Use commas, spaces, or a mix of both to separate wave clauses (note: only commas are supported prior to WikiTraccs v1.33.0).

Here are supported ways of selecting waves:

Wave selection example	Description
1	Migrate wave 1
1 2 3	Migrate waves 1, 2, and 3
1,2,3	Migrate waves 1, 2, and 3
1-3	Migrate waves 1, 2, and 3
1,4-6,8	Migrate waves 1, 4, 5, 6, and 8
pilot	Migrate the named wave `pilot`
pilot review	Migrate the named waves `pilot` and `review`
pilot, 2, review	Migrate the named waves `pilot` and `review` and wave 2
-4	Migrate all waves up to and including 4
4-	Migrate all waves equal to or greater than 4
1,4-	Migrate wave 1 and all waves equal to or greater than 4
*	Migrate all selectors with wave configuration, but skip selectors with empty WT_Setting_Waves column
	Migrate all selectors with checked Wt_Setting_RequestTransformation column

Tip

Above syntax is also valid in the WT_Setting_Waves column. This can be useful to include selectors in multiple migration waves.

Note

For a Space Inventory entry to be considered at all for migration, the Wt_Setting_RequestTransformation field has to be checked. This is a requirement independent of any wave configuration.

Use cases for waves

Waves are used to partition the migration into different chunks.

Those chunks can then be

migrated one after another
migrated in parallel by multiple WikiTraccs instances

Have a look at the How to run parallel WikiTraccs migrations blog post about the latter use case.

1 - Include/Exclude Filters

This article explains how ad-hoc include/exclude filters work and how to combine them with waves.

The Waves & filters field in WikiTraccs.GUI supports both wave clauses and filter clauses.

Use waves to mark selectors from the Space Inventory for the next migration run.

Use filters to include or exclude specific spaces or content items on-the-fly, without having to modify any selectors. This is great for testing and iterating quickly on specific pages.

Note

If you have not read about the general wave syntax yet, start with Migration Waves.

How filters work together with waves

Waves and filters are evaluated together, but they have different jobs:

Waves choose selectors from the Space Inventory you want to run.
Filters include or exclude specific spaces or content IDs, on-the-fly, withoug having to modify selectors in the Space Inventory.

The following example selects the pilot and review waves for migration, as well as the HR space, while excluding the page with ID 12345 from the migration run.

pilot review +space.key:HR -id:12345

Supported filter clauses

The following filter clauses are supported:

Clause	Meaning	Example
`+id:`	Include one content ID	`+id:12345`
`-id:`	Exclude one content ID	`-id:12345`
`+ids:`	Include multiple content IDs	`+ids:12345,67890`
`-ids:`	Exclude multiple content IDs	`-ids:12345,67890`
`+id!:`	Force one content ID to be enqueued; this will force-overwrite the SharePoint page	`+id!:12345`
`+ids!:`	Force multiple content IDs to be enqueued; this will force-overwrite the SharePoint pages	`+ids!:12345,67890`
`+space.key:`	Include one space by space key	`+space.key:HR`
`-space.key:`	Exclude one space by space key	`-space.key:ARCHIVE`
`+space.keys:`	Include multiple spaces by space key	`+space.keys:HR,FIN,IT`
`-space.keys:`	Exclude multiple spaces by space key	`-space.keys:ARCHIVE,LEGACY`
`+space.id:`	Include one space by space ID	`+space.id:123456`
`-space.id:`	Exclude one space by space ID	`-space.id:123456`
`+space.ids:`	Include multiple spaces by space ID	`+space.ids:123,456,789`
`-space.ids:`	Exclude multiple spaces by space ID	`-space.ids:123,456,789`

The +id! and +ids! filter variants force existing (previously migrated) SharePoint pages to be overwritten.

The +id and +ids filter variants (without !) behave “normally”:

if the page already exists in SharePoint and did not change in Confluence, the page is skipped in the migration run
if the page already exists in SharePoint and did change in Confluence, the page is either skipped, or overwritten, depending on the Update outdated SharePoint pages setting

Content IDs and content types

Content ID filters can optionally include a content type.

Example:

+id:12345;#blogpost

Use this in Confluence Cloud to explicitly address non-page content types like blog posts.

Examples

Migrate one named wave, but exclude one space:

pilot -space.key:ARCHIVE

Migrate two waves and include one specific content item:

1 2 +id:12345

Migrate one wave and include several specific pages:

pilot +ids:12345,67890,77777

Migrate one wave and force one specific page to be overwritten in SharePoint:

pilot +id!:12345

Migrate one wave and explicitly include several spaces:

pilot +space.keys:HR,FIN,IT

Order matters

When multiple filter clauses could match the same item, the first matching filter clause wins.

Because of that, put the more specific filter first.

Example:

pilot +id:12345 -space.key:ARCHIVE

In this example, content ID 12345 stays included even if it belongs to space ARCHIVE, because the specific include clause comes before the broader exclude clause.

If you reverse the order, the exclude clause wins:

pilot -space.key:ARCHIVE +id:12345

Separators

You can separate clauses with spaces, commas, or a mix of both.

Examples:

pilot review +space.key:HR
pilot,review,+space.key:HR
pilot, review +space.key:HR

Inside grouped filter clauses such as +ids: or +space.keys:, the individual values are separated with commas.

Typical usage patterns

run a wave and add a few specific pages: pilot +ids:12345,67890
run a wave and force specific pages to be overwritten: pilot +id!:12345
re-migrate a single page: dummywave +id!:12345 (dummywave doesn’t exist)

For the general wave syntax and examples like wave ranges or wildcards, see Migration Waves.