Basic Knowledge
Essential knowledge articles on Connect SDK
External Webhook Integration Architecture - commercetools Connector
Essential knowledgeExplains how the commercetools Connector ingests inbound webhooks and dispatches outbound payloads across the integration ecosystem. Partners will learn to configure and apply this shared framework utility, which manages message routing, handler resolution, and internal queue mechanics. For the business, this asynchronous architecture ensures real-time, secure data transmission and protects platform stability by preventing message loss during high-volume storefront traffic spikes.Note: This architectural component serves as a global framework utility rather than a single functional pipeline.- Core Function & Outcome: You will learn how the framework utility orchestrates bidirectional ingress and egress loops, serving as the master execution blueprint for all entity-specific data synchronization pipelines.
- Asynchronous Queue Infrastructure: The architecture processes incoming webhook payloads through an external
`ct-queue` and an internal Event Queue sequentially, decoupling network reception tasks from backend data processing to maintain platform throughput. - Declarative Route Filtering: Implementing partners can manage message names, configure explicit inclusion filters, and reassign target event pathways directly inside the
`application-connector.yml` configuration file. - Extensible Handler Architecture: The core message routing and processing layers are completely decoupled, allowing developers to cleanly register custom storefront event handlers by extending the base
`MessageHandler` class.
Category Sync - commercetools Connector
Essential knowledgeExplains how the commercetools Connector synchronizes category trees from a storefront outbound to Fluent Order Management. Partners will learn to manage real-time subscriptions and batch execution paths to mirror catalog hierarchies. For the business, this automation aligns navigation structures across platforms, ensures consistent item grouping for backend orchestration, and eliminates manual data entry.Note: This article forms part of the outbound pipeline category, where data flows out of the commercetools environment to an external destination.- Core Function & Outcome: You will learn how the connector coordinates the export of category trees from commercetools to Fluent Order Management, establishing matching catalog nodes across both environments.
- Dual-Trigger Execution: Supports manual, scheduler-driven complete catalog extraction alongside automatic background delta tracking.
- Subscription Management: Relies on core commercetools subscriptions to stream real-time creation and modification alerts into the integration layers.
- Extensible Routing Architecture: Allows business rules, message paths, and handler logic maps to be safely overridden via central YAML configurations. Technical partners can easily reassign event paths, manage inclusion filters, and override standard handler classes inside the centralized
`application-connector.yml` configuration file.
Consignment Updates - commercetools Connector
Essential knowledgeExplains how the commercetools Connector tracks shipping events from Fluent Order Management to update commercetools. Partners will learn to manage the inbound webhook pipeline that automatically generates native delivery records, parcel data, and carrier tracking links. For the business, this sync eliminates manual shipment logging and gives customers instant visibility into order transit via the storefront interface.Note: This article forms part of the inbound pipeline category, where data flows into the commercetools environment from an external source.- Core Function & Outcome: You will learn how the commercetools Connector captures consignment updates from Fluent Order Management to automatically generate delivery records, package manifests, and carrier tracking data inside commercetools.
- Asynchronous Queue Infrastructure: Inbound webhook payloads undergo cryptographic signature and parameter verification in the first stage before entering an internal queue, where a named handler processes the data updates asynchronously in the second stage.
- Structural Entity Mapping: The system maps Fluent consignment entities directly onto fulfillment models, which translate into native, line-item level delivery records to cleanly support orders split across multiple packages or locations.
- Data Enrichment Mechanism: Because incoming webhooks carry minimal payloads to reduce network overhead, the connector automatically dispatches a
`GetConsignmentById` GraphQL query back to Fluent to pull complete carrier details and package dimensions before updating commercetools.
Customer Sync - commercetools Connector
Essential knowledgeExplains how the commercetools Connector synchronizes customer profile data from a storefront to Fluent Order Management. Partners will learn to configure, validate, and extend this outbound data pipeline from the storefront trigger to the final GraphQL delivery. For the business, this real-time pipeline removes profile fragmentation, giving customer service agents instant access to accurate records.Note: This article forms part of the outbound pipeline category, where data flows out of the commercetools environment to an external destination.- Core Function & Outcome: You will learn how the commercetools Connector detects and processes customer creations and modifications automatically the moment they occur on the storefront, removing the need for manual batch data transfers.
- Asynchronous Queue Infrastructure: The architecture routes payloads through an external
`ct-queue` and an internal Event Queue sequentially, decoupling storefront event triggers from backend database processing to protect platform stability. - Declarative Route Filtering: Implementing partners can manage message types, configure explicit inclusion filters, and reassign target data pathways directly within the
`application-connector.yml` configuration file without modifying core system code. - Extensible Handler Architecture: The core message routing and transformation layers are completely decoupled, enabling developers to cleanly introduce custom profile fields and data-mapping logic by extending the base
`MessageHandler` class.
Order Sync - commercetools Connector
Essential knowledgeExplains how the commercetools Connector manages the two-way pipeline that exports new orders from a storefront to Fluent Order Management and handles asynchronous status updates. Partners will learn to configure event-driven triggers, enable customer profile creations, and apply route filters. For the business, this real-time sync establishes a single source of truth for transactions across Home Delivery and store pickup channels.Note: This article forms part of the outbound pipeline category, where data flows out of the commercetools environment to an external destination.- Core Function & Outcome: You will learn how the commercetools Connector handles order exports from commercetools to Fluent Order Management, automates integrated customer profile creation, and establishes the webhook ecosystem for order status processing.
- Out-of-the-Box Capabilities: Out-of-the-box (OOTB) functionality natively supports Home Delivery (HD) and Click and Collect (CC) order structures, complete with automated type-specific order number generation patterns.
- System & Sync Limitations: Designed strictly for new transactions and does not synchronize historical orders created prior to extension installation. Additionally, the order update and modification handlers must be customized to fit your specific implementation needs.
- Extensible Pipeline Architecture: The message routing and handler framework is completely decoupled. Developers can easily update message names, override standard classes, or extend the baseline order creation logic to attach custom operational attributes.
Connect SDK Libraries
Essential knowledgeThe Connect SDK Libraries comprise a modular software development framework designed for building integrations with Fluent Order Management. The architecture centers around a mandatory core module that handles foundational communication, configuration storage, and routing capabilities. Implementation teams can extend this baseline engine using specialized, pluggable add-on libraries to introduce web frameworks, security filters, specific cloud or infrastructure adapters, and isolated simulation testing suites.- What You Will Learn: You will understand the structural purpose of each component within the Connect SDK framework and learn how to select the appropriate core, web, cloud infrastructure, or testing dependencies for your implementation project.
- Mandatory Core Requirement: The
`connect-sdk-core` library is a mandatory dependency for all SDK-based implementations. It houses the baseline engine components, including the REST and GraphQL API client, authentication management for sensitive credentials, message routing, and the configuration manager. - Asynchronous Processing Boundary: All transactional endpoints and internal processing steps handled by the SDK execute asynchronously in the background. The explicit exception to this design rule is product availability processing, which runs synchronously.
- Pluggable Architecture Strategy: Advanced technical capabilities are intentionally isolated into decoupled modules. Developers append specialized add-ons like
`connect-sdk-core-web-security` for Spring Security filters, `connect-sdk-core-aws` for Amazon Web Services (AWS) deployment services like Amazon Simple Queue Service (SQS) and AWS Secrets Manager, or `connect-sdk-core-kafka` for Apache Kafka support. - Isolated Testing Frameworks: The SDK segregates quality assurance utilities into specific test scopes. Teams deploy
`connect-sdk-test-core` to mock external API calls with Wiremock, or utilize the AWS and Kafka test extensions to run integration tests inside software containers alongside LocalStack or virtual Kafka brokers.
Fluent Connect SDK Architecture
Essential knowledgeThis article will cover the high-level design and features of the SDK.- The Connect SDK architecture consists of core, cloud, and additional libraries, enabling the building and extension of connectors.
- Key features include configurations, a secret manager for sensitive information, a scheduler for periodic operations, listeners/subscribers, web services/webhooks, an event log, product availability options, and SDK handlers for custom business logic.
- The message lifecycle follows a specific flow, and there are two integration approaches: Pull and Push. The SDK offers patterns for scheduled operations and receiving external requests, and it includes dead letter queues, metrics, and logs for monitoring and observability.
- Build and deployment use SpringBoot, generating a deployable JAR with an embedded Tomcat.
