How nimitshukla123/sfcc-marketting-cloud-connector works
Project Type and Purpose
• This is a Salesforce B2C Commerce “cartridge‐based” integration connector that sits inside a B2C Commerce (Demandware) instance. It implements an above-the-API integration between B2C Commerce (both SiteGenesis and SFRA storefronts) and Salesforce Marketing Cloud (MC) via REST and SOAP APIs. It includes:
• A handler framework (int_handlerframework) that abstracts MC API calls and event tracking hooks.
• A marketing-cloud cartridge (int_marketing_cloud) that provides feeds, triggered-send logic, data-export jobs, models and webservice adapters.
• SiteGenesis/SFRA controller overlays (int_sitegenesis_marketing_cloud_controllers) for transactional emails and form handlers.
• A core cartridge (int_sitegenesis_marketing_cloud_core) that supplies ISML templates for UI components and hooks.
• A plugin cartridge (plugin_marketing_cloud) for SFRA-style controller overrides and helper methods.
• Postman collections for API testing and environment setups.
• Scheduled jobs (in sites/site_template) to push data syncs (catalog, orders, promotions, customers) to MC.
High-Level Architecture – Main Components
A. Storefront Layer (SiteGenesis or SFRA)
• Controllers (e.g., Cart, Account, Order) loaded from the storefront code and overlaid by int_* cartridges.
• ISML templates for pages/forms (opt-in, subscription, preferences).
• collect.js snippet for client-side analytics tracking.
B. Handler Framework Cartridge (int_handlerframework)
• Hook proxies and communication scripts that intercept platform hooks (onRequest, email, tracking) and route requests to handlers.
• Object mappers and velocity templates for data transformation.
• A thin façade over dw.svc.* to call MC REST/SOAP services.
C. Marketing-Cloud Cartridge (int_marketing_cloud)
• REST/SOAP service definitions (helper.js, rest.js, soap.js) for Marketing Cloud endpoints.
• Data models (authToken, dataExport, message, subscriber, trigger) to structure MC payloads and responses.
• Feed jobs (catalog.js, content.js, orders.js, customers.js, promotions.js, upload.js) under scripts/feeds and scripts/jobs to push CSV/XML via services or FTP.
• Triggered-send transactional email handlers.
• Custom Objects and site preferences for mapping configuration (steptypes.json, properties files).
D. Plug-in Cartridge (plugin_marketing_cloud)
• SFRA controller overrides and helper JS modules for account, email, contact-us.
E. Data Persistence & Configuration
• Custom Objects defined in sites/site_template/meta (e.g., MarketingCloudAuthToken, MarketingCloudTriggers, MarketingCloudDataExportStatus).
• Services.xml and jobs.xml to register scheduled tasks.
• cartridge int_* .properties and steptypes.json for cartridge order and metadata.
F. External Systems
• Marketing Cloud (REST & SOAP endpoints)
• FTP/SFTP (optional) for bulk data feeds.
Relationships & Interactions
1. Storefront controller receives HTTP request → If hook enabled, handler framework’s onRequest hook triggers data-layer script → event sent to MC via REST collect.js or server-side service call.
2. Cart/Order actions invoke hookProxy scripts → HandlerInclude routes to communication scripts → appropriate MC API method invoked (REST/SOAP).
3. Scheduled jobs (cron) run data-export cartridges → generate payload via Velocity templates → send to MC via bulk API or FTP.
4. Transactional email hooks intercept platform emails → map trigger keys and attributes → send triggered-send calls to MC.
5. Custom Objects store mapping configs, trigger definitions, token cache; ServiceRegistry handles credentials fallback per site.
Architectural Patterns & Design Principles
• Modular Cartridge Architecture: each integration concern is isolated in its own cartridge, loaded in dependency order.
• Adapter/Facade Pattern: handlerframework scripts abstract the MC API calls behind uniform interfaces.
• Hook-Based Extension: leveraging SFCC server and email hooks to inject tracking and transactional email logic without modifying core storefront.
• Template-Driven Data Mapping: Velocity templates drive the transformation of Commerce data into MC API payloads.
• Configuration-First: JSON and properties files define mapping, steptypes, and site preferences to avoid hardcoding.