sharepoint variations – the complete guide – part 1 – the...

SharePoint Variations – The complete

Guide – Part 1 – The Basics

★★★★★

★★★★

★★★

★★

★

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

• 0

• 0

• 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:

Multilingual sites

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).

We will discuss the details about how to achieve this in a later chapter.

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.

Variation Top Site

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.

We will discuss the Relationships List in more detail in a later chapter.

Figure 1: Variation Hierarchy


Guide – Part 2 – User Interface

★★★★★

★★★★

★★★

★★

★


• 0

• 0

• 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

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:

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:

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:

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:

Ribbon

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

page:


Guide – Part 3 – Triggers

★★★★★

★★★★

★★★

★★

★


• 0

• 0

• 0



Part 3 – Triggers










Part 13 – Logging




Part 17 – MOSS 2007 vs. SP 2010

Part 18 – FAQ

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.

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.

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.


Guide – Part 4 – Timer Jobs

★★★★★

★★★★

★★★

★★

★


• 0

• 0

• 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 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.

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.

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:

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


Guide – Part 5 – Configuration Overview

★★★★★

★★★★

★★★

★★

★


• 0

• 0

• 0



Part 3 – Triggers










Part 13 – Logging




Part 17 – MOSS 2007 vs. SP 2010

Part 18 – FAQ

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

Settings page.

The variation settings page looks as follows:

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.

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 targetautomatically), all updates to the source page will still automatically be propagated to the target label. This functionality wasMOSS 2007 and led to different workarounds like disabling the page propagation timerjob (which is responsible to copy thelabels) 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 thiscontrol 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 pagestarget 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.

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:

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.

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.


Guide – Part 6 – Configuration Internals

★★★★★

★★★★

★★★

★★

★


• 0

• 0

• 0



Part 3 – Triggers










Part 13 – Logging




Part 17 – MOSS 2007 vs. SP 2010

Part 18 – FAQ

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 supportedIf you find an inconsistency in one of these settings and you cannot resolve it using the UI you should open a support case with Microsoftanalyzed and fixed in a supported manner.

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

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.

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 variationfeature of site manager will automatically adjust all links to the moved item – including the link in the RelationshipsThe same benefit applies to all peered sites and pages. Moving them around using site manager will not breakpages 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.

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.

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.

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 templatelabel 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.


Guide – Part 7 – Variation Hierarchy

Creation

★★★★★

★★★★

★★★

★★

★


• 0

• 0

• 0



Part 3 – Triggers










Part 13 – Logging




Part 17 – MOSS 2007 vs. SP 2010

Part 18 – FAQ

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 variationto 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.

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.

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

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


Guide – Part 8 – Creating Page Variants

★★★★★

★★★★

★★★

★★

★


• 0

• 0

• 0



Part 3 – Triggers










Part 13 – Logging




Part 17 – MOSS 2007 vs. SP 2010

Part 18 – FAQ

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.

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 usingsimilar to the automatic creation mode.

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

b) From Site Manager:

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:

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.

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.


Guide – Part 9 – Creating Site Variants

★★★★★

★★★★

★★★

★★

★


• 0

• 0

• 0



Part 3 – Triggers










Part 13 – Logging




Part 17 – MOSS 2007 vs. SP 2010

Part 18 – FAQ

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.

• A site which has the Publishing feature activated is moved into the source hierarchy

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:

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.


Guide – Part 10 – Restructuring the

Hierarchy

★★★★★

★★★★

★★★

★★

★


• 0

• 0

• 0



Part 3 – Triggers










Part 13 – Logging




Part 17 – MOSS 2007 vs. SP 2010

Part 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:

• 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.

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 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 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.

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 thebe 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 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.

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 ItemDeletedevents.

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 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 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.

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

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 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 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 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

when the event handler cancels the delete operation because it identifies that the site to be deleted is the top site of a labelhierarchy.

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

“before” event. That means if the delete is not performed for whatever reason (e.g. because another event handler cancelsinconsistent relationships list as the relationships list entries for the site and all it’s pages is already gone.

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.

Important: Similar to move operations which went beyond outside of a variation label it usually requires to restore a backup from

to roll back the changes. You cannot just restore the site from the recycle bin as the relationships list entries 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.

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 separateThe side effect of this limitation is that with large hierarchies it can happen that the operation takes more time than the standard requestseconds). 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 the10 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.


Guide – Part 11 – Variations Fixup Tool

★★★★★

★★★★

★★★

★★

★


• 0

• 0

• 0



Part 3 – Triggers










Part 13 – Logging




Part 17 – MOSS 2007 vs. SP 2010

Part 18 – FAQ

The Variations Fixup Tool has been integrated into stsadm.exe to allow administrators to fix

common variation problems, which are caused by inconsistencies between the actual site structure

and the data stored in the relationships list. This article will

• explain the different operation modes of the variations fixup tool

• allow you to understand which type of problems can be fixed using the tool

Usage The Variations Fixup Tool has been integrated into stsadm.exe to allow administrators to fix common

variation problems, which are caused by inconsistencies between the actual site structure and the data

stored in the relationships list.

The tool has four different operation modes:

• Scan – This operation mode can be used to analyze the variations hierarchy and report identified

problems

This parameter provides functionality that cannot be accessed using the Central Administration

Web site.

• Fix – Corrects identified problems. If the recurse parameter is used, fixes are done recursively for

all sub-sites

This parameter provides functionality that cannot be accessed using the Central Administration

Web site.

• Spawn – This operation mode creates new variations for a site in the source variation label

specified by the URL parameter. New peers are created for either all or one specific target

variations label. If the recurse parameter is used, variations for sub-sites and pages are also created

This operation mode is equivalent to the New Variation Site user interface setting that is located

on the Site Content and Structure page.

• ShowRunningJobs – Displays current status of Variations Propagate Page Job Definition and

Variations Propagate Site Job Definition timer jobs that are located on the Timer Job Status page

of the SharePoint Central Administration Web site

The command supports the following parameters to configure these operation modes:

• URL – The URL of a site in the source variation label where variations system data is being

analyzed or corrected. This parameter is required for all operation modes

• Label – the variation label to operate on. This parameter is supported by the following operation

modes: Scan, Fix, Spawn

• Recurse – whether to perform the operation recursively or not. This parameter is supported by the

following operation modes: Scan, Fix, Spawn

The command syntax is as follows:

stsadm -o variationsfixuptool

-url <absolute web URL>

[-fix]

[-scan]

[-spawn]

[-showrunningjobs]

[-recurse]

[-label <label to fix or spawn>]

The different operation modes

In order to use the command correctly it is important to understand what the different operation modes

do.

ShowRunningJobs

This command enumerates all running jobs for all the automatic propagation jobs for sites and pages:

• Variations Propagate Page Job Definition

• Variations Propagate Site Job Definition

This command will not report any of the other “manual” variation jobs:

• Variations Create Hierarchies Job Definition

• Variations Create Page Job Definition

• Variations Create Site Job Definition

Scan

This command analyzes sites and pages in the variation source hierarchy.

For each Site/Page, it reports:

• If the source site is marked as being in the source variation hierarchy

(SPWeb.AllProperties[“__InSourceHierarchy”] == True ?). If the site is marked as being in the

source hierarchy means that the page is part of the source hierarchy.

• The Variation Group Id of the source site or page

(SPWeb.AllProperties[“Variation Group Id”] or

PublishingPage.ListItem[FieldId.VariationGroupId])

• Which peers are registered in the relationships list with same Variation Group Id

• If a variation peer exists in the configured labels (default is all spawned labels) by first checking if

a peer is configured in the relationships list with the same variation group ID for the given label. If

no peer can be found using the relationships list we try to lookup the peer using the default URL

that would be used when creating a variant in the given label

• The variation group id of the variation peers in the target labels (SPWeb.AllProperties[“Variation

Group Id”] or PublishingPage.ListItem[FieldId.VariationGroupId])

• If the source site/page is configured in the relationships list

In addition the command reports the variation labels used for the peer check (default is all spawned

labels).

The tool will not identify any issues – it is required to analyze the report in detail and interpret it in order

to find problems.

Fix

This operation mode invokes the same method as the Scan operation mode but beside analyzing and

reporting the issues it will invoke fix routines for sites and pages.

It is important to understand which types of issues are fixed and which are not.

The following issues are automatically fixed:

• Missing Variation Group ID on source site or source page

• Missing relationships list entry for source or target page or site

• Missing Variation Group ID on target site or target page

• Different Variation Group ID in source site/page and target site/page (source ID will win)

Any other problem in the variation hierarchy is not fixed by this operation mode. E.g. fix mode will not

create missing variation peers.

Spawn

This operation mode allows spawning an existing site in the source label to one or all spawned target

labels. The operation mode is similar to the New Variation Site option available in Site Content and

Structure.

Be aware that this operation mode cannot be used to spawn pages in already spawned sites. In case that page variations are missingvariations fixup tool to recreate them. You have to manually create/recreate them using the UI.

The command initiates the site spawn operation by creating a scheduled work item for the

SpawnSiteJobDefinition timerjob. The spawn will be performed as soon as the timerjob runs.

The difference between the scheduled work item created by the CPVAreaEventReceiver and the

Variationsfixuptool is that the tool has the option to create a workitem, which only spawns the site to one

specific variation rather than to all spawned variation labels.

A common use scenario is to configure the source variation label with the Hierarchy Creation option to

create only the root site and not the complete hierarchy and later to spawn the hierarchy or parts of the

hierarchy from the source label using the STSADM command.

In MOSS 2007, this command was a major benefit compared to the automatic hierarchy creation in the

UI, as it was the only way to force the creation in OWSTIMER rather than W3WP.

With SharePoint 2010 where all actions are already in OWSTIMER the benefit of using the STSADM

command rather than the UI is rather limited.

Summary The variations fixup tool allows to create a report (-Scan) about all items in the source label including

their variation group id, whether they have a reference in the relationships list and all peer pages with the

same variation group id in the configured labels. The tool will not automatically report problems but

requires an engineer to analyze the report and identify issues bases on his experiences.

The tool also allows to report which site and page propagation jobs are running (-ShowRunningJobs)

when the command is executed and the status the job is in. On the other hand, the tool does not report

anything regarding the other variation timer jobs (create hierarchy, create site, create page).

The tool allows to fix issues related to inconsistencies between items in the source and target site and the

relationships list (-Fix).

On the other hand, this command will not fix any other types of inconsistencies – e.g. missing items in

the source or target label.

The tool also allows to spawn a site or a site hierarchy including the pages from the source to either all

spawned target labels or a specific target label by creating a scheduled work item for the

SpawnSiteJobDefinition timer job.


Guide – Part 12 – Customization

★★★★★

★★★★

★★★

★★

★


• 0

• 0

• 0



Part 3 – Triggers










Part 13 – Logging




Part 17 – MOSS 2007 vs. SP 2010

Part 18 – FAQ

This module explains supported ways to implement customizations in the variation system.

You can apply the following types of customization:

• Custom routing logic for the landing page in the variation root site

• A custom menu to allow switching between the variation labels

• Implement Variation Aware web parts

• Add event receivers to apply modification to items in the target label after they got replicated.

Customizing the Variation Landing Page Overview

The following actions are performed while creating the variation hierarchy:

• A page named VariationRoot.aspx is created in the pages library of the variation root site based

on the VariationRootPageLayout.aspx page layout file in the Master Page and Page Layouts

Gallery

• The Welcome page URL of the Variation root site is configured to point to the VariationRoot.aspx

page

If a user navigates to the Variation root site, SharePoint Server 2010 looks up the configure Welcome

Page of the site and redirects to the VariationRoot.aspx page. As this page is based on

VariationRootPageLayout.aspx, it executes the logic in the page layout file.

The VariationRootPageLayout.aspx page layout contains a reference to a file

called VariationsRootLanding.ascx file, which resides on the file system in

the …\14\template\controltemplates folder. The VariationsRootLanding.ascx file implements the

logic, which redirects the user to a Variation site.

The default logic used in the VariationsRootLanding.ascx file is to redirect the user to the Variation site

that matches the browser’s accepted languages.

How to customize the Variation Root logic

If you want the Variation root landing page logic to redirect the user to a Variation site that is not based

on the accept language, you can do this in one of three ways. Each option has its own advantages and

disadvantages, and you should consider them carefully before deciding which approach to use:

Directly edit the VariationsRootLanding.ascx

Benefits:

This is the quickest way to edit the logic, as you only have to edit the logic in the

VariationsRootLanding.ascx file in the file system of each Web front-end (WFE) server.

Caveats:

All site collections in the farm will use the same logic to redirect to a variation label.

The change has to be done on all WFEs and if a change is required, it is necessary to update the files on

all WFEs.

Use a copy of the VariationsRootLanding.ascx

This method requires changing the reference to user control in the VariationRootPageLayout.aspx using

SharePoint Designer.

Benefits:

You can easily update the logic by replacing the logic in the custom ascx file on the file system.

Each site collection can have a different logic for the redirection.

Caveats:

The copy has to be created on all WFEs and if a change is required, it is necessary to update the files on

all WFEs.

You have to update the VariationRootPageLayout.aspx to reference the updated user control.

Move logic directly into the VariationRootPageLayout.aspx

This can be achieved by copying and adjusting the content from the VariationsRootLanding.ascx file

into the VariationRootPageLayout.aspx in the Master Page and Page Layouts Gallery.

Benefits:

Like the previous approach, this approach also provides rapid customization through direct editing.

Changes have to be done only at one single location as the logic is in the database.


Caveats:

To complete this process, it is required to modify the web.config to allow inline code in the

VariationRootPageLayout.aspx page.

<SharePoint>

<SafeMode … >

<!– Enable ASP.NET compilation for variation root logic –>

<PageParserPath

VirtualPath=”/_catalogs/masterpage/VariationRootPageLayout.aspx”

CompilationMode=”Always”

AllowServerSideScript=”True”

AllowUnsafeControls=”False”

IncludeSubFolders=”False”/>

</PageParserPaths>

</SafeMode>

</SharePoint>

An additional customization might be to place the logic into a custom assembly and deploy this using a

feature into the Global Assembly Cache of all machines. Then you can reference this custom code either

from the user control or directly from the VariationRootPageLayout.aspx page.

Creating a Variation Label Menu Control Overview

Many websites allow a reader to switch to a different language version of the same page using a

hyperlink – either textual or as an image (e.g. the country flag).

SharePoint 2010 provides a framework to implement the required functionality quickly:

Master Page

Each of the default master pages contains a reference to a file called VariationsLabelMenu.ascx, through

a DelegateControl element in their markup:

<SharePoint:DelegateControl runat=”server” ID=”GlobalDelegate0″

ControlId=”GlobalSiteLink0″ />

Delegate Control

The publishing feature registers the DelegateControl GlobalSiteLink0 element

in …\14\TEMPLATE\FEATURES\Publishing\VariationsFlagControl.xml. This XML file points to the

VariationsLabelMenu.ascx file, which causes all sites provisioned with the publishing feature to have the

rendering provided by VariationsLabelMenu.ascx. This also causes the master pages for all publishing

site collections in the server farm to contain the same rendering provided by VariationsLabelMenu.ascx.

…\14\TEMPLATE\FEATURES\Publishing\VariationsFlagControl.xml

<!– _lcid=”1033″ _version=”14.0.4750″ _dal=”1″ –>

<!– _LocalBinding –>

<Elements xmlns=”http://schemas.microsoft.com/sharepoint/”>

<Control

Sequence=”50″

Id=”GlobalSiteLink0”

ControlSrc=”~/_controltemplates/VariationsLabelMenu.ascx”>

</Control>

<Control

Sequence=”50″

Id=”VariationsFlagControl”

ControlSrc=”~/_controltemplates/VariationsLabelMenu.ascx”>

</Control>

</Elements>

As you can see the same user control is registered with two different control Ids: GlobalSiteLink0 and

VariationsFlagControl. It does not matter which Id you use in your master pages – both will work.

Because the Delegate controls are the same for all publishing sites in all site collections, they all

reference the same user control on the file system, the rendering cannot vary from site collection to site

collection with default setup.

VariationsLabelMenu.ascx

The VariationsLabelMenu.ascx file needs to contain the logic to render variation label menu on the page.

Per default only the VariationDataSource control is embedded in this control but not a rendering control

to leverage this data source. So per default no variation labels menu is displayed.

In order to display the variation labels menu it is required to update the VariationsLabelMenu.ascx and

add a reference to a rendering control for the data source.

We will discuss supported methods to customize this control in the next sections.

VariationDataSource

The VariationDataSource control is not a rendering control. It acts as data source for other web controls,

which support data binding like a Repeater, or a DataList control.

It provides information about peers of the current page in other variation labels.

This data source can be utilized by different controls like an ASP.NET Repeater or a DataList control or

the VariationsLabelEcbMenu shipped with SharePoint.

<cms:VariationDataSource id=”LabelMenuDataSource” LabelMenuConfiguration=”1″

Filter=”” runat=”server”/>

Label Menu Configuration

The VariationDataSource control supports three different operation modes using the

LabelMenuConfiguration attribute:

• Link to Peers: this is the default and most common operation mode. In this mode, the data source

returns links to peer pages of the current page.

LabelMenuConfiguration=”1″

• Link to Parent: using this operation mode the data source returns links to the peers of the parent

site. That link will not point to the peer page but to the peer site of the current site.


• Link to Top Site: using this operation mode the data source returns links to the top sites of peer

labels.


Filtering

The variation data source supports filtering on the label result set. If e.g. administrative labels exist in the

hierarchy, which should not be exposed to users, then you can create a regular expression filter on the

label name to exclude them from the view, which means that the data source will not return links to peer

pages in the filtered labels. A simple filter could be “^\w”. This filter will only display labels which start

with alphanumeric characters (a-z, A-Z, 0-9). Labels starting (e.g.) with a special character like “-” will

not be displayed.

Rendering Control

We will discuss how to use the VariationDataSource with a rendering control in the next sections.

Customizing the variation label menu logic

In the previous section, we discussed the different instances involved in rendering a variation label

menu. However, without customization no menu is displayed, as no rendering control is included in the

out-of-the-box user control.

Different customizations are possible – each with individual advantages and disadvantages:

Directly edit the VariationsLabelMenu.ascx

Benefits:

This is the quickest way to edit the logic, as you only have to edit the logic in the

VariationsLabelMenu.ascx file in the file system of each front-end Web server.

Caveats:

All site collections in the farm will use the same logic to render the variation label menu.

The change has to be done on all WFEs and if a change is required, it is necessary to update the files on

all WFEs.

Use a copy of the VariationsLabelMenu.ascx

This method requires changing the reference to the user control in the master page using SharePoint

designer and/or to register a new control for the delegate control using a custom feature.

Benefits:

You can easily update the logic by replacing the logic in the custom .ascx file on the file system.


Caveats:

The copy has to be created on all WFEs and if a change is required, it is necessary to update the files on

all WFEs.

Copy the user control into the master page gallery

This method also requires changing the reference to the user control in the master page using sharepoint

designer and/or to register a new control for the delegate control using a custom feature.

Benefits:

Like the previous approach, this approach also provides rapid customization through direct editing using

SharePoint designer.

Changes have to be done only at one single location as the logic is in the database.


Caveats:

To complete this process, it is required to modify the web.config to allow inline code in the

VariationLabelMenu.ascx user control in the master page gallery.

<SharePoint>

<SafeControls>

<!– Marks the VariationsLabelMenu.ascx as safe. –>

<SafeControl

src=”http://blogs.technet.com/_catalogs/masterpage/VariationsLabelMenu

.ascx”

Safe=”True” AllowRemoteDesigner=”True” />

</SafeControls>

<SafeMode … >

<!– Marks VariationsLabelMenu.ascx for compilation. –>

<PageParserPaths>

<PageParserPath

VirtualPath=”/_catalogs/masterpage/VariationsLabelMenu.ascx”

CompilationMode=”Always”

AllowServerSideScript=”True”

AllowUnsafeControls=”False” />

</PageParserPaths>

</SafeMode>

</SharePoint>

Render the variation label menu

After we have discussed different way to modify the VariationsLabelMenu.ascx we need to look into the

specific changes that have to be done to this file to enable rendering of the variation label menu.

Per default, the content of the VariationsLabelMenu.ascx looks as follows:

<%@ Control Language=”C#” %>

<%@Assembly Name=”Microsoft.SharePoint.Publishing, Version=14.0.0.0,

Culture=neutral, PublicKeyToken=71e9bce111e9429c”%>

<%@Register TagPrefix=”CMS” Assembly=”Microsoft.SharePoint.Publishing,

Version=14.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c”

namespace=”Microsoft.SharePoint.Publishing.WebControls”%>



As you can see, the VariationDataSource control is included but no rendering control is available to

render links to peer pages or sites.

VariationsLabelEcbMenu

In SharePoint 2007, the file looked slightly different:

<%@ Control Language=”C#” %>

<%@Assembly Name=”Microsoft.SharePoint.Publishing, Version=12.0.0.0,

Culture=neutral, PublicKeyToken=71e9bce111e9429c”%>

<%@Register TagPrefix=”CMS” Assembly=”Microsoft.SharePoint.Publishing,

Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c”

namespace=”Microsoft.SharePoint.Publishing.WebControls”%>

<%– <cms:VariationsLabelEcbMenu id =”varlabelmenu1″ DataSourceID=”LabelMenuDataSource”

DisplayText=”<%$Resources:cms,VariationLabelMenuTitle%>” IsCallbackMode=”true”

runat=”server” /> –%>



As you can see, the user control contained a commented reference to the VariationsLabelEcbMenu,

which utilized the VariationDataSource.

In SharePoint 2010, the VariationsLabelEcbMenu is still available but marked as deprecated.

That means your existing applications still work (at least with the current version) but it is recommended

to use a different control for future implementations.

Many customer have special needs to render the variation labels (e.g. to render a flag beside the label

name) which cannot be done with this control.

Using the standard ASP.NET controls gives much more control of the generated html.

ASP.NET Repeater or DataList control

The main difference between these two controls is that the Repeater allows a more flexible formatting

while the DataList renders each entry in a table rows or table columns.

Both controls use templates and data binding for the rendering.

Here is a simple example for the Repeater control:

<asp:Repeater ID=”Repeater1″ runat=”server”

DataSourceID=”LabelMenuDataSource” EnableViewState=”False”>

<ItemTemplate>

<a href=”<%# DataBinder.Eval(Container.DataItem, “NavigateUrl”) %>”>

<%# DataBinder.Eval(Container.DataItem, “DisplayText”) %></a>

</ItemTemplate>

<SeparatorTemplate> | </SeparatorTemplate>

</asp:Repeater>

Each Container object in the item template supports the following public properties:

• DisplayText - DisplayName of the label

• Name – Title of the label

• NavigateUrl – the URL of the peer item, the peer site or the top site in the label

• ToolTip – returns the same as NavigateUrl

Each of these properties can be used inside the ItemTemplate for the rendering of the current Variation

link node.

The Repeater control supports two different templates: one to be used for each of the elements in the

collection the repeater iterates over, and one, which will be used as a separator between the elements.

In the sample above, we just use a vertical bar as separator, which is a nice way to separate entries in a

horizontal list. Alternatively, you can embed the repeater in a html table and use column/row end/start

tags in the separator template.

Common problem using the VariationDataSource

After implementing a custom label menu using the VariationDataSource and one of the ASP.NET

controls you will notice the following problem when using the View or Edit properties from the ribbon

(callstack enabled and custom errors disabled in web.config to get a better error message):

This error occurs as with all controls, which perform databinding on first load – including the

VariationsLabelEcbMenu if CallbackMode is disabled.

Note: The IsCallbackMode attribute of the VariationLabelEcbMenu controls whether databinding is performed with everyuser clicks the dropdown rendered by the menu.

See my previous post for more details and workaround of this problem.

Implementing Variation Aware Web Parts Web Parts are a black box for the content deployment and migration API. Only the web part itself knows

what type of content is stored inside it. When variating pages from source to target it might be that the

content of the web part has to be adjusted to work correct at the new location.

The content deployment and migration API cannot directly perform these modifications as it does not

know which operations to perform to make the web part content compatible with the new location.

To overcome this problem the developer of a web part can implement

the IWebPartVariationUpdate interface. Using this interface it is possible to implement an Update

method which can then be called by the variation feature after the page holding the web part has been

replicated to the target label to ensure that the web part can fix its internal data.

From the web parts shipped with SharePoint only the ContentByQueryWebPart and

the TableOfContentsWebPart implement this interface.

Customizing using Event Receivers You can apply event receivers to the Sites or Pages libraries of the target label – e.g. through Feature

stapling – and perform specific operations.

A good example of such a modification has been demonstrated by Vamsi Krishna Rallabhandi on his

recent blog post:

• Handling incorrect link propagation in Site Variations in SharePoint 2010

harePoint Variations – The complete Guide

– Part 13 – Logging

★★★★★

★★★★

★★★

★★

★


• 0

• 0

• 0



Part 3 – Triggers










Part 13 – Logging




Part 17 – MOSS 2007 vs. SP 2010

Part 18 – FAQ

This part highlights the different logging options for the SharePoint variation system.

Variation Logs The variation system logs status information into the hidden Long Running Operation Status list in the

root of the site collection. Most problems related to variations are reflected in this log.

The Variation logs can be inspected through a link in the Site Collection Administration section of the

Site Settings page:

The variation log uses a GridView control to display a filtered view of the Long Running Operation

Status list using a SPDataSource control. The data source returns all rows from the Long Running

Operation Status list where the Type Of Job column contains the string “Variation”. Newest entries are

listed first.

Success messages and Failures are listed in separate columns, which give easy access to the information

if a problem has occurred with recent propagations:

ULS Log In case that the information in the Variation Log is not sufficient to isolate a variation problem, it is

possible to leverage the SharePoint Unified Logging Service (ULS) to get additional logging

information.

Both the Variations Infrastructure and the Content Deployment and Migration API (which is used to

perform export and import operations during page propagation) use the ULS log to report problems

using the following categories:

For the Content Deployment and Migration API:

• SharePoint Foundation\Content Migration

• SharePoint Foundation\Topology

For the Variations Feature:

• Web Content Management\Site Management

• Web Content Management\Publishing Provisioning

To troubleshoot, variation related issues these four categories should be set to Verbose in the central

administration page.

You can use ULS Viewer to conveniently analyze ULS log files.

The most important category is Site Management. You should filter the ULS log for this category first. If

this does not give you relevant information, add the other two WCM categories on top. If the problem is

related to problems occurring during export/import, you need to add the two SharePoint Foundation

categories as well.


Guide – Part 14 – Troubleshooting

★★★★★

★★★★

★★★

★★

★


• 0

• 0

• 0



Part 3 – Triggers










Part 13 – Logging




Part 17 – MOSS 2007 vs. SP 2010

Part 18 – FAQ

This part will provide troubleshooting steps for the following common type of problems:

• Propagation Problems

• Variation Hierarchy is not created

• Automatic Page/Site propagation does not work

• Manual Page/Site propagation does not work

• Variation Label menu does not show correct results

• Variation landing page redirection does not work correct

Troubleshoot propagation problems

Propagation problems can be caused either in the application pool or in the SharePoint timer services. So

the first troubleshooting step has to be to determine if the problem occurs in the application pool or in

the timer service.

The following sequence of troubleshooting steps should be applied:

General steps

1. Check the Variation Log (see part 13 for details)

2. Check the ULS log for problems (see part 13 for the required categories)

3. Use STSADM -o variationsfixuptool -scan to analyze variation inconsistencies which might be

related to the problem

Isolate if worker process or timerjob

If the Variation Log indicates that the timer job is not executed:

1. Check if the relevant timerjob for the web application is enabled and correctly scheduled

Note: You can use powershell to dump a filtered timerjob list for your web application, which contains the relevant information.

command dumps the information about the variation timerjobs for the web application on port 1007: PS> (get-spwebapplication http://servername).JobDefinitions | where {$_.DisplayName -matchDisplayName, IsDisabled, LastRunTime, Schedule | fl

2. Check if the relevant timerjob has been executed successfully in the relevant timeframe

Note: You can use powershell to dump a filtered timerjob history for your web application. E.g. the following command dumps

variation timerjobs for the web application on port 1007: PS> (get-spwebapplication http://servername).JobHistoryEntries | where {$_.JobDefinitionTitle“variation”} The following command dumps the history for the create hierarchies timer job:

PS> (get-spwebapplication http://servername).JobHistoryEntries | where {$_.JobDefinitionTitleCreate Hierarchies Job Definition”}

3. Check if a scheduled work item for the specific type and is created in the ScheduledWorkItems

table when the relevant action is performed. See the table at the end of Part 4 to identify the

Work item to look for.

4. Check if the scheduled work item is removed from the Scheduled Work Items table after the

timerjob has been started and ended.

Warning: Direct read access to a production SharePoint database can affect the performance of the site. It is recommendedMicrosoft to do this type of troubleshooting on a production system.

5.

Troubleshoot propagation problems in variation timerjobs

If problems occur within a timerjob you usually have to rely on the information provided by the

Variation Log or ULS logs to isolate the problem. If this information is not sufficient to isolate the issue

you should consider to open a support call with Microsoft as advanced debugging skills will be required

to further isolate the problem.

Troubleshooting propagation problems in the worker process

The following steps are relevant for spawn/hierarchy creation problems where the workitem is not added

to the ScheduledWorkItems table in the content database.

In this case, the problem is caused inside the IIS worker process.

If an event handler should initiate the failing operation verify if the event handler is properly bound to

the relevant Pages library or site.

Note: You can use the following powershell command to dump all event receivers registered on a specific Pages library. PS> (get-spweb http://servername/en).Lists[“Pages”].EventReceivers | select Type,Class | fl

The following event handlers need to be registered on the Pages library to ensure that the variation

system works correct:

Type : ItemDeleting

Class : Microsoft.SharePoint.Publishing.PagesListCPVEventReceiver

Type : ItemAdded


Type : ItemUpdated


Type : ItemDeleted


Type : ItemCheckedIn


Note: You can use the following powershell command to dump all event receivers registered on a specific Site: PS> (get-spweb http://servername/en).EventReceivers | select Type,Class | fl

The following event handlers need to be registered on the site to ensure that the variation system works

correct:

Type : WebDeleting

Class : Microsoft.SharePoint.Publishing.CPVAreaEventReceiver

Type : WebMoving


Type : WebMoved


Be careful if you find that custom event receivers are listening to the same events as the logic in the

custom event receivers might badly interact with the event receivers registered by the variation system.

For the manual spawn/hierarchy creation actions, you usually have to rely on the information provided

by the Variation Log or ULS logs to isolate the problem. If this information is not sufficient to isolate

the issue you should consider to open a support call with Microsoft as advanced debugging skills will be

required to further isolate the problem.

Troubleshoot Variation Label menu related problems

Here we need to differentiate between two different problems:

The variation labels menu never shows up

This is a common scenario if there is a problem in the VariationsLabelMenu.ascx, which causes the

dynamic compilation to fail. E.g., incorrect assembly references can cause this problem. Unfortunately,

SharePoint consumes such compile time problems and just silently hides the affected user control rather

than showing the error.

The “easiest” way I found to troubleshoot these issues is to attach a debugger (e.g. Visual Studio) to the

worker process and monitor the status messages while loading a page with the variation labels menu.

Usually problems are reported as System.Web.HttpParseExceptions.

You might see messages like these:

(9ac.15d4): CLR exception – code e0434f4d (first chance)

CLR exception type: System.Web.HttpParseException

“Unknown server tag ‘CMS:VariationsLabelEcbMenuX’.”

(9ac.1268): CLR exception – code e0434f4d (first chance)

CLR exception type: System.Web.HttpParseException

“Could not load file or assembly ‘Microsoft.SharePoint.Publishing,

Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c’ or one

of its dependencies. The system cannot find the file specified.”

You will have to analyze and correct the parser errors reported with the exception to fix the problem.

The variation labels menu does not show links to all existing peers

This usually indicates a problem in the relationship between the peer pages. Either site/page properties

are not correctly set or entries in the relationships list are missing or incorrect.

The best way to isolate such problems is to use STSADM -o variationsfixuptool -scan to analyze the

problems and STSADM -o variationsfixuptool -fix to solve the problem.

Troubleshoot Variation landing page related problems

The first important step is to check from which location the VariationRoot.aspx receives the logic to

perform the routing.

As outlined in Part 10 it is possible to move the logic out of the VariationRootLanding.ascx into other

controls or even into libraries in the SharePoint content database.

Verify the welcome page settings of the variation root site and ensure that it points to the

VariationRoot.aspx page. Verify if the VariationRoot.aspx page uses the VariationRootPageLayout.aspx

page. If customization has been applied to the variation root logic, use SharePoint designer or

Powershell to inspect the content of the VariationRootPageLayout.aspx

Note: You can use the following powershell command sequence to dump the binary content from the SPFile object of the VariationRootPageLayout.aspxlayout to the file system: PS> $byteArr = ((get-spweb http://server).Lists[“Master Page Gallery”].Items | where{$_.Name -match“VariationRootPageLayout.aspx” }).File.OpenBinary()

PS> [System.IO.File]::WriteAllBytes( “c:VariationRootPageLayout.aspx”, $byteArr)

Possible Reasons for routing problems with the variation landing page

In general, there are five different reasons, which can cause routing problems with the Variation landing

page:

Problem in the variation label definition

Analyze using a custom view if the hierarchy for the desired target label is created and that the correct

language, locale and top site is configured in the list item.

Problem with the relationship between variation peers

Either site/page properties are not correctly set or entries in the relationships list are missing or incorrect.

The best way to isolate such problems is to use STSADM -o variationsfixuptool -scan to analyze the

problems and STSADM -o variationsfixuptool -fix to solve the problem.

Permission problems

If the logic in the VariationsRootLanding.ascx is using security trimmed API (e.g.

Variations.Current.UserAccessibleLabels), it is possible the routine is influenced by different

permissions of the users and whether they arrive on the page anonymous or authenticated.

Test if the users can navigate to the variation top site of the desired label using the direct URL.

Browser configuration problems

The default routing logic uses the language settings configured in the browser to determine the target

label. If the user has changed these settings, the routing might not be as expected. A network monitor

trace reveals the language settings configured by the user and can help to isolate such problems.

Problems in the logic of the landing page

Often the default routing logic does not fulfill the customer’s requirement and needs to be adjusted.

Alternatively, customers have already implemented a custom logic, which does not work as expected.


Guide – Part 15 – "View Changes" Button

★★★★★

★★★★

★★★

★★

★

December 1, 2011 by Stefan Goßner // 0 Comments

• 0

• 0

• 0



Part 3 – Triggers










Part 13 – Logging




Part 17 – MOSS 2007 vs. SP 2010

Part 18 – FAQ

This lesson gives insights into the Variation specific View Changes ribbon action and how it determines

the versions to compare.

It is important to understand that this button is always disabled if you see the button in context of a page

which does not reside in a target variation label. You cannot use it (e.g.) in the source label. It is also

disabled if the current page in the target label is a major version or if only one version has been

propagated from source to target.

What the button allows you to do is to compare the most recently propagated source page version with

the version of the source page which was last used to create an approved version in the target.

To give you an example:

The Diagram above shows the following actions:

1. A user created a page in the source label (version 1.0)

2. The page was approved (version 1.0) which caused automatic propagation to the target where

the page arrives as version 0.1

3. A translator worked on the page in the target label and approved it (Version 1.0)

4. In the source label someone changed something in the page (Version 1.1)

5. Later the page is approved again (version 2.0) which causes automatic replication to the target

label (version 1.1)

6. Before a translator was able to work on the updated propagated page in the target another

change is done in the source and approved (version 3.0) which causes another automatic

propagation to the target (Version 1.2)

7. Another change is done on source but is not yet approved (version 3.1)

8. Now a translator starts to work on the page (version 1.2 and 1.3).

9. The translator would like to know what has changed in the source page since he last translated

the content. He uses the View Changes button which shows him the difference between version

1.0 and version 3.0 in the source page.

The question is now: how does SharePoint know which versions to compare?

Propagation Version Tracking The variation system keeps track about the last propagated page version in two different places:

In a column of the Relationships List Entry

When a new version is variated to the target label the variation system adds/updates the relationships list

entry of the created/updated target page.

The LastPropagateSourcePageVersion column of the relationships list entry will receive the version

of the source page of the variation

In a property of the target peer page

When a new version is variated to the target label the variation system preserves the previous value of

thePreviousSpawnSourcePageVersion property of the list item in the target page.

This property is changed by the ItemUpdated event receiver when the page is either approved or

scheduled to go live in the future. The event receiver will then copy the value of

the LastPropagateSourcePageVersion from the relationships list entry into this property.

That means the LastPropagateSourcePageVersion column in the relationships list always contains the

version of the source page which was last variated to the target while

the PreviousSpawnSourcePageVersion property of the target page always contains the version of the

source page which was last propagated for the currently approved version in the target.

If both versions are the same, then the published version of the page in the target label is based on the

last propagated source version.

If both versions are different, then at least one update has been propagated from source to target since

the last version was published in target.

The View Changes ribbon action

The View Changes ribbon action evaluates the version information stored in

the LastPropagateSourcePageVersion column of the relationships list entry and in

the PreviousSpawnSourcePageVersion property of the page.

If both are different it generates an url to the _layouts/VersionDiff.aspx page passing in information

about the source page (list id and item id) and the information about the two different versions stored as

listed above to create a comparison.

The VersionDiff.aspx page comes with SharePoint Foundation and allows to compare the content in the

different columns of a list item using the VersionDiffIterator control.


Guide – Part 16 – Translation Support

★★★★★

★★★★

★★★

★★

★


• 0

• 0

• 0



Part 3 – Triggers










Part 13 – Logging




Part 17 – MOSS 2007 vs. SP 2010

Part 18 – FAQ

Today I will explains how translatable columns and the variation export/import functionality can be used

to support content translation

We will cover the following topics:

• Explain the purpose of translatable columns

• Explain how to enable export/import functionality in manage content and structure

• Explain how to translate content and create a new import package

Translatable columns The site settings menu contains another option which belongs to Variations which we did not yet

discuss:

Although not obvious from the name Translatable Columns are part of the Variation Infrastructure.

The purpose of translatable columns is to allow to flag which columns in publishing pages of a site

collection should be translated.

Be aware that SharePoint itself does not take care of translation! It also does not support different

languages in the same column as the option might imply.

Translatable columns are only used to flag specific columns as translatable when an export package is

created to allow an external company to translate the content.

Important: The translateable columns information is only for information to the translator. There is nothing that could prevent the

any other column beside the one marked as being translatable. All changes to any column will be applied when importing the package back into the variation system. As well those columns markedthose which are not marked as translatable.

TranslateFields property

The information about the translatable columns is stored in Xml format the TranslateFields property in

the property bag of the root folder of the relationships list in the root site of the site collection:

<Fields>

<Field Id=”52578fc3-1f01-4f4d-b016-94ccbcf428cf”>Comments</Field>

<Field Id=”34a72e09-3ca6-4931-b2e3-f81c40bb87bd”>Description</Field>

<Field Id=”f55c4d88-1f2e-4ad9-19af4ee7ee8″>Page Content</Field>

</Fields>

Export/Import of a variation label for translation Export/Import using the UI

Looking at a site in a target label in site manager in MOSS 2007 you can see the following two options:

Comparing this with the menu options of a site in a target label on SharePoint 2010 you will miss these

options:

To use the Export Variation and Import variation dialog options in SharePoint 2010 it is required to

enable these options by editing the_layouts/SiteManager.aspx file:

…

<SharePoint:MenuItemTemplate UseShortId=false id=”OLWebExport”

runat=”server” Text=”<%$Resources:cms,SmtExport%>”

ClientOnClickScript=”SmtVariationExportWarning(‘%WebExportUrl%’)” Visible=”false

” />

<SharePoint:MenuItemTemplate UseShortId=false id=”OLWebImport” runat=”server”

Text=”<%$Resources:cms,SmtImport%>”

ClientOnClickNavigateUrl=”%WebImportUrl%&%SourceParam%” Visible=”false” />

…

After changing the value of the Visible attribute to true the options are available also on SharePoint

2010.

After choosing the Export Variation option the server will export all pages in the pages library of the site

into a content migration package which is streamed back as response to the post request.

Choosing the Import Variation option redirects to a dialog that allow to pick the content migration

package holding the translated content.

Important: The dialog seems to imply that the import will be performed into the selected site – but that is not what happens.The Import

with RetainObjectIdentity = true – which means that the items in the package will be imported with the same Guid and Url as they

if you exported site1 and then select the import option in site2 the import will still be performed into site1. That also means that thebeing imported have a different URL as before – e.g. because their Url name has changed or because the site was moved.

Export/Import using the PublishingService

To allow automated translation of content SharePoint provides the export and import funcationality also

through the ExportObjects andImportObjects methods of the PublishingService web service which

can be accessed using the following URL:

http://servername/site/_vti_bin/PublishingService.asmx

There is good documentation on how to use the web service for export and import on MSDN:

• PublishingService.ExportObjects Method

• PublishingService.ImportObjects Method

Content Migration Package for translation We will not go into all the details of the content migration package here. But I will highlight the relevant

parts which are required to implement a translation service.

ExportSettings.xml

The ExportSettings.xml file contains the information about the settings used to export the package and

the objects selected to be exported:

<?xml version=”1.0″ encoding=”utf-8″?>

<ExportSettings

xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”

xmlns:xsd=”http://www.w3.org/2001/XMLSchema”

SiteUrl=”http://servername/”

FileLocation=”C:\Temp\b3c42cb3-922a-4738-878a-bb4df62bd86b”

BaseFileName=”f265b29f-dbb5-4b71-93c6-3e6ed9a89add.cmp”

IncludeSecurity=”None” IncludeVersions=”CurrentVersion”

ExportPublicSchema=”true” ExportFrontEndFileStreams=”true”

ExportMethod=”ExportAll” ExcludeDependencies=”false”

xmlns=”urn:deployment-exportsettings-schema”>

<ExportObjects>

<DeploymentObject Id=”00000000-0000-0000-0000-000000000000″

Type=”ListItem” ParentId=”00000000-0000-0000-0000-000000000000″

Url=”/VarRoot/target/site1/Pages/default.aspx“

ExcludeChildren=”false” IncludeDescendants=”All” />

</ExportObjects>

</ExportSettings>

You will find one DeploymentObject per exported page as the Translation export functionality selects

each page explicitly for export.

VariationsLanguageSettings.xml

This file only exists in content migration packages, which are created with the export for translation

option.

The file contains the information about source and desired target language to be used for the translation.

The information is taken from the configuration of the source label and the exported target label.

<LanguageSettings>

<SourceLanguage>en-US</SourceLanguage>

<TargetLanguage>de-DE</TargetLanguage>

</LanguageSettings>

TranslatableFieldSettings.xml

This file only exists in content migration packages, which are created with the export for translation

option – and only if translatable columns are defined in the site collection.

The content of this file will be an exact copy of the value of the TranslateFields property in the property

bag of the root folder of the relationships list in the root site of the site collection:

<Fields>

<Field Id=”52578fc3-1f01-4f4d-b016-94ccbcf428cf”>Comments</Field>

<Field Id=”34a72e09-3ca6-4931-b2e3-f81c40bb87bd”>Description</Field>

<Field Id=”f55c4d88-1f2e-4ad9-19af4ee7ee8″>Page Content</Field>

</Fields>

The information in this file should be used by translators – or 3rd party editing tools supporting

translators to allow them to decide which column values to translate.

Manifest.xml

This is the file which translators have to work on to translate the content. As changing the markup would

cause problems during re-import it is recommended to read the file with a custom tool which provides

access only to those columns defined in TranslatableFieldSettings.xml.

<?xml version=”1.0″ encoding=”utf-8″?>

<SPObjects xmlns=”urn:deployment-manifest-schema”>

<SPObject Id=”04f122ee-aeb6-017f-99a7-7447d09414a1″

ObjectType=”SPContentType” …

Url=”/VarRoot/target/site1/Pages”>

<ContentType ID=”0x010100C568DB…” …>

…

<Fields>

…

<Field ID=”{f55c4d88-1f2e-4ad9-aaa8-819af4ee7ee8}”

Name=”PublishingPageContent” StaticName=”PublishingPageContent”

SourceID=”http://schemas.microsoft.com/sharepoint/v3″

Group=”Page Layout Columns” DisplayName=”Page Content”

Type=”HTML” Required=”FALSE” Sealed=”TRUE” RichText=”TRUE”

RichTextMode=”FullHtml” Customization=”” ColName=”ntext6″

RowOrdinal=”0″ />

…

<SPObject Id=”7bda6573-027d-4670-9ebb-c588483b9143″

ObjectType=”SPFile” …

Url=”/VarRoot/target/site1/Pages/default.aspx”>

<File Url=”Pages/default.aspx”…>

<Properties>

…

<Property Name=”PublishingPageContent” Type=”String”

Access=”ReadWrite”

Value=”Content to be translated” />

…

<SPObject Id=”cf8a9bfd-5892-4938-908f-ed9328e305d5″

ObjectType=”SPListItem” …

Url=”/VarRoot/target/site1/Pages/default.aspx”>

<ListItem FileUrl=”Pages/default.aspx” …>

<Fields>

…

<Field Name=”PublishingPageContent”

Value=”Content to be translated”

FieldId=”f55c4d88-1f2e-4ad9-aaa8-819af4ee7ee8” />

Identifying the relevant fields to be translated is not completely straight forward: first you have to

identify which field to translate from the TranslatableFieldSettings.xml. Here you can use the Field Id or

the field Display Name to find the Field information in the SPContentType object in the Manifest.xml

file.

This will allow you to get the Name property of the SPField which is referenced later in the SPListItem

and SPFile objects in the manifest.xml file which hold the actual content to be translated.

It is important that as well the content in the SPFile and in the SPListItem object is translated (both will

hold the same information).


Guide – Part 17 – MOSS 2007 vs. SP 2010

★★★★★

★★★★

★★★

★★

★


• 0

• 0

• 0



Part 3 – Triggers










Part 13 – Logging




Part 17 – MOSS 2007 vs. SP 2010

Part 18 – FAQ

Timerjob changes In MOSS 2007, various variation specific operations were executed in the worker process of the actual

web application rather than in a timer job. That caused a problem with large sites – especially on 32-bit

systems – as the memory resources available to the worker process had to be shared between the

variation operations and worker threads, which were handling web requests.

In MOSS 2007, only two operations were handled in timer jobs:

• Automatic creation of site variants (handled in the SpawnSitesJobDefinition timer job)

• Automatic creation of page variants (handled in the PropagateVariationPageJobDefinition timer

job)

As some of the remaining operations – e.g. creating new variation hierarchies for an existing variation

system – could run for many hours, it was possible that the configured application pool recycling

intercepted the variation operations, which led to partially propagated content between source and target.

With SharePoint 2010, the design has been changed in a way that the critical functionality has been

moved out of the worker process and into a timer job.

The following operations are affected by this design change:

• Creation of variation hierarchies (now handled in the CreateVariationHierarchiesJobDefinition

timer job)

• Manual creation of sites and pages (now handled in the CreateVariationPageJobDefinition timer

job)

• Manual update of a page variant (now handled in the CreateVariationSiteJobDefinition timer

job)

Another important change is that all the variation timer jobs are now pausable and support recycling of

the SharePoint timer service.

UI Changes Most of the remaining differences are a side effect of the fact that the operations are now no longer

executed as long running operations (LRO) but as timer jobs executed in a different process.

Due to this change, operations executed in the UI are now no longer executed when the user request the

operation in the UI but when the timer job runs next.

That means that UI actions, which previously started a long running operation in the worker process

have been changed to an action which only enqueues the operation for a scheduled timer job.

For a user, this change can have a significant impact on the workflow of an author as he now has to wait

for the timer job to be executed before he can work on the target items.

If the default schedule of the timer jobs is used that means, the user has to wait until the next day for the

creation of a variation hierarchy when a new label is created, and for up to one hour for each page that

needs to be variated.

Logging Changes Variations logs are much more stable and reliable in SharePoint 2010 than in MOSS 2007. In MOSS

2007 there were many situations where variation propagation failed without helpful information in the

Variation log – sometimes the entry was there but empty.

In SharePoint 2010 the variation log is much more stable and usually it is possible to pinpoint the reason

for a failed propagation through just this log.

Another change in logging are the ULS log categories used by the content deployment and migration

API.

In MOSS 2007 the Content Deployment and Migration API used mainly the Upgrade category while in

SharePoint 2010 it uses the Content Migration and Topology category.

harePoint Variations – The complete Guide

– Part 18 – FAQ

★★★★★

★★★★

★★★

★★

★


• 0

• 0

• 0



Part 3 – Triggers










Part 13 – Logging




Part 17 – MOSS 2007 vs. SP 2010

Part 18 – FAQ

In this last part of the article series I would like to address common questions I receive from customers.

You might want to check for updates on this page in the future as I will update this part with new

questions as they arise.

Common Questions Question: Are permissions replicated from source to target label?

Answer: No. Permissions are not replicated as it is expected that the same user can have a different role

in a different label.

Question: Are manually activated features replicated from source to target label?

Answer: This depends: if the features activation is done before the site has been created in the target

label through the variation engine then the features will also be activated on the target label. Features

activated on the sites later will not get replicated as the variation engine only supports updates to pages

but not to sites.

Question: Is the content of minor versions of pages replicated to the target label?

Answer: In general the answer is no. Only major versions are replicated to the target label. The only

exception is during initial replication of a site from source to target when pages are provisioned through

the site templates. During the replication the content of the current version of the related pages in the

source label is replicated to the target label – even if this is a minor version.

Question: Is there a list of columns and properties which do not get overwritten during replication?

Answer: See in the note at the bottom of Part 7

Question: Are properties in the site property bag replicated from source to target?

Answer: No, site properties are not replicated.

Question: Are changes to navigation settings replicated between source and target labels?

Answer: This depends: if the navigation setting changes are done before the site has been created in the

target label through the variation engine then the navigation settings will be replicated to the target label.

Navigation changes done later will not get replicated as the variation engine only supports updates to

pages but not to sites.

https://blogs.technet.microsoft.com/stefan_gossner/2011/11/14/sharepoint-variations-the-

complete-guide-part-1-the-basics/