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.

> **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](references/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](references/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](references/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](references/service-layer-architecture.md).

### Data Management
**ImpEx**: Scripting language for data import/export. See [impex-guide.md](references/impex-guide.md).
**FlexibleSearch**: SQL-like query language for items. See [flexiblesearch-reference.md](references/flexiblesearch-reference.md).

### OCC API
RESTful web services exposing commerce functionality. Controllers use `DataMapper` for DTO conversion. See [occ-api-development.md](references/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](references/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](references/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](references/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](references/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](references/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](references/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](references/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](references/promotions-rule-engine.md).

### Caching
Multi-layered caching: platform region caches (entity, query, typesystem), Spring `@Cacheable`, and cluster-aware invalidation. See [caching-guide.md](references/caching-guide.md).

### Backoffice
Administration UI customization via cockpitng: widget configuration, custom editors, search/list views, wizards, and deep links. See [backoffice-configuration.md](references/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](references/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](references/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](references/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](references/impex-guide.md) | Templates: `assets/impex-scripts/`

### Query with FlexibleSearch
```sql
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](references/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](references/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](references/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](references/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](references/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](references/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](references/promotions-rule-engine.md) | Templates: `assets/promotions/`

### Integrate Composable Storefront (Spartacus)
1. Set up OCC endpoints and CORS on the Commerce backend
2. Scaffold Angular app: `ng add @spartacus/schematics@latest --base-url <OCC_URL> --base-site=<SITE_ID> --ssr`
3. Configure `SpartacusConfigurationModule` with `provideConfig`
4. Customize CMS components via `cmsComponents` mapping in `provideConfig`
5. Override services by providing custom service classes in feature modules

Reference: [composable-storefront.md](references/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](references/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](references/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](references/testing-guide.md)

## Quick Reference

| Task | Reference | Assets | Script |
|------|-----------|--------|--------|
| Extension setup | [extension-development.md](references/extension-development.md) | `assets/extension-structure/` | `scripts/generate-extension.sh` |
| Type definitions | [type-system.md](references/type-system.md) | `assets/item-type-definition/` | - |
| Service layer | [service-layer-architecture.md](references/service-layer-architecture.md) | `assets/service-layer/` | - |
| Data import | [impex-guide.md](references/impex-guide.md) | `assets/impex-scripts/` | `scripts/validate-impex.sh` |
| Queries | [flexiblesearch-reference.md](references/flexiblesearch-reference.md) | `assets/flexiblesearch-queries/` | `scripts/query-items.sh` |
| API customization | [occ-api-development.md](references/occ-api-development.md) | `assets/occ-customization/` | - |
| Checkout/Storefront (legacy) | [accelerator-customization.md](references/accelerator-customization.md) | `assets/checkout-customization/` | - |
| Composable Storefront | [composable-storefront.md](references/composable-storefront.md) | `assets/composable-storefront/` | - |
| CCv2 deployment | [ccv2-deployment.md](references/ccv2-deployment.md) | - | - |
| SAP BTP/Kyma | [sap-btp-integration.md](references/sap-btp-integration.md) | - | - |
| Testing | [testing-guide.md](references/testing-guide.md) | - | - |
| Spring config | [spring-configuration.md](references/spring-configuration.md) | - | - |
| Data patterns | [data-modeling-patterns.md](references/data-modeling-patterns.md) | - | - |
| Troubleshooting | [troubleshooting-guide.md](references/troubleshooting-guide.md) | - | - |
| CronJobs | [cronjob-task-engine.md](references/cronjob-task-engine.md) | `assets/cronjob/` | - |
| Business processes | [business-process.md](references/business-process.md) | `assets/business-process/` | - |
| Solr search | [solr-search-configuration.md](references/solr-search-configuration.md) | `assets/solr-configuration/` | - |
| Promotions | [promotions-rule-engine.md](references/promotions-rule-engine.md) | `assets/promotions/` | - |
| Caching | [caching-guide.md](references/caching-guide.md) | - | - |
| Backoffice | [backoffice-configuration.md](references/backoffice-configuration.md) | - | - |

## 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/
Production-quality code templates ready to copy and customize. Organized by domain (service-layer, impex-scripts, etc.).