Adobe Commerce Connector

Feature Context

What is Adobe Commerce about?

Adobe Commerce empowers thousands of retailers and brands with the eCommerce platforms and flexible cloud solutions to rapidly innovate and grow. The Marigold Engage Adobe Commerce connector allows our Adobe Commerce-using customers to integrate their eCommerce data well in their marketing messaging to be able to send more nuanced and better targeted messages to their end users.

How it works

The Adobe Commerce connector supports polling-based two-way data sync. It connects to the client’s Adobe commerce setup and polls the entities configured for the sync using the standard Adobe Commerce v2 REST API. On detecting an update, it retrieves the updated data and imports it into one or more lists in Engage.
If the data sync is set up to be two-way then any updates in the Engage list(s) are also synced back to the Adobe Commerce entity.

We presently do not have the capability to sync deleted records.

The connector currently supports syncing with the following Adobe Commerce entities:

• categories
• categories-attributes
• Coupons
• credit-memos
• customer-groups
• customers
• invoices
• orders
• orders-items
• products
• products-attribute-sets-groups
• products-attribute-sets
• products-attributes
• products-attributes-types
• products-links-types
• products-options-types
• products-types
• sales-rules
• shipments
• stores-configs
• stores-groups
• stores
• store-website
• transactions

 

Activation and Configuration

Prerequisites

The connector uses Adobe Commerce REST API for data synchronization and the main prerequisite is to have the REST API endpoints accessible to the connector. The Adobe Commerce setup hence needs to open incoming/outgoing access for the port on which Adobe Commerce REST API is hosted. Both Adobe Commerce Open Source and Adobe Commerce Commerce distributions are bundled with REST API support by default.

The connector supports Adobe Commerce v2 and above for Adobe Commerce Open Source (aka Adobe Commerce Community) and Adobe Commerce Commerce (aka Adobe Commerce Enterprise).

 

You will also need the following information ready:

Adobe Commerce URL – This is the base URL of the Adobe Commerce server and is used by the connector to construct the REST API endpoint URL. This base URL can be derived from the Adobe Commerce Admin UI URL by removing the “/admin” suffix from it. For instance:

Adobe Commerce Admin Username and Password – This is the username and password of a Adobe Commerce account with admin privileges. An admin account is required to have access to the customer’s entity in Adobe Commerce . This is the same username/password that is used for that account to login into the Adobe Commerce Admin UI.

 

Set up the Connector

Campaign

1. Go to Configuration / Connectors / Connector instances.

2. Click New Connector instance and fill out the following properties:

On the General tab:

• Server — This is the name of the server on which the Campaign connector is installed.  Select one from the drop-down list. Only servers on which the connector is installed are listed.
• Connector — Select Adobe Commerce as connector type.
• Name and Description — Provide a name and description for this connector.

On the Parameters tab:

• URL — The URL of your Adobe Commerce instance.
• User — The Adobe Commerce user name. This user should have admin user rights.
• Password — The Adobe Commerce password.

3. At this point, only bi-directional data synchronisation is possible between Adobe Commerce and Campaign. Flag the data synchronization option to activate this. All other options are de-activated as they’re not supported.

Note: It’s not possible to synchronize deleted records at this point.

4. Click OK.

Note: When the connector instance is created and the option ‘Data synchronization’ is checked the Adobe Commerce structure is downloaded automatically into the Campaign database.

 

Engage

1. Go to the Admin Configuration / Data Integration / Connectors and add a New connector:

A properties panel is displayed on the right:

2. Set the following properties:

• Name and Description — Provide a name and description for this connector.
• Connector — Select Adobe Commerce Connector as type of connector from the drop-down list.
• Server — This is the name of the server on which Engage is installed. Select one from the drop-down list. Only servers on which the connector is installed are listed.
• Can be used for — You can only choose Data sync for the Adobe Commerce connector at this point. Message sync is not yet available.
• URL — The URL of your Adobe Commerce instance.
• Consumer Key — The Consumer Key of the Adobe Commerce marketplace. This can be obtained from the Adobe commerce profile page.
• Consumer Secret — The Consumer Secret of the Adobe Commerce instance. This can be obtained from the Adobe commerce profile page.
• Access Token — The access token provided to the customer. This can be obtained from the Developer account, within the apps security settings.
• Access Secret — The access secret provided to the customer. This can be obtained from the Developer account, within the apps security settings.

3. Save the connector

 

Configure the Data Sync

Campaign

1. After selecting the Connector instance, activate the Configuration tab at the bottom.

2. Right click within the overview and select New synchronization. A dialog is displayed:

3. After ticking the option 'Synchronization', select the Campaign list (audience, Data) from the pick list associated to the 'Campaign List/Audience' field.

4. Next, select the Adobe Commercetable to be synchronized with the selected Campaign list.

5. Define the time interval between two consecutive synchronizations, with a minimum of 1 minute.

6. Set the maximum batch size for Adobe Commerce and Campaign. Two distinct fields are provided as Campaign allows a much larger batch size than Adobe Commerce .

7. The Scheduling section allows scheduling the execution of data synchronization. Set a time frame within which synchronization must be executed.

8. The lower section Alerts allows configuring if alert emails must be sent to a given email address. This is possible when

• Synchronization succeeded
• Synchronization failed
• Synchronization timed out. In this case a time out in seconds can be defined.

Note: The email message is a standard email in English.

9. Activate the Synchronization Details tab to complete the rest of the configuration. The following is available:

The scope in Campaign can either be the Master list or an extended profile of this list. Depending on the selected scope, the list of Campaignfields on the left of the dialog is adapted.

On the right, all fields downloaded for the selected Adobe Commerce table are listed.

10. Define the fields to be synchronized by selecting a field from the 'Campaign fields' list on the left and a field from the ‘Data source fields’ list on the right.

11. Select the Direction in which synchronization must be executed for this matching by clicking the button in the middle. There are 3 possibilities:

• in both directions
• from data source to Campaign
• from Campaign to Data source

12. Next, Press the Link button. The matching is added to the pane at the bottom.

Note: When multiple fields require matching, select first the Campaign fields on the left by holding down the CTRL button. Next select all Data source fields on the right. Press Link. The Campaign-Data source fields are in this case matched from top to bottom, linking the first one selected in Campaign to the first one selected in Data source and so on.

13. Perform the above steps for each Campaign-Data source matching that is required.

Note: It is possible to define a different synchronization direction for each matching.

14. To remove links right click on a link and select Unlink.

It is equally possible to change the synchronization direction for a defined link from within the lower pane.

When an issue occurs in the synchronization of these fields (example: types do not correspond, field lengths do not match…) the items are marked with a special icon.

Hovering over such an item shows more details on the field.

When clicking ‘OK’ a list with warnings is shown (in case warnings are available), but you can always continue:

Technical note: When saving the synchronization configuration all mandatory fields and indexes are automatically added.  A dialog pops up informing the user of this. 

Once the data synchronisation is set up and the sync is executed, Adobe Commerce information is available in Campaign to personalize messages and launch a journey for the audience containing the Adobe Commerce users.

 

Engage

1. Go to Data Exchange/Data Syncs.

2. Create a New data sync. The wizard is launched and the following needs to be defined:

3. On the Setup step, there are two tabs available : Setup and Advanced.
In this step, you can define all the settings for the Data Sync.

Setup step - tab ‘Setup’

Connector — Choose any appropriate connector configured for the current organization in the Admin Configuration. When a connector is selected, the header for the drop-down below changes from 'Connector table' to ‘Connector name’ table'.

Connector table — Select any table from the drop-down by clicking and scrolling through the list or by entering part of a table name (which filters the list) before making your selection. This list contains the tables from your Data source database, sorted alphabetically.

Engage list — Select any list that exists in the current organization.

By default, the Schedule switch is disabled, which means the Data Sync is not scheduled. In that case, a notification is shown to explain that you can manually start the data sync execution and run it once.

Note: The execution can be manually started through the ‘Execute once now’ button on the Connector Data Syncs Start page.

When the switch is enabled, the schedule settings become available:

• Start date and End date — You can set a start date and/or end date for the sync. For example, your task can start now but needs to run indefinitely.
• Periodicity — Indicate when the sync should run :
• Daily — Select the times of day at which the sync should run. You can select more than one.
• Weekly — Select the day of the week on which the sync should run. The sync can run more than once a week. You can also set the start time.
• Monthly — Select the days of the month on which the sync should run. You can also select the time of day at which the sync should start.
• Periodically — Set the recurrence of the sync, expressed in minutes. For example, the sync runs every 10 minutes.
• Once — Set once if the sync needs to be executed just once. You can also change the start time.

A message can be sent when the Data Sync has been completed successfully, or if it fails or a timeout occurs. To activate a notification, simply enable the corresponding switch and enter one or more email addresses (multiple email addresses are separated by a semicolon). You can also select a notification group. These notification groups are created in the Admin Configuration.

Note: Notifications are optional. When enabling one or more notifications, you need to provide at least one email address or group for each enabled notification.

As soon as you have selected all the properties, a Next button becomes available to navigate to the Sync step.

 

Setup step - tab ‘Advanced’

On the Advanced tab, you can define the Data source batch size and the Engage batch size.

Data source batch size — Used to determine how many records are retrieved per batch from the Data source (in case of Data source to Engage sync) or updated/inserted in the Data source (in case of Engage to Data source sync).

Engage batch size — Used to determine how many records are retrieved per batch from Engage (in case of Engage to Data source sync) or updated/inserted in Engage (in case of Data source to Engage sync).

Click Next to go to the next step, which is the Sync step.

4. On the Sync step, there are three tabs available : Sync, Filters and History.

 

Sync step - tab ‘Sync’

The sync tab lets you define the Data source fields that need to be synchronized with the Engage fields. A mapping between the fields is defined as well as the direction of the sync. Engage fields can be selected from the master list as well as linked lists.

Technical note: Make sure that the type and field length of the mapped fields correspond (such as syncing a Data source date field only with a Engage date field).

Note: When setting up a sync between the Data source and Engage, Data source tables and lists can be used just once in a sync.

Data source field — Data source fields can be selected from the Data source table (selected in the setup step) by clicking and scrolling through the list or by entering part of a field name (which filters the list) before making your selection.

Scope — The list (selected in the setup step) can be selected as 'Master' list, and all of its 1:1 relations. By default, the scope 'Master' is selected.

Field — Fields from the scope can be selected (a combo-box appears only when a scope is selected).

 

You can also determine the direction of the data sync using the following buttons :

• ← : Engage list to Data source table

• ↔ : Both ways

• → : Data source table to Engage list

Note: Computed fields (non-persisted and persisted) can be selected as field when the chosen direction is 'Engage list to Data source table'. For 'bi-directional' and 'Data source table to Engage list', computed fields can’t be selected.

It's possible to add a new field to the target list (selected as scope), using the Create new field option.

When this option is selected, a new text field appears underneath the drop-down in which a field name can be entered. This value is required.

• The new field name has a default value equal to the Data source field name (in uppercase) unless that field name already exists. In this case, the field is empty (a placeholder is shown instead).

• The new field name can’t be the name of an existing field, already configured new field or a non-permitted keyword (front-end validation).

• Spaces in the field name are converted to underscores (for consistency).

• The type of the new field is automatically derived from the type of the selected Data source field.

  • If the selected Data source field has data type TEXT or LINK with length=0, then the new field will have data type LONGTEXT

• As soon as the data sync is created/updated, the new fields are created on the list selected as scope.

Syncs can be sorted by clicking on one of the column headers (Data source Field, Direction, Scope, Field). Clicking on a header sorts the results in ascending order of the column values. Active sorting is indicated by an up (ascending) or down (descending) arrow next to the column header. Clicking on a header of an already active sorting column, changes the sorting direction for that column.

A complete row can be deleted by clicking on the bin icon.
The last remaining row can’t be deleted.

 

Sync step - tab ‘Filters’

On the Filters tab, the user can define :

• a Data source filter — This is a text-area in which you can type a filter. Only records matching the filter will be synchronized. The filter syntax depends on the connector that you are using. For more details on the syntax, please consult the corresponding manuals/support site.

• a Engage filter — Only records matching this filter will be synchronized during the data sync run. This filter can be built using the Constraint Builder, containing the same options as for building dynamic segments.

Note: Defining filters is optional. No filters are set by default.

When a filter is set for either the Data source fields or the fields, this is indicated by a filter icon next to the corresponding header on the 'Sync' tab.

When you click on a filter icon, the Filters tab is opened.

An organization filter is automatically applied to the Data Sync when it's defined on the Audience List.

Sync step - tab ‘History’

The history of a data sync provides details on previous executions.

This includes :

• the source and destination table of the data sync
• the details per run :
  • the run date
  • the direction of the data synchronization
  • the total number of records included
  • the number of records that successfully synchronized, and the ones that failed
  • the starting time of the sync
  • the duration of the sync

When no synchronization has been executed yet or no data is available yet, the user is informed :

When execution history is available, it looks like this :



Each run can be expanded by clicking on the down-arrow on the left, to show more details about failed records.
When erroneous data is available, it will be shown here.

Note: When a data sync generates an error, this error will also be visible from the notifications in the top menu bar of Marigold Engage. Clicking the notification takes the user to the ‘History’ tab of the Data Sync.

Failed records for which an error message is returned, can be exported to a CSV file. An ‘Export’ button is available to launch the export. This ‘Export’ button will NOT be available when the cause of the failed record is UNKNOWN or when there are no failed records.

When a failure happens before the individual records are captured, the system doesn't know how many records would have been included in the sync.
In that case, 'Unknown' is shown instead of the number of failed records.

Note : In case of a long list of failed records, only the first 10 failed records are shown.

When you've finished configuring the sync, press the 'Save' button (or 'Update' button if you are modifying an existing Data Sync).

Note: The 'Save' (or 'Update') button is only available when at least one field map is defined. Otherwise the button is disabled.

 

Validation errors/warnings

One or more validation errors/warnings appear if your configuration is not correct or if (an)other issue(s) occur(s).

List of possible errors :
- Data source connector instance is in use
- Data source sync configuration is already disabled
- Data source sync configuration is already enabled
- Data source sync not scheduled
- Data source table field is used multiple times
- Data source table already used in data sync
- Schedule end date should be less than start date
- Invalid Data source batch size for Data source sync
- Invalid Data source connector instance
- Invalid Data source table
- Invalid Data source table field
- Invalid data sync direction
- Invalid list
- Invalid notification email address
- Invalid notification group
- Invalid notification timeout configuration
- Invalid notification type
- Invalid relation
- Invalid schedule data configuration
- Start date should be greater than current date
- Invalid schedule type
- Invalid Engage batch size for Data source sync
- Invalid Engage list field
- Invalid start time format
- Engage list already used in data sync
- Engage list field is used in Data source data sync
-Engage list is used in Data source data sync
- Notification configuration is missing
- Notification groups are not configured
- Schedule data configuration is missing
- Schedule end date is required
- Schedule start date is required
- Schedule type is required
- Engage list field is used multiple times
- Start time is required
- Failed to save the Data source sync data configuration
- Failed to delete the Data source data sync between Data source table [Data source TableName] and Engage list [listName]
- Failed to disable Data source sync between Engage list [listName] and Data source table [Data source TableName]
- Failed to enable Data source sync between Engage list [listName] and Data source table [Data source TableName]
- Failed to mark Data source sync between Engage list [listName] and Data source table [Data source TableName] for execution

List of possible warnings :
- The data type of the Data source table field and Engage list field does not match
- Field length of the Data source field and Engage list field does not match

Note: There are placeholders [listName] and [Data source TableName] in some messages, which are substituted at run time with information based on the context.

Errors and warnings are shown in a validation pane at the bottom of the screen after clicking the 'Save' button. In that case, the Save button label changes to 'Update'.

When navigating to the ‘Sync’ tab and clicking on an error/warning in the validation pane, the row linked to the error/warning is highlighted (if applicable).
This allows issues to be easily resolved.
When done, click on the ‘Update’ button to save your changes.

Example:
When selecting a warning in the validation pane, the row that causes the problem is highlighted on the Sync tab. The label of the button shows 'Update'.

Note: Some errors will continue to be displayed as notification messages at the top-right instead of using the validation pane, such as:
- 'The selected Data source table does not have any fields' (Setup step).
- 'The Data source table is already in use' (Sync step).

When everything has been set up correctly, the Data sync will be created and visible on the Start page.