Introduction

Migrating to Content Sync is usually very straightforward because of the automated onboarding options the service provides. Before diving into the exact steps, let's clarify some important key concepts first.


How content is uniquely identified across sites

Content Sync

Usually if you want to reference an entity like a node, you will use its ID. But this ID is generated by the database and while it's guaranteed to be unique per site, an ID is not unique across sites. Different sites may store identical content but with a different ID.

Luckily, Drupal introduced the concept of very broadly using UUIDs back in Drupal 8. While numerical IDs are only locally unique, UUIDs are globally unique. While there's a theoretical chance of collisions, you can assume that UUIDs are guaranteed to be unique across your sites across all the content you have.

That's why we are mapping content across sites by the UUID of each content entity. Content Sync is also able to synchronize a handful of config entities like blocks or webforms that are mapped by their ID because config entities in Drupal have a unique string machine name as their ID that's shared between sites rather than a numerical per-site ID.


Other solutions

Most other solutions for sharing content like entity_share or Acquia Content Hub also use UUIDs to map content. If you have used any other provider before for content syndication, it's very likely that Content Sync will immediately work with all your existing content without any migration at all. If you aren't sure about whether mapping by UUID is sufficient, you can check what UUIDs were assigned to your entities before across your sites to verify that UUIDs are identical.


How updates are initiated

With Content Sync, you can freely configure when, what and how content is pushed from a site or pulled into a site. This is done by creating Flow configurations on each site. You can support multiple use-cases or workflows by creating multiple Flows. Sites can be both a publisher and a subscriber (both push and pull content).

This flexibility makes it very straightforward to migrate from other solutions that usually offer much fewer options.


Local content changes

Whether or not local changes are allowed depends on your Content Sync configuration. If you have used another solution before that is stateful, meaning there's important meta information like the overridden state saved per entity that has to be migrated, please reach out to us as we have automated many of this before and also have ready-to-use automations available for the most-requested cases.


Step-by-step migration instructions


Step 1: Preparation

We always recommend starting with a Content Flow diagram that simplifies documentation and communication between all stakeholders. A Content Flow diagram should show:

  • Which sites can push/pull which content.
    • It's usually sufficient to document "root entities" like nodes and just assume that paragraphs, media, files etc. come along with it to avoid a bloated diagram. But this may very well include other entities like menu items or taxonomies if you sync them independently of node content.
  • What content is pushed/pulled automatically or manually.
  • What Pools are used by which site for which content, if more than 1 Pool is used.
  • Which taxonomy filters are used by subscribing sites.
    • If you use taxonomy filters, we strongly recommend synchronizing the taxonomy itself through another Flow, independently of content.
  • The update mode on the pulling site(s).
  • Whether content can be deleted and/or unpublished across sites.

How exactly you structure this diagram depends on your exact use-case. For most implementations you want to create one diagram per "workflow" that usually consists of one pushing Flow and one pulling Flow. For example: 1 workflow to keep the vocabularies "Sites" and "Products" or "Faculties" in sync across all sites, managed (pushed) by 1 main site and 1 workflow to share "article" and "basic_page" nodes between site A and sites B, C and D.


Step 2: Configuration

Create a project in Content Sync of type Test and connect your test sites to it. Choose test sites that are representative for the workflows you want to configure based on your documentation from Step 1. For each of your workflows, create the corresponding Flows on your sites.

Content Sync provides Flows and Pools as config entities, so you can easily share and reuse them across your sites. It's also important to export your configuration before deploying your sites or your configurations may get lost. You can use config_ignore and config_split to manage configuration more easily between multiple sites.

Tip: If Flows only differ by their taxonomy filter, you can override this setting per Flow in the site's settings.php file.


Step 3: Test run

For each of your workflows, perform a couple of test runs with new content. Be sure to include tests for each type you support and for the actions create, update, delete and unpublish, depending on what's allowed by the config.


Step 4: Include existing content

Because Content Sync maps content by ID, it's very likely that it will automatically work with all your existing content that was distributed by other means before adding Content Sync- as long as the entities share the same UUID. Check out the introduction to learn more about this.

But this is only true for create and update actions. The unpublish and delete action will not work for existing content that was not shared through Content Sync before because Content Sync has no way of knowing that another site has already gotten a piece of content before and we should unpublish or delete it. To resolve this efficiently, Content Sync provides mass update options. While you can choose to just push all content from your source sites, this will trigger updates for all your content across all of your sites and can result in a massive usage increase and unnecessary content changes; while Content Sync automatically throttles requests to not overload your site, this may still impact your site performance and also take a very long time to propagate. That's why Content Sync provides a saner alternative through Mass Updates. To perform this initial state migration, please follow the steps below for each of your workflows separately (unless the same sites are pushing and pulling content).


Step 4.1: Push existing content

To avoid the issues of mass updates outlined above, disable the pulling Flows on all sites. This can be done through settings.php, but you have to run drush cse to make our service aware of the change. Once that's done, head over to the Updates tab of Content Sync and click on Mass Updates for each of your workflows and use the Start New action to initiate a Push All migration. This will run in the background to share all content from your site with our service.

If you see timeouts during this operation, you can decrease the throttle limits in the Advanced settings tab. If on the other hand your site is still running very fast, you can also increase the throttle limit to allow more simultaneous push operations.


Step 4.2: Map pushed content

Once all content has been pushed successfully -which you can verify with some samples in the Content tab of the Content Sypc App- it's time to map your content on other sites. For this, you want to first enable the pulling Flows again and then follow the same steps as above by going to Updates > Mass Updates > Start New, but now you want to use the Map Existing Content action. This has to be done for all sites where state is required, i.e. where your workflows allow unpublishing or deleting content; other workflows may skip this step if no state is necessary. You can also automate this using drush if you're working with many sites.

This operation usually finishes in less than 10% of the time that the push operation takes because we are not serializing data or storing new content.

Once mapping is finished for all sites, you can test the procedure e.g. by deleting some test content.


Conclusion

Migrating from other solutions to Content Sync is very straightforward. While the process above outlines the most important steps for your migration, we do recommend that you also follow our general onboarding guidelines and consult our documentation for everything else that you need.

If you are unsure about any of the steps or encounter any obstacles, please reach out to our support.