Microsoft SharePoint Team Blog

How to Upgrade an Area based on a Custom Site Definition

[Updated: Added ImageUrl attribute for step 1b.  Thanks, Michael!]

This post outlines the extra steps needed to upgrade a Sharepoint Portal Server 2003 (SPS) area.  First, some background information which explains why these extra steps are needed.  (For simplicity in this post I may refer to WSS 2.0 and SPS 2003 as v2 with MOSS 2007 and WSS 3.0 as v3).

The SPS 2003 area feature is built on top of Windows Sharepoint Server 2.0 (WSS 2.0) site feature.  An SPS area, in a nut shell, is just a DB row with a backing WSS site. A SPS area as a whole provides many additional functionalities on top of a WSS site, but as far as WSS is concerned, the area backing web is just another WSS site based on a custom site definition. 

WSS can’t fully upgrade a site created from a custom site definition without additional information since it doesn’t know the full extent of the customization made.  So, we need to provide an upgrade definition file in order to upgrade a custom WSS site.  Upgrading an SPS area is not much different.  Since SPS knows how it has derived the SPS area definitions (SPS, SPSTOC, SPSTOPIC etc.) from the WSS team site definition, the SPS upgrade process can provide the upgrade definition file to WSS. 

A custom SPS area, derived from one of the out-of-the-box area definitions, contains two sets of customizations as it appears to WSS, one made by SPS, and one made by the end user.  In order to upgrade a custom area created from a custom area definition we would have to provide an upgrade definition file that tells WSS how to upgrade both sets of customizations.   As we will see later, we are going to derive our custom upgrade definition file from the upgrade definition of the stock area which we used to create our custom area definition in v2.

The Microsoft Office Sharepoint Server 2007 (MOSS) publishing site that a v2 SPS area is upgrading into isn’t just the next incarnation of the area feature.  It really is a whole new concept with many exciting functionalities.  Let’s go over a couple that have upgrade implications.  Though the concept of “ghosted” page still exists underneath the cover, it has been largely made irrelevant in MOSS due to the page layout feature.  Instead of having all the code in the actual aspx page, a v3 (2007) publishing page refers to a layout page which in turn can have a .Net master page.  What people typically consider as the “Chrome” or “Navigation” section of the page is in the .master page.  The rest of the page, such as field controls and webpart zones, goes into the layout page.  The actual field data are store with the publishing page.  Webpart associations are also based on the actual publishing page.  The layout page is essentially the template for the publishing pages. (More about page layout and master page in MOSS 2007)  We would have many publishing pages that are based on only a limited numbers of layout pages.  We would not normally modify a publishing page directly.  In fact, there isn’t much to modify.  Crack open the source of a publishing page, all we see is a single code behind reference to the page assembly that takes care of the whole page layout magic:

<%@ Page Inherits="Microsoft.SharePoint.Publishing.TemplateRedirectionPage, Microsoft.SharePoint.Publishing, Version=12.0.0.0, Culture=neutral, PublicKeyToken=xxxx" %>

So, we really don’t care if the actual publishing page itself is ghosted or not since it will just have that one line of code in either case.  We just need to tweak and maintain the handful of page layouts.  As we will see later, we will need to modify a config file to specify a page layout for the welcome page of our custom areas as part of upgrade.         

The upgrade process allows us to specify whether to reghost unghosted pages during upgrade.  Neither choice is perfect.  We either lose customization made on the unghosted pages or we end up with a page that doesn’t incorporate all of the v3 features and worse yet perpetuate these unghosted pages and make our life harder managing them in v3.  We will have to make the call depending on what is more important to us.  Every deployment is different.  As we will see later, there is something better we can do for unghosted welcome pages. 

Remember the C1, C2, etc placeholders in v2 SPS URL’s?  They were there to separate the logical area navigation hierarchy from the physical area backing web hierarchy.  WSS v2 had some limitations when it comes to moving a site.  This separation in logical and physical hierarchy essentially allowed the support for area moves after creation.  These limitations no longer exist in WSS v3, so these placeholders are removed as part of the upgrade process.  Upgrade takes care of fixing most of the internal URL breaks as a result.  For the rest and external URL’s there is a redirect service.

Comparing a v2 area site definition at “%SystemDrive%\Program Files\Common Files\Microsoft Shared\web server extensions\60\TEMPLATE\<lcid>\SPSTOPIC” and the corresponding v3 one at “%SystemDrive%\Common Files\Microsoft Shared Debug\Web Server Extensions\60\TEMPLATE\SiteTemplates\SPSTOPIC,” we immediately notice that the “Lists” folder is gone.  In fact, there is only a very short “default.aspx” file containing the above mentioned code behind line and an “onet.xml” file under the “xml” folder.  Instead of having the list definitions duplicated in each area site definition, they have been turned into features.  Check under the “%SystemDrive%\Program Files\Common Files\Microsoft Shared Debug\Web Server Extensions\12\TEMPLATE\FEATURES” directory to see the list features among many other new v3 features.  If we have defined custom list in v2, we might want to think about converting them into features as well.  That way they can be used in any site instead of being bound to a particular site definition.  If we do decide to featurize our list definition, then we will need to modify the upgrade definition file to tell WSS how to upgrade our existing lists into our new feature.  Also, notice that the site definitions are no longer language specific.  This is reflected in the upgrade definition file as well.

Now, finally we can move onto the steps.  Keep in mind these are just the ones specifically related to upgrading custom areas.  All the rest of the portal upgrade steps still apply.  Also, make sure to have backups before attempting to upgrade.  Trying the upgrade process on a test server first is also highly recommended. 

We are going to assume we have a v2 custom area template at “%SystemDrive%\Program Files\Common Files\Microsoft Shared\web server extensions\60\TEMPLATE\<lcid>\SPSCUSTOM” with an ID of 10001 which was created based on the SPSTOPIC template.  There are five major steps.  Four of them we do after binary step up and before the actual upgrade process, and the last one we do after upgrade has completed successfully.

1.       We need a webtemp xml file to map our area template name to our area template ID.  This is the only place WSS looks for site template name and ID association.  We should already have this file in v2.  We can just move that file straight over to “%SystemDrive%\Program Files\Common Files\Microsoft Shared Debug\Web Server Extensions\12\TEMPLATE\<lcid>\XML” in v3.  It is best if we created our own webtemp file instead of modifying one of the out-of-the-box ones, so just in case, here are the steps to creating a new one:

a.       Create a file called webtemp*.xml (i.e. webtempcust.xml) in the above mentioned directory.

b.      Add the following xml into that file:

<?xml version="1.0" encoding="utf-8"?>

<Templates xmlns:ows="Microsoft SharePoint">

    <Template Name=" SPSCUSTOM " ID="10001">

       <Configuration ID="0" Title="Custom Area Template" Type="0" Hidden="TRUE" ImageUrl="../images/spshome.gif" Description="This is a custom area template."/>

    </Template>   

</Templates>

Notice the Hidden=”TRUE” attribute.  Quite a few of the top reasons to create a custom template in v2 are no longer valid.  Enforcing UI consistency is now done through .Net master page and the page layout feature.  We don’t need custom template to create custom list definitions now since lists are factored out of individual site templates and into features.  So, chances are we really don’t want our users to create sites out of these templates anymore.  They are really just there as an upgrade vehicle. 

2.       We need to create the v3 equivalent of the v2 area definition.  We are assuming our v2 template was created by copying and modifying the SPSTOPIC template, so we can do the same to create our v3 custom template as well. 

a.       Navigate to “%SystemDrive%\Program Files\Common Files\Microsoft Shared Debug\Web Server Extensions\12\TEMPLATE\SiteTemplates” directory.

b.      Copy the SPSTOPIC template and rename the copy to SPSCUSTOM. 

c.       We can then apply the same customization we did in v2 to this newly created custom template.  Obviously, we will need reapply the customization in a v3 compatible way.  If we have any custom list we want to featurize.  Now is a good time to do that as well.

3.       In order to take advantage of the page layout feature, we will need to specify which layout page to use for our area welcome pages.  Crack open the “SiteUpgraderConfigSPS.xml” file under the “%SystemDrive%\Program Files\Common Files\Microsoft Shared Debug\Web Server Extensions\12\CONFIG\UPGRADE\” directory.  Here is what the file looks like:

<?xml version='1.0'?>

<SPSSiteUpgraderConfig>

    <PublishingPageLayoutMappings>

        <PublishingPageLayoutMapping WebTemplateId="20" PublishingPageLayout="/_catalogs/masterpage/defaultlayout.aspx"/>

        <PublishingPageLayoutMapping WebTemplateId="22" PublishingPageLayout="/_catalogs/masterpage/welcomelayout2.aspx"/>

        <PublishingPageLayoutMapping WebTemplateId="30" PublishingPageLayout="/_catalogs/masterpage/welcomelayout2.aspx"/>

        <PublishingPageLayoutMapping WebTemplateId="31" PublishingPageLayout="/_catalogs/masterpage/welcomelayout2.aspx"/>

        <PublishingPageLayoutMapping WebTemplateId="32" PublishingPageLayout="/_catalogs/masterpage/welcomelayout2.aspx"/>

        <PublishingPageLayoutMapping WebTemplateId="33" PublishingPageLayout="/_catalogs/masterpage/newshomelayout.aspx"/>

        <PublishingPageLayoutMapping WebTemplateId="34" PublishingPageLayout="/_catalogs/masterpage/welcomelayout2.aspx"/>

        <PublishingPageLayoutMapping WebTemplateId="36" PublishingPageLayout="/_catalogs/masterpage/welcomelayout2.aspx"/>

    </PublishingPageLayoutMappings>

</SPSSiteUpgraderConfig>

We are going to add another PublishingPageLayoutMapping entry under the PublishingPageLayoutMappings node:

<PublishingPageLayoutMapping WebTemplateId="10001" PublishingPageLayout="/_catalogs/masterpage/customlayout.aspx"/>

We are basically saying that for all welcome pages in areas created using our custom area template with ID of 10001, use customlayout.aspx as the page layout.  Customlayout is just an example; we could use any name we want as long as it is unique within the page layout gallery.  This layout page can be structured anyway we want.  If our goal is to duplicate our v2 look and feel exactly, we can just take our v2 default.aspx page, added the v3 webpart manager control  (<WebPartPages:SPWebPartManager id="m" runat="Server" /> ), and use that as our layout page.  Obviously we are going to miss out on some of the v3 features since our v2 UI would not expose them. 

The recommended way to create the layout page is to copy an out-of-the-box v3 layout page and modify the copy to suit our needs.  A good layout page to copy is located at “%SystemDrive%\Program Files\Common Files\Microsoft Shared Debug\Web Server Extensions\12\TEMPLATE\FEATURES\PortalLayouts\welcomelayout2.aspx.”  Make sure the webzone ID’s stay the same as in v2, or we will end up with webparts in the wrong zone or moved off to the page gallery after upgrade.

If we unghosted our v2 welcome pages to apply a consistent UI using FrontPage, why not upgrade the UI changes into the page layout feature which is meant to do just that.  Inspect all the unghosted pages (prescan will list all of them).  Try and see if we can divide all the customizations into a few layout types.  Create those layout pages, and map area templates to layout pages using the SiteUpgraderConfigSPS.xml file.  Then upgrade with the reghost option enabled.  This does require our customizations to match nicely with area definitions since we can only specify page layout per area template definition ID.  However, if we can get the majority of them correct, we can always come back in and manually tweak the page layout of a few welcome pages after upgrade.

So, where do these new custom page layouts go?  Well, since we haven’t even started the upgrade, the page layout gallery hasn’t been created yet.  Hang on to these layouts, and we will upload them in step five.

4.       Now, it is time to finally create our upgrade definition file.  Creating this file can be as easy as searching and replacing a few strings depending on the type of customizations we did to our custom area template.

An upgrade definition file can have multiple <WebTemplate> nodes with each outlining how to upgrade sites created from a particular site template.  Since we created our custom area template from the SPSTOPIC template (ID=31), we will use this WebTemplate as our starting point:

a.       Open the SPSUpgradePremium.xml file (or SPSUpgrade.xml depending on our SKU) under “%SystemDrive%\Program Files\Common Files\Microsoft Shared Debug\Web Server Extensions\12\CONFIG\UPGRADE” directory and locate the < WebTemplate> node with ID=31.

b.      Create an xml file in the same directory with any name and add the following xml text to the file:

<?xml version="1.0" encoding="utf-8"?>

<Config xmlns="urn:Microsoft.SharePoint.Upgrade">

</Config>

c.       Copy the entire ID=31 <WebTemplate> from SPSUpgradePremium.xml to our new file under the <Config> node.

d.      Change ID to 10001 and replace the text SPSTOPIC with SPSCUSTOM.

It is recommended that we don’t modify the existing upgrade definition file and create our own instead.  Modifying any existing upgrade definition file is not supported and will cause problems when installing patches.

There are four sub-nodes in a WebTemplate node:

<Lists>: maps a list ID to the corresponding list feature ID.  If we featurized any of our v2 custom list, we need to add an entry here.

<Files>: maps an old setup path (ghost path) to the new one.  For example, our area template has moved from a directory under an lcid to a global directory, thus we need the following entry to tell upgrade how to fix the setup path:

<File FromPath="{LocaleId}\SPSCUSTOM\default.aspx" ToPath="SiteTemplates\SPSCUSTOM\default.aspx" />

Also, our lists definitions have been moved out of site definitions and their support files moved to a global directory as well, that is why we need entries like the following:

<File FromPath="{LocaleId}\SPSCUSTOM\Lists\announce\AllItems.aspx" ToPath="pages\viewpage.aspx" />

We will need to add one entry for each custom file that has its setup path moved.

<AppliedSiteFeatures>: This one is only useful if our custom template can be used to create the root site in a site collection.  Since SPS v2 does not allow custom home area template, this one is irrelevant for upgrade.

<AppliedWebFeatures>: Allows us to specify what features to turn on for areas created using our custom template during upgrade.  The features with their ID’s already listed here are all required for upgrade to work correctly.  We can add any additional one as  needed.

5.       Once upgrade has finished successfully, navigate to “master page and page layouts” gallery at http://<servername>/_catalogs/masterpage/Forms/AllItems.aspx and click on the “Upload” button in the toolbar to upload the page layouts created in step three above.

Guest Post: Boxin Li, Dev, SharePoint Product Team.