Tag

migration

Browsing

Introduction

When migrating from SharePoint on-premises to SharePoint Online/Office 365, you may find that some users have a checked-out file called spcommon[1].png. If you ask users about it, they'll have no idea what you're talking about.

As it turns out, this isn't a bug. It is possible for users to check-out this file without knowing they did it.

But for this issue to occur, you need a "perfect storm" to happen: a series of things that occur that are seamingly unrelated that results in the issue we're discussing today.

What is spcommon[1].png

spcommon.png is an image that SharePoint uses to render things like checkboxes, arrows, gears, and pretty much any icon that you see on a SharePoint page.

If you download the file, it looks like a bunch of icons in one bigger image:
SPCOMMON.PNG

Those types of images are called sprites; they usually consist of many images grouped together as a single image. That image is bigger to download than individual images, but since most browsers try to avoid re-downloading a file it has already downloaded (something known as caching -- pronounced cashing) -- making the entire page load faster.

SharePoint uses the giant sprite and hides irrelevant parts of the image (by setting a background-url and background-position CSS styles).

On a typical SharePoint page, the spcommon.png image may be shown dozens of times.

So why do I get a spcommon[1].png file that gets checked out by users?

Perfect Storm

This issue will typically happen in document libraries that either Require check-out before editing files or that have a mandatory property.

I've seen this issue in SharePoint 2013 and SharePoint 2016 migrations, but it could potentially happen in SharePoint 2019 as well.

As you already know, users can drag and drop documents unto a document library using their browsers, and SharePoint will try to upload the document.

If you try drag and drop a document to a library that requires checking in or one that has mandatory properties, the newly uploaded document will be checked out until the user provides values for the mandatory properties and checks the document in.

Most browsers also allow you to select an image from a web page and drag and drop it. (Try it now with an image on this page!).

If you try to drag and drop an image onto a document library page, it will try to upload that image into the document library. If that library has mandatory properties, the image will be uploaded but checked-out.

Here is where it gets crazy: if a user tries to click on the checkmark next to a document and accidentally drags the mouse instead -- even for a few pixels -- the browser will think that the user meant to upload the image to the document library.

The checkmark

And the image used to display the checkbox is -- you guessed it --spcommon.png.

It often happens too quickly for users to notice, but here is what happens if you slow it down and take a screen shot of a user dragging the checkmark icon in a document library:

Dragging the checkmark

And since most browsers will try to uniquely name dragged files, the spcommon.png file is automatically renamed to spcommon[1].png.

Conclusion

The issue with a mysterious checked-out spcommon[1].png file in a document library requires a lot of factors to happen.

Fortunately, It seems that newer versions/patches of SharePoint prevent this issue from happening by giving users an error message saying "Folders and invalid files can't be dragged to upload", meaning that you're less likely to find this issue in future migrations.

Issue prevented?

If you see this error when migrating files to SharePoint Online, you can safely ignore it.

Introduction

I know, I know, there are already tons of SharePoint migrations to Office 365 "Best Practices" articles out there. My evil twin even wrote an article on how to fail a migration recently, which received much more attention than it deserved.

I have done many large scale migrations and given many presentations on the topic, but I didn't want this article to be a "things Hugo says you should do" article. There are many other authors who are much more insightful and eloquent.

This article is a compilation of the best "best practices" articles I could find. I have included the list of articles at the end.

By all means, do not trust that my conclusions are accurate or unbiased. Feel free to read all the referenced articles and make your own conclusions -- and then comment below!

Overview

Migration Best Practices

Approach

I searched for SharePoint to Office 365 Migration Best Practices on Google and Bing and compiled all results.

I did not include articles that were behind a paywall, or those that required you to provide an email to get access to the article/download anything.

I also excluded any articles that were purely technical (e.g.: the ones that show you how to use a migration tool).

After carefully reading each article, I create a table listing each article with every "best practice" idea discussed in the article.

When looking for best practice criteria, I looked for articles that focused on the following outcomes:

  • Increased user adoption of Office 365
  • Increased user satisfaction
  • No loss of productivity/increased productivity
  • No loss of data
  • Accuracy of migrated data
  • Reduced risks

I tabulated the best practices that appeared in 3 or more articles.

I focused on the top 10 best practices but ended up with 11 topics. I chose to separate Clean Files and No "as-is" because -- while they are arguably similar -- most authors discussed both points separately.

Analysis

The list below provides links to each of the articles reviewed. I chose to use a legend (instead of writing each best practice in the header) because I wanted the table to be easy to see at a glance.

Legend

The following letters correspond to a best practice idea. We'll discuss each idea below.

A
Incremental
B
Inform Users
C
Analyze/Audit
D
Plan
E
No "As-Is"
F
Accurate Estimates
G
Clean-up
H
Train Users
I
Information Architecture
J
Not just an IT initiative
K
Test
L
Champions
ArticleAuthorABCDEFGHIJKL
5 common mistakes when migrating to Office 365lightningtools83
5 Key Steps for Migrating SharePoint to the CloudSteve Marsh
5 Mistakes To Avoid When Migrating from SharePoint to Office 365Maggie Swearingen
Adoption and SharePoint migrations – it’s a thing!Shafina Hassam
Anatomy of a SharePoint Migration [INFOGRAPHIC]Joanne Klein
Best Practices for a Smooth Office 365 MigrationMichael Pichna
Best way to implement SharePoint in a large organizationGregory Zelfond
How to Migrate Documents to SharePoint and Office 365: Step-by-Step InstructionsGregory Zelfond
Migrating SharePoint to Office 365 – Best (Recommended) PracticesVeenus Maximiuk
Migrating to SharePoint Online? Get this ULTIMATE checklist ready!Arut Selvan
Moving file shares to SharePoint on-premises to SharePoint Online isn’t a simple lift and shiftTervela
Recommended Best Practices for Migrating SharePoint to Office 365Veenus Maximiuk
SharePoint Migration InfographicGTconsult A Team
Top 5 Mistakes to Avoid When Migrating to Office 365David Davidov

Findings

Incremental

Many authors agree that you should migrate your content incrementally, or in batches, rather than migrating everything at once.

For example, you should consider migrating content on a team-by-team basis. Doing so gives you the opportunity to properly analyze and audit the data to be migrated, clean up the data and re-organize it as you migrate, and spend quality time with the users to inform them and train them.

It also gives you the opportunity to test each migration and -- more importantly -- to get your content owners to verify (and possibly sign-off) on the migration.

Getting sign-off from content owners is a great way to help speed up the decommissioning of the old data (which is a re-occurring best practice, but didn't make the top list).

Inform Users

The topic of "Informing Users" and "Communicating" was one of the most common best practices. Most experts agree that you should inform your users in advance about the exciting new platform they'll soon be using, describe the benefits of the new platform, and inform them of timing.

Migrating to Office 365 impacts users. Your users may make up their minds to "boycott" the new platform before they even see what's coming.

This is often due to fear of the unknown from your users.

Take the time to explain to your users what's coming, how they will benefit from this migration, and when it will happen.

You can't expect users to drop everything they're doing for your migration. Try migrating the accounting department during fiscal year end and you'll see just how much push back you can get from your users.

Analyze/Audit

The # 1 best practice seems obvious, but it is often forgotten.

Before migrating, you should perform an in-depth analysis of the content you'll be migrating. Don't just count how many files there are!

Consider the following :

  • Custom solutions
  • Business processes that will be affected
  • Security/permissions
  • Deprecated features
  • File path length (see this article to understand why you should care)
  • Metadata
  • How much space will be needed to migrate

Not all content needs to be migrated (see Clean Up, below), but every piece of content should be accounted for. While most of your files may be migrated, some may be archived or skipped because they are duplicate. Keeping an audit of all your content, along with their migration status will help ensure that all your content is accounted for.

Plan

A successful migration begins with creating a migration plan.

This is what I typically put in my migration plans:

- Objectives and Goals
    * Business-Related Goals
    * Migration-Related Goals
- Migration Strategies
    * Strategy 1
        * Tools
        * Implications
    * Strategy 2
        * Tools
        * Implications
    * ...
    * Strategy n
        * Tools
        * Implications
- Migration Environment
- Migration Guidelines
- Migration Process
    * Preparation
    * Migration Step 1
    * Migration Step 2
    * ...
    * Migration Step n
    * Migration Execution & Validation
    * Decommissioning of Replaced Resources
    * Rollback Plan

Your migration plan should include going to each team in your organization and identify their processes, the custom solutions they use, the files they need and plan how and where you will migrate everything.

No "As-Is"

Let me be clear: none of the best bet articles I listed above explicitly say "No As-Is".

Most experts agree, however, that doing a simple "lift and shift" is a bad idea.

Don't simply copy the documents over "as-is". Take the time to re-evaluate the Information Architecture to take advantage of the capabilities that SharePoint Online offers with Office 365.

Consider moving the sub-sites within sub-sites to a flatter site structure.

Consider using hubs to group sites together.

Consider distributing sub-folders to different document libraries.

Look for long file URLs and make sure that they'll fit within the URL length limits once migrated.

Just make sure that you don't accept the status quo.

Accurate Estimates

Failed migrations often underestimate the effort involved in migrating content to Office 365.

To paraphrase George W. Bush, "don't misunderestimate the effort involved".

As Joanne Klein explains in her article, don't underestimate the time it takes to plan the migration.

You also need to estimate the time you will need to migrate the files.

What's the best way to estimate the migration effort? Perform test migrations with real files.

You can actually test the migration in your new Office 365 tenant. If you're concerned about "tainting" your production environment, just migrate a site to a temporary destination in your production environment (e.g.: HR to HRTest) and delete the site after your tests are complete.

Once you have performed a test migration you can extrapolate the time it took to perform the test (including the time it took to do the analysis and planning) to get a better estimate.

Clean-up

As we discussed above (see No "As-Is"), you should not simply lift and shift your files.

Take this opportunity to clean up files as you go. Remove duplicates, remove old files and other files that have no business being moved to the new environment.

If your business folks have a "let's keep files forever" retention policy, now is a great opportunity to encourage them to adopt an adequate retention policy.

While you're at it, look for documents that have the words "Final" or "Draft" in them. Then look for documents with the same name -- but without "Final" and "Draft" in them (they often have dates or version numbers in the file names as well). They usually indicate users who don't quite understand how versioning works in SharePoint.

That's also a sign that you should train your users.

Train Users

With the number of training resources available out there, there are no excuses for not training your users.

The only valid reason for not training your users is if you want your migration to fail.

Information Architecture

Take the time to create an Information Architecture for your migrated content.

If you don't take the time to develop an Information Architecture that will help your users find the content they need, they'll blame SharePoint for not being able to find documents and you'll get poor user adoption.

If you need help with developing an Information Architecture, I've written a few articles on the subject -- but there are plenty of resources out there.

Not just an IT initiative

“Be prepared to answer the question "how much of my time/my staff's time will you need?". Someone will ask.

Migrating SharePoint to Office 365 is more than just moving files and server resources. You need to change how your users will work too.

Don't approach your migration as an IT-only initiative. It should not be.

Get executive buy-in, involve your stakeholders, involve your users.

The IT team can lead the migration initiative, but you need to involve other departments as well.

Consult the teams as you move their content and make sure that you listen to their pain points. Find a way to alleviate their pain points in Office 365.

As we said before, don't forget that other departments also have jobs to do. They aren't waiting at your beck and call. Be considerate of their time.

Be prepared to answer the question "how much of my time/my staff's time will you need?". Someone will ask.

Test

Most experts will encourage you to test your migration.

By "testing", we don't mean counting how many files are in the source and -- after migration -- counting how many files are in the destination to see if it matches.

Before the real migration, perform a test migration with real documents to your real production environment and verifying that everything that was supposed to migrate did migrate.

After migration, get your content owners to test finding and opening documents.

Verify that you didn't lose metadata when you migrated.

Verify that permissions are accurate and that users who shouldn't see files won't see those files.

Verify that those files with the longest URLs can be opened on a user's workstation without any issues.

Champions

Along the same lines as Not just an IT initiative and Train Users, consider finding users who are willing to be your first test subjects.

They'll become your champions later.

Don't let some executive name their favourite people who don't have any real experience using the old SharePoint site. Find actual users who are suffering so much that they're willing to spend extra time testing the new platform, finding all warts and bugs -- just for the possibility that the new platform will make their lives better.

Find those users who aren't afraid to complain loudly, but who are willing to listen.

Find those who are influential among their peers. They're the ones that will encourage other users to adopt your new platform.

Working with champions usually consists of three phases:

  • Engage: Get the champions involved in the decision process. Show them the possibilities. Try giving them choices ("would you prefer A or B?") and avoid asking questions that require them to be Office 365 experts to answer ("what content types do you need?").
  • Empower: Give your champions permissions to manage their own site. Give them room to make mistakes and to recover from them.
  • Extend: Encourage your champions to extend their use of SharePoint Online. Encourage them to create new document libraries, to invite other users, and to push the boundaries of how they'll use what's at their disposal. Remember: users don't always tell you what they need, they often tell you what they think you want to hear -- letting your champions extend how they use their new site may reveal requirements that were never discussed.

If you find that your users tell you that they don't have time for you, that they're too busy, it is probably because you didn't try to find champions first.

Once your champions find how awesome Office 365 is, they'll tell other users. Those users who were too busy and didn't have time for you will soon be begging to work with you because they want to have all the cool stuff the champions got.

Conclusion

Every expert has their own perspective on what best practices exist when it comes to migrating SharePoint to Office 365, but there are common ideas that they all seem to agree with.

I would love to make this list even more comprehensive. If you have found an article that you believe should be included in this article, please let me know in the comments. I'll keep growing the list and updating the research.

Introduction

What happens when you file to plan

When migrating content from a network file share to SharePoint Online (or SharePoint on premises), remember SharePoint's URL length limitations.

This article discusses the current limitation with URL lengths in SharePoint. It discusses how this limitation manifests itself, and how it can impact you during your SharePoint migration.

A matter of legacy

In SharePoint, the limit for a document's URL is 400 characters long. We'll discuss this in greater length (see what I did there?) later, but for now, let's discuss how we get long path names.

To begin with, nobody in their right mind ever says "I think I'll name my file SuperInsaneLongFileNameThatIDontEverWantToTypeAgainBecauseItIsTooLong.docx".

That'd be just annoying.

Instead, people get long path names because of the legacy infrastructure dictated by file shares.

You see, on a network file share, users don't get the luxury of using metadata or versioning. As a result, users tend to get creative and create folder structures as a substitute to convey metadata.

We've used this example before. Imagine that your users store case files on a network file share. They want to group case files by status, so they case folders for each status under the Cases folder:

\Cases
    \Open
    \Closed
    \Pending review

They also want to group cases by year, so they create a folder for every year in each Cases > Status folder:

\Cases
    \Open
        \2017
        \2018
        \2019
    \Closed
        \2017
        \2018
        \2019
    \Pending review
        \2017
        \2018
        \2019

Each case is placed in the folder matching the year it was received, within the folder for the case status.

Now imagine that, in the process of managing a case, your staff receive electronic evidence, via USB sticks, removable drives, or email attachments -- or whatever way. To keep these files together, users start creating folders. Of course, they want to keep track of when they received the files, so they put the files in a folder called John Smith files received Jan 21, 2019

Also, because our users want to keep incoming documents (stuff they received during the case management process) from outgoing documents (letters and documents they send out through the case management process), they create separate folders, aptly named Incoming documents and Outgoing documents.

For example, let's pretend we have an open case, numbered CA-12345678, from 2019. The folder structure would look like this:

\Cases
    \Open
        \2017
        \2018
        \2019
            \CA-12345678
                \Incoming documents
                    \John Smith files received Jan 21, 2019
                        \Photo evidence 1.png
                        \Letter from complainant.pdf
                        \...
    \Closed
        \2017
        \2018
        \2019
    \Pending review
        \2017
        \2018
        \2019

Of course, they also want to keep track of outgoing documents they work on, so they name the files accordingly:

\Cases
    \Open
        \2017
        \2018
        \2019
            \CA-12345678
                \Incoming documents
                    \John Smith files received Jan 21, 2019
                        \Photo evidence 1.png
                        \Letter from complainant.pdf
                        \...
                \Outgoing documents
                    \Case Summary
                        \Case review v1 Feb 21.docx
                        \Case review v2 Feb 25.docx
                        \Case review v3 Feb 27.docx
                    \Case interviews
                        \Interview with John Smith Jan 23, 2019 raw.mp4
                        \Interview with John Smith Jan 23, 2019 transcript v1.docx
                        \Interview with John Smith Jan 23, 2019 transcript final.docx
                        \Interview with John Smith Jan 23, 2019 transcript final final.docx
    \Closed
        \2017
        \2018
        \2019
    \Pending review
        \2017
        \2018
        \2019

And so on.

Users don't do this to be annoying. They do this because they need a way to manage their information with the tools they have. Without metadata at their disposal, they use long file and folder names.

As long as they keep their file paths shorter than 255 characters, most Windows applications will be able to handle opening and saving files from the file share. This isn't a limitation of UNC paths, it is a limitation within the apps that try to open and save files (for example, your PDF reader). Depending on the version of Windows you use, and assuming you use applications from this century, you can probably get away with longer file paths.

Typically, organizations will map file shares to a drive to make it easier for users. So, instead of having a path that starts with:

\\servername\networksharename

They'll have a single letter pointing to the file share. For example, S:\. It helps keep the file paths shorter, thus preventing any issues.

Everyone is happy.

Until they try moving the files to SharePoint.

SharePoint URL Length Limitations

Prior to May 2017, the maximum URL length for a file stored in SharePoint was 255 characters.

Since then, Microsoft kindly increased the maximum path size to 400 characters.

When I say 400 characters, I really mean 400 unicode units. If you use International characters with multibyte values, you actually get less that 400 characters.

"So what? Our file names are less than 400 characters", you may ask.

You see, the URL is for the entire URL of the file, including:
https:\\yourtenant.sharepoint.com/sites/yoursitename/yourdocumentlibraryname/yourfolderpath/subfolderpath/Filename.extension/?parameters

For example, let's say your tenant is called Contoso, your site called Case Management, and your document library called Shared documents. On your file share, that file path that started with:

S:\

...when migrated to SharePoint, will become:

https://contoso.sharepoint.com/sites/case%20management/shared%20documents/

That's a whopping extra 71 characters added to your file names. Those file paths that didn't cause any issues on a network file share can suddenly be too long once migrated to SharePoint.

How long URLs manifest themselves

No issues when uploading documents

Here is the problem: you may be able to migrate your documents to SharePoint -- even if they have long file names that exceed the maximum path length.

Errors opening documents online

However, when you try to open the file, you get an error. For example, here is what happens when I try to open a document with Word online:
Word File Path Too Long

Errors opening documents using desktop applications

What's worse, if your users are on an older version of Windows, or if they use a Mac, they may experience issues with file paths around the 255 character length!

Also, if they try to Sync the files to OneDrive for Business, and they try to open documents using older desktop applications, they may get an error indicating that the "file could not be opened" or the ever-mysterious "an error has occurred".

"Some files work, some files don't"

Users may experience an issue when only a few documents (or folders) won't open, but other files open without problems.

This usually happens with file names that have different lengths. Shorter file names open without issues because the full paths are less than 400 characters. Longer file names don't open because the file names are longer than 400 characters.

To regular users, it seems like a random issue.

But you and I know better, don't we?!

How to solve the URL length issue

You migrated your file share to SharePoint without getting any errors while uploading the documents.

Everything looks good.

Then a user tries to open a document with a URL that exceeds the limit. And they get an error. Of course, this always happens with someone very high up in your company, usually minutes before a very important event.

Move files to a shorter URL

The easiest way to solve this problem: use SharePoint's Move functionality within a document library to move the file to a shorter URL.

Move to

For example, if the file is 5 folders deep in a document library, try moving the file to the root of that document library.

It may shorten the URL with enough precious characters to allow you to open the file.

Then have the talk (you know, the one about why you should use shorter folder names and file names) with your users.

Errors with custom code

If you use custom code to connect to SharePoint using REST, you may also run into issues when the full URL for the REST call exceeds the limit.

One way to solve this problem is to use GetFileById and pass the unique file id instead of trying to use the file name:

https://yourtenant.sharepoint.com/sites/yoursitename/_api/web/GetFileById('fileid')

How to test URL length limits

When I tested the maximum URL length for this article I manually created super-long file names.

Fortunately, you don't have to do that. Thanks to Rene Modery, you can use a script to create long file paths. It uses the SharePoint PnP cmdlets to connect to SharePoint and create long paths for you.

Conclusion

When planning a SharePoint migration, pay attention to long path names. You may be able to migrate the documents without issues, but your users will run into issues opening documents.

If your users work with older desktop applications, older versions of Windows, or Macs, you may want to stick to a maximum URL length of fewer than 255 characters.

If your users have the latest version of Windows and Office, you can safely plan for maximum server-relative URL lengths (i.e.: the URL without the https://[yourtenant].sharepoint.com) of 400 characters.

Of course, after your content is migrated, help your users understand why they shouldn't use silly long file and folder names anymore and show them how to use metadata.

I hope this will save you some headaches in the future.

Update

Contrary to Microsoft's own article, it appears the 400 character limit no longer counts the https://[yourtenant].sharepoint.com/ or the parameters (e.g.: ?web=1) in the URL length. The limit of 400 characters applies to the server-relative file path.

When a URL contains special characters, like space, %, #, etc., the characters get URL-encoded. For example, space will be encoded as %20. When verifying if your file URL to shorter than 400 characters, SharePoint uses the un-encoded URL (i.e.: special characters count as 1 character).

For more information