All Collections
Integrations
Magento Open Source and Adobe Commerce
Setup
Configuration guide for Magento Open Source and Adobe Commerce
Configuration guide for Magento Open Source and Adobe Commerce

Learn how to install and set up the Dotdigital for Magento 2 connector.

Gareth Burroughes avatar
Written by Gareth Burroughes
Updated over a week ago

This comprehensive guide provides start to finish instructions for users who need to install and configure the connector for the first time. It focuses on the most important things you need to know and do, in order to get up and running.

This guide doesn't cover advanced features. Full and comprehensive guidance can be found in the Dotdigital for Magento Open Source and Adobe Commerce section of the Help Centre.


Before you start

Things you need to know:

  • The integration has an initial onboarding charge for setup assistance, and a monthly license fee to ensure ongoing support and development. To learn more, speak to your Customer Success Manager.


Pre-installation Health Check

Compatibility

The Dotdigital for Magento connector is compatible with both the Community and Enterprise platforms of Magento.

  • For Community we're compatible with 2.2 +

  • For Enterprise we're compatible with 2.2 +

Conflicts

While every site is different, the connector could potentially come into conflict with other extensions, for example, abandoned cart extensions and other SMTP tools. It’s important therefore to state these during the installation process.

File Permissions

  • Requires full access (0777) to the var/export directory or full access to the CRON user running on the server.

Cron Tasks

The connector has several cron tasks attached with the install to ensure the connector functions correctly. Below is a list of current tasks and their timings:,The cron heartbeat should be running every minute to action the required tasks.

Have Multiple Websites?

The connector supports multiple websites. If there are multiple sites within the same Magento instance then we recommend you link one site to one Dotdigital account. If you are configuring multiple sites to multiple Dotdigital accounts, you must follow the entire process for each separate Dotdigital account you have.


Installation

The installation of the Magento 2 connector can be done via FTP or Composer. If you are on a version of Magento 2.2.2 + the connector is already bundled into Magento and no installation is required.

FTP

  1. Download the files to the connector from GitHub located at https://github.com/dotmailer/dotmailer-magento2-extension

  2. Unzip the downloaded file.

  3. Create the directory structure in Magento (Magento_Root/app/code/Dotdigitalgroup/Email).

  4. Drop all content inside the unzipped folder to directory (Magento_Root/app/code/Dotdigitalgroup/Email).

  5. Run the command php bin/magento module:enable Dotdigitalgroup_Email in Magento root.

  6. Run the command php bin/magento setup:upgrade in Magento root.

  7. Run the command php bin/magento setup:di:compile if you have a single website and store or run php bin/magento setup:di:compile-multi-tenant if you have multiple.

  8. Clear cache from Magento admin.

Composer

  1. Set up the correct path for Composer or keep Composer within Magento root.

  2. In Magento root, run command composer require dotmailer/dotmailer-magento2-extension.

  3. After the above is successful, run the command php bin/magento module:enable Dotdigitalgroup_Email in Magento root. This lets Magento know about the module.

  4. Run the command php bin/magento setup:upgrade in Magento root. This ensures any installer scripts we may have are executed properly and store the current data version.

  5. Run the command php bin/magento setup:di:compile if you have a single website and store.

    • Run php bin/magento setup:di:compile-multi-tenant if you have multiple.

  6. Clear cache from Magento admin.

Bundle (Magento 2.2.2 +)

The bundled version comes stock with version 2.3.8 of the connector. There are a few different scenarios for how to properly setup and upgrade the connector. Each scenario is documented in detail in our Upgrading to Magento 2.2.2 article. We strongly suggest that you review this article prior to doing any work with the connector.

Enterprise Edition

Additional files are required to synchronise certain types of data found in Enterprise versions of Magento such as Reward Points and Customer Segments. The files can be found on GitHub. and should be added after the standard connector has been installed.


Credentials

Create an API user

To enable the connector to communicate with your Dotdigital account and allow data synchronisation, you need to enter valid Dotdigital API credentials.

API user credentials are made up of a username and password and are required to authenticate each operation/method call that's made and to make sure you're connected to the correct account.

To create an API user:

  1. Expand the User menu in the bottom left and go to Settings > Access > API users.

  2. Select NEW USER.

  3. Enter a description and password for the new API user.

  4. Select Enabled to activate the user.

  5. Select SAVE.

Create a transactional email user

You can make use of Dotdigital's transactional email service to send, manage and track all of your transactional emails. The transactional service acts as a delivery mechanism for all the transactional emails such as order and shipping confirmations.

Learn more about using Dotdigital's EasyEditor to create and manage transactional emails for Magento in the Transactional email templates article.

To create a transactional email user:

  1. Expand the User menu in the bottom left and go to Settings > Transactional email > Credentials.

  2. Select NEW USER.

  3. Enter a description and password for the new transactional email user.

  4. Select Enabled to activate the user.

  5. Select SAVE.

Enter API credentials in Magento

To enter your API credentials:

  1. Go to Stores > Configuration.

  2. Expand the Dotdigital menu, then select Accounts.

  3. Expand the Enabled drop-down menu, and select Yes.

  4. Select Save Config.
    You see a confirmation to notify you that the credentials are valid.

Enter transactional email credentials in Magento

To enter your transactional email credentials:

  1. In Magento 2, go to Stores > Configuration.

  2. Expand the Dotdigital menu, then select Transactional Emails.

  3. Expand the Enabled drop-down menu, and select Yes.

  4. Expand the Send Mode drop-down menu, and select SMTP.

  5. For Host, enter your hostname:

    • r1-smtp.dotdigital.com if you have an account belonging to region 1 (Europe)

    • r2-smtp.dotdigital.com if you have an account belonging to region 2 (North America)

    • r3-smtp.dotdigital.com if you have an account belonging to region 3 (Asia)

  6. Enter your transactional email Username and Password.

  7. Expand the Port drop-down menu, then choose an open port.

    • Options: 25, 587, and 2525.

  8. Select Save Config.

Multiple environments

A separate set of credentials must be used for your live and staging sites.


Map data fields

In addition to the basic contact information, the connector provides you the ability to map over 40 other pieces of key retail information that you store about contacts from your Magento website to your Dotdigital account.

To automatically map your data fields:

  1. In Magento 2, go to Stores > Configuration.

  2. Expand the Dotdigital menu, then select Developer.

  3. Under the heading Sync Settings, for Automap Data Fields, select Run Now.


Lists

The connector synchronises contacts to three different lists for three Magento contact types:

  • Customers - Registered customers of your Magento site that have a customer account.

  • Subscribers - Contacts who have opted into newsletter subscription on your site.

  • Guests - Email addresses from an order placed during guest checkout. They are neither a customer or a subscriber.

Before synchronisation begins, you must create these lists in Dotdigital so they can be selected and mapped to from within the connector.

Create lists

Lists can be created directly in the connector or from inside your Dotdigital account.

To create lists:

  1. Go to Stores > Configuration.

  2. Expand the Dotdigital menu, then select Sync Settings.

  3. Under the heading Create List, for List Name, enter a name for your list.

  4. Expand the Visibility drop-down menu, and choose either Private or Public.

    • This setting controls whether contacts can see the list in a preference centre.

  5. Select Create New List.

Repeat the steps above until all lists are created.

Mapping

To map your lists:

  1. In Magento 2, go to Stores > Configuration.

  2. Expand the Dotdigital menu, then select Sync Settings.

  3. Under the heading List Mapping, expand the Add Customers To drop-down menu, and choose the list you want to add your customers to.

  4. Expand the Add Subscribers To drop-down menu, and choose the list you want to add your subscribers to.

  5. Expand the Add Guests To drop-down menu, and choose the list you want to add your guests to.

  6. Select Save Config.


Tracking

Site tracking enriches your data and your understanding of your contacts' engagement with your site, whilst ROI tracking gives you a greater appreciation of your campaigns' ROI conversion rates.

In Magento 2 version 3.2.4 upwards, site and ROI tracking are enabled by default.

To manage site tracking:

  1. In Magento 2, go to Stores > Configuration.

  2. Expand the Dotdigital menu, then select Configuration.

  3. Under the heading Tracking, expand the ROI Tracking drop-down menu, and select Yes.

  4. Expand the Page Tracking drop-down menu, and select Yes.

  5. For Web Behavior Tracking Profile Id, enter your Web behavior tracking ID. Learn more in Install Web behavior tracking.

  6. Select Save Config.


Easy Email Capture

Easy email capture functionality allows you to capture your site's user's email addresses when they haven't fully completed your checkout process or newsletter sign up process.

To turn on Easy Email Capture:

  1. In Magento 2, go to Stores > Configuration.

  2. Expand the Dotdigital menu, then select Configuration.

  3. Under the heading Abandoned Carts, expand the Easy Email Capture (Checkout) drop-down menu, then select Yes.

  4. Expand the Easy Email Capture (Newsletter) drop-down menu, then select Yes.

  5. Select Save Config.


Order Sync Settings

Import status

You can choose to only import and synchronize orders of a certain status, rather than all of them. For example, you might only be interested in sending campaigns or running segments based on orders that have been fulfilled. In this case, you might only want to import orders in a Complete status.

To choose your order import status:

  1. In Magento 2, go to Stores > Configuration.

  2. Expand the Dotdigital menu, then select Configuration.

  3. Under the heading Transactional Data, for Import Order With Status, select the order statuses you want to import.

    To choose multiple, hold down the CTRL key on your keyboard.

  4. Select Save Config.

Custom attributes

In addition to our standard default order data fields, you have the option to synchronize custom order attributes. This list comprises all of the order attributes that are available within the Magento system, allowing you to segment and send content based upon these additional fields.

To choose your order custom attributes status:

  1. In Magento 2, go to Stores > Configuration.

  2. Expand the Dotdigital menu, then select Configuration.

  3. Under the heading Transactional Data, for Order Custom Attributes, select the attributes you want to import.

    To choose multiple, hold down the CTRL key on your keyboard.

  4. Select Save Config.

Future adjustments

Changes made to custom order attributes are reflected in new imports run after the adjustment has been made. To include these in previous imports the order insight collection must be deleted and the data re-imported.


Catalog sync settings

The connector allows you to map and synchronise your product catalog to your Dotdigital account. With your product catalog synchronised, you can insert products into campaigns with ease with the Products building block, or set up Product recommendations.

You can choose to sync products of a certain visibility and/or product type rather than all products. This allows you to keep your catalog organised by excluding products that are no longer relevant on your site.

To manage your catalog sync settings:

  1. In Magento 2, go to Stores > Configuration.

  2. Expand the Dotdigital menu, then select Configuration.

  3. Under the heading Catalog Sync Settings, expand the Catalog values drop-down menu, then choose the catalog value.

  4. For Catalog Visibility, select the visibility type for the products to be exported.

  5. For Catalog Type, select the catalog types to be exported.

  6. Select Save Config.

Broken product images

To fix broken product images, try setting the Catalog Values to Store. This uses the store URL for the image path instead of the admin URL.


Enable sync

After your lists have been mapped and your order insight settings configured you can enable the data sync.

To enable data sync:

  1. In Magento 2, go to Stores > Configuration.

  2. Expand the Dotdigital menu, then select Sync Settings.

  3. Under the heading Sync, you can see all the different types of sync settings.

  4. To enable sync for a sync type, expand the sync type drop-down menu, then select Yes.

    Most users enable Customer, Subscriber, Guest and Order.

  5. Select Save Config.

Within 15 minutes contacts and insight data should begin to be batched. Details for advanced synchronisation options such as Wishlist and Review can be found at Dotdigital for Magento.

Delay

There is an hour delay prior to importing the order information. This delay is in place to prevent order imports from failing due to missing contacts.

Status check

There are several ways to check that data is syncing from Magento into Dotdigital.

Contact sync report

Contacts that are successfully batched to be imported should be marked as Imported.

To view your sync report:

  1. In Magento 2, go to Stores > Configuration.

  2. Expand the Dotdigital menu, then select Sync Settings.

  3. Under the heading Sync, you can see all the different types of sync settings.

  4. Find the sync you want to view the report for, then select Click here for status.

Importer Status

Batched contacts/orders should exist in this report. Once the importer cron has run an import should be marked with a status of Importing. Shortly after, data should appear in Dotdigital.

To view your importer status:

  1. In Magento 2, go to Reports > Customer Engagement > Importer Status.

Troubleshooting

Cron

Confirm Dotdigital (ddg) cron jobs are running. Cron is a vital part of making sure your data syncing happens correctly. We recommend installing Cron Job Manager to give you a real-time view of the tasks running throughout your site, as well as giving you the ability to manage and configure your cron jobs.

API user

Confirm API credentials are active and valid. You can view the status of the API credentials on the dashboard. The dashboard can be accessed under Reports > Dashboard.

Sync Enabled

Confirm at least one contact sync is turned on.

Check Permissions

Requires full access (0777) to the var/export directory or full access to the CRON user running on the server.


Abandoned cart - email series

Abandoned cart emails are an important tool and key sales recovery strategy for ecommerce businesses. Research by marketing industry experts has suggested that around 70% of online consumers abandon carts. That means about one in three carts gets checked out first time.

Abandoned cart series are set up directly within the interface of the connector and can be sent to customers and guests. Customers and guests can receive up to three different emails that are scheduled for different time intervals. If your Magento instance has more then once website, you can configure different emails and settings per website.

Using external dynamic content (EDC), you can include the contents of their cart within the body of the emails you send.

Learn more about setting up abandoned carts in Magento 2 in Abandoned cart: Setting up an abandoned cart program - Magento 2 and Create an abandoned cart email.

Need more flexibility?

If you require more flexibility with setting up abandoned carts you can enrol contacts into an Abandoned Cart Program. This allows you to use the Program Builder to tailor the abandoned carts to fit your business needs. For example, you can include more emails or exit contacts based on specific types of behavior. This feature is only available in connector version 3.20 and above.

Status Check

You can check the status of abandoned cart emails with the Campaign Sends report. To access the Campaign Sends report, in Magento 2, go to Reports > Customer Engagement > Campaign Sends.

In this report, you can see whether abandoned cart emails are being queued for sending, whether they are being sent to Dotdigital, and whether anything is failing. You can sort and filter this report in a number of ways to find the information you're looking for.

Troubleshooting

External Dynamic Content

Confirm the external dynamic content link is correct that you’re using for pulling abandoned carts information into your campaign content. To check this select Dynamic Content from the Dotdigital menu in Magento.

Cron

Confirm ddg_automation_abandonedcarts and ddg_automation_campaign cron jobs are running. Without both of these running abandoned cart emails will not be batched or sent.

Conflict

Disable extensions you might have used previously to send abandoned cart emails.

Did this answer your question?