Selective Content Migration
This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
Content migration covers two general areas: full content migrations as well as incremental, or "selective," content migration. A full migration is the migration of an entire SharePoint site or site collection as a content migration package (or packages) to create a mirror image of the original site collection on a new server. Selective migration, on the other hand, refers to any of several content migration scenarios in which specific content items on the source site are selectively packaged for migration on the basis of specified criteria and custom logic. Selective migration involves using the content deployment and migration APIs located in the Microsoft.SharePoint.Deployment namespace.
Content Migration Overview
Many scenarios require moving content from one SharePoint site to another. When the scenario calls for a full migration (that is, moving the entire contents of a SharePoint site or site collection), the task is relatively simple. Typically, you use either of two main approaches:
Use the export and import operations in the Stsadm.exe utility to migrate data from one site to another. For more information, see Using Stsadm.exe to Migrate Site Data.
Alternatively, you can use SOAP calls to the ExportWeb and ImportWeb methods that are implemented on the Sites Web service to migrate data from a remote server.
However, both of these methods have limitations. Both limit you to migrating only a full SharePoint site, or site collection. In addition, neither allows you to retain object identity during the migration operation. Retaining object identity is an essential feature of selective migration. Using Stsadm.exe and Sites Web service have other limitations as well.
Consequently, for content migration scenarios that require you to export only selected content, or that require you to automate or customize migration operations, there is only one approach: you must write a custom solution that uses the APIs in the Microsoft.SharePoint.Deployment namespace.
Important
Selective migration requires that you have performed a full content migration first, so that the destination is a mirror image of the source.
Selective migration applies, typically, to content that needs to be migrated from server to server based on factors such as content version (current versus future), time stamp, and content state (approved versus in review, for example). Selection criteria provides a high degree of granularity from the scope of the site collection down; that is, you have selection control at the scope of the Web, the list, folder, and list item.
You can have any number of .cmp files in a migration operation, and you can also have multiple destinations. However, the objects contained in a given content migration package (.cmp) file must originate from a single site collection.
Migration Scenarios
The APIs in the Microsoft.SharePoint.Deployment namespace provide a rich migration toolbox that gives you an enormous degree of flexibility to support wide ranging migration scenarios. Following is a list of migration and deployment features that are supported in Windows SharePoint Services 3.0. This list is only a high-level, generalized summary of supported migration scenarios. The Deployment APIs are sufficiently rich to support any number of special circumstances that you might face.
Export an entire site collection (that is, do a full migration).
Export a specific site inside a site collection, including or excluding content in subsites as needed. The deployment APIs allow you to include or exclude dependencies.
Export a SharePoint list or document library, or even of a specific folder inside a document library.
Export a single list item or document from a document library. This provides the extreme migration granularity that enables so much flexibility.
Export object dependencies like images or attached files.
Generate your export file as a compressed export (.cmp) package, or as uncompressed files.
Throttle exports by specifying a maximum size for the compressed export package file (multiple export files will be created if required).
Support incremental exports of items that are selected for export based on change tokens. This allows you to automate exporting all items that have been created, changed, or deleted after the timestamp specified in the change token.
Import the exported content with or without preserving object identity—that is, you can configure objects in the export package to retain their object GUID. This is a requirement for selective migrations.
Import the migration content under the same or a different parent in the destination content database. Moving items to a different position in the site hierarchy is an operation is known as reparenting.
Do link fixup during import.
Migration Planning
We cannot stress enough the importance of advance planning for your selective migration jobs. When structuring your selective migrations, you need to ask some key questions to you help clarify exactly what data needs to be migrated:
What site objects do we need to migrate?
How frequently do we need to migrate these objects?
Do some content object need to be migrated on a different schedule than others?
What items do not ever need to be migrated?
What contingencies and edge cases could affect our planning assumptions?
Most planning issues require setting values for the export settings (SPExportSettings). Following are considerations that affect your migration:
Versions (IncludeVersions property on the SPExportSettings object).
Decide whether your migration is going export only the latest major version of the specified file (this is the default), or whether instead to export only the current version, all versions, or only the last major and its minor versions. Following are the allowable values for the IncludeVersions property.
All |
Exports all existing versions of selected files |
CurrentVersion |
Exports only the most recent version of selected files |
LastMajor |
Default value. Exports only the last major version of selected files |
LastMajorAndMinor |
Exports the last major version and its minor versions |
The requirements of you application dictate which value is appropriate. However, if the migration is done on a recurring schedule, and if performance is a consideration, the best option may be CurrentVersion. Setting the value to All incurs a significant performance drag.
Security groups and roles (IncludeSecurity).
It is generally not necessary, nor performant, to include security group and roles data in a selective migration scenario. While migrating this data during the initial setup and migration of the destination site is appropriate, exporting this data when running selective migrations will slow down the migration.
The exception, of course, is when there are changes detected to security data. Your application logic should detect this and configure this property appropriately. Note that the IncludeSecurity property calls into the SPIncludeSecurity enumeration, which provides three allowable values. The default is None, which provides that no security data is migrated.
All |
Specifies the export of user memberships and role assignments such as out of the box roles like Web Designer, plus any custom roles that extend from the out of the box roles. The ACL for each object is exported to the migration package, as well as user information defined in the DAP or LDAP servers. |
None |
Default value. No user role or security group information is exported. |
WssOnly |
Specifies the export of user memberships and role assignments such as out of the box roles like Web Designer, plus any custom roles that extend from the out of the box roles. The ACL for each object is exported to the migration package; however, user information defined in the DAP or LDAP servers is not exported. |
Planning for Performance
Several of the export and import settings that are discussed below can potentially affect the performance of your migration operations. While fine-tuning for performance might not provide large percentage performance gains, in the case of very large migrations you might realize significant improvements.
Not using file compression improves the performance of your export and import oprations by roughly thirty percent. File compression is enabled by default, so you will need to explicitly change the FileCompression property on both the SPExportSettings and SPImportSettings (both derived from the FileCompression property on the SPDeploymentSettings class).
Setting SuppressAfterEvents on the SPImportSettings object to true (the default is false) causes the import operation to ignore After events. provides a minor performance gain.
Setting the IncludeVersions property to false on the SPExportSettings object obtains a minor performance gain. This is less so for this property on the SPImportSettings object.
Setting the IncludeSecurity property to false on the SPExportSettings object obtains a performance gain. This is less so for this property on the SPImportSettings object. Note, however, that you should never set this property to false when user data is exported (although this is generally not the case during selective migrations).
During selective migrations, a great deal of performance is consumed by the process of selecting export objects. If your export includes a large number of export objects, you will see a decline in performance.
You can also obtain minor performance gains if on import you set the CommandLineVerbose and the LogFilePath properties to false. This is particularly true on the SPImportSettings object.
See Also
Concepts
Key Concepts in Selective Migration