Import URL Rewrites

You can easily migrate to the Magento Commerce Cloud platform without losing SEO rankings and traffic. Use the magento/url-rewrite-import-export module to redirect traffic from your old, indexed URLs to new URLs.

This module supports PHP versions 7.0.13 and later patch releases and all 7.1.x and 7.2.x patch releases. The module is available for Magento version 2.2.x and 2.3.x only.

To install the URL rewrite module:

  1. Add the module to the composer.json file.

    1
    
    composer require magento/module-url-rewrite-import-export
    
  2. Configure the .magento.env.yaml file deploy stage with cron consumers to run urlRewriteImport only.

    1
    2
    3
    4
    5
    6
    7
    
    stage:
      deploy:
        CRON_CONSUMERS_RUNNER:
          cron_run: true
          max_messages: 1000
          consumers:
            - urlRewriteImport
    

    Or, you can configure to run all consumers:

    1
    2
    3
    4
    5
    
    stage:
      deploy:
        CRON_CONSUMERS_RUNNER:
          cron_run: true
          max_messages: 1000
    

    See CRON_CONSUMERS_RUNNER environment variable for more information about configuring consumers:

  3. Add, commit, and push code changes.

    1
    
    git add -A && git commit -m "Install UrlRewriteImportExport module" && git push origin <branch name>
    

Import the URL Rewrites file

The URL Rewrites module exports custom rewrites using the following CSV file format:

request_path,target_path,redirect_type,store_code
request-test1,home,0,default
request-test2,home,301,default
request-test3,contact,302,default
Column Description
request_path Redirect FROM the request path.
target_path Redirect TO the target path.
redirect_type The type of redirect:
0 —an internal Magento redirect type. Magento renders a page using the target_path path.
301 —permanently moved status code.
302 —temporarily moved status code.
store_code The store view code.

You use the Magento Admin panel to import the URL Rewrites file.

To import URL Rewrites:

  1. On the Marketing menu, click URL Rewrites in the SEO & Search section.

  2. Click Add URL Rewrite.

  3. In the form, click Upload and choose the CSV file to import.

  4. Select the Behavior.

    • Add/Update — adds new URL rewrite and updates existing URL Rewrites
    • Delete — removes existing URL rewrites
  5. Click Import.

    The import task begins with the following message:

    Task scheduled URL rewrite

    A successful import returns the following message:

    Successful URL rewrite

Troubleshooting the import

Large uploads are limited by the upload_max_filesize directive in php.ini. If your URL file is bigger than the existing limit, see Customize php.ini settings to increase it.

If the import is not successful, you receive an error message reporting the URL rewrite failed:

Failed URL rewrite

To research the URL rewrite error:

  1. Click View Details to see detailed information about the failure.

    Alternatively, you can find this log on the System menu, click Bulk Actions in the Action Logs section.

  2. In the Bulk Actions Log view, search for your task, and click Details in the Action column.

    Bulk actions log

  3. In the Action Details view, click the error number in the ID column to download a report about the failed operation.

    An example report:

    request_path,target_path,redirect_type,store_code,messages
    request-test1,home,503,default,"This line is ignored. Column redirect_type has wrong redirect code"
    request-test,contact,302,second,"This line is ignored. Store View with second code does not exist"