This guide will describe the procedure to use Acquia Migrate Accelerate.
Note
Acquia will remove all features of Acquia Migrate Accelerate from Cloud Platform on April 10, 2024. For all Drupal site owners, an open source version of the Acquia Migrate Accelerate module is available in the community. For more information, see Acquia Migrate: Accelerate - now open source!.
The steps to use Acquia Migrate Accelerate are as follows:
Step 0: Prerequisites - entitlement and permissions
Your Acquia Account Manager can grant you access to Acquia Migrate Accelerate via an entitlement on your Acquia Cloud Enterprise subscription. Send them an inquiry, if interested.
Once this has been granted, you have access to start using Acquia Migrate: Accelerate! However, because Acquia Migrate Accelerate takes a copy of your production site’s data, the ability to generate the Acquia Migrate Accelerate environment is only granted to users with appropriate permissions.
Acquia Migrate Accelerate defines the following new permissions:
Manage the Acquia Migrate Accelerate Migrate Environment: Create, promote, and delete the Migrate Environment within an application.
Refresh the Acquia Migrate Accelerate Migrate Environment: Pull down a fresh copy of data from the production website.
By default, these permissions will only be granted to the Administrator role. See Working with roles and permissions for information on how to assign Acquia Migrate: Accelerate permissions to other roles.
Step 1: Access Acquia Migrate Accelerate
To start using Acquia Migrate Accelerate:
Log in to your Cloud Platform account.
In the Develop menu, select the correct Organization, and then click Applications, and the specific Drupal 7 Application you wish to migrate.
From this page, click the Actions button towards the upper-right side of the screen and select Create Migration Environment (note that it can take a few moments for this option to appear). This will start the wizard that will provide an overview of the required steps.
Tip
If you do not see this option, make sure that your Cloud user has the appropriate permissions listed in Step 0.
Step 2: Migration wizard
This will begin the Migration Wizard, which will provide an overview of the process, prompt you to give the environment a name, and provide the choice of whether or not to copy environment settings over from your production environment.
At the end of the wizard, you’ll be given a summary and directed to begin environment provisioning. Click Start Provisioning to complete.
If at any time you make a mistake this does not describe what you want, click Go Back and adjust settings as needed. If you want to cancel the entire process, click Cancel.
Step 3: Wait for access to Acquia Migrate Accelerate environment
Depending on the size of your D7 database and files, you must wait for a few minutes to a few hours while your new Drupal 9 site and your environment are provisioned. The provisioning of the AMA environment is handled as a task on the task server. Therefore, like other tasks such as cron jobs and deployments, you do not need to wait with the browser window open while the process gets completed. You can periodically check to monitor the progress.
Under the hood, this process creates an On-Demand Environment (ODE) for your application, copies the Drupal 7 production site’s database and files to it to use as source data for the migration, and runs the Drupal 7 module list against the Module Recommendation Engine to determine the best Drupal 9 equivalents. A Drupal 9 site will be automatically generated and installed based on these recommendations, and its code committed to a new branch in your repository called ama-XXXXX.
Once completed, you will have a new environment in your list, which contains some migration-specific features and functionality.
Tip
This environment intentionally looks different from your other environments, and lacks drag/drop deployment capabilities, among some other features. This is done in order to prevent accidentally overwriting your Drupal 7 code/data with Drupal 9 code/data or vice-versa. Instead, use Refresh when you need to get an update of the Drupal 7 data onto the site, or Promote when you are ready to deploy your Drupal 9 site to become your new production site.
Step 4: Set up your new Drupal site (one-time)
To configure your new Drupal 9 site, complete the following:
Click the Migration Dashboard button on your new environment to move from the Cloud interface to the Drupal interface and begin configuration.
Essential Configuration: The first page will direct you to enter the following information:
Base URL: The URL to your Drupal 7 production website (this is used to link in case of content edits, which need to be made on the source site and refreshed down).
Email address, username, and password for the User 1 account on the Drupal 9 site (we prompt for this in case organizations are outsourcing their migrations to third parties and do not wish to share the production User 1 credentials with their contractors)
Log In: Enter your User 1 username and password to log into your Drupal 9 site.
Security notice: The Acquia Migrate Accelerate environment is by default publicly accessible to aid in content auditing by other members of your team. This page provides you with tips and advice on locking it down further should you need.
Step 5: Select the data to migrate (one-time)
The initial Acquia Migrate Accelerate screen displays a list of data (content types, nodes, taxonomy vocabularies, and so on) from your Drupal 7 site, along with the number of records for each, and any dependencies between elements. By default, all data with at least 1 record will be selected, though you can customize further (for example, to remove “test” content types) by selecting or clearing the checkbox of one or more of the data present.
When you are happy with your selections, click Start Migration, then View Migrations Dashboard to begin!
Step 6: Import and view records from the Dashboard
Next, you’ll be prompted to click View Migrations Dashboard. Go ahead, click it and you’ll be taken to the Migration Dashboard (also available from Acquia Migrate > Migrations).
On your first visit to the Migrate Dashboard, it will perform an initial import of your underlying data structures (for example, content type definitions) and dependencies (such as Filter Format configuration) that are required in order to begin importing your content from Drupal 7 to Drupal 9.
The Migrations Dashboard acts as your main work area. You can import (or rollback) content, and watch the content migration as it runs. Viewing error logs and dashboard messages may help you to see possible migration issues, stalled migrations, or other issues. From here, you can:
Review the content in the In progress, Needs Review, Completed, Skipped, and - Refresh tabs.
Track the progress of the migration (how many records have successfully migrated of the total number to migrate).
See the count of migration errors that have occurred.
Check the import status and other details for any given piece of data.
Here’s a brief summary of the tabs that you see on the Migrations dashboard:
Tab | Description |
|---|---|
In progress | Lists the migrations that have yet to be imported; your “to-do” list. |
Needs review | Lists the migrations that completed but with issues. |
Completed | Lists the migrations that completed without any issues. |
Skipped | Lists the migrations that were explicitly marked as skipped in the migration process. (For example, content types with fields that do not have an equivalent Drupal 9 module yet.) |
Step 7: Resolve migration issues
Preview data to check for issues
Click in a specific Migration row to review the Preview, Mapping, or Details tabs.
Using the Preview tab, you can review data before it is migrated to the new site to check for errors, including data in the wrong field, malformed data, and missing data or images. You can compare both “raw” before and after values, as well as see a visual preview of the content.
To troubleshoot a single content item (such as your “About Us” page), you can use the By source site URL field and enter the original source site URL to see how it will be migrated.
Note
Make sure the target is the same type as the migration you’re viewing. If you’re looking at Articles, but providing the URL to a Page, the Preview function will not find it.
Important
If you find problems, generally speaking, these should be resolved on the source site and then re-migrated with the Refresh capability in your migration environment in Cloud Platform.
Resolve Migration Issues in Messages
Navigate to Acquia Migrate > Messages to review any migration messages.
The following two types of issues are tracked:
Migration issues, which must be fixed on the Drupal 9 site.
Entity validation errors, which are content errors on your D7 site that must be fixed there.
Messages can be dynamically filtered by type, specific migration, and so on. For common errors, Acquia also provides a solution with recommended next steps.
Refreshing content from production
Your new Drupal 9 site should be considered read-only from the perspective of content changes. The Refresh capability of Acquia Migrate Accelerate allows you to down-sync the latest content changes from production so that you are always migrating against the latest data.
When fixing entity validation errors, or even when correcting a small typo, you need to make the content change on your source site (Production), and then click Refresh on the Acquia Migrate Accelerate Cloud environment to bring the new content down.
Once this is done, the Refresh tab on the Migrations Dashboard shows new records to import. Select them, click Import, and your content changes will make their way over to your new site!
Resolve Migration Issues in the Module Auditor
Navigate to Acquia Migrate > Modules to view the Module Auditor, which provides an overview of the Module Recommendation Engine decisions that were made for your particular site. You can search or filter the results; for example, restricting the list to only modules with an Acquia-vetted migration path.
Tip
While the Module Recommendation Engine will download all modules that it knows to download for your site, only modules explicitly marked as Acquia-vetted are installed by default.
Toggle between the Found (contrib) and Unknown (custom) tabs to review the module recommendations provided, and go ahead and install or uninstall the desired modules based on your requirements.
Tip
You generally will have better results if you install new modules one at a time, instead of all at once. In particular, modules that define their own migration paths can introduce further migration-related bugs into the process.
Once you have completed your migration, you have the following options:
Click the Migration Dashboard button to move into your Drupal site to start or continue your migration.
Click the Promote button to deploy your new site to one of your other Cloud Platform environments in preparation for it to go live.
Click the Refresh button to pull the latest data and files from your source Drupal 7 environment. This ensures that you’re always migrating against the latest target.
(Optional) Step 8: Debug the underlying migrations
Mapping Page Overview
The Mapping page provides insight into how the underlying migration is structured in the Drupal Migrate API. This can be useful information for debugging, if the preview is not looking as expected.
The table lists the following:
Item | Description |
|---|---|
Source Field | Name of the database column coming from Drupal 7 |
Destination Field | Name of the database column going into Drupal 9 |
Field Type | Describes the nature of the data contained within this column’s data; for example, Integer, String, Entity Reference |
Process Plugins | Any transformations to the data that are occurring along the way; for example, looking up data from another table, or skipping the row if the value is empty. |
In addition, if the data for a particular migration has not been imported yet, you can override a default mapping to make changes to it. Currently, the only property that can be overridden is the ability to skip a source field. This can be useful if there is a particularly problematic field which does not have a Drupal 9 equivalent module, and you want to ensure that the rest of the data imports fine without it. Later, when a suitable migration is found for the field, you can unskip it, rollback, and attempt the import again.
Details Page Overview
Acquia Migrate Accelerate makes an effort to surface available migrations in site builder terminology. However, often, a single migration in Acquia Migrate Accelerate can represent several Migration Plugins from the Drupal Migrate API under the hood.
The Details page is a tool for developers to gain insight into the underlying Migration Plugins for a particular human-readable migration, as well as what dependencies it has, and why.
The underlying migrations make reference to YAML files in the file system at
paths such as /core/modules/ORIGINATING_MODULE_NAME/migrations/
UNDERLYNG_MIGRATION.yml.
Step 9: Port your custom code to Drupal 9
Acquia Migrate Accelerate is very useful for bringing over your site’s configuration and content, and for providing the best-known migration path for 100s of Drupal’s contributed modules.
For custom code, however, including custom modules, code modifications, and your theme (look and feel), Acquia Migrate Accelerate will point you in the direction of useful resources, but cannot automate these changes by itself.
You can also take a look at the Drupal community module Drupal 7 to 8/9/10 Module Upgrader , which attempts to automatically convert several of the most common APIs from Drupal 7 to the current Drupal version.
Acquia Site Studio is an optional product pairing that provides a low-code solution to generating your site’s look and feel on the current Drupal version. For more information, view Acquia Migrate > Appearance.
Cloud IDE is another optional product pairing that provides easy access to development tools such as XDebug, Drush, and Composer for performing the last 20 percent of your migration.
Common data migration issues and how to solve them
If you wish to take a look at the common data migration issues and ways to resolve them, see Known issues when upgrading from Drupal 7.