upgrading share point portal server 2003 customizations to share point server 2007 (parts 1 & 2)

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

Summary: Learn the requirements to perform an upgrade of Microsoft Office SharePoint Portal Server 2003

customizations to Microsoft Office SharePoint Server 2007. This article contains parts 1 & 2.

Microsoft Corporation

November 2007

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

Contents

Introduction to Upgrading SharePoint Customizations

New SharePoint Concepts and Terminology

Feature Introduction

Determining the Upgrade Approach

Determining How to Handle Customizations

Deprecated APIs That Require Action

Upgrading Customized Features Within SharePoint Products and Technologies

Running the Pre-Upgrade Scan Tool

Creating Upgrade Definition Files

Upgrading Custom Site Definitions

Upgrading Custom Site Templates

Upgrading Areas and Listings

Upgrading Areas Based on Custom Site Definitions

Upgrading List Definitions

Upgrading Customized (Unghosted) Pages

Upgrading Custom Web Parts

Upgrading Custom Event Handlers

Upgrading Custom Themes and Style Sheets

Upgrading Custom Code or Pages in Layouts Folders

Inclusions or Exclusions

Upgrading Third-Party Customizations

Conclusion

Additional Resources

http://msdn.microsoft.com/en-us/library/bb954662.aspx#MOSS2007UpgradeCustomizationsP1_IntroductiontoUpgradingSharePointCustomizations

http://msdn.microsoft.com/en-us/library/bb954662.aspx#MOSS2007UpgradeCustomizationsP1_NewSharePointConceptsandTerminology

http://msdn.microsoft.com/en-us/library/bb954662.aspx#MOSS2007UpgradeCustomizationsP1_FeatureIntroduction

http://msdn.microsoft.com/en-us/library/bb954662.aspx#MOSS2007UpgradeCustomizationsP1_DeterminingtheUpgradeApproach

http://msdn.microsoft.com/en-us/library/bb954662.aspx#MOSS2007UpgradeCustomizationsP1_DeterminingHowtoHandleCustomizations

http://msdn.microsoft.com/en-us/library/bb954662.aspx#MOSS2007UpgradeCustomizationsP1_DeprecatedAPIsthatRequireAction

http://msdn.microsoft.com/en-us/library/bb954662.aspx#MOSS2007UpgradeCustomizationsP1_UpgradingCustomizedFeatureswithinSharePoint

http://msdn.microsoft.com/en-us/library/bb954662.aspx#MOSS2007UpgradeCustomizationsP1_RunningthePreUpgradeScanTool

http://msdn.microsoft.com/en-us/library/bb954662.aspx#MOSS2007UpgradeCustomizationsP1_CreatingUpgradeDefinitionFiles

http://msdn.microsoft.com/en-us/library/bb954662.aspx#MOSS2007UpgradeCustomizationsP1_UpgradingCustomSiteDefinitions

http://msdn.microsoft.com/en-us/library/bb954662.aspx#MOSS2007UpgradeCustomizationsP1_UpgradingCustomSiteTemplates

http://msdn.microsoft.com/en-us/library/bb954662.aspx#MOSS2007UpgradeCustomizationsP1_UpgradingAreasandListings

http://msdn.microsoft.com/en-us/library/bb954662.aspx#MOSS2007UpgradeCustomizationsP1_UpgradingAreasBasedonCustomSiteDefinitions

http://msdn.microsoft.com/en-us/library/bb954662.aspx#MOSS2007UpgradeCustomizationsP1_UpgradingListDefinitions

http://msdn.microsoft.com/en-us/library/bb954662.aspx#MOSS2007UpgradeCustomizationsP1_UpgradingCustomizedUnghostedPages

http://msdn.microsoft.com/en-us/library/bb954662.aspx#MOSS2007UpgradeCustomizationsP1_UpgradingCustomWebParts

http://msdn.microsoft.com/en-us/library/bb954662.aspx#MOSS2007UpgradeCustomizationsP1_UpgradingCustomEventHandlers

http://msdn.microsoft.com/en-us/library/bb954662.aspx#MOSS2007UpgradeCustomizationsP1_UpgradingCustomThemesandStyleSheets

http://msdn.microsoft.com/en-us/library/bb954662.aspx#MOSS2007UpgradeCustomizationsP1_UpgradingCustomCodeorPagesinLayoutsFolders

http://msdn.microsoft.com/en-us/library/bb954662.aspx#MOSS2007UpgradeCustomizationsP1_InclusionsorExclusions

http://msdn.microsoft.com/en-us/library/bb954662.aspx#MOSS2007UpgradeCustomizationsP1_UpgradingThirdPartyCustomizations

http://msdn.microsoft.com/en-us/library/bb954662.aspx#MOSS2007UpgradeCustomizationsP1_Conclusion

http://msdn.microsoft.com/en-us/library/bb954662.aspx#MOSS2007UpgradeCustomizationsP1_AdditionalResources

Introduction to Upgrading SharePoint Customizations

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

planning on the part of the SharePoint administrator, especially when performing the upgrade from Microsoft Office

SharePoint Portal Server 2003. This article provides the information required to perform the upgrade in an

environment that has been customized, either slightly or significantly, from the base installation of SharePoint

Portal Server 2003.

The upgrade process is not as simple as inserting a CD and running Setup. You need to carefully plan your

approach, anticipate issues that might come up during or after the process, and consider your specific

environment—especially when working with customized SharePoint sites and applications.

Because the upgrade process itself is documented on the SharePoint Server TechCenter on TechNet, the main

focus of this article is how to identify customizations, what you should know before beginning the upgrade, and

how to successfully upgrade customizations.

New SharePoint Concepts and Terminology

Microsoft Office SharePoint Server 2007 introduces new functionality and enhancements that help IT professionals

deploy and maintain Office SharePoint Server 2007 solutions. Together, these new enhancements provide IT

organizations with better control over information resources; individually these enhancements provide functional

benefits that help reduce administrative overhead and help IT administrators work more efficiently and effectively.

Changes that affect IT organizations and IT professionals include:

An improved administration model that centralizes configuration and management tasks, and helps IT

organizations delineate and delegate administrative roles.

New and improved compliance features and capabilities that help organizations secure resources and

manage business-critical processes.

New and improved operational tools and capabilities that drive down the total cost of ownership (TCO).

Improved support for network configuration.

Improved extensibility of the SharePoint object model that helps to make custom applications and

components easier to deploy and manage.

These changes mean that some of the ways that you are used to working with your sites and pages might not work

or might not be the most effective. The following tables can help you understand some of the key changes to

terminology and functionality that immediately affect the administration and site management process after

upgrading. For more information about changes to Office SharePoint Server 2007, see What's New for IT

Professionals in Office SharePoint Server 2007.

Table 1 lists updated or new concepts and terminology that reflect the new architecture and design of Office

SharePoint Server 2007.

Table 1. Mapping terminology of SharePoint Portal Server 2003 to SharePoint Server 2007

SharePoint Portal Server 2003 Concept or Term

Office SharePoint Server 2007 Concept or Term Comments

http://www.microsoft.com/technet/prodtechnol/office/sharepoint/default.mspx

http://technet2.microsoft.com/Office/en-us/library/527763c3-90a5-4d3b-9781-fc9580314a2d1033.mspx

http://technet2.microsoft.com/Office/en-us/library/527763c3-90a5-4d3b-9781-fc9580314a2d1033.mspx

Virtual server Web application Change in terminology.

Shared services Shared Services Providers

The architecture behind shared services has changed significantly, to allow easier and more flexible sharing of resources. For more information, see Plan Shared Services Providers.

Areas Sites SharePoint Portal Server 2003 areas are upgraded to sites that use the Publishing Site Template. To manage your site, on the Site Actions menu, click Manage Content and Structure.

Portal security Windows SharePoint Services security

Portal security is now managed by using the new Windows SharePoint Services 3.0 security model. Groups and users are upgraded to this model. For more information about the new security model, see Plan Site and Content Security (Office SharePoint Server).

Custom authentication

New authentication choices

You can now use ASP.NET authentication methods, such as forms authentication, with Office SharePoint Server 2007 instead of creating a completely custom authentication solution. For more information, see Plan Authentication Methods (Office SharePoint Server).

Rights management

Now available for documents stored in document libraries.

SharePoint Portal Server 2003 backward-compatible document libraries

Office SharePoint Server 2007 document libraries

SharePoint Portal Server 2003 backward-compatible document libraries are not supported for Office SharePoint Server 2007. You can move any content stored in these libraries into standard document libraries in Office SharePoint Server 2007. A tool for migrating this content is under development. For more information, see Perform Post-Upgrade Steps for a Gradual Upgrade (Office SharePoint Server) or Perform Post-Upgrade Steps for an In-Place Upgrade (Office SharePoint Server).

Feature Introduction

Windows SharePoint Services 3.0 introduces an inherently portable and modular functionality known as a Feature,

which simplifies modifying sites through site definitions. A Feature is a package of Windows SharePoint Services

elements that you can activate for a specific scope, and that helps users accomplish a particular goal or task.

Working with Features

Features reduce the complexity involved in making simple site customizations, and are robust when upgrades are

applied to a deployment. Features eliminate the need to copy large chunks of code to change simple functionality.

As a result, Features reduce versioning and inconsistency issues that may arise among front-end Web servers.

Features make it easier to activate or deactivate functionality during a deployment, and administrators can easily

transform the template or definition of a site by simply toggling a particular Feature on or off in the user interface.

Features provide the following capabilities:

Scoping semantics for determining where custom code runs

Pluggable behavior for installing or uninstalling Features within a deployment

Pluggable behavior for activating or deactivating Features at a given scope

A scoped property bag for storing data required by a Feature within its scope

http://technet2.microsoft.com/Office/en-us/library/cce2f987-3949-44be-8057-663b38fc949d1033.mspx

http://technet2.microsoft.com/Office/en-us/library/cce2f987-3949-44be-8057-663b38fc949d1033.mspx

http://technet2.microsoft.com/Office/en-us/library/85a1866e-2743-4f98-a1ac-9ea61905c6d41033.mspx

http://technet2.microsoft.com/Office/en-us/library/85a1866e-2743-4f98-a1ac-9ea61905c6d41033.mspx

http://technet2.microsoft.com/Office/en-us/library/40117fda-70a0-4e3d-8cd3-0def768da16c1033.mspx

http://technet2.microsoft.com/Office/en-us/library/40117fda-70a0-4e3d-8cd3-0def768da16c1033.mspx

http://technet2.microsoft.com/Office/en-us/library/63f1755d-6d6d-4554-adce-c259fe346acc1033.mspx



http://technet2.microsoft.com/Office/en-us/library/7d4d75f0-fe37-4ade-809e-d68c730a07451033.mspx

http://technet2.microsoft.com/Office/en-us/library/7d4d75f0-fe37-4ade-809e-d68c730a07451033.mspx

The basis of a unified framework for distributed deployment of Windows SharePoint Services solutions

To implement a Feature, you add a subfolder containing a Feature definition within the Features setup directory

(Local_Drive:\Program Files\Common Files\Microsoft Shared\web server

extensions\12\TEMPLATE\FEATURES). The Feature subfolder includes a Feature.xml file that defines the

base properties of the Feature and lists elements bound to it, such as XML files containing element manifests and

any other supporting files. A Feature folder may contain only a Feature.xml file, or it may contain a Feature.xml file

and any number of supporting element files, including XML files, but also .aspx, .htm, .xsn, .resx, .dll, and other

file types.

Note:

If you create a folder within the Features directory through Windows Explorer by right-clicking a folder, pointing to New, and then clicking Folder, the new folder does not have inherited permissions. If you deploy a Feature in the folder, some Windows SharePoint Services pages (such as pages for site settings or list views) throw an exception. You can fix this problem by right-clicking the new folder, clicking Properties, clicking Security, and then clicking Advanced. On the Permissions tab, delete uninherited permissions from the folder. You can also fix this problem by creating the new folder at the command prompt through the md command.

After creating the Feature folder, you can install and activate the Feature through command-line operations of

stsadm.exe, or through the SharePoint object model. You can also activate a Feature through the user interface.

Installing a Feature makes its definition and elements known throughout a server farm, and activating the Feature

makes the feature available at a particular scope.

The Feature element is used in a Feature.xml file to define a Feature and to specify the location of assemblies,

files, dependencies, or properties that support the Feature. A Feature includes a Feature.xml file and any number

of files describing individual elements. Another Feature element from a different schema is used in an Onet.xml file

to specify that a Feature be activated within a site definition.

Items that were previously contained within a large site definition file are broken out as separate elements within

Features. An element is an atomic unit within a Feature. A Feature.xml file typically points to one or more XML files

whose top-level <Elements> tag contains definitions for elements that support the Feature. Elements in Windows

SharePoint Services 3.0 often correspond to what were discrete nodes in the Onet.xml or Schema.xml file of the

previous version. There are several types of element—for example, a custom menu item or an event handler.

A Feature could provide, for example, a "My Favorite Items" functionality that includes the following elements:

A custom list that stores, per user, a list of favorite items, which is created as a single hidden list per

workspace when the Feature is enabled

A custom menu item that is attached to all lists, named "Add to Favorites," which adds an item to the

Favorites list

A Web Part that implements usage data and link tracking to display the user's top 10 favorites at the top

of a page

Each element of the Feature might not be very useful by itself, but when you enable the Feature on a site, all these

elements add up to a complete solution.

Feature Stapling in Windows SharePoint Services 3.0

In Windows SharePoint Services 2.0, many of the customizations that organizations wanted required changes to

the built-in site definitions. These types of customization were not supported by Microsoft because these files may

need to be replaced by future service packs. To work around this limitation with the site definitions, you would

copy the built-in definitions, make the required customizations, and hide the original definitions from the end user.

This process would ensure that a service pack would not break the site definition.

In SharePoint Server 2007, Features enable you to turn functionality on and off within a site, even if the

functionality was not in the original site definition. Although modifying the built-in site definitions is still not

advisable or supported, you can use a process named Feature Stapling to attach a Feature to a site definition

without modifying it in any way. For example, you can use this process to attach your custom application to the

built-in definition.

To create a staple, you actually create another Feature that does the staple. Following is an excerpt from a

SharePoint staple Feature we use to staple a Multilanguage Feature to the STS, BDR, and SPS site definitions.

Feature.xml file

Xml

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

<Feature Id="82E2EA42-39E2-4B27-8631-ED54C1CFC491"

Title="$Resources:MultiLangStaplingFeatureName"

Description="$Resources:MultiLangstaplingFeatureDescription"

Version="12.0.0.0"

Scope="Farm"

xmlns="http://schemas.microsoft.com/sharepoint/"

DefaultResourceFile="_Res">

<ElementManifests>

<ElementManifest Location="TransMgmtFunc.xml"/>

</ElementManifests>

</Feature>

TransMgmtFunc.xml file that contains the FeatureSiteTemplateAssociation element

Xml

Copy Code <Elements xmlns="http://schemas.microsoft.com/sharepoint/">

<FeatureSiteTemplateAssociation Id="29D85C25-170C-4df9-A641-

12DB0B9D4130" TemplateName="STS#0" />


12DB0B9D4130" TemplateName="STS#1" />


12DB0B9D4130" TemplateName="BDR#0" />


12DB0B9D4130" TemplateName="SPS#0" />

</Elements>

The preceding code "staples" the Feature with the ID "29D85C25-170C-4df9-A641-12DB0B9D4130" to the STS#0,

STS#1, BDR#0, and SPS#0 site definitions. This is very powerful because it enables you to add functionality to site

definitions without modifying the site definitions. To staple your Feature to all site definitions, you can staple it to

the GLOBAL site definition, and it will be added to all sites that are created.

For more information, see Chris Johnson's blog post Feature Stapling in WSS V3, and the Microsoft SharePoint

Products and Technologies Team Blog entry Customizing MOSS 2007 My Sites Within the Enterprise.

Determining the Upgrade Approach

Before you run any upgrade process, you must determine which upgrade approach to take. You can follow one of

several paths, depending on the needs of your organization. An in-place upgrade is used to upgrade all SharePoint

sites at one time, which is best suited for very limited, single-server deployments or small deployments. In

production, the in-place upgrade is suggested only for testing purposes, either in a separate test environment or by

using a virtual network. The virtual in-place upgrade provides you with the ability to quickly roll back changes

made during the upgrade through the use of undo disks.

For almost all upgrades, the gradual upgrade is the best path. A gradual upgrade allows finer control of the

upgrade process by allowing one or more site collections to be upgraded at a time. The level of control offered by

the gradual upgrade approach makes it the most desirable option for almost all environments. Both in-place and

gradual upgrades take place on the same hardware on which your previous version is installed. A gradual upgrade

is a better option than an in-place upgrade because it enables the administrator performing the upgrade to control

how many site collections to upgrade at one time. In this way, large deployments can be upgraded gradually over

several weekends while continuing to host the previous version sites. This is possible because you can continue to

host the sites that are not yet upgraded on the same server as the upgraded sites.

If you are performing a gradual upgrade in a shared services environment, you can choose between two options:

Upgrade the parent portal site first (recommended) or you can upgrade the child portal sites first, by

using a new shared services provider. When performing this type of upgrade, you must follow specific

steps (for guidance, see Perform a Gradual Upgrade with Shared Services).

Migrate the lists and libraries from your Windows SharePoint Services 2.0 or SharePoint Portal Server

2003 environment to Windows SharePoint Services 3.0 or SharePoint Server 2007. This may also be an

option when migrating from platforms such as Lotus Notes or Domino, collaborative shares, or

collaborative public folders. This content migration upgrade approach simply copies the data into the new

environment, dropping the UI and customizations. The migration API is built into the product allowing for

a fairly flexible method of pushing content in and setting the appropriate metadata columns.

If you are either moving to new hardware or redesigning and restructuring your deployment, you can migrate your

databases from the old version to the new version rather than directly upgrading them. When you perform a

database migration, you perform an in-place upgrade on the databases, but you do not upgrade your server farm

configuration data. Although this upgrade path has more manual steps than either an in-place or a gradual

upgrade, it can be the best option if you have highly customized sites or custom Web services or applications. For

information about database migration, see Chapter Overview: Deploy a New Farm, Then Migrate Databases (Office

SharePoint Server 2007) on Microsoft TechNet.

If your organization has a significant amount of data to migrate, then a multithreaded database attach method can

provide you with a quicker and potentially more flexible path than the gradual approach and the basic database

migration. In the multithreaded approach, you create two or more front-end Web/query/index servers with a

http://blogs.msdn.com/cjohnson/archive/2006/11/01/feature-stapling-in-wss-v3.aspx

http://blogs.msdn.com/sharepoint/archive/2007/03/22/customizing-moss-2007-my-sites-within-the-enterprise.aspx

http://technet2.microsoft.com/Office/en-us/library/a44147be-3658-4bf0-ae39-0fca0794c01b1033.mspx

http://technet2.microsoft.com/Office/en-us/library/ba3cdb4d-a498-40a4-b3be-4363df3f19671033.mspx

http://technet2.microsoft.com/Office/en-us/library/ba3cdb4d-a498-40a4-b3be-4363df3f19671033.mspx

common SQL Server environment. You can find information about this approach on Bill Baer's blog on Microsoft

TechNet.

If your environment is highly customized, you might want to get back to an environment that is more supportable

or easier to upgrade by purposely removing some of the customization. The approach of migrating and then

upgrading will serve that purpose. Basically, you migrate your customized environment into a clean Windows

SharePoint Services 2.0 or SharePoint Portal Server 2003 environment, and then use the stsadm backup and

restore commands to migrate the site collections into a clean database with a built-in file system and _layouts

folder. This reduces the customization and overhead of the upgrade, and you can focus on running one of the three

simple upgrades: in-place, gradual, or database migration. With this approach, you can focus on using many of the

built-in features available in Windows SharePoint Services 3.0 and SharePoint Server 2007 that were not available

in the earlier versions.

Table 2. Comparison of upgrade approaches

Approach Description Advantages Disadvantages Best for

In-place upgrade

Upgrades the content and configuration data in place, at one time.

Sites retain original URLs. Updates existing databases and servers by using existing hardware.

Environment is offline while it runs. No ability to revert to original site. Limited capability for all but smallest deployments. Unable to manage customizations. Often fails, not recommended for inexperienced administrators.

Single-server or small server farm. Suggested for testing purposes only (see virtual in-place upgrade).

Virtual in-place upgrade

Upgrades the content and configuration data in place within a virtualized environment.

Easy to rollback changes by using undo disks. No need for the physical hardware.

Timely trial-and-error process.

Single-server or small server farm. Suggested as a preferred alternative to regular in-place upgrade.

Gradual upgrade (recommended)

Installs the new version side-by-side with the previous version. The server administrator determines which site collections to upgrade and when to upgrade them.

Enables a more granular approach: You can upgrade at the site collection level. Reduces the amount of time any single user is affected. Sites retain original URLs. Can revert to original site. Uses existing hardware.

More complex and resource-intensive. Must redirect URLs during upgrade process, which causes issues for some client applications such as Microsoft Office. Requires extra storage in Microsoft SQL Server. Microsoft Windows SharePoint Services 2.0 scalable hosting mode is not supported.

Medium or large server farms (without shared services) with many sites for which you must limit downtime. Good when your environment has many customizations.

Gradual The same as Same as gradual Same as gradual Server farm of any

http://blogs.technet.com/wbaer/

upgrade for shared services

gradual upgrade but with separate upgrade passes to upgrade parent portal sites and child portal sites.

upgrade, but allows you to upgrade parent and child portal sites individually.

upgrade, plus: Two search crawls are active at the same time for the SharePoint Portal Server 2003 and SharePoint Server 2007 environments.

size with shared services.

Content migration

Only migrate lists and libraries from the Windows SharePoint Services 2.0 or SharePoint Portal Server 2003 environment to SharePoint Server 2007.

Supported by migration partners such as AvePoint, DocAve, and Tzunami Deployer.

Loses any customizations to the environment.

Situations where the content is important, but the customized templates are expendable.

Database migration (advanced)

Requires the server administrator to install the new version on a separate farm or separate hardware, and then manually migrate the databases into the new environment.

Enables moving to new farm or new hardware. SharePoint Portal Server 2003 environment is available and is untouched by upgrade.

Complex process that requires many manual steps and involves a higher risk of error. Requires additional manual steps to retain original URLs for sites. Search scopes must be re-created and search settings must be reapplied. Requires new server farm, and twice the amount of SQL Server storage space.

Those who are moving to new hardware or a new architecture. Those who need to maximize upgrade throughput. This approach is required for Windows SharePoint Services 2.0 environments that use scalable hosting mode or Active Directory directory service account creation mode.

Multithreaded database attach

Database migration approach, but creating two or more front-end Web/query/index servers in the SQL Server environment.

Multiple threads of data reduce the amount of time required to transfer data between the databases.

Same drawbacks as Database Migration. Advanced setup steps required.

Environments requiring a Database Migration approach with large amounts of data to migrate.

Migrate then upgrade

Migrates data into a clean Windows SharePoint Services 2.0 or SharePoint Portal Server 2003 environment (losing the existing customizations), and then upgrades the deployment.

Brings the environment from a highly customized, difficult to support configuration to a more manageable, built-in configuration.

Any customizations required by the organization must be re-created.

Environments with a very high level of customization, which creates a deployment that is difficult to manage and support.

Additional information and suggestions about choosing an upgrade path are available on Joel Oleson's SharePoint

Land blog.

http://blogs.msdn.com/joelo/archive/tags/Upgrade/default.aspx

http://blogs.msdn.com/joelo/archive/tags/Upgrade/default.aspx

Determining How to Handle Customizations

If you have extensively customized your SharePoint Portal Server 2003 sites (by using Microsoft Office FrontPage

2003), you need to determine how to handle your customized sites when you upgrade. Your approach will vary

based on the extent of the customizations, the complexity of your site, and your goals for upgrading. You can

choose to keep the customizations, throw out the customizations, or redo the customizations:

Throw Out the Customizations

If you are planning a complete site redesign, or if you are significantly changing the information architecture, then

the upgrade is your chance to start over with a new look or a new organization. There are two ways to throw out

your customizations and start with a fresh site:

Upgrade (either in-place or gradual) and reset all pages to use the default pages from the site

definition. After an in-place upgrade, use Microsoft Office SharePoint Designer 2007 to reattach the

default page layouts. For more information, see Building tylerbutler.com, Part 4:The Main Home Page and

Migrating Content.

For a gradual upgrade, use the upgrade option to reset the entire Web site to use the site definition

pages. With this approach, you can start with the new look and functionality, and then decide whether to

customize the site again. Site owners can reapply customizations when they review the upgraded sites.

Note:

If you added a completely custom page to your site (for example, if you replaced default.aspx with a different file rather than making changes to the existing default.aspx file), that page has no association with the site definition and cannot be reattached to the page layout. If you want your custom page to have the same look and feel as the other pages in your site, consider creating a page based on the site definition and transferring your content to that new page.

Start fresh with a new site in the new environment. This approach works when you are dramatically

redesigning your site and you do not need to have either the structure or most of the content in the new

site. Create a new site, create a new site design, and transfer your content into the new site. This is not

an upgrade path, but rather an opportunity to design your new site from the beginning. For a list of

Microsoft SharePoint Partners that can help in this process, see Additional Resources.

Keep the Customizations

Although this approach allows you to keep the same look and feel, you are not able to take advantage of the new

capabilities available in the new version. This approach is generally discouraged because it results in mismatched

SharePoint 2007 pages, which can result in confusion. If you really want your pages to look just as they did, there

are three ways to keep the customizations:

Do an in-place upgrade. By default, an in-place upgrade preserves customizations and does not reset to

the site definition. Some controls, such as the Site Actions menu, might not be available in your

upgraded site.

Do a gradual upgrade, and keep the site in the previous version environment (do not upgrade

the site). This maintains the site exactly as it is, with the previous version functionality only. This is

usually a short-term solution, because most organizations do not want to support both versions over the

long term.

Do a gradual upgrade and upgrade the site, but do not reset any pages to the site definition.

This approach might result in an uneven look if you did not customize every page. Customized pages

http://blogs.msdn.com/ecm/archive/2006/12/11/building-tylerbutler-com-part-4-the-main-home-page-and-migrating-content.aspx

http://blogs.msdn.com/ecm/archive/2006/12/11/building-tylerbutler-com-part-4-the-main-home-page-and-migrating-content.aspx


retain the previous version's look and functionality, and pages that are not customized have the new

version's look and functionality. Some controls, such as the Site Actions menu, breadcrumbs, and the

new navigation, will not be available in your customized pages.

Note:

By default, custom pages are kept as is after upgrade (except for themes).

Redo the Customizations

This approach allows you to take advantage of the new capabilities, modify your design slightly if you want, and

move to a more manageable design. You can take advantage of the new master pages model to apply your design,

rather than customizing each individual page. Converting customized landing pages to use page layouts instead

also reduces future maintenance costs, because you can simply change the page layouts rather than changing each

individual page. There are three ways to redo the customizations:

Do an in-place or gradual upgrade and do not reset the pages to the site definition version.

After upgrade, modify the appropriate master pages and page layouts in the upgraded site to take on the

previous version's look and feel, and then reattach the page layouts to all customized pages. This gives all

formerly customized landing pages the same look as the site before upgrade. You can incorporate the new

controls, such as the Site Actions menu, into your new page layouts as part of this work.

Do an in-place upgrade and do not reset the pages to the site definition. After upgrade, open

the site and copy the customizations, then reattach the page layouts and reapply your

customizations to the master pages and page layouts, as appropriate. By default, an in-place

upgrade preserves customizations and does not reset the pages to the site definition version. When you

open the site by using a Web page editor compatible with SharePoint Server 2007, such as Microsoft

Office SharePoint Designer 2007, you can copy the customizations and then reset the original pages to get

the new functionality. Then you can reapply any customizations to the master pages and page layouts that

still make sense. Doing this process with an in-place upgrade is somewhat complicated because you need

to copy the customized pages before resetting them. Consider using the following gradual upgrade

method instead.

Note:

If you perform an in-place upgrade, you cannot revert to the previous version of the site. To have the previous version and the new version of the site side by side so that you can transfer customizations from the previous version site to the new version site, use a gradual upgrade—or, if you are performing an in-place upgrade, ensure that you first create a copy on another server or server farm that is running the previous version.

Do a gradual upgrade and, in the upgraded site, reattach the page layout. Then transfer the

customizations from your original site to the master pages and page layouts in the upgraded site by using

Office SharePoint Designer 2007. This option provides you with the most flexibility. Because you can refer

to the original site, you can see exactly how you did the previous customizations. And because you

reattached the page layouts, you can see the new functionality and decide which customizations to

reapply to the master pages and page layouts and which to ignore.

For more information about reapplying customizations after upgrade, see Reapply Customizations in the

Browser and Microsoft Office SharePoint Designer 2007 and Reset a Customized Page to the Site

Definition.

http://technet2.microsoft.com/Office/en-us/library/da3e6cbb-a478-4c7a-ae5a-4560c62206681033.mspx

http://technet2.microsoft.com/Office/en-us/library/da3e6cbb-a478-4c7a-ae5a-4560c62206681033.mspx

http://office.microsoft.com/en-us/sharepointdesigner/HA101741451033.aspx


To determine which Windows SharePoint Services 2.0 customized site templates are deployed and used within the

organization, you must use the pre-upgrade scan tool to scan your Windows SharePoint Services 2.0 environment.

Running the pre-upgrade scan tool is part of the Windows SharePoint Services 3.0 upgrade process and is

described in Running the Pre-Upgrade Scan Tool.

Using the pre-upgrade scan tool, you must scan your sites, and then fix any errors before you perform the

upgrade. If you have not successfully run this tool before you attempt to upgrade your environment, when you do

run the SharePoint Products and Technologies Configuration wizard, it will exit and prompt you to run the scan

tool.

Deprecated APIs That Require Action

All object model changes in Office SharePoint Server 2007 were made with strong consideration for backward-

compatibility with SharePoint Portal Server 2003. So even though you may encounter a completely redesigned area

of the object model, such as areas, your code should work. You should be aware, however, that your earlier code,

although functional, might not perform in the way you expect in the new object-model hierarchy.

If you upgrade applications that use deprecated classes or members, and when you write new applications, you

must use the new classes or members in the applications for them to work properly in Office SharePoint Server

2007. For a lists of the APIs that are deprecated in Office SharePoint Server 2007 either because of the

introduction of a new feature or enhancements in an existing feature, see SharePoint Portal Server 2003 APIs

Deprecated in Office SharePoint Server 2007 and SharePoint Portal Server 2003 APIs That Do Not Work in Office

SharePoint Server 2007.

Upgrading Customized Features Within SharePoint Products and Technologies

Organizations with a large investment in SharePoint Products and Technologies are recipients of significant

innovations in the enterprise collaboration and portal capabilities. More often than not, as the implementation has

grown, so has the significant customization of Windows SharePoint Services 2.0 and SharePoint Portal Server 2003

to achieve organization goals.

Some organizations have consciously practiced a controlled growth model. In those, administrators who are well-

versed and trained in SharePoint Portal Server design, architecture, and best practices have also been able to apply

design and usage guidelines to enable all areas of the organization to benefit. Conversely, organizations that have

not devoted resources to tightly manage and plan the SharePoint Portal Server infrastructure must often handle

multiple unwanted management effects. These include the uncontrolled propagation of sites and portals,

inconsistent security models and access right delegation (for example, everyone is an administrator), stale or aging

portals that are no longer used, and other aspects of uncontrolled usage and growth.

Regardless of the growth model within the organization, the migration to SharePoint Server is one that requires

organizations to completely understand their SharePoint Portal Server environments. For the latest information

about this topic, see Governance Information for SharePoint Server 2007 on Microsoft TechNet.

The second part of this two-part article ( Upgrading SharePoint Portal Server 2003 Customizations to SharePoint

Server 2007 (Part 2 of 2)) focuses on how to address individual customizations to each part of the SharePoint

Products and Technologies architecture, including templates, site definitions, Web Parts, event handlers,

customized (unghosted) pages, themes, style sheets, custom code or pages, inclusions, exclusions, and third-party

customizations. In each section, we discuss the issues, suggest upgrade paths, and provide links to additional

information about how to address the customization during the upgrade. For specific information about how to

prepare for and to execute the actual upgrade process, see Upgrading to Office SharePoint Server 2007 on

Microsoft TechNet.

http://msdn.microsoft.com/en-us/library/bb954662.aspx#MOSS2007UpgradeCustomizationsP1_RunningthePreUpgradeScanTool

http://msdn.microsoft.com/en-us/library/ms545807.aspx


http://technet.microsoft.com/en-us/sharepointserver/bb507202.aspx

http://msdn.microsoft.com/en-us/library/bb954661.aspx


http://technet2.microsoft.com/Office/en-us/library/396c85d9-4b86-484e-9cc5-f6c4d725c5781033.mspx

Running the Pre-Upgrade Scan Tool

Before you perform an upgrade, you must use the pre-upgrade scan tool (prescan.exe) to scan your sites and then

you must fix any errors. If you do not successfully run this tool and you attempt to upgrade your environment,

when you attempt to run the SharePoint Products and Technologies Configuration wizard, the wizard will exit and

prompt you to run the tool. We highly recommend that the server administrator run the pre-upgrade scan tool

before the upgrade, and resolve any problems that can be resolved before scheduling the upgrade.

Note:

You might need to run the pre-upgrade scan tool more than once. For example, if you run the tool to evaluate your server farm but you are not going to be performing the upgrade for a few weeks, you must run the tool again just before you perform the upgrade to scan any new sites and to ensure that no additional issues have appeared. Also, after you resolve any issues from your first scan, you must run the tool again; otherwise, when you try to run the SharePoint Products and Technologies Configuration wizard, you might see an error message that pre-scan has not been run.

For each SharePoint site, issues reported by this tool include the existence of the following objects:

Customized site templates. You must know which site templates are customized for a particular site so

that you can verify the customizations again after the upgrade.

Orphaned objects. Objects such as list items, lists, documents, Web sites, and site collections can be

orphaned—that is, the objects exist but are not associated with a particular site. Because orphaned

objects do not work in the previous version, they will not work after the upgrade. If you perform an in-

place upgrade, the orphaned items still exist but do not work. If you perform a gradual upgrade, orphaned

items are not copied to the new site. We recommend that you clean up any orphaned objects before

upgrading.

Note:

Members of the Administrators group on the front-end Web servers can recover orphaned items before the upgrade by following the steps in Knowledge Base article 918744, Description of a New Command-Line Operation That You Can Use to Repair Content Databases in Windows SharePoint Services.

Custom Web Parts. Report the existence of custom Web Parts to the appropriate site administrator or

developer before upgrading, to give the administrator or developer time to investigate. Heavily obfuscated

custom Web Parts might need to be rebuilt and redeployed after the upgrade.

Sites that are based on languages or that use controls that are not installed. If the database

contains a Web site based on a language template pack that is not currently installed on the front-end

Web servers, or a Web site uses controls (such as the Microsoft Office Web Components) that are not

currently installed on the front-end Web servers, install the missing language packs or controls before

upgrading.

Figure 1 shows a segment of a summary file. It shows the site template, Board of Directors—Basic, and lists all of

the pages in the site template. A customized page is denoted by the unghostedPage element at the beginning of

the URL tag for the page. A site is customized if one or more of its pages are customized (unghosted).

Figure 1. Sample of a summary file

http://support.microsoft.com/kb/918744


Use the information gathered from the pre-upgrade scan tool to determine:

Whether to perform an in-place upgrade or a gradual upgrade.

Upgrade approach. Office SharePoint Server provides information to help you decide which type of

upgrade to perform. It is important to consider the report generated by the pre-upgrade scan tool when

making this decision. Generally, if you find significant issues, use a gradual upgrade rather than an in-

place upgrade so that you can resolve the issues.

Whether to upgrade some or all site collections that contain customized sites.

Which sites need to have customizations reapplied or redone after upgrade and therefore might take

longer than others in the review stage.

Important:

After you run the pre-upgrade scan tool, the metadata for all lists and libraries is updated for your sites; however, the dates for individual list items and documents do not change during this process.

To install the prescan.exe tool, first install SharePoint Server 2007 on a test server, then search for the

prescan.exe file and preupgradescanconfig.xml file and copy these to the computer running the existing version.

At the command prompt, change to the folder that contains the two files, and then run the following command to

scan all servers in your server environment.

prescan.exe /c preupgradescanconfig.xml /all

You can specify that the pre-upgrade scan tool scan all Web sites in your environment by using the /all parameter

command, or scan a specific URL by using the /vURL parameter command. If you do not supply a scoping

parameter, all Web sites are scanned.

To download the pre-upgrade scan tool from the Microsoft Download Center, see SharePoint Products and

Technologies Utility: Pre-Upgrade Scan Tool.

http://www.microsoft.com/downloads/details.aspx?FamilyID=e8a00b1f-6f45-42cd-8e56-e62c20feb2f1&DisplayLang=en

http://www.microsoft.com/downloads/details.aspx?FamilyID=e8a00b1f-6f45-42cd-8e56-e62c20feb2f1&DisplayLang=en

Note:

Templates used by SharePoint Portal Server 2003 can be incorrectly identified during the pre-upgrade scan as custom templates unless you use the preupgradescanconfig.xml file when you perform the scan. This file contains additional logic to identify the portal site templates as standard templates used by SharePoint Portal Server 2003, rather than as custom templates based on Windows SharePoint Services 2.0.

If you already installed the new version but have not yet run the SharePoint Products and Technologies

Configuration wizard, you can run the pre-upgrade scan tool from the following folder: %PROGRAMFILES%

\Common Files\Microsoft Shared\web server extensions\12\BIN. The amound of time it

takes to run the scan can vary from several minutes to a few hours, depending on the amount of content in your

environment.

After the scan completes, a summary report is displayed in the Command Prompt window. If there are any errors

or if any upgrade issues are found for your sites, you can review the full report to see the details. The report is

named PreupgradeReport_uniqueID_Log.txt (where uniqueID is a number string) and it is located in the temp

directory on the computer of the user who ran the tool (for example, %SYSTEMDRIVE%:\Documents and

Settings\User1\Local Settings\Temp). There is also a prescan.log file in the same directory; this

prescan.log file notes the time or times when the pre-upgrade scan tool was run.

You can use the reports to find and troubleshoot issues (search for "error" in the report to find the issues). You can

also share the relevant pre-upgrade scan test results with other members of the upgrade team. For example, you

can report issues such as customized site templates or custom Web Parts to the appropriate site owner, Web

designer, or developer before scheduling the upgrade to give them time to investigate the issues and take

preliminary steps. For example, a designer or developer might decide that it would be prudent to rebuild a heavily

obfuscated Web Part before the upgrade occurs. Site owners can then verify any customizations that were done to

their sites, including changes to site templates and to core Active Server Pages Extension (ASPX) files, and can

note any potential issues.

For a list of common errors, see You Receive an Error Message When You Run the Pre-Upgrade Scan Tool

(Prescan.exe) to Scan Windows SharePoint Services 2.0 Sites Before You Upgrade to Windows SharePoint Services

3.0.

Creating Upgrade Definition Files

A site upgrade definition file describes how to map a customized previous-version site definition to a new-version

site definition. The goal of a site upgrade definition file is to give developers a tool to transform their previous-

version sites into new-version equivalents that take advantage of all the improvements the new version offers.

For Office SharePoint Server 2007, there are additional page template upgrade definition files for specific page

templates (also known as page layouts). A page template is an Active Server Pages Extension (ASPX) file that

defines the structure of a page. Page templates enable you to create new pages based on the page template,

rather than editing the pages in a Web page editor that is compatible with Office SharePoint Server 2007. Page

templates are stored at the top-level (root) of the site collection and are shared across the site collection.

In Office SharePoint Server 2007, page templates are used for most pages in the portal site. All new-version site

definitions for Office SharePoint Server 2007 include page templates, and many portal pages that were based on

the standard portal site definition in the previous version are based on different page layouts in the new version.

The upgrade process moves portal pages from the previous version to pages that use page templates in the new

version. Page templates from the previous version are moved to the default set of page templates that are included

http://support.microsoft.com/Default.aspx?id=937291



with the new version. If the default set of page templates does not meet your needs, you can create a custom set

and provide an upgrade definition file to map the older portal pages to the new page templates.

An upgrade definition file for a site definition has the following sections:

WebTemplate. Specifies upgrade information for the entire Web template. You need one

<WebTemplate> tag per upgrade definition file.

Lists. Specifies upgrade information for each list or library in the template. In the Lists section, you need

one <List> tag per list or library.

Files. Specifies upgrade information for the individual pages in the template. In the Files section, you

need one <File> tag for each uncustomized (ghosted) page in the template.

Applied SiteFeature and Applied WebFeature. Specifies upgrade information for any site collection–

level features or subsite-level features included in the template. In the Applied SiteFeature and Applied

WebFeature sections, you need one <Feature> tag for each feature at that level in the template.

For more information about creating upgrade definition files, including a sample upgrade definition file, see

Upgrade Definition Files and Upgrade Definition Schema in the Windows SharePoint Services 3.0 SDK.

The following example, taken from one of the files installed in Office SharePoint Server 2007, outlines the format

for a page template upgrade definition file.

Xml

Copy Code <SPSSiteUpgraderConfig>

<PublishingPageLayoutMappings>

<PublishingPageLayoutMapping WebTemplateId="20"

PublishingPageLayout="/_catalogs/masterpage/defaultlayout.aspx"/>


PublishingPageLayout="/_catalogs/masterpage/welcomelayout2.aspx"/>

</PublishingPageLayoutMappings>

</SPSSiteUpgraderConfig>

This example shows that a Web site template maps to a page template; the Web site template with ID=20 maps to

the page layout=defaultlayout.aspx. This means that every site that uses the template ID of 20 has a home page

(usually default.aspx) that uses a page layout defined by defaultlayout.aspx.

Create Upgrade Definition Files

Give the upgrade definition file a unique name that begins with the name of the site definition. For example, for a

site definition named STS1, name the upgrade definition file STS1_upgrade.xml. You must install upgrade

definition files to the following path: %WinDir%\Program Files\Common Files\Microsoft

Shared\Web Server Extensions\12\Config\Upgrade.

For more information, see Deploy Upgrade Definition Files and New Site Definitions. For more information about

creating upgrade definition files, such as what to include in the files and the schema to follow, see the Welcome to

the Microsoft Office SharePoint Server 2007 SDK.

Upgrading Custom Site Definitions



http://technet2.microsoft.com/Office/en-us/library/c32cbc26-b1cd-4c3a-8285-6223d458e86d1033.mspx



Site definitions in SharePoint Portal Server 2003 include the set of presentation (ASPX) and configuration (XML)

files from which all SharePoint sites and lists are derived. Site definitions contain all the configuration data for the

site and are stored on the file system of each front-end Web server. As sites are created, SharePoint Portal Server

references these files to define the layout, structure, and initial content. The site definition is referenced by each

list and page that is derived from the site definition.

Site definitions are similar in SharePoint Server 2007 to their counterparts in SharePoint Portal Server 2003. One

notable change is that site definitions no longer use a single monolithic Onet.xml file to define the structure of the

site and various Schema.xml files to define the structure of lists and views. SharePoint Server 2007 relies on

Features to define what is linked to a specific site definition.

In Windows SharePoint Services 2.0 and SharePoint Portal Server 2003, many types of customization required you

to customize site definitions, which usually involved copying the STS site definition and modifying list schemas,

pages, and other structural elements in the copied definition. Large parts of the custom site definition were not

customized, which meant that they maintained many of the same basic traits as the STS site definition.

Recommended Upgrade Method

The way to obtain a Windows SharePoint Services 3.0 equivalent for a custom site definition created in Windows

SharePoint Services 2.0 varies depending on the site definition. If you did not heavily customize the site definition

in relation to the Windows SharePoint Services 2.0 site definition on which it was based, the best option may be to

create a Windows SharePoint Services 3.0 equivalent for that site definition and retrofit the new definition to

include Windows SharePoint Services 2.0 customizations. For example, if your only customization to a Windows

SharePoint Services 2.0 site definition was the addition of a custom list, or a copy of the STS site definition and

customization of the Default.aspx page for a custom look and feel, then you should probably re-create the

customization by using the Windows SharePoint Services 3.0 STS base site definition. If your customizations were

more extensive, however, it is probably wiser to convert the Windows SharePoint Services 2.0 site definition into a

Windows SharePoint Services 3.0 equivalent.

Because Windows SharePoint Services is deeply integrated with ASP.NET 2.0, the structure of ASP.NET pages

(.aspx files) used in SharePoint sites has changed significantly. When hosting a Web site based on a Windows

SharePoint Services 2.0 site definition, Windows SharePoint Services executes pages in a compatibility mode to

ensure that they function within the deployment. However, when running pages from a Windows SharePoint

Services 3.0 site definition, Windows SharePoint Services does not run the pages in compatibility mode for

performance reasons. As a result, when you create your Windows SharePoint Services 3.0 site definition, you must

modify your ASP.NET pages to some extent.

If you have not customized ASPX pages in your Windows SharePoint Services 2.0 site definition, it is good practice

to copy the Default.aspx page of the Windows SharePoint Services 3.0 STS site definition (located in the path

12\TEMPLATE\SiteTemplates\sts\xml) into your site definition.

All Web Part pages must now contain an ASP.NET Web Part manager to function properly. Consequently, if you

have customized ASPX pages, you must add a Web Part manager to them, which you do by inserting

<WebPartPages:SPWebPartManager id="m" runat="Server" /> into the pages.

Note:

Because all SharePoint master pages include a Web Part manager, it is good practice to take the extra step of basing your ASP.NET pages on a master page. You gain more flexibility from a master page–based infrastructure, and master pages help ensure that common parts of Windows SharePoint Services functionality are included on the page.

The structure of the Onet.xml file has changed in fundamental ways. If you did not customize Onet.xml in your

Windows SharePoint Services 2.0 custom site definition, it is good practice to copy the Windows SharePoint

Services 3.0 Onet.xml from the path 12\TEMPLATE\SiteTemplates\sts\xml into your site definition.

In Windows SharePoint Services 3.0, all XML files in the setup directory are converted to use resource expressions

($Resources) to make them work for any language for which language packs are installed. To make a Windows

SharePoint Services 2.0 site definition work for multiple languages, and to benefit from this expanded use of

resources, you must make many changes in the Windows SharePoint Services 2.0 XML files. In this case, it might

be best to copy the Windows SharePoint Services 3.0 STS site definition and add then your customizations to it.

If you customized the Onet.xml file in your Windows SharePoint Services 2.0 site definition, you must modify the

file to work in Windows SharePoint Services 3.0. The following basic steps can help make your Windows SharePoint

Services 2.0 Onet.xml file more consistent with a Windows SharePoint Services 3.0 site definition:

To ensure that Web sites created through your definition consistently use the new Windows SharePoint

Services 3.0 base list types, remove the <BaseTypes> section from your Windows SharePoint Services 2.0

Onet.xml file. Base list types are now included by default in SharePoint sites and do not need to be

defined in your file.

Remove standard lists from the Windows SharePoint Services 2.0 Onet.xml file. Many lists required for

SharePoint functionality are now included by default in Windows SharePoint Services 3.0 and do not need

to be defined in your Onet.xml file. For more information, see Upgrading List Definitions.

Remove the <ListTemplate> tag for lists where the Name attribute equals webtemp, listtemp, wplib, or

datasrcs. Also remove the underlying list definitions for these lists by removing the LISTS\WEBTEMP,

LISTS\LISTTEMP, LISTS\wplib, and LISTS\DATASRCs folders. Remove each <List> tag from the

Configurations section where the Type attribute equals 113 (Web template gallery), 114 (list template

gallery), or 111 (Web Part gallery).

Consider mapping the DocumentTemplates section to Windows SharePoint Services 3.0 document

templates. The system of expressing document templates in a site definition has not changed significantly

in Windows SharePoint Services 3.0. Document templates are still stored in a per-locale directory.

For your specific site definition, you must ensure that you have the corresponding set of document

template files in the path \12\TEMPLATE\locale ID\site definition name. However, if your document

template files are not customized, you can simply make your site definition reuse document templates. To

do this, annotate each <DocumentTemplate> node in your Onet.xml file to specify Path="STS".

After you have customized your site definition, test it in Windows SharePoint Services 3.0 to ensure that new Web

sites created through the definition behave as expected. After you have created the proper Windows SharePoint

Services 3.0 site definition, the next step is to create an upgrade definition to map your site definition from

Windows SharePoint Services 2.0 to Windows SharePoint Services 3.0.

For more information about how to complete this process, see Chapter 3: Preparing a Site Template Based on a

Customized Site Definition in the Upgrade Toolkit for Windows SharePoint Services Sites and Templates Guide on

Microsoft TechNet.

For more information about upgrading your custom site definitions, updating ASPX files, and editing the Onet.xml,

see Upgrading a Custom Windows SharePoint Services 2.0 Site Definition.

For more detailed information about working with upgrade definition files, see Upgrading SharePoint Portal Server

2003 Customizations to SharePoint Server 2007 (Part 2 of 2).

http://msdn.microsoft.com/en-us/library/bb954662.aspx#MOSS2007UpgradeCustomizationsP1_UpgradingListDefinitions

http://www.microsoft.com/technet/solutionaccelerators/collaboration/utwssst3.mspx

http://www.microsoft.com/technet/solutionaccelerators/collaboration/utwssst3.mspx

http://msdn.microsoft.com/en-us/library/aa543837.aspx



Upgrading Custom Site Templates

A custom site template is a package that contains a customized site design based on an existing site definition. Site

templates in this context exist outside any site definition. The site definition is a server-side collection of files that

define the structure of one or more site templates. When a user customizes a site or list in the user interface, the

custom template consists of the difference between the original state of the site or list as determined by its

definition and the state of the site when the custom template is generated. Custom templates remain tied to a

particular site definition (for example, the one for a SharePoint site or a Meeting Workspace site), so that if the site

definition is not present or is changed, the custom template will not work.

A custom template is persisted as a file with the .stp file name extension. When a site template is used to create a

new site collection or site, the site definition that it is based on will be referenced, but any modified files will be

stored directly into the database and considered customized (unghosted).


The Solution Accelerator Team (SAT) has created the Upgrade Toolkit for Windows SharePoint Services Sites and

Templates Guide Solution Accelerator, which provides guidance and tools to enable IT professionals to successfully

upgrade their Windows SharePoint Services 2.0 custom sites and templates. Following the guidelines in this

Solution Accelerator results in a set of custom sites and templates that operate in a Windows SharePoint Services

3.0 environment.

The Upgrade Toolkit for Windows SharePoint Services Sites and Templates serves two main purposes:

To provide IT professionals with the guidance and tools to upgrade customized Windows SharePoint

Services 2.0 sites and site templates to function in a Windows SharePoint Services 3.0 environment. The

upgraded sites and site templates maintain their customizations and acquire a set of Windows SharePoint

Services 3.0 Features.

To provide a set of upgraded application templates for Windows SharePoint Services based on those

currently published for Windows SharePoint Services 2.0 on TechNet and to provide instructions for

installing these application templates in a Windows SharePoint Services 3.0 environment.

Before you begin, there are two important points you should know about the custom site template upgrade

process:

The Windows SharePoint Services site template upgrade process is performed as part of the upgrade to

Windows SharePoint Services 3.0.

The process is composed of two stages: One stage is performed before your environment is upgraded

from Windows SharePoint Services 2.0 to Windows SharePoint Services 3.0, and the other is performed

after the upgrade is complete. These steps are addressed in detail in the Upgrade Toolkit for Windows

SharePoint Services Sites and Templates.

Upgrading Areas and Listings

The object model, user interface, and architecture of areas and listings have changed. Areas now use Windows

SharePoint Services 3.0 Web architecture, so the URLs of sites change. Bucket Web sites are removed during

upgrade. In a clean installation, the user gets portal sites that are named just like new Windows SharePoint

Services 3.0 sites. SharePoint Services 2.0 listings do not exist in Office SharePoint Server 2007. A new summary

links Feature displays links on a page.


http://www.microsoft.com/technet/solutionaccelerators/collaboration/default.mspx

http://www.microsoft.com/technet/solutionaccelerators/collaboration/default.mspx

To preserve data and functionality, upgrading moves listings to an Office SharePoint Server 2007 list and uses the

Content Query Web Part (CQWP) to display the items on a page. We recommend that you manually move

upgraded data to summary links, because this is the new feature for displaying, sorting, and grouping links on a

page.

During upgrade, areas are automatically moved to sites and bucket Web site URLs are removed. You must change

favorites and other externally saved links. Upgrading automatically moves listings to an Office SharePoint Server

2007 list and a CQWP. News listings are also upgraded to Link lists or pages. We recommend that you manually

move the data to the summary links Feature to receive all of the benefits of easy in-page link editing. To do this,

you must add a summary links Web Part or control to the page, and then manually copy links from the upgraded

list to the summary links Web Part.

Upgrading Areas Based on Custom Site Definitions

The SharePoint Portal Server 2003 area is built on top of Windows SharePoint Services 2.0 site functionality. The

area as a whole provides additional functionality beyond the Windows SharePoint Services site, but as far as

Windows SharePoint Services is concerned, the area-backing site is just another Windows SharePoint Services site

based on a custom site definition. Windows SharePoint Services cannot fully upgrade a site created from a custom

site definition without additional information because it does not know the full extent of the customizations. During

the upgrade, an upgrade definition file must be provided to upgrade the custom SharePoint Portal Server area,

similar to the process of upgrading a custom Windows SharePoint Services site.


A custom SharePoint Portal Server area, derived from one of the default area definitions, contains two sets of

customizations as it appears to Windows SharePoint Services, one made by SharePoint Portal Server, and one

made by the end user. To upgrade a custom area created from a custom site definition, you must provide an

upgrade definition file that tells Windows SharePoint Services how to upgrade both sets of customizations.

To complete this upgrade, you must complete five major steps. The first four steps are completed after the binary

installation before the actual upgrade process; the last step is completed after the upgrade has completed

successfully.

Start by creating a custom webtemp*.xml file in the Windows SharePoint Services 3.0 location

%SystemDrive%\Program Files\Common Files\Microsoft Shared Debug\Web Server

Extensions\12\TEMPLATE\LCID\XML. For example, name this file webtempCUSTOM.xml. Add the

following code to this XML file.

Xml

Copy Code <?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>

Then you must create the Windows SharePoint Services 3.0 equivalent of the 2.0 area definition. Most custom

templates are created by copying and modifying an existing template, such as the SPSTOPIC template. Identify the

template that was used to create your 2.0 template, and then find the corresponding template in Windows

SharePoint Services 3.0 in the path %SystemDrive%\Program Files\Common Files\Microsoft

Shared Debug\Web Server Extensions\12\TEMPLATE\SiteTemplates. Copy this template into

the same directory and rename the file with a name such as SPSCUSTOM. By comparing the original 2.0 custom

template to the new 3.0 custom template, you can apply the customizations to the new template.

To take advantage of the page layout functionality, you need to specify which layout page to use for the area

welcome pages. Navigate to the path %SystemDrive%\Program Files\Common Files\Microsoft

Shared Debug\Web Server Extensions\12\CONFIG\UPGRADE, and then open

SiteUpgraderConfigSPS.xml. The file contains the following code.

Xml

Copy Code <?xml version='1.0'?>

<SPSSiteUpgraderConfig>

<PublishingPageLayoutMappings>


PublishingPageLayout="/_catalogs/masterpage/defaultlayout.aspx"/>










PublishingPageLayout="/_catalogs/masterpage/newshomelayout.aspx"/>





</PublishingPageLayoutMappings>

</SPSSiteUpgraderConfig>

Under the <PublishingPageLayoutMappings> node, add another entry under <PublishingPageLayoutMapping> with

the following code.

Xml

Copy Code <PublishingPageLayoutMapping WebTemplateId="10001"

PublishingPageLayout="/_catalogs/masterpage/customlayout.aspx"/>

This line tells Windows SharePoint Services that for all welcome pages in areas created by using the new custom

area template with an ID of 10001, use CustomLayout.aspx as the page layout. The *.aspx and ID can be set to

any value that is not already in use by Windows SharePoint Services. If the goal is to duplicate the Windows

SharePoint Services 2.0 look and feel, copy the 2.0 default.aspx page and add the 3.0 Web Part manager control

code <WebPartPages:SPWebPartManager id="m" runat="Server" />. However, some

functionality is not available if you use this method.

The recommended method of creating the layout page is to copy the built-in Windows SharePoint Services 3.0

layout page and modify the copy to meet your needs. A good layout page to copy is located in the path

%SystemDrive%\Program Files\Common Files\Microsoft Shared Debug\Web Server

Extensions\12\TEMPLATE\FEATURES\PortalLayouts\welcomelayout2.aspx. Ensure that the

Web zone IDs stay the same as in Windows SharePoint Services 2.0, or you will have Web Parts in the wrong zone

or moved off to the page gallery after upgrade.

Now you must create the upgrade definition file. You can create this file by searching and replacing a few strings,

depending on the type of customization you did to the custom area template. The upgrade definition file can have

multiple <WebTemplate> nodes with each outlining how to upgrade sites created from a particular site template.

For this example, the custom area template is based on the SPSTOPIC template (ID=31).

To create the upgrade definition file

1. Open the SPSUpgradePremium.xml file (or SPSUpgrade.xml depending on the SKU) in the path

%SystemDrive%\Program Files\Common Files\Microsoft Shared Debug\Web

Server Extensions\12\CONFIG\UPGRADE, and locate the <WebTemplate> node with ID=31.

2. In the path %SystemDrive%\Program Files\Common Files\Microsoft Shared

Debug\Web Server Extensions\12\CONFIG\UPGRADE, create an XML file that contains the

following text.

Xml


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

</Config>

3. Copy the entire ID=31 <WebTemplate> from SPSUpgradePremium.xml to the new file under the

<Config> node.

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

We recommend that you create your own upgrade definition file (rather than modify the existing upgrade definition

file). Modifying any existing upgrade definition file is not supported and causes problems when installing patches.

There are four subnodes in the <WebTemplate> node:

<Lists> maps a list ID to the corresponding list Feature ID. If you turned any of the 2.0 custom lists into

Features ("featurized" them), you must add an entry to this node.

<Files> maps an old setup path (ghost path) to the new path. For example, if an area template has

moved from a directory under an LCID to a global directory, you need the following entry to tell the

upgrade how to fix the setup path.

Xml

Copy Code <File FromPath="{LocaleId}\SPSCUSTOM\default.aspx"

ToPath="SiteTemplates\SPSCUSTOM\default.aspx" />

Also, the lists definitions are moved out of site definitions, and their support files are moved to a global

directory. As a result, you need entries such as the following.

Xml

Copy Code <File FromPath="{LocaleId}\SPSCUSTOM\Lists\announce\AllItems.aspx"

ToPath="pages\viewpage.aspx" />

Add one entry for each custom file that has its setup path moved.

<AppliedSiteFeatures> is useful only if the custom template can be used to create the root site in a site

collection. Because Windows SharePoint Services 2.0 does not allow a custom home area template, this

tag is irrelevant during the upgrade.

<AppliedWebFeatures> allows you to specify what Features to turn on for areas created by using the

custom template during upgrade. The Features that have their IDs already listed here are all required for

upgrade to work correctly. You can add others as needed.

Finally, after upgrade has finished successfully, navigate to the master page and Page Layouts gallery at

http://servername/_catalogs/masterpage/Forms/AllItems.aspx, and then click Upload in the

toolbar to upload the page layouts.

For more information, see the Microsoft SharePoint Products and Technologies Team Blog entry How to Upgrade an

Area Based on a Custom Site Definition.

Upgrading List Definitions

List definitions in Windows SharePoint Services 2.0 are contained within site definitions. In Windows SharePoint

Services 3.0, the list definitions are moved into SharePoint Features to make them more easily accessible to all site

definitions. For this reason, you no longer need to redefine lists that you do not intend to customize within your site

definition.


http://blogs.msdn.com/sharepoint/archive/2007/03/06/how-to-upgrade-an-area-based-on-a-custom-site-definition.aspx

http://blogs.msdn.com/sharepoint/archive/2007/03/06/how-to-upgrade-an-area-based-on-a-custom-site-definition.aspx

If you have not customized any standard list definitions, simply remove the standard Windows SharePoint Services

2.0 list definitions from your site definition and replace them with a reference to the standard Windows SharePoint

Services 3.0 team collaboration Feature.

To remove the standard list definitions from your site definition

1. Remove the<ListTemplate> tags in Onet.xml for the following list types: custlist, gridlist, doclib,

imglib, voting, discuss, favorite, announce, contacts, events, tasks, xmlform, and issue.

2. Remove the supporting list directories for these Windows SharePoint Services 2.0 list definitions. That is,

for your Windows SharePoint Services 3.0 site definition, you can remove the Windows SharePoint

Services 2.0 ANNOUNCE, CONTACTS, CUSTLIST, DISCUSS, DOCLIB, EVENTS, FAVORITE, GRIDLIST,

IMGLIB, ISSUE, TASKS, VOTING, and XMLFORM folders from \LISTS.

3. In each of the <Configuration> tags within your Onet.xml file, add a reference to the team collaboration

Feature, as follows.

Xml

Copy Code <Configuration ...>

<WebFeatures>



<Feature ID="00BFEA71-4EA5-48D4-A4AD-7EA5C011ABE5" />

</WebFeatures>

</Configuration>

If you have customized specific list definitions (for example, the document library definition [DOCLIB]), then you

must use a different approach. Replace all the uncustomized lists as mentioned previously (in this case, all lists

except DOCLIB). Instead of adding a reference to the team collaboration Feature in your <Configuration> tags,

add specific references to the Features that contain list definitions that you have not customized.

If you have customized only the document library (DOCLIB) list definition in your Windows SharePoint Services 2.0

site definition, add Feature references for Features that are scoped to a site collection or Web site within the

<Configuration> tags of your Onet.xml file. Add references for every Feature except the document library

definition, so that this list definition maintains your customizations.

For additional information about this process, see Upgrading Standard List Definitions.

Upgrading Customized (Unghosted) Pages

Site definition files are cached in memory on the server at process startup of Internet Information Services (IIS).

This improves scalability and performance by reducing unnecessary data storage or retrieval, and by allowing

pages that are not customized to be reused across sites. The information contained in these files is pulled from the

cache at run time. Pages and list schemas are read from the site definition files but appear to be actual files within

a site, which is why these files are referred to as uncustomized or "ghosted."

When site pages are customized by using FrontPage or other means, with the exclusion of browser-based

customizations such as modifications to Web Parts, the pages become customized or "unghosted," and their

contents are stored in the database. Windows SharePoint Services 2.0 does not natively provide a means for

removing customization from ("re-ghosting") pages. In addition, uploaded .aspx files are automatically considered

customized (unghosted).

When upgrading to Office SharePoint Server 2007, any page that is still in its ghosted state immediately benefits

from the Office SharePoint Server 2007 look and feel. However, any page that is customized (unghosted) maintains

the SharePoint Portal Server 2003 look and feel, unless you revert the page to the site definition. When you revert

to the site definition, the page appears in the default look and feel format.


You can take three possible approaches to upgrading customized (unghosted) pages, depending on your

preference.

With default site definitions and customized (unghosted) home pages, the primary decision is whether to

revert to the site definition or not. When the upgrade takes place, only those pages that are in the default

(uncustomized or ghosted) state take on the new look and feel (such as new breadcrumbs, top navigation,

and security trimmed UI). With customized (unghosted) sites, you must reset the site definition for the

entire site or reset it page-by-page by using the Site Actions menu to access Site Settings, and then

clicking Reset to Site Definition. For additional explanation and instructions, see Reset a Customized

Page to the Site Definition.

Reset the site definition on the sites in the Administration UI as they are upgraded. This administration

option is available on the Central Administration page, from the Operations tab. Navigate to Site

Collection Upgrade, click Actions, and then click Upgrade Settings. Choosing this option resets all

pages in the sites that are upgraded while this is enabled.

Revert sites to the site definition during the upgrade process from the command line. This can be

accomplished by using the command-line option. For more information, see Upgrade Sites by Using the

Command Line.

Upgrading Custom Web Parts

A Web Part is an ASP.NET server control that serves a particular purpose, such as displaying data from a worksheet

or streaming stock quotations from an online Web service. Web Parts are inserted in Web Part zones on Web Part

Pages. Web Part zones are containers for Web Parts; they group and organize Web Parts and provide a set of

properties that configure the Web Parts in that zone. Web Part Pages consolidate data and Web content through

Web Part zones to create dynamic information portals.

Web Parts in SharePoint Portal Server 2003 are small, configurable server-side components that normally render

HTML code that is returned to the client browser. Web Parts can require server-side assemblies to be installed if

the Web Part requires server-side code, and these assemblies can be installed either in a virtual server–specific Bin

directory or in the global assembly cache of the server. Web Parts installed in the global assembly cache are

upgraded as is. Web Parts in the global assembly cache during a gradual upgrade must be re-registered; only in-

place upgrade retains the registration. We do not recommend using in-place upgrade if you have any

customizations, because of the likelihood of failed upgrades in conjunction with customizations.


Most custom Web Parts continue working after upgrade. However, you should test your Web Parts in ASP.NET 2.0

to verify that they will work in the new environment. In particular, you must rebuild or redeploy custom Web Parts

if you:

Used the ASP.NET 1.1 obfuscation tools; you must rebuild your Web Parts by using ASP.NET 2.0.



http://technet2.microsoft.com/Office/en-us/library/94c49b6d-527e-4387-9557-8cfe8b55ede91033.mspx#section2

http://technet2.microsoft.com/Office/en-us/library/94c49b6d-527e-4387-9557-8cfe8b55ede91033.mspx#section2

Are moving to a new server farm by using the database migration path for upgrade. If you choose this

upgrade path, you must redeploy your Web Parts to the new farm.

Have stored your custom Web Parts in the \BIN folder and are not upgrading in-place. Gradual upgrade

does not upgrade items to the new \BIN folder, so you must redeploy your Web Parts.

To upgrade your Web Parts, test them in ASP.NET 2.0, and then either rebuild or redeploy any Web Parts that

meet the previous criteria.

Upgrading Custom Event Handlers

Event handlers in SharePoint Portal Server 2003 can be registered only for document libraries. Event handlers

consist of server-side installed assemblies that are referenced individually at each document library that should

become event-enabled. Additionally, the virtual server that hosts the document library must be set to allow event

handlers to expose the document library advanced settings where event handlers are referenced. Only a single

event handler can be referenced on any one document library.

Many developers use the event handlers in Windows SharePoint Services to execute custom managed code behind

document libraries or form libraries. The goal of Windows SharePoint Services 3.0 is to provide developers with an

even richer platform for developing custom integration points and building new types of applications on top of the

infrastructure. For this purpose, the event handlers in Windows SharePoint Services 3.0 are extended in scope and

depth in many ways. SharePoint Server 2007 provides many new events and even allows for synchronous events,

allowing you to launch an event before data is committed. No longer are event handlers just for items you create;

they are also for lists and sites you create.


If you have custom event handlers configured for your environment, you must reapply the event handlers or use

new Features to perform the tasks instead. We recommend that you use a Feature instead of a custom event

where it is practical to do so.

For more information, see How to: Create an Event Handler Feature and Feature Events.

During the upgrade process, many other considerations might take precedence over the existing custom event

handlers. To account for this, Office SharePoint Server 2007 provides you the ability to continue using the Windows

SharePoint Services 2.0 event handlers. From the Central Administration page, click the Application

Management tab, and then click Web Application General Settings. From the Web Application General

Settings page, scroll to the Backward-Compatible Event Handlers section to enable or disable this functionality.

Upgrading Custom Themes and Style Sheets

Themes in SharePoint Portal Server 2003 are collections of style sheets and image files that you use to apply an

overall style to a SharePoint site. Themes are installed server-side as a directory that contains multiple resource

files and also requires an entry in the SPThemes.xml file. Themes are a low-risk customization because a site

collection is not modified when a template is applied. Instead, effects appear client-side through the visual

modification of Web pages by the themes CSS file.

As a general rule, if you are using a SharePoint Portal Server 2003 theme, you should consider creating an Office

SharePoint Server 2007 theme. Because themes can be more effective than master pages at branding a site, it is

usually only necessary to create a master page if you want to change the structure of a page.

Note:



During the upgrade process, each site is reset to the default theme.


Although themes function identically in Office SharePoint Server 2007 to how they functioned in SharePoint Portal

Server 2003, the tags that the CSS files apply can be different. Most existing SharePoint Portal Server 2003 custom

themes do not render correctly in the Office SharePoint Server 2007 environment. In most cases, you must

recreate the custom themes so that they can render correctly. During your upgrade process, however, you should

consider using master pages, which is a new option in SharePoint Server 2007.

Master pages provide the look and feel and standard behavior that you want for all of the pages in your site.

Together with layout pages, they produce output that combines the layout of the master page with content from

the layout page. Because Windows SharePoint Services 3.0 is built on top of ASP.NET 2.0, it supports master pages

for defining elements that are common to all pages. You can specify all of the shared elements of your site in the

master page or pages, and add content page–specific elements to content pages.

For more information, see Master Pages and Windows SharePoint Services Default Master Pages.

When you install Windows SharePoint Services, a single default master page is applied to all the pages in a site.

You can, however, create your own master pages for a site and make them available to the site and any sites

beneath it. For more information about customizing master pages, see Customizing Master Pages in Windows

SharePoint Services.

Upgrading Custom Code or Pages in Layouts Folders

The _layouts directory in SharePoint Portal Server 2003 contains many files that are common to the functioning of

each site. This directory is available to each site through the relative path URL/_layouts. Any changes made in the

_layouts directory apply across all sites hosted on the same server. These pages are stored in the virtual directory

for the SharePoint Web application. The _layouts directory is also virtualized as a subfolder of every SharePoint

site, and is exposed in a site collection or subsite, for example, http://MyServer/_layouts/Mysite.aspx

or http://MyServer/a/b/c/_layouts/Mysite.aspx.


Windows SharePoint Services 2.0 _layouts pages typically refer to built-in layout files that are installed to the

\Web Server Extensions\60\TEMPLATE\LAYOUTS\Locale_ID setup directory. Because Windows

SharePoint Services 3.0 layouts files are now stored in a language-independent folder, Windows SharePoint

Services automatically sets up a redirect that navigates users from

/_layouts/Locale_ID/nameofoldpage.aspx to /_layouts/newpage.aspx.

For customized sites that are using the _layouts folder, remember that Office SharePoint Server 2007 no longer

contains a "bin" directory in the _layouts virtual directory, so all pages must use inline code.

For more information, see Upgrading Pages and Web Parts and Application _layouts Page Type.

Inclusions or Exclusions

In Windows SharePoint Services 2.0, there are two categories of paths you can manage: included and excluded. An

included path indicates that Windows SharePoint Services manages that path. An excluded path indicates that the

path is managed by a different application (Windows SharePoint Services should leave it alone).








When performing content database migration steps, it is important that all inclusion paths, custom Web Parts, and

custom site definitions are reapplied. Inclusion paths (such as /teams or /mysites) are commonly missed. When

completing the upgrade, ensure that all inclusion paths are re-created. This is not necessary for exclusion paths

because those are now assumed by default.

You can manage paths in SharePoint Products and Technologies by using the HTML Administration Pages. To

include or exclude a new path, use the Define Managed Paths page for the virtual server that contains the path.

From the command prompt, by using the STSADM tool, use the addpath and deletepath operations are to

manage paths. Both operations take the -url and -type parameters. The -type parameter has three values:

exclusion, explicitinclusion, and wildcardinclusion. For example, to add a new wildcard inclusion to manage

all sites at the top level of http://server1, you would use syntax like the following.

Copy Code stsadm -o addpath -url http://server1/ -type wildcardinclusion

For more information, see Managing Paths in the Administrator's Guide for Windows SharePoint Services.

Upgrading Third-Party Customizations

Office Web Components (OWC)

Microsoft Office Web Parts and Components is a collection of Web Parts, Web Part Page solutions, templates, and

data-retrieval services that work closely with Microsoft Office 2003 and Windows SharePoint Services 2.0. These

added functionalities were particularly useful for large organizations that deployed the Microsoft Office system

throughout their organization and wanted to take advantage of the enhanced functionality and efficiencies these

Web Parts and components provided for their sites.

The Office Web Components (OWC) are a set of ActiveX controls that provide four principal components:

Spreadsheet, Chart, PivotTable, and Data Source Control (DSC). In the 2007 Microsoft Office system, these Office

Web Components are no longer installed.

OWC are being discontinued because a more flexible technology is required to help customers address the following

needs that are not addressed by OWC:

A server-side Microsoft Office Excel calculation engine

Greater parity with Office Excel when worksheets are delivered over the Web

The ability to enable worksheets to be more scalable and stable when loaded onto a server

Improved security

The ability to perform more detailed analysis to improve overall business intelligence

To address these customer challenges, the Enterprise Client Access License (CAL) version of Office SharePoint

Server 2007 includes a technology named Excel Services, which includes the following:

A server-side Excel calculation engine

The ability to enable browser-based worksheet viewing and interactivity

Web service access to the spreadsheet calculation engine in Excel

http://www.microsoft.com/resources/documentation/wss/2/all/adminguide/en-us/stsf05.mspx

For additional information about Excel Services, see Excel Services Overview or the MSDN Blog Posts Category

Excel Server.


There are a couple of items to consider if you are currently using solutions that use OWC. If the solutions are

meeting your present needs, then you can continue to use OWC. However, if you feel that OWC is lacking certain

features and is failing to address your needs, be aware that OWC is being discontinued and no functionalities will

be added. Many browser-based OWC solutions might be migrated to use the new, thin Excel capabilities on the

server, but the server does not provide a complete superset of functionality (for example, typing into any cell in

the worksheet or adding new measures or dimensions to a PivotTable view from the browser is not supported).

If you need to install the Office Web Parts after upgrading, you can do this by locating three CAB files in the path

Program Files\Common Files\Microsoft Shared\Web Server Extensions\60\wppacks:

Microsoft.sharepoint.solutions.greatplains.cab, Microsoft.sharepoint.webparts.quickquote.cab, and

Microsoft.office.dataparts.cab. These files are explained in Shane Young's blog post How to Manually Install the

Office Web Parts in SharePoint v3. After you find the CAB files, add each of them by using the following stsadm.exe

command.

Copy Code stsadm.exe -o addwppack -filename "c:\program files\common

files\microsoft shared\web server

extensions\60\wppacks\microsoft.office.dataparts.cab" -globalinstall

For more information about issues related to the upgrade of Office 2003 Web Parts and components, see Cannot

View a SharePoint Services 3.0 Web Site After You Migrate a Windows SharePoint Services 2.0 Content Database.

RSS

RSS is a new syndication technology that has become popular over the last several years. Essentially, RSS is an

XML file (also called a "feed," "Web feed," or "channel") that contains either a summary of content from a Web site

or the full text. RSS feeds enable content publishers and consumers to exchange information in a simple and

elegant way. A publisher produces an RSS feed and makes it available at a location (URL). Consumers (software

that is a "feed reader" or "aggregator") read the feed and reformat the information for display. SharePoint Products

and Technologies understand XML and are well suited to process RSS. Updated content such as blog entries, news

headlines, or podcasts are examples of what might be published as RSS feeds.


In the previous versions of SharePoint Products and Technologies, there was no default support for RSS feeds, so

many organizations added RSS functionality by installing add-ons. Because Office SharePoint Server 2007 provides

this functionality, we recommend transferring your third-party RSS add-on to the native Office SharePoint Server

2007 interface. The feature itself is installed and enabled automatically after the upgrade. By navigating to a list or

document library, you can select View RSS Feed from the Actions menu.

MSNBC Web Parts Discontinued

MSNBC Web Parts have been discontinued in the online Web Part gallery for Windows SharePoint Services. Web

Parts that link to MSNBC now return the following error:

Cannot display information. This Web Part requires a connection to the Internet and Microsoft Internet Explorer 5.0

or later running on a Windows operating system. Customers are advised to remove these Web Parts as soon as it is

convenient to do so.


http://blogs.msdn.com/excel/archive/category/11361.aspx

http://msmvps.com/blogs/shane/archive/2006/09/02/How-to-manually-install-the-Office-Web-Parts-in-SharePoint-v3.aspx

http://msmvps.com/blogs/shane/archive/2006/09/02/How-to-manually-install-the-Office-Web-Parts-in-SharePoint-v3.aspx




If your pages contain these Web Parts, you should remove the Web Parts completely. To obtain up-to-date or live

data in a Windows SharePoint Services site, we recommend that you pull data from an RSS feed. If you need

additional help with this topic, search or post your own questions on the TechNet Forums Site for SharePoint

Products and Technologies.

Next step: Upgrading SharePoint Portal Server 2003 Customizations to SharePoint Server 2007 (Part 2 of 2).

Conclusion



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.

http://forums.microsoft.com/technet

http://forums.microsoft.com/technet


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

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.

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.

http://msdn.microsoft.com/en-us/library/bb954661.aspx#MOSS2007UpgradeCustomizationsP2_WorkingwithUpgradeDefFilesToolstoHelpYou

http://msdn.microsoft.com/en-us/library/bb954661.aspx#MOSS2007UpgradeCustomizationsP2_UpgradeProcessOverview

http://msdn.microsoft.com/en-us/library/bb954661.aspx#MOSS2007UpgradeCustomizationsP2_Step1LocatetheCustomSiteDefinitiontoUpgrade

http://msdn.microsoft.com/en-us/library/bb954661.aspx#MOSS2007UpgradeCustomizationsP2_Step2IdentifyCustomizations

http://msdn.microsoft.com/en-us/library/bb954661.aspx#MOSS2007UpgradeCustomizationsP2_Step3SelectUpgradeFilesandCopyAllFilestoCorrectFolders

http://msdn.microsoft.com/en-us/library/bb954661.aspx#MOSS2007UpgradeCustomizationsP2_Step4CreateUpgradeDefFile

http://msdn.microsoft.com/en-us/library/bb954661.aspx#MOSS2007UpgradeCustomizationsP2_DrillingintotheUpgradeDefinitionFile

http://msdn.microsoft.com/en-us/library/bb954661.aspx#MOSS2007UpgradeCustomizationsP2_ElementsandAttributes

http://msdn.microsoft.com/en-us/library/bb954661.aspx#MOSS2007UpgradeCustomizationsP2_AnnotatedWalkthroughoftheSampleUpgradeDefinitionFile

http://msdn.microsoft.com/en-us/library/bb954661.aspx#MOSS2007UpgradeCustomizationsP2_Conclusion




http://office.microsoft.com/download/afile.aspx?AssetID=AM101599211033

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

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

http://www.microsoft.com/downloads/details.aspx?familyid=72d6aa49-787d-4118-ba5f-4f30fe913628&displaylang=en

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

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:

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


<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


ToFeatureId="00BFEA71-7E6D-4186-9BA8-C047AC750105" />

<List


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.

Xml

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

Xml

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

<WebTemplate

ID="1"

LocaleId="*"





<Lists>

<List


ToFeatureId="00BFEA71-D1CE-42de-9C63-A44004CE0104"

v3Type="0x0104">

</List>

<List


ToFeatureId="00BFEA71-7E6D-4186-9BA8-C047AC750105"

v3Type="0x0105">

<Source v2List="105" />

</List>

</Lists>

<Files>

<File


ToPath= "SiteTemplates\STS\default.aspx">

</File>

<File


ToPath= "Features\AnnouncementsList\announce\AllItems.aspx">

</File>




http://msdn.microsoft.com/en-us/library/bb954661.aspx#MOSS2007UpgradeCustomizationsP2_ElementsandAttributes

<File


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>


<Feature ID="00BFEA71-1C5E-4A24-B310-BA51C3EB7A57" />



<Feature ID="00BFEA71-D1CE-42de-9C63-A44004CE0104" />

<Feature ID="00BFEA71-7E6D-4186-9BA8-C047AC750105" />

<Feature ID="00BFEA71-DE22-43B2-A848-C05709900100" />


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


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


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


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


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.


<Feature

ID = "GUID"

Force = "TRUE" | "FALSE" />


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


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.


<Feature

ID = "GUID"

Force = "TRUE" | "FALSE" />


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


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

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

<WebTemplate

ID="1"

LocaleId="*"









<Lists>



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


ToFeatureId="00BFEA71-D1CE-42de-9C63-A44004CE0104"

v3Type="0x0104">


</List>



<List




ToFeatureId="00BFEA71-7E6D-4186-9BA8-C047AC750105"

v3Type="0x0105">


</List>

...

</Lists>



<Files>

<File




ToPath= "SiteTemplates\STS\default.aspx" />

<File


ToPath= "Features\AnnouncementsList\announce\AllItems.aspx" />

<File

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>






<Feature ID="00BFEA71-1C5E-4A24-B310-BA51C3EB7A57" />







<Feature ID="00BFEA71-D1CE-42de-9C63-A44004CE0104" />

<Feature ID="00BFEA71-7E6D-4186-9BA8-C047AC750105" />

<Feature ID="00BFEA71-DE22-43B2-A848-C05709900100" />

...


</WebTemplate>

</Config>

Conclusion



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.