# Dotmailer / Dotdigital

`Dotdigitalgroup_Email` is the third-party Magento connector used to send customer, subscriber, guest, order and catalogue data to Dotdigital.

Dotmailer is the older product name. Cru classes and database fields that contain `Dotmailer`, `dotm_*` or `DM` refer to the same integration.

## Contact synchronization

1. Magento customer and newsletter events update the connector's local contact state.
2. The contact-sync cron selects customers, newsletter subscribers and guest-order contacts that need syncing.
3. Contacts are written to CSV files using the configured Dotdigital data-field mappings.
4. CSV files are registered in the connector importer queue.
5. The importer cron sends queued work to the Dotdigital API and updates the local import state.

Newsletter changes can also queue unsubscribe and resubscribe operations. A newly subscribed contact may be added to the configured subscriber automation.

## Cru-specific exports

Cru extends the standard customer export with:

- Sales-representative names
- One Boolean Dotdigital data field for each selected wine region

A separate export processes eligible `cru_customer/contacts` records where `offers = 1`. New and updated contacts are written to CSV and registered in the same importer queue. The fields `dotm_created_at` and `dotm_updated_at` record when these contacts were queued.

## Magento configuration

Use **Email Connector > Configuration** in Magento admin:

- **API Credentials** enables and authenticates the connector.
- **Data Mapping** maps Magento customer and order fields to Dotdigital data fields.
- **Sync Settings** selects address books for customers, subscribers and guests, controls whether non-subscribers can be imported, and enables each sync type.

Configuration is website-scoped. Always check the selected website before making changes. Customer synchronization skips a website if no customer address book is mapped.

## Scheduled jobs

| Job | Schedule | Purpose |
| --- | --- | --- |
| `ddg_automation_customer_subscriber_guest_sync` | Configurable | Exports customers, subscribers and guest contacts |
| `ddg_automation_importer` | Configurable | Processes queued API imports |
| `cru_customer_contact_dotmailer_sync` | Daily at 01:45 | Exports eligible Cru contact records |
| `cru_dotmailer_refresh_segments` | Daily at 02:49 | Refreshes local `email_dm_segments` data |
| `ddg_automation_campaign` | Every 5 minutes | Sends queued connector campaigns |
| `ddg_automation_status` | Every 15 minutes | Updates automation enrolment and status |
| `ddg_automation_order_and_quote_sync` | Configurable | Sends order and quote transactional data |

Cron expressions use the effective server/Magento cron timezone.

## Troubleshooting

1. Confirm the source Magento customer and newsletter values are correct.
2. Confirm the Dotdigital API is enabled for the affected website.
3. Verify customer, subscriber and guest address-book mappings.
4. Verify that all required Dotdigital data fields are mapped.
5. Check `cron_schedule` for recent contact-sync and importer executions and their statuses.
6. Check the connector logs and importer queue for pending or failed entries.
7. Use the connector's **Sync Contact** admin action to retry one customer.
8. Do not manually change `dotm_created_at` or `dotm_updated_at` unless deliberately reconciling or forcing an export.

## Key implementation files

Paths are relative to `web-root/`.

- `app/code/local/Cru/Customer/Model/Email/Apiconnector/Contact.php`
- `app/code/local/Cru/Customer/etc/config.xml`
- `app/code/local/Cru/Newsletter/Model/Observer.php`
- `app/code/community/Dotdigitalgroup/Email/Model/Cron.php`
- `app/code/community/Dotdigitalgroup/Email/Model/Newsletter/Observer.php`
- `app/code/community/Dotdigitalgroup/Email/etc/config.xml`
- `app/code/community/Dotdigitalgroup/Email/etc/system.xml`
- `app/code/community/Dotdigitalgroup/Email/etc/adminhtml.xml`