What to consider when migrating to Storyblok

Our wonderful developers here at Storyblok have a lot of experience in content migrations, and we want to help guide you through the process of migrating to Storyblok and show you where the most common issues can occur and how you can either avoid them or fix them.

Pre-migration

You need to consider the content types you want to have inside your new project. Let's say you have a content type for news, which you also use for events. During migration to Storyblok, you might want to split those two into separate content types so that they can have different field structures, which will make it easier for the user to create custom fields. So if you’ve been using one content type for two different content types, a migration is the perfect time to fix these issues, and you can always create a script that will detect which entries need to be moved to one content type or the other.

You should be aware that there’s always the chance of losing content during a migration. It could be due to so many different things, and some things might go unnoticed for a while. This is why it's important to keep a copy of your existing website (database and assets) for at least 2 or 3 months post migration, so if you lose a piece of content during the migration, you can go back to your source and find what you’re missing. Another failsafe method is to have several people double-check the migration. It’s best if you have three or four different sets of eyes to look over the migration, from developers to marketers, as they might notice any issues in the content that a developer could miss.

Content migration guide

1. Create a copy of your database to work off of.
2. Check what content types you currently have on your old website and map them to the new content types you will be using in Storyblok.
3. Delve more deeply into each content type and find out what fields you want to migrate over.
4. Think about your URL structure and if it will change. In case it will, you will need to create a list of redirects either manually or with a script.
5. Check for any design issues that might be related to migrated assets that might not have the correct quality/ratio to be displayed properly in your project.
6. Create a list of the content that will be migrated with your script and what will be migrated manually.
7. Create the scripts that will move most of the content into Storyblok.
8. Decide what you want to do with the script after the migration. For example, using your script on some manually migrated content to clean it up.
9. After you publish everything, you need to have everything reviewed by at least two other people.
10. Fix any issues or alterations, and you might need to run scripts to fix things globally.
11. Monitor your new project with SEO Tool and Google Search Console.
    1. Start with SEO Tool because it will spot all the 404 errors in the internal links immediately, which you will need to fix.
    2. Afterwards, monitor your project with Google Search Console for some time because it will scan your search results in Google and tell you if you have any 404 errors.
12. Keep monitoring your project and everything should be stable within three to six weeks, depending on the size of your migration and team.

Common issues and how to address them

Inline links

The biggest issue you’ll probably face is with Inline links - For example, if you have a website and you have a PDF in the assets of your website, and you’ve been using an inline link for that PDF all across your website. When migrating, you need to detect all those inline links and update them so that they function properly after you complete your migration to Storyblok. This needs to happen for every asset you have stored during your migration process, and if done incorrectly and left with broken links, will have your users unable to find the content they are looking for and will have a negative effect from an SEO & Google perspective.

Slugs

You have to keep your eye on your slugs as well. If in your old CMS your slugs were using numeric IDs, then all your slugs need to change to text during migration to Storyblok, which you can do in your migration script.

Finding assets

Another issue is when you want to check the assets that are stored inside your project. When you come to check inside the HTML content of your pages, you can’t only search for your domain in case the URLs are set with a relative path. In situations like this, you need to write ‘regular expressions’ to detect these types of patterns in the code, and then write a script to recognize these assets, clone them into Storyblok, and replace and save the new HTML.

Inefficient asset migration

You have to watch out for situations where you are linking the same asset to two different pages. During migration, you don’t want that asset to be uploaded twice. You should start by making a list of all the assets that you have in your content, download those assets, then replace the URL leading to that asset on both pages with its new URL. This is quite a challenge as there are a lot of things you need to keep in mind during the migration process. If you miss one thing, you are very likely to end up with an error that you won’t be able to spot very easily.

Key Takeaways

Migrating is a big step, one that needs to be taken carefully with meticulous planning, careful revision, and probably some big fixes here and there. There are lots of considerations, and always remember to have several eyes looking over the migration as it goes on, it will help so much in the long run. Once you’re done migrating your project, why not reach out to us to co-author a case study about your experience? We’d love to hear from you.