Skip to main content

Understanding SAP Commerce OCC

Omni Commerce Connect (OCC) is the RESTful Web Service API that powers the headless integration between the Archibald framework and SAP Commerce Cloud (Hybris).

The Headless Paradigm​

In a traditional SAP Commerce setup (using Accelerator), the backend is responsible for both data and UI rendering. In the Archibald Headless Paradigm, these are decoupled:

  1. Archibald (Frontend): Manages the user experience, routing, and UI rendering.
  2. OCC (Data Engine): Serves raw JSON data via authenticated endpoints.

This separation allows for a much faster, modern frontend experience while leveraging the robust commerce logic of SAP.

Resource Structure​

OCC v2 endpoints follow a consistent hierarchical structure. Archibald's commerce providers are pre-configured to handle this structure automatically.

Base Pattern: {host}:{port}/{base}/{version}/{baseSite}/{url} (with the default configuration this resolves to /rest/v2/{baseSite}/{url})

  • baseSite: The unique identifier for your storefront (e.g., apparel-uk). This context is managed globally in the ConfigService.
  • Resource: The commerce entity being accessed (e.g., products, users, carts).

Key Concepts​

1. Field Selection (Data Depth)​

OCC uses a powerful fields parameter to prevent "over-fetching." Archibald allows you to control this at the hook or module level.

  • BASIC: Only returns essential identifiers (e.g., code, name).
  • DEFAULT: Returns common fields needed for standard components (e.g., name, summary, basic image).
  • FULL: Returns the complete data tree, including technical specs and nested attributes.

2. Isomorphic Context​

When Archibald makes an OCC request, it automatically attaches the current user's context:

  • Language: ?lang=en
  • Currency: ?curr=GBP
  • Authorization: Bearer {token} (handled by the @archibald/auth integration).

BFF and Security (The Token Exchange)​

A critical part of the Archibald integration is the Secure Token Exchange. To protect the user's security, raw SAP Commerce OAuth tokens (JWTs) are never exposed to the browser.

How it works:​

  1. Cookie Storage: When a user logs in, the Archibald BFF receives the token from SAP Commerce and stores it in a secure, HTTP-only cookie.
  2. Request Interception: For every subsequent request from the frontend to the BFF, the cookie is sent automatically by the browser.
  3. Token Restoration: The Archibald AuthModule middleware extracts the token from the cookie and attaches it as a Bearer token to the outgoing OCC request.

This pattern prevents Cross-Site Scripting (XSS) attacks from stealing user session tokens.

Error Handling​

OCC returns structured error objects. The Archibald integration layer maps these into a unified DefaultResponseError format, allowing the frontend to react gracefully (e.g., showing a 404 for an UnknownIdentifierError).

Next Steps​

To see how to configure these endpoints for your project, visit the Configuration Guide.