Skip to main content

Best Practices for SAP Commerce Integration

This section provides architectural and optimization guidance specifically for integrating the Archibald framework with SAP Commerce (Hybris).

Sections​

Core Integration Principles​

  • Standardized Mapping: SAP Commerce (Hybris) responses are often deeply nested and highly specific to the OCC API. Always use Mappers to transform these responses into clean, standardized TypeScript interfaces. This decouples your frontend components from the backend's data structure.
  • OCC API Stewardship: Optimize payload sizes by requesting only the fields you need. Use the fields parameter in your providers (e.g., fields: 'BASIC' or fields: 'DEFAULT') to reduce pressure on the SAP Commerce servers and improve response times.
  • Context-Aware Requests: Ensure that baseSite, language, and currency are always correctly synchronized between the Archibald application state and the OCC API requests. The framework's CommerceProvider handles much of this, but project-specific mappers must respect these settings.

Performance Optimization​

  • Intelligent Caching: Use the DataClient caching strategies to store relatively static SAP Commerce data (like category trees or product descriptions). Set shorter TTLs for highly dynamic data like prices, stock levels, or cart totals.
  • BFF Orchestration: For complex pages, use the Archibald server modules to orchestrate multiple OCC calls into a single, optimized frontend request. This reduces the number of round-trips from the client to the server.
  • Media Optimization: SAP Commerce often returns absolute URLs for images. Ensure your project uses a centralized media helper or the Image component to handle these URLs, applying correct scaling or CDN prefixes as needed.

Error Handling and Resilience​

  • Standardized Error Mapping: The SAP Commerce integration layer should catch OCC-specific errors (like UnknownIdentifierError) and map them to standard Archibald error types or HTTP codes (e.g., 404).
  • Graceful Degradation: Design your components to handle missing SAP Commerce data gracefully. For example, if a product review fetch fails, the product detail page should still remain functional and usable.
  • Retry Strategies: Configure retry logic for non-mutating OCC requests in your ConfigService to handle transient network issues or temporary backend unavailability.

Customization and Extensibility​

  • File Shadowing over Modification: When you need to change a default behavior in @archibald/commerce, always use File Shadowing. This allows you to override specific mappers or adapters without breaking the upgrade path for the core framework.
  • Provider Inheritance: If a project requires unique logic for a specific commerce feature (e.g., a custom checkout step not supported by standard OCC), extend the base CommerceProvider and override only the necessary methods.
  • Mock Integration: During development and testing, always use the Mock providers. This allows your team to work independently of the SAP Commerce backend availability and ensures your test suite is stable and fast.