Dotdigital Integration with Adobe App Builder

Welcome to the Dotdigital for Adobe Commerce accelerator app.

Our app provides a simple starter integration with Adobe Commerce via Adobe App Builder. It will perform single synchronizations of customers, subscribers, products and orders into Dotdigital.

Prerequisites

Merchants should be familiar with Adobe’s Commerce Integration Starter Kit and their public documentation for this project. You will need to:

• Create an App Builder project in the Adobe developer console
• Configure a new integration in Commerce

You may also need to:

• Install or update additional modules in Commerce

Acquire the app

• Acquire the app from Adobe Exchange
• Enter initial configuration for Adobe Commerce and Dotdigital
• Download the code

Configuration

• Download and unzip the project
• Copy the env file cp env.dist .env
• Fill in all required OAuth, module and workspace configs as per the comments
• Fill in the following Adobe Commerce configs (unless already configured in Exchange):

COMMERCE_BASE_URL=

Authentication

You can configure a Commerce Integration with:

COMMERCE_CONSUMER_KEY=
COMMERCE_CONSUMER_SECRET=
COMMERCE_ACCESS_TOKEN=
COMMERCE_ACCESS_TOKEN_SECRET=

Or an Adobe Identity Management Integration (IMS) with:

OAUTH_CLIENT_SECRETS=[""]
OAUTH_TECHNICAL_ACCOUNT_ID=
OAUTH_TECHNICAL_ACCOUNT_EMAIL=
OAUTH_SCOPES=[""]
OAUTH_IMS_ORG_ID=

For IMS, don't forget to create an admin user in Adobe Commerce with the email of the technical account user from your workspace's OAuth Server-to-Server configuration.

• Read more

Event Provider configuration

Update your provider label in events.config.yaml to match your target project, for example:

Commerce events provider - 3527417-dotdigital-stage

Dotdigital account configuration

• Fill in the following Dotdigital configs (unless already configured in Exchange):

DOTDIGITAL_API_URL=
DOTDIGITAL_API_USER=
DOTDIGITAL_API_PASSWORD=
DOTDIGITAL_LIST_CUSTOMER=
DOTDIGITAL_LIST_SUBSCRIBER=
DOTDIGITAL_CATALOG_COLLECTION_NAME=
DOTDIGITAL_CATALOG_BASE_LINK_URL=
DOTDIGITAL_CATALOG_BASE_MEDIA_URL=
DOTDIGITAL_DATAFIELD_MAPPING=

You must ensure that any data fields you include in your DOTDIGITAL_DATAFIELD_MAPPING array exist in your Dotdigital account.

Deployment

Following the next steps, you will deploy and onboard the starter kit for the first time. The onboarding process sets up event providers and registrations based on your selection.

Configure the project

Install the npm dependencies using the command:

npm install

This step will connect your starter kit project to the App builder project you created earlier. Ensure to select the proper Organization > Project > Workspace with the following commands:

aio login
aio console org select
aio console project select
aio console workspace select

Sync your local application with the App Builder project using the following command:

aio app use
# Choose the option 'm' (merge) 

Select which components to use

• Edit the file app.config.yaml if you only want to deploy specific entities.
• Edit the ./onboarding/config/registrations.json file if you don't need an event registration for a particular entity.

Onboarding and event subscription

Run these configuration scripts for onboarding and event subscription before deploying:

npm run configure-events
npm run configure-commerce-events

Deploy

Run the following command to deploy the project; this will deploy the runtime actions needed for the onboarding step:

aio app deploy

Read more:

• Starter kit onboarding
• [Starter kit IMS configuration] (https://developer.adobe.com/commerce/extensibility/starter-kit/checkout/connect/)
• Subscribing to events in Adobe Commerce

Verify

You can confirm the success of the deployment in the Adobe Developer Console by navigating to the Runtime section on your workspace:

Check your App developer console to confirm the creation of the registrations:

In the Adobe Commerce Admin, check the values populated in Stores > Settings > Configuration > Adobe Services > Adobe I/O Events > General configuration:

Events

Here are the events with the minimal required fields you need to subscribe to, it includes the REST API endpoints that could trigger these events:

Entity	Event	Required fields	REST API Ref
Product	observer.catalog_product_save_commit_after	id, entity_id, name, sku, stock_data.qty, price, status, type_id, url_key, image, created_at, parent_id, store_ids	product create / update
Customer	observer.customer_save_commit_after	id, email	customer create / update
Order	observer.sales_order_save_commit_after	entity_id, grand_total, order_currency_code, created_at, subtotal, items, customer_email, increment_id, quote_id, status, addresses, store_name, discount_amount, payment, shipping_description, shipping_amount, coupon_code	order create / invoice / ship / refund (and others)
Subscriber	observer.newsletter_subscriber_save_after	subscriber_id, subscriber_email, subscriber_status