Upgrading SharePoint Portal Server 2003 Customizations to SharePoint Server 2007 (Part 2 of 2)

  • Article

Summary: Learn to work with upgrade definition files, understand key elements and attributes, and walk through an annotated sample upgrade definition file so that you can perform an upgrade of Microsoft Office SharePoint Portal Server 2003 customizations to Microsoft Office SharePoint Server 2007. This article is part 2 of 2. (16 printed pages)

Microsoft Corporation

November 2007

Applies to: Microsoft Office SharePoint Server 2007, Windows SharePoint Services 3.0

Contents

  • Working with Upgrade Definition Files: Tools to Help You

  • Upgrade Process Overview

  • Step 1: Locate the Custom Site Definition to Upgrade

  • Step 2: Identify Customizations

  • Step 3: Select Upgrade Files and Copy All Files to Correct Folders

  • Step 4: Create an Upgrade Definition File

  • Drilling Down: Understanding the Upgrade Definition File

  • Elements and Attributes of the Upgrade Definition File

  • Annotated Walkthrough of the Sample Upgrade Definition File

  • Conclusion

  • Additional Resources

This article is a continuation of Upgrading SharePoint Portal Server 2003 Customizations to SharePoint Server 2007 (Part 1 of 2).

Working with Upgrade Definition Files: Tools to Help You

To work effectively with XML files as you upgrade your customizations in Windows SharePoint Services 2.0 or Microsoft Office SharePoint Portal Server 2003 to Windows SharePoint Services 3.0 or Microsoft Office SharePoint Server 2007, you need the right tools. We recommend the following tools for your use:

  • WinDiff, a tool provided with most Microsoft operating systems, can be used to compare files and find differences in them. Using WinDiff to compare the original (default) site definition files to current (custom) site definition files makes it easier to identify customizations and ensure that all customizations are accounted for.

  • Microsoft Office SharePoint Server 2007 Custom Templates and Mapping Files Worksheet can help you plan an upgrade and document customizations.

  • XML Notepad 2007 is a free download that provides a simple, intuitive user interface for browsing and editing XML documents (see Figure 3). Other third-party tools can also be purchased for the same purpose.

    Note

    One approach to working with site definitions and mapping files is to open three XML Notepad sessions: one showing the current schema (onet.xml), the second showing the mapping file (starting with one of the default upgrade files supplied by SharePoint Portal Server 2003), and the third showing the destination file (or base 3.0 site definition file).

    Figure 1. Onenet.xml in XML Notepad

    WSS 2.0 hive with custom areas

Upgrade Process Overview

After performing the following steps, you should be ready to perform a test upgrade:

  1. Locate custom site definitions to upgrade.

  2. Identify customizations in the current version of Windows SharePoint Services 2.0 or SharePoint Portal Server 2003.

  3. Select upgrade files, and then copy all files to the correct folders.

  4. Create an upgrade definition file.

Step 1: Locate the Custom Site Definition to Upgrade

In Windows SharePoint Services 3.0, custom site definitions are stored in the following path:

Local_drive:\Program Files\Common Files\Microsoft Shared\Web server extensions\60\TEMPLATE\1033\Area Name\XML

For comparison, in Microsoft Office SharePoint Server 2007, these same files are stored in a similar path. The only difference is the "12" in the SharePoint Server path instead of "60" in the Windows SharePoint Services path, as shown here:

%WinDir%\Program Files\Common Files\Microsoft Shared\Web server extensions\12\TEMPLATE\1033\

Table 1 lists default SharePoint template folders that you will almost always see (notice that most default SharePoint templates start with SPS), and what the folders map to.

Table 1. Template folders and mappings

Default SharePoint Template Folder

Maps To

SPS

Home

SPSBWEB

To create bucket Web sites

SPSCOMMU

Communities

SPSMSITE

Site registry

SPSNEWS

Subareas under News

SPSNHOME

News Home

SPSPERS

MySite

SPSTOC

Topics Home

SPSTOPIC

Topic

Other Template Folder

Maps To

GP

Great Plains (if installed)

MPS

Team Web site

STS

SharePoint Team Services

Other Folders

Maps To

XML

Site definition for the SharePoint organization

In Figure 2, the SPSORGANIZATION folder contains a custom site definition.

Figure 2. Windows SharePoint Services 2.0 hive with custom areas

Onet.xml in XML Notepad

Step 2: Identify Customizations

The most time-consuming step in the upgrade process may be identifying existing customizations and then deciding which customizations to upgrade, to migrate, and to discard, and then mapping those customizations to the Office SharePoint Server 2007 or Windows SharePoint Services 3.0 equivalents. This step is critical to a successful upgrade because it defines the post-upgrade environment.

Identify Customizations in the Current Implementation

In the SharePoint Server 2003 hive (also referred to as the 6.0 hive), you can use tools such as WinDiff or Beyond Compare to compare the existing site definition to the site definition that was originally used to create it. By comparing the original default template with the current template, you can identify customizations that were made and determine what you must map for a successful upgrade. For example, if the current site definition was originally based on the STS template, then you must compare the current site definition to the default STS template site definition. You can document these differences as a starting point for the upgrade and mapping.

This process can be challenging. Determining the template on which your site definition was originally based requires that you are familiar with the original site definitions. You will likely see entries and references in the current site definition that are similar to or that match those in the original template. For example, if the current site definition was based on the STS site template, many STS entries will appear in the current file. There is often a pattern for custom entries. Using Contoso as an example, many custom entries may start with "Contoso". Also, you can identify custom elements by looking for pages and graphics that match company branding, colors, and logos.

You can also use the WinDiff tool to compare the entire original directory with the current directory. This can help you to identify custom list definitions that were encapsulated in the site definition in Windows SharePoint Services 3.0 or SharePoint Portal Server 2003.

Examine Each Modified File to Determine If It Should Be Upgraded

Next, examine each file that has been modified to determine if it should be upgraded: either because it has been replaced by new built-in functionality in Windows SharePoint Services 3.0 or SharePoint Server 2007, or because the customization is no longer needed. Be sure to examine the following files and customization locations:

  • Onet.xml: This file is where the majority of changes occur. Examples of customizations include a Quick Launch bar that has been added to the site, Quick Launch options, or additional navigation such as an embedded navigation control.

  • Custom lists: Determine which custom lists should be "featurized" ("featurizing" custom lists is discussed in more detail later in this section). Base your decision to featurize a list on business reasons. If a list will be heavily reused, it should be made into a Feature in Windows SharePoint Services or SharePoint Server. In Windows SharePoint Services 2.0 and SharePoint Portal Server 2003, the primary reason for a list definition is to provide a template for creating similar lists. For Windows SharePoint Services 3.0 and Office SharePoint Server 2007, this kind of list should be upgraded to a Feature. Some upgrade specialists do not recommend featurizing lists during an upgrade to keep the upgrade process as simple as possible. In this case, any required list featurization is performed after the upgrade. Every organization must determine which approach is best for their needs.

  • Default.aspx: The goal for this file is to interrogate it, locate customizations, and determine how to preserve certain elements after the upgrade. Are there static Web Parts, zoneless Web Parts, or any HTML that has been added directly to default.aspx? These types of customizations will be lost because the default.aspx file is not parsed during the upgrade. Also, look for additional Web site zones. Three zones are preserved in the upgrade, but anything outside of these zones is placed in a single zone page—the equivalent of a lost-and-found page for Web Parts. To avoid this issue, add any statically assigned Web Parts to the new default.aspx file to match the existing zones. Before doing this, you must determine how many of these elements should be abstracted to the master page (and therefore how many would need to be accommodated in the page layout). If a portal site is being upgraded, there is an additional layer of complexity because portal sites are automatically converted to publishing sites. In these cases, it is up to each organization to determine what to preserve on the publishing site.

All identified customizations should be examined and referenced against the supportability article Supported and Unsupported Scenarios for Working with Custom Site Definitions and Custom Area Definitions in Windows SharePoint Services, in SharePoint Portal Server 2003, and in Office SharePoint Server 2007.

Considerations for Determining Whether to Keep a Customization

Consider the following when determining whether to keep a customization:

  • Do not upgrade Web parts that are no longer needed.

  • Some Web Parts cannot be upgraded. Attempts to upgrade these Web Parts will fail because, during the upgrade process, each Web Part is interrogated in an attempt to capture its data. If Web Parts do not support serialization or personalization, they might cause the upgrade to fail.

  • Some Microsoft Office FrontPage customizations create problems during an upgrade because they leave the upgraded site in V2 compatibility mode.

  • Consider removing customizations written for SharePoint Portal Server 2003 if SharePoint Server 2007 provides a default solution. For example, many organizations wrote in-house site membership Web Parts with SharePoint Portal Server 2003, and this functionality is provided by default with SharePoint Server 2007. Unfortunately, there is no way to "remap" the functionality of one Web Part with another, so during the upgrade you cannot replace Web Part X with Web Part Y. In this kind of situation, you should not upgrade Web Part X, and you should implement Web Part Y after the upgrade.

Step 3: Select Upgrade Files and Copy All Files to Correct Folders

After you locate the custom sites you want to upgrade, select the upgrade definition file that you will use to create a new site definition to replace the Windows SharePoint Services 2.0 or SharePoint Portal Server 2003 version in the "12" hive. Office SharePoint Server 2007 provides several upgrade templates that you can use as a starting point for creating the upgrade mapping file. You can find these in the following path:

C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\Config\Upgrade

Table 3. Default upgrade mapping templates

Upgrade Mapping Template Recommended Use

DLCUpgradeb2b.xml

Less common, and unlikely to be used.

IPFSUpgrade.xml

Less common, and unlikely to be used.

MPSUpgrade.xml

Microsoft Office Project Server. Less common; may be used if a custom project file definition has been implemented.

MSPUpgradeB2B.xml

Microsoft Office Project Server Build to Build. Less common; may be used if a custom project file definition has been implemented in a B-to-B scenario.

OSRVUpgrade.xml

Less common, and unlikely to be used.

OSSSearchUpgrade.xml

Less common. May be used by ISV organizations that have implemented search customizations.

SiteUpgraderConfigSPS.xml

Used to upgrade custom area definitions.

SPSUpgradeB2BPremium.xml

Build to Build; unlikely to be used for mapping.

WSSUpgrade.xml

Very common. May be used for the majority of upgrades.

WSSUpgradeB2B.xml

Less common.

SPSUpgrade.xml

Use this if you are moving to Microsoft Office SharePoint Server 2007 Standard Edition.

SPSUpgradePremium.xml

Use this if you are moving to Microsoft Office SharePoint Server 2007 Enterprise Edition.

Copy the selected upgrade definition file to the following path.

%WinDir%\Program Files\Common Files\Microsoft Shared\Web server extensions\12\TEMPLATE\SiteTemplates\

You can give the folder any name, provided that it does not contain spaces. This folder often has the same name in the new folder structure that it had in the old folder structure. After you copy the file, you can rename it to something that is meaningful in the context of the upgraded site. After this file is modified, it replaces the original Windows SharePoint Services 2.0 or SharePoint Portal Server 2003 site definition file.

Step 4: Create an Upgrade Definition File

The following example describes edits you must make to the definition file if you have a custom site definition named CONTOSO based on the default STS.

To begin building your upgrade mapping file

  1. Copy the file to the "12" hive at C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\CONFIG\UPGRADE.

  2. Rename the file to CONTOSOUpgrade.xml.

  3. Modify the CONTOSOUpgrade.xml file, which is also referred to as the Upgrade Definition File or UDF. At this point, the WSSUpgrade.xml file (now named CONTOSOUpgrade.xml) appears as follows (the <Lists> and <Files> attribute entries have been truncated to save space).

WSSUpgrade.xml, Unmodified

<?xml version="1.0" encoding="utf-8"?>
<Config xmlns="urn:Microsoft.SharePoint.Upgrade">
  <WebTemplate
    ID="1"
    LocaleId="*"
    FromProductVersion="2"
    BeginFromSchemaVersion="0"
    EndFromSchemaVersion="0"
    ToSchemaVersion="2">
    <Lists>
      <List
        FromTemplateId="104"
        ToFeatureId="00BFEA71-D1CE-42de-9C63-A44004CE0104" />
      <List
        FromTemplateId="105"
        ToFeatureId="00BFEA71-7E6D-4186-9BA8-C047AC750105" />
      <List
        FromTemplateId="100"
        ToFeatureId="00BFEA71-DE22-43B2-A848-C05709900100" />
  ...
    </Lists>
    <Files>
      <File
        FromPath="{LocaleId}\STS\default.aspx"
           ToPath=  "SiteTemplates\STS\default.aspx"/>
      <File
        FromPath="{LocaleId}\STS\Lists\announce\AllItems.aspx"
        ToPath=  "pages\viewpage.aspx"/>
      <File
        FromPath="{LocaleId}\STS\Lists\announce\DispForm.aspx"
        ToPath=  "pages\form.aspx"/>
  ... 
    </Files>
    <AppliedSiteFeatures>
      <FeatureId="00BFEA71-1C5E-4A24-B310-BA51C3EB7A57" />
    </AppliedSiteFeatures>
    <AppliedWebFeatures>
      <FeatureId="00BFEA71-4EA5-48D4-A4AD-7EA5C011ABE5" />
      <FeatureId="F41CC668-37E5-4743-B4A8-74D1DB3FD8A4" />
    </AppliedWebFeatures>
  </WebTemplate>
</Config>

  1. Modify the file by making these changes:

    • <WebTemplate ID="10001": You must modify the WebTemplate ID to match the site definition. In this case, the WebTemplate ID was 10001 for the site CONTOSO.

    • <Lists>: Where you turn lists into Features (featurize the lists). In this example, no changes are required.

Notes: About List IDs

You can find the list template ID in the Onet.xml file of the site definition from which it came. For example, ..\1033\CONTOSO\XML\onet.xml shows the following, and here the ListID is 502.

<ListTemplate Name="CONTOSO"
DisplayName="Contoso"
Type="502"
BaseType="0"
OnQuickLaunch="TRUE"
SecurityBits="11"
Description="Create a list for Contoso when you want to manage 
information about people that your team works with, such as customers 
or partners. You can share information between your contacts list and 
Windows SharePoint Services-compatible contacts programs."
Image="/_layouts/images/itcontct.gif">
</ListTemplate>

Notes: About Turning Custom Lists into Features

To save time, many organizations decide to upgrade lists rather than create Features from (featureize) them. However, we recommend that you consider turning lists into Features because it will provide more flexibility and enable you to use the new Features in multiple sites.

To turn a list into a Feature, you need a GUID for the Feature, which can often be supplied by the developer who created the list Feature. The GUID is not stored in any XML file. If you do not have the GUID, you can use the following workaround:

  1. Identify the list to map to a Feature.

  2. Create a Feature in SharePoint Server 2007. SharePoint Server 2007 automatically assigns a GUID to that Feature.

  3. Reference that GUID for the upgrade mapping file.

Note

Performance degradation sometimes occurs when content types are added as Features, so consider doing this sparingly.

Notes: About the Files Section

The From and To path in the file mapping portion of the upgrade definition file identifies the setup path in the database. The specified files are not moved. This is a mapping of the elements that were a part of the previous version to the SharePoint Server 2007 equivalent, so that after the upgrade, when users visit the site, they access the correct SharePoint Server 2007 files. Also be aware that while most elements and files are in the same location, the document template folder has moved to the global site definition. Adjust custom references to document templates in the <Files> section accordingly.

Remember that the upgrade definition file was only intended to do the following:

  1. Map list IDs to Feature IDs so that lists can be turned into Features (featurized).

  2. Remap a file path. In a site definition, you can define file modules and setup paths. Files can be mapped to a shared file or to a file that is now under a different location (due to a change from 60 [Windows SharePoint Services 2.0] to 12 [Windows SharePoint Services 3.0]).

  3. Activate Features on Web sites.

  4. Activate Features on site collections.

Drilling Down: Understanding the Upgrade Definition File

An upgrade definition file describes how to map a customized Windows SharePoint Services 2.0 site definition to a Windows SharePoint Services 3.0 site definition. It maps files, lists, libraries, and Features, and specifies the new Windows SharePoint 3.0 functionality to place in the upgraded site definition.

Upgrade definition files can be confusing. To clarify your understanding of upgrade definition files, the following section provides a sample file and walks you through the details of its elements and attributes.

XML Basics

To help you read an XML file, you need to know the following basic terminology:

  • Element: A unit of XML data, delimited by tags. An XML element can enclose other elements and is used to organize information in XML documents. For example, in the XML structure, "<Lists><List>...</List></Lists>", the Lists element contains one (and potentially many) List elements.

  • Attribute: A qualifier on an XML tag that provides additional information. For example, in the tag <FromTemplateId="104">, FromTemplateId is an attribute, and 104 is its value.

  • Beginning and ending elements and attributes: Elements and attributes begin with an opening tag, (for example, <NAME>) and end with a closing tag (for example, </NAME>).

Building an Upgrade Definition File

A site upgrade definition file provides a way to transform sites customized in the previous version of Windows SharePoint Services so that they take advantage of features in the new version. An upgrade definition file maps the files and list data of one build or version to a subsequent build or version, and specifies additional items that should be placed within upgraded Web sites.

You register an upgrade definition file for a site definition by giving it a unique file name, usually starting with the name of the site definition, and placing it in the folder of the setup directory. Site upgrade definitions are registered per site definition, but multiple upgrade definitions may exist for the same site definition. A site upgrade definition also includes list upgrade templates, which describe how the particular columns of a list map to content types in the new version of Windows SharePoint Services.

A good way to understand upgrade definitions is to study the upgrade definition files that are included in an installation of Windows SharePoint Services, which are located in the path C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\Config\Upgrade. The Upgrade directory includes two upgrade templates: one that upgrades from version 2 to version 3, and one that upgrades between builds from Beta 2 of Windows SharePoint Services to its final release version.

When you create an upgrade definition file, it must contain the following elements:

  • Config: Specifies the top-level element for the upgrade schema.

  • WebTemplate: Contains the template ID of the site template that you are upgrading.

  • Lists: Specifies how to upgrade existing lists and libraries in the site.

  • List: Specifies how to upgrade an existing list.

  • Files: Contains descriptions of the relationships between existing files and their equivalents for upgrading.

  • File: Describes the relationship between an existing file and its equivalent for upgrading.

  • Applied SiteFeatures: Specifies a list of Features to map to equivalent Features for site collections created through the new version of Windows SharePoint Services.

  • Applied WebFeatures: Specifies a list of Features to map to equivalent Features for subsites that are created by using the new version of Windows SharePoint Services.

For additional detailed information about upgrade definition files, see Upgrade Definition Files and Upgrade Definition Schema in the Windows SharePoint Services 3.0 SDK.

Sample Upgrade Definition File

The following is an example of an upgrade definition file. For an explanation of the key elements (noted in bold), see Elements and Attributes of the Upgrade Definition File.

<Config xmlns="urn:Microsoft.SharePoint.Upgrade">
  <WebTemplate
    ID="1"
    LocaleId="*"
    FromProductVersion="2"
    BeginFromSchemaVersion="100"
    EndFromSchemaVersion="149"
    ToSchemaVersion="150">
  <Lists>
    <List
      FromTemplateId="104"
      ToFeatureId="00BFEA71-D1CE-42de-9C63-A44004CE0104"
      v3Type="0x0104">
    </List>
    <List
      FromTemplateId="105"
      ToFeatureId="00BFEA71-7E6D-4186-9BA8-C047AC750105"
      v3Type="0x0105">
      <Source v2List="105" />
    </List>
  </Lists>
  <Files>
    <File
      FromPath="{LocaleId}\STS\default.aspx"
      ToPath=  "SiteTemplates\STS\default.aspx">
    </File>
    <File
      FromPath="{LocaleId}\STS\Lists\announce\AllItems.aspx"
      ToPath=  "Features\AnnouncementsList\announce\AllItems.aspx">
    </File>
    <File
      FromPath="{LocaleId}\STS\Lists\announce\DispForm.aspx"
      ToPath=  "Features\AnnouncementsList\announce\DispForm.aspx">
    </File>
    <File
      FromPath="{LocaleId}\STS\Lists\announce\EditForm.aspx" 
      ToPath=  "Features\AnnouncementsList\announce\EditForm.aspx">
    </File>
    <File
      FromPath="{LocaleId}\STS\Lists\announce\NewForm.aspx"
      ToPath=  "Features\AnnouncementsList\announce\NewForm.aspx">
    </File>
  </Files>
  <AppliedSiteFeatures>
    <Feature ID="00BFEA71-1C5E-4A24-B310-BA51C3EB7A57" />
  </AppliedSiteFeatures>
  <AppliedWebFeatures>
    <Feature ID="00BFEA71-D1CE-42de-9C63-A44004CE0104" />
    <Feature ID="00BFEA71-7E6D-4186-9BA8-C047AC750105" />
    <Feature ID="00BFEA71-DE22-43B2-A848-C05709900100" />
  </AppliedWebFeatures>
  </WebTemplate>
</Config>

Elements and Attributes of the Upgrade Definition File

Config Element (Upgrade)

Specifies the top-level containing element for the upgrade definition.

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

Attributes

Attribute Description

xmlns

Specifies the Windows SharePoint Services Upgrade namespace: urn:Microsoft.SharePoint.Upgrade

Child Elements

WebTemplate

WebTemplate Element (Upgrade)

Contains the site template upgrade definition.

<WebTemplate

BeginFromSchemaVersion = "Integer"

EndFromSchemaVersion = "Integer"

FromProductVersion = "Integer"

ID = "Integer"

LocaleId = "Integer"

RemoveSiteExternalSecurityProvider = "TRUE | "FALSE"

ToSchemaVersion = "Integer">

...

<Lists>

Attributes

Attribute Description

BeginFromSchemaVersion

Optional Integer. Specifies the start of a schema version range to which this upgrade definition applies.

EndFromSchemaVersion

Optional Integer. Specifies the end of a schema version range to which this upgrade definition applies.

FromProductVersion

Optional Integer. Specifies the product version of the original site definition to which this upgrade definition applies.

ID

Required Integer. Specifies a unique identifier for the upgrade definition.

LocaleId

Optional Integer. Specifies the locales to which the site upgrade definition applies. Set to * to imply that the definition applies to all site definition upgrades. Windows SharePoint Services implements only one upgrade definition per locale. If * is specified and a locale-specific upgrade definition exists, Windows SharePoint Services uses the locale-specific upgrade definition. If the locale-specific definition does not exist, Windows SharePoint Services defaults to the * upgrade definition.

RemoveSiteExternalSecurityProvider

Optional Boolean. TRUE to exclude any external security provider from the upgrade; otherwise, FALSE.

ToSchemaVersion

Optional Integer. Specifies the product version to which the site definition is upgraded.

Child Elements

AppliedSiteFeatures, AppliedWebFeatures, Files, Lists

Lists Element (Upgrade)

Contains definitions for how existing lists should be upgraded on a list template-by-list template basis.

Attributes

None.

Child Elements

List

List Element (Upgrade)

Specifies how an existing list should be upgraded.

<List

FromTemplateId = "Integer"

ToFeatureId = "GUID"

v3Type = "Integer">

</List>

Attributes

Attribute Description

FromTemplateId

Required Integer. Specifies the list definition to be upgraded.

ToFeatureId

Required GUID. Specifies the ID of the content type feature to which the old list definition is upgraded.

v3Type

Required Integer. Specifies the content type ID to which the old list definition is upgraded. Example: v3Type="0x0104"

Source Element (Upgrade)

<Source v2List = "String"> </Source >

Attributes

Attribute Description

v2List

String

Files Element

Contains descriptions of the relationships between existing provisioned files and their equivalents for upgrading to a new version of Windows SharePoint Services.

Child Element

File Element (Upgrade)

Describes the relationship between an existing provisioned file to its equivalent for upgrading to a new version of Windows SharePoint Services, specifying how setup paths of files in the previous version map to setup paths in the new version relative to the \60\Template and \12\Template directories respectively.

<File

FromPath = "String"

ToPath = "String">

</File>

Attributes

Attribute Description

FromPath

Required String. Specifies the setup path of the file to be upgraded relative to the \Program Files\Common Files\Microsoft Shared\web server extensions\60\TEMPLATE directory. Use the token {LocaleId} to specify a locale identifier as part of the path.

Example:

FromPath="{LocaleId}\STS\Lists\announce\EditForm.aspx"

ToPath

Required String. Specifies the location in the setup directory of the file to which the file of the old version is mapped relative to the \Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE directory. Example:

ToPath= "Features\AnnouncementsList\announce\EditForm.aspx"

AppliedSiteFeatures Element (Upgrade)

Supplies a list of site collection Features to be marked as "provisioned" for site collections created through the new version of Windows SharePoint Services. For example, an announcements list template of the previous version must be mapped to its equivalent announcements Feature in the new version.

Note

All Features must have GUIDs.

<AppliedSiteFeatures>

<Feature

ID = "GUID"

Force = "TRUE" | "FALSE" />

</AppliedSiteFeatures>

Feature Element (Upgrade)

Specifies a Feature to be marked as "provisioned" for Web sites or site collections created through the new version of Windows SharePoint Services.

<Feature

ID = "GUID"

Force = "TRUE" | "FALSE"/>

Attributes

Attribute Description

Force

Optional Boolean. TRUE if the Feature is installed by force during upgrade even if the feature is already installed; otherwise, FALSE.

ID

Required GUID. Specifies the ID of the Feature.

AppliedWebFeatures Element (Upgrade)

Supplies a list of Web site Features to be marked as "provisioned" for Web sites created through the new version of Windows SharePoint Services. For example, an announcements list template of the previous version must be mapped to its equivalent announcements Feature in the new version.

<AppliedWebFeatures>

<Feature

ID = "GUID"

Force = "TRUE" | "FALSE" />

</AppliedWebFeatures>

Note

All features must have a GUID.

Feature Element (Upgrade)

Specifies a Feature to be marked as "provisioned" for Web sites or site collections created through the new version of Windows SharePoint Services.

<Feature

ID = "GUID"

Force = "TRUE" | "FALSE"/>

Attribute Description

Force

Optional Boolean. TRUE if the Feature is installed by force during upgrade even if the Feature is already installed; otherwise, FALSE.

ID

Required GUID. Specifies the ID of the Feature.

Annotated Walkthrough of the Sample Upgrade Definition File

The following sample upgrade definition file is annotated to walk you through key elements and attributes (noted in bold).

<Config xmlns="urn:Microsoft.SharePoint.Upgrade">
<!-- WebTemplate - Contains site template upgrade information.
ID - Contains unique integer for every upgrade definition.
LocalID - Determines the upgrade file to use during an upgrade; the 
setting of "*" means this upgrade definition can be used unless a 
locale-specific upgrade exists.-->
  <WebTemplate 
    ID="1"
    LocaleId="*"
    <!-- FromProductVersion - When determining if a site can be 
    upgraded, the following algorithm is used to choose an upgrade
    definition file:
    1. If the Web site is not running on the latest product version,
    Windows SharePoint Services chooses an upgrade definition file 
    that updates the site to the latest schema version. Upgrade 
    definitions can upgrade across versions, or across schemas, but 
    not both, which means that a definition cannot have both the 
    FromProductVersion and BeginFromSchemaVersion/EndFromSchemaVersion
    attributes set. If no upgrade definition can be found to upgrade 
    the Web site across versions, the Web site cannot be upgraded.
    2. If Number 1 does not apply, an upgrade definition file is chosen
    such that the value of the ToSchemaVersion attribute most closely 
    matches the current schema version of the site definition (without
    surpassing it), and the schema version of the existing site 
    instance falls in the range between BeginFromSchemaVersion and 
    EndFromSchemaVersion.
    3. If more than one site upgrade definition passes the criteria 
    of Number 2, the upgrade definition with the highest 
    BeginFromSchemaVersion value is chosen.
    4. If there is both a generic language and a specific locale 
    template for a given site definition, Windows SharePoint Services 
    chooses the specific locale template.-->
    FromProductVersion="2"
    BeginFromSchemaVersion="100"
    EndFromSchemaVersion="149"
    ToSchemaVersion="150">
  <!--Lists element contains information about how to upgrade
  existing lists.-->
  <Lists>
    <!--List element defines how to upgrade a specific list.-->
    <List
    <!--FromTemplateId specifies type of list from previous 
    SharePoint version.
    ToFeatureId is the GUID of the content type feature that the list
    is being upgraded to (maps to a feature ID defined in the 
    AppliedWebFeatures element).
    V3Type is content type ID to which the old list is upgraded. -->
      FromTemplateId="104"
      ToFeatureId="00BFEA71-D1CE-42de-9C63-A44004CE0104"
      v3Type="0x0104">
      <Source v2List="104" />
    </List>
    <!-- List element attributes here are the same as above.-->
    <List
      FromTemplateId="105"
      <!-- ToFeatureId maps to a Feature ID defined in the 
      AppliedWebFeatures element.-->
      ToFeatureId="00BFEA71-7E6D-4186-9BA8-C047AC750105"
      v3Type="0x0105">
      <Source v2List="105" />
    </List>
    ...
  </Lists>
  <!--Files element contains descriptions of relationships between
  existing provisioned files and their equivalents for upgrading to a 
  new version.-->
  <Files>
    <File
      <!--FromPath is the relative path of the file to upgrade.
      Notice that {LocaleId} is used instead of the default full path
      (\Program Files\Common Files\Microsoft Shared\web server 
      extensions\60\TEMPLATE).
      ToPath is location in the setup directory of the file to which 
      the file of the old version is mapped, relative to the 
      \Program Files\Common Files\Microsoft Shared\web server 
      extensions\12\TEMPLATE directory.-->
      FromPath="{LocaleId}\STS\default.aspx"
      ToPath=  "SiteTemplates\STS\default.aspx" />
    <File
      FromPath="{LocaleId}\STS\Lists\announce\AllItems.aspx"
      ToPath=  "Features\AnnouncementsList\announce\AllItems.aspx" />
    <File
      FromPath="{LocaleId}\STS\Lists\announce\DispForm.aspx"
      ToPath=  "Features\AnnouncementsList\announce\DispForm.aspx" />
    <File
      FromPath="{LocaleId}\STS\Lists\announce\EditForm.aspx" 
      ToPath=  "Features\AnnouncementsList\announce\EditForm.aspx"/>
    <File
      FromPath="{LocaleId}\STS\Lists\announce\NewForm.aspx"
      ToPath=  "Features\AnnouncementsList\announce\NewForm.aspx" />
    ...
  </Files>
  <!--AppliedSiteFeatures element is a list of site collection 
  features to mark as "provisioned" for site collections created. 
  For example, an announcements list template of the previous version
  must be mapped to its equivalent announcements feature in the new 
  version.-->
  <AppliedSiteFeatures>
    <!--Feature ID element is a feature to mark as "provisioned" for 
    Web sites or site collections created through the new version.-->
    <Feature ID="00BFEA71-1C5E-4A24-B310-BA51C3EB7A57" />
  </AppliedSiteFeatures>
  <!--AppliedWebFeatures element is a list of Web site features to 
  mark as "provisioned" for Web sites created through the new version
  of Windows SharePoint Services. For example, an announcements list 
  template of the previous version must be mapped to its equivalent 
  announcements Feature in the new version. -->
  <AppliedWebFeatures>
    <!--Feature ID element specifies a Feature to mark as "provisioned" 
    for Web sites or site collections created through the new version.
    Note: The first feature ID maps to the first upgraded list. The 
    second feature ID maps to the second upgraded list.-->
    <Feature ID="00BFEA71-D1CE-42de-9C63-A44004CE0104" />
    <Feature ID="00BFEA71-7E6D-4186-9BA8-C047AC750105" />
    <Feature ID="00BFEA71-DE22-43B2-A848-C05709900100" />
    ...
  </AppliedWebFeatures>
  </WebTemplate>
</Config>

Conclusion

The third generation of Microsoft SharePoint Products and Technologies introduces new functionality and enhancements that help organizations collaborate and access business intelligence. Microsoft Office SharePoint Server 2007 greatly streamlines the business process, but the deployment process requires the administrator to plan ahead, especially when performing the upgrade from Microsoft Office SharePoint Portal Server 2003. This article provides the information needed to perform the upgrade in an environment customized from the base installation of SharePoint Portal Server 2003.

Additional Resources

For more information, see the following resources:

2007 Microsoft Office System

Microsoft SharePoint Products and Technologies

Upgrade Solutions from Microsoft SharePoint Partners