Configuration guide - Magento 2

This comprehensive guide provides start to finish instructions for users who are attempting 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 going. 

This guide doesn't cover advanced features. Full and comprehensive guidance can be found at dotmailer for Magento 2.

Contents

  Pre-Installation Health Check
  Connector Installation
  API and Transactional Credentials
  Mapping Data Fields
  Address Books
  Tracking
  Easy Email Capture
  Order Sync Settings
  Catalog Sync Settings
  Enable Sync
  Abandoned Carts

Pre-Installation Health Check

Compatibility

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

  • For Community we're compatible with 2.0 +
  • For Enterprise we're compatible with 2.0 +

Conflicts

While every site is different, the connector could potentially come into conflict with other extensions. For example, abandon cart extensions and other SMTP tools could also possibly come into conflict with the connector, and this makes it important 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:

  • ddg_automation_abandonedcarts - 5 minute intervals
  • ddg_automation_campaign - 5 minute intervals
  • ddg_automation_catalog_sync -15 minute intervals
  • ddg_automation_cleaner – 1st of every month
  • ddg_automation_customer_subscriber_guest_sync - 15 minute intervals
  • ddg_automation_importer – 5 minute intervals
  • ddg_automation_order_and_quote_sync - 15 minute intervals
  • ddg_automation_reviews_and_wishlist - 15 minute intervals
  • ddg_automation_status -15 minute intervals

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 dotmailer account.  If you are configuring multiple sites to multiple dotmailer accounts, you will need to follow the entire process for each separate dotmailer account you have.

^ Back to Top


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. Download it as a ZIP and unzip the 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 will let Magento know about the module.
  4. Run the command 'php bin/magento setup:upgrade' in Magento root. This will ensure 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.
  6. Run 'php bin/magento setup:di:compile-multi-tenant' if you have multiple.
    Clear cache from Magento admin.

Bundle (Magento 2.2.2 +)

The bundled version comes stock with version 2.3.8 of the connector.  There is a few different scenarios on how to properly setup and upgrade the connector.  Each scenario is documented in detail in our 'Upgrading to Magento 2.2.2' article located here.   It is highly recommend to review the 'Upgrading to Magento 2.2.2' article prior to doing any work with the connector.

Enterprise Edition?

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

^ Back to Top


 Credentials

Create API User

To enable the connector to communicate with your dotmailer account and allow data synchronisation, you need to enter valid dotmailer 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. 

Click on the person-and-cog icon in the bottom left corner to produce the settings menu and select Access.

Screen_Shot_2018-03-09_at_1.46.53_PM.png

A settings menu will appear;  select the API users tab and click on New user.

Screen_Shot_2018-03-09_at_2.54.07_PM.png

Create Transactional User 

You can make use of dotmailer'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.  If you are looking to use dotmailer's easy editor to create and manage transactional emails for Magento please review the Transactional email templates article.

To use the transactional service a transactional user must be created. This process is similar to creating an API user. Select Access from the settings menu that appears when clicking the person-and-cog icon in the bottom left corner of the screen.

Screen_Shot_2018-03-09_at_1.46.53_PM.png

A settings menu will appear; select the Transactional email users tab and then click on New user to enter the details.

Screen_Shot_2018-03-09_at_1.54.17_PM.png

Enter API Credentials in Magento

Return to your Magento admin panel and select the API Credentials option from the dotmailer menu item.  This menu item can be accessed by navigating to Stores > Configuration.

menu_m2.png

Set 'Enabled' to Yes and then enter the credentials (username and password) of the API user just created

m2_auth.png

When finished click Save Config.  A confirmation is message is displayed notifying you the credentials are valid.

Enter Transactional Credentials in Magento

From Magento select Transactional Emails from the dotmailer menu.  

trans_menu.png

Select Yes to enable the feature then enter the hostname, username and password.

  • r1-smtp.dotmailer.com if you have an account belonging to region 1 (Europe)
  • r2-smtp.dotmailer.com if you have an account belonging to region 2 (North America)
  • r3-smtp.dotmailer.com if you have an account belonging to region 3 (Asia)

trans_settings_2.png

Select an open port. Your options are 25,587 and 2525.

port_trans.png

Click Save when finished.

Custom From Address

Remember to setup the accounts default Custom From Address. This is done from Transactional Email> Settings> From addresses. More information about Custom From Addresses can be found here.

^ Back to Top


Mapping Data Fields 

In addition to the basic contact information, the connector provides you the ability to map over 40 key retail information that you store on contacts from your Magento website to your dotmailer account.

To map the fields automatically choose the Developer option from the dotmailer menu.

dev_menu.png

Under the Sync Settings sections choose Run Now next to the 'Automap Data Fields' option. After a few moments, the page is reloaded with a success message.

automap.png

^ Back to Top


Address Books 

The connector synchronises contacts to three different address books 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 via guest checkout. They are neither a customer or a subscriber.

Before synchronisation begins, you need to create these address books so they can be selected and mapped to from within the connector.

Create

Address books can be created directly within the connector or within your dotmailer account.  To create address books from within the connector select the Sync Settings from the dotmailer menu.

sync_setting.png

Select the Create Address Book section towards the bottom of the page. Provide the address book a name and select the visibility. Selecting 'public' means contacts will be able to join or unsubscribe from it.  When finished, click Create New Address Book.

create_ab.png

Repeat the steps above until all address books are created.

Mapping

Under the Address Book Mapping section choose the appropriate address books from the drop-down menu to map your customers, subscribers and guests to.

ab_maps.png

When finished with your mapping, select Save Config in the top right.

^ Back to Top


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.

Site Tracking is managed from Configuration.

config_dm_menu.png

From the Tracking section select Yes for 'ROI Tracking Enabled' and/or 'Page Tracking Enabled'.

roi.png

When finished, click Save Config.

^ Back to Top


Easy Email Capture

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

Easy Email Capture is managed from Configuration.

config_dm_menu.png

From the Abandoned Carts section select Yes for “Easy Email Capture (Checkout)” and/or “Easy Email Capture (Newsletter)”.

EE_capture.png

When finished, click Save Config.

^ Back to Top


Order Sync Settings

Import Status

You have the option 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.

The order settings is managed from Configuration.

config_dm_menu.png

From the Transactional Data section choose the status types to be imported from the "Import With Status" list.

orderstatus.png

When finished, click 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 too.

Under the Transactional Data section choose the attributes to be included in the import from the "Order Custom Attributes" list.

custom_att.png

When finished, click 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 

^ Back to Top


Catalog Sync Settings

The connector provides the facility to map and synchronise your product catalog against your dotmailer account. With your product catalog syncrhonised, you will be able to insert products into campaigns with ease by utilising the 'Products' building block or setup 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.

The catalog settings is managed from Configuration.

config_dm_menu.png

From the 'Catalog Sync Settings' section choose the Store Value, Product Visibility and Product Types you want to sync. 

catalog_syn_settings2.PNG

When finished, click Save.

Broken Product Images?

Try setting the 'Catalog Values' to Store. This uses the store URL for the image path instead of the admin URL.

^ Back to Top


Enable Sync 

After address books have been mapped and your order insight settings configured you can enable the data sync. Return to the Sync Settings page by selecting Sync Settings from the menu.

sync_setting.png

Under the Sync section select Yes to all sync types you would like to enable. Most enable Customer, Subscriber, Guest and Order.

enabled_sync.png

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

Delay

When enabling order synchronisatoin for the first time 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 that data syncing from Magento into dotmailer is taking place.

Contact Sync Report

Contacts that are successfully batch to be imported should be marked as imported.  This is accessed under Sync Settings > Click here for status

imported_contact.png

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 dotmailer.  This is access under Reports > Marketing Automation > Importer Status

import_status.png

Troubleshooting

Cron

Confirm dotmailer (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.

^ Back to Top


Abandoned Cart

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 carts are setup and configured 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.

Creation

Abandoned carts uses a series of trigger campaigns.  To create and build trigger campaigns login to your dotmailer account.  From the main page choose the Automation menu item and then choose Trigger Campaign Content.  

Screen_Shot_2018-03-09_at_7.56.45_PM.png

Access the email content and drag the External Dynamic Content building block into the location where you would like the cart content to be displayed.

Screen_Shot_2018-03-09_at_8.21.48_PM.png

Return to Magento and navigate to Dynamic Content.  

dc.png

Copy the Abandoned Cart URL and return to the campaign in dotmailer.

ac_edc.png

Select the External Dynamic Content building block. Paste the Abandoned Cart URL previously copied to the 'Address' field then click Apply.  

Screen_Shot_2018-03-09_at_8.29.17_PM.png

When done editing the campaign content click Save

New to Automation?

If you are new to program building we suggest you watch the Automation training videos or review our Automation section.

 Configuration

After the campaigns have been created access the Abandoned Carts menu item from Magento

ac_menu_item.png

The page is broken down into two sections for Customers and Guests. Go through each section and enable the amount of abandoned cart emails you require.  Choose the time delay and Campaign to Send from each section as well.

ab_selection.png

When finished click the Save Config button.

Multiple Websites?

If you need to setup abandoned carts for separate websites select the website name from the site drop-down and then navigate to the Abandoned Cart menu item.

Status Check

You are able to check the status of abandoned cart emails by access the Campaign Sends report.  This can be access from the Magento 'Reports' menu item.

campaign_sends.png

By reviewing this report you are able to tell whether abandoned cart emails are being queued for sending, whether they are being sent to dotmailer 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 dotmailer 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.

Have more questions? Submit a request

Comments