DEV Community: Aliaksandr Tsviatkou

CAP Advanced Patterns — Drafts, i18n, Audit Logging & Production Readiness

Aliaksandr Tsviatkou — Thu, 26 Mar 2026 15:26:41 +0000

Lesson 3.4 — CAP Advanced Patterns & Production Readiness

1. Draft Handling
2. Localization (i18n)
3. Temporal Data & Audit Logging
4. Deployment Topologies
5. Performance Optimization
Top 5 Pitfalls
What to Learn Next

Summary: Production CAP Java applications require mastering draft handling for Fiori UIs, localization/i18n, temporal data, deployment topologies (MTA vs Helm), and performance optimization. This lesson covers these advanced patterns with practical examples and configuration.

1. Draft Handling

What is Draft?

Draft enables Fiori's "edit session" pattern: a user opens an entity for editing, makes changes over multiple requests, then saves or discards. Changes are stored in a draft table until explicitly activated.

User clicks "Edit"     User modifies fields     User clicks "Save"
       │                      │                        │
       ▼                      ▼                        ▼
┌──────────────┐    ┌──────────────┐    ┌──────────────────────┐
│ DRAFT_NEW    │    │ Draft table  │    │ Copy draft → active  │
│ creates draft│───→│ updated      │───→│ Delete draft          │
│ copy         │    │ (multiple    │    │ Return active entity  │
│              │    │  requests)   │    │                       │
└──────────────┘    └──────────────┘    └──────────────────────┘

CDS Annotation

service AdminService {
    @odata.draft.enabled
    entity Books as projection on db.Books;
}

This auto-generates:

DRAFT_Books table for storing in-progress edits
Draft-specific OData actions: draftEdit, draftActivate, draftPrepare

Draft Handler in Java

@Component
@ServiceName(AdminService_.CDS_NAME)
public class AdminServiceHandler implements EventHandler {

    // Runs when user clicks "Save" (draft → active)
    @Before(event = DraftService.EVENT_DRAFT_SAVE, entity = Books_.CDS_NAME)
    public void validateOnSave(DraftSaveEventContext context) {
        CqnSelect draftQuery = Select.from(Books_.class)
            .where(b -> b.IsActiveEntity().eq(false)  // draft version
                .and(b.ID().eq(context.getCqn().entries().get(0).get("ID"))));

        Books draft = db.run(draftQuery).single(Books.class);

        if (draft.getTitle() == null || draft.getTitle().isBlank()) {
            throw new ServiceException(ErrorStatuses.BAD_REQUEST,
                "Title is required before saving");
        }
        if (draft.getPrice() == null || draft.getPrice().compareTo(BigDecimal.ZERO) <= 0) {
            throw new ServiceException(ErrorStatuses.BAD_REQUEST,
                "Price must be positive");
        }
    }

    // Runs during draft preparation (field validation while editing)
    @Before(event = DraftService.EVENT_DRAFT_PREPARE, entity = Books_.CDS_NAME)
    public void prepareWarnings(DraftPrepareEventContext context) {
        // Side-effect free validation — add warnings but don't reject
        Messages messages = context.getMessages();
        // Add warnings that show in Fiori UI but don't block save
    }
}

Draft Timeout

cds:
  drafts:
    cancellation-timeout: 15d  # Auto-delete drafts after 15 days

2. Localization (i18n)

CDS Text Bundles

// db/schema.cds
entity Books {
    key ID : UUID;
    title  : localized String(200);  // enables translations
    descr  : localized String(2000);
}

The localized keyword generates a Books.texts table:

-- Auto-generated
CREATE TABLE my_bookshop_Books_texts (
    locale VARCHAR(14),
    ID UUID,
    title VARCHAR(200),
    descr VARCHAR(2000),
    PRIMARY KEY (locale, ID)
);

i18n Properties Files

# srv/src/main/resources/i18n/messages.properties (default/English)
book_not_found=Book with ID {0} not found
order_submitted=Order {0} submitted successfully
insufficient_stock=Not enough stock for book {0}. Available: {1}

# srv/src/main/resources/i18n/messages_de.properties (German)
book_not_found=Buch mit ID {0} nicht gefunden
order_submitted=Bestellung {0} erfolgreich eingereicht
insufficient_stock=Nicht genug Bestand für Buch {0}. Verfügbar: {1}

Using Localized Messages in Handlers

@On(event = "submitOrder")
public void onSubmitOrder(SubmitOrderContext context) {
    Books book = db.run(Select.from(Books_.class).byId(context.getBook()))
        .first(Books.class)
        .orElseThrow(() -> new ServiceException(ErrorStatuses.NOT_FOUND,
            MessageKeys.BOOK_NOT_FOUND, context.getBook()));

    if (book.getStock() < context.getQuantity()) {
        throw new ServiceException(ErrorStatuses.CONFLICT,
            MessageKeys.INSUFFICIENT_STOCK, book.getTitle(), book.getStock());
    }
    // ... process order
}

3. Temporal Data & Audit Logging

Managed Aspects (Auto-filled Fields)

using { managed, cuid } from '@sap/cds/common';

entity Orders : cuid, managed {
    // cuid provides: key ID : UUID;
    // managed provides: createdAt, createdBy, modifiedAt, modifiedBy
    orderNo    : String(20);
    totalAmount: Decimal(15,2);
    status     : String(20);
}

CAP automatically fills these fields:

createdAt / modifiedAt — server timestamp
createdBy / modifiedBy — from JWT user ID

Audit Logging with @changelog

@changelog: [title, price, stock]
entity Books : managed {
    key ID : UUID;
    title  : String(200);
    price  : Decimal(10,2);
    stock  : Integer;
}

CAP generates change log entries for annotated fields, recording old value, new value, user, and timestamp.

Soft Delete Pattern

entity Orders : managed {
    key ID      : UUID;
    // ... fields ...
    deletedAt   : Timestamp;
    deletedBy   : String(255);
}

// Service shows only non-deleted
service OrderService {
    entity Orders as projection on db.Orders
        where deletedAt is null;
}

@On(event = CqnService.EVENT_DELETE, entity = Orders_.CDS_NAME)
public void softDelete(CdsDeleteEventContext context) {
    // Instead of physical delete, set deleted fields
    String orderId = extractId(context);
    CqnUpdate update = Update.entity(Orders_.class)
        .data("deletedAt", Instant.now())
        .data("deletedBy", context.getUserInfo().getName())
        .byId(orderId);
    db.run(update);
    context.setResult(List.of(Map.of("ID", orderId)));
    context.setCompleted(); // prevent generic delete handler
}

4. Deployment Topologies

MTA (Cloud Foundry)

# mta.yaml
_schema-version: "3.1"
ID: my-cap-app
version: 1.0.0

modules:
  - name: my-cap-srv
    type: java
    path: srv
    parameters:
      memory: 1024M
      buildpack: sap_java_buildpack_jakarta
    properties:
      SPRING_PROFILES_ACTIVE: cloud
      JBP_CONFIG_COMPONENTS: '{jres: ["com.sap.xs.java.buildpack.jre.SAPMachineJRE"]}'
    requires:
      - name: my-xsuaa
      - name: my-hana
      - name: my-destination

  - name: my-cap-db-deployer
    type: hdb
    path: gen/db
    requires:
      - name: my-hana

resources:
  - name: my-xsuaa
    type: org.cloudfoundry.managed-service
    parameters:
      service: xsuaa
      service-plan: application
      path: ./xs-security.json

  - name: my-hana
    type: com.sap.xs.hdi-container
    parameters:
      service: hana
      service-plan: hdi-shared

  - name: my-destination
    type: org.cloudfoundry.managed-service
    parameters:
      service: destination
      service-plan: lite

Helm (Kyma)

my-cap-helm/
├── Chart.yaml
├── values.yaml
├── templates/
│   ├── deployment-srv.yaml
│   ├── deployment-sidecar.yaml    # MTX sidecar (if multi-tenant)
│   ├── service.yaml
│   ├── apirule.yaml
│   ├── service-instance-xsuaa.yaml
│   ├── service-instance-hana.yaml
│   ├── service-binding-xsuaa.yaml
│   ├── service-binding-hana.yaml
│   └── job-db-deploy.yaml          # HDI deployer as K8s Job

CF vs Kyma Deployment Comparison

Aspect	Cloud Foundry (MTA)	Kyma (Helm)
Packaging	MTA archive (.mtar)	Docker image + Helm chart
DB deployment	`hdb` module (auto)	K8s Job with HDI deployer image
Service binding	MTA `requires`	BTP Operator CRDs
Scaling	CF `instances` parameter	K8s HPA
Routing	CF routes + approuter	APIRule + Istio
Sidecar (MTX)	Separate CF app	Separate K8s Deployment

5. Performance Optimization

Query Optimization

// BAD: fetches all columns, all rows
CqnSelect bad = Select.from(Books_.class);

// GOOD: project only needed columns, filter, limit
CqnSelect good = Select.from(Books_.class)
    .columns(b -> b.ID(), b -> b.title(), b -> b.price())
    .where(b -> b.stock().gt(0))
    .orderBy(b -> b.title().asc())
    .limit(50);

Batch Operations

// BAD: N individual inserts
for (Map<String, Object> book : books) {
    db.run(Insert.into(Books_.class).entry(book));
}

// GOOD: single batch insert
db.run(Insert.into(Books_.class).entries(books));

Connection Pool Tuning

spring:
  datasource:
    hikari:
      maximum-pool-size: 10
      minimum-idle: 2
      connection-timeout: 30000
      idle-timeout: 600000
      max-lifetime: 1800000

Caching with Spring Cache

@Cacheable(value = "genres", key = "'all'")
public List<Genres> getAllGenres() {
    return db.run(Select.from(Genres_.class)).listOf(Genres.class);
}

@CacheEvict(value = "genres", allEntries = true)
public void onGenreChanged() {
    // Called when genres are modified
}

Top 5 Pitfalls

Not enabling draft for Fiori edit scenarios. Without @odata.draft.enabled, Fiori Elements uses "direct edit" mode which doesn't support multi-step editing or concurrent user detection.
Ignoring the localized keyword. Adding translations retroactively requires database migration. Plan for i18n from the start using localized on user-facing String fields.
Deploying without a startup probe. CAP Java apps with CDS compilation at startup can take 30-60s. Without a startup probe, Kubernetes kills the pod before it's ready.
Not batching database operations. Individual inserts/updates in a loop are orders of magnitude slower than batch operations. Always use .entries(list).
MTA descriptor out of sync with actual services. Forgetting to add a new service to mta.yaml causes deployment failures. Keep the MTA descriptor as the definitive deployment manifest.

What to Learn Next

Lesson 3.5: CAP Fiori Elements — UI annotations for automatic UI generation
Lesson 1.4: Multi-Tenancy — MTX sidecar deployment patterns
Lesson 4.1: CI/CD — automating MTA builds and Helm deployments
Lesson 4.2: Observability — monitoring CAP applications in production

CAP Remote Services & Mashups — Consuming External APIs

Aliaksandr Tsviatkou — Thu, 26 Mar 2026 15:26:38 +0000

Lesson 3.3 — CAP Remote Services & Mashups

1. Remote Service Architecture
2. Importing External Service Definitions
3. Destination Configuration
4. Consuming Remote Services in Handlers
5. Error Handling & Resilience
Top 5 Pitfalls
What to Learn Next

Summary: CAP Java supports integrating external services — S/4HANA OData APIs, REST APIs, and other CAP services — as "remote services" defined in CDS. This enables mashup scenarios where your application combines local data with remote data, projecting external entities alongside your own. This lesson covers importing external APIs, the Destination Service, remote service consumption, mashup patterns, and error handling.

1. Remote Service Architecture

┌────────────────────────────────────────────────────────────┐
│                  CAP Java Application                       │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  CDS Model                                           │   │
│  │  ┌──────────────┐  ┌──────────────────────────────┐  │   │
│  │  │ Local Entities│  │ External Service (imported)   │  │   │
│  │  │ (Books,      │  │ (API_BUSINESS_PARTNER)       │  │   │
│  │  │  Orders)     │  │                              │  │   │
│  │  └──────┬───────┘  └──────────────┬───────────────┘  │   │
│  │         │                         │                   │   │
│  │  ┌──────▼─────────────────────────▼───────────────┐   │   │
│  │  │  Mashup Service                                 │   │   │
│  │  │  (combines local + remote in one projection)    │   │   │
│  │  └──────────────────────┬──────────────────────────┘   │   │
│  └─────────────────────────┼──────────────────────────────┘   │
│                            │                                   │
│  ┌─────────────────────────▼──────────────────────────────┐   │
│  │  CAP Runtime                                            │   │
│  │  ┌──────────────────┐  ┌────────────────────────────┐  │   │
│  │  │ Local DB (HANA)  │  │ Remote HTTP Client          │  │   │
│  │  │ via CQN → SQL    │  │ via Destination Service     │  │   │
│  │  └──────────────────┘  └─────────────┬──────────────┘  │   │
│  └──────────────────────────────────────┼─────────────────┘   │
└─────────────────────────────────────────┼─────────────────────┘
                                          │
                          ┌───────────────▼───────────────┐
                          │  BTP Destination Service       │
                          │  ┌─────────────────────────┐   │
                          │  │ S4HANA_DEST              │   │
                          │  │  URL: https://s4.sap.com │   │
                          │  │  Auth: OAuth2SAMLBearer  │   │
                          │  └─────────────────────────┘   │
                          └───────────────┬───────────────┘
                                          │
                          ┌───────────────▼───────────────┐
                          │  S/4HANA Cloud                 │
                          │  /sap/opu/odata/sap/           │
                          │  API_BUSINESS_PARTNER          │
                          └───────────────────────────────┘

2. Importing External Service Definitions

Step 1: Download the EDMX

From the SAP Business Accelerator Hub or your S/4HANA system:

# Download API_BUSINESS_PARTNER EDMX
curl -o srv/external/API_BUSINESS_PARTNER.edmx \
  "https://api.sap.com/api/API_BUSINESS_PARTNER/resource/edmx"

Step 2: Import in CDS

// srv/external/API_BUSINESS_PARTNER.cds (auto-generated from EDMX)
// Run: cds import srv/external/API_BUSINESS_PARTNER.edmx

@cds.external
service API_BUSINESS_PARTNER {
    @cds.persistence.skip
    entity A_BusinessPartner {
        key BusinessPartner         : String(10);
        BusinessPartnerFullName     : String(81);
        FirstName                   : String(40);
        LastName                    : String(40);
        BusinessPartnerCategory     : String(1);
        to_BusinessPartnerAddress   : Composition of many A_BusinessPartnerAddress;
    }

    @cds.persistence.skip
    entity A_BusinessPartnerAddress {
        key BusinessPartner : String(10);
        key AddressID       : String(10);
        Country             : String(3);
        CityName            : String(40);
        StreetName          : String(60);
        PostalCode          : String(10);
    }
}

Step 3: Reference in Your Service

using { API_BUSINESS_PARTNER as s4bp } from './external/API_BUSINESS_PARTNER';
using { my.bookshop as db } from '../db/schema';

service MashupService {
    // Local entity
    entity Orders as projection on db.Orders;

    // Remote entity (projected from imported service)
    @readonly
    entity BusinessPartners as projection on s4bp.A_BusinessPartner {
        key BusinessPartner,
        BusinessPartnerFullName,
        FirstName,
        LastName
    };
}

3. Destination Configuration

BTP Destination Setup

Destination Name: S4HANA_BP
URL:              https://my-s4hana.s4hana.ondemand.com
Authentication:   OAuth2SAMLBearerAssertion
Audience:         https://my-s4hana.s4hana.ondemand.com
Token URL:        https://my-s4hana.s4hana.ondemand.com/sap/bc/sec/oauth2/token
Client ID:        <communication arrangement client>
Client Secret:    <communication arrangement secret>

CAP Configuration for Remote Services

# application.yaml
cds:
  remote:
    services:
      API_BUSINESS_PARTNER:
        destination:
          name: S4HANA_BP
          type: odata-v2      # S/4HANA uses OData V2
          suffix: /sap/opu/odata/sap/API_BUSINESS_PARTNER

Or via package.json / .cdsrc.json:

{
  "cds": {
    "requires": {
      "API_BUSINESS_PARTNER": {
        "kind": "odata-v2",
        "model": "srv/external/API_BUSINESS_PARTNER",
        "[production]": {
          "credentials": {
            "destination": "S4HANA_BP",
            "path": "/sap/opu/odata/sap/API_BUSINESS_PARTNER"
          }
        }
      }
    }
  }
}

4. Consuming Remote Services in Handlers

Basic Remote Service Call

@Component
@ServiceName(MashupService_.CDS_NAME)
public class MashupServiceHandler implements EventHandler {

    @Autowired
    @Qualifier(API_BUSINESS_PARTNER_.CDS_NAME)
    private CqnService bpService;  // Remote service (injected by CAP)

    @On(event = CqnService.EVENT_READ, entity = "MashupService.BusinessPartners")
    public void readBusinessPartners(CdsReadEventContext context) {
        // CAP translates CQN to OData query and sends to S/4HANA
        CqnSelect query = context.getCqn();
        Result result = bpService.run(query);
        context.setResult(result);
    }
}

Mashup: Combine Local + Remote Data

@After(event = CqnService.EVENT_READ, entity = Orders_.CDS_NAME)
public void enrichOrdersWithBPData(CdsReadEventContext context) {
    List<Map<String, Object>> orders = context.getResult().listOf(HashMap.class);

    // Collect unique BP IDs
    Set<String> bpIds = orders.stream()
        .map(o -> (String) o.get("customerId"))
        .filter(Objects::nonNull)
        .collect(Collectors.toSet());

    if (bpIds.isEmpty()) return;

    // Batch fetch from S/4HANA
    CqnSelect bpQuery = Select.from(A_BusinessPartner_.class)
        .columns(bp -> bp.BusinessPartner(), bp -> bp.BusinessPartnerFullName())
        .where(bp -> bp.BusinessPartner().in(bpIds));

    Map<String, String> bpNames = bpService.run(bpQuery)
        .streamOf(A_BusinessPartner_.class)
        .collect(Collectors.toMap(
            A_BusinessPartner::getBusinessPartner,
            A_BusinessPartner::getBusinessPartnerFullName
        ));

    // Enrich local orders with remote BP names
    orders.forEach(order -> {
        String bpId = (String) order.get("customerId");
        order.put("customerName", bpNames.getOrDefault(bpId, "Unknown"));
    });
}

Custom Action: Create in Remote System

@On(event = "createBusinessPartner")
public void createBP(CreateBusinessPartnerContext context) {
    Map<String, Object> bpData = new HashMap<>();
    bpData.put("BusinessPartnerCategory", "1"); // Person
    bpData.put("FirstName", context.getFirstName());
    bpData.put("LastName", context.getLastName());

    CqnInsert insert = Insert.into(A_BusinessPartner_.class).entry(bpData);

    try {
        Result result = bpService.run(insert);
        context.setResult(result.single(A_BusinessPartner_.class));
    } catch (ServiceException e) {
        throw new ServiceException(ErrorStatuses.BAD_GATEWAY,
            "Failed to create BP in S/4HANA: " + e.getMessage(), e);
    }
}

5. Error Handling & Resilience

Timeout Configuration

cds:
  remote:
    services:
      API_BUSINESS_PARTNER:
        http:
          timeout: 30000       # 30 seconds
          connectionTimeout: 5000  # 5 seconds

Error Handling Pattern

@On(event = CqnService.EVENT_READ, entity = "MashupService.BusinessPartners")
public void readBPWithFallback(CdsReadEventContext context) {
    try {
        Result result = bpService.run(context.getCqn());
        context.setResult(result);
    } catch (ServiceException e) {
        if (isTransientError(e)) {
            // Retry once
            try {
                Thread.sleep(1000);
                Result result = bpService.run(context.getCqn());
                context.setResult(result);
            } catch (Exception retryEx) {
                log.error("Retry failed for BP read", retryEx);
                throw new ServiceException(ErrorStatuses.BAD_GATEWAY,
                    "S/4HANA temporarily unavailable");
            }
        } else {
            throw new ServiceException(ErrorStatuses.BAD_GATEWAY,
                "Failed to read from S/4HANA: " + e.getMessage());
        }
    }
}

private boolean isTransientError(ServiceException e) {
    int status = e.getErrorStatus().getCode();
    return status == 503 || status == 429 || status == 408;
}

Caching Remote Data

@Autowired
private CacheManager cacheManager;

@Cacheable(value = "businessPartners", key = "#bpId", unless = "#result == null")
public A_BusinessPartner getCachedBP(String bpId) {
    CqnSelect query = Select.from(A_BusinessPartner_.class).byId(bpId);
    return bpService.run(query).single(A_BusinessPartner_.class);
}

spring:
  cache:
    caffeine:
      spec: maximumSize=500,expireAfterWrite=300s  # 5 min TTL

Top 5 Pitfalls

Not using the Destination Service. Hardcoding S/4HANA URLs and credentials in your app is a security risk and breaks environment portability. Always use BTP Destinations.
Fetching too much data from remote systems. CQN queries on remote services translate to OData $filter, $select, $top. If you fetch all BPs without filters, you'll time out. Always project and filter.
Ignoring OData version mismatch. S/4HANA uses OData V2. CAP's remote service client handles translation, but you must configure type: odata-v2 correctly.
No error handling for remote calls. Remote systems go down. Without try/catch, a single S/4HANA timeout will return 500 to your users instead of a graceful degradation.
N+1 query problem with mashups. Fetching BP data for each order individually creates N remote calls. Always batch-fetch remote data using IN filters.

What to Learn Next

Lesson 3.1: CAP Architecture — handler model and CQN queries
Lesson 3.4: CAP Advanced Patterns — deployment topologies, caching strategies
Lesson 2.4: Kyma Eventing — event-driven integration alternative to synchronous API calls
Lesson 1.3: Event Mesh — asynchronous data synchronization patterns

CAP Security & Authorization — XSUAA, @restrict & Multi-Tenant Auth

Aliaksandr Tsviatkou — Thu, 26 Mar 2026 15:26:35 +0000

Lesson 3.2 — CAP Security, Authorization & Authentication

1. Authentication Architecture
2. CDS-Based Authorization
3. Programmatic Authorization
4. Multi-Tenant Security
5. Testing with Mock Users
Top 5 Pitfalls
What to Learn Next

Summary: CAP Java integrates with SAP XSUAA and IAS for authentication and provides a declarative authorization model via CDS annotations (@requires, @restrict). This lesson covers the authentication flow, CDS-based authorization, instance-based authorization, programmatic security, multi-tenant security concerns, and testing with mock users.

1. Authentication Architecture

Authentication Flow

Browser/Client          Approuter           XSUAA              CAP Java
     │                     │                  │                    │
     │  GET /app           │                  │                    │
     │────────────────────→│                  │                    │
     │                     │ redirect to login│                    │
     │←────────────────────│                  │                    │
     │                     │                  │                    │
     │  Login credentials  │                  │                    │
     │─────────────────────┼─────────────────→│                    │
     │                     │                  │ Authenticate       │
     │                     │                  │ Issue JWT           │
     │  JWT token          │                  │                    │
     │←────────────────────┼──────────────────│                    │
     │                     │                  │                    │
     │  GET /odata/v4/catalog/Books           │                    │
     │  Authorization: Bearer <JWT>           │                    │
     │────────────────────────────────────────┼───────────────────→│
     │                     │                  │                    │
     │                     │                  │    Validate JWT    │
     │                     │                  │    Extract roles   │
     │                     │                  │    Check @restrict │
     │                     │                  │                    │
     │  200 OK + data      │                  │                    │
     │←───────────────────────────────────────┼────────────────────│

JWT Claims Used by CAP

{
  "sub": "user123",
  "email": "john@example.com",
  "scope": [
    "my-app!t12345.Viewer",
    "my-app!t12345.Admin"
  ],
  "xs.user.attributes": {
    "Country": ["DE", "US"],
    "CostCenter": ["CC100"]
  },
  "zid": "tenant-zone-id",
  "grant_type": "authorization_code"
}

CAP extracts from JWT:

Roles — from scope claim (mapped via role templates)
User attributes — from xs.user.attributes (for instance-based auth)
Tenant — from zid claim (for multi-tenancy)
User ID — from sub or user_name claim

Configuration

# application.yaml
cds:
  security:
    authentication:
      mode: jwt          # jwt (production) or dummy (development)
    mock:
      users:
        alice:
          password: alice
          roles: [Admin, Viewer]
          attributes:
            Country: [DE]
        bob:
          password: bob
          roles: [Viewer]
          attributes:
            Country: [US]

2. CDS-Based Authorization

@requires — Role-Based Access to Entire Services/Entities

// Require authentication for the entire service
service CatalogService @(requires: 'authenticated-user') {

    // Public read, but require Viewer role
    @requires: 'Viewer'
    entity Books as projection on db.Books;

    // Only Admin can manage authors
    @requires: 'Admin'
    entity Authors as projection on db.Authors;
}

// Admin-only service
service AdminService @(requires: 'Admin') {
    entity Config as projection on db.AppConfig;
}

@restrict — Fine-Grained Operation-Level Authorization

service CatalogService {

    // Different roles for different operations
    @restrict: [
        { grant: 'READ',   to: 'Viewer' },
        { grant: 'WRITE',  to: 'Editor' },
        { grant: '*',      to: 'Admin'  }
    ]
    entity Books as projection on db.Books;

    // Instance-based: users can only see their own orders
    @restrict: [
        { grant: 'READ', to: 'Customer', where: 'createdBy = $user' },
        { grant: '*',    to: 'Admin' }
    ]
    entity Orders as projection on db.Orders;

    // Attribute-based: users see data from their country only
    @restrict: [
        { grant: 'READ', to: 'Viewer', where: 'country = $user.Country' },
        { grant: '*',    to: 'Admin' }
    ]
    entity Suppliers as projection on db.Suppliers;
}

Pseudo-Variables in @restrict

Variable	Meaning	Source
`$user`	Current user ID	JWT `sub` claim
`$user.<attr>`	User attribute value	JWT `xs.user.attributes`
`$now`	Current timestamp	Server clock
`$unrestricted`	Bypass all restrictions	Used in privileged service calls

xs-security.json Mapping

{
  "xsappname": "my-app",
  "tenant-mode": "dedicated",
  "scopes": [
    { "name": "$XSAPPNAME.Viewer", "description": "Read access" },
    { "name": "$XSAPPNAME.Editor", "description": "Write access" },
    { "name": "$XSAPPNAME.Admin",  "description": "Full access" }
  ],
  "attributes": [
    { "name": "Country", "description": "Country filter", "valueType": "string" },
    { "name": "CostCenter", "description": "Cost center", "valueType": "string" }
  ],
  "role-templates": [
    {
      "name": "Viewer",
      "scope-references": ["$XSAPPNAME.Viewer"],
      "attribute-references": ["Country"]
    },
    {
      "name": "Editor",
      "scope-references": ["$XSAPPNAME.Editor", "$XSAPPNAME.Viewer"],
      "attribute-references": ["Country"]
    },
    {
      "name": "Admin",
      "scope-references": ["$XSAPPNAME.Admin", "$XSAPPNAME.Editor", "$XSAPPNAME.Viewer"]
    }
  ]
}

3. Programmatic Authorization

Accessing User Info in Handlers

@Component
@ServiceName(CatalogService_.CDS_NAME)
public class CatalogServiceHandler implements EventHandler {

    @Before(event = CqnService.EVENT_CREATE, entity = Orders_.CDS_NAME)
    public void enrichOrder(CdsCreateEventContext context) {
        UserInfo user = context.getUserInfo();

        // Get user ID
        String userId = user.getName();

        // Check roles
        boolean isAdmin = user.hasRole("Admin");

        // Get user attributes
        List<String> countries = user.getAttributeValues("Country");

        // Set audit fields
        context.getCqn().entries().forEach(order -> {
            order.put("createdBy", userId);
            order.put("createdAt", Instant.now());
        });
    }

    @Before(event = CqnService.EVENT_UPDATE, entity = Orders_.CDS_NAME)
    public void checkOwnership(CdsUpdateEventContext context) {
        UserInfo user = context.getUserInfo();
        if (user.hasRole("Admin")) return; // Admin can update anything

        // Check if user owns the order
        String orderId = context.getCqn().entries().get(0).get("ID").toString();
        CqnSelect check = Select.from(Orders_.class)
            .where(o -> o.ID().eq(orderId).and(o.createdBy().eq(user.getName())));

        if (db.run(check).rowCount() == 0) {
            throw new ServiceException(ErrorStatuses.FORBIDDEN,
                "You can only update your own orders");
        }
    }
}

Privileged (Technical) Access

For service-to-service calls or background jobs that need to bypass authorization:

@Autowired
private CqnService catalogService;

public void backgroundJob() {
    // Run with system/privileged user — bypasses @restrict
    RequestContext privileged = RequestContext.CDS_SYSTEM_USER;

    catalogService.run(privileged, ctx -> {
        CqnSelect allOrders = Select.from(Orders_.class);
        return db.run(allOrders);
    });
}

4. Multi-Tenant Security

Tenant Isolation

In multi-tenant applications, CAP automatically:

Extracts tenant ID from JWT zid claim
Routes database queries to the correct HDI container
Prevents cross-tenant data access

@Before(event = "*")
public void logTenantAccess(EventContext context) {
    String tenant = context.getUserInfo().getTenant();
    log.info("Request from tenant: {}", tenant);
    // CAP automatically routes to correct HDI container
    // No manual tenant filtering needed!
}

Cross-Tenant API Calls

If a provider-side job needs to access tenant data:

public void processTenant(String tenantId) {
    RequestContext tenantContext = RequestContext.of(b -> {
        b.tenant(tenantId);
        b.user(SystemUser.of(tenantId));
    });

    service.run(tenantContext, ctx -> {
        // This runs in the context of the specified tenant
        return db.run(Select.from(Orders_.class));
    });
}

5. Testing with Mock Users

Integration Test Setup

@SpringBootTest
@AutoConfigureMockMvc
class CatalogServiceAuthTest {

    @Autowired
    private MockMvc mockMvc;

    @Test
    @WithMockUser(username = "alice", roles = {"Viewer"})
    void viewerCanReadBooks() throws Exception {
        mockMvc.perform(get("/odata/v4/catalog/Books"))
            .andExpect(status().isOk());
    }

    @Test
    @WithMockUser(username = "bob", roles = {"Viewer"})
    void viewerCannotCreateBooks() throws Exception {
        mockMvc.perform(post("/odata/v4/catalog/Books")
                .contentType("application/json")
                .content("{\"title\":\"New Book\",\"price\":29.99}"))
            .andExpect(status().isForbidden());
    }

    @Test
    void unauthenticatedCannotAccess() throws Exception {
        mockMvc.perform(get("/odata/v4/catalog/Books"))
            .andExpect(status().isUnauthorized());
    }

    @Test
    @WithMockUser(username = "admin", roles = {"Admin"})
    void adminCanCreateBooks() throws Exception {
        mockMvc.perform(post("/odata/v4/catalog/Books")
                .contentType("application/json")
                .content("{\"title\":\"New Book\",\"price\":29.99}"))
            .andExpect(status().isCreated());
    }
}

Mock Users in application.yaml (Dev Profile)

spring:
  profiles: default  # local development only
cds:
  security:
    authentication:
      mode: dummy     # accepts any credentials
    mock:
      users:
        admin:
          password: admin
          roles: [Admin, Editor, Viewer]
          attributes:
            Country: [DE, US]
        viewer:
          password: viewer
          roles: [Viewer]
          attributes:
            Country: [DE]

Top 5 Pitfalls

Using authentication.mode: dummy in production. This disables JWT validation entirely. Always use jwt mode in production and ensure XSUAA binding exists.
Confusing scopes and roles. XSUAA scopes are technical (my-app!t12345.Viewer). Role templates map scopes to business roles (Viewer). CDS @requires uses role template names.
Forgetting instance-based authorization for user-specific data. @requires: 'Viewer' grants access to ALL entities of that type. Use @restrict with where clauses for row-level filtering.
Not testing authorization in integration tests. Unit tests often skip security. Use @WithMockUser or CAP's mock user configuration to test authorization rules.
Hardcoding tenant checks in handlers. CAP handles tenant isolation automatically via the persistence layer. Manual WHERE tenant_id = ? filters are unnecessary and error-prone.

What to Learn Next

Lesson 1.4: Multi-Tenancy — XSUAA identity zones and tenant-mode
Lesson 3.1: CAP Architecture — handler model and event processing
Lesson 3.3: CAP Remote Services — securing service-to-service communication
Lesson 1.1: BTP Architecture — XSUAA and trust configuration

CAP Java Architecture — CDS, Event Handlers & CQN Query API

Aliaksandr Tsviatkou — Thu, 26 Mar 2026 15:26:32 +0000

Lesson 3.1 — CAP Java Architecture & Core Concepts

1. CAP Java Architecture Overview
2. CDS Compilation Pipeline
3. Event Handler Model
4. CQN Query API
5. Project Structure
Top 5 Pitfalls
What to Learn Next

Summary: The SAP Cloud Application Programming Model (CAP) for Java provides a framework built on Spring Boot that adds CDS-based domain modeling, a generic runtime for OData/REST services, an event-driven handler model, and built-in BTP service integration. This lesson covers the CAP Java architecture, CDS compilation pipeline, the event/handler model, CQN query API, and how CAP compares to pure Spring Boot development.

1. CAP Java Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                    CAP Java Application                      │
│                                                              │
│  ┌─────────────────────────────────────────────────────┐    │
│  │  CDS Model Layer (.cds files)                        │    │
│  │  - Domain entities, types, associations              │    │
│  │  - Service definitions (projections, actions)        │    │
│  │  - Annotations (UI, auth, validation)                │    │
│  └──────────────────────┬──────────────────────────────┘    │
│                         │ cds compile → CSN (JSON)           │
│  ┌──────────────────────▼──────────────────────────────┐    │
│  │  CAP Java Runtime                                    │    │
│  │  ┌──────────────┐ ┌──────────────┐ ┌─────────────┐  │    │
│  │  │ OData V4     │ │ REST         │ │ Messaging    │  │    │
│  │  │ Adapter      │ │ Adapter      │ │ Adapter      │  │    │
│  │  └──────┬───────┘ └──────┬───────┘ └──────┬──────┘  │    │
│  │         │                │                │          │    │
│  │  ┌──────▼────────────────▼────────────────▼──────┐   │    │
│  │  │            Generic Event Processor             │   │    │
│  │  │  (dispatches CQN events to handlers)           │   │    │
│  │  └──────────────────────┬─────────────────────────┘   │    │
│  │                         │                              │    │
│  │  ┌──────────────────────▼──────────────────────────┐  │    │
│  │  │         Custom Event Handlers (your code)        │  │    │
│  │  │  @Before / @On / @After                          │  │    │
│  │  └──────────────────────┬──────────────────────────┘  │    │
│  │                         │                              │    │
│  │  ┌──────────────────────▼──────────────────────────┐  │    │
│  │  │         Persistence Layer                        │  │    │
│  │  │  CQN → SQL (HANA / H2 / PostgreSQL)             │  │    │
│  │  └─────────────────────────────────────────────────┘  │    │
│  └────────────────────────────────────────────────────────┘  │
│                                                              │
│  ┌────────────────────────────────────────────────────────┐  │
│  │  Spring Boot Foundation                                 │  │
│  │  DI, Auto-config, Actuator, Security, Web Server        │  │
│  └────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

CAP = Spring Boot + CDS + Generic Runtime

What CAP Adds	What Spring Boot Provides
CDS modeling language	Dependency injection
Generic CRUD for OData/REST	Web server (Tomcat)
Event-driven handler model	Auto-configuration
CQN query abstraction	Actuator, profiles
BTP service integration	Security framework
Draft support	Transaction management
Fiori annotations	Testing infrastructure

2. CDS Compilation Pipeline

From .cds to Runtime

.cds files          cds compile          CSN (JSON)          CAP Runtime

schema.cds    ─┐                    ┌─ db/csn.json      ─┐
service.cds   ─┤──→ cds compile ──→├─ srv/csn.json     ─┤──→ Java classes
annotations.cds─┘                    └─ EDMX metadata    ─┘    + generic handlers

Domain Model (schema.cds)

namespace my.bookshop;

entity Books {
    key ID     : UUID;
    title      : String(200)  @mandatory;
    descr      : String(2000);
    author     : Association to Authors;
    genre      : Association to Genres;
    stock      : Integer      @assert.range: [0, 999];
    price      : Decimal(10,2);
    currency   : Currency;
    createdAt  : Timestamp    @cds.on.insert: $now;
    modifiedAt : Timestamp    @cds.on.insert: $now  @cds.on.update: $now;
}

entity Authors {
    key ID    : UUID;
    name      : String(100)  @mandatory;
    books     : Composition of many Books on books.author = $self;
    country   : Country;
}

entity Genres : sap.common.CodeList {
    key ID    : Integer;
    parent    : Association to Genres;
    children  : Composition of many Genres on children.parent = $self;
}

Service Definition (service.cds)

using my.bookshop as db from '../db/schema';

service CatalogService @(path: '/catalog') {

    @readonly
    entity Books as projection on db.Books {
        *, author.name as authorName
    } excluding { createdAt, modifiedAt };

    @requires: 'Admin'
    entity Authors as projection on db.Authors;

    // Unbound action
    action submitOrder(book : Books:ID, quantity : Integer) returns { stock : Integer };

    // Bound function
    function getBooksByAuthor(authorId : Authors:ID) returns array of Books;
}

What Gets Generated

From these CDS files, the CAP build produces:

CSN (Core Schema Notation) — JSON representation of the model
EDMX — OData V4 metadata document
HDI artifacts — SQL tables, views for HANA deployment
Java interfaces — Optional typed accessor interfaces

3. Event Handler Model

Handler Registration

@Component
@ServiceName(CatalogService_.CDS_NAME)
public class CatalogServiceHandler implements EventHandler {

    @Autowired
    private PersistenceService db;

    // BEFORE: validation, enrichment (runs before generic handler)
    @Before(event = CqnService.EVENT_CREATE, entity = Books_.CDS_NAME)
    public void validateBook(CdsCreateEventContext context) {
        context.getCqn().entries().forEach(book -> {
            String title = (String) book.get("title");
            if (title == null || title.isBlank()) {
                throw new ServiceException(ErrorStatuses.BAD_REQUEST, "Title is required");
            }
        });
    }

    // ON: replace generic handler (full control)
    @On(event = CqnService.EVENT_READ, entity = Books_.CDS_NAME)
    public void readBooks(CdsReadEventContext context) {
        // Custom read logic (e.g., external API call)
        CqnSelect query = context.getCqn();
        Result result = db.run(query);
        context.setResult(result);
    }

    // AFTER: post-processing (modify result before returning)
    @After(event = CqnService.EVENT_READ, entity = Books_.CDS_NAME)
    public void afterReadBooks(CdsReadEventContext context) {
        context.getResult().forEach(book -> {
            Integer stock = (Integer) book.get("stock");
            book.put("availability", stock > 0 ? "In Stock" : "Out of Stock");
        });
    }

    // Custom action handler
    @On(event = "submitOrder")
    public void onSubmitOrder(SubmitOrderContext context) {
        String bookId = context.getBook();
        Integer quantity = context.getQuantity();

        CqnSelect select = Select.from(Books_.class).byId(bookId);
        Books book = db.run(select).single(Books.class);

        if (book.getStock() < quantity) {
            throw new ServiceException(ErrorStatuses.CONFLICT, "Not enough stock");
        }

        book.setStock(book.getStock() - quantity);
        CqnUpdate update = Update.entity(Books_.class).data(book);
        db.run(update);

        context.setResult(Map.of("stock", book.getStock()));
        context.setCompleted();
    }
}

Event Processing Order

HTTP Request (OData/REST)
    │
    ▼
┌─────────────┐
│  @Before     │ ← Validation, enrichment, authorization checks
│  handlers    │   (multiple handlers possible, ordered by @HandlerOrder)
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  @On         │ ← Core logic (generic CRUD or your custom handler)
│  handler     │   Only ONE @On handler executes (first registered wins)
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  @After      │ ← Post-processing (modify result, trigger side effects)
│  handlers    │   (multiple handlers possible)
└──────┬──────┘
       │
       ▼
HTTP Response

4. CQN Query API

CQN (CDS Query Notation) is CAP's type-safe query builder, analogous to JPA Criteria API or jOOQ:

Select Queries

// Simple select
CqnSelect query = Select.from(Books_.class);

// With filter
CqnSelect query = Select.from(Books_.class)
    .where(b -> b.stock().gt(0)
        .and(b.price().lt(50)));

// With expand (join)
CqnSelect query = Select.from(Books_.class)
    .columns(b -> b._all(), b -> b.author().expand())
    .where(b -> b.genre().name().eq("Fiction"))
    .orderBy(b -> b.title().asc())
    .limit(10, 0);

// By key
CqnSelect byId = Select.from(Books_.class)
    .byId("550e8400-e29b-41d4-a716-446655440000");

Insert, Update, Delete

// Insert
Map<String, Object> bookData = Map.of(
    "ID", UUID.randomUUID().toString(),
    "title", "Clean Code",
    "price", 29.99,
    "stock", 100
);
CqnInsert insert = Insert.into(Books_.class).entry(bookData);
Result result = db.run(insert);

// Update
CqnUpdate update = Update.entity(Books_.class)
    .data("stock", 50)
    .byId(bookId);
db.run(update);

// Upsert
CqnUpsert upsert = Upsert.into(Books_.class).entry(bookData);
db.run(upsert);

// Delete
CqnDelete delete = Delete.from(Books_.class)
    .where(b -> b.stock().eq(0));
db.run(delete);

CQN vs JPA/Spring Data

CQN (CAP)	JPA / Spring Data
`Select.from(Books_.class)`	`bookRepository.findAll()`
`.where(b -> b.stock().gt(0))`	`@Query("SELECT b FROM Book b WHERE b.stock > 0")`
`.columns(b -> b.title(), b -> b.price())`	Projection interfaces
`db.run(query).listOf(Books.class)`	Repository method return
CDS associations (auto-join)	`@ManyToOne`, `@OneToMany`
No entity manager / session	EntityManager, L1/L2 cache

5. Project Structure

my-cap-project/
├── pom.xml                    # Parent POM
├── db/
│   ├── schema.cds             # Domain model
│   └── data/                  # CSV test data
│       └── my.bookshop-Books.csv
├── srv/
│   ├── pom.xml                # Service module POM
│   ├── src/main/
│   │   ├── resources/
│   │   │   ├── application.yaml
│   │   │   └── edmx/          # Generated OData metadata
│   │   └── java/
│   │       └── com/sap/demo/
│   │           ├── Application.java
│   │           └── handlers/
│   │               └── CatalogServiceHandler.java
│   └── cat-service.cds        # Service definition
├── app/                        # Fiori UI (optional)
└── mta.yaml                   # BTP deployment descriptor

Key Maven Dependencies

<dependencies>
    <!-- CAP Java SDK -->
    <dependency>
        <groupId>com.sap.cds</groupId>
        <artifactId>cds-starter-spring-boot</artifactId>
    </dependency>
    <!-- OData V4 protocol adapter -->
    <dependency>
        <groupId>com.sap.cds</groupId>
        <artifactId>cds-adapter-odata-v4</artifactId>
    </dependency>
    <!-- HANA database support -->
    <dependency>
        <groupId>com.sap.cds</groupId>
        <artifactId>cds-feature-hana</artifactId>
    </dependency>
    <!-- XSUAA security -->
    <dependency>
        <groupId>com.sap.cds</groupId>
        <artifactId>cds-feature-xsuaa</artifactId>
    </dependency>
</dependencies>

Top 5 Pitfalls

Bypassing the CQN API to use raw JDBC. CAP's generic runtime (authorization, draft, localization) only works through CQN. Raw SQL bypasses all of it.
Putting business logic in @After instead of @On. @After runs after the database operation. For validation or transformation before persistence, use @Before.
Not understanding that @On replaces the generic handler. If you register an @On handler for READ, the built-in CRUD handler won't run — you must handle the full query yourself or delegate to db.run().
Ignoring the CDS model as the single source of truth. Don't define database tables manually. Let CDS generate HDI artifacts, EDMX metadata, and typed interfaces from one model.
Using Spring Data repositories alongside CAP persistence. CAP has its own persistence layer. Mixing Spring Data JPA with CAP causes confusion about which layer handles transactions, caching, and authorization.

What to Learn Next

Lesson 3.2: CAP Security — @requires, @restrict, XSUAA integration
Lesson 3.3: CAP Remote Services — connecting to S/4HANA and external APIs
Lesson 3.4: CAP Advanced Patterns — draft, localization, deployment topologies
Lesson 3.5: CAP Fiori Elements — annotations for automatic UI generation

Kyma Eventing & S/4HANA Extension Patterns

Aliaksandr Tsviatkou — Thu, 26 Mar 2026 15:26:29 +0000

Lesson 2.4 — Kyma Eventing & Extension Patterns

1. Side-by-Side Extension Model
2. S/4HANA Event Integration
3. Extension Patterns
4. Resilience Patterns
5. Event Processing Best Practices
Top 5 Pitfalls
What to Learn Next

Summary: SAP's recommended approach for extending S/4HANA and other SAP systems is "side-by-side" extensions on BTP — keeping the clean core clean while building custom logic externally. Kyma provides the eventing infrastructure and runtime for these extensions. This lesson covers the side-by-side extension model, event-driven architecture patterns, S/4HANA event integration, and production-ready extension design.

1. Side-by-Side Extension Model

Clean Core Principle

┌──────────────────────────────────┐     ┌──────────────────────────────────┐
│        S/4HANA (Clean Core)       │     │     Kyma Runtime (Extensions)     │
│                                   │     │                                   │
│  ┌──────────────────────────────┐ │     │  ┌──────────────────────────────┐ │
│  │  Standard Business Logic     │ │     │  │  Custom Logic                │ │
│  │  (no modifications)          │ │     │  │  - Validations               │ │
│  └──────────────────────────────┘ │     │  │  - Enrichments               │ │
│                                   │     │  │  - Integrations              │ │
│  ┌──────────────────────────────┐ │     │  │  - Notifications             │ │
│  │  Released APIs (stable)      │─┼─────┼─→│  - Custom workflows          │ │
│  └──────────────────────────────┘ │     │  └──────────────────────────────┘ │
│                                   │     │                                   │
│  ┌──────────────────────────────┐ │     │  ┌──────────────────────────────┐ │
│  │  Business Events             │─┼─────┼─→│  Event Subscribers           │ │
│  │  (BP Changed, SO Created...) │ │     │  │  (Functions / Microservices) │ │
│  └──────────────────────────────┘ │     │  └──────────────────────────────┘ │
└──────────────────────────────────┘     └──────────────────────────────────┘
              │                                          │
              └──────────── Event Mesh ──────────────────┘

Why side-by-side?

S/4HANA upgrades are not blocked by custom code
Extensions can be developed, tested, and deployed independently
Different lifecycle: extensions can iterate faster than core ERP
Clear API boundaries via Released APIs and Business Events

2. S/4HANA Event Integration

Event Flow: S/4HANA → Kyma

S/4HANA Cloud              SAP Event Mesh           Kyma Runtime
     │                          │                        │
     │ BP Changed event         │                        │
     │ (RAP Business Event)     │                        │
     │─────────────────────────→│                        │
     │                          │ CloudEvent format      │
     │                          │────────────────────────→│
     │                          │                        │ Subscription match
     │                          │                        │ → deliver to sink
     │                          │                        │
     │                          │                        │ ┌─────────────────┐
     │                          │                        │ │ Event Handler   │
     │                          │                        │ │ (Function/Pod)  │
     │                          │                        │ └────────┬────────┘
     │                          │                        │          │
     │                          │                        │   Call S/4 API
     │←─────────────────────────┼────────────────────────┼──────────┘
     │  GET /API_BUSINESS_PARTNER│                       │
     │  (Released API)           │                        │

Common S/4HANA Business Events

Event Type	Description	Use Case
`sap.s4.beh.businesspartner.changed.v1`	BP master data changed	Sync to CRM/MDM
`sap.s4.beh.businesspartner.created.v1`	New BP created	Trigger onboarding
`sap.s4.beh.salesorder.created.v1`	Sales order created	Fulfillment workflow
`sap.s4.beh.salesorder.changed.v1`	Sales order modified	Update downstream
`sap.s4.beh.purchaseorder.created.v1`	Purchase order created	Approval workflow
`sap.s4.beh.product.changed.v1`	Product master changed	Catalog sync

Event Payload (CloudEvents Format)

{
  "specversion": "1.0",
  "type": "sap.s4.beh.businesspartner.changed.v1",
  "source": "/default/sap.s4.beh/XXXXXXXXXX",
  "id": "ABY+LHK...",
  "time": "2024-03-15T14:30:00Z",
  "datacontenttype": "application/json",
  "data": {
    "BusinessPartner": "1000042"
  }
}

Important: S/4HANA events carry minimal data (usually just the key). You must call back to S/4HANA APIs to get the full entity data.

3. Extension Patterns

Pattern 1: Event-Driven Data Sync

Sync business partner changes from S/4HANA to an external CRM:

@Component
@ServiceName("EventProcessorService")
public class BPSyncHandler implements EventHandler {

    @Autowired
    private S4HanaClient s4Client;

    @Autowired
    private CrmClient crmClient;

    @On(event = "sap.s4.beh.businesspartner.changed.v1")
    public void onBPChanged(EventContext context) {
        String bpId = context.get("data").get("BusinessPartner").asText();

        // 1. Fetch full BP data from S/4HANA (Released API)
        BusinessPartner bp = s4Client.getBusinessPartner(bpId);

        // 2. Transform to CRM format
        CrmContact contact = CrmContact.builder()
            .externalId(bp.getBusinessPartner())
            .name(bp.getBusinessPartnerFullName())
            .email(bp.getEmailAddress())
            .build();

        // 3. Upsert in CRM
        crmClient.upsertContact(contact);

        log.info("Synced BP {} to CRM", bpId);
    }
}

Pattern 2: Validation Extension (Pre-Check via API)

Validate business rules before S/4HANA processing using a custom API:

Fiori App → Custom Validation API (Kyma) → S/4HANA API
                     │
                     ├── Check credit limit (external service)
                     ├── Check sanctions list
                     └── Return allow/deny

@On(event = CdsService.EVENT_CREATE, entity = "OrderValidation")
public void validateOrder(CdsCreateEventContext context) {
    CdsData order = context.getCqn().entries().get(0);

    String customerId = order.get("customerId").toString();
    BigDecimal amount = (BigDecimal) order.get("totalAmount");

    // External credit check
    CreditCheckResult credit = creditService.check(customerId, amount);
    if (!credit.isApproved()) {
        throw new ServiceException(ErrorStatuses.FORBIDDEN, 
            "Credit limit exceeded for customer " + customerId);
    }

    // Sanctions screening
    boolean sanctioned = sanctionsService.screen(customerId);
    if (sanctioned) {
        throw new ServiceException(ErrorStatuses.FORBIDDEN,
            "Customer is on sanctions list");
    }

    context.setResult(Map.of("approved", true, "creditScore", credit.getScore()));
}

Pattern 3: Notification Extension

Send notifications when key business events occur:

// Kyma Function: notify-on-large-order
module.exports = {
  main: async function (event, context) {
    const orderData = JSON.parse(event.data);
    const orderId = orderData.SalesOrder;

    // Fetch full order from S/4HANA
    const order = await fetchOrder(orderId);

    if (order.TotalNetAmount > 100000) {
      // Send Teams notification
      await sendTeamsNotification({
        title: `Large Order Created: ${orderId}`,
        text: `Customer: ${order.SoldToParty}\nAmount: ${order.TotalNetAmount} ${order.TransactionCurrency}`,
        urgency: "high"
      });

      // Send email to sales manager
      await sendEmail({
        to: order.SalesManagerEmail,
        subject: `Action Required: Large Order ${orderId}`,
        body: `A sales order exceeding 100K has been created...`
      });
    }

    return { statusCode: 200 };
  }
};

Pattern 4: Saga / Orchestration

Coordinate multiple services with compensation on failure:

Order Created Event
      │
      ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│ 1. Reserve       │───→│ 2. Process       │───→│ 3. Send          │
│    Inventory     │    │    Payment       │    │    Confirmation  │
│    (S/4HANA)     │    │    (Stripe)      │    │    (Email)       │
└────────┬────────┘    └────────┬────────┘    └─────────────────┘
         │ failure              │ failure
         ▼                      ▼
┌─────────────────┐    ┌─────────────────┐
│ Compensate:      │    │ Compensate:      │
│ Release inventory│    │ Release inventory│
│                  │    │ Refund payment   │
└─────────────────┘    └─────────────────┘

4. Resilience Patterns

Retry with Exponential Backoff

apiVersion: eventing.kyma-project.io/v1alpha2
kind: Subscription
metadata:
  name: bp-sync-sub
spec:
  source: ""
  types:
    - sap.s4.beh.businesspartner.changed.v1
  sink: http://bp-sync-service.my-app.svc.cluster.local
  config:
    maxInFlightMessages: "10"

In the handler, implement retry logic:

@Retryable(
    value = {S4HanaException.class, HttpTimeoutException.class},
    maxAttempts = 3,
    backoff = @Backoff(delay = 1000, multiplier = 2.0)
)
public BusinessPartner fetchBPWithRetry(String bpId) {
    return s4Client.getBusinessPartner(bpId);
}

Dead Letter Queue Pattern

module.exports = {
  main: async function (event, context) {
    try {
      await processEvent(event);
    } catch (error) {
      // After max retries, send to dead letter topic
      if (getRetryCount(event) >= MAX_RETRIES) {
        await publishToDeadLetter(event, error);
        return { statusCode: 200 }; // ACK to prevent redelivery
      }
      // Return error to trigger redelivery
      return { statusCode: 500, body: { error: error.message } };
    }
  }
};

Circuit Breaker

@CircuitBreaker(name = "s4hana", fallbackMethod = "s4Fallback")
public BusinessPartner getBusinessPartner(String id) {
    return s4HanaApi.getByKey(id);
}

public BusinessPartner s4Fallback(String id, Exception ex) {
    log.warn("S/4HANA circuit open, using cached data for BP {}", id);
    return cache.get("bp:" + id);
}

5. Event Processing Best Practices

Idempotency

Events may be delivered more than once. Always design idempotent handlers:

@On(event = "sap.s4.beh.businesspartner.changed.v1")
public void onBPChanged(EventContext context) {
    String eventId = context.get("id").asText();

    // Check if already processed
    if (eventStore.exists(eventId)) {
        log.info("Event {} already processed, skipping", eventId);
        return;
    }

    // Process event
    processBusinessPartnerChange(context);

    // Mark as processed
    eventStore.save(eventId);
}

Event Ordering

Events from the same source may arrive out of order. Use timestamps or version numbers:

public void syncBusinessPartner(BusinessPartner incoming) {
    BusinessPartner existing = repository.findById(incoming.getId());

    if (existing != null && existing.getLastChanged().isAfter(incoming.getLastChanged())) {
        log.warn("Stale event for BP {}, skipping", incoming.getId());
        return;
    }

    repository.save(incoming);
}

Top 5 Pitfalls

Treating events as commands. Events report what happened ("BP changed"), not what to do. Don't assume the event payload has all the data — call back to APIs for details.
Not implementing idempotency. Events can be delivered multiple times. Without idempotent handlers, you'll get duplicate processing.
Tight coupling to S/4HANA availability. If your event handler synchronously calls S/4HANA and it's down, you lose events. Use retry + DLQ patterns.
Ignoring event ordering. Two rapid changes to the same BP may arrive in reverse order. Use timestamps to detect stale events.
Building a monolithic extension. Split extensions by bounded context (one service for BP sync, another for order validation). Each should have its own subscriptions and lifecycle.

What to Learn Next

Lesson 1.3: Event Mesh — deep dive into messaging infrastructure
Lesson 2.1: Kyma Architecture — eventing module internals
Lesson 2.3: Serverless Functions — lightweight event handlers
Lesson 3.3: CAP Remote Services — calling S/4HANA APIs from CAP

Kyma Serverless Functions — When to Use & How to Build

Aliaksandr Tsviatkou — Thu, 26 Mar 2026 15:26:26 +0000

Lesson 2.3 — Kyma Serverless Functions

1. Functions vs Microservices: Decision Framework
2. Function CRD
3. Binding BTP Services to Functions
4. Event-Triggered Functions
5. Practical Patterns
Top 5 Pitfalls
What to Learn Next

Summary: Kyma Serverless Functions provide a lightweight, event-driven compute model for simple tasks — webhook handlers, data transformations, event processors — without the overhead of building Docker images and Helm charts. This lesson covers when to use functions vs microservices, the Function CRD, runtime environments, BTP service binding, and practical patterns.

1. Functions vs Microservices: Decision Framework

Criteria	Kyma Function	Java Microservice
Complexity	Simple logic (< 500 LOC)	Complex business logic
Language	Node.js, Python	Java, Node.js, Go, any
Startup time	~1-3s (cold start)	~15-60s (Spring Boot)
Dependencies	npm/pip packages only	Full Maven/Gradle ecosystem
Container control	None (managed)	Full Dockerfile control
Scaling	Auto (0 to N, scale-to-zero)	HPA (min 1 replica)
State	Stateless only	Stateless (can use external state)
Testing	Limited local testing	Full unit/integration testing
Debugging	Console logs only	Full IDE debugging
Best for	Event handlers, webhooks, glue code	Business services, APIs, CAP apps

Rule of thumb: If you'd write it as an AWS Lambda, write it as a Kyma Function. If you'd write it as an ECS service, write it as a Kyma microservice.

2. Function CRD

Basic Node.js Function

apiVersion: serverless.kyma-project.io/v1alpha2
kind: Function
metadata:
  name: order-validator
  namespace: my-app
spec:
  runtime: nodejs20
  source:
    inline:
      source: |
        module.exports = {
          main: async function (event, context) {
            const order = JSON.parse(event.data);

            // Validate order
            if (!order.customerId || !order.items?.length) {
              return { statusCode: 400, body: { error: "Invalid order" } };
            }

            // Check total
            const total = order.items.reduce((sum, item) => sum + item.price * item.qty, 0);

            return {
              statusCode: 200,
              body: { 
                valid: true, 
                orderId: order.id, 
                total: total 
              }
            };
          }
        };
      dependencies: |
        {
          "name": "order-validator",
          "version": "1.0.0",
          "dependencies": {}
        }
  scaleConfig:
    minReplicas: 0
    maxReplicas: 5
  resourceConfiguration:
    function:
      resources:
        requests:
          cpu: "50m"
          memory: "64Mi"
        limits:
          cpu: "200m"
          memory: "256Mi"

Python Function

apiVersion: serverless.kyma-project.io/v1alpha2
kind: Function
metadata:
  name: data-transformer
  namespace: my-app
spec:
  runtime: python312
  source:
    inline:
      source: |
        import json

        def main(event, context):
            data = json.loads(event["data"])

            # Transform S/4HANA BP format to internal format
            transformed = {
                "id": data.get("BusinessPartner"),
                "name": data.get("BusinessPartnerFullName"),
                "email": data.get("EmailAddress", "").lower(),
                "region": map_country_to_region(data.get("Country", ""))
            }

            return {"statusCode": 200, "body": json.dumps(transformed)}

        def map_country_to_region(country):
            regions = {"DE": "EMEA", "US": "NA", "JP": "APJ"}
            return regions.get(country, "UNKNOWN")
      dependencies: |
        requests==2.31.0

Git Source (Production Pattern)

For production, store function source in Git instead of inline:

apiVersion: serverless.kyma-project.io/v1alpha2
kind: Function
metadata:
  name: order-validator
spec:
  runtime: nodejs20
  source:
    gitRepository:
      url: "https://github.com/my-org/my-functions.git"
      baseDir: "/functions/order-validator"
      reference: "main"
      auth:
        type: key
        secretName: git-creds

3. Binding BTP Services to Functions

Using Environment Variables from Secrets

apiVersion: serverless.kyma-project.io/v1alpha2
kind: Function
metadata:
  name: bp-event-handler
spec:
  runtime: nodejs20
  source:
    inline:
      source: |
        const axios = require('axios');

        module.exports = {
          main: async function (event, context) {
            // Credentials from BTP service binding (mounted as env vars)
            const xsuaaUrl = process.env.XSUAA_URL;
            const clientId = process.env.XSUAA_CLIENTID;
            const clientSecret = process.env.XSUAA_CLIENTSECRET;

            // Get OAuth token
            const tokenResponse = await axios.post(
              `${xsuaaUrl}/oauth/token`,
              'grant_type=client_credentials',
              { auth: { username: clientId, password: clientSecret } }
            );

            // Call S/4HANA via destination
            const bpId = JSON.parse(event.data).BusinessPartner;
            // ... fetch full BP data

            return { statusCode: 200, body: { processed: bpId } };
          }
        };
      dependencies: |
        { "dependencies": { "axios": "^1.6.0" } }
  env:
    - name: XSUAA_URL
      valueFrom:
        secretKeyRef:
          name: my-xsuaa-secret
          key: url
    - name: XSUAA_CLIENTID
      valueFrom:
        secretKeyRef:
          name: my-xsuaa-secret
          key: clientid
    - name: XSUAA_CLIENTSECRET
      valueFrom:
        secretKeyRef:
          name: my-xsuaa-secret
          key: clientsecret

4. Event-Triggered Functions

Connecting a Function to Kyma Eventing

# Step 1: Deploy the function
apiVersion: serverless.kyma-project.io/v1alpha2
kind: Function
metadata:
  name: bp-event-processor
  namespace: my-app
spec:
  runtime: nodejs20
  source:
    inline:
      source: |
        module.exports = {
          main: async function (event, context) {
            console.log("Received CloudEvent:", JSON.stringify(event.extensions));
            console.log("Event data:", event.data);

            const bpId = JSON.parse(event.data).BusinessPartner;
            console.log(`Processing BP: ${bpId}`);

            // Your processing logic here

            return { statusCode: 200, body: { processed: true } };
          }
        };
---
# Step 2: Create subscription pointing to the function's service
apiVersion: eventing.kyma-project.io/v1alpha2
kind: Subscription
metadata:
  name: bp-changed-sub
  namespace: my-app
spec:
  source: ""
  types:
    - sap.s4.beh.businesspartner.changed.v1
  sink: http://bp-event-processor.my-app.svc.cluster.local
  config:
    maxInFlightMessages: "10"

HTTP-Triggered Functions (API Gateway)

# Expose function via APIRule
apiVersion: gateway.kyma-project.io/v1beta1
kind: APIRule
metadata:
  name: order-validator-api
  namespace: my-app
spec:
  host: order-validator.kyma.ondemand.com
  service:
    name: order-validator  # auto-created Service for the Function
    port: 80
  gateway: kyma-system/kyma-gateway
  rules:
    - path: /.*
      methods: ["POST"]
      accessStrategies:
        - handler: jwt
          config:
            jwks_urls:
              - "https://mysubaccount.authentication.eu10.hana.ondemand.com/token_keys"

5. Practical Patterns

Pattern: Event Router

Route different event types to different processing logic:

module.exports = {
  main: async function (event, context) {
    const eventType = event.extensions?.type || event.type;

    switch (eventType) {
      case 'sap.s4.beh.businesspartner.created.v1':
        return handleBPCreated(event);
      case 'sap.s4.beh.businesspartner.changed.v1':
        return handleBPChanged(event);
      default:
        console.warn(`Unknown event type: ${eventType}`);
        return { statusCode: 200, body: { skipped: true } };
    }
  }
};

Pattern: Webhook Adapter

Convert external webhook formats to CloudEvents for internal consumption:

const axios = require('axios');

module.exports = {
  main: async function (event, context) {
    // Receive Stripe webhook
    const stripeEvent = JSON.parse(event.data);

    // Transform to CloudEvent and publish to internal topic
    const cloudEvent = {
      specversion: "1.0",
      type: `my.company.payment.${stripeEvent.type}.v1`,
      source: "/stripe/webhook",
      id: stripeEvent.id,
      data: {
        amount: stripeEvent.data.object.amount,
        currency: stripeEvent.data.object.currency,
        customerId: stripeEvent.data.object.customer
      }
    };

    // Forward to NATS/Event Mesh
    await axios.post('http://eventing-publisher.eventing-system.svc.cluster.local/publish', cloudEvent);

    return { statusCode: 200 };
  }
};

Top 5 Pitfalls

Using functions for complex business logic. If your function exceeds ~300 LOC or needs multiple modules, switch to a microservice.
Ignoring cold start latency. Scale-to-zero means the first request after idle will be slow (~2-5s). Set minReplicas: 1 for latency-sensitive endpoints.
Not testing locally. Kyma functions are hard to test locally. Extract core logic into testable modules and import them.
Storing state in function memory. Functions can scale to zero and back. Use external storage (Redis, HANA) for any state.
Inline source in production. Use Git source for version control, code review, and CI/CD integration.

What to Learn Next

Lesson 2.1: Kyma Architecture — understanding the serverless module
Lesson 2.4: Kyma Eventing — event-driven extension patterns
Lesson 1.3: Event Mesh — the messaging backbone for functions

Deploying Java Microservices on SAP Kyma — Helm, Docker & BTP Services

Aliaksandr Tsviatkou — Thu, 26 Mar 2026 15:26:21 +0000

Lesson 2.2 — Deploying Java Microservices on Kyma

1. Containerizing a Spring Boot / CAP Java Application
2. Helm Chart Structure
3. Service Credential Consumption
4. Health Probes and Graceful Shutdown
5. Deployment Commands
Top 5 Pitfalls
What to Learn Next

Summary: Deploying Java applications on Kyma requires Docker containerization, Helm chart packaging, BTP service binding via the BTP Operator, and production-hardening with health probes, resource limits, and HPA. This lesson walks through the full deployment lifecycle — from Dockerfile to production-ready Helm chart — with comparisons to Cloud Foundry deployment patterns.

1. Containerizing a Spring Boot / CAP Java Application

Dockerfile (Multi-Stage Build)

# Stage 1: Build
FROM maven:3.9-eclipse-temurin-17 AS builder
WORKDIR /app
COPY pom.xml .
COPY srv/ srv/
COPY db/ db/
RUN mvn clean package -DskipTests -B

# Stage 2: Runtime
FROM eclipse-temurin:17-jre-alpine
WORKDIR /app

# Security: run as non-root
RUN addgroup -S appgroup && adduser -S appuser -G appgroup
USER appuser

COPY --from=builder /app/srv/target/*.jar app.jar

EXPOSE 8080
ENV JAVA_OPTS="-XX:MaxRAMPercentage=75.0 -XX:+UseG1GC"

ENTRYPOINT ["sh", "-c", "java $JAVA_OPTS -jar app.jar"]

Key Differences from Cloud Foundry

Aspect	Cloud Foundry	Kyma
Container	Buildpack creates it for you	You write the Dockerfile
Base image	SAP JVM / SapMachine (in buildpack)	Your choice (Temurin, SapMachine, etc.)
Memory tuning	CF sets `-Xmx` from memory quota	You set via `JAVA_OPTS` and K8s resource limits
Service credentials	`VCAP_SERVICES` env var	Mounted K8s Secrets (files or env vars)
Port binding	`$PORT` env var (assigned by CF)	You control (typically 8080)

Building and Pushing the Image

# Build the image
docker build -t my-registry.example.com/my-app:1.0.0 .

# Push to container registry (SAP BTP uses your own registry)
docker push my-registry.example.com/my-app:1.0.0

2. Helm Chart Structure

my-app-chart/
├── Chart.yaml
├── values.yaml
├── templates/
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── apirule.yaml
│   ├── service-instance.yaml    # BTP ServiceInstance
│   ├── service-binding.yaml     # BTP ServiceBinding
│   ├── hpa.yaml
│   └── _helpers.tpl

Chart.yaml

apiVersion: v2
name: my-java-app
description: SAP BTP Java microservice on Kyma
type: application
version: 1.0.0
appVersion: "1.0.0"

values.yaml

replicaCount: 2

image:
  repository: my-registry.example.com/my-app
  tag: "1.0.0"
  pullPolicy: IfNotPresent

imagePullSecrets:
  - name: registry-secret

service:
  port: 8080

resources:
  requests:
    memory: "512Mi"
    cpu: "250m"
  limits:
    memory: "1Gi"
    cpu: "1000m"

autoscaling:
  enabled: true
  minReplicas: 2
  maxReplicas: 10
  targetCPUUtilization: 70

xsuaa:
  serviceOfferingName: xsuaa
  servicePlanName: application
  parameters:
    xsappname: my-app
    tenant-mode: dedicated

hana:
  serviceOfferingName: hana
  servicePlanName: hdi-shared

apiRule:
  host: my-app

Deployment Template

# templates/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "my-java-app.fullname" . }}
  labels:
    {{- include "my-java-app.labels" . | nindent 4 }}
spec:
  replicas: {{ .Values.replicaCount }}
  selector:
    matchLabels:
      {{- include "my-java-app.selectorLabels" . | nindent 6 }}
  template:
    metadata:
      labels:
        {{- include "my-java-app.selectorLabels" . | nindent 8 }}
    spec:
      {{- with .Values.imagePullSecrets }}
      imagePullSecrets:
        {{- toYaml . | nindent 8 }}
      {{- end }}
      containers:
        - name: {{ .Chart.Name }}
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
          imagePullPolicy: {{ .Values.image.pullPolicy }}
          ports:
            - containerPort: {{ .Values.service.port }}
              protocol: TCP
          env:
            - name: SPRING_PROFILES_ACTIVE
              value: "cloud"
          volumeMounts:
            - name: xsuaa-secret
              mountPath: /etc/secrets/sapcp/xsuaa/my-xsuaa
              readOnly: true
            - name: hana-secret
              mountPath: /etc/secrets/sapcp/hana/my-hana
              readOnly: true
          resources:
            {{- toYaml .Values.resources | nindent 12 }}
          livenessProbe:
            httpGet:
              path: /actuator/health/liveness
              port: {{ .Values.service.port }}
            initialDelaySeconds: 30
            periodSeconds: 10
            failureThreshold: 3
          readinessProbe:
            httpGet:
              path: /actuator/health/readiness
              port: {{ .Values.service.port }}
            initialDelaySeconds: 20
            periodSeconds: 5
            failureThreshold: 3
          startupProbe:
            httpGet:
              path: /actuator/health/liveness
              port: {{ .Values.service.port }}
            initialDelaySeconds: 10
            periodSeconds: 5
            failureThreshold: 30  # 10s + 30*5s = up to 160s startup time
      volumes:
        - name: xsuaa-secret
          secret:
            secretName: my-xsuaa-secret
        - name: hana-secret
          secret:
            secretName: my-hana-secret

BTP Service Binding Templates

# templates/service-instance.yaml
apiVersion: services.cloud.sap.com/v1
kind: ServiceInstance
metadata:
  name: my-xsuaa
spec:
  serviceOfferingName: {{ .Values.xsuaa.serviceOfferingName }}
  servicePlanName: {{ .Values.xsuaa.servicePlanName }}
  parameters:
    {{- toYaml .Values.xsuaa.parameters | nindent 4 }}
---
apiVersion: services.cloud.sap.com/v1
kind: ServiceBinding
metadata:
  name: my-xsuaa-binding
spec:
  serviceInstanceName: my-xsuaa
  secretName: my-xsuaa-secret

3. Service Credential Consumption

SAP BTP Credential Mounting Convention

SAP libraries (Cloud SDK, spring-xsuaa, CAP) expect credentials at:

/etc/secrets/sapcp/<service-name>/<instance-name>/

The mounted secret files contain JSON credentials. Example file tree:

/etc/secrets/sapcp/xsuaa/my-xsuaa/
├── clientid
├── clientsecret
├── url
├── xsappname
└── ...  (one file per credential key)

Spring Boot Configuration for Kyma

# application-cloud.yaml (activated by SPRING_PROFILES_ACTIVE=cloud)
sap:
  cloud:
    security:
      xsuaa:
        credential-type: binding-secret

CAP Java automatically discovers credentials from mounted secrets when running on Kyma.

4. Health Probes and Graceful Shutdown

Spring Boot Actuator Configuration

# application.yaml
management:
  endpoints:
    web:
      exposure:
        include: health,info,prometheus
  endpoint:
    health:
      probes:
        enabled: true
      show-details: always
  health:
    livenessstate:
      enabled: true
    readinessstate:
      enabled: true

server:
  shutdown: graceful

spring:
  lifecycle:
    timeout-per-shutdown-phase: 30s

Graceful Shutdown Flow

1. K8s sends SIGTERM to container
2. K8s removes pod from Service endpoints (no new traffic)
3. Spring Boot stops accepting new requests
4. Spring Boot waits for in-flight requests (up to 30s)
5. Spring Boot closes connections and shuts down
6. K8s waits for terminationGracePeriodSeconds (default 30s)
7. If still running, K8s sends SIGKILL

# In deployment spec
spec:
  terminationGracePeriodSeconds: 45  # > spring shutdown timeout

5. Deployment Commands

# Create namespace with Istio injection
kubectl create namespace my-app
kubectl label namespace my-app istio-injection=enabled

# Create image pull secret
kubectl create secret docker-registry registry-secret \
  --docker-server=my-registry.example.com \
  --docker-username=user \
  --docker-password=password \
  --namespace my-app

# Deploy with Helm
helm install my-app ./my-app-chart \
  --namespace my-app \
  --set image.tag=1.0.0

# Upgrade
helm upgrade my-app ./my-app-chart \
  --namespace my-app \
  --set image.tag=1.1.0

# Check status
kubectl get pods -n my-app
kubectl get servicebindings -n my-app
kubectl get apirules -n my-app

Top 5 Pitfalls

Running as root in containers. Always create a non-root user in your Dockerfile. Kyma may enforce PodSecurityPolicies.
Not setting -XX:MaxRAMPercentage. Without it, the JVM may try to use more memory than the container limit, causing OOMKill.
Missing startup probes for Java apps. Spring Boot can take 30-60s to start. Without startup probes, K8s kills the pod thinking it's unhealthy.
Hardcoding secrets in values.yaml. Use sealed secrets, external secrets operator, or pass secrets via --set at deploy time.
Forgetting Istio sidecar memory overhead. Each pod gets an Envoy proxy (~50-100MB). Factor this into resource requests.

What to Learn Next

Lesson 2.1: Kyma Architecture — understanding the platform components
Lesson 2.3: Kyma Serverless Functions — lightweight alternatives to microservices
Lesson 4.1: CI/CD — automating Docker builds and Helm deployments
Lesson 4.2: Observability — Prometheus metrics, distributed tracing on Kyma

Kyma Runtime Architecture — Kubernetes + Istio + SAP Eventing

Aliaksandr Tsviatkou — Thu, 26 Mar 2026 15:26:18 +0000

Lesson 2.1 — Kyma Architecture & Core Components

1. Kyma vs Vanilla Kubernetes
2. Kyma Cluster Architecture
3. Istio Service Mesh in Kyma
4. Kyma API Gateway
5. Kyma Eventing
Top 5 Pitfalls
What to Learn Next

Summary: SAP Kyma Runtime is a managed Kubernetes offering on BTP that adds an opinionated layer of components — Istio service mesh, NATS-based eventing, API Gateway, and the BTP Operator — on top of a standard K8s cluster. This lesson covers what Kyma adds versus vanilla Kubernetes, the modular architecture, Istio internals, API Gateway configuration, and eventing infrastructure.

1. Kyma vs Vanilla Kubernetes

What Kyma Adds

┌──────────────────────────────────────────────────────────┐
│                    Kyma Runtime                           │
│                                                          │
│  ┌────────────────────────────────────────────────────┐  │
│  │  SAP-Managed Layer                                  │  │
│  │  ┌──────────┐ ┌──────────┐ ┌───────────────────┐   │  │
│  │  │ Istio    │ │ Kyma API │ │ BTP Operator      │   │  │
│  │  │ Service  │ │ Gateway  │ │ (ServiceInstance/  │   │  │
│  │  │ Mesh     │ │ (APIRule)│ │  ServiceBinding)   │   │  │
│  │  └──────────┘ └──────────┘ └───────────────────┘   │  │
│  │  ┌──────────┐ ┌──────────┐ ┌───────────────────┐   │  │
│  │  │ NATS     │ │ Serverless│ │ Lifecycle Manager │   │  │
│  │  │ Eventing │ │ Functions │ │ (module install)  │   │  │
│  │  └──────────┘ └──────────┘ └───────────────────┘   │  │
│  └────────────────────────────────────────────────────┘  │
│                                                          │
│  ┌────────────────────────────────────────────────────┐  │
│  │  Standard Kubernetes                                │  │
│  │  Pods, Deployments, Services, ConfigMaps, Secrets   │  │
│  │  Namespaces, RBAC, HPA, PDB, Ingress               │  │
│  └────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────┘

Component	Vanilla K8s	Kyma
Service mesh	Install Istio yourself	Pre-installed, SAP-managed Istio
API Gateway	Ingress controller (nginx, etc.)	APIRule CRD → Istio VirtualService + Oathkeeper
Eventing	Install NATS/Kafka yourself	Kyma Eventing (NATS or Event Mesh backend)
BTP services	Manual credential management	BTP Operator: ServiceInstance/ServiceBinding CRDs
Serverless	Install Knative/OpenFaaS	Kyma Functions (Node.js, Python)
Certificate mgmt	cert-manager manual setup	Integrated cert management
DNS	External-DNS manual setup	Managed DNS for *.kyma.ondemand.com

Kyma Modules System

Kyma uses a modular installation model. Modules are optional components enabled via the Kyma CR:

apiVersion: operator.kyma-project.io/v1beta2
kind: Kyma
metadata:
  name: default
  namespace: kyma-system
spec:
  modules:
    - name: istio
    - name: api-gateway
    - name: eventing
    - name: btp-operator
    - name: serverless       # optional
    - name: telemetry        # optional

You can enable/disable modules without affecting the core cluster.

2. Kyma Cluster Architecture

System Namespaces

kyma-system/          — Kyma core components, lifecycle manager
istio-system/         — Istio control plane (istiod, gateways)
eventing-system/      — NATS server, eventing controller
serverless-system/    — Serverless function controller
btp-operator/         — BTP Operator controller
kube-system/          — Standard K8s system components

Rule: Never deploy your workloads into system namespaces. Create dedicated namespaces for your applications.

BTP Operator for Service Consumption

The BTP Operator lets you manage BTP service instances and bindings as Kubernetes resources:

# Create a service instance
apiVersion: services.cloud.sap.com/v1
kind: ServiceInstance
metadata:
  name: my-xsuaa
  namespace: my-app
spec:
  serviceOfferingName: xsuaa
  servicePlanName: application
  parameters:
    xsappname: my-app
    tenant-mode: dedicated
    oauth2-configuration:
      redirect-uris:
        - "https://my-app.kyma.ondemand.com/**"
---
# Create a binding (generates K8s Secret)
apiVersion: services.cloud.sap.com/v1
kind: ServiceBinding
metadata:
  name: my-xsuaa-binding
  namespace: my-app
spec:
  serviceInstanceName: my-xsuaa
  secretName: my-xsuaa-secret

The BTP Operator communicates with the BTP Service Manager API to provision/bind services and stores credentials in Kubernetes Secrets.

3. Istio Service Mesh in Kyma

Sidecar Injection

Istio injects an Envoy proxy sidecar into every pod in labeled namespaces:

apiVersion: v1
kind: Namespace
metadata:
  name: my-app
  labels:
    istio-injection: enabled  # enables automatic sidecar injection

Each pod gets two containers:

Pod: my-service-abc123
├── my-service (your Java app, port 8080)
└── istio-proxy (Envoy sidecar, intercepts all traffic)

Mutual TLS (mTLS)

Istio enables automatic mTLS between all pods in the mesh:

Pod A (my-service)          Pod B (other-service)
┌─────────────────┐        ┌─────────────────┐
│ App container    │        │ App container    │
│ (plain HTTP)     │        │ (plain HTTP)     │
│       │          │        │       ▲          │
│       ▼          │        │       │          │
│ Envoy sidecar ───┼──mTLS──┼─→ Envoy sidecar │
│ (encrypts)       │        │ (decrypts)       │
└─────────────────┘        └─────────────────┘

Your application code uses plain HTTP; Istio handles encryption transparently.

Traffic Management

# VirtualService for traffic splitting (canary deployment)
apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: my-service
spec:
  hosts:
    - my-service
  http:
    - route:
        - destination:
            host: my-service
            subset: v1
          weight: 90
        - destination:
            host: my-service
            subset: v2
          weight: 10
---
apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: my-service
spec:
  host: my-service
  subsets:
    - name: v1
      labels:
        version: v1
    - name: v2
      labels:
        version: v2

4. Kyma API Gateway

APIRule CRD

The APIRule is Kyma's abstraction for exposing services externally with authentication:

apiVersion: gateway.kyma-project.io/v1beta1
kind: APIRule
metadata:
  name: my-service-api
  namespace: my-app
spec:
  host: my-service.kyma.ondemand.com
  service:
    name: my-service
    port: 8080
  gateway: kyma-system/kyma-gateway
  rules:
    # Public endpoint (no auth)
    - path: /health
      methods: ["GET"]
      accessStrategies:
        - handler: noop
    # JWT-protected endpoint
    - path: /api/.*
      methods: ["GET", "POST", "PUT", "DELETE"]
      accessStrategies:
        - handler: jwt
          config:
            jwks_urls:
              - "https://mysubaccount.authentication.eu10.hana.ondemand.com/token_keys"
            trusted_issuers:
              - "https://mysubaccount.authentication.eu10.hana.ondemand.com"

Under the hood, APIRule creates:

An Istio VirtualService for routing
An Ory Oathkeeper Rule for authentication/authorization

CORS Configuration

spec:
  corsPolicy:
    allowOrigins:
      - exact: "https://my-frontend.example.com"
    allowMethods: ["GET", "POST", "PUT", "DELETE", "OPTIONS"]
    allowHeaders: ["Authorization", "Content-Type"]
    allowCredentials: true

5. Kyma Eventing

NATS vs Event Mesh Backend

Kyma Eventing supports two backends:

Feature	NATS (default)	Event Mesh
Deployment	In-cluster NATS server	BTP managed service
Durability	In-memory (limited)	Persistent queues
S/4HANA integration	Via Event Mesh bridge	Native
Scale	Single cluster	Cross-region
Cost	Included in Kyma	Additional BTP service cost

Subscription CRD

apiVersion: eventing.kyma-project.io/v1alpha2
kind: Subscription
metadata:
  name: bp-changed-sub
  namespace: my-app
spec:
  source: ""
  types:
    - sap.s4.beh.businesspartner.changed.v1
  sink: http://my-service.my-app.svc.cluster.local:8080/events
  config:
    maxInFlightMessages: "10"

The eventing controller ensures events matching the specified types are delivered to the sink URL via HTTP POST with CloudEvents format.

Event Type Versioning

Follow the SAP naming convention:

<prefix>.<domain>.<business-object>.<operation>.v<version>

Examples:
sap.s4.beh.businesspartner.changed.v1
my.company.order.validated.v1
my.company.order.validated.v2  # new version with breaking changes

Top 5 Pitfalls

Forgetting istio-injection: enabled label on namespaces. Without it, pods don't get sidecars and miss mTLS, traffic management, and observability.
Using Ingress instead of APIRule. Kyma's API Gateway (APIRule) integrates with Istio and Oathkeeper. Standard K8s Ingress won't work correctly on Kyma.
Not configuring resource requests/limits. Istio sidecars add ~50MB memory per pod. Account for this in your resource planning.
Assuming NATS eventing is durable. Default NATS backend is in-memory. For production event-driven architectures, use Event Mesh backend.
Deploying into system namespaces. Kyma upgrades may overwrite your resources. Always use dedicated namespaces.

What to Learn Next

Lesson 2.2: Deploying Java Microservices on Kyma — Dockerfiles, Helm charts, service bindings
Lesson 2.3: Kyma Serverless Functions — when and how to use them
Lesson 2.4: Kyma Eventing & Extension Patterns — S/4HANA side-by-side extensions
Lesson 1.1: BTP Architecture — how Kyma fits in the BTP landscape

SAP BTP Multi-Tenancy — SaaS Architecture for Java Developers

Aliaksandr Tsviatkou — Thu, 26 Mar 2026 15:26:15 +0000

Lesson 1.4 — BTP Multi-Tenancy

1. BTP Multi-Tenancy Model
2. Tenant Isolation Patterns
3. XSUAA in Multi-Tenant Context
4. CAP Multi-Tenancy Support (@sap/cds-mtxs)
5. Operational Concerns
Top 5 Pitfalls
What to Learn Next

Summary: Multi-tenancy on SAP BTP enables building SaaS applications where a single deployment serves multiple customers (tenants) with data isolation, independent configuration, and per-tenant extensibility. This lesson covers the BTP multi-tenancy lifecycle, tenant isolation patterns, XSUAA identity zones, CAP's MTX framework, and operational concerns — compared with Spring Boot / Hibernate multi-tenancy patterns.

1. BTP Multi-Tenancy Model

Core Concept

In BTP's multi-tenancy model, your application is deployed once in a provider subaccount, and customer organizations subscribe from their own subaccounts:

┌─────────────────────────────────┐
│     Provider Subaccount          │
│     (your SaaS app deployed)     │
│                                  │
│  ┌────────────────────────────┐  │
│  │  App Instance (shared)     │  │
│  │  - Single CF app / K8s pod │  │
│  │  - Shared code, shared URL │  │
│  └────────────────────────────┘  │
└──────────┬───────────────────────┘
           │ subscriptions
     ┌─────┼──────────────┐
     │     │              │
     ▼     ▼              ▼
┌────────┐ ┌────────┐ ┌────────┐
│Tenant A│ │Tenant B│ │Tenant C│
│(sub-   │ │(sub-   │ │(sub-   │
│account)│ │account)│ │account)│
│        │ │        │ │        │
│ Own HDI│ │ Own HDI│ │ Own HDI│
│ Own IDP│ │ Own IDP│ │ Own IDP│
└────────┘ └────────┘ └────────┘

SaaS Provisioning Service (saas-registry)

The saas-registry service manages the tenant subscription lifecycle:

{
  "xsappname": "my-saas-app",
  "appUrls": {
    "onSubscription": "https://my-saas-app-srv.cfapps.eu10.hana.ondemand.com/mt/v1.0/subscriptions/tenants/{tenantId}",
    "getDependencies": "https://my-saas-app-srv.cfapps.eu10.hana.ondemand.com/mt/v1.0/subscriptions/dependencies"
  }
}

Subscription Lifecycle

Tenant Admin                SaaS Registry           Your App (callback)        HANA Cloud
     │                           │                        │                       │
     │ Subscribe to app          │                        │                       │
     │──────────────────────────→│                        │                       │
     │                           │ PUT /subscriptions/    │                       │
     │                           │     tenants/{tenantId} │                       │
     │                           │───────────────────────→│                       │
     │                           │                        │                       │
     │                           │                        │ Create HDI container  │
     │                           │                        │──────────────────────→│
     │                           │                        │      OK              │
     │                           │                        │←─────────────────────│
     │                           │                        │                       │
     │                           │                        │ Deploy schema         │
     │                           │                        │──────────────────────→│
     │                           │                        │      OK              │
     │                           │                        │←─────────────────────│
     │                           │                        │                       │
     │                           │  200 OK + app URL      │                       │
     │                           │←──────────────────────│                       │
     │  App available at         │                        │                       │
     │  tenant-a.my-app.com      │                        │                       │
     │←─────────────────────────│                        │                       │

2. Tenant Isolation Patterns

Schema-Per-Tenant (HDI Containers)

This is the default and recommended pattern on BTP:

HANA Cloud Instance
├── HDI Container (Tenant A) → Schema: TENANT_A_HDI
│   ├── Table: BOOKS
│   └── Table: AUTHORS
├── HDI Container (Tenant B) → Schema: TENANT_B_HDI
│   ├── Table: BOOKS
│   └── Table: AUTHORS
└── HDI Container (Tenant C) → Schema: TENANT_C_HDI
    ├── Table: BOOKS
    └── Table: AUTHORS

Pros:

Complete data isolation at the database level
Tenants cannot accidentally access each other's data
Independent schema evolution per tenant (for extensibility)
GDPR compliance: delete tenant = drop HDI container

Cons:

Resource overhead: each container has metadata tables
Schema upgrades must propagate to all containers
Cross-tenant queries impossible (by design)
HANA Cloud connection limits may become a bottleneck

Shared-Schema with Discriminator Column

All tenants share the same tables, distinguished by a tenant_id column:

CREATE TABLE books (
    id UUID PRIMARY KEY,
    tenant_id VARCHAR(36) NOT NULL,  -- discriminator
    title VARCHAR(200),
    price DECIMAL(10,2)
);

-- Every query MUST include tenant_id filter
SELECT * FROM books WHERE tenant_id = 'tenant-a-guid' AND price > 10;

Pros:

Lower resource overhead
Simpler deployment (single schema)
Cross-tenant analytics possible (with proper authorization)

Cons:

Risk of data leakage if tenant filter is missing
No database-level isolation
Complex GDPR data deletion
CAP does not support this pattern natively

Comparison with Spring Boot / Hibernate

Aspect	Spring Boot + Hibernate	CAP on BTP
Schema-per-tenant	`MultiTenantConnectionProvider` + `CurrentTenantIdentifierResolver`	Built-in via `@sap/cds-mtxs`
Shared schema	`@TenantId` column + Hibernate filters	Not natively supported
Tenant resolution	Custom filter / interceptor	Automatic from JWT `zid` claim
Schema migration	Flyway per-tenant loop	HDI deployer per-container
Tenant provisioning	Custom code	`saas-registry` callbacks

3. XSUAA in Multi-Tenant Context

Tenant Resolution via Subdomain

The approuter resolves the tenant from the URL subdomain:

https://tenant-a.my-saas-app.cfapps.eu10.hana.ondemand.com
         ^^^^^^^^
         subdomain → maps to tenant identity zone

The approuter:

Extracts subdomain from the request URL
Resolves it to an XSUAA identity zone
Redirects the user to the tenant-specific XSUAA for authentication
Receives a JWT with the tenant's zid (zone ID) claim

JWT Tenant Claims

{
  "zid": "tenant-a-zone-guid",
  "ext_attr": {
    "subaccountid": "tenant-a-subaccount-guid",
    "zdn": "tenant-a"
  },
  "iss": "https://tenant-a.authentication.eu10.hana.ondemand.com/oauth/token",
  "scope": ["my-saas-app!t12345.Viewer"],
  "client_id": "sb-my-saas-app!t12345"
}

The zid claim is used by CAP to route database queries to the correct HDI container.

xs-security.json for Multi-Tenancy

{
  "xsappname": "my-saas-app",
  "tenant-mode": "shared",
  "scopes": [
    { "name": "$XSAPPNAME.Viewer", "description": "View data" },
    { "name": "$XSAPPNAME.Admin", "description": "Administer" },
    { "name": "$XSAPPNAME.mtcallback", "description": "MT callback", "grant-as-authority-to-same-serviceplan": ["application"] }
  ],
  "role-templates": [
    { "name": "Viewer", "scope-references": ["$XSAPPNAME.Viewer"] },
    { "name": "Admin", "scope-references": ["$XSAPPNAME.Admin", "$XSAPPNAME.Viewer"] }
  ]
}

Note "tenant-mode": "shared" — this enables multi-tenant operation. The mtcallback scope allows the saas-registry to call your onSubscription endpoint.

4. CAP Multi-Tenancy Support (@sap/cds-mtxs)

Architecture

CAP provides the @sap/cds-mtxs module (MTX Sidecar) that handles:

Tenant provisioning (HDI container creation)
Schema deployment per tenant
Schema upgrade propagation
Tenant extensibility (custom CDS extensions per tenant)

┌─────────────────────────────────────────────┐
│              CAP Application                 │
│                                             │
│  ┌─────────────────┐  ┌─────────────────┐  │
│  │  Java Backend    │  │  MTX Sidecar    │  │
│  │  (CAP Java)      │  │  (Node.js)      │  │
│  │                  │  │                  │  │
│  │  - CDS services  │  │  - /mt/v1.0/... │  │
│  │  - Event handlers│  │  - HDI deployer  │  │
│  │  - OData/REST    │  │  - Extension mgr │  │
│  │                  │  │  - Schema upgrade│  │
│  └────────┬─────────┘  └────────┬─────────┘  │
│           │                      │            │
│           └──────────┬───────────┘            │
│                      │                        │
│               Service Bindings                │
│  (XSUAA, saas-registry, service-manager)      │
└──────────────────────┬────────────────────────┘
                       │
              ┌────────┴────────┐
              │  HANA Cloud      │
              │  ┌──────┐       │
              │  │HDI-A │       │
              │  │HDI-B │       │
              │  │HDI-C │       │
              │  └──────┘       │
              └─────────────────┘

Sidecar Configuration

// package.json (MTX sidecar)
{
  "cds": {
    "requires": {
      "multitenancy": true,
      "extensibility": true,
      "toggles": true
    },
    "mtx": {
      "element-prefix": ["Z_", "MY_"],
      "namespace-blocklist": ["com.sap.", "sap."]
    }
  }
}

Schema Upgrade Propagation

When you deploy a new version of your CDS model, the MTX sidecar must upgrade all tenant schemas:

# Trigger upgrade for all tenants
cds-mtx upgrade --all

# Or via REST API
POST /mtx/v1/model/upgrade
{
  "tenants": ["*"]  // all tenants
}

The sidecar iterates through all subscribed tenants, deploys the new schema to each HDI container, and handles migration. This is atomic per tenant — if one tenant's upgrade fails, others are not affected.

5. Operational Concerns

Tenant-Aware Logging

import org.slf4j.MDC;

@Before(event = "*")
public void addTenantToMDC(EventContext ctx) {
    String tenantId = ctx.getUserInfo().getTenant();
    MDC.put("tenant_id", tenantId);
}

Logback pattern:

<pattern>%d{ISO8601} [%thread] %-5level [tenant=%X{tenant_id}] %logger{36} - %msg%n</pattern>

Noisy-Neighbor Detection

Monitor per-tenant resource consumption:

-- Per-tenant HDI container memory usage
SELECT SCHEMA_NAME,
       ROUND(SUM(MEMORY_SIZE_IN_TOTAL) / 1024 / 1024, 2) AS total_mb,
       SUM(RECORD_COUNT) AS total_records
FROM M_CS_TABLES
GROUP BY SCHEMA_NAME
ORDER BY total_mb DESC;

GDPR: Tenant Data Deletion

With schema-per-tenant, GDPR "right to erasure" is straightforward:

# Unsubscribe tenant → triggers onSubscription DELETE callback
# MTX sidecar drops the HDI container
DELETE /mt/v1.0/subscriptions/tenants/{tenantId}

This physically removes all tenant data, making compliance verification simple.

Connection Pool Considerations

Each tenant's HDI container requires database connections. With 100 tenants and a pool size of 5 per tenant, you need 500 connections:

# application.yaml
spring:
  datasource:
    hikari:
      maximum-pool-size: 5        # per tenant
      minimum-idle: 1             # keep connections warm
      idle-timeout: 300000        # 5 minutes
      connection-timeout: 30000   # 30 seconds

Pitfall: HANA Cloud has connection limits per instance size. Monitor M_CONNECTIONS and size your HANA instance accordingly.

Top 5 Pitfalls

Forgetting tenant-mode: shared in xs-security.json. Without this, XSUAA creates a dedicated (single-tenant) service instance.
Not testing schema upgrades with multiple tenants. A CDS model change that works for new tenants may fail on existing tenants with data.
Ignoring connection pool sizing. More tenants = more HDI containers = more connections needed. Plan HANA instance sizing early.
Missing the MTX sidecar in deployment. The Java backend alone cannot handle tenant provisioning — the Node.js sidecar is required.
Not implementing tenant-aware logging from day one. Without tenant context in logs, debugging production issues across tenants is nearly impossible.

What to Learn Next

Lesson 1.1: BTP Architecture — subaccount hierarchy and entitlements
Lesson 1.2: HANA Cloud — HDI container internals
Lesson 3.2: CAP Security — authorization in multi-tenant context
Lesson 3.4: CAP Advanced Patterns — deployment topologies for MTX
SAP BTP Multi-Tenancy documentation

SAP BTP Event Mesh & Integration — Event-Driven Architecture

Aliaksandr Tsviatkou — Thu, 26 Mar 2026 15:26:12 +0000

Lesson 1.3 — BTP Event Mesh & Integration

1. SAP Event Mesh Architecture
2. CloudEvents Specification
3. Enterprise Messaging Patterns
4. Integration Suite vs Event Mesh
5. Implementing an Event-Driven CAP Java Microservice
Top 5 Pitfalls
What to Learn Next

Summary: Event-driven architecture on SAP BTP centers on SAP Event Mesh — a fully managed messaging service that implements the CloudEvents specification and integrates natively with S/4HANA business events. This lesson covers Event Mesh internals, messaging patterns, comparison with Kafka/RabbitMQ, SAP Integration Suite positioning, and a hands-on implementation of an event-driven CAP Java microservice.

1. SAP Event Mesh Architecture

Overview

SAP Event Mesh is a multi-protocol message broker built on top of SAP's messaging infrastructure. It supports AMQP 1.0, MQTT 3.1.1, and HTTP (REST) protocols.

┌──────────────────────────────────────────────────────────┐
│                    SAP Event Mesh                         │
│                                                          │
│  ┌──────────────────────────────────────────────────┐    │
│  │              Message Broker Cluster                │    │
│  │                                                    │    │
│  │  ┌─────────┐   ┌─────────┐   ┌─────────┐        │    │
│  │  │ Queue A │   │ Queue B │   │ Queue C │  ...    │    │
│  │  └────┬────┘   └────┬────┘   └────┬────┘        │    │
│  │       │              │              │             │    │
│  │  Topic Subscriptions (pattern matching)           │    │
│  │  sap/s4/beh/businesspartner/changed/v1           │    │
│  │  sap/s4/beh/salesorder/created/v1                │    │
│  │  my/app/custom/event/v1                          │    │
│  └──────────────────────────────────────────────────┘    │
│                                                          │
│  Protocols: AMQP 1.0 | MQTT 3.1.1 | HTTP/REST           │
│  Format: CloudEvents 1.0                                 │
└──────────────────────────────────────────────────────────┘

Queues vs Topic Subscriptions

Event Mesh uses a topic-based publish/subscribe model with queue-based consumption:

Topics are hierarchical strings (e.g., sap/s4/beh/businesspartner/changed/v1). Publishers send messages to topics.
Queues are durable message stores. Consumers read from queues.
Topic subscriptions bind a queue to one or more topic patterns. A queue receives all messages matching its subscribed topics.

Publisher → Topic: sap/s4/beh/salesorder/created/v1
                    │
                    ├──→ Queue "order-processor" (subscribed: sap/s4/beh/salesorder/*)
                    │         → Consumer A (microservice)
                    │
                    └──→ Queue "audit-logger" (subscribed: sap/s4/beh/+/+/v1)
                              → Consumer B (audit service)

Topic patterns support:

* — matches one segment (e.g., sap/s4/beh/*/created/v1)
> — matches one or more segments at the end (e.g., sap/s4/beh/>)

QoS Levels

QoS	Meaning	Use Case
0 (At most once)	Fire and forget, no ack	Telemetry, metrics
1 (At least once)	Delivered at least once, may duplicate	Business events (default for S/4HANA events)
2 (Exactly once)	Not supported by Event Mesh	—

Critical: Event Mesh provides at-least-once delivery. Your consumers must be idempotent. Design handlers to safely process the same event multiple times.

Webhook Registration

For services that cannot maintain persistent connections (e.g., serverless), Event Mesh supports webhook delivery:

{
  "name": "my-webhook-sub",
  "address": "queue:my-events",
  "webhookUrl": "https://my-app.cfapps.eu10.hana.ondemand.com/api/events",
  "qos": 1,
  "handshakeSecret": "my-secret-123"
}

Event Mesh performs a handshake (challenge-response) to verify webhook ownership before activating the subscription.

Comparison with Kafka / RabbitMQ

Feature	Event Mesh	Apache Kafka	RabbitMQ
Model	Topic → Queue (pub/sub)	Topic → Partition → Consumer Group	Exchange → Queue (pub/sub or direct)
Ordering	Per-queue FIFO	Per-partition ordering	Per-queue FIFO
Replay	No (consumed = gone)	Yes (offset-based replay)	No (ack = gone)
Retention	TTL-based	Time/size-based retention	TTL-based
Throughput	Medium (~1000 msg/s per queue)	Very high (~100K+ msg/s)	High (~10K+ msg/s)
Protocol	AMQP, MQTT, HTTP	Kafka protocol (TCP)	AMQP 0.9.1
SAP integration	Native S/4HANA events	Requires connector	Requires connector
Management	Fully managed on BTP	Self-managed or Confluent	Self-managed or CloudAMQP
Dead letter	Manual (DLQ pattern)	Via connectors	Built-in DLX

Key takeaway for Kafka users: Event Mesh does not support message replay. If you need event sourcing or replay capability, consider Kafka on Kyma or a hybrid architecture.

2. CloudEvents Specification

SAP standardized on the CloudEvents specification for all business events. CloudEvents defines a common envelope format:

Envelope Structure

{
  "specversion": "1.0",
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "source": "/default/sap.s4.beh/XXXXXXXXXX",
  "type": "sap.s4.beh.businesspartner.changed.v1",
  "datacontenttype": "application/json",
  "time": "2024-11-15T10:30:00Z",
  "data": {
    "BusinessPartner": "1000042",
    "BusinessPartnerName": "ACME Corp",
    "ChangedFields": ["BusinessPartnerName", "SearchTerm1"]
  }
}

S/4HANA Event Types

S/4HANA emits events following a naming convention:

sap.s4.beh.<business-object>.<operation>.v<version>

Examples:
sap.s4.beh.businesspartner.changed.v1
sap.s4.beh.businesspartner.created.v1
sap.s4.beh.salesorder.created.v1
sap.s4.beh.salesorder.changed.v1
sap.s4.beh.purchaseorder.released.v1
sap.s4.beh.product.created.v1

The data payload is intentionally minimal — it contains the key fields and changed fields, not the full business object. Your consumer is expected to call back to S/4HANA's OData API to fetch the complete data.

Topic-to-Queue Mapping for S/4HANA Events

S/4HANA → Event Mesh Topic: sap/s4/beh/businesspartner/changed/v1
                                │
Queue subscription pattern: sap/s4/beh/businesspartner/*/v1
                                │
                                ▼
Queue: "bp-processor" → Your microservice receives the event

3. Enterprise Messaging Patterns

Fan-Out

One event consumed by multiple independent services:

                        ┌──→ Queue "enrichment" → Enrichment Service
                        │
Topic: order.created ───┼──→ Queue "inventory"  → Inventory Service
                        │
                        └──→ Queue "notification" → Notification Service

Each queue has its own subscription to the same topic. Each consumer processes independently.

Competing Consumers

Multiple instances of the same service consume from one queue for horizontal scaling:

Queue: "order-processor"
    ├──→ Instance 1 (processes message A)
    ├──→ Instance 2 (processes message B)
    └──→ Instance 3 (processes message C)

Event Mesh distributes messages round-robin across connected consumers on the same queue. Only one consumer receives each message.

Dead-Letter Queue Pattern

Event Mesh doesn't have a built-in DLQ mechanism. Implement it in your application:

@On(event = "sap.s4.beh.businesspartner.changed.v1")
public void handleBusinessPartnerChanged(EventContext ctx) {
    int retryCount = getRetryCount(ctx);

    try {
        processEvent(ctx.getData());
    } catch (TransientException e) {
        if (retryCount < MAX_RETRIES) {
            // Re-publish with incremented retry count and delay
            republishWithDelay(ctx, retryCount + 1, calculateBackoff(retryCount));
        } else {
            // Send to dead-letter queue for manual investigation
            publishToDeadLetterQueue(ctx);
            log.error("Event moved to DLQ after {} retries: {}", MAX_RETRIES, ctx.getId());
        }
    } catch (PermanentException e) {
        // Immediately DLQ — no retry will fix this
        publishToDeadLetterQueue(ctx);
        log.error("Permanent failure, moved to DLQ: {}", e.getMessage());
    }
}

Retry with Exponential Backoff

private Duration calculateBackoff(int retryCount) {
    // Base: 1s, then 2s, 4s, 8s, 16s (max 30s)
    long delayMs = Math.min(
        (long) Math.pow(2, retryCount) * 1000,
        30_000
    );
    // Add jitter to prevent thundering herd
    delayMs += ThreadLocalRandom.current().nextLong(0, delayMs / 4);
    return Duration.ofMillis(delayMs);
}

4. Integration Suite vs Event Mesh

When to Use Each

┌─────────────────────────────┐    ┌─────────────────────────────┐
│   SAP Integration Suite      │    │   SAP Event Mesh             │
│                              │    │                              │
│  - Request/Response (sync)   │    │  - Fire-and-forget (async)   │
│  - Data transformation       │    │  - Pub/sub pattern           │
│  - Protocol mediation        │    │  - Event-driven extensions   │
│  - Complex routing (iFlows)  │    │  - Real-time notifications   │
│  - Batch data replication    │    │  - Loose coupling            │
│  - API management            │    │  - CloudEvents standard      │
│                              │    │                              │
│  Good for:                   │    │  Good for:                   │
│  - ETL / data sync           │    │  - Side-by-side extensions   │
│  - Legacy system adapters    │    │  - Microservice choreography │
│  - Complex transformations   │    │  - Decoupled architecture    │
└─────────────────────────────┘    └─────────────────────────────┘

Hybrid Architecture

In practice, you often combine both:

S/4HANA
   │
   ├──→ Event Mesh (business events: BP changed, SO created)
   │         │
   │         └──→ Kyma microservice (real-time processing)
   │
   └──→ Integration Suite (batch replication: nightly sync of master data)
            │
            └──→ HANA Cloud (data warehouse / reporting)

Rule of thumb:

Use Event Mesh when the consumer decides when and how to react to business events
Use Integration Suite when you need data transformation, protocol mediation, or orchestrated integration flows

5. Implementing an Event-Driven CAP Java Microservice

Project Setup

my-event-app/
├── srv/
│   ├── src/main/java/com/myapp/
│   │   └── handlers/
│   │       └── BusinessPartnerEventHandler.java
│   └── src/main/resources/
│       └── application.yaml
├── db/
│   └── schema.cds
├── package.json
├── pom.xml
└── mta.yaml

CDS Model

// db/schema.cds
namespace my.events;

entity BusinessPartnerMirror {
    key bpId         : String(10);
    name             : String(200);
    city             : String(100);
    country          : String(3);
    lastSyncedAt     : Timestamp;
    sourceEvent      : String(100);
}

// srv/event-service.cds
using my.events from '../db/schema';

service EventService {
    entity BusinessPartners as projection on events.BusinessPartnerMirror;
}

// Declare event subscription
@protocol: 'none'  // no OData exposure for the event handler service
service EventHandlerService {
    event businessPartnerChanged : {
        BusinessPartner : String(10);
    };
}

CAP Messaging Configuration

# srv/src/main/resources/application.yaml
cds:
  messaging:
    services:
      - name: "messaging"
        kind: "enterprise-messaging"
        format: "cloudevents"
        subscriptions:
          - event: "sap.s4.beh.businesspartner.changed.v1"
            queue: "bp-changed-queue"
          - event: "sap.s4.beh.businesspartner.created.v1"
            queue: "bp-created-queue"

Event Handler (Java)

package com.myapp.handlers;

import com.sap.cds.services.EventContext;
import com.sap.cds.services.handler.EventHandler;
import com.sap.cds.services.handler.annotations.On;
import com.sap.cds.services.handler.annotations.ServiceName;
import com.sap.cds.services.messaging.TopicMessageEventContext;
import com.sap.cds.services.persistence.PersistenceService;
import com.sap.cds.ql.Upsert;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Component;

import java.time.Instant;
import java.util.Map;

@Component
@ServiceName("messaging")
public class BusinessPartnerEventHandler implements EventHandler {

    private static final Logger log = LoggerFactory.getLogger(BusinessPartnerEventHandler.class);

    private final PersistenceService db;
    private final S4HanaClient s4Client;  // SAP Cloud SDK client

    public BusinessPartnerEventHandler(PersistenceService db, S4HanaClient s4Client) {
        this.db = db;
        this.s4Client = s4Client;
    }

    @On(event = "sap.s4.beh.businesspartner.changed.v1")
    public void onBusinessPartnerChanged(TopicMessageEventContext ctx) {
        Map<String, Object> eventData = ctx.getData();
        String bpId = (String) eventData.get("BusinessPartner");

        log.info("Received BP changed event for: {}", bpId);

        // 1. Call back to S/4HANA to get full BP data
        BusinessPartner fullBp = s4Client.getBusinessPartner(bpId);

        // 2. Upsert into local mirror table (idempotent operation)
        Map<String, Object> mirrorData = Map.of(
            "bpId", bpId,
            "name", fullBp.getBusinessPartnerName(),
            "city", fullBp.getCity(),
            "country", fullBp.getCountry(),
            "lastSyncedAt", Instant.now().toString(),
            "sourceEvent", "sap.s4.beh.businesspartner.changed.v1"
        );

        db.run(Upsert.into("my.events.BusinessPartnerMirror").entry(mirrorData));

        log.info("BP {} mirrored successfully", bpId);

        // 3. Optionally publish a derived event
        publishDerivedEvent(bpId, fullBp);
    }

    @On(event = "sap.s4.beh.businesspartner.created.v1")
    public void onBusinessPartnerCreated(TopicMessageEventContext ctx) {
        // Similar logic, reuse the upsert pattern
        onBusinessPartnerChanged(ctx);
    }

    private void publishDerivedEvent(String bpId, BusinessPartner bp) {
        // Publish to a custom topic for downstream consumers
        Map<String, Object> derivedEvent = Map.of(
            "bpId", bpId,
            "enrichedName", bp.getBusinessPartnerName(),
            "region", mapCountryToRegion(bp.getCountry()),
            "timestamp", Instant.now().toString()
        );

        // CAP messaging API for publishing
        // messaging.emit("my.app.bp.enriched.v1", derivedEvent);
    }
}

MTA Deployment Descriptor

# mta.yaml
_schema-version: "3.1"
ID: my-event-app
version: 1.0.0

modules:
  - name: my-event-app-srv
    type: java
    path: srv
    parameters:
      memory: 1024M
      disk-quota: 512M
      buildpack: sap_java_buildpack
    requires:
      - name: my-event-app-db
      - name: my-event-app-messaging
      - name: my-event-app-xsuaa
      - name: my-event-app-destination

  - name: my-event-app-db-deployer
    type: hdb
    path: db
    requires:
      - name: my-event-app-db

resources:
  - name: my-event-app-db
    type: com.sap.xs.hdi-container
    parameters:
      service: hana
      service-plan: hdi-shared

  - name: my-event-app-messaging
    type: org.cloudfoundry.managed-service
    parameters:
      service: enterprise-messaging
      service-plan: default
      path: ./event-mesh.json  # Event Mesh descriptor

  - name: my-event-app-xsuaa
    type: org.cloudfoundry.managed-service
    parameters:
      service: xsuaa
      service-plan: application
      path: ./xs-security.json

  - name: my-event-app-destination
    type: org.cloudfoundry.managed-service
    parameters:
      service: destination
      service-plan: lite

Event Mesh Service Descriptor

// event-mesh.json
{
  "emname": "my-event-app",
  "version": "1.0.0",
  "namespace": "my/app/events",
  "options": {
    "management": true,
    "messagingrest": true
  },
  "rules": {
    "queueRules": {
      "publishFilter": ["${namespace}/**"],
      "subscribeFilter": ["${namespace}/**", "sap/s4/beh/**"]
    },
    "topicRules": {
      "publishFilter": ["${namespace}/**"],
      "subscribeFilter": ["${namespace}/**", "sap/s4/beh/**"]
    }
  }
}

Sequence Diagram

S/4HANA          Event Mesh         CAP Java Service        HANA Cloud
   │                  │                    │                     │
   │ BP Changed       │                    │                     │
   │─────────────────→│                    │                     │
   │  (CloudEvent)    │                    │                     │
   │                  │ Queue: bp-changed  │                     │
   │                  │───────────────────→│                     │
   │                  │                    │                     │
   │                  │                    │ GET /BusinessPartner│
   │←─────────────────┼────────────────────│ ('1000042')        │
   │ {full BP data}   │                    │                     │
   │─────────────────→┼───────────────────→│                     │
   │                  │                    │                     │
   │                  │                    │ UPSERT mirror table │
   │                  │                    │────────────────────→│
   │                  │                    │        OK           │
   │                  │                    │←────────────────────│
   │                  │                    │                     │
   │                  │  Publish derived   │                     │
   │                  │←───────────────────│                     │
   │                  │ my/app/bp/enriched │                     │
   │                  │                    │                     │

Top 5 Pitfalls

Not designing for idempotency. Event Mesh delivers at-least-once. Use UPSERT instead of INSERT, and check for duplicate event IDs.
Expecting full payloads in S/4HANA events. S/4HANA events are notifications with keys only. You must call back to get the full object.
Ignoring topic subscription filters. Overly broad filters (e.g., sap/s4/beh/>) cause your queue to receive events you don't need, wasting resources.
Missing the Event Mesh service descriptor. Without proper rules.queueRules.subscribeFilter, your app can't subscribe to S/4HANA event topics.
Confusing Event Mesh with Kafka. No replay, no consumer group offsets. If you need replay, architect a separate event store.

What to Learn Next

Lesson 2.4: Kyma Eventing & Extension Patterns — event-driven extensions on Kubernetes
Lesson 3.3: CAP Remote Services — calling back to S/4HANA OData from CAP
Lesson 4.1: CI/CD — deploying event-driven apps with MTA
SAP Event Mesh REST API documentation
CloudEvents specification: https://cloudevents.io/

SAP HANA Cloud Deep Dive — HDI, Multi-Model Engine & Performance

Aliaksandr Tsviatkou — Thu, 26 Mar 2026 15:26:08 +0000

Lesson 1.2 — SAP HANA Cloud Deep Dive

1. HANA Cloud vs On-Premise HANA
2. HANA Multi-Model Engine
3. HDI (HANA Deployment Infrastructure)
4. Connectivity from CF / Kyma Applications
5. Performance Tuning
Comparison with PostgreSQL / MySQL
Top 5 Pitfalls
What to Learn Next

Summary: SAP HANA Cloud is a columnar, in-memory relational database offered as a managed service on BTP. For Java architects coming from PostgreSQL or MySQL, the paradigm shift is significant: HANA's column store, multi-model engines (document, graph, spatial), and HDI deployment model all require new mental models. This lesson covers HANA Cloud internals, the HDI container architecture, connectivity patterns from CF/Kyma, and performance tuning strategies — all compared against familiar RDBMS concepts.

1. HANA Cloud vs On-Premise HANA

Architecture Differences

┌─────────────────────────────────────────────────────┐
│                 SAP HANA Cloud                       │
│                                                     │
│  ┌──────────┐  ┌──────────┐  ┌───────────────────┐ │
│  │ Column   │  │ Row      │  │ Native Storage    │ │
│  │ Store    │  │ Store    │  │ Extension (NSE)   │ │
│  │ (hot)    │  │ (OLTP)   │  │ (warm/cold data)  │ │
│  │ in-memory│  │ in-memory│  │ disk-based pages  │ │
│  └──────────┘  └──────────┘  └───────────────────┘ │
│                                                     │
│  ┌──────────────────────────────────────────────┐   │
│  │         Persistence Layer (disk)              │   │
│  │  - Data volumes, log volumes                  │   │
│  │  - Page-loadable columns (NSE)                │   │
│  │  - Automatic tiering                          │   │
│  └──────────────────────────────────────────────┘   │
│                                                     │
│  Managed by SAP: backups, patching, HA, scaling     │
└─────────────────────────────────────────────────────┘

Feature	On-Premise HANA	HANA Cloud
Memory model	All data in memory (column store)	Memory + disk (NSE for warm data)
Scaling	Scale-up only (add RAM)	Elastic compute scaling, storage auto-grows
Administration	Full DBA access, OS-level	No OS access, limited admin via SQL/Cockpit
Multi-tenancy	MDC (Multitenant Database Containers)	Managed by SAP, one instance per service
Backup/Recovery	Manual or scripted	Automatic, point-in-time recovery via Cockpit
Network	Direct TCP access	TLS-only, access via service binding credentials
Cost model	License + hardware	Consumption-based (CU — Compute Units)

Native Storage Extension (NSE)

NSE is HANA Cloud's game-changer for cost optimization. It allows you to mark columns or entire tables as page-loadable instead of column-loadable:

-- Column-loadable (default): entire column loaded into memory
CREATE TABLE orders (
    id BIGINT PRIMARY KEY,
    customer_id BIGINT,
    amount DECIMAL(15,2),
    created_at TIMESTAMP
);

-- Page-loadable: only accessed pages loaded into memory buffer cache
ALTER TABLE orders ALTER (amount DECIMAL(15,2) PAGE LOADABLE);

-- Or make entire table page-loadable
ALTER TABLE orders PAGE LOADABLE;

When to use NSE:

Historical data that is rarely queried
Large text/LOB columns
Audit tables
Tables where the hot working set is < 20% of total data

Analogy for PostgreSQL devs: NSE is conceptually similar to PostgreSQL's TOAST mechanism combined with buffer pool management — data lives on disk and is paged into memory on demand. The key difference is that HANA's column store still provides columnar compression benefits even for page-loadable data.

2. HANA Multi-Model Engine

HANA is not just a relational database. It includes five distinct processing engines:

Column Store (Primary)

The column store is HANA's default and strongest engine. Data is stored column-by-column with dictionary encoding and various compression schemes:

Traditional Row Store (PostgreSQL/MySQL):
Row 1: [id:1, name:"Alice", city:"Berlin", age:30]
Row 2: [id:2, name:"Bob",   city:"Berlin", age:25]
Row 3: [id:3, name:"Carol", city:"Munich", age:35]

HANA Column Store:
id column:   [1, 2, 3]
name column: [dict: 0=Alice, 1=Bob, 2=Carol] → [0, 1, 2]
city column: [dict: 0=Berlin, 1=Munich] → [0, 0, 1]  ← high compression
age column:  [30, 25, 35]

Benefits:

Compression: Dictionary encoding, run-length encoding, cluster encoding. Typical 5-10x compression ratio.
Vectorized processing: Column scans process data in CPU-cache-friendly chunks.
Aggregation speed: SELECT city, AVG(age) FROM users GROUP BY city only reads city and age columns, skipping all others.

-- Check compression ratio
SELECT TABLE_NAME, 
       ROUND(MEMORY_SIZE_IN_TOTAL / 1024 / 1024, 2) AS memory_mb,
       ROUND(DISK_SIZE / 1024 / 1024, 2) AS disk_mb,
       RECORD_COUNT
FROM M_CS_TABLES
WHERE SCHEMA_NAME = 'MY_SCHEMA'
ORDER BY MEMORY_SIZE_IN_TOTAL DESC;

Row Store

Used for:

System tables (internal catalog)
Tables with frequent single-row updates (point lookups by PK)
Temporary tables in stored procedures

-- Explicitly create a row-store table (rarely needed)
CREATE ROW TABLE session_cache (
    session_id VARCHAR(128) PRIMARY KEY,
    user_id BIGINT,
    data NCLOB,
    expires_at TIMESTAMP
);

Rule of thumb: Use column store for everything unless you have a specific reason not to. HANA's column store handles OLTP workloads well due to its delta merge architecture.

Document Store (JSON Collections)

HANA includes a native JSON document store — useful for schema-less data:

-- Create a JSON collection
CREATE COLLECTION products;

-- Insert documents
INSERT INTO products VALUES ('{"name": "Laptop", "specs": {"ram": 16, "cpu": "i7"}, "tags": ["electronics", "computing"]}');
INSERT INTO products VALUES ('{"name": "Phone", "specs": {"ram": 8, "cpu": "A15"}, "tags": ["electronics", "mobile"]}');

-- Query with JSON path expressions
SELECT * FROM products 
WHERE "specs"."ram" > 10;

-- Join collections with relational tables
SELECT p.*, o.order_date
FROM products p
JOIN orders o ON p."_id" = o.product_id;

Comparison with MongoDB: HANA's document store supports basic CRUD and querying but lacks MongoDB's aggregation pipeline, change streams, and sharding. Use it for auxiliary semi-structured data, not as a primary document database.

Graph Engine

For traversal-heavy queries (org charts, supply chains, social networks):

-- Create a graph workspace
CREATE GRAPH WORKSPACE my_graph
    EDGE TABLE edges
        SOURCE COLUMN source_id
        TARGET COLUMN target_id
        KEY COLUMN edge_id
    VERTEX TABLE vertices
        KEY COLUMN vertex_id;

-- Shortest path query
SELECT * FROM SHORTEST_PATH(
    my_graph,
    vertex_start => 'A',
    vertex_end => 'Z',
    direction => 'OUTGOING'
);

-- Pattern matching (like Cypher in Neo4j)
MATCH (a)-[e]->(b)-[f]->(c)
WHERE a.name = 'SAP' AND c.type = 'Subsidiary'
RETURN a.name, b.name, c.name;

Spatial Engine

For geographic data (store locations, delivery zones, geofencing):

CREATE TABLE stores (
    id INTEGER PRIMARY KEY,
    name VARCHAR(100),
    location ST_POINT(4326)  -- SRID 4326 = WGS84
);

INSERT INTO stores VALUES (1, 'Berlin Store', ST_GeomFromText('POINT(13.405 52.52)', 4326));
INSERT INTO stores VALUES (2, 'Munich Store', ST_GeomFromText('POINT(11.582 48.135)', 4326));

-- Find stores within 100km of a point
SELECT name, location.ST_Distance(ST_GeomFromText('POINT(13.0 52.5)', 4326)) AS distance_m
FROM stores
WHERE location.ST_Distance(ST_GeomFromText('POINT(13.0 52.5)', 4326)) < 100000;

3. HDI (HANA Deployment Infrastructure)

Container Model

HDI is the deployment mechanism for HANA Cloud artifacts. It manages database objects through a design-time/runtime separation:

┌─────────────────────────────────────────────┐
│            HANA Cloud Instance               │
│                                             │
│  ┌─────────────┐  ┌─────────────┐          │
│  │ HDI Container│  │ HDI Container│  ...    │
│  │ (App A)      │  │ (App B)      │         │
│  │              │  │              │         │
│  │ Schema:      │  │ Schema:      │         │
│  │ APP_A_HDI_1  │  │ APP_B_HDI_1  │         │
│  │              │  │              │         │
│  │ Design-time: │  │ Design-time: │         │
│  │ .hdbcds      │  │ .hdbtable    │         │
│  │ .hdbview     │  │ .hdbcalcview │         │
│  │ .hdbrole     │  │ .hdbgrants   │         │
│  │              │  │              │         │
│  │ Runtime:     │  │ Runtime:     │         │
│  │ Tables       │  │ Tables       │         │
│  │ Views        │  │ Views        │         │
│  │ Procedures   │  │ Calc Views   │         │
│  └─────────────┘  └─────────────┘          │
└─────────────────────────────────────────────┘

Key concepts:

Each HDI container maps to a database schema with its own isolated namespace
Design-time artifacts (.hdb* files) are deployed by the HDI deployer, which generates runtime objects
The container owner has DML access; a separate technical user has DDL access
Schema evolution is automatic: the HDI deployer computes the delta between design-time artifacts and current runtime state

Design-Time Artifacts

Artifact	Extension	Purpose
CDS entities	`.hdbcds`	Define tables and views using CDS syntax
Tables	`.hdbtable`	Define tables using HANA SQL DDL
Views	`.hdbview`	SQL views
Calculation views	`.hdbcalculationview`	Graphical multi-level analytical views
Procedures	`.hdbprocedure`	Stored procedures (SQLScript)
Table types	`.hdbtabletype`	Reusable table type definitions
Roles	`.hdbrole`	Container-level roles
Grants	`.hdbgrants`	Cross-container access grants
Synonyms	`.hdbsynonym`	Access objects outside the container

CDS vs hdbtable

-- .hdbcds syntax (SAP's CDS for HANA, not CAP CDS)
context my.model {
    entity Orders {
        key id       : Integer;
        customer     : String(100);
        amount       : Decimal(15, 2);
        createdAt    : UTCTimestamp;
    };
};

-- Equivalent .hdbtable syntax
COLUMN TABLE "my.model::Orders" (
    "id" INTEGER NOT NULL,
    "customer" NVARCHAR(100),
    "amount" DECIMAL(15, 2),
    "createdAt" TIMESTAMP,
    PRIMARY KEY ("id")
);

Important distinction: HDI .hdbcds is HANA-native CDS syntax. CAP's CDS (.cds files) is a different language that compiles down to .hdbcds or .hdbtable artifacts for HANA deployment.

HDI in Multi-Tenancy

In multi-tenant CAP applications, each tenant gets its own HDI container:

Tenant "customer-a" → HDI Container → Schema: CUSTOMER_A_HDI_1
Tenant "customer-b" → HDI Container → Schema: CUSTOMER_B_HDI_1
Tenant "customer-c" → HDI Container → Schema: CUSTOMER_C_HDI_1

The @sap/cds-mtxs sidecar manages container provisioning and schema upgrades across all tenants.

4. Connectivity from CF / Kyma Applications

Service Binding Anatomy

When you bind a HANA Cloud HDI service instance, you receive credentials:

{
  "credentials": {
    "host": "abc123.hana.prod-eu10.hanacloud.ondemand.com",
    "port": "443",
    "driver": "com.sap.db.jdbc.Driver",
    "url": "jdbc:sap://abc123.hana.prod-eu10.hanacloud.ondemand.com:443?encrypt=true&validateCertificate=true",
    "schema": "MY_HDI_CONTAINER",
    "hdi_user": "MY_HDI_CONTAINER#OO",
    "hdi_password": "...",
    "user": "MY_HDI_CONTAINER#OO",
    "password": "...",
    "certificate": "-----BEGIN CERTIFICATE-----\n..."
  }
}

JDBC Connection (Java)

// Direct JDBC (not recommended for CAP apps)
import com.sap.db.jdbc.Driver;

String url = credentials.getString("url");
String user = credentials.getString("user");
String password = credentials.getString("password");

Connection conn = DriverManager.getConnection(url, user, password);

CAP's Built-In Persistence Layer

CAP Java abstracts HANA connectivity entirely. You define CDS models and CAP generates SQL:

// db/schema.cds
namespace my.bookshop;

entity Books {
    key ID    : UUID;
    title     : String(200);
    author    : Association to Authors;
    price     : Decimal(10, 2);
    stock     : Integer;
}

entity Authors {
    key ID    : UUID;
    name      : String(100);
    books     : Association to many Books on books.author = $self;
}

CAP compiles this to HDI artifacts and handles connection pooling, schema resolution, and multi-tenancy automatically. The CQN query engine translates programmatic queries to HANA SQL:

// CAP Java handler — no raw SQL needed
@On(event = CqnService.EVENT_READ, entity = "my.bookshop.Books")
public void onReadBooks(CdsReadEventContext ctx) {
    CqnSelect query = Select.from("my.bookshop.Books")
        .columns(b -> b.title(), b -> b.price(), b -> b.author().expand(a -> a.name()))
        .where(b -> b.stock().gt(0))
        .orderBy(b -> b.title().asc())
        .limit(20);
    ctx.setResult(db.run(query));
}

Generated SQL:

SELECT T0."TITLE", T0."PRICE", T1."NAME" AS "author_name"
FROM "MY_BOOKSHOP_BOOKS" T0
LEFT JOIN "MY_BOOKSHOP_AUTHORS" T1 ON T0."AUTHOR_ID" = T1."ID"
WHERE T0."STOCK" > 0
ORDER BY T0."TITLE" ASC
LIMIT 20

Connection from Kyma

In Kyma, use the BTP Operator to create a ServiceBinding that injects HANA credentials:

apiVersion: services.cloud.sap.com/v1
kind: ServiceInstance
metadata:
  name: hana-hdi
spec:
  serviceOfferingName: hana
  servicePlanName: hdi-shared
---
apiVersion: services.cloud.sap.com/v1
kind: ServiceBinding
metadata:
  name: hana-hdi-binding
spec:
  serviceInstanceName: hana-hdi
  secretName: hana-hdi-secret

Mount the secret into your pod:

volumes:
  - name: hana-credentials
    secret:
      secretName: hana-hdi-secret
containers:
  - name: app
    volumeMounts:
      - name: hana-credentials
        mountPath: /etc/secrets/sapcp/hana/hdi
        readOnly: true

5. Performance Tuning

Explain Plans

-- Text-based explain plan
EXPLAIN PLAN FOR
SELECT customer_id, SUM(amount) 
FROM orders 
WHERE created_at > '2024-01-01'
GROUP BY customer_id;

SELECT * FROM EXPLAIN_PLAN_TABLE;

Key operators to watch:

COLUMN SEARCH — efficient columnar scan
COLUMN TABLE FILTER — predicate pushdown to column engine
HASH JOIN / MERGE JOIN — join strategies
ROW TABLE SCAN — row store access (potential bottleneck for analytics)
CPEXTRACT — extraction from column store to row processing (bad sign for large datasets)

Delta Merge

HANA's column store uses a write-optimized delta store and a read-optimized main store:

Write → Delta Store (row-oriented, small, fast inserts)
              │
              ▼ (async merge)
         Main Store (column-oriented, compressed, fast reads)

Monitor delta merge:

-- Check tables with large delta stores
SELECT TABLE_NAME, 
       RECORD_COUNT,
       RAW_RECORD_COUNT_IN_DELTA,
       ROUND(RAW_RECORD_COUNT_IN_DELTA * 100.0 / NULLIF(RECORD_COUNT, 0), 2) AS delta_pct
FROM M_CS_TABLES
WHERE SCHEMA_NAME = 'MY_SCHEMA'
  AND RAW_RECORD_COUNT_IN_DELTA > 10000
ORDER BY RAW_RECORD_COUNT_IN_DELTA DESC;

-- Trigger manual merge if needed
MERGE DELTA OF "MY_SCHEMA"."MY_TABLE";

Partition Pruning

For large tables, partitioning enables the query engine to skip irrelevant data:

-- Range partitioning by date
CREATE TABLE events (
    id BIGINT GENERATED ALWAYS AS IDENTITY,
    event_type VARCHAR(50),
    payload NCLOB,
    created_at DATE NOT NULL
)
PARTITION BY RANGE (created_at) (
    PARTITION '2024-01-01' <= VALUES < '2024-04-01',
    PARTITION '2024-04-01' <= VALUES < '2024-07-01',
    PARTITION '2024-07-01' <= VALUES < '2024-10-01',
    PARTITION '2024-10-01' <= VALUES < '2025-01-01',
    PARTITION OTHERS
);

-- Hash partitioning for even distribution
CREATE TABLE user_events (
    user_id BIGINT,
    event_data NVARCHAR(5000)
)
PARTITION BY HASH (user_id) PARTITIONS 8;

Common Anti-Patterns

Anti-Pattern	Problem	Fix
Row-by-row processing in loops	Bypasses columnar vectorization	Use set-based SQL or array processing
`SELECT *` on wide tables	Loads all columns from column store	Select only needed columns
Overusing calculation views	Layer upon layer of calc views creates complex execution plans	Flatten where possible, use SQL views for simple projections
Missing partition pruning	Full table scans on partitioned tables	Ensure WHERE clauses include the partition column
Excessive use of row store	Row store doesn't benefit from columnar compression	Move to column store unless OLTP pattern requires row store
Not monitoring delta merge	Large delta stores degrade read performance	Set up monitoring, tune auto-merge thresholds

Memory Consumption Analysis

-- Top memory consumers
SELECT SCHEMA_NAME, TABLE_NAME, TABLE_TYPE,
       ROUND(MEMORY_SIZE_IN_TOTAL / 1024 / 1024, 2) AS total_mb,
       ROUND(MEMORY_SIZE_IN_MAIN / 1024 / 1024, 2) AS main_mb,
       ROUND(MEMORY_SIZE_IN_DELTA / 1024 / 1024, 2) AS delta_mb,
       RECORD_COUNT
FROM M_CS_TABLES
ORDER BY MEMORY_SIZE_IN_TOTAL DESC
LIMIT 20;

-- Memory by column for a specific table
SELECT COLUMN_NAME, 
       ROUND(MEMORY_SIZE_IN_MAIN / 1024 / 1024, 2) AS main_mb,
       COMPRESSION_TYPE,
       DISTINCT_COUNT
FROM M_CS_COLUMNS
WHERE SCHEMA_NAME = 'MY_SCHEMA' AND TABLE_NAME = 'MY_TABLE'
ORDER BY MEMORY_SIZE_IN_MAIN DESC;

Comparison with PostgreSQL / MySQL

Concept	PostgreSQL/MySQL	HANA Cloud
Default storage	Row-oriented (heap)	Column-oriented
In-memory	Buffer pool caches pages	All active data in memory (column store) or paged (NSE)
Compression	pg: TOAST, InnoDB: page compression	Dictionary encoding, RLE, cluster encoding (automatic)
Schema migration	Flyway / Liquibase	HDI deployer (declarative)
JSON support	`jsonb` type (PostgreSQL)	Document store (collections)
Graph queries	Recursive CTEs or Apache AGE	Native graph engine
Spatial	PostGIS extension	Built-in spatial engine
Execution plans	`EXPLAIN ANALYZE`	`EXPLAIN PLAN FOR` + `EXPLAIN_PLAN_TABLE`
Connection pooling	PgBouncer / HikariCP	HikariCP (JDBC) / CAP internal pool
Full-text search	`tsvector` / `tsquery`	Built-in full-text indexes

Top 5 Pitfalls

Treating HANA like PostgreSQL. Don't write row-by-row processing loops. HANA's column store excels at set-based operations.
Ignoring NSE. Keeping cold data in-memory wastes expensive compute units. Use page-loadable for historical data.
Bypassing HDI. Creating objects directly via SQL (not through .hdb* artifacts) means they won't be managed, versioned, or deployable.
Not monitoring delta merge. A table with 50% data in delta store performs like a row store. Monitor M_CS_TABLES.RAW_RECORD_COUNT_IN_DELTA.
Overcomplicating calc views. Calculation views are powerful but add latency at each layer. For simple joins and projections, SQL views or CDS views are faster and easier to debug.

What to Learn Next

Lesson 1.1: BTP Architecture — how HANA Cloud fits in the BTP service ecosystem
Lesson 3.1: CAP Java core concepts — how CAP abstracts HANA via CDS models and CQN
Lesson 3.4: Advanced CAP patterns — connection pooling, batch processing, deployment topologies
SAP HANA Cloud SQL Reference Guide — full DDL/DML reference
SAP HANA Cloud Performance Guide — deep tuning documentation

SAP BTP Architecture & Runtime Model — A Java Architect's Guide

Aliaksandr Tsviatkou — Thu, 26 Mar 2026 15:26:05 +0000

Lesson 1.1 — SAP BTP Architecture & Runtime Model

1. Multi-Environment Architecture
2. Subaccount, Directory, and Entitlement Hierarchy
3. BTP Service Marketplace & Open Service Broker API
4. BTP Connectivity: Cloud Connector & Destinations
5. BTP Security Model — XSUAA Internals
Top 5 Pitfalls for Java Developers on BTP
What to Learn Next

Summary: SAP Business Technology Platform (BTP) is a PaaS offering that hosts three distinct runtime environments — Cloud Foundry, Kyma (Kubernetes), and ABAP — under a unified commercial and governance model. Understanding BTP's internal structure is critical for Java architects because it dictates how services are consumed, how security tokens flow, and how on-premise connectivity works. This lesson dissects BTP's architecture layer by layer, from the organizational hierarchy down to the VCAP_SERVICES binding mechanism.

1. Multi-Environment Architecture

BTP offers three runtime environments within a single subaccount. Each serves a different workload profile:

┌─────────────────────────────────────────────────────────────────┐
│                     SAP BTP Global Account                      │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                      Subaccount                           │  │
│  │                                                           │  │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐   │  │
│  │  │ Cloud       │  │ Kyma        │  │ ABAP            │   │  │
│  │  │ Foundry     │  │ Runtime     │  │ Environment     │   │  │
│  │  │             │  │             │  │                 │   │  │
│  │  │ - Buildpacks│  │ - K8s pods  │  │ - ABAP stack    │   │  │
│  │  │ - Diego     │  │ - Istio     │  │ - Steampunk     │   │  │
│  │  │   cells     │  │ - Eventing  │  │ - RAP / CDS     │   │  │
│  │  │ - cf push   │  │ - Helm      │  │ - ADT (Eclipse) │   │  │
│  │  └─────────────┘  └─────────────┘  └─────────────────┘   │  │
│  └───────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

Cloud Foundry Environment

Runtime model: Application instances run inside Diego cells (Linux containers managed by the Diego orchestrator). You deploy via cf push or MTA (cf deploy).
Scaling: Horizontal scaling by instance count. Each instance is a separate container with its own memory/disk quota. No shared filesystem between instances.
Buildpacks: SAP provides sap_java_buildpack (based on SAP JVM or SapMachine) and the community java_buildpack. SAP's buildpack includes built-in support for BTP service credentials injection.
Best for: Stateless web applications, CAP applications, batch jobs, and traditional 12-factor apps.

Kyma Environment

Runtime model: A managed Kubernetes cluster with pre-installed modules (Istio, NATS Eventing, API Gateway, Serverless). You deploy via kubectl apply, Helm charts, or Kyma-specific CRDs.
Scaling: Full Kubernetes HPA, VPA, and pod-level resource management. You control CPU/memory requests and limits directly.
SAP Additions: BTP Operator (manages service instances/bindings as K8s CRDs), Kyma API Gateway (APIRule CRD), Kyma Eventing (Subscription CRD).
Best for: Microservices architectures, event-driven extensions, workloads requiring sidecar patterns, teams already invested in Kubernetes.

ABAP Environment (Steampunk)

Runtime model: A full ABAP application server instance running in the cloud. You develop using the ABAP RESTful Application Programming Model (RAP) via ABAP Development Tools (ADT) in Eclipse.
Best for: Extending S/4HANA with ABAP-native code, building reusable ABAP APIs, teams with deep ABAP expertise.

When to Use Each

Criteria	Cloud Foundry	Kyma	ABAP
Team skills	Java/Node.js, CF CLI	Java + Kubernetes	ABAP, RAP
Deployment model	`cf push` / MTA	Helm / kubectl	ADT / abapGit
Sidecar support	No	Yes (Istio)	No
Event-driven extensions	Via Event Mesh client lib	Native Subscription CRD	Enterprise Event Enablement
Container control	Low (buildpack-managed)	Full (custom Dockerfiles)	None
Cold start	Low (~2-5s)	Varies (depends on image)	N/A (always running)

Pitfall for Spring Boot devs: Cloud Foundry is not Docker. You don't write a Dockerfile for CF — you use buildpacks. If you need custom container images, use Kyma.

2. Subaccount, Directory, and Entitlement Hierarchy

BTP's organizational model has four levels:

Global Account
├── Directory (optional grouping)
│   ├── Subaccount (dev)
│   ├── Subaccount (staging)
│   └── Subaccount (prod)
└── Subaccount (sandbox)

Key Concepts

Global Account: The commercial boundary. All entitlements (service quotas) are assigned here. You get a global account when you purchase BTP.
Directory: Optional organizational grouping. Useful for managing entitlements and access across multiple subaccounts. Directories can contain sub-directories.
Subaccount: The isolation boundary. Each subaccount gets its own:
- Identity zone (XSUAA tenant)
- Cloud Foundry org (if CF is enabled)
- Kyma cluster (if Kyma is enabled)
- Network isolation
- Service instances
Entitlements: Service plans are allocated from Global Account → Directory → Subaccount. An entitlement grants the right to create service instances of a specific plan.

How Quota Works

Global Account: 10 units of HANA Cloud (memory)
├── Directory "Production"
│   ├── Subaccount "prod-eu" → entitled: 6 units
│   └── Subaccount "prod-us" → entitled: 4 units
└── Directory "Non-Production"
    ├── Subaccount "dev" → entitled: 2 units (from remaining pool)
    └── Subaccount "staging" → entitled: 2 units

Some services use numeric quotas (e.g., HANA Cloud memory GB, runtime memory MB). Others use boolean entitlements (entitled or not, e.g., Destination service plan "lite").

Pitfall: Entitlements are not the same as service instances. You must first entitle a subaccount to a service plan, then create a service instance in that subaccount. Forgetting the entitlement step is one of the most common BTP onboarding errors.

3. BTP Service Marketplace & Open Service Broker API

How Service Brokers Work

BTP's service marketplace is built on the Open Service Broker API (OSB API). Every service in the marketplace (HANA Cloud, XSUAA, Destination, Event Mesh, etc.) is backed by a service broker.

┌──────────────┐     OSB API      ┌──────────────────┐
│  cf / BTP    │ ────────────────→ │  Service Broker  │
│  Controller  │  PUT /v2/        │  (e.g., XSUAA    │
│              │  service_instances│   broker)        │
│              │  /v2/            │                  │
│              │  service_bindings │  Provisions the  │
│              │                  │  actual resource  │
└──────────────┘                  └──────────────────┘

The OSB API flow:

Catalog: GET /v2/catalog — broker advertises its service plans
Provision: PUT /v2/service_instances/:id — creates the resource (e.g., an XSUAA tenant, a HANA schema)
Bind: PUT /v2/service_instances/:id/service_bindings/:bid — creates credentials for an app to consume the resource
Unbind / Deprovision: Cleanup

Service Binding Injection

When you bind a service to a CF application, the platform injects credentials via the VCAP_SERVICES environment variable:

{
  "VCAP_SERVICES": {
    "xsuaa": [
      {
        "label": "xsuaa",
        "plan": "application",
        "name": "my-xsuaa",
        "credentials": {
          "clientid": "sb-my-app!t12345",
          "clientsecret": "SECRET",
          "url": "https://mysubaccount.authentication.eu10.hana.ondemand.com",
          "uaadomain": "authentication.eu10.hana.ondemand.com",
          "verificationkey": "-----BEGIN PUBLIC KEY-----\n...",
          "xsappname": "my-app!t12345",
          "identityzone": "mysubaccount",
          "tenantid": "abcd-1234-..."
        }
      }
    ],
    "hana": [
      {
        "label": "hana",
        "plan": "hdi-shared",
        "name": "my-hdi",
        "credentials": {
          "host": "abcdef.hana.prod-eu10.hanacloud.ondemand.com",
          "port": "443",
          "user": "HDI_CONTAINER_USER",
          "password": "...",
          "schema": "MY_HDI_CONTAINER_SCHEMA",
          "url": "jdbc:sap://..."
        }
      }
    ]
  }
}

In Kyma, the BTP Operator creates Kubernetes secrets from service bindings and mounts them into pods as files:

apiVersion: services.cloud.sap.com/v1
kind: ServiceBinding
metadata:
  name: my-xsuaa-binding
spec:
  serviceInstanceName: my-xsuaa
  secretName: my-xsuaa-secret  # K8s Secret created automatically

The secret is then mounted as a volume or injected as env vars into your deployment.

Pitfall for AWS/Azure devs: Unlike AWS where you use IAM roles and instance metadata, BTP services always require explicit binding. There's no implicit credential resolution — you must create a service binding and parse VCAP_SERVICES (CF) or mounted secrets (Kyma).

4. BTP Connectivity: Cloud Connector & Destinations

Cloud Connector Architecture

The Cloud Connector (SCC) enables access to on-premise systems from BTP without opening inbound firewall ports. It works as a reverse-invoke tunnel:

┌─────────────────────┐          ┌─────────────────────┐
│   On-Premise         │          │    SAP BTP           │
│                      │          │                      │
│  ┌────────────────┐  │  TLS    │  ┌────────────────┐  │
│  │ Cloud          │──┼────────→│  │ Connectivity    │  │
│  │ Connector      │  │ outbound│  │ Service         │  │
│  │ (Java process) │  │ only    │  │                 │  │
│  └───────┬────────┘  │          │  └────────┬───────┘  │
│          │           │          │           │          │
│  ┌───────▼────────┐  │          │  ┌────────▼───────┐  │
│  │ SAP S/4HANA    │  │          │  │ Your CF/Kyma   │  │
│  │ (RFC, HTTP,    │  │          │  │ Application    │  │
│  │  LDAP)         │  │          │  │                │  │
│  └────────────────┘  │          │  └────────────────┘  │
└─────────────────────┘          └─────────────────────┘

Key points:

SCC opens an outbound TLS tunnel to BTP's Connectivity Service. No inbound ports needed.
SCC runs as a Java process on-premise (on the same network as your backend systems).
Virtual host mapping: SCC maps virtual-host:virtual-port to actual on-prem-host:port, hiding internal topology.
High availability: Deploy two SCC instances in master-shadow configuration.

Principal Propagation

Principal propagation forwards the end-user identity from BTP through the Cloud Connector to the on-premise system:

User → BTP App (JWT from XSUAA)
         │
         ▼
    Connectivity Service (exchanges JWT for short-lived X.509 cert)
         │
         ▼
    Cloud Connector (presents client certificate via mutual TLS)
         │
         ▼
    On-Premise SAP System (maps X.509 subject to SAP user via trust config)

This requires:

XSUAA configured to include user attributes in the JWT
Cloud Connector configured with a system certificate trusted by the on-premise system
On-premise system's trust store configured to accept the SCC's CA certificate
User mapping rules (e.g., email → SAP user ID)

Destination Service

The Destination Service stores connection details (URL, authentication method, proxy settings) as named configurations:

{
  "Name": "S4HANA_ONPREM",
  "Type": "HTTP",
  "URL": "http://virtual-host:443",
  "ProxyType": "OnPremise",
  "Authentication": "PrincipalPropagation",
  "sap-client": "100"
}

Your application resolves destinations at runtime:

// Using SAP Cloud SDK
HttpDestination destination = DestinationAccessor
    .getDestination("S4HANA_ONPREM")
    .asHttp();

// All requests via this destination go through Cloud Connector
List<BusinessPartner> partners = new DefaultBusinessPartnerService()
    .getAllBusinessPartner()
    .executeRequest(destination);

Pitfall: Destinations are cached. If you rotate credentials in the destination configuration, running application instances may still use stale credentials until the cache expires (default 5 minutes). In production, use CacheExpirationStrategy or restart instances after credential rotation.

5. BTP Security Model — XSUAA Internals

XSUAA Overview

XSUAA (Extended Services for UAA) is BTP's OAuth2 authorization server, based on Cloud Foundry's UAA (User Account and Authentication). It is the central component for:

Issuing JWT tokens
Managing OAuth2 clients (service instances)
Defining and checking scopes/authorities
Multi-tenant identity zone isolation

JWT Token Structure

A typical XSUAA JWT token:

{
  "jti": "abc123...",
  "ext_attr": {
    "enhancer": "XSUAA",
    "subaccountid": "tenant-guid",
    "zdn": "mysubaccount"
  },
  "sub": "user-guid",
  "scope": [
    "my-app!t12345.Admin",
    "my-app!t12345.Viewer",
    "openid"
  ],
  "client_id": "sb-my-app!t12345",
  "cid": "sb-my-app!t12345",
  "azp": "sb-my-app!t12345",
  "grant_type": "authorization_code",
  "user_id": "user-guid",
  "origin": "sap.default",
  "user_name": "john.doe@example.com",
  "email": "john.doe@example.com",
  "given_name": "John",
  "family_name": "Doe",
  "zid": "tenant-guid",
  "aud": ["my-app!t12345", "openid"],
  "iss": "https://mysubaccount.authentication.eu10.hana.ondemand.com/oauth/token",
  "exp": 1700000000,
  "iat": 1699996400
}

Key claims:

zid — tenant ID (identity zone). Critical for multi-tenancy.
scope — array of granted scopes. Format: <xsappname>.<scope-name>
ext_attr.subaccountid — the subaccount that owns this tenant
origin — identity provider origin (e.g., sap.default, corporate-idp)

Scope and Authority Mapping

Defined in xs-security.json:

{
  "xsappname": "my-app",
  "tenant-mode": "dedicated",
  "scopes": [
    { "name": "$XSAPPNAME.Admin", "description": "Administrator" },
    { "name": "$XSAPPNAME.Viewer", "description": "Read-only access" }
  ],
  "role-templates": [
    {
      "name": "AdminRole",
      "scope-references": ["$XSAPPNAME.Admin", "$XSAPPNAME.Viewer"]
    },
    {
      "name": "ViewerRole",
      "scope-references": ["$XSAPPNAME.Viewer"]
    }
  ]
}

The mapping chain:

xs-security.json → Scopes → Role Templates → Role Collections → Users/Groups
                    (code)    (deploy-time)    (BTP cockpit)     (IDP)

Scopes are defined in xs-security.json and deployed with the XSUAA service instance
Role Templates group scopes and are also in xs-security.json
Role Collections are created in BTP Cockpit (or via API) and reference role templates
Users or IDP Groups are assigned to role collections

OAuth2 Flows

Flow	Use Case	Token Endpoint
`authorization_code`	End-user login via browser (Fiori, approuter)	`/oauth/token` with `code`
`client_credentials`	Service-to-service communication (no user context)	`/oauth/token` with `client_id` + `client_secret`
`password` (deprecated)	Testing only — avoid in production	`/oauth/token` with `username` + `password`
`urn:ietf:params:oauth:grant-type:jwt-bearer`	User token exchange (propagate user identity between services)	`/oauth/token` with `assertion` (existing JWT)

User token exchange is the most misunderstood flow. It's used when:

Service A receives a user request with a JWT
Service A needs to call Service B on behalf of the same user
Service A exchanges its JWT for a new JWT scoped to Service B

// Using SAP Cloud SDK for user token exchange
HttpDestination dest = DestinationAccessor
    .getDestination("SERVICE_B")
    .asHttp();
// Cloud SDK automatically handles token exchange if destination
// is configured with Authentication=OAuth2UserTokenExchange

Pitfall from Spring Security background: XSUAA scopes are not the same as Spring Security authorities by default. The spring-xsuaa library maps scopes to Spring authorities by stripping the xsappname prefix. So my-app!t12345.Admin becomes authority Admin. If you're using @PreAuthorize("hasAuthority('Admin')"), this works. But if you compare raw JWT scopes, you'll see the full qualified name.

Top 5 Pitfalls for Java Developers on BTP

Confusing entitlements with service instances. You must entitle a subaccount before you can provision services.
Using Docker assumptions in Cloud Foundry. CF uses buildpacks, not Dockerfiles. Use Kyma if you need custom container images.
Ignoring VCAP_SERVICES parsing. Libraries like @sap/xssec and spring-xsuaa handle this, but custom code that reads env vars directly often breaks when multiple bindings of the same service type exist.
Not configuring principal propagation end-to-end. Missing any step in the chain (XSUAA → Connectivity Service → Cloud Connector → on-prem trust) results in opaque 403 Forbidden errors.
Assuming scopes are globally unique. Scopes are namespaced by xsappname. In multi-tenant scenarios, the xsappname includes a tenant-specific suffix.

What to Learn Next

Lesson 1.2: HANA Cloud deep dive — HDI containers, multi-model engine, performance tuning
Lesson 1.4: Multi-tenancy on BTP — SaaS provisioning, tenant-aware routing, XSUAA identity zones
Lesson 3.1: CAP Java architecture — how CAP abstracts over BTP services
SAP Cloud SDK documentation: how the SDK integrates with Destination and Connectivity services

DEV Community: Aliaksandr Tsviatkou

CAP Advanced Patterns — Drafts, i18n, Audit Logging & Production Readiness

Lesson 3.4 — CAP Advanced Patterns & Production Readiness

Table of Contents

1. Draft Handling

What is Draft?

CDS Annotation

Draft Handler in Java

Draft Timeout

2. Localization (i18n)

CDS Text Bundles

i18n Properties Files

Using Localized Messages in Handlers

3. Temporal Data & Audit Logging

Managed Aspects (Auto-filled Fields)

Audit Logging with @changelog

Soft Delete Pattern

4. Deployment Topologies

MTA (Cloud Foundry)

Helm (Kyma)

CF vs Kyma Deployment Comparison

5. Performance Optimization

Query Optimization

Batch Operations

Connection Pool Tuning

Caching with Spring Cache

Top 5 Pitfalls

What to Learn Next

CAP Remote Services & Mashups — Consuming External APIs

Lesson 3.3 — CAP Remote Services & Mashups

Table of Contents

1. Remote Service Architecture

2. Importing External Service Definitions

Step 1: Download the EDMX

Step 2: Import in CDS

Step 3: Reference in Your Service

3. Destination Configuration

BTP Destination Setup

CAP Configuration for Remote Services

4. Consuming Remote Services in Handlers

Basic Remote Service Call

Mashup: Combine Local + Remote Data

Custom Action: Create in Remote System

5. Error Handling & Resilience

Timeout Configuration

Error Handling Pattern

Caching Remote Data

Top 5 Pitfalls

What to Learn Next

CAP Security & Authorization — XSUAA, @restrict & Multi-Tenant Auth

Lesson 3.2 — CAP Security, Authorization & Authentication

Table of Contents

1. Authentication Architecture

Authentication Flow

JWT Claims Used by CAP

Configuration

2. CDS-Based Authorization

@requires — Role-Based Access to Entire Services/Entities

@restrict — Fine-Grained Operation-Level Authorization

Pseudo-Variables in @restrict

xs-security.json Mapping

3. Programmatic Authorization

Accessing User Info in Handlers

Privileged (Technical) Access

4. Multi-Tenant Security

Tenant Isolation

Cross-Tenant API Calls

5. Testing with Mock Users

Integration Test Setup

Mock Users in application.yaml (Dev Profile)

Top 5 Pitfalls

What to Learn Next

CAP Java Architecture — CDS, Event Handlers & CQN Query API

Lesson 3.1 — CAP Java Architecture & Core Concepts

Table of Contents

1. CAP Java Architecture Overview

CAP = Spring Boot + CDS + Generic Runtime

2. CDS Compilation Pipeline

From .cds to Runtime

Domain Model (schema.cds)