Content Migration: Importing Content
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 is a two-step process. First, you export content from the source to a migration package, and then you import the migration package to the destination.
Overview of the Import Operation
The flowchart below illustrates the conceptual flow of a typical import operation using the migration APIs in the Deployment namespace. On the surface, importing content is simply the reverse of the export. That said, there is a more complex flow and a greater number of decision points in the import operation.
Selective Migration: Export Flowchart
.gif)
When specifying your import settings (SPImportSettings), ensure that you match the corresponding export settings (SPExportSettings). For example, if the FileCompression property on the SPExportSettings object is set to true, the corresponding FileCompression property on the SPImportSettings object must also be set to true.
The process flow presents decision points at which the flow branches. The first decision point is whether to retain the identity of your objects. This property setting determines whether the import object is located by object GUID (if retaining object identity) or by URL. (For more information about object identity and other migration concepts, see Key Concepts in Selective Migration.)
The next decision point pertains to reparenting. If the object is a top-level object in the hierarchy, and if you are not retaining object identity, then you must reassign a parent object. If, on the other hand, this is not a top-level object and you are not retaining object identity, then reparenting is not required.
If the operation fails to locate the import object, a new one is created. However, if the object is located, and if you simply moving the object (as in a copy/move operation), the operation assigns the object a new URL. If this is an update (a file update, for example), the operation keeps the original URL.
Import Settings (SPImportSettings) Properties
The SPDeploymentSettings class serves as the base class from which both SPExportSettings and SPImportSettings are derived. Its members, then, are inherited by both of the these derived classes, while the SPImportSettings class contains specialized import-related members.
Properties on the Microsoft.SharePoint.Deployment.SPImportSettings class, plus those of the base class, fall into four groups:
Required: Property settings that are required for import.
Important: Property settings that are of high importance and that you should be consider in your import planning.
Selective-related: Property settings that are specifically related to import operations in a selective migration.
Minor: Minor or rarely used property settings.
Required import settings
-
Sets or retrieves a GUID that identifies the import destination site.
-
Sets or retrieves a URL that locates the import destination site.
BaseFileName (inherited from Microsoft.SharePoint.Deployment.SPDeploymentSettings)
Sets or retrieves the name of the content migration package (.cmp) file, or files. These consist of one or more .cab files (using the .cmp file extension). The value is taken from the baseFileName parameter on the SPDeploymentSettings class constructor (SPDeploymentSettings).
When there are multiple .cmp files, the file names are appended numerically. For example, where the baseFileName parameter is "MyWeb", and where the export operation produces multiple .cmp files, the migration packages are named "MyWeb1.cmp", "MyWeb2.cmp", and so forth.
SiteUrl (inherited from Microsoft.SharePoint.Deployment.SPDeploymentSettings)
Sets or retrieves the URL of the destination site collection on import. The value is an absolute URL to the site. This value is provided in the siteUrl parameter of the SPDeploymentSettings class constructor (SPDeploymentSettings).
FileLocation (inherited from Microsoft.SharePoint.Deployment.SPDeploymentSettings)
Sets or retrieves the file path and directory location where the conten migration package (or packages) are placed on the import destination. This value is provided in the fileLocation parameter of the SPDeploymentSettings class constructor (SPDeploymentSettings).
Important import settings
-
Sets or retrieves a value from the SPImportUserInfoDateTimeOption enumeration that specifies the level of user information to retain on import. The allowable values are:
ImportAll: Retains all of the original author and editor information, including date/time stamp and user lookup values.
None: (Default) Replaces the author and editor data with the System Account; creates a current (time of import) date/time stamp, and replaces user lookup values with an empty string ("").
ReplaceUserWithSystemAccount: Retains the original date/time stamp, but replaces the author and editor data with the System Account, and replaces user lookup values with an empty string ("").
The default falue is None.
-
Sets or retrieves a value from the SPUpdateVersions enumeration that specifies the handling of versioning information on import:
Append: Appends versioned items on import.
Overwrite: Deletes the existing item on import, then reinserts the imported version.
Ignore: Ignores versioning.
CommandLineVerbose (inherited from Microsoft.SharePoint.Deployment.SPDeploymentSettings)
Retrieves or sets a Boolean value that specifies whether you want migration information outputted to a command line console. The default value is false.
FileCompression (inherited from Microsoft.SharePoint.Deployment.SPDeploymentSettings)
Retrieves or sets a Boolean value that specifies whether the content migration package is compressed using the CAB compression protocol. The default value is true; the default is for the content migration package to be compressed.
The import setting for this property must match that provided on the SPExportSettings.FileCompression property.
IncludeSecurity (inherited from Microsoft.SharePoint.Deployment.SPDeploymentSettings)
Retrieves or sets a SPIncludeSecurity enumeration value that specifies the amount of user security roles and role membership data to include in the migration package. The enumeration provides three options: All, None, and WssOnly. The value selected must match that provided on the SPExportSettings.IncludeSecurity property
LogFilePath (inherited from Microsoft.SharePoint.Deployment.SPDeploymentSettings)
Retrieves or sets a value that specifies the fully qualified path to the log file for the content migration operation.
Selective migration-related import settings
-
Sets or retrieves a Boolean value that specifies whether to retain identifying object GUIDs during import. Setting this to true directs the import to retain object GUIDs; the default value is false.
SPImportSettings.RetainObjectIdentity is the lynchpin of selective migration, because the core concept is importing updated versions of existing files. The only way the destination knows that an item is an updated version of an existing item is to compare object identity using object GUIDs.
Because databases do not permit duplicate GUIDs, you should be careful when implementing this property. It is only useful in selective migration scenarios. Furthermore, to support field deletion (which deletes previous versions of items at the export source when they are updating and deleting the same file at the import destination), this value must be set to true. Note, too, that to support selective migrations you must set the ExportMethod property to a field value of ExportChanges.
Minor import settings
-
Sets or retrieves a Boolean value that determines whether the import operation ignores Web Parts associated with a file. Set to true to disable importing Web Parts; the default value is false.
Note that this property is used primarily to support the Variations feature in CMS.
-
Sets or retrieves a Boolean value that determines whether the migration operation ignores After events that are fired when files or list items are created or modified. Set to true to ignore After events; the default value is false.
Supressing the handling of After events can increase performance slightly during import. Furthermore, even if performance is not a concern, setting this value to true helps avoid potential problems resulting from event handler errors.
HaltOnWarning (inherited from Microsoft.SharePoint.Deployment.SPDeploymentSettings)
Sets or retrieves a Boolean value that specifies whether to suspend the migration when a warning is encountered. Set to false to ignore warnings and continue the migration. The default is false.
HaltOnNonfatalError (inherited from Microsoft.SharePoint.Deployment.SPDeploymentSettings)
Sets or retrieves a Boolean value that specifies whether to suspend the migration when an error (nonfatal) is encountered. Set to false to ignore nonfatal errors and continue the migration. The default is false.
See Also
Concepts
Key Concepts in Selective Migration