SharePoint Variations – The complete Guide – Part 10 – Restructuring the Hierarchy

This module explains the actions performed when applying structural changes to the content in the variation hierarchy. This includes moving and deleting of sites and pages as well as recoveries from recycle bin.

I will explain the actions performed when restructuring the source hierarchy, discuss how the variation consistency is preserved when the structural changes are applied and explain which actions can break the consistency between source and target labels

The following actions are covered in this article:

Moving a Publishing Page

The actions performed when moving a publishing page are different based on whether the move operation is within the same label or goes beyond the boundaries of a variation label.

It is important to understand that WSS does not support moving items outside of the current site. Due to this limitation the move operations for publishing pages has been implemented as a copy&delete operation. When a page is “moved” around in a site collection using Site Manager the Move action in Site Manager updates all links pointing to the page to reflect the new location. That also includes the links in ObjectID column of the Relationships List.

In addition, the move action is variation aware – means it updates the variation specific columns in case that a move operation ends in a different variation label or outside the variation hierarchy.

The move is divided into four steps:

1. Copy to the new location using content deployment and migration API
2. Update Links pointing to the item to point to the new location
3. Delete of the old item
4. Maintain the relationships list items for the variation group of the moved item

Copy to the new location

This step is performed using an export/import operation using the content deployment and migration API. Between export and import, the manifest files are modified to update variation specific fields in case that the move operation goes outside the original variation label.

That demonstrates the tight integration of the variation system into other operations in Site Manager.

Updating Links to the moved item

I will not go into the details of the link management as I have explained these details in the following blog already: Deep Dive into the SharePoint Content Deployment and Migration API – Part 4

One specialty in this operation is that the link management checks if the link to the item comes from an item in the relationships list. If the link comes from the relationships list, the link management verifies if the move operations went beyond the boundary of a variation label and only updates the link if source and target of the move operation is in the same variation label.

This is necessary to support the maintenance of relationships list items in the final step of the move operation, which is discussed below.

Deleting the old item

The delete operation itself is a trivial task. However, the delete operation triggers two events, which are responsible to perform the next step: ItemDeleting and ItemDeleted.

Maintenance of Relationships List items

In case that a move operation went beyond the boundary of a variation label additional operations are required as the moved item is no longer part of the previous variation group. To detect whether a move operation went beyond the boundary of a variation label we check whether the relationships list reference points to the deleted item or to the new created item (see “Updating Links to the moved item” above).

The variation system hooks up to the following events to handle this:

• ItemDeleting – This event fires after Site Manager has copied the item to the new location, fixed the links pointing to the item and is about to delete the original item to complete the move operation.

  The publishing feature has bound the Microsoft.SharePoint.Publishing.PagesListCPVEventReceiver.ItemDeleting event receiver to this event to gather the Variation Group Id from the page that is going to be deleted and make it available to the ItemDeleted event handler, which fires after the delete operation has been completed.

• ItemDeleted – This event is fired after the original page has been deleted.

  The publishing feature has bound the Microsoft.SharePoint.Publishing.PagesListCPVEventReceiver.ItemDeleted event receiver to this event, which is responsible to maintain the relationships list references in case that the move operation moved an item out of a variation label. In this situation, the item is no longer a member of the previous variation group and the relationships list entry has to be updated accordingly.

  In case that an item that resided in the source variation label was moved out of the source label all relationships list entries for the variation group of the moved items will be recycled – means neither the item in the source label nor the items in the target labels are variation hierarchy items after the move.

  In case that the move operation for an item in the target variation label went beyond the boundaries of its label the list item in the Relationships List is marked as deleted (Deleted column gets value Yes). This flag is used in combination of the setting, which controls whether to recreate deleted target items, or not.

Moving a Publishing Site

Unlike moving pages, WSS support move operations for sites natively. No export/import is required.

Important to understand is that when a site is moved around in a site collection, WSS updates all links pointing to the site to reflect the new location. That also includes the links in ObjectID column of the Relationships List.

In addition, the move action is variation aware – means it updates the variation specific columns in case that a move operation ends in a different variation label or outside the variation hierarchy.

The move is divided into three steps:

• Move the site
• Update Links pointing to the site
• Maintain the relationships list items for the variation group of the moved site

Moving the site

That step is done by simply assigning a new Url to the ServerRelativeUrl property of the managed SPWeb object. The real move operation is performed as soon as the property change is committed using SPWeb.Update.

There is one special situation, which needs to be taken care of: that is the scenario where the site being moved is the top site of a variation label. As moving this site would invalidate the variation label such a move is not allowed.

The variation system hooks up to the following event to handle this:

• WebMoving – This event fires before the actual move operation is performed within the COM layer.

  The publishing feature has bound the Microsoft.SharePoint.Publishing.CPVAreaEventReceiver.WebMoving event receiver to this event, which checks if the site being moved is a variation top site and cancels the move operation in this case.

Updating links pointing to the site

This operation is performed automatically in when changing the ServerRelativeUrl property of a site. That means that no special action has to be done to perform this link fixup.

Maintenance of Relationships List items

In case that a move operation went beyond the boundary of a variation label, additional operations are required as the moved site is no longer part of the previous variation group. To detect whether a move operation went beyond the boundary of a variation label we check the label the item is in before and after the move.

The variation system hooks up to the following event to handle this:

• WebMoved – This event handler fires after the move operation has been completed.

  The publishing feature has bound the Microsoft.SharePoint.Publishing.CPVAreaEventReceiver.WebMoved event receiver to this event which is responsible to maintain the relationships list references in case that the move operation moved a site out of a variation label. In this situation, the site is no longer a member of the previous variation group and the relationships list entries of the site and all child sites and child pages have to be deleted.

  In case that a move operation moved a site, from outside the source label into the source label (as well from a target label and from a location outside the variation hierarchy), this event handler is responsible to mark the site as being a part of the source label and will also initiate the spawn of the moved site to the target labels.

Deleting/Restoring a Publishing Page

Delete Operation

When a publishing page which resides in a target variation label is deleted it is important to mark its relationships list item as deleted to ensure that future update operations work correct and can either recreate the deleted item (if configured) or to allow a user to manually create a page variant in the label the deleted item resided in.

In case that a publishing page in the source variation label has been deleted it is necessary to recycle all relationships list entries for the variation group of the deleted page as these pages can no longer be updated after their source page has been deleted.

Delete operations for Publishing pages through the UI or through object model can either use the recycle bin (SPFile.Recycle method) or can be a final delete without a chance to recover the item (SPFile.Delete method). Both methods will raise the ItemDeleting and ItemDeleted events.

The variation system hooks up to the following events to maintain the relationships list items during a delete operation:

• ItemDeleting – This event fires when the WSS object model is about to delete or recycles the page

  The publishing feature has bound the Microsoft.SharePoint.Publishing.PagesListCPVEventReceiver.ItemDeleting event receiver to this event to gather the Variation Group Id from the page that is going to be deleted and make it available to the ItemDeleted event handler, which fires after the delete operation has been completed.

• ItemDeleted – This event fires after the WSS object model has deleted the page

  The publishing feature has bound the Microsoft.SharePoint.Publishing.PagesListCPVEventReceiver.ItemDeleted event receiver to this event, which is responsible to maintain the relationships list references for the deleted items.

  In case that a page in the source variation label has been deleted, all relationships list entries for the variation group of the deleted item are recycled – means neither the item which was deleted in the source label nor the items in the target labels are variation hierarchy items after the delete.

  In case that a page in a target label has been deleted, the list item in the Relationships List is marked as deleted (Deleted column set to Yes). This flag is used in combination of the setting, which controls whether to recreate deleted target items, or not.

Restore Operation

In case of a restore operation it is necessary to ensure that the deleted status in its relationships list item is removed to ensure that future updates work correct and that a user cannot create a new page variant in the same label.

The restore operation fires the ItemAdded event in the list where the restored item gets restored into.

The variation system hooks up to the following events to maintain the relationships list items during a delete operation:

• ItemAdded – This event fires after the item has been successfully restored in the pages library

  The publishing feature has bound the Microsoft.SharePoint.Publishing.PagesListCPVEventReceiver.ItemAdded event receiver to this event change the deleted status on the relationships list entries associated with the restored page, and also uses this event to restore the recycled relationships list entries of the variation group of the restored page, in case that the restored page resides in the source label.

Deleting/Restoring a Publishing Site

Delete Operation

When deleting a publishing site, which is part of the variation hierarchy, a couple of important checks and clean-up steps are required. For example, it is important to verify if the site is a mandatory site for the variations system and prevent the deletion in such situation.

In addition, the relationships list items referencing the deleted sites and the pages in these sites have to be deleted as well.

The variation system hooks up to the following event to fulfill this duty:

• WebDeleting – This event fires for each site that is going to be deleted. In case that a site is deleted, which contains subsites, and then this event fires for each subsite as well. When performing the delete from within Site Manager the delete starts at the leaves – meaning, the deepest sites in the hierarchy are deleted first and the WebDeleting event for these leave sites fires first as well.

  The publishing feature has bound the Microsoft.SharePoint.Publishing.CPVAreaEventReceiver.WebDeleting event receiver to this event which first checks if the site being deleted is the variation root site and cancels the delete in case that there are any spawned variation labels. If there are no spawned variation labels, the event handler removes the variation root site URL from the variation settings and allows the delete operation to continue.

  The next thing checked is if the site being deleted is a variation top site of a variation label and cancels the delete in this case as the delete of the top site would invalidate the variation label

In case, that the delete operation is valid the WebDeleting event handler cleans up the relationships list items for the site and all included pages.

Restore Operation

The option to restore sites and site collections has been added with SharePoint 2010 Service Pack 1. Unfortunately the Variation Feature currently does not support this functionality which means that a site restore from the recycle bin will not be part of the variation hierarchy as the relationships list entries for the site and included pages will not be recreated.

Deleting a Variation Label

From a variation perspective, the actions required when deleting a variation label are nearly identical to the actions performed when deleting a site: the variation top site and all its child sites and pages have to be removed from the relationships list recursively.

In addition to this step, the variation label itself has to be removed by deleting the list item representing the variation label in the variation labels list.