SharePoint Variations has been implemented to address the following common scenarios:
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.
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.
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.
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.
[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.
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.
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.
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 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.
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 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 library of a site in the source label can cause the Variations Create Hierarchies Job Definition timer job to fail.
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.
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.
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
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
The variation system adds three links to the site collection administration section of the site settings page which will be discussed in further chapters:
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:
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:
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:
The variation system extends the ribbon with additional operations related to the current publishing page:
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.
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:
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
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 ScheduledWorkItems carries 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.
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 from SPPausableJobDefinition.
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.
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
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:
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.
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 target label (either manually or automatically), all updates to the source page will still automatically be propagated to the target label. This functionality was a major pain point in MOSS 2007 and led to different workarounds like disabling the page propagation timerjob (which is responsible to copy the content to the target labels) or creating a dummy source label to allow updates in all productive labels without affecting the content in the target labels.
In SP2010 the additional configuration the Disable Automatic Propagation option has been introduced to overcome this limitation. It allows to control whether content updates in the source label will be automatically propagated to the target label or not. If automatic propagation updates are disabled then the Automatic Creation option is ignored for pages (but it is still used for sites). Neither new nor updated pages are propagated to the target labels.
Unfortunately this option is not available in the UI - it has to be set using object model:
Disable automatic propagation:
$rootWeb = Get-SPWeb http://url-to-sitecollection
$relationshipsList = $rootWeb.Lists["Relationships List"]
$propertyStore = $relationshipsList.RootFolder
$propertyStore.Properties.Add("DisableAutomaticPropagation", "True")
$propertyStore.Update();
Enable automatic propagation:
$propertyStore = $relationshipsList.RootFolder
$propertyStore.Properties.Remove("DisableAutomaticPropagation")
$relationshipsList = $rootWeb.Lists["Relationships List"]
$rootWeb = Get-SPWeb http://url-to-sitecollection
$propertyStore.Update();
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.
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.
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.
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.
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.
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:
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.
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.
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).
This setting allows to configure the locale settings for the sites provisioned in the new variation label.
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
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.
Important: Be aware that direct modification of the settings mentioned below without going through the SharePoint UI is not supported!
If you find an inconsistency in one of these settings and you cannot resolve it using the UI you should open a support case with Microsoft to get the issue analyzed and fixed in a supported manner.
The variation system uses seven different places to store configuration information
Property bag of root site of site collection
Property bag of root folder of root site of site collection
Property bag of root folder of Relationships List
List Items in Relationships List
List Items in Variation Labels List
Property bag of sites in the Variation Hierarchy
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 clear this property.
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 variation root using Site Manager. The link management feature of site manager will automatically adjust all links to the moved item - including the link in the Relationships List.
The same benefit applies to all peered sites and pages. Moving them around using site manager will not break the relationship link and further updates to the pages will be propagated to the moved target pages automatically.
List Items in Variation Labels List
Each list item in the Variation Labels list represents a label configured for variations.
Property bag of sites in the Variation Hierarchy
To efficiently link sites to their peers, it is necessary to store some information within the property bag of the Publishing sites:
Variation Group Id
The Id of the Variation Group assigned to the site and its peers.
Fields of Pages in the Variation Hierarchy
To efficiently link pages to their peers, it is necessary to store some information within special fields of the Publishing Pages:
Variation Relationship Link
The variation system stores the URL to the associated list item in the Relationships List the "Variation Relationship Link" field of the publishing page. More details about the Relationships List in the next section.
Variation Group ID
The Id of the Variation Group assigned to the page and its peers.
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 has the value "{F68A02C8-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.
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 page.
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 the Microsoft.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 the CreateVariationHierarchiesJobDefinition 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 template of the source site as the replication to the target label uses normal SharePoint provisioning methods using the same template to create the site in the target label. However, the content of the pages created in the 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.
In order to create the hierarchies you first need to configure the variation labels, which should be spawned. At least the source Variation Label has to be configured in order to create the hierarchies.
Important: The creation of the hierarchies will fail if a site exists inside the Variation root site with the same name as one of the variation labels, which is about to be spawned.
The Create Hierarchies button in the UI will create a Scheduled Work Item in the Content Database of the site collection which is later retrieved by the CreateVariationHierarchiesJobDefinition timer job to do the actual creation of the hierarchy.
Per default, the timer job is configured to run once a day between 12 AM and 3 AM - that means a user will usually have to wait until the next day for the hierarchy creation to happen.
Alternatively, a farm administrator can run the job manually at any given time from the central admin site.
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:
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
Create the Variation Top site for the source variation label underneath the Variation Root site
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:
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 the VariationRootPageLayout.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.
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.
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:
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
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
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
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
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
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 will not be copied as it 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 a page variant:
Title, Description, StartDate, EndDate, Layout, Audience, Contact, LocalContactName, LocalContactEmail, LocalContactImage, PreviousSpawnSourcePageVersion, FieldId.DocumentId, FieldId.AverageRatings, FieldId.RatingsCount
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 to check-in and check-out items when updating the item is disabled. The reason is that in this situation the ItemCheckedIn event will not fire as not check-in occurs.
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.
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:
Note: You can also create page variants using the Update button in the ribbon. Be aware that this will automatically create/update page variants in all target labels. This option does not only update existing peers but also create new peers in labels where the page has not been variated to using the default options - similar to the automatic creation mode.
This behavior prevents granular content updates to existing peers in case that DisableAutomaticPropagation is set to True.
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.
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 Variations option 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 that page variants will also 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.
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 the FeatureActivated 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 the SpawnSitesJobDefinition timer job which will perform the site propagation.
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.
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
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:
Copy to the new location using content deployment and migration API
Update Links pointing to the item to point to the new location
Delete of the old item
Maintain the relationships list items for the variation group of the moved item
This step is performed using an export/import operation using the content deployment and migration API. Between export and import, the manifest files are modified to update variation specific fields in case that the move operation goes outside the original variation label.
That demonstrates the tight integration of the variation system into other operations in Site Manager.
I will not go into the details of the link management as I have explained these details in the following blog already: Deep Dive into the SharePoint Content Deployment and Migration API - Part 4
One specialty in this operation is that the link management checks if the link to the item comes from an item in the relationships list. If the link comes from the relationships list, the link management verifies if the move operations went beyond the boundary of a variation label and only updates the link if source and target of the move operation is in the same variation label.
This is necessary to support the maintenance of relationships list items in the final step of the move operation, which is discussed below.
The delete operation itself is a trivial task. However, the delete operation triggers two events, which are responsible to perform the next step: ItemDeleting and ItemDeleted.
In case that a move operation went beyond the boundary of a variation label additional operations are required as the moved item is no longer part of the previous variation group. To detect whether a move operation went beyond the boundary of a variation label we check whether the relationships list reference points to the deleted item or to the new created item (see "Updating Links to the moved item" above).
The variation system hooks up to the following events to handle this:
ItemDeleting - This event fires after Site Manager has copied the item to the new location, fixed the links pointing to the item and is about to delete the original item to complete the move operation.
The publishing feature has bound the Microsoft.SharePoint.Publishing.PagesListCPVEventReceiver.ItemDeleting event receiver to this event to gather the Variation Group Id from the page that is going to be deleted and make it available to the ItemDeleted event handler, which fires after the delete operation has been completed.
ItemDeleted - This event is fired after the original page has been deleted.
The publishing feature has bound the Microsoft.SharePoint.Publishing.PagesListCPVEventReceiver.ItemDeleted event receiver to this event, which is responsible to maintain the relationships list references in case that the move operation moved an item out of a variation label. In this situation, the item is no longer a member of the previous variation group and the relationships list entry has to be updated accordingly.
In case that an item that resided in the source variation label was moved out of the source label all relationships list entries for the variation group of the moved items will be recycled - means neither the item in the source label nor the items in the target labels are variation hierarchy items after the move.
In case that the move operation for an item in the target variation label went beyond the boundaries of its label the list item in the Relationships List is marked as deleted (Deleted column gets value Yes). This flag is used in combination of the setting, which controls whether to recreate deleted target items, or not.
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
That step is done by simply assigning a new Url to the ServerRelativeUrl property of the managed SPWeb object. The real move operation is performed as soon as the property change is committed using SPWeb.Update.
There is one special situation, which needs to be taken care of: that is the scenario where the site being moved is the top site of a variation label. As moving this site would invalidate the variation label such a move is not allowed.
The variation system hooks up to the following event to handle this:
WebMoving - This event fires before the actual move operation is performed within the COM layer.
The publishing feature has bound the Microsoft.SharePoint.Publishing.CPVAreaEventReceiver.WebMoving event receiver to this event, which checks if the site being moved is a variation top site and cancels the move operation in this case.
This operation is performed automatically in when changing the ServerRelativeUrl property of a site. That means that no special action has to be done to perform this link fixup.
Note: In case that the Variation Root site is not identical with the root site of the site collection it is possible to move the Variation Root site to a new location as well. The configuration setting for the variation root site will automatically be updates as it is stored as hyperlink in a list item in the Relationships List and will be adjusted through the same mechanism as other hyperlinks pointing to the site.
In case that a move operation went beyond the boundary of a variation label, additional operations are required as the moved site is no longer part of the previous variation group. To detect whether a move operation went beyond the boundary of a variation label we check the label the item is in before and after the move.
The variation system hooks up to the following event to handle this:
WebMoved - This event handler fires after the move operation has been completed.
The publishing feature has bound the Microsoft.SharePoint.Publishing.CPVAreaEventReceiver.WebMoved event receiver to this event which is responsible to maintain the relationships list references in case that the move operation moved a site out of a variation label. In this situation, the site is no longer a member of the previous variation group and the relationships list entries of the site and all child sites and child pages have to be deleted.
In case that a move operation moved a site, from outside the source label into the source label (as well from a target label and from a location outside the variation hierarchy), this event handler is responsible to mark the site as being a part of the source label and will also initiate the spawn of the moved site to the target labels.
Important: Moving a site out of the variation hierarchy - especially moving it out of the source label is a not reversible operation! As the Variation Group Id is removed from the site and all included sub sites and pages and as the relationships list entries are removed you cannot just move the site back to it's original location and assume that everything is back to normal.
If such a move is performed by accident it usually requires to restore a backup taken before the move operation to roll back the changes.
When a publishing page which resides in a target variation label is deleted it is important to mark its relationships list item as deleted to ensure that future update operations work correct and can either recreate the deleted item (if configured) or to allow a user to manually create a page variant in the label the deleted item resided in.
In case that a publishing page in the source variation label has been deleted it is necessary to recycle all relationships list entries for the variation group of the deleted page as these pages can no longer be updated after their source page has been deleted.
Delete operations for Publishing pages through the UI or through object model can either use the recycle bin (SPFile.Recycle method) or can be a final delete without a chance to recover the item (SPFile.Delete method). Both methods will raise the ItemDeleting and ItemDeleted events.
The variation system hooks up to the following events to maintain the relationships list items during a delete operation:
ItemDeleting - This event fires when the WSS object model is about to delete or recycles the page
The publishing feature has bound the Microsoft.SharePoint.Publishing.PagesListCPVEventReceiver.ItemDeleting event receiver to this event to gather the Variation Group Id from the page that is going to be deleted and make it available to the ItemDeleted event handler, which fires after the delete operation has been completed.
ItemDeleted - This event fires after the WSS object model has deleted the page
The publishing feature has bound the Microsoft.SharePoint.Publishing.PagesListCPVEventReceiver.ItemDeleted event receiver to this event, which is responsible to maintain the relationships list references for the deleted items.
In case that a page in the source variation label has been deleted, all relationships list entries for the variation group of the deleted item are recycled - means neither the item which was deleted in the source label nor the items in the target labels are variation hierarchy items after the delete.
In case that a page in a target label has been deleted, the list item in the Relationships List is marked as deleted (Deleted column set to Yes). This flag is used in combination of the setting, which controls whether to recreate deleted target items, or not.
In case of a restore operation it is necessary to ensure that the deleted status in its relationships list item is removed to ensure that future updates work correct and that a user cannot create a new page variant in the same label.
Important: Take special care when restoring a page in a target label. If the page has been moved to a different location before it got deleted and a new item has been recreated in the target label, you will end up with two pages in the same label for the same variation group.
This is not supported and can lead to exceptions.
The restore operation fires the ItemAdded event in the list where the restored item gets restored into.
The variation system hooks up to the following events to maintain the relationships list items during a delete operation:
ItemAdded - This event fires after the item has been successfully restored in the pages library
The publishing feature has bound the Microsoft.SharePoint.Publishing.PagesListCPVEventReceiver.ItemAdded event receiver to this event change the deleted status on the relationships list entries associated with the restored page, and also uses this event to restore the recycled relationships list entries of the variation group of the restored page, in case that the restored page resides in the source label.
When deleting a publishing site, which is part of the variation hierarchy, a couple of important checks and clean-up steps are required. For example, it is important to verify if the site is a mandatory site for the variations system and prevent the deletion in such situation.
In addition, the relationships list items referencing the deleted sites and the pages in these sites have to be deleted as well.
The variation system hooks up to the following event to fulfill this duty:
WebDeleting - This event fires for each site that is going to be deleted. In case that a site is deleted, which contains subsites, and then this event fires for each subsite as well. When performing the delete from within Site Manager the delete starts at the leaves - meaning, the deepest sites in the hierarchy are deleted first and the WebDeleting event for these leave sites fires first as well.
The publishing feature has bound the Microsoft.SharePoint.Publishing.CPVAreaEventReceiver.WebDeleting event receiver to this event which first checks if the site being deleted is the variation root site and cancels the delete in case that there are any spawned variation labels. If there are no spawned variation labels, the event handler removes the variation root site URL from the variation settings and allows the delete operation to continue.
The next thing checked is if the site being deleted is a variation top site of a variation label and cancels the delete in this case as the delete of the top site would invalidate the variation label
Important: As mentioned above the delete will start at the leaves when deleting the site in Site Manager. That means that all the child sites will already be gone when the event handler cancels the delete operation because it identifies that the site to be deleted is the top site of a label or the root site of the variation hierarchy.
In case, that the delete operation is valid the WebDeleting event handler cleans up the relationships list items for the site and all included pages.
Note: Unlike the delete operation for sites the cleanup of relationships list entries does not happen in the "after" event of the delete (WebDeleted) but in the "before" event. That means if the delete is not performed for whatever reason (e.g. because another event handler cancels the delete) you will end up with an inconsistent relationships list as the relationships list entries for the site and all it's pages is already gone.
The option to restore sites and site collections has been added with SharePoint 2010 Service Pack 1. Unfortunately the Variation Feature currently does not support this functionality which means that a site restore from the recycle bin will not be part of the variation hierarchy as the relationships list entries for the site and included pages will not be recreated.
Important: Similar to move operations which went beyond outside of a variation label it usually requires to restore a backup from before the site delete operation to roll back the changes.
You cannot just restore the site from the recycle bin as the relationships list entries will not be recreated.
From a variation perspective, the actions required when deleting a variation label are nearly identical to the actions performed when deleting a site: the variation top site and all its child sites and pages have to be removed from the relationships list recursively.
In addition to this step, the variation label itself has to be removed by deleting the list item representing the variation label in the variation labels list.
Deletion of a variation label is a synchronous operation, which is handled within the http request that initiated it.
The operation is not performed in a timer job and is not implemented as a long running operation, which would be executed on a separate thread.
The side effect of this limitation is that with large hierarchies it can happen that the operation takes more time than the standard request execution timeout (110 seconds).
In such a situation, the variation cleanup operation will not be completed successfully before ASP.NET terminates the http request.
Workaround: You can increase the execution timeout value by modifying the web.config file in the _layouts directory by adding the following details (36000 = 10 hours):
<configuration>
…
<location path="VariationLabels.aspx">
<system.web>
<httpRuntime executionTimeout="36000" />
</system.web>
</location>
…
<configuration>
You also should disable application pool recycling option while the label delete operation is executed.
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
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>]
In order to use the command correctly it is important to understand what the different operation modes do.
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
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.
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.
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 missing you cannot use the variations 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.
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.
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.
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.
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.
Each site collection can have a different logic for the redirection.
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.
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.
LabelMenuConfiguration="2"
Link to Top Site: using this operation mode the data source returns links to the top sites of peer labels.
LabelMenuConfiguration="3"
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.
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.
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.
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.
Each site collection can have a different logic for the redirection.
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>
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"%>
<cms:VariationDataSource id="LabelMenuDataSource" LabelMenuConfiguration="1" Filter="" runat="server"/>
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" /> --%>
<cms:VariationDataSource id="LabelMenuDataSource" LabelMenuConfiguration="1" Filter="" 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.
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 every page request or only if the user clicks the dropdown rendered by the menu.
See my previous post for more details and workaround of this problem.
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.
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
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:
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.
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
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
Check the Variation Log (see part 13 for details)
Check the ULS log for problems (see part 13 for the required categories)
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:
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. E.g. the following command dumps the information about the variation timerjobs for the web application on port 1007:
PS> (get-spwebapplication http://servername).JobDefinitions | where {$_.DisplayName -match "variation"} | select DisplayName, IsDisabled, LastRunTime, Schedule | fl
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 the history for all variation timerjobs for the web application on port 1007:
PS> (get-spwebapplication http://servername).JobHistoryEntries | where {$_.JobDefinitionTitle -match "variation"}
The following command dumps the history for the create hierarchies timer job:
PS> (get-spwebapplication http://servername).JobHistoryEntries | where {$_.JobDefinitionTitle -match "Variations Create Hierarchies Job Definition"}
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.
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 recommended to open a support case with Microsoft to do this type of troubleshooting on a production system.
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
Class : Microsoft.SharePoint.Publishing.PagesListCPVEventReceiver
Type : ItemUpdated
Class : Microsoft.SharePoint.Publishing.PagesListCPVEventReceiver
Type : ItemDeleted
Class : Microsoft.SharePoint.Publishing.PagesListCPVEventReceiver
Type : ItemCheckedIn
Class : Microsoft.SharePoint.Publishing.PagesListCPVEventReceiver
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
Class : Microsoft.SharePoint.Publishing.CPVAreaEventReceiver
Type : WebMoved
Class : Microsoft.SharePoint.Publishing.CPVAreaEventReceiver
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.
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.
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.aspx page layout 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.
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:
A user created a page in the source label (version 1.0)
The page was approved (version 1.0) which caused automatic propagation to the target where the page arrives as version 0.1
A translator worked on the page in the target label and approved it (Version 1.0)
In the source label someone changed something in the page (Version 1.1)
Later the page is approved again (version 2.0) which causes automatic replication to the target label (version 1.1)
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)
Another change is done on source but is not yet approved (version 3.1)
Now a translator starts to work on the page (version 1.2 and 1.3).
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?
The variation system keeps track about the last propagated page version in two different places:
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
When a new version is variated to the target label the variation system preserves the previous value of the PreviousSpawnSourcePageVersion 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 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.
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
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 translator to change/translate 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 marked as being translatable and those 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>
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 is performed with RetainObjectIdentity = true - which means that the items in the package will be imported with the same Guid and Url as they were exported. That means if you exported site1 and then select the import option in site2 the import will still be performed into site1. That also means that the import will fail if the items being imported have a different URL as before - e.g. because their Url name has changed or because the site was moved.
To allow automated translation of content SharePoint provides the export and import funcationality also through the ExportObjects and ImportObjects 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
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.
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.
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>
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.
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).
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.
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.
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.
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.
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.