Monday, March 30, 2015

What to Expect When You're Expecting a SharePoint Migration

After death and taxes, SharePoint migrations are now the third certainty in life. Just because it's a certainty doesn't mean it needs to be feared.

Like any salty SharePoint consultant, I have quite a few war stories for SharePoint migrations. I won't share my stories here. Instead I want to share a few lessons I've learned so you can make your migration a better experience for everyone involved.

Before The Migration

Before you decide to migrate there's a few questions you need to answer. You may think some of these are obvious or don’t apply to your scenario, but these questions and how you answer them serve as a foundation for the rest of the migration project.

- Am I migrating on-premise or to the cloud?

- Am I migrating to a new version of SharePoint?

- How much data am I moving?

- How frequently is this data used?

- When I migrate, am I going to change functionality?

- Which migration tool is best for my needs?

- Do date stamps such as created and modified need to be preserved?

When you move houses, you pack up your belongings and get rid what you no longer need. SharePoint migrations are the same. I'm not saying you need to have a garage sale, but use the migration as an opportunity to assess what data is used in the site. If it is used, bring it along. If the data isn't used or is stale, there's a few considerations: you can keep it here and make the current site an archive, move it to another more formal archive site (such as a records center), or it can be deleted. These aren't all the solutions but are merely idea starters as to what to do with your old data. 

During The Migration

The next part of the migration equation is the execution of the migration, and a lot of that falls onto the migration tool itself. No two tools are made the same. It's best to execute several test migrations to environments that are similar to the final, target environment to help you figure out how the tool will handle your migration.

Regardless of the tool you use, here are some things you need to consider when configuring and executing migration jobs include:

- Are you migrating third party solutions such as Nintex and their dependencies such as workflow history lists?

- Are you migrating existing JavaScript libraries and external stylesheets? If so, are these in the hive folder or within the site being migrated?

- Are the site templates in the target environment correct?

- Is the metadata mapped correctly?

- Are permissions to be preserved between the source and target site?

I can speak from experience that adjusting the site templates mid-migration due to an eleventh hour change in requirements is a recipe for no bueno situation. Be sure that you double check that your t's are crossed and your lowercase j's are dotted on your site templates and the business validates the new templates before you migrate a single site.

No matter how much content you're migrating, you need to monitor the tool. What do I mean by monitor the tool? If the tool is spitting out errors, it's better to catch them now instead of several hours, or even several days, later if you're moving a lot of content. Plus by monitoring, you can take a sneak peek to validate that everything is correct. Which leads to my next section.

After the Migration

Once you've migrated, you need to validate thoroughly.

There's a few facets to validating a migration. The first one is to go through the questions in the tool section above and see that it did everything you wanted it to. Different environments have different behaviors and while a tool may work smoothly in one environment doesn't necessarily mean it'll be smooth sailing in another environment. This can be due to a number of reasons: patch levels, different authentication etc.,

Second, when you begin validating a migration, be attune to errors and inconsistencies and try to identify patterns. If a tool did something once, it most likely did it somewhere else - either in the current site in a different library or in the same library on another site. Patterns may not jump out to you immediately so it's important that you take time here and not skimp through the validation.

If you find that the tool did something undesired, of course you want to fix it and there's a few routes to choose. Can the tool correct the issue? It may be as simple as using the tool to update metadata or re-running the migration job with a different setting. If the tool chokes for whatever reason, can the correction be done in the browser? Also, how many times does this need to be done? If it's an unreasonable amount of times, save time and write a PowerShell script. Now you may not be a PowerShell jockey and if you're migrating to Office365, PowerShell won't be an option, but writing a script over a few hours may save days of manual configuration. Also, most migration tools offer a command line interface where migration jobs can be batched. This is a viable option if PowerShell is not available. Client side object model is also a valid option.

Whether you use a migration tool, PowerShell, or CSOM to address these issues, be precise and prudent in your work. Think of yourself as a doctor performing surgery. You want to use a scalpel not a machete. Migration tools and PowerShell can do a lot of good, but they can also do a lot of unintentional bad. This is where the test migrations from earlier come in clutch. Doctor’s prepare for surgery in a variety of ways. For your migration, prepare yourself by testing and thoroughly validating in a non-production environment before doing anything in production.

Another facet of validation applies when you're migrating but also updating or changing functionality. If you're migrating to a new site and there's deprecated functionality, you need to validate that any and all old functionality has been removed. For example, there may be web parts on pages from an old feature that will no longer work. You'll probably be greeted with a big old "Sorry an error has occurred" message. This may not phase you, but if the end user sees it they'll panic. As part of your validation you'll have to figure out the best way to remove this functionality (cough *PowerShell* cough). Ideally this is caught early in the project and can be addressed in one of the initial migrations.

When there's new functionality, especially if the user experience changes, make sure that users are able to correctly interact with all of the migrated content. Working with the developers and the validating the functionality against the project's requirements are paramount to a successful migration and functionality upgrade.

In addition to functional validation of the site, the last and arguably most important facet of validating a migration is you need to validate that the site you're migrating to has all the content. Again, PowerShell to the rescue here. If you can't run PowerShell, most major migration tools have some sort of site inventory functionality. Compare functionality can be done through Excel and Access, or you can adapt the compare snippet in the blog post and run PowerShell locally on your desktop.


While SharePoint migrations may be the third certainty in life, they should not be feared. Think of a SharePoint migration as a time to rejuvenate your site with the latest and greatest functionality while bringing your content along for the ride. Hopefully the questions I posed in in this blog along with the lessons learned can help you and your team plan and execute a smooth SharePoint migration.