Filter Cascading

When applying filters, not migrating a content item can potentially effect other items that reference it. For example, if a user is not migrated, a workbook owned by that user would normally not be able to migrate without changing the owner or taking other steps to handle the reference. In many cases when a content item is skipped, the intention is to also skip migrating the content items that reference it. For example, if a project is not migrated, you might want to also skip the workbooks and data sources in that project. Cascading a filter allows it to apply to all content items that reference the item being filtered.

Cascading Filters

To have a filter cascade to content items that reference the current item, assign a cascade skip status in a filter. Content items that reference this item will then have the same cascade skip status applied by a default filter when those content types are migrated.

item.status = FilterStatus.CASCADE_SKIP

See Sample: Filter projects by name for a full example of a cascading filter.

Non-Cascading Filters

To have a filter only apply to the current item, assign a non-cascade skip status in a filter. Content items that reference this item will need to be handled manually through additional filters, mappings, or transformers.

item.status = FilterStatus.SKIP

See Sample: Filter users by site role for a full example of a non-cascading filter.

Filter Ordering and Overriding

Filters run in the order they are registered. Each filter is run on all items of the content type available to filter, including those marked for exclusion by previous filters. This means that setting the filter status of an item overrides any decisions made by previous filters, including cascading filters from previous content types.

Updating Boolean Filters

In previous versions of Migration SDK filters never cascaded, and used a simple boolean return value to determine whether the filtering content item was migrated or skipped. Filters using these boolean return values continue to function as before. To update these filters to allow them to cascade:

  • Override the filter method instead of the should_migrate method.
  • Convert the logic of the filter that returns true to either return without modifying the input context, or set the context's status property to FilterStatus.MIGRATE to overwrite previous filters.
  • Convert the logic of the filter that returns false to set the context's status property either to FilterStatus.SKIP or FilterStatus.CASCADE_SKIP.