SharePoint Content Migration Object Model and Content Migration Packages

The SharePoint Content Migration APIs, previously known as the PRIME APIs, are an incredibly powerful tool, not just for content migration and content deployment, but also for:

  • Creating reusable templates
  • Changing the site definition of an existing site
  • Creating replication solutions
  • Modifying properties that are not exposed through the object model
  • Creating SharePoint sites programmatically for distribution

At its simplest, content migration exports a site or part of a site into a file known as a content migration package. The content migration package is actually a cab file that contains several xml files and dat files. Then, the package can be moved and imported into a new site.

The power of the content migration packages is that the amount of information exported can be modified for different purposes, and then the xml files in the resulting package can be edited. This gives you supported ways to view and edit the structure and properties of your site in a format that is both human and machine readable.

Copying or Moving a Site

The easiest content migration task is creating a copy of a site using the stsadm utility. This method can also be used to move a site, or to move a sub site into its own site collection.

Note: The new site will not be an exact copy of the original. If a user was subscribed to an alert on the original site, they will not be subscribed to an alert on the new site. If items were in the recycle bin on the original site, they will not exist in the new site. For more information, see: Content Migration Overview.

Steps:

  1. Export the Site
  2. Create the new Site Collection, if necessary
  3. Import the Site

Export the Site

To view the options for exporting a site:

 C:\>stsadm -help export

stsadm.exe -o export
           -url <URL to be exported>
           -filename <export file name>
               [-overwrite]
           [-includeusersecurity]
           [-haltonwarning]
           [-haltonfatalerror]
           [-nologfile]
           [-versions <1-4>
               1 - Last major version for files and list items (default)
               2 - The current version, either the last major or the last minor
               3 - Last major and last minor version for files and list items
               4 - All versions for files and list items]
           [-cabsize <integer from 1-1024 megabytes> (default: 25)]
           [-nofilecompression]
           [-quiet]

To run the export:

 C:\>stsadm –o export –url https://url/to/site -filename c:\exportfile.cmp 
–includeusersecurity –versions 4

This will export the site specified at the url, and the sub sites beneath it. The includeusersecurity switch causes the new site to have the same permissions as the original site. The versions switch set to 4 specifies that all versions should be included.

Pay special attention to the nofilecompression switch. It will cause the content migration package to be output to an uncompressed folder instead of a single cab file. This makes it harder to move to a different machine, but makes it much easier to edit the files.

Create New Site Collection

Content Migration will export Sites, but not Site Collection. If you want to copy the site into another site in the same site collection, or into another site in an existing site collection, you can skip this step.

New Site Collections can be created through the Central Administration UI, or through the stsadm utility.

 C:\>stsadm -help createsite

stsadm.exe -o createsite
            -url <url>
            -owneremail <someone@example.com>
            [-ownerlogin <DOMAIN\name>]
            [-ownername <display name>]
            [-secondaryemail <someone@example.com>]
            [-secondarylogin <DOMAIN\name>]
            [-secondaryname <display name>]
            [-lcid <language>]
            [-sitetemplate <site template>]
            [-title <site title>]
            [-description <site description>]
            [-hostheaderwebapplicationurl <web application url>]
            [-quota <quota template>]

When creating a new site collection, be sure that the top level site either does not have a site template (omit the –sitetemplate switch), uses the blank site template, or uses the same site template as the exported site.

Import the Site

The content migration package can be imported to the same site collection as the original site, a new site collection, or even a new farm.

To view the options for importing a site:

 C:\>stsadm -help import

stsadm.exe -o import
           -url <URL to import to>
           -filename <import file name>
           [-includeusersecurity]
           [-haltonwarning]
           [-haltonfatalerror]
           [-nologfile]
           [-updateversions <1-3>
               1 - Add new versions to the current file (default)
               2 - Overwrite the file and all its versions (delete then insert)
               3 - Ignore the file if it exists on the destination]
           [-nofilecompression]
           [-quiet]

To run the import:

 C:\>stsadm –o import –url https://url/to/new/site -filename c:\exportfile.cmp 
–includeusersecurity 

Congratulations, you have now created a copy of your site.

To move a site, you can now delete the original site, and be sure to let all site members know the new url.

Creating a Reusable Template

An easy way to create a reusable template is to choose "Save site as template" from the Site Settings page. If the save site as template method meets your needs, you should use it, since it is simple and doesn't require box admin privileges to create or use the template.

In some cases, the save site as template method will not meet your needs. For example, site templates have a maximum file size (10 MB by default, increasable to 500 MB) and cannot be created from publishing sites, such as the Publishing Portal. In these cases, you can use content migration to achieve similar functionality.

Steps:

  1. Create the template site and make all desired changes
  2. Export the site as described above, but without the includeusersecurity switch
  3. To create a site from the template, Import the site as described above

Changing the Site Definition of an Existing Site

As you might know, it is not possible to change the site definition of a site after it is created. In many cases this is not a problem, because you can often activate feature to give a site functionality that is usually found on a different site definition.

However, there are times when you may want to change the site definition, such as to enable functionality that is hard coded to a site definition (such as the metaweblog APIs on the BLOG definition), or to move a site from a custom site definition to an OOB definition.

With content migration you can export a site, edit the package to change the site definition, and then import the package into a new site with that definition.

Steps:

  1. Export the site with the nofilecompression switch, so that the package will be easy to modify
  2. Edit the content migration package
    1. Change the WebTemplate property of the web to indicate the new site definition
    2. Update the SetupPath properties of any files that came from the old site definition
  3. Delete the old site
  4. Import the package into a new site at the same url as the old site

Export the Site

Export the site as described above, but include the nofilecompression switch so that the site will be exported to a folder. This enables you to avoid the steps of decompressing the cab file and recreating the cab file.

To run the export:

 C:\>stsadm –o export –url https://url/to/site -filename c:\exportfolder –includeusersecurity –versions 4 -nofilecompression


Edit the Content Migration Package

Browse to the folder specified above. The folder will have many dat files which represent the files from the site including views, forms, pages, and documents.

The file Manifest.xml stores all of the properties and metadata about the site, lists, and items. Open it using Notepad or Visual Studio.

For more information, see: Working with a content migration package.

Change the WebTemplate property

Find the WebTemplate attribute of the Web element for the site you want to change and change it to the name of the new Site Definition. Repeat this for any other sites that you would like to change to a new definition.

 <Web Id="bef0732d-8270-4029-bc19-02908c8334fe" Name="" Description="" 
Locale="English (United States)" CurrencyLocaleId="1033" Language="1033" 
TimeZoneId="78" Time24="false" CalendarType="1" AdjustHijriDays="0" 
Collation="25" RegionalSettingsLocaleId="1033" AlternateCalendarType="0" 
ShowWeeks="false" FirstWeekOfYear="0" WorkDays="62" WorkDayStartHour="480" 
WorkDayEndHour="1020" FirstDayOfWeek="0" Configuration="0" PresenceEnabled="true" 
SyndicationEnabled="true" QuickLaunchEnabled="true" TreeViewEnabled="false" 
ParserEnabled="true" Provisioned="true" ParentId="00000000-0000-0000-0000-000000000000" 
IsRootWeb="true" Title="test" ServerRelativeUrl="/sites/test" WebTemplate="BLOG" 
AlternateCssUrl="" CustomizedCssFiles="" CustomJSUrl="" IncludeSupportingFolders="false"
RootFolderId="fe983ea4-f376-4b86-bc64-f6f9875dbd68" SystemCatalogsIncluded="true" 
SecurityProvider="00000000-0000-0000-0000-000000000000" 
MasterUrl="/sites/test/_catalogs/masterpage/default.master"
CustomMasterUrl="/sites/test/_catalogs/masterpage/default.master" 
Created="2007-02-21T22:20:32Z" Author="1" SiteLogoDescription="" 
HasUniqueRoleDefinitions="true" HasUniqueRoleAssignments="true" 
RequestAccessEmail="administrator@litwareinc.com">

            

Change the SetupPath properties.

The SetupPath is the location on the file system where the original file lives, for files that were created from a site definition. This location is important because if a file has not been unghosted, meaning that it has not been modified in SharePoint Designer (or other similar application), the actual file from the file system is displayed (for improved performance).

Also, if a file has been modified, when the user selects "reset to site definition", it resets the file to the one found at the setup path.

If you are changing a site from one default template to another, you may not want to modify the setup paths.

If you are changing a site from a custom site definition to a default template, you may want to update the setup paths so that the pages will point to the files from the default definition and not the custom definition.

If you have upgraded a V2 custom site definition and want to move to V3 default definition, you can use the mappings in 12\config\upgrade\wssupgrade.xml to help you determine the correct new setup paths. Also, be sure to update the SetupPathVersion attribute.

 <SPObject Id="6752a91b-811f-49eb-8dbd-38479ba21b23" ObjectType="SPFile" 
ParentId="1e992cab-0a5e-46ba-bcda-95144d66cd78" 
ParentWebId="bef0732d-8270-4029-bc19-02908c8334fe" ParentWebUrl="/sites/test" 
Url="/sites/test/_catalogs/lt/Forms/AllItems.aspx">
<File Url="_catalogs/lt/Forms/AllItems.aspx" Id="6752a91b-811f-49eb-8dbd-38479ba21b23"
ParentWebId="bef0732d-8270-4029-bc19-02908c8334fe" ParentWebUrl="/sites/test"
Name="AllItems.aspx" ListId="7ac7eef1-ca61-4ec3-9d16-146b2ba02892" 
ParentId="1e992cab-0a5e-46ba-bcda-95144d66cd78" 
TimeCreated="2007-02-21T14:20:37" TimeLastModified="2007-02-21T14:20:37" 
Version="1.0" IsGhosted="true" 
SetupPath="pages\viewpage.aspx" SetupPathVersion="3" 
SetupPathUser="1073741823" FileValue="00000000.dat">
<WebParts>
<WebPart Name="44a44ab9-1680-4d1f-912d-ae6036c4637f" Flags="1" 
Hidden="false" Threaded="false" ReadOnly="false" 
RecurrenceRowset="false" FPModified="false" ModerationType="" 
Personal="false" OrderedView="false" 
ListId="7ac7eef1-ca61-4ec3-9d16-146b2ba02892" Version="1" 
DisplayName="All Templates" BaseViewID="1" Level="major" 
WebPartZoneID="Main" 
WebPartTypeId="2242cce6-491a-657a-c8ee-b10a2a993eda" 
IsIncluded="true" WebPartOrder="1" Type="0" FrameState="0" />
</WebParts>
</File>
</SPObject>


Delete the Old Site

If you want the new site to have the same URL, you will have to delete the existing site.

First, make a backup of the site using SQL or SharePoint:

 C:\>stsadm -help backup

For site collection backup:
    stsadm.exe -o backup
        -url <url>
        -filename <filename>
        [-overwrite]

For catastrophic backup:
    stsadm.exe -o backup
        -directory <UNC path>
        -backupmethod <full | differential>
        [-item <created path from tree>]
        [-percentage <integer between 1 and 100>]
        [-backupthreads <integer between 1 and 10>]
        [-showtree]
        [-quiet]

Next, if the site is the top level site, record the site collection level settings such as the quota and site collection administrators.

Next, delete the site.

 C:\>stsadm -help deleteweb

stsadm.exe -o deleteweb
           -url <url>

Finally, if the site was a top level site, create a new site collection and apply the settings, being sure to omit the sitetemplate switch.

 C:\>stsadm -help createsite

stsadm.exe -o createsite
            -url <url>
            -owneremail <someone@example.com>
            [-ownerlogin <DOMAIN\name>]
            [-ownername <display name>]
            [-secondaryemail <someone@example.com>]
            [-secondarylogin <DOMAIN\name>]
            [-secondaryname <display name>]
            [-lcid <language>]
            [-sitetemplate <site template>]
            [-title <site title>]
            [-description <site description>]
            [-hostheaderwebapplicationurl <web application url>]
            [-quota <quota template>]


Import the Site

Import the site as described above, but include the nofilecompression switch so that the site will be imported from the folder. This enables you to avoid the steps of decompressing the cab file and recreating the cab file.

To run the import:

 C:\>stsadm –o import –url https://url/to/new/site -filename c:\exportfolder
                
–includeusersecurity 

Summary

Hopefully this has provided you with helpful information, and a sense of how powerful the content migration APIs are. Please let me know any feedback or questions you have.

Jackie