What level of expertise is required to use Acquia Migrate Accelerate?¶

Acquia Migrate Accelerate (AMA) lowers the barrier to entry for site builders to migrate from Drupal 7 to Drupal 9. However, your Drupal 7 site might have issues such as data model issues, which make the migration challenging and may need to be resolved. AMA provides insight into some of the changes that you need to make to your Drupal 7 site to migrate successfully, and insight into issues that you need to resolve on your Drupal 9 site. The changes in Drupal 7 tend to be data integrity problems that also affect the Drupal 7 site, such as missing values for the required fields.

Finally, after you complete the migration with AMA, custom modules and your custom theme need to be rebuilt as they cannot be migrated.

How is AMA different from the Drupal migration tools?¶

AMA extends Drupal’s powerful migration system by adding an intuitive user interface. It also provides support for hundreds of the most popular contrib modules. AMA automatically migrates you into Drupal 9 best practices, and includes data integrity checks with automatic suggestions on how to resolve migration messages to save your team’s countless hours.

For example, many competing files and media modules of Drupal 7 get their data migrated into the media module of Drupal 9 core. The data is then available through the Media Library.

Is there anything I can do to prepare for a successful migration?¶

Yes, you can do the following:

1. Check whether your site has a sites/sites.php file. If the file is available, ensure that the default domain name of your source environment is configured to use the site directory that you want to migrate. If there’s only one site directory, AMA uses that one. Otherwise, it uses the default. If there are multiple site directories and none is specified as default, the migration environment fails to create successfully.
2. Check whether your repository has a WELCOME tag. If the tag is removed, create a dummy “welcome” tag to avoid issues. The dummy tag can be empty with only a text file.
3. Check whether you’re following Drupal and Cloud Platform best practices for Setting the private file directory on Cloud Platform. If your site’s private file directory does not follow these best practices, it may cause issues.
4. Disable any modules that you are no longer in use for your Drupal 7 site. This reduces the opportunity for errors, and also reduces noise on your Drupal 9 site.
5. Analyze which content you want to migrate to your Drupal 9 site, and which content you do not need. You can choose specific content types for migration in the AMA UI. You can also change your content selection later.
6. Read Acquia Migrate Accelerate Overview and Using Acquia Migrate Accelerate documents. These documents help you understand what to expect and how to use the product.

Does AMA support multilingual migrations?¶

Yes.

Does AMA support multi-site migrations?¶

AMA does not officially support multi-site migrations. However, you can migrate one site at a time with AMA.

How do I get access to AMA?¶

AMA is included with all Acquia Cloud Enterprise subscriptions. It is not available for Acquia Cloud Professional or Site Factory subscriptions. Reach out to your account manager to request the addition of AMA to your subscription. Then, ensure to set up the correct permissions for any non-admin users.

Which parts of my site will AMA migrate?¶

AMA generates a Drupal 9 codebase with the modules that you need to recreate your Drupal 7 site. After the codebase is generated, AMA helps you migrate your configuration, content types, and content to the new site. AMA does not migrate custom modules, views, or your custom theme. You can recreate them on your Drupal 9 site.

What is included with AMA?¶

AMA includes a CD Environment specifically for your migration. This environment does not count against your CD Environment entitlements. AMA also includes a Drupal 9 application with a new database and filesystem. You will also have access to the AMA module, and the Recommendations Engine that identifies the best Drupal 9 equivalents for your Drupal 7 modules.

Which sites are the best fit for AMA?¶

1. Your site must be on Drupal 7 to use AMA.
2. AMA does not officially support multi-site migrations; single sites are the best fit for AMA.
3. Sites that use many of the top 100 contrib modules benefit most from the Recommendations Engine.
4. Sites with complex data models and/or a lot of content benefit the most from AMA’s logic and automation, as it saves a lot of time.

Which sites are not a good fit for AMA?¶

1. Sites that have a lot of custom code benefit the least, as AMA cannot migrate custom code.
2. If your site does have a lot of custom code, AMA provides you with automated recommendations for the Drupal 7 contributed modules that you did use.
3. While different sites may benefit to different degrees, AMA helps every Acquia customer migrating from Drupal 7 to Drupal 9.

Can I make changes to my site’s architecture or data model during the migration?¶

The migration to Drupal 9 is a good opportunity to re-envision your site. AMA helps you perform a lift-and-shift migration from your Drupal 7 site to a new Drupal 9 site. It does not give you the opportunity to make big changes as part of the migration process. You can make changes to your site after you migrate everything you want to carry over to your Drupal 9 site.

Which modules are included in the Recommendations Engine?¶

The Recommendations Engine automatically includes the recommended migration path for every Drupal 7 module that is compatible with Drupal 9. Acquia updates this list regularly as more Drupal 7 modules are ported to Drupal 9. Acquia’s team has vetted the upgrade path for a subset of these modules, and includes patches to improve the migration as needed. The team has vetted over 200 Drupal 7 module upgrade paths so far, and is actively vetting new ones. Sometimes, certain modules claim to be compatible with Drupal 9, but they are actually not compatible. AMA’s Recommendation Engine also handles this for you.

Will I have visibility into the output of the Recommendations Engine?¶

Yes. After your Drupal 7 site runs through the Recommendations Engine, a Drupal 9 codebase is generated, and it includes the modules that you will need for your site. The Modules tab in the AMA UI shows you the original Drupal 7 modules, with the Drupal 9 equivalents. The modules that are vetted by Acquia are automatically installed and enabled. Acquia is confident that they correctly migrate data for the vast majority of sites. You will have the opportunity to enable the recommended modules that are not vetted by Acquia. They are already downloaded using Composer, but not yet installed in Drupal.

Will AMA preserve the configuration of my Drupal 7 contributed modules that have equivalent modules in Drupal 9?¶

Yes. AMA will automatically include these modules and automatically install the ones that Acquia’s team has vetted.

Can I migrate Views with AMA?¶

No, AMA cannot migrate views because Drupal cannot migrate views. However, it migrates everything you need to recreate your views.

Can I migrate from another CMS to Drupal 9 with AMA?¶

No. AMA is specifically designed for Drupal 7 to Drupal 9 migration. Acquia recommends Acquia Migrate Re-Platform for migrations from other CMSs to Drupal 9.

Which environment does AMA migrate from?¶

AMA makes a copy of your Drupal 7 site’s production database and filesystem, and uses the copy as the migration source. Therefore, your production site does not have to support extra load during migrations.

How do I get new content from my Drupal 7 site to my new Drupal 9 site?¶

Acquia knows that you’re always adding new content to your Drupal production site. To get the latest content to your in-progress Drupal 9 site, use the Refresh button in the Cloud Platform user interface to copy over the live production database and files to the migration environment. If you make significant changes to your Drupal 7 site (beyond adding/editing content), you may want to create a new migration environment to ensure that you include those changes in your Drupal 9 site.

Can I create new content directly on my Drupal 9 site during the migration?¶

No. Your Drupal 9 site remains in the “Read Only” mode until you promote your site to Dev or Stage, and remove the AMA module. This is by design — your Drupal 7 production site is the source of record for new content to prevent data loss on your new Drupal 9 site during the migration process.

You can create and tweak the configuration. For example, you can create views on your new Drupal 9 site. If you need to create a new migration environment, Acquia recommends that you export your configuration before doing so, to avoid having to repeat this work. You can re-import the exported configuration to your new migration environment.

What happens when I click the “Promote” button?¶

When you click the Promote button, you can choose to promote your site to Dev or Stage. After selecting an environment, the Drupal 9 site is copied and promoted to the selected environment. The AMA module remains installed, but you cannot do migration activities on the promoted Drupal 9 site. The migration environment continues to exist, ready to do additional migration activities, if you choose to do so. For more information, see Finishing your Drupal 9 site.

How do I disable the AMA module when I am done with my migration?¶

When you are done with the migration, the AMA UI indicates that all migrations have completed. In addition, your migration should meet the following criteria:

1. Either there are no migration messages, or all messages only describe warnings about changes from Drupal 7 to Drupal 9.
2. You’ve manually verified, at least through spot checking, that the data in the Drupal 9 site is complete and accurate.

At this point, you can promote your migration environment into your ACE subscription’s Dev or Staging environment using the Promote button in the Cloud Platform UI. After completing this step, uninstall the AMA Drupal module in the environment you promoted it to. This removes AMA-specific database tables and disables the “Read Only” mode.

I got 80 - 90% of my data migrated, but I’m not sure how to finish the last 10-20%.¶

The last 10-20% of a migration may require you to port your custom modules, or work through issues with your Drupal 7 site that are highlighted on the Messages tab in the Migrate UI. You may need to engage with Professional Services to work through these final pieces of the migration.

Where can I learn more about working with a CD environment?¶

Working with CD environments.

What should I do with my site when I’ve finished using AMA?¶

When you’ve finished migrating your site with AMA, you should do a final refresh of the content, and then promote your site to Dev or Stage using the Promote button in the Cloud Platform UI. For more information, see Finishing your Drupal 9 site.

How do Drupal Starter Kits and AMA work together? I was not asked which distribution I wanted to use during the AMA process. How and when do I choose Drupal Starter Kits as my distribution?¶

Drupal Starter Kits and AMA do not work together. AMA cannot transform data of existing sites to fit into Drupal Starter Kits' data model. You can use Drupal Starter Kits, but it will not display your Drupal 7 data.

Is AMA a module of Drupal 9?¶

AMA is more than a module as it also includes auto-generating a Drupal 9 site based on your Drupal 7 site. However, there is an AMA module for Drupal and it runs on Drupal 9. Basically, AMA spins up a new Drupal 9 site, including the AMA module. You gradually migrate your Drupal 7 data to Drupal 9 by interacting with the AMA module.

My migration environment failed to get created successfully. Why?¶

There are several reasons why your migration environment might initially fail. Check for error messages in the task log in the Cloud Platform user interface, or go through the following checklist:

1. In your sites.php file, ensure that the default domain name of your source environment is configured to use the site directory that you wish to migrate. For more information, see I want to change the source database for my migration. If your sites.php file is configured incorrectly, you might see an error message similar the following:

   Generating recommendations failed. If you have a docroot/sites/sites.php file, please make sure that the internal
   Acquia domain https://EXAMPLE.prod.acquia-sites.com/ is configured to point to the docroot/sites/ subdirectory that
   you wish to migrate. See the documentation for details.
   

2. Some modules on Drupal.org claim to be compatible with Drupal 9. However, they actually cause issues when you install them in Drupal 9. The migration environment fails when one of these modules is installed. Acquia constantly monitors these modules, but new releases happen all the time. It’s possible that you’ve run into a recent regression. Create a Support ticket so that Acquia can block the module and help you move forward. You might see an issue similar the following:

   Your requirements could not be resolved to an installable set of packages.
   

3. Check to ensure that your repository has a “welcome” tag. If you’ve removed it previously, you can recreate a dummy “welcome” tag (it can be empty with just a text file), and then the environment creation process should work as expected.
4. Check to ensure that you’re following Drupal and Acqiua best practices for Setting the private file directory on Acquia Cloud. If your site’s private file directory does not follow these best practices, it may cause issues.

I have some issues to resolve on my messages tab. What is the best way to handle them?¶

The messages tab includes two types of messages that should be addressed differently:

• Migration issues: these typically need to be fixed on the Drupal 9 site after your migration. However, some of these issues may be solved by making changes on the Drupal 7 site. For most of these issues, Acquia Migrate Accelerate automatically provides a suggested solution. If it does not, create a Support ticket.
• Entity validation errors: these are virtually always data integrity errors on your Drupal 7 site, and must be fixed there. For example, after the content of a particular type was already created, a new required field was added. The content that was already created never had this required field filled in. You need to click Refresh in the Acquia Cloud UI after making these changes. They then appear in the migration environment and the validation errors disappear after importing the refreshed data.

I want to use Acquia Migrate Accelerate to migrate a Drupal 7 multi-site. How can I do that?¶

Acquia Migrate Accelerate does not officially support multisite migrations. However, you can migrate one site at a time by changing the default database. Follow the steps in the section I want to change the source database for my migration to change the source database for your migration to do so.

I want to change the source database for my migration. How can I do that?¶

Set up your internal Acquia FQDN to point to the same site as the one you want to migrate by doing the following:

1. In your sites.php file, ensure that the default domain name of your source environment is configured to use the site directory that you want to migrate. So, a line similar to the following is used if the multisite you want to migrate resides in docroot/sites/foobar:

   $sites['EXAMPLE.prod.acquia-sites.com] = 'foobar';
   

If there’s only one site directory, Acquia Migrate Accelerate uses that one. Otherwise, it uses the default.

If there’s more than one site directory and no default is specified, it fails with an error message similar the following:

Generating recommendations failed. If you have a ``docroot/sites/sites.php`` file, please make sure that the internal Acquia domain
https://EXAMPLE.prod.acquia-sites.com/ is configured to point to the ``docroot/sites/`` subdirectory that you wish to migrate. See
the documentation for details.

How can I move custom modules to my Drupal 9 site?¶

Acquia Migrate Accelerate cannot migrate custom modules. However, you can port the module to Drupal 9 and then add the module to the git branch that you’re using for the AMA environment. Preferably using composer require companyname/modulename, to make it easy to version the module independently of the migration environment, if it needs to be recreated.

I have a content type that cannot be migrated due to dependencies, but I cannot migrate the dependencies. What shall I do?¶

If you do not see specific dependencies on the In Progress tab, check to see if you skipped them. If so, they appear on the Skipped tab. You must unskip them to add them back to the Migrations tab so that you can take action.

In other cases, there may be issues with the dependent migrations that you need to address before they can be successfully migrated. Click the module name to view the messages specifically related to that migration.

In some cases, you may have circular dependencies in your data model that prevent you from moving forward. In such a case, create a Support ticket. You must provide a sanitized copy of your database so that the Acquia Support team can reproduce and troubleshoot your issue.

I want to start over, or need to recreate my migration environment. How can I do that?¶

If you’ve encountered issues where using a new migration environment is the best course of action, you may need to destroy your existing environment and create a new one. Look for the trash can icon in the upper right corner of the migration environment.

When you create the new migration environment, you will get the latest version of the AMA module, the latest version of the Recommendations Engine will be applied to your Drupal 7 site, you’ll install a fresh Drupal 9 environment, and re-import the latest content from your D7 production site.

Before doing that, ensure that all of your code changes are committed to the Git branch that your AMA environment is using. The Git branch name is indicated on the AMA environment card, and starts with “ama-“.

The new migration environment creates a new branch that does not include any of the work you did on your theme, your custom code, or any additional configuration changes that you made previously. Incorporate the work that you’ve already done by merging all the feature branches you were working on, or by cherry picking the changes and adding them to the new branch. If you are porting custom modules or themes, Acquia recommends to version each module or theme individually so that you can use the composer require companyname/modulename command for each of them in your new migration environment. That is simpler than moving over the work from the previous AMA branch.

If you need help with Git, see Resources for Learning Git in Acquia Knowledge Base.

I need to update the AMA module, but I don’t want to recreate my migration environment. What can I do?¶

For the AMA module, if there are new features or fixes that you need for your migration, you may be instructed to update to the latest version of the AMA module.

You do not need to start over with a new migration environment to take advantage of the latest features and fixes in the AMA module. Instead, run the following command on localhost or a Cloud IDE:

composer update acquia/acquia-migrate-accelerate --with-dependencies

Commit the result to Git. However, if you need to take advantage of features and fixes to the migrations recommendations or migration processing, you will need to recreate your migration environment.

I refreshed my database, but there is more data in the Refresh tab than I expected. What can I do?¶

With AMA’s Refresh function, you can copy over the live production database and file from your Drupal 7 site to the migration environment. After refreshing, you may see more content on the Refresh tab than what was changed. AMA is built upon Drupal’s migration system, which is unable to isolate the specific rows that were changed, so identifying the specific content types that were changed is definitely out of reach. The migration system knows which tables are changed, and so AMA identifies all of the migrations that rely on those tables as items to refresh.

For example, if a single node (an article, page, or blog) was created, the migration system does not know which of those types of content needs to be refreshed. Therefore, AMA marks them all as needing a refresh, and all appear on the Refresh tab.

The composer.json file that was generated by the Acquia Migrate Accelerate module is restricting the version of modules so they can’t be updated. How do I update them?¶

Yes, the AMA-generated composer.json is restricting versions of just about every module, for two reasons:

• It’s pinning to a specific version, such as 1.4, if one or more patches, which add or fix migrations, are applied. That’s because the patches may not apply to newer versions.
• It’s specifying a particular minimum version, such as ^2.3, to ensure that a version of the module is installed that contains a migration path that Acquia has vetted. This is particularly true for Drupal core, where for the past year, AMA has been applying between 30 and 50 patches to it for you, to make the migration work reliably. Acquia is always working to get those patches committed upstream.

After the migration is complete¶

After the migration is complete, you uninstall the acquia_migrate, migrate_drupal, and migrate modules. After that, there is no more need for patches that add or fix migrations. At this point, you can remove the patches and also make all of the version constraints less restrictive. For example, AMA currently recommends drupal/user_hash 2.0.0 with this patch:

"require": {
     …
     "drupal/user_hash": "2.0.0",
     …
 },
 "extra": {
     …
     "patches": {
         …
         "drupal/user_hash": {
             "Issue #3232037: Configuration missing while D7 to D9 migration": "https://www.drupal.org/files/issues/2021-09-09/configuration_missing-3232037-2.patch"
         },
         …
     },
     …

If you delete that patch, you end up with:

"patches": {
     …
 }

then you can also loosen the version constraint, which means you end up with:

"require": {
     …
     "drupal/user_hash": "^2",
     …
 },
 "extra": {
     …
     "patches": {
         …
     },
     …

Now, run composer install to see:

$ composer update drupal/user_hash
Gathering patches for root package.
Loading composer repositories with package information
Updating dependencies
Lock file operations: 0 installs, 1 update, 0 removals
  - Upgrading drupal/user_hash (2.0.0 => 2.0.1)
Writing lock file
Installing dependencies from lock file (including require-dev)
Package operations: 0 installs, 1 update, 0 removals
  - Downloading drupal/user_hash (2.0.1)
Gathering patches for root package.
Gathering patches for dependencies. This might take a minute.
  - Upgrading drupal/user_hash (2.0.0 => 2.0.1): Extracting archive
   Generating autoload files
43 packages you are using are looking for funding.
Use the `composer fund` command to find out more!

In this example, composer found the newest version matching the constraint ^2. You’ll have to repeat this process for every package that has a specific version pinned. Composer unfortunately makes this hard to automate. Besides, you’ll want to do this gradually to ensure everything continues to work. You may have added patches of your own, which you do not want to remove.

I need to provide a “sanitized database” to the AMA team so they can troubleshoot an issue. How do I do that?¶

Every Drupal site is different, and so is every Drupal 7 to 9 migration. Your migration might run into an issue that Acquia Migrate Accelerate has not seen before. When this happens, the AMA team requests a “sanitized database” from your Drupal 7 site so that they can reproduce the issue and develop a resolution that will help you move forward, and ensure that others do not run into the same issue. The following are the instructions for creating a sanitized database on Acquia Cloud:

1. Back up your development environment database.
2. Copy your production database to your development environment.

3. SSH into your application and run the following command to generate the sanitized database:

   drush sql-sanitize

4. Share the file with Acquia’s Support team by attaching it to the support ticket.
5. Restore the backed up database to your development environment.

Can I use Acquia Migrate Accelerate without an Acquia subscription?¶

For all Drupal site owners, an open source version of the Acquia Migrate Accelerate module is available in the community. With this module, all Drupal 7 users can leverage the Acquia Migrate Accelerate module to migrate their site to Drupal 9. For more information, see Acquia Migrate: Accelerate - now open source!.

An Acquia Cloud subscription is required to use Cloud Platform and leverage Acquia Migrate Accelerate in the Cloud Platform user interface.