Utility Spotlight: Upgrade Toolkit for SharePoint Sites and Templates

Article
09/08/2016

Utility SpotlightUpgrade Toolkit for SharePoint Sites and Templates

Luis Câmara Manoel and Peter Skjøtt Larsen

Download the code for this article: Upgrade Toolkit for Windows SharePoint Services Sites and Templates (699KB)

With the recent arrival of Windows SharePoint Services (WSS) 3.0, many administrators are faced with the task of upgrading their existing WSS 2.0 sites and data to their new WSS 3.0 environments. Though WSS 3.0 provides extensive tools that adequately migrate site data and

upgrade site structure, additional work might be necessary to upgrade the structure of customized sites or site templates.

However, additional work might be necessary to upgrade the structure of customized sites or site templates. Fortunately, the Microsoft® Solution Accelerator team has released the Upgrade Toolkit for Windows® SharePoint® Services Sites and Templates, which provides guidance and tools around this practice (see the "WSS Resources" sidebar). This column focuses on some of the challenges and solutions associated with upgrading customized sites to WSS 3.0 environments. But first, see the "WSS Terminology" sidebar for some definitions of common terms.

The Upgrade Process

Why should you upgrade? There are a number of new WSS 3.0 features that might compel site owners to upgrade:

Recycle Bin, which lets users retrieve inadvertently deleted documents.
Folder item level security, which allows site administrators to control which people or groups have access to folders.
E-mailing to lists, which allows lists such as blog post lists on a SharePoint site to receive content through e-mail.
Site Actions button, which lets users easily create sites and pages, edit pages, and manage site settings.
Breadcrumbs, which provide immediate navigational context for the user.
Mobile views, which enable mobile users to take advantage of convenient offline synchronization capabilities.
RSS feeds, which let RSS-enabled programs such as Internet Explorer 7.0 and Outlook® 2007 retrieve information from lists.
Versioning in document libraries, which allows minor versioning and control for document check out before edit.

Because the site and template upgrade process depends on taking specific steps prior to and following the actual server upgrade to WSS 3.0 (see Figure 1), the definition of site and template upgrade requirements is an important step in the overall WSS 3.0 upgrade strategy. Site owners and server managers should work together to determine which sites and templates should be instantiated and upgraded into a WSS 3.0 environment. Once these custom sites have been selected, the upgrade work can begin.

Figure 1 WSS site and site template upgrade workflow

Figure 1** WSS site and site template upgrade workflow **(Click the image for a larger view)

Identify Customized Site Templates

How do you determine if the sites have been customized? WSS 3.0 provides the pre-upgrade scan tool that generates a report on changes made to site templates for the entire farm. You should run this tool before starting migration to select which site templates require special attention.

The tool provides a report in XML format as shown in Figure 2. The element unghostedPage indicates that a site has been customized.

Figure 2 Pre-upgrade scan tool report on changes made to site templates

<?xml version=”1.0” encoding=”utf-8”?>
<summary>
  <sites>
    <site url=”https://mscc-shr-v3-01” storage=”172767226”>
      <webs>
        <web url=”https://mscc-shr-v3-01/Board of Directors-Basic”>
          <unghostedPage url=”https://mscc-shr-v3-01/Board of Directors-Basic/Board Information/
                Forms/default.aspx” />
          <unghostedPage url=”https://mscc-shr-v3-01/Board of Directors-Basic/Board Information/
                Forms/AllItems.aspx” />
          <unghostedPage url=”https://mscc-shr-v3-01/Board of Directors-Basic/Board Information/
                Forms/DispForm.aspx” />
          <unghostedPage url=”https://mscc-shr-v3-01/Board of Directors-Basic/Board Information/
                Forms/EditForm.aspx” />
          <unghostedPage url=”https://mscc-shr-v3-01/Board of Directors-Basic/Board Information/
                Forms/Upload.aspx” />
          <unghostedPage url=”https://mscc-shr-v3-01/Board of Directors-Basic/Board Information/
                Forms/WebFldr.aspx” />
          <unghostedPage url=”https://mscc-shr-v3-01/Board of Directors-Basic/Company Finance and 
                Business Planning/Forms/AllItems.aspx” />
          <unghostedPage url=”https://mscc-shr-v3-01/Board of Directors-Basic/Company Finance and 
                Business Planning/Forms/DispForm.aspx” />
          <unghostedPage url=”https://mscc-shr-v3-01/Board of Directors-Basic/Company Finance and 
                Business Planning/Forms/EditForm.aspx” />

Custom Site Definitions

Most of the customized WSS 2.0 sites you’ll want to upgrade were probably built from templates created from standard WSS site definitions. It is possible, however, that some of the customized site templates were built on customized site definitions. This may be the case if developers in your organization created customized site definitions or if you purchased third-party applications or templates built on customized site definitions. This column will cover only the standard site definition scenario. For more information on the custom site template scenario, consult the "WSS Resources" sidebar.

Having verified that your .stp files and sites are indeed built from standard site definitions, which means that upgrade site definitions exist in WSS 3.0, you can proceed to install and instantiate your sites.

To upgrade specific WSS 2.0 site templates, first you’ll need to install the templates on a WSS 2.0 server (see Stage 1 in Figure 1). Then you’ll need to create sites based on each of the installed templates.

To streamline the process of installing multiple .stp files, instantiating multiple sites, and cleaning the server of any temporary files after the upgrade process is completed, the solution accelerator provides a set of scripts that leverage Stsadm.exe commands (see the "Solution Scripts" sidebar for details). Stsadm.exe is a command-line application that offers a complete set of WSS operations for managing SharePoint servers and sites. The solution scripts automate this process by letting you batch install and instantiate or to perform these tasks sequentially. The time savings can be considerable if many .stps are to be installed and many sites to be instantiated.

Solution Scripts

The installation and site creation process uses two scripts that run Stsadm.exe:

MigInstStp.cmd installs the site templates using the Stsadm.exe addtemplate operation. This operation has the parameters _SOURCEFILELOCATION, _SOURCEFILENAME, and _FILETITLE.
MigMakeSite_1.cmd creates the new sites. MigMakeSite_1.cmd runs the Stsadm.exe createweb operation. This operation has the parameters _SERVERURL, _SITENAME, _SITETEMPLATENAME, and _SITETITLE.

Run these scripts on the local WSS 2.0 server with access to the location of your saved site template (.stp) files. To run these scripts, you must be a member of the local Administrators group on the server or a member of the WSS Administrators group with site create permissions. The Upgrade Toolkit for Windows SharePoint Services Sites and Templates guide provides a detailed description on how to take full advantage of these scripts. With your .stps installed and your sites instantiated, you are now ready to proceed to server upgrade. The WSS 3.0 upgrade approaches are explained in detail in “Upgrading to Windows SharePoint Services 3.0” (see the link listed in the “WSS Resources” sidebar).

WSS Terminology

Windows SharePoint Services has its own unique terminology. Here’s a brief glossary of commonly used terms.

Site Definition This is a set of files that defines a specific type of site. A site definition includes .xml, .aspx, .ascx, and Master Page files, as well as list template files and content files stored in a special folder on the front-end Web server. WSS comes with a set of standard, out-of-the-box site definitions that includes Team Site, Blank Site, and Document Workspace. Initially, these are the only site templates stored in the site template gallery and available in the Select a template list on New SharePoint Site.

Site Template Site templates define how to instantiate a SharePoint site. In order to create a new SharePoint site, you must select a site template upon which to base the site. For example, you can create a new site named "Board of Directors" based on a standard "Blank Site" template. You can then add lists, libraries, Web Parts and other customizations to the instantiated site. To make these customizations available to others, you can then save this site as a template named "Board of Directors" that is based on the "Blank Site" site definition. WSS saves the customized site template as a .stp (site template) file, places it in the site template gallery, and displays it in the "Select a template" list on the New SharePoint Site page so users can later create new sites based on it. Site templates contain a series of site configuration files, including .xml, .aspx, image, and others that are then compressed into a single .stp file. (.Stp files are similar in function to .cab files.) The most important of these files is Manifest.xml, which contains critical information such as site structure and navigation, lists and libraries, placement of Web Parts, custom list definitions, and the site definition on which the customized site template is based.

Application Template These are Windows SharePoint Services site templates that are developed to meet the requirements of specific business processes or tasks. They are published by Microsoft and are available for download free of charge to WSS customers.

Customized Site This is a SharePoint site with a user interface that has been modified.

Master Page This is an area where default layout information, such as banner, navigation controls and other menus can be stored for a consistent interface throughout the site.

Ghosted Pages These are pages whose contents are not stored in the WSS content database but rather are read from a site definition file. Ghosted pages have not been customized.

Unghosted Pages These are pages that have been modified from the site definition file, and whose contents are stored in the WSS content database.

After Server Upgrade—Site Inspection

Now you’ve arrived at Stage 2 in the upgrade workflow (refer back to Figure 1). The steps you take in this stage of the site and template upgrade include the following:

Open and verify the upgraded sites.
Apply the default Master Page.
Fix feature and layout issues with the new sites.
Save the corrected sites as new WSS 3.0 site templates.
Redeploy the new WSS 3.0 site templates on the server.
Create sites from the redeployed site templates.
Open the new sites and check that they function as expected.
Initiate the clean-up process.

Resetting to Site Definition

When you first open your upgraded site, you will see that it still very much resembles a WSS 2.0 site. To make the site appear more like a WSS 3.0 site, you must first reset to the site definition in your new WSS 3.0 site. This will fix most of your layout problems and you will not lose any customizations made to Web Parts, provided these Web Parts already reside in a Web Part zone that exists on the site definition page. This action will also apply the default Master Page to all of your sites’ pages.

A Master Page, as its name suggests, is an area where default layout information, such as banner, navigation controls, and other menus can be stored for a consistent appearance. This allows you to make design changes on the Master Page and have the changes propagate across the entire site. By applying Master Pages, all WSS 3.0 native functionality will be enabled in your upgraded sites.

Though the site should now look and function like a native WSS 3.0 site, you are still likely to find a few problem areas, such as Discussion boards, customized Web Parts, hyperlinks, and themes.

Fixing What’s Broken

A number of problems can occur in upgraded and customized site templates. Here are some of the most common problems and some simple ideas on how to fix them.

The WSS 2.0 default style sheet is still applied to a site. Remove the old style sheet in SharePoint Designer.

Web Parts are missing or in the wrong places. Move or insert Web Parts using SharePoint Designer.

Web Parts don’t function correctly. Remove Web Parts that are incompatible with WSS 3.0, and contact the Web Part developer to inquire if corresponding Web Parts have been built for WSS 3.0 environments.

Customized lists and libraries don’t look right. Save your existing data; then recreate the customized list or library and import the saved data.

Enabled WSS 3.0 features are not available. Team collaboration capabilities may have to be explicitly activated the under Site Features.

Hyperlinks no longer work. Hardcoded hyperlinks may require manual updating.

The theme has changed. Apply the appropriate WSS theme.

Almost Done

As the end of the process approaches and the problems have all been fixed, it is time to perform a final verification of the sites. You should save the corrected sites as WSS 3.0 site templates, perform a new .stp installation and site instantiation (you can use the handy scripts here as well), and finally, open the site to verify that all issues have been addressed and your upgraded sites and .stps are ready for further distribution in your work environment.

Alternatives to Upgrading

Upgrading templates using the automated tools and processes described here may not always be the best approach. If you are using highly customized third-party templates, it may be prohibitively difficult to upgrade the templates on your own and it might be better to wait for a new version of the template. In other cases, creating a brand new template on WSS 3.0 and then implementing the features of the old template may be the best option.

Application Templates

There is a set of Microsoft-developed application templates available for WSS 2.0 and for WSS 3.0. The new WSS 3.0 set includes upgraded versions of some of the WSS 2.0 application templates. If you have been using any of these templates, you can upload the upgraded WSS 3.0 version into your WSS 3.0 environment.

If you have been using one of the WSS 2.0 application templates that has not been upgraded for WSS 3.0, the solution accelerator provides you with a set of WSS 2.0 application templates that have been upgraded to work in a WSS 3.0 environment.

Summary

The Upgrade Toolkit for Windows SharePoint Services Sites and Templates will prove extremely valuable in helping you retain your 2.0 templates, sites and customizations in your 3.0 environment. For additional information on this topic, and to get the Toolkit, visit the sites indicated in the "WSS Resources" sidebar.

We would like to thank Betty Houser for her valuable contributions to this column and to the solution accelerator.

WSS Resources

Luis Câmara Manoel is a Program Manager in the Microsoft Solution Accelerator group. He has been with Microsoft for a year. Previously Luis worked as a project and program manager at Novell Inc and Volera in Provo, Utah. Luis can be contacted at luiscam@microsoft.com.

Peter Skjøtt Larsen is a Product Manager in the Microsoft Solution Accelerator group. He has been with Microsoft for over four years in development and marketing. Previously he developed client and server software for the financial, engineering, and telecom industries. Peter can be contacted at petela@microsoft.com.

Figure 2 Pre-upgrade scan tool report on changes made to site templates

Additional resources