Part 1 - The BasicsPart 2 - User InterfacePart 3 - TriggersPart 4 - Timer JobsPart 5 - Configuration OverviewPart 6 - Configuration InternalsPart 7 - Variation Hierarchy CreationPart 8 - Creating Page VariantsPart 9 - Creating Site VariantsPart 10 - Restructuring the HierarchyPart 11 - Variations Fixup ToolPart 12 - CustomizationPart 13 - LoggingPart 14 - TroubleshootingPart 15 - "View Changes" ButtonPart 16 - Translation SupportPart 17 - MOSS 2007 vs. SP 2010Part 18 - FAQ
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:
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:
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.
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.
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.
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:
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.
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.
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.
The move is divided into three steps:
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:
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.
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.
Note: In case that the Variation Root site is not identical with the root site of the site collection it is possible to move the Variation Root site to a new location as well. The configuration setting for the variation root site will automatically be updates as it is stored as hyperlink in a list item in the Relationships List and will be adjusted through the same mechanism as other hyperlinks pointing to the site.
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 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.
Important: Moving a site out of the variation hierarchy - especially moving it out of the source label is a not reversible operation! As the Variation Group Id is removed from the site and all included sub sites and pages and as the relationships list entries are removed you cannot just move the site back to it's original location and assume that everything is back to normal.
If such a move is performed by accident it usually requires to restore a backup taken before the move operation to roll back the changes.
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:
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.
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.
Important: Take special care when restoring a page in a target label. If the page has been moved to a different location before it got deleted and a new item has been recreated in the target label, you will end up with two pages in the same label for the same variation group.
This is not supported and can lead to exceptions.
The restore operation fires the ItemAdded event in the list where the restored item gets restored into.
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.
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:
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
Important: As mentioned above the delete will start at the leaves when deleting the site in Site Manager. That means that all the child sites will already be gone when the event handler cancels the delete operation because it identifies that the site to be deleted is the top site of a label or the root site of the variation hierarchy.
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.
Note: Unlike the delete operation for sites the cleanup of relationships list entries does not happen in the "after" event of the delete (WebDeleted) but in the "before" event. That means if the delete is not performed for whatever reason (e.g. because another event handler cancels the delete) you will end up with an inconsistent relationships list as the relationships list entries for the site and all it's pages is already gone.
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.
Important: Similar to move operations which went beyond outside of a variation label it usually requires to restore a backup from before the site delete operation to roll back the changes.
You cannot just restore the site from the recycle bin as the relationships list entries will not be recreated.
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.
Deletion of a variation label is a synchronous operation, which is handled within the http request that initiated it.
The operation is not performed in a timer job and is not implemented as a long running operation, which would be executed on a separate thread.
The side effect of this limitation is that with large hierarchies it can happen that the operation takes more time than the standard request execution timeout (110 seconds).
In such a situation, the variation cleanup operation will not be completed successfully before ASP.NET terminates the http request.
Workaround: You can increase the execution timeout value by modifying the web.config file in the _layouts directory by adding the following details (36000 = 10 hours):
<configuration>… <location path="VariationLabels.aspx"> <system.web> <httpRuntime executionTimeout="36000" /> </system.web> </location> … <configuration>
You also should disable application pool recycling option while the label delete operation is executed.
What web.config contains "Variation Labels.aspx" ?
as outlined in the article the web.config in the _layouts virtual directory.