Stefan Goßner

Senior Escalation Engineer for SharePoint Products and Technologies

Deep Dive into the SharePoint Content Deployment and Migration API - Part 5

Deep Dive into the SharePoint Content Deployment and Migration API - Part 5

  • Comments 71
  • Likes

[Part 1 - Part 2 - Part 3 - Part 4 - Part 5 - Part 6 - Part 7]

Avoiding common problem

This can be one of the most frequently updated chapters of this article series as "common problems" can change over time. In addition I can only talk about common problems I have seen so far. But let get started.

Problem 1: Mixing deployments with and without retaining object identity

First of all: if possible you should avoid this! Importing with different settings for this property into the same database can lead to serious problems during future deployment and such databases will become hard to maintain.

Be aware that this also means that you should not use STSADM -o import against a database that should be used as the destination of a content deployment job!

STSADM -o import will not retain the object identity while content deployment does.

So why is there a problem when mixing imports with different RetainObjectIdentity settings?

The reason is that with RetainObjectIdentity enabled the imported object will have to be created with the same name and the same guid at the same location in the destination database as it was in the source database. If the item already exists it will be updated. If not it will be created.

Problems occur if there is an item with the same name but a different Guid in the destination database. This can happen if someone has authored on the destination server and created items with the same name but or if he imported content from the source server WITHOUT RetainObjectIdentity setting set to true.

In case that items with the same name but different GUID are allowed for the affected item you will end up with two items with the same name on the destination server. This will be the case (e.g.) for usual ListItems.

In case that items with the same name but different GUID are not allowed for the affected item the import will run into an exception similar to the one below and stop:

Failed to create the 'Pages' library. OriginalException: There can only be one instance of this list type in a web.

=> In order to avoid this problem you have to guarantee that content added to the destination database will not have any name/guid conflicts with the source database - even if new content is added to the source database in the future!

Problem 2: Running multiple imports without retaining object identity for updates of the same content

When doing an export and import without retaining the object identity on the destination server you can end up with duplicate items in lists as each import tries to create the same list item again with a different GUID. The import is not able to decide whether you would like to overwrite an existing item with the same name or if you would like to have multiple list items with the same name. Without retaining the object identity you will end up with multiple list items with potentially the same content. To force overwrite of list items you have to retain the object identity.

That means you cannot use STSADM -o export/import as a replacement for content deployment! If you need to do deploy content to a remote destination server without connectivity you need to write a custom tool that has retain object identity enabled rather than using STSADM -o import based on the code samples provided in Part 3 of this article series.

=> STSADM -o export and import should only be used if the content being imported does not already exist in the destination database and if the database will not be used as the destination database for content deployment (see Problem 1 above).

Problem 3: delete an item from the source site that belonged to the site definition and recreate it

This is a different flavor of the problem discussed as Problem 1

During provisioning of a site items defined in the site definition template are added to the site. Problems can occur when changes are made to the provisioned items. Especially if the provisioned items are deleted and replaced with items with the same name. That approach will work well on a single server installation. But it will cause problems when using content deployment.

The reason is that during content deployment the site will be provisioned on the destination server using the site definition template. And this will also cause all items defined in this template to be created. When content deployment now tries to import the updated or replaced items there will be a conflict. You will end up with an exception similar to the one in Problem 1.

=> You should never modify or delete one of the items created through the site definition in your site. If the site definition does not suite your needs you should create a custom site definition that fits to your needs and use this instead to avoid the need to customize some of the provisioned items.

Problem 4: deploy from destination back to source

This is something that theoretically can be done but only if the source hasn't changed since it was last deployed to the destination. Otherwise the same issues as in Problem 1 can occur.

Also be aware that it will not be an incremental deployment - means you cannot just deploy the changes since you deployed from source to destination. The reason is that the timestamp information about what to deploy is stored with the deployment job. As this information only exists on the source system the first deployment from destination back to source will deploy everything! So the result would be the same as deploying into an empty site collection on the soruce system. And actually deploying into an empty site collection would be better to avoid problems in case that changes have been done on the source system.

Problem 5: deploy partial content without exporting the parent items

When deploying with retaining the object identity (as you can do with content deployment in the central admin) it is not possible to reparent items. Deployment with retaining the object identity requires that the identity of the object is the same on the destination server and the identity is defined by Id, Name and by the Url.

So the parent of each deployed object has to exist on the destination server in order to successfully import the package on the destination server. We have seen that customers are trying to export a specific subtree of the site without exporting the parents. E.g. only a specific variation label without the variation root.

If the parent of the exported objects does not exist on the importing site then the item cannot be imported and the deployment will fail.

=> Ensure that all parents of all content being exported exists on the destination server.
=> Or create a custom export tool that does not retain object identity and changes the parent during import as discussed in Part 3 but be aware about the limitations discussed as Problem 2.

Problem 6: deploy partial content with references outside the selected scope

This is similar to Problem 5 except that we assume that the parent objects of the selected object exists in the destination database. In this situation you might assume that no problems should occur. That is not correct. When exporting items in a subtree per default all referenced objects (like images or documents) will be exported as well. Even if these objects are outside the selected scope. In this situation the export package will contain objects which might not have a parent in the destination database. 

If the parent of this image or document does not exist on the importing site then the item cannot be imported and the deployment will fail.

=> Ensure that authors do not use resources from other parts of the site collection which is not being exported.
=> Or create a custom export tool that uses the ExcludeDependencies to exclude objects outside the selected export scope. See Part 2 for more details.


  • Hi,

    I am trying to export a subweb from a subweb(site/subweb1/subweb2).

    I cant make it work the way I want. I have tried 2 ways.

    1. Export all subwebs and set SPIncludeDescendants.None on all webs, except subweb2. Result: the whole site is exported, with all content (even on subweb1)

    2. Only export subweb2. Result: The subweb goes directly in the site when I import the exported file (site/subweb2).

    Does anybody have an idea on how to solv this?

  • Hi Johan,

    with SPIncludeDescendants.None for subweb1 lists of subweb1 should not be exported.

    Please double check.



  • Stefan,

    Another great addition to the deployment series. I will alert those inside the MSFT SP PRIME team about this new "common problems" section with a suggestion that they contribute content.

    Thanks again for your sharing this great info.

    NickG (MSFT)

  • Stefan,

    Extremely useful post (and series).

    Maurice Prather's <a href="">Beware of import/export</a> post also makes for interesting reading. It seems some of the problems Maurice mentions are different to those you've detailed here - are the issues in Maurice's post still known issues? Any other comments on the post?



  • Hi Chris,

    there are lots of things to take into consideration when using the deployment and migration API. Several things will be addressed in hotfixes and the upcoming service pack.

    I don't know all the issues in Maurice list - not all have passed my desk as service requests.

    I can only say: if you run into an issue, open a support call to get it addressed if possible.



  • Hi Stefan,

    This additional section helps me to understand MOSS Content Deployment. Thanks.

    Btw, another content deployment problem causes me a lot of trouble.

    I moved all images from a folder to a new create folder. After that, I deleted the old folder. It works fine on staging, but the content deployment job fails. It said the parent folder cannot be found on destination server.

    Can you help to tell me why ?

    Thanks so much

  • Hi Tony,

    this sounds like a potential problem in MOSS. Please open a support case to get this analyzed as this should not happen.



  • Hi Stefan.

    the problems about deploying from destination and back to source using normal content deployment is pretty dificult to find any info on - so your addin are greatly appreciated.

    We have a scenario where the majority of info will be edited from the inside - and deployed to the outside, wich all works fine - allthough the part about rolling out solutions sure has some strange problems growing along with it.

    BUT anyway  - our outside users will be writing to specific lists and it would indeed be nice if i cold deploy them back in to the inside once in a while.

    Now my q is - would you consider this setup sane?


    Per Hoyer


  • Hi Per,

    in this scenario I would write a custom application that explicitly exports the lists that need to be deployed back. It needs to be Then import this into your source server.

    You should not use content deployment for this as it does not have the required granularity to only export/import specific lists.

    This also allows to implement some error handling to avoid problems caused by name/guid conflicts.



  • HI Stefan,

    I have a question about the migration.

    I want to migrate a listitem such as portal page from one site to another site, and I also want to keep the listitem's parent. e.g. suppose we have a item called "myDocFolder/test.aspx", I want to migrate this item to another site, and keep the item's parent, e.g "myDocFolder", which doesn't exist on the destination site, when I do this, I got the following error:

    The list item /sites/team/myDocFolder/test.aspx.aspx cannot be imported because its parent web  does not exist.

    If I create the docuemnt folder "myDocFolder", on the destination server, the migartion works properly. So How can I keep the parent folder , which doesn't exist on destination server? do SharePoint support this?



  • Hi Greg,

    you need to export the parent folder as well.

    Just add this folder to the list of objects to export and mark it to not include descendents to ensure that not all list items are exported.



  • Hi Stefan, thanks for this great series it has been most helpful.

    So here's the $20 question: How can items be moved from one site to a different location in another site?

    I need to move some content and simultaneuosly restructure the site so that the destination site has the same content, but a different structure. I certainly want to avoid the issues you've ooutlined, so it seems that the export/import that allows reparenting is not an option.

    I've experimented with code to move all items (and version histories) individually from the source to the destination. The basic idea is to grab each item in the source, check if it exists on the destination (delete the destination version if it exists), then add each version with properties to the destination.

    Is this a sound approach? It seems like I'm just manually doing what the reparent options would be doing, except for the fact I'm doing a check/delete before adding the file to the destination. Should my check/delete protect me from having multiple items with the same name and different GUIDs?

  • Hi Shamus,

    actually it sounds more like a copy operation than a move as you are not talking about removing the item on the source location.

    In such a situation you might end up with duplicate content when repeating the action and doing reparetenting.

    As you need to restructure the site you cannot retain the object identity - so you have to reparent.

    So your approach of checking if an item with the same name already exists and deletion looks like the best way to avoid the duplication.



  • Thanks for many good tips with Content Deployment.

    We are setting up a content deployment work on a large site (12GB) and the largest subsites is too large to use Content Deployment for the initial run, causing memory exception when decompression the files. Tried to avoid it by using stsadm -o export/import, but got same problem as you mention here.

    How can we do an initial export with retaining the object identity? Is there no way doing this without coding the deployment ourself?



  • Hi Oddborn,

    you should open a support case for this.



Your comment has been posted.   Close
Thank you, your comment requires moderation so it may take a while to appear.   Close
Leave a Comment
Raw Html Fix