Sap Commerce Cloud

SAP Commerce Development

Overview

SAP Commerce Cloud (formerly Hybris) is an enterprise e-commerce platform built on Java and Spring. This skill provides guidance for extension development, type system modeling, service layer implementation, data management, API customization, accelerator patterns, Composable Storefront (Spartacus/Angular) integration, CCv2 cloud deployment, SAP BTP/Kyma integration, SmartEdit customization, and testing patterns for both Cloud (CCv2) and On-Premise deployments.

Platform baseline: Examples target SAP Commerce Cloud 2211-jdk21.1 or later, using JDK 21, Spring 6, Jakarta APIs, and OpenAPI 3. Use commerceSuiteVersion: "2211-jdk21" in CCv2 to follow the latest update in that line. See jdk21-migration.md.

Modern Storefront Note: The JSP-based Accelerator storefront (Spring Web Flow, JSP/JSTL) is the legacy approach. The modern recommended storefront is Composable Storefront (formerly Spartacus) — an Angular/TypeScript Single Page Application that communicates with the backend exclusively via OCC REST APIs. New projects should use Composable Storefront. See composable-storefront.md.

Core Architecture

Type System

Data modeling via items.xml defines item types, attributes, relations, and enumerations. Types are compiled into Java classes during build. See type-system.md for syntax and patterns.

Extensions

Modular architecture where functionality lives in extensions. Each extension has extensioninfo.xml for metadata, items.xml for types, and *-spring.xml for beans. See extension-development.md.

Service Layer

Four-layer architecture: Facade (API for controllers) → Service (business logic) → DAO (data access) → Model (generated from types). See service-layer-architecture.md.

Data Management

ImpEx: Scripting language for data import/export. See impex-guide.md. FlexibleSearch: SQL-like query language for items. See flexiblesearch-reference.md.

OCC API

RESTful web services exposing commerce functionality. Controllers use DataMapper for DTO conversion. See occ-api-development.md.

Accelerators (Legacy JSP Storefront)

Pre-built JSP/Spring MVC storefronts: B2C (retail) and B2B (enterprise with approval workflows). Legacy approach — new projects should use Composable Storefront or a headless approach. See accelerator-customization.md.

Composable Storefront (Spartacus)

Angular/TypeScript SPA that replaces JSP accelerators. Communicates exclusively via OCC APIs. Supports PWA, SSR, and feature libraries for B2C/B2B. See composable-storefront.md.

Headless Commerce

SAP Commerce Cloud as a headless backend — OCC APIs consumed by any frontend (React, Vue, mobile apps, etc.). The backend serves product, catalog, cart, order, and user data via REST. Composable Storefront is SAP's reference headless frontend, but custom frontends are supported.

CCv2 Cloud Deployment

SAP Commerce Cloud v2 (CCv2) is the managed cloud offering. Deployment is driven by manifest.json defining extensions, aspects (storefront/api/backoffice), and properties. See ccv2-deployment.md.

SAP BTP Integration

SAP Business Technology Platform integration via API Registry module and SAP BTP Extensions Integration Module (Kyma runtime). Allows microservices/serverless functions to react to Commerce events. See sap-btp-integration.md.

CronJobs & Task Engine

Scheduled and asynchronous job execution. Define AbstractJobPerformable implementations, configure via ServicelayerJob + CronJob + Trigger in ImpEx. See cronjob-task-engine.md.

Business Processes

Stateful workflows for order processing, returns, approvals, and custom flows. XML process definitions with action beans (AbstractSimpleDecisionAction, AbstractAction), wait states, and event triggers. See business-process.md.

Solr Search

Product search and faceted navigation powered by Apache Solr. Configure indexed types, properties, value providers, and boost rules. See solr-search-configuration.md.

Promotions & Rule Engine

Drools-based promotion rules with conditions and actions. Supports order/product/customer promotions, coupons, and custom actions. See promotions-rule-engine.md.

Caching

Multi-layered caching: platform region caches (entity, query, typesystem), Spring @Cacheable, and cluster-aware invalidation. See caching-guide.md.

Backoffice

Administration UI customization via cockpitng: widget configuration, custom editors, search/list views, wizards, and deep links. See backoffice-configuration.md.

Common Workflows

Create a Custom Extension

1. Generate structure with ant extgen or use template from assets/extension-structure/
2. Configure extensioninfo.xml with dependencies
3. Define types in items.xml
4. Configure beans in *-spring.xml
5. Add to localextensions.xml
6. Build: ant clean all

Reference: extension-development.md | Template: assets/extension-structure/

Define Custom Item Types

1. Create or modify *-items.xml in extension
2. Define itemtype with attributes, relations
3. Build to generate model classes
4. Use in services/DAOs

Reference: type-system.md | Templates: assets/item-type-definition/

Implement Service Layer

1. Create DTO class for data transfer
2. Create DAO interface and implementation with FlexibleSearch
3. Create Service interface and implementation with business logic
4. Create Facade interface and implementation for external API
5. Configure beans in *-spring.xml

Reference: service-layer-architecture.md | Templates: assets/service-layer/

Import Data with ImpEx

1. Create .impex file with header and data rows
2. Use INSERT_UPDATE for create/modify operations
3. Define macros for reusable values
4. Import via HAC or ant importImpex

Reference: impex-guide.md | Templates: assets/impex-scripts/

Query with FlexibleSearch

SELECT {pk} FROM {Product} WHERE {code} = ?code
SELECT {p.pk} FROM {Product AS p JOIN Category AS c ON {p.supercategories} = {c.pk}} WHERE {c.code} = ?category

Reference: flexiblesearch-reference.md | Examples: assets/flexiblesearch-queries/

Customize OCC API

1. Create controller with @Controller and @RequestMapping
2. Create WsDTO for response data
3. Create populator for model-to-DTO conversion
4. Register in *-web-spring.xml

Reference: occ-api-development.md | Templates: assets/occ-customization/

Extend Accelerator Checkout

1. Create custom checkout step implementing CheckoutStep
2. Configure in checkout flow XML
3. Create JSP for step UI
4. Register beans in *-spring.xml

Reference: accelerator-customization.md | Templates: assets/checkout-customization/

Create a Scheduled Job (CronJob)

1. Implement AbstractJobPerformable<CronJobModel> with perform() method
2. Register Spring bean with parent="abstractJobPerformable"
3. Create ServicelayerJob, CronJob, and Trigger via ImpEx
4. Test via HAC > Platform > CronJobs

Reference: cronjob-task-engine.md | Templates: assets/cronjob/

Define a Business Process

1. Create process definition XML in resources/processes/
2. Implement action beans extending AbstractSimpleDecisionAction
3. Register action beans in Spring with parent="abstractAction"
4. Register process definition via ProcessDefinitionResource Spring bean
5. Start process via BusinessProcessService.createProcess() and startProcess()

Reference: business-process.md | Templates: assets/business-process/

Configure Solr Product Search

1. Set up SolrFacetSearchConfig with server, languages, currencies, catalog versions
2. Define SolrIndexedType for Product
3. Configure SolrIndexedProperty entries (searchable, facet, sortable)
4. Set up indexer CronJobs (full nightly, incremental every 5 min)
5. Test search via HAC > Platform > Solr

Reference: solr-search-configuration.md | Templates: assets/solr-configuration/

Set Up Promotions

1. Create PromotionGroup for your store
2. Define PromotionSourceRule with conditions and actions
3. Configure coupons (SingleCodeCoupon / MultiCodeCoupon) if needed
4. Publish rules to activate them
5. Test in Backoffice > Marketing > Promotion Rules

Reference: promotions-rule-engine.md | Templates: assets/promotions/

Integrate Composable Storefront (Spartacus)

1. Set up OCC endpoints and CORS on the Commerce backend
2. Select a Composable Storefront version from SAP's compatibility matrix
3. Scaffold Angular app: ng add @spartacus/schematics@<COMPATIBLE_VERSION> --base-url <OCC_URL> --base-site=<SITE_ID> --ssr
4. Configure SpartacusConfigurationModule with provideConfig
5. Customize CMS components via cmsComponents mapping in provideConfig
6. Override services by providing custom service classes in feature modules

Reference: composable-storefront.md | Templates: assets/composable-storefront/

Deploy to CCv2

1. Configure manifest.json at repository root with commerceSuiteVersion, extensions, aspects
2. Set environment properties in CCv2 Cloud Portal or property files
3. Push to connected repository to trigger build
4. Promote build through environments (dev → staging → production)

Reference: ccv2-deployment.md

Integrate SAP BTP / Kyma

1. Configure API Registry module to expose Commerce APIs and events
2. Connect Kyma runtime via SAP BTP Extensions Integration Module
3. Implement microservices/lambdas to react to Commerce events
4. Use API Registry for webhook-based outbound communication

Reference: sap-btp-integration.md

Write Tests for Custom Extension

1. Annotate unit tests with @UnitTest, integration tests with @IntegrationTest
2. Unit tests: use Mockito mocks, no Spring context, place in testsrc/
3. Integration tests: extend ServicelayerTest or ServicelayerTransactionalTest
4. OCC API integration tests: use REST Assured or MockMvc against a running OCC endpoint
5. Load test data via importCsv("/myext/test/testdata.impex", "utf-8")
6. Run locally: ant unittests -Dtestclasses.extensions=myextension
7. Configure CCv2 test run in manifest.json under "tests"

Reference: testing-guide.md

Quick Reference

Resources

scripts/

Utility scripts for common tasks:

• generate-extension.sh - Scaffold new extension structure
• validate-impex.sh - Validate ImpEx syntax before import
• query-items.sh - Execute FlexibleSearch queries via HAC

references/

Detailed guides for each topic area. Load as needed for in-depth information.

assets/

Focused reference templates organized by domain. Copy only the files relevant to the task, replace com.example packages, and adapt project-specific business rules before production use.