Share via

SharePoint Content Migration Object Model and Content Migration Packages

  • Article

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

Comments

  • Anonymous
    February 26, 2007
    If you are utilizing the WCM features of MOSS, you MUST check out this post. Good job Jackie!! &lt;/steve&gt

  • Anonymous
    March 07, 2007
    hi, if i would like to move a sub site and make it a top level site, is this possible. i can me reached at chongtingfong@gmail.com thanks & regards, tingfong

  • Anonymous
    March 21, 2007
    Where does stsadm -o export get the credentials?  How do you specify credentials for a remote site?

  • Anonymous
    April 10, 2007
    can we activate and deactivate sharepoint feature programatically ?? thanks a lot. Sanjay Tiwari www.SuperShaadi.com

  • Anonymous
    June 04, 2007
    Hi, I am trying to share some content between an intranet site and an internet website,which are in the same server but are different site collections and different web applications.Any ideas how I can do the shareing? Thanks, MRB.

  • Anonymous
    August 02, 2007
    The export command is not working on a subsite. The cmp is only 6 Kb and the import does not import any content or structure.

  • Anonymous
    August 10, 2007
    Content deployment works well when a clear connection between the source farm and the destination farm

  • Anonymous
    September 18, 2007
    The comment has been removed

  • Anonymous
    October 04, 2007
    For the file size not being the right size. Make sure you are logged into the server with the sitecollection administrator account. That will give the access required to navigate the enitre site during export.

  • Anonymous
    January 09, 2008
    Today I gave Microsoft InTrack presentation about SharePoint deployment. This was the agenda: Content

  • Anonymous
    January 09, 2008
    Today I gave Microsoft InTrack presentation about SharePoint deployment. This was the agenda: Content

  • Anonymous
    March 19, 2008
    I tried this but the import always fails because I changed the webtemplate from STS to CMSPublishing but for some reason the import always tacks on #1 at the end. So it makes the template be CMSPublishing#1 not CMSPublishing#0 as it should be. The Manifest file only contains STS when the true template is STS#1 if I change the webtemplate to CMSPublishing#0 then it try to import it to CMSPublishing#0#1 so the import always tacts on that #1 from  the old template.. where in the manifest file can I change the #1 to #0? Also I can't read all your blog some of the text is cut off in the middleframe and you can't scroll over.

  • Anonymous
    March 24, 2008
    Pingback from IT-Dev obieg dokumentow! Great article about Sharepoint content deployment API!

  • Anonymous
    April 10, 2008
    is there anyway to change existing site template to another site template like collabration without losing data? thanks

  • Anonymous
    July 29, 2008
    I've migrated a site collection using the same stsadm commands and works great excepting lists that have lookup fields. This kind of fields keep the original list id, so in a progressive development or mantain, it's impossible to change its values. Do you realiazed that problem??

  • Anonymous
    August 12, 2008
    Hi,  Is it possible to archive the contents in one pages library to another pages Library in another SiteCollection using Content Migration API.

  • Anonymous
    September 04, 2008
    Are you aware of any package solutions for purchase that perform backup and restore of a site or entire site collection? One of our additional criteria is that the Site Definition used to create the source site (Development) has been updated in the target location (Production). Thanks, PF

  • Anonymous
    April 15, 2009
    puedo migrar contendio del componente MyContent de joomla 1.0 a sharepoint. y si puedo como lo hago saludos el_doctor55@hotmail.com ese es mi correo saludos