SharePoint Variations

(1)

SharePoint Variations – The complete

Guide – Part 1 – The Basics

★★★★★

★★★★

★★★

★★

★

November 14, 2011 by Stefan Goßner//12 Comments

• 0

Part 1 – The Basics

Part 2 – User Interface Part 3 – Triggers Part 4 – Timer Jobs

Part 5 – Configuration Overview Part 6 – Configuration Internals Part 7 – Variation Hierarchy Creation Part 8 – Creating Page Variants Part 9 – Creating Site Variants Part 10 – Restructuring the Hierarchy Part 11 – Variations Fixup Tool Part 12 – Customization Part 13 – Logging

Part 14 – Troubleshooting Part 15 – “View Changes” Button Part 16 – Translation Support Part 17 – MOSS 2007 vs. SP 2010 Part 18 – FAQ

Today I will start a new article series, which will discuss all aspects of the SharePoint Variations feature. The article series will provide insights into the underlying architecture and will also provide details about customization.

But before we can start with the internals we first have to start with the basics.

The idea behind

SharePoint Variations has been implemented to address the following common scenarios:

(2)

Many companies operate globally, and even in their home market, companies often must appeal to customers who speak different languages. This diversity often requires that publishing sites be tailored for different cultures, markets, and geographic regions.

Multiple Devices

In addition, the importance of new internet connected devices like mobile phones, PDAs and internet enabled media players becomes more and more important – so presenting the same information in a different layout on different target devices is mandatory for many customers.

Coordinating Content Creation and Update

Maintaining a number of different versions, or “variations,” of publishing sites or pages is difficult and time consuming because it can be difficult to coordinate the creation and updating of content between the variations.

Accuracy of Content

Another important factor is the accuracy of the content in the different languages, which requires the integration with individual workflows, and an export and import functionality of the content for the purpose of translation through external companies.

Understanding Variations

[The terms used in this paragraph are explained in the Terminology section below]

SharePoint Variations allows copying sites and content from the source variation label to one or more target variation labels. By default, the variations feature copies only the site structure and publishing pages from the Pages library of the source variation label.

The variations feature does not copy other site content, such as lists or other document libraries, unlike the content deployment feature, which copies all content, including lists and other document libraries, from one site to another.

It is possible to configure the variation feature to copy resources like images and documents bound to publishing pages also to target variation sites – but this will only work for documents and images which reside in libraries and folders which also exist in the target site with the same site relative Url.

Another important difference between the variation feature and content deployment is that the copied content in the target variation labels can be changed, unlike the content deployment feature, for which changing copied content on the target is discouraged.

By default, when users navigate to the Variation Root Site, they are redirected to the appropriate top site of a variation label, based on the language setting of their Web browser. For example, if a user’s default browser language is French, SharePoint Server 2010 redirects that user to the top site of the French variation label.

It is possible to customize this behavior by replacing or updating the redirection page responsible for the routing with a different page. This new page can implement custom logic to redirect the user based on other criteria (e.g. information from the User-Agent string).

(3)

Terminology

The Variation Feature allows tailoring publishing sites for different cultures, markets, languages, devices or any other criteria defined by a customer.

Variation settings enable site owners to create and maintain a number of different “variations,” of the same publishing sites or pages.

Variation Hierarchy

Exactly one variation hierarchy can be defined per site collection. It consists of a Variation Root – and sub trees for each of the “variations” which we refer to as variation labels.

Variation Root Site

Each site collection can have a maximum of one hierarchical structure, which supports variations. Each variation label defines the top site of a sub-tree of this hierarchy. The site, which contains the different site structures (e.g. one structure for English and one for German) of the different variation labels, is the variation root site.

As only one hierarchical structure supporting variations can exist in a site collection it also means that there can only be one variation root per site collection.

The variation root site contains the landing page that contains the logic, which redirects users to the correct label (more details in a later chapter).

The variation root site can be a site at any level in a site collection, including the top-level site. It is not possible to change the variation root site after the variation hierarchy has been created.

Variation Labels

Variation labels are the names given to each of the variants. For example, variant labels could be language names – such as English, French, or German – or devices – such as PDA, mobile phone, Internet Explorer – or a combination of both like Spanish mobile phone, English Internet Explorer etc. The flexibility is endless as the Variation system allows customers to define a custom routing logic to decide to which label to redirect a user who browses the site (more details in a later chapter).

Up to 50 variation labels are supported in a site collection. There are two different types of variation labels:

• Source Variation Label

The source variation label holds the sites where content is authored, published, and later pushed to the target labels. There can be only one source variation label per variation hierarchy. After a source variation label has been defined and its hierarchy has been created, it cannot be changed.

• Target Variation Label

The target variation labels receive most or all of their content from the source variation label. Although new content can be created on a target label, that content is not shared with other labels and is unique to the label in which it was created.

(4)

The Variation Top site is the root or upper most site in a variation label. All Variation Top sites in a hierarchy are direct children of the Variation Root site and define the root of the hierarchy within a variation label.

Variation Pages

Variation pages are the publishing pages that are stored in the Pages library of the source variation sites and the target variation sites. These pages and any dependent resources such as images and documents are the only content that is copied from the source label to the target labels.

Important: Storing non-publishing pages inside the Pages library of a site is unsupported! Non-publishing pages inside the Pages label can cause the Variations Create Hierarchies Job Definition timer job to fail.

Page Variants

These are the peer pages bound together by the variation feature. Each variation label can contain one variant of a page in the source label. If the item in the source label is updated the content of the source page is automatically populated to the page variants in the target labels.

Variation Group

Each source site or page defines a separate variation group. All variants of the site or page in the different labels belong to the same Variation Group.

Relationships List

The variation system needs to keep track about peer sites and pages to ensure that updates performed in the source label are correctly transferred to the target label.

This tracking information is stored in the Relationships List. Each page or site in the variation hierarchy is represented in the relationships list as a separate list item: the Relationships List Entry.

(5)

Figure 1: Variation Hierarchy

SharePoint Variations – The complete

Guide – Part 2 – User Interface

★★★★★

★★★★

★★★

★★

(6)

★

• 0

Part 1 – The Basics

Part 2 – User Interface

Part 3 – Triggers Part 4 – Timer Jobs

The variation system is integrated in the user interface of a site collection in five different locations: • Site Settings page

• Master Pages • Page Layouts

• Site Manager (Manage Content and Structure) • Ribbon

Site Settings

The variation system adds three links to the site collection administration section of the site settings page which will be discussed in further chapters:

(7)

Master pages

The variation system registers a delegate control in each of the default master pages to allow easy integration of a variation label menu on publishing pages in the variation hierarchy:

(8)

Page Layouts

The variation system allows to associate page layouts with specific variation labels to allow the

implementation of different designs in different labels, to support different layouts for different devices, languages (e.g. LTR vs. RTL support) and cultures:

(9)

Manage content and structure

The variation system integrates into the context menu of sites and pages in the variation system to support spawning new sites and pages from this dialog. In addition, manage content and structure shows variation sites with a different icon than other sites:

(10)

(11)

Ribbon

The variation system extends the ribbon with additional operations related to the current publishing page:

SharePoint Variations – The complete

Guide – Part 3 – Triggers

★★★★★

★★★★

★★★

★★

★

• 0

Part 1 – The Basics Part 2 – User Interface

Part 3 – Triggers

Part 4 – Timer Jobs

Part 5 – Configuration Overview Part 6 – Configuration Internals

(12)

Part 7 – Variation Hierarchy Creation Part 8 – Creating Page Variants Part 9 – Creating Site Variants Part 10 – Restructuring the Hierarchy Part 11 – Variations Fixup Tool Part 12 – Customization Part 13 – Logging

The variation system in SharePoint allows automatically creating and updating content in target variation labels.

Some of these actions are performed silently without a user requesting variation updates explicitly through UI interaction.

In order to perform these updates it is necessary for the variation system to be informed about content changes and changes in the variation hierarchy to keep the links between the variation peers intact. To achieve this, the variation system registers different event handlers, which trigger content updates and the maintenance of the underlying data structures:

ItemAdded event on Pages Library

This event is used to restore and update relationships list entries in case that a publishing page was restored from the recycle bin.

ItemUpdated event on Pages Library

This event is used to trigger the peer page creation and peer page update if automatic content creation and propagation is enabled for Pages libraries which have minor versions and/or content moderation enabled.

ItemCheckedIn event on Pages Library

This event is used to trigger the peer page creation and peer page update if automatic content creation and propagation is enabled for Pages libraries which have minor versions and content moderation disabled.

(13)

ItemDeleting event on Pages Library

This event is used to collect the information about the variation group the publishing page which is about to be deleted belongs to – to make it available in the ItemDeleted event firing after the delete operation. Inside the ItemDeleted event it is not possible to get this information directly from the publishing page as this page has already been deleted at this time.

ItemDeleted event on Pages Library

This event is used to update the relationships list entries for deleted and recycled publishing pages. • If a publishing page which resided in the source variation label is deleted or recycled then all

relationships list entries referencing the variation group of the deleted/recycled page are recycled as well.

• If a publishing page which resided in a target variation label was deleted or recycled then its relationships list entry is marked as deleted by setting the value of the “Deleted” column of the relationships list entry to “Yes”.

In case of a restore of a deleted page from the recycle bin, these actions have to be reverted. See the ItemAdded event for details.

FeatureActivated event on PublishingWeb

This event is used to trigger source site variation to target labels when the Publishing feature is activated on a site. This happens as well when a new Publishing site is provisioned inside the source label or if the feature is manually activated on a site that resides in the source label.

FeatureDeactivating event on PublishingWeb

This event is used to delete the relationship list entries and the variation specific properties when deactivating the publishing feature on a site.

WebDeleting event on PublishingWeb

This event is used to cancel a delete operation in case that the site being deleted is the Root Site of the Variation Hierarchy (if spawned labels exist) or a Top site of a Variation Label. In all other cases, the variation system uses this event to clean up the relationship list items for the deleted site and its pages.

(14)

WebMoving event on PublishingWeb

This event is used to cancel the move operation in case that the site being moved is the Top site of a Variation Label, as moving a Variation Top site would destroy the variation label it belongs to.

WebMoved event on PublishingWeb

This event is used to trigger source site variation to target labels if a site is moved from outside the source label into the source label. In addition, it will cleanup the information in the relationship list in case that a site is moved out of a variation label.

SharePoint Variations – The complete

Guide – Part 4 – Timer Jobs

★★★★★

★★★★

★★★

★★

★

• 0

Part 1 – The Basics Part 2 – User Interface Part 3 – Triggers

Part 4 – Timer Jobs

Part 14 – Troubleshooting Part 15 – “View Changes” Button

(15)

Part 16 – Translation Support Part 17 – MOSS 2007 vs. SP 2010 Part 18 – FAQ

Timer jobs are a great feature of SharePoint to use when you need to perform background execution at regular or specific times or when you need to execute code on all or selected servers in the farm. The Variations feature uses specific SharePoint timer jobs to perform tasks such as creating and

propagating sites and pages. The Variation Timer jobs are bound to each web application which contain (or contained in the past) a site collection which has the publishing feature enabled.

You can change the Schedule for each job on the Job Definitions page on the Central Administration Web site. The following timer jobs are used to with Variations:

The different Variation Timer Jobs

Variations Create Hierarchies Job Definition

This timer job is responsible to create the variation hierarchy of unspawned labels by creating peers in the new label of sites and pages in the source variation label. By default, this timer job runs once a day.

Class: Microsoft.SharePoint.Publishing.Internal.CreateVariationHierarchiesJobDefinition

Variations Create Page Job Definition

This timer job creates peer pages on the target variation sites whenever a user explicitly requests the creation of a variant of a page using the UI (Ribbon or Site Manager) – e.g. if the Automatic Creation option has been disabled and a user decides that a page needs to have a page variant in a different label. By default, this timer job runs hourly.

Class: Microsoft.SharePoint.Publishing.Internal.CreateVariationPageJobDefinition

Variations Create Site Job Definition

This timer job creates peer sites when the Automatic Creation option has been disabled and a user manually creates a new variation site using Site Manager. By default, this timer job runs every 5 minutes.

Class: Microsoft.SharePoint.Publishing.Internal.CreateVariationSiteJobDefinition

Variations Propagate Page Job Definition

Creates and updates peer pages in target variation label after a page in the source variation label has been approved or after the update has been manually requested by a user through the Ribbon. By default, this timer job runs hourly.

Class: Microsoft.SharePoint.Publishing.Internal.PropogateVariationPageJobDefinition

Variations Propagate Site Job Definition

Creates peer sites when the Automatic Creation option is enabled. By default, this timer job runs every 5 minutes.

(16)

Class: Microsoft.SharePoint.Publishing.Internal.SpawnSitesJobDefinition

Communication between worker process and Timer Jobs

Creating variation hierarchies, spawning sites and pages manually or automatically – all these operations are usually triggered from within the worker process. As the worker process account is often not allowed to write into the configuration database where SharePoint timer jobs live, it is not possible to configure the timer jobs directly.

To overcome this limitation, the configuration data for the timer jobs has to be stored within the current content database and the timer job will pick up the data from there.

WSS provides a built in mechanism for this by providing the SPWorkItemJobDefinition class. Timer job definitions derived from this class are able to read configuration data from work items, which are stored in the ScheduledWorkItems table in the content database. The Sharepoint object model allows adding, reading and removing work items to/from this table.

As many different timer jobs can work on the same ScheduledWorkItems table it is necessary to ensure that each ScheduledWorkItemscarries a type information (a unique id) to ensure that the timer job picks up the correct work items.

Related to variations this means that each site or page spawn request and each variation hierarchy creation request is represented by a specific work item in the scheduled work item table. When the appropriate timer job runs the next time, it reads all work items related to this timer job from

the ScheduledWorkItems table and processes them one by one. After the timer job has completed the processing of a work item, it removes the work item from the ScheduledWorkItems table.

Underlying WSS Timer Job framework

SPJobDefinition

All timer job are persistable objects derived from the SPJobDefinition class.

SPPausableJobDefinition

In SharePoint 2010, a new abstract class derived from SPJobDefinition has been included, which supports pausing and restart of timer jobs:SPPausableJobDefinition.

This class declares a second Execute method, which allows to hand-in a job state to the timer job. Timer jobs derived from SPPausableJobDefinition can use this job state (SPJobState) to store values when the job is paused, which can be retrieved later when the job is resumed.

SPWorkItemJobDefinition

SharePoint 2007 introduced a SPWorkItemJobDefinition Timer job class derived

from SPJobDefinition which provided a framework which allowed the implementation of Timer jobs which process a list of work items of a specific type.

With SharePoint 2010, SPWorkItemJobDefinition now also supports the pause and resume functionality and is now derived fromSPPausableJobDefinition.

(17)

For backward compatibility reasons the class still supports Timer job definitions developed without the pausing functionality in mind.

In SharePoint 2010 the actual Timer job derived from SPWorkItemJobDefinition only has to implement two methods: WorkItemType() which returns the unique ID of the work item type that should be processed in the timer job, and ProcessWorkItem() which processes one single work item of the defined type.

The framework provided in the SPWorkItemJobDefinition base class handles the rest of the processing like reading the work items from the database, updating the Timer job progress (visible as progress bar in the central admin), pausing and resume.

Variation Timer Jobs Framework

All variation timer jobs implement the SPWorkItemDefinition class. As many variation timer jobs perform very similar operations, an additional intermediate abstract

class VariationsSpawnJobDefinitionBase has been implemented which acts as base class to four of the five variation timer jobs:

(18)

Work Item type for Scheduled Variation Work Items

Timer Job Workitem Type

CreateVariationHierarchiesJobDefinition E7496BE8-22A8-45BF-843A-D1BD83ACEB25 CreateVariationSiteJobDefinition 943D4A28-4147-4A73-B4D1-4A9162D4ECE2 CreateVariationPageJobDefinition 726ddd8f-0e23-4c35-88b5-4fba39482515 PropogateVariationPageJobDefinition EA95AB64-3857-4403-96D0-3AEB3DBDB123

SpawnSitesJobDefinition 5A4B0E0E-0579-4a5d-B233-C2932F031912

SharePoint Variations – The complete

Guide – Part 5 – Configuration Overview

★★★★★

★★★★

★★★

★★

(19)

★

• 0

Part 1 – The Basics Part 2 – User Interface Part 3 – Triggers Part 4 – Timer Jobs

Part 5 – Configuration Overview

Part 6 – Configuration Internals Part 7 – Variation Hierarchy Creation Part 8 – Creating Page Variants Part 9 – Creating Site Variants Part 10 – Restructuring the Hierarchy Part 11 – Variations Fixup Tool Part 12 – Customization Part 13 – Logging

Variation Settings page

Most of the Variation settings can be configured in the Site Collection Administration section of the Site Settings page.

(20)

The Variations Settings page allows to configure the following options:

Variation Home

Here you can configure the Variation Root Site. After the variation root site has been selected and a variations hierarchy has been created, the root site cannot be changed.

Automatic Creation

Determines whether sites and pages on the source variation site are created automatically on the target variation sites. By default, this option is enabled.

(21)

If you disable this option, sites and pages that are created on the source variation site are not automatically variated to the target. You have to create the site and page variants manually using UI actions provided by the variation system.

Note: This option only controls the creation of peer pages – not the update. If a user decided to create a peer page in a target automatically), all updates to the source page will still automatically be propagated to the target label. This functionality was MOSS 2007 and led to different workarounds like disabling the page propagation timerjob (which is responsible to copy the labels) or creating a dummy source label to allow updates in all productive labels without affecting the content in the target In SP2010 the additional configuration the Disable Automatic Propagation option has been introduced to overcome this control whether content updates in the source label will be automatically propagated to the target label or not. If automatic disabled then the Automatic Creation option is ignored for pages (but it is still used for sites). Neither new nor updated pages target labels.

Unfortunately this option is not available in the UI – it has to be set using object model: Disable automatic propagation:

$rootWeb = Get-SPWeb http://url-to-sitecollection

$relationshipsList = $rootWeb.Lists[“Relationships List”] $propertyStore = $relationshipsList.RootFolder

$propertyStore.Properties.Add(“DisableAutomaticPropagation”, “True”) $propertyStore.Update();

Enable automatic propagation:

$propertyStore = $relationshipsList.RootFolder

$propertyStore.Properties.Remove(“DisableAutomaticPropagation”) $relationshipsList = $rootWeb.Lists[“Relationships List”] $rootWeb = Get-SPWeb http://url-to-sitecollection

$propertyStore.Update();

Recreate Deleted Target Page

Determines whether a page should be re-created on a target variation site if the page was deleted from the target variation site, and the page on the source variation site has been republished. By default, this option is enabled. If you disable this option, deleted pages are not recreated on target variation sites.

Update Target Page Web Parts

Determines whether changes made to Web Parts on pages on a source variation site are also made on pages on target variation sites. By default, this option is enabled.

Notification

Sends e-mail to the contact of the welcome page of a target variation site when a new page or site is created or to the contact person of the specified page when a page is updated. By default, this option is enabled.

(22)

Resources

Specifies whether to use the same resources on the source variation site when pages are copied to target label or to copy them to the target label as well. Only Resources in libraries, which are provisioned with the containing site, can be copied to the target, as the variation system does not have an option to vary libraries. For standard publishing sites, only images and documents in the Publishing Images and Documents library can be copied. By default, this option is set to reference existing resources.

Variation Labels page

Similar to the Variation Settings the configuration option for the Variation Labels is available in the Site Collection Administration section of the site settings page.

The Variation Labels page for a typical variation site looks as follows:

Using the variation labels page it is possible to create new variation labels, to edit or delete existing variation labels and to initiate the creation of the variation hierarchy for the defined variation labels.

Creating a new variation label

A new variation label can be created using the New Label option from the Variation Labels page, which will open the Create Variation Label dialog:

(23)

The Create Variation Label page allows to configure the following options:

Label Name

The label name will be used as URL name of the variation top site for the new variation label. Only characters which are allowed in a URL can be used for the Label name. A friendly name with other characters can be configured as the Display Name.

Display Name

The display name is the friendly name of the new variation label. Here you can use also characters, which are not allowed in an URL. The friendly name will be used as Title for the variation top site of the label.

(24)

Site Template Language

This setting allows to configure the language pack to be used when provisioning sites within the new variation label. This setting will only be available if more than one language pack is installed (base language + at least one language pack).

Locale

This setting allows to configure the locale settings for the sites provisioned in the new variation label.

Hierarchy Creation

This setting is not available in the UI if a source variation label has been defined but the hierarchy of the source variation hierarchy has not yet been created.

This setting influences the creation of the hierarchy of labels added after the initial hierarchy creation was done.

In such a situation, it is possible to define whether the new label:

• should get a copy of all sites and pages in the source hierarchy, or • if only the site structure should be replicated, or

• if only the top site should be created

Source Variation

The options in this section are disabled as soon as a source variation label has been defined as only one source variation label can exist per site collection.

Using the settings in this section, you can define whether the new label will be the source variation label or a target label.

If the new label is the source label, you can also select a publishing site template to be used when provisioning the variation top site of the different labels.

SharePoint Variations – The complete

Guide – Part 6 – Configuration Internals

(25)

★★★★★

★★★★

★★★

★★

★

• 0

Part 5 – Configuration Overview

Part 6 – Configuration Internals

Part 7 – Variation Hierarchy Creation Part 8 – Creating Page Variants Part 9 – Creating Site Variants Part 10 – Restructuring the Hierarchy Part 11 – Variations Fixup Tool Part 12 – Customization Part 13 – Logging

In the previous part I have provided an overview about the configuration settings available in SharePoint 2010 related to Variations.

Today I will provide you additional information about where these configuration settings are stored and in this context also about the famous Relationships List.

Configuration Storage

Important: Be aware that direct modification of the settings mentioned below without going through the SharePoint UI is not supported If you find an inconsistency in one of these settings and you cannot resolve it using the UI you should open a support case with Microsoft analyzed and fixed in a supported manner.

(26)

The variation system uses seven different places to store configuration information 1. Property bag of root site of site collection

2. Property bag of root folder of root site of site collection 3. Property bag of root folder of Relationships List 4. List Items in Relationships List

5. List Items in Variation Labels List

6. Property bag of sites in the Variation Hierarchy 7. Fields of pages in the Variation Hierarchy

Here are the details about the information stored in these locations: Property bag of root site of site collection

This location is used to describe the location of the Relationships List and the Variation Labels list. The following properties are used by the variation system:

_VarRelationshipsListId

This property contains the unique ID of the Relationships List. Most code parts in the Variation System use the value in this property to access the Relationships List rather than the Url name.

_VarLabelsListId

This property contains the unique ID of the Variation Labels List. The Variation System always uses the value in this property to access the Variation Labels list.

Property bag of root folder of root site of site collection

This location is used to synchronize the interactions of content deployment import operations and the variation system. The following property is used by the variation system:

DeploymentInProgress_

SiteId

This property exists while a content deployment job performs an import operation into the current site collection is active. After the import is completed the property will be removed. The variation system checks this property in context of autospawning of created pages and sites. Authoring actions during import operations are discouraged as sites and pages created by authors while an import operation is running will not be automatically spawned to the target sites.

Note: Parallel execution of content deployment imports can cause a problem, as the first finishing job will

(27)

Property bag of root folder of Relationships List

This is the place where most of the configuration settings configured in the Variation Settings page are stored.

UpdateWebPartsPropertyName

This property stores the configuration setting for the “Update Target Page Web Parts” option on the variation settings page.

Default Value: True AutoSpawnStopAfterDeletePropertyName

This property stores the configuration setting for the “Recreate Deleted Target Page” option on the variation settings page.Default: False SourceVarRootWebTemplatePropertyName

This property stores the configuration setting site template to be used for the top sites of each label. This setting is configured when defining the source label rather than in the variation settings page.

Default Value: CMSPUBLISHING#0 CopyResourcesPropertyName

This property stores the configuration setting for the “Resources” option on the variation settings page.

Default: False EnableAutoSpawnPropertyName

This property stores the configuration setting for the “Automatic Creation” option on the variation settings page.

Default: True SendNotificationEmailPropertyName

This property stores the configuration setting for the “Notification” option on the variation settings page.

Default: True DisableAutomaticPropagation

This property can be used to disable automatic variation of content changes and new pages to the target labels. If this property is set to True then the only way to vary content changes to the target pages is through a manual update in the UI. This setting can only be configured using object model.

Default: False TranslateFields

This property is used when leveraging external translation services to flag specific columns to be translatable. The information about the translatable fields are stored in this property in Xml format. Translatable columns are covered in Module 10.

(28)

List Items in Relationships List Variation Root Site URL

This URL is stored as a hyperlink in the ObjectId link field in a list item in the relationships list. The item is identified by a well-known Guid (F68A02C8-2DCC-4894-B67D-BBAED5A066F9) in the GroupId column.

Note: Storing the variation root in a link field has the benefit that it is possible to move around the variation feature of site manager will automatically adjust all links to the moved item – including the link in the Relationships The same benefit applies to all peered sites and pages. Moving them around using site manager will not break pages will be propagated to the moved target pages automatically.

List Items in Variation Labels List

Each list item in the Variation Labels list represents a label configured for variations.

Property bag of sites in the Variation Hierarchy

To efficiently link sites to their peers, it is necessary to store some information within the property bag of the Publishing sites:

Variation Group Id

The Id of the Variation Group assigned to the site and its peers.

Fields of Pages in the Variation Hierarchy

To efficiently link pages to their peers, it is necessary to store some information within special fields of the Publishing Pages:

Variation Relationship Link

The variation system stores the URL to the associated list item in the Relationships List the “Variation Relationship Link” field of the publishing page. More details about the Relationships List in the next section.

Variation Group ID

The Id of the Variation Group assigned to the page and its peers.

Relationships List

SharePoint needs to keep track of the associations between sites and pages in the different variation labels to ensure that changes done to the source variation are automatically propagated to the target labels.

(29)

This association data is kept in a hidden list in the root of the site collection named Relationships List. You can view the content of this list by navigating to the following URL:

http://url-to-site-collection/Relationships%20List

The “All Items” view only contains the Title column of the list elements – which is always empty. To view the content in this list more effectively you should create a new view (you should not change the “All Items” view) where all the columns are enabled.

To identify which of the entries are variation peers have a look at the GroupGuid column. All peers have the same Id in the GroupGuid column.

Note: The variation root site is also represented in the Relationships List. The GroupGuid column for the variation root site always 2DCC-4894-B67D-BBAED5A066F9}”.

The Variation retrieves the list item with this well-known Guid above to locate the variation root site

Important Fields GroupGuid

This field allows to find peers for a given page. All peers have the same GroupGuid value.

In addition, a well-known Guid in this GroupGuid value identifies the variation root site.

ObjectID

This is a link field. The hyperlink in this link field points to the associated site or item in the variation hierarchy. The text value of the field represents the location of the item when it was first added to the variation hierarchy. ParentAreaID

The content of this field is currently not used by the variation system. This is a link field. The hyperlink in this field points to the parent area of the associated item when it was first added to the variation hierarchy. The hyperlink and text value is not updated when the associated item or site is moved to another site in the hierarchy.

This field is empty for the variation root site. LastPropagatedSourcePageVersion

This text field is empty if the list item represents an element in the source variation hierarchy or a site in a target hierarchy. If the list item represents a document in the target label it will contain the version of the item in the source label used to propagate this target item.

(30)

Deleted

This field is used to track whether a variant of an item has been deleted in a label to prevent it from being recreated if the user configured “Recreate Deleted Target Page” to false.

Variation Labels List

The Variations Labels list is used to store the settings for the different variation labels.

Note: When you try to navigate to the Variation Labels list, you will notice that you get redirected to the Variation Labels management Each variation label is represented by one list item in the variation labels list and the configuration for

each label is stored in the fields of the list item.

Important Fields

Label (StaticName: Title)

This text field contains the Name of the label, which is used for the URL to the top site.

Flag Control Display Name

This text field contains the Title of the variation top site. This value is also use in

theMicrosoft.SharePoint.Publishing.WebControls.VariationDataSource class, which can be used to implement navigation between the variation labels. I will discuss this in more details in a later part.

Hierarchy Is Created

This Yes/No field is No at the beginning and changed to Yes by

the CreateVariationHierarchiesJobDefinition timer job after the hierarchy for the label has been created.

Is Source

This Yes/No field defines whether the label represented by this list item is a source or target label.

Language

This text field contains the configured language (selected language pack) configured for the label.

Locale

This text field contains the configured locale for the label. Top Web URL

This Link field contains the link to the top site of the variation label. This field is filled by theCreateVariationHierarchiesJobDefinition timer job after the top site for the label has been created.

(31)

Hierarchy Creation Mode

This Choice field contains the information what to do when the variation hierarchy for the label is created. The following options are available: Publishing Sites and All Pages

This option will create the top variation site for the label and will replicate the site structure and all pages created in the source label to the target label.

Publishing Sites only

This option will create the top variation site for the label and will replicate the site structure of the source label to the target label. Pages, which are not part of the site template, are not replicated.

Note: Be aware that this method will also create all lists and documents, which are defined in the site template label uses normal SharePoint provisioning methods using the same template to create the site in the target label. target label will not be sync’d with the items from the source label.

Root Sites Only

This option will only create the top variation site for the label.

SharePoint Variations – The complete

Guide – Part 7 – Variation Hierarchy

Creation

★★★★★

★★★★

★★★

★★

★

• 0

(32)

Part 6 – Configuration Internals

Part 7 – Variation Hierarchy Creation

Part 8 – Creating Page Variants Part 9 – Creating Site Variants Part 10 – Restructuring the Hierarchy Part 11 – Variations Fixup Tool Part 12 – Customization Part 13 – Logging

Overview

In order to create the hierarchies you first need to configure the variation labels, which should be spawned. At least the source Variation Label has to be configured in order to create the hierarchies.

Important: The creation of the hierarchies will fail if a site exists inside the Variation root site with the same name as one of the variation to be spawned.

The Create Hierarchies button in the UI will create a Scheduled Work Item in the Content Database of the site collection which is later retrieved by the CreateVariationHierarchiesJobDefinition timer job to do the actual creation of the hierarchy.

Per default, the timer job is configured to run once a day between 12 AM and 3 AM – that means a user will usually have to wait until the next day for the hierarchy creation to happen.

(33)

Alternatively, a farm administrator can run the job manually at any given time from the central admin site.

What happens during Timer Job execution?

Source variation and target variation top sites are always created one level below the variation root site. Each variation top site is using the site template configured when defining the source variation label. To change the look and feel between the different top sites you can either use a different theme and/or a different master page.

When the variations hierarchy is first created, only the variation top sites are created. Afterwards you can create the sub sites in the variation source hierarchy. Variants of these sites are then created in the target labels – either automatically or manually.

If sites or pages are created directly in a target label, they will not be part of the variation hierarchy and content in these sites and pages will be independent from other labels.

If a new label is added to the variation hierarchy after the variations hierarchy of the source label has been first created, a new top variation site is created for the new label and in addition, (default setting) pages and sites in the source label are automatically variated to the new label.

Creating the variation hierarchy involved three major steps:

1. Create the VariationRoot.aspx landing page which contains the logic to redirect to the different label and configure this page as welcome page for the Variation Root site 1. Create the Variation Top site for the source variation label underneath the Variation

Root site

2. Replicate the site structure and the publishing pages from the Source Variation label to new configured target and not yet spawned variation labels

Here are more details about the three steps:

Configuring the Variation landing page

The Timer Job first verifies if a page with name VariationRoot.aspx exists in the Pages library of the Variation root site.

If this is not the case, it will create, check-in, publish and approve a new Publishing Page at this location based on theVariationRootPageLayout.aspx page layout, which is part of the SharePoint Server Publishing Infrastructure feature.

The last step is to configure the VariationRoot.aspx page as welcome page for the variation root site.

(34)

Creating the Variation Top site for the source variation label

The Timer Job first verifies if the top site of the source label already exists and will skip the rest of the steps if yes.

After checking that the top site does not exist, it will disable the automatic spawning of new created sites to the target labels to ensure that the Timer Job responsible to perform the site spawning does not pick up the new site while the hierarchy is not fully created.

The next step is to provision a new publishing site based on site template, locale and language configured in the variation settings. The title of the site will be the configured display name of the variation label.

The new site will then be marked as being a member of the variation hierarchy and a new entry for the site is created in the global Relationships List.

Afterwards the new site is configured as variation top site of the label and the hierarchy of the label will be marked as created.

The final step is to re-enable the automatic spawning of new created sites to the target labels.

Replicating content from source to target labels

This is the most complex step as it is possible to add new labels long after the source hierarchy is created and new sites and pages have been added to the source label it is not sufficient to just replicate the variation top site to the target labels.

Depending on the variation settings, it might be necessary to replicate the following information: • Just the top level sites

• The whole site structure without pages • The whole site structure including all pages

The default is to replicate the whole site structure including all pages.

Here is the high-level description of how the replication is done by the timer job. Be aware that some of these operations are also performed in the other timer jobs, which are responsible to replicate only sites or pages:

For each unspawned target label, we perform the following steps:

1. Provision the top site in the target label using the same template as on the source label using the Display Name, locale and language configured for the target label

(35)

2. Ensure that the new site has the same configuration (variation group id, welcome page, features, navigation, UIVersion, Master page, Theme…) as the peer site in the source label

3. The new site will then be marked as being a member of the variation hierarchy and a new entry for the site is created in the global Relationships List

4. Pair up the pages created while provisioning the site with the equivalent items in the source site by assigning the same variation group ID to both and copy the page content from source to target label using the content deployment and migration API 5. Recursively provision all sites that exist below the variation top site in the source

label to the target label and copy all pages in the pages library using the content deployment and migration API. If required adjust the page layout of the page based on the page layout configuration for the different labels

6. Afterwards the new top site is configured as variation top site of the label and the hierarchy of the label will be marked as created

Note: Be aware that the pages in the target label will not be a one-to-one copy of the pages in the source label. Certain field and properties has to be possible to have different values in source and target. Here is a list of the fields which are not overwritten when creating/updating Title, Description, StartDate, EndDate, Layout, Audience, Contact, LocalContactName, LocalContactEmail, LocalContactImage, PreviousSpawnSourcePageVersion, FieldId.DocumentId, FieldId.AverageRatings, FieldId.RatingsCount

SharePoint Variations – The complete

Guide – Part 8 – Creating Page Variants

★★★★★

★★★★

★★★

★★

★

• 0

(36)

Part 6 – Configuration Internals Part 7 – Variation Hierarchy Creation

Part 8 – Creating Page Variants

Part 9 – Creating Site Variants Part 10 – Restructuring the Hierarchy Part 11 – Variations Fixup Tool Part 12 – Customization Part 13 – Logging

Automatic Creation of Page Variants

Usually a page variation is automatically created for a page in the following situations:

• A new page is added to the source variation label and the following settings are configured: • Automatically create site and page variations is enabled

• The DisableAutomaticPropagation option is not set to True

• A page is updated in the source variation label while the shadow page in the target label has been deleted and the following settings are configured:

• Automatically create site and page variations is enabled

• Recreate a new target page when the source page is republished is enabled • The DisableAutomaticPropagation option is not set to True

The automatic creation is initiated from either the ItemUpdated event or ItemCheckedIn event implemented in the Microsoft.SharePoint.Publishing.PagesListCPVEventReceiver class, which are bound to the Pages library.

If moderation and minor versions are disabled on a Pages library, the ItemCheckedIn event will initiate the content propagation.

If moderation and/or minor versions are enabled on the Pages library, the ItemUpdated event will initiate the content propagation if the item is in either in approved or scheduled moderation state.

Note: Be aware that automatic propagation will not happen if moderation and minor versions are disabled and also the requirement items when updating the item is disabled. The reason is that in this situation the ItemCheckedIn event will not fire as not check-in As discussed in an Part 4 the event receiver will create a Scheduled Work Item for

the PropogateVariationPageJobDefinition which will perform the content propagation. The same timer job is also responsible to propagate changes done to existing pages in the source label to the target label.

(37)

Manual Creation of Page Variants

There are certain situations where customers do not want to have automatic page creation or recreation in the target labels. Therefore automatic page variant creation might be disabled.

In case that automatic page variant creation is disabled it is required to create a variant manually using one of the following options:

a) From the Publish Tab of the Ribbon while

browsing the page

Note: You can also create page variants using the Update button in the ribbon. Be aware that this will automatically create/update labels. This option does not only update existing peers but also create new peers in labels where the page has not been variated to using similar to the automatic creation mode.

This behavior prevents granular content updates to existing peers in case that DisableAutomaticPropagation is set to True.

(38)

Both options redirect to the _layouts/CreatePage.aspx page passing in details about the original item for which the variant should be created like item id, list id, web id and folder the item resides in:

(39)

When creating a page variant manually it is possible to select a different but compatible page layout (means a page layout associated with the same content type). You can also choose a different Url name, title and description but not a different site and folder relative path. The page will be created in the peer site of the source site and the same folder in the pages library as the item in the source site. If a different folder location is required you can move the item to the desired folder after it got replicate to the target label.

It is also possible to specify for each created page variant whether to copy the resources used in the page to the target label or to reference them in the source label.

(40)

The settings choosen on the page will be passed to the CreateVariationPageJobDefinition timer job within the Scheduled Work Item.

Manual Update of page variants using the UI

Usually content changes are automatically propagated to all existing page variants through the PropagateVariationPageJobDefinition.

Except if automatic content change propagation is disabled by settings the DisableAutomaticPropagation option to False.

In case that automatic propagation is disabled, the only way to force a content update in the target labels is to use the Update Variationsoption in the Ribbon.

From the Publish Tab of the Ribbon while browsing the page:

Important: Using this action the page will be propagated to all target variation labels. Unlike automatic update operations that means be created in labels which did not have a page variant before the update operation.

The content propagation will be performed by the PropogateVariationPageJobDefinition timer job.

SharePoint Variations – The complete

Guide – Part 9 – Creating Site Variants

★★★★★

★★★★

(41)

★★★

★★

★

• 0

Part 5 – Configuration Overview Part 6 – Configuration Internals Part 7 – Variation Hierarchy Creation Part 8 – Creating Page Variants

Part 9 – Creating Site Variants

Part 10 – Restructuring the Hierarchy Part 11 – Variations Fixup Tool Part 12 – Customization Part 13 – Logging

Automatic Creation of Site Variants

Usually a site variation is automatically created for a site if the automatically create site and page variations option is enabled in the following situations:

• A new Publishing Site is provisioned within the source hierarchy

In this case, the site creation activates the Publishing Feature, which is invokes theFeatureActivated event handler of the

Microsoft.SharePoint.Publishing.PublishingFeatureHandler class which initiates the spawning of the site.

• The Publishing Feature is activated on a site which resides in the source hierarchy In this case, the creation is the same as for the previous scenario. That means activating the Publishing feature on a site (e.g. team) in the variation source hierarchy will automatically initiate the creation of variant sites in the target labels.

(42)

In this case, the spawning of the site is initiated from the WebMoved event implemented in the Microsoft.SharePoint.Publishing.CPVAreaEventReceiver class. This event is bound to all sites that have the Publishing feature activated.

As discussed in Part 4 the event receivers above will create a Scheduled Work Item for theSpawnSitesJobDefinition timer job which will perform the site propagation.

Manually Creation of Site Variants

There are certain situations where customers do not want to have automatic site creation in the target labels. So the option might be disabled.

In case that automatic site variant creation is not enabled, it is possible to create a variant manually using the following option in Site Manager:

(43)

This option redirects to http://url-to-source-site/_layouts/NewVariationSite.aspx page passing in details about the original site for which the variant should be created:

When creating a site variant manually it is possible to select a different Title and a different URL name for the site in the target label. The site will always be created in the peer site of the parent site in the source label. If a different location in the target label is required it is possible to move the site to a different location later without breaking the variation link between the sites and without affecting the ability to create variant pages later.

The settings chosen on the page will be passed to the CreateVariationSiteJobDefinition timer job within the Scheduled Work Item.

(44)

SharePoint Variations – The complete

Guide – Part 10 – Restructuring the

Hierarchy

★★★★★

★★★★

★★★

★★

★

• 0

Part 5 – Configuration Overview Part 6 – Configuration Internals Part 7 – Variation Hierarchy Creation Part 8 – Creating Page Variants Part 9 – Creating Site Variants

Part 10 – Restructuring the Hierarchy

Part 11 – Variations Fixup Tool Part 12 – Customization Part 13 – Logging

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.

(45)

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

• Moving a Publishing Site

• Deleting/Restoring a Publishing Page • Deleting/Restoring a Publishing Site • Deleting a Variation Label

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.

(46)

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

(47)

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.

(48)

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.

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 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 be adjusted through the same mechanism as other hyperlinks pointing to the site.

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.

Important: Moving a site out of the variation hierarchy – especially moving it out of the source label is a not reversible removed from the site and all included sub sites and pages and as the relationships list entries are removed you cannot 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

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.