Integration Server

The Integration Server is a horizontally scalable Self-Managed Commerce webapp that consumes and processes messages from JMS queues and exposes a set of REST APIs for use by trusted back-end services. It is used in client projects for back-end integrations and uses the following technologies:

• Apache Camel

  A framework for asynchronous integration that provides concrete implementations of Enterprise Integration Patterns (EIP), connectivity to a wide variety of transports and APIs, and domain specific languages to wire EIPs and transports together.

• Spring Security

  Enforces HTTP Basic Authentication on all Integration Server endpoints, with the exception of the /status and /healthcheck endpoints, which are left unsecured so that health probes and load balancers can reach them. Authentication is backed by the Commerce Manager user store, and access is restricted to users assigned to the Web Service Access role (internally WSUSER) or a superuser role. For details, see API Security.

REST APIs

Integration Server exposes the following REST APIs. Each path is rooted at the Integration Server context (for example, http://<host>:8083/integration):

Base Path	API
/insights	Operational Insights API - Retrieve configuration and runtime metrics from all Self-Managed Commerce services in a running environment.
/importexport	Import/Export API - Export and import Self-Managed Commerce data as XML documents.
/syndication/v1/catalog	Catalog Syndication API - Retrieve catalog projections (brands, offers, attributes, options, field metadata, categories) for downstream systems.
/promoiq/v1/promotions	PromoIQ API - Evaluate product and cart promotion actions, retrieve promotion rules, and manage coupons, coupon groups, and coupon codes.
/shipping/v1/shipments	Shipment Completion API - Allow external fulfillment systems to complete shipments, trigger payment capture, and send shipment confirmation emails.

API Security

Integration Server should not be exposed on the public internet, as described in our Security Positioning Statement. These APIs should be restricted by network security for use by trusted, internal services.

In addition to network controls, Integration Server APIs require HTTP Basic Authentication. Every request must include an Authorization header of the form Basic <credentials>, where <credentials> is the Base64 encoding of <username>:<password>. For example, the credentials apiuser:s3cret-pass encode to YXBpdXNlcjpzM2NyZXQtcGFzcw==, producing this header:

Authorization: Basic YXBpdXNlcjpzM2NyZXQtcGFzcw==

Most HTTP clients handle the encoding automatically. With curl, pass the credentials via -u:

curl -u apiuser:s3cret-pass https://<integration-host>/integration/insights/request

Valid credentials are the username and password of any Commerce Manager user assigned to the built-in Web Service Access user role. The role is assigned to a user in Commerce Manager under Configuration → User Roles. For more information about the role itself, see Built-in User Roles.

important

In production environments, disable the default admin user and create a dedicated user for API access. The admin account ships with well-known default credentials, so leaving it enabled is a credential-guessing risk.

JMS Queues

In addition to its REST APIs, the Integration Server is the primary consumer of JMS messages emitted by the rest of the Self-Managed Commerce platform. It consumes from virtual-topic consumer queues against the following ActiveMQ virtual topics:

Virtual Topic	Purpose
VirtualTopic.ep.orders	Order lifecycle events used by the order confirmation email, shipment shipped email, shipment release failure email, return/exchange email, on-hold email, cancellation email, order accepted handler, order hold resolution handler, order release handler, gift-certificate-creation message producer, and notification handlers.
VirtualTopic.ep.customers	Customer events used by the registration, password-changed, password-forgotten, anonymous-customer-registered, and wish-list-shared email handlers and by customer-event notification handlers.
VirtualTopic.ep.cmusers	Commerce Manager user events used by the user-created, password-changed, and password-reset email handlers.
VirtualTopic.ep.giftcertificates	Gift certificate events used by the gift-certificate-created email handler.
VirtualTopic.ep.dataimport	Data import events used by the import-job-completed email handler.
VirtualTopic.ep.changesets	Data Sync Tool change set events used by the DST email listener.
VirtualTopic.ep.domain	Domain entity events used by the domain projection builder, domain cache invalidation handler, and product event consumer.
VirtualTopic.ep.domain.bulk	Domain bulk update events used by the projection bulk change handler.
VirtualTopic.ep.carts	Shopping cart and cart item events used by the cart and cart item event consumers.

The Integration Server also consumes from the following direct queues and topics:

Destination	Purpose
jms:ep.emails (queue)	The default email send queue. Email handlers publish formatted messages here, and the email sender consumes and dispatches them via SMTP.
jms:ep.emails.dlq (queue)	Dead letter queue for messages that the email sender could not deliver.
jms:topic:ep.insights.configuration	Operational Insights configuration request topic. The Integration Server replies on ep.insights.configuration.reply.
jms:topic:ep.insights.runtime	Operational Insights runtime metrics request topic. The Integration Server replies on ep.insights.runtime.reply.
jms:topic:ep.insights.ping	Operational Insights instance discovery topic. The Integration Server replies on ep.insights.ping.reply with its instance GUID.

The JMS destinations for the virtual-topic consumers are stored as system settings under COMMERCE/SYSTEM/MESSAGING/... and can be overridden per environment. For more information about tuning concurrent consumers, see Performance Considerations.

Configuring the Integration Server

• Velocity Email Formatting - Customize the Velocity templates used to format outgoing email messages.
• Performance Considerations - Tune concurrent JMS consumers for performance.