SpsDev.Com's Import / Export Tool is new for Microsoft SharePoint 2007.  It allows you to select items within a site - from an entire list or document library, down to individual list items or documents - and export them from one list or site and then import them into another.  Along the way you have total control over how the data is moved around.

There are three main components to this application:

• The Import / Export Tool is a Windows application that must be run on the SharePoint server.  You can use the rich graphical interface to select items for export, perform exports, explore an export file, mapped exported items to new destination sites, libraries, and lists, and perform imports.  This is installed by default.
• The Admin Pages is a SharePoint solution that when deployed and activated, adds additional menu items to the Site Administration section of each site’s settings page.  It includes one page for doing exports and another for doing imports.  This requires you to perform additional steps once setup is complete, which are explained in the readme file that was installed with the product.
• A reusable component that your developers can use to simplify adding import and export capabilities to custom applications.  The sdImpExpData component is used by our own Import / Export tool as well as Admin Pages.  We have included a sample application with complete source code to help demonstrate how to use the object model.  We have also included a document called ObjectModel.doc which documents the object model’s class, methods and properties.

Exporting Data - Windows Application

The Import / Export Tool has a simple application interface to make it easy for you to select what items to export, and what options to use as part of that export.  You start by entering the Url to the site that contains the data from which you wish to perform the export.  When you click the List Object button, our Import / Export tool will quickly interrogate the site to find all of the lists and libraries within that site, along with all of the folders and items in each one as well. With a simple point and click interface, you select which of these items, or hierarchy of items that should be exported.

Simply select the lists, folders, items, and/or documents that you want to export, tell us the filename to which the export should be saved and click the Export button - that's all there is too it.  We export not only the items, but also the metadata associated with those items. If you want some additional control during the export or import process though, you can have it.  Just click the Settings button to configure the details of your request:

There are three kinds of settings - Common Settings, Export Settings and Import Settings.

Common Settings

Common settings include:

• Log export activity - if you check this box, a log file will be created to record all import and/or export activity.  If there are any issues during the import or export process you should choose this option to create a log file of what is happening so that it can be examined by the SpsDev.Com development team.
• Log File - this is the name of the file that will be created (if it doesn't exist) or appended to with information regarding an import or export process.
• Stop on non-fatal errors - if you check this box then the import or export will stop on all errors, even non-fatal ones.

Export Settings

Export settings include:

• Export Security - when you do an export you can choose whether the security associated with items is exported as well.  You can export with the Groups, Users and custom user information that you may have updated in the site, or just the Groups and Users that have security rights to the items, or no security at all.
• Export Versions - by default when you export items or documents, the Import / Export Tool will export the last major version only.  Alternatively, you can configure it to export All versions, just the current version, or the last major and minor version.

Import Settings

Import settings include:

• Ignore WebParts - if this box is checked then web parts will when importing pages.  Normally it is unchecked.
• Retain GUIDs - if you have an application built in SharePoint that is expecting a specific GUID for a page or item then you should check this box.  Normally it is unchecked.
• Suppress event handlers during import - check this box if your destination list or library includes event handlers that fire on the creation or update of documents, and you don't want them to fire during the import process.
• How to Handle Versions - when you import files you have a choice in what happens when a file with the same name already exists.  You can overwrite the current version, append a new version, or just ignore the versions and write the file.
• User Info for Imported Items - when you import items you can control what information is used for fields such as "Created By" and "Modified By".  You can retain the original author and publishing date information, you can have it set to the current user performing the import and use the current date, or you can keep the original publishing date but change the user to be the System Account.

Importing Data - Windows Application

Importing data with the Import / Export Tool is just as easy as exporting.  Just tell us the name of the file that contains the exported information.  We'll crack it open and explore the contents so we know what's in it:

Begin by entering the Url to the site into which you are going to import the contents in the Destination Site edit box.  If the export file contains list items or documents, you can optionally choose for each one the destination list or library into which they should be imported.  To map an item, click the Get Site Info button after you have entered the Destination Site Url.  It will query the SharePoint site and fill the Lists and Libraries drop down with all of the list, libraries and folders in the site.  You can check one or more items in the list of items to be imported, select the destination list, library or folder into which it should be imported, then click the Map Item button.  You can map different items to different destinations, and change existing mappings by selecting them, select the new destination, and clicking the Map Item button again.  If you want to start the mappings over again just click the Explore File button.

If you don't create a mapping for an item then we'll just try to import it into a list or library with the same name from which it was exported.  Once you've configured any import mappings just click the Import button and your data will be imported into the site you've specified in the Destination Site edit box.

Exporting Data - Admin Pages

After you have added and deployed the sdImportExportWeb.wsp solution, and activated the SpsDevImpExp feature, you will have two new menu items in the Site Administration section of the Site Settings page:

If you click on the Export Items link you will see a page that looks like this:

To begin the export process, click the Find Items button.  It will enumerate all of the lists, libraries, folders and items in the site.  It then displays the list of items and exposes the Export button, as shown in the picture below:

Select each item that should be exported by clicking the box next to the item's name.  If an item has a plus sign next to it, click it to expand the item and see all of the additional items that it contains.  Once you have selected all of the items for export you can fill in the export configuration Options.  The Options are:

• Export File: provide the name of a file share and file name where the export should be saved.  The application pool account that the SharePoint web application is using must have at least Change rights on this share.  If you aren't sure what account the application pool is using you can ask your SharePoint administrator or just try to do the export.  If it can't save the file because it doesn't have rights, it will tell you what account it is using to try and save the export file.  This field is required.
•  Log File: provide a name in the same format and with the same permission requirements as for the Export File setting.  If you enter a value in this field then a log file will be created that reports on every step of the export process.  This field is not required.
• Export Security: select the amount of security information that should be included with the export.  The options are:
  • All - Includes user memberships and role assignments such as out of the box roles like Web Designer, or any custom roles that extend from the out of the box roles. The ACL for each object is migrated. In addition, user information defined in the DAP or LDAP servers is included.
  • Groups and Users - Includes user memberships and role assignments such as out of the box roles like Web Designer, or any custom roles that extend from the out of the box roles. The ACL for each object is migrated. No user information defined in the DAP or LDAP servers is included.
  • None - no security information is included in the export.
• Export Versions: select the version information for items that should be included with the export.  NOTE: At the time this version of the SpsDev Import / Export Tool was shipped, there is a bug in the SharePoint 2007 export API in which documents that have versions do not properly retain the Author information when imported.  Instead, all versions use the same Author as the last published version.  If you are experiencing this problem please contact Microsoft for a fix.  The options are:
  • All - All versions of items are exported.
  • Current Version - Only the current version of items are exported.
  • Last Major - Only the last Major version is exported.
  • Last Minor - Only the last Minor version is exported.
• Halt on non-fatal Errors: if you check this box the export will be stopped on any error, whether it is fatal to the export process or not.
• Overwrite File: if you check this box and an export file already exists at the same location as you entered in the Export File field, it will be overwritten.  If it exists and this box is not checked then it will generate a fatal error and the export will not continue.

After you have selected the items for export and provided all of the export configuration Options, click the Export button.  This may take a long time depending on how many items you are exporting.  If you select too much content, the operation in the Admin Pages may time out, and require you to use the Import / Export tool or a custom application that utilizes the sdImpExpData object to do the export.

If the export completes, successfully or otherwise, a message will be displayed near the top of the page that informs you whether it worked.  If it did work, it will also tell you the name of an Xml file that it created that will need to be used when you import the data from the export file that was just created.

Importing Data - Admin Pages

After you have exported data, you can use the Import Items page to import the data into a different list or library in the same site, or a different site altogether.  Begin by navigating to the site where you wish to import the data, and select the Site Settings...SpsDev.Com's Import Items menu.  It will display a page that looks like this:

Following are the import configuration options:

• Import Xml:  When you export data with the SpsDev.Com Export Items page, it created a CAB file that contains the exported data, and an Xml file that describes the data and is used during import.  In this field, you must paste in the Xml from that file, including the mappings you have added to that file for each item being imported.  The file structure looks like this:

All of the Xml shown above is included in the file that is created at export time, except for the value in the ParentUrl attribute.  The ParentUrl attribute is where you enter the location into which the item should be placed when imported.  Please note that all locations must be in the same site collection - you can't map a single import to multiple site collections.  For individual items, enter the fully-qualified Url to a list or library.  For list or libraries, enter the fully-qualified Url to the site collection where the item should be imported. This field is required.

• Exported CAB File: enter the file share and file name where the export file is that will be imported.  As described in the Exporting Data - Admin Page section, the application pool account for the SharePoint web application that hosts the site collection into which the data is being imported must have at least Read rights to this file share (Change rights is required if you enter a Log File). This field is required.
•  Log File: provide a name in the same format and with the same permission requirements as for the Export File setting.  If you enter a value in this field then a log file will be created that reports on every step of the export process.  This field is not required.
• Versions: select the versions should be treated during import.  The options are:
  • Append - append versions from the import to any existing versions of the same item(s)
  • Ignore - ignore the item if an existing item with the same name exists
  • Overwrite - overwrite all existing versions with the new item and its versions
• User Info: select the user information that should be stamped on imported items.  The options are:
  • Retain Authors and Dates - The original item author and date will be preserved on the items when they are imported.  NOTE: As described in the Exporting Data - Admin Page section, at the time this version of the SpsDev Import / Export Tool was shipped there is a bug in the SharePoint 2007 export API in which documents that have versions do not properly retain the Author information when imported.  Instead, all versions use the same Author as the last published version.  If you are experiencing this problem please contact Microsoft for a fix.
  • Use Current User and Date - the name of the user performing the import and the current date and time will be stamped on the items as the creator and create date.
  • Use System Account - the System Account will be listed as the creator, and the current date and time will be stamped as the create date.
• Halt on non-fatal Errors: if you check this box the export will be stopped on any error, whether it is fatal to the export process or not.
• Ignore Web Parts: if you check this box then the import will ignore web parts present on any publishing pages. This is primarily used only in Variations.
• Retain GUIDs: if you check this box then the GUIDs that were used for the items in the source site are maintained when the items are imported into the new site.  Note that this will not work if you are importing items within the same site.
• Suppress Event Handlers: if you check this box then all event handlers that would normally fire when the data is created will instead be suppressed.

After you have provided all of the import configuration options, click the Import button.  This may take a long time depending on how many items you are exporting.  If you select too much content, the operation in the Admin Pages may time out, and require you to use the Import / Export tool or a custom application that utilizes the sdImpExpData object to do the import.

If the import completes, successfully or otherwise, a message will be displayed near the top of the page that informs you whether it worked.

Known Issues

During the course of our own testing we have found a number of issues or anomalies that you may also experience when using the tool.  These are not bugs in the product, but either nuances in the way the import / export features work in SharePoint, or bugs in the SharePoint import / export interfaces themselves.  We will keep a list up to date right here - please check these issues first before filing a bug report with SpsDev.Com.

A: It will work fine. A new list or library will be created with the same name as the one the items were exported from, and they will be imported into it.

A: You will not lose the metadata. The metadata will be added to the list or library that you import the items into. It won't show up in the default view however, but if you view the properties for an item you will see it. You can also add the metadata properties to any view after that point so that it can be seen in the default page for list or library.

A: You may encounter an error during import if it contains both list items and documents. We recommend doing them separately if you encounter issues.

A: This is a bug with the SharePoint import /export API. Please contact Microsoft to report the issue and obtain a fix.

A: You may see this error if you export an item that contains metadata from a content type that includes a calculated site column. This occurs because of a limitation in the SharePoint import / export API.

A: This occurs because of a limitation in the SharePoint import / export API. Please contact Microsoft if you would like this feature included in the future.

A: This occurs because of a limitation in the SharePoint import / export API. Please contact Microsoft if you would like this feature included in the future.

A: This occurs because of a limitation in the SharePoint import / export API. Please contact Microsoft if you would like this feature included in the future.

A: This is a bug with the SharePoint import /export API. Please contact Microsoft to report the issue and obtain a fix.

A: This is an issue with the SharePoint navigation. Normally if you wait a few moments or do an IISRESET it should fix the problem.

A: You will get a successful import message even if the entire import did not succeed. The SharePoint Import API returns success if only part of the import worked; if part of it failed it does not tell you what failed - it only says that it worked.

A: The metadata will show the value when you go into View Properties, but not in the default view. But the metadata field is added to the list or library so you can add it to a view and start using it.

A: This error occurs when you include escape characters in the ParentUrl attribute for an item. In the example above, the escape characters are "%20", which represents a space. Instead just use the actual character, such as a space in this example, and try again.

A: This error may occur even when you have the Import settings configured to overwrite a version. It is likely that you are trying to import to a library that was created by the Publishing feature for the site collection. You may be able to work around this problem by checking out the target document first and then importing your data, or else deleting the target item altogether. Unfortunately SharePoint is inconsistent in how it handles this situation.