SAP Clean Core Extensibility: Tier Model, ABAP Cloud, and BTP Side-by-Side Extensions

TL;DR

• Bottom line: SAP Clean Core is a governance framework that classifies all S/4HANA extensions into four compliance levels (A-D). Level A (released APIs only, ABAP Cloud or BTP) is the only fully clean approach; the old 3-tier model (Tier 1/2/3) was replaced by this A-D system in August 2025. [src1]
• Key limit: S/4HANA Cloud Public Edition only allows Level A extensions -- no classic ABAP, no unreleased APIs, no modifications. Private Edition and On-Premise allow Levels A-D but only A is "clean." [src3]
• Watch out for: The old Tier 2 "wrapper" pattern (wrapping unreleased SAP objects in standard ABAP and releasing for ABAP Cloud) is now classified as Level B -- technically stable but not fully clean-core compliant. [src1, src2]
• Best for: Any organization planning S/4HANA cloud migration, custom code remediation, or new extension development that needs to remain upgrade-safe. [src4]
• Authentication: BTP side-by-side extensions use OAuth 2.0 (SAML assertion or client credentials) via SAP BTP Destination Service; on-stack ABAP Cloud uses system communication arrangements. [src6]

System Profile

SAP Clean Core is not a single API or product -- it is a strategic framework and governance model that spans all SAP S/4HANA editions (Cloud Public, Cloud Private, and On-Premise). The framework defines how custom extensions, integrations, and configurations should be built to keep the ERP core standard, upgrade-safe, and cloud-ready. It covers six dimensions: clean processes, clean extensions, clean data, clean integration, clean operations, and clean software stack. This card focuses on the clean extensions dimension. [src4]

API Surfaces & Capabilities

SAP Clean Core defines multiple extension surfaces, each with different clean core compliance implications. The fundamental principle is: extensions must access SAP business objects only through well-defined, upgrade-stable interfaces. [src3]

Rate Limits & Quotas

Clean Core does not define traditional API rate limits. Instead, the constraints are governance-based: what you are allowed to develop, and what the ATC will permit through transport pipelines. [src5]

ABAP Cloud Language Restrictions

ATC Governance Thresholds

Authentication

Authentication Gotchas

• BTP side-by-side extensions to S/4HANA Cloud Public Edition must use Communication Arrangements -- direct RFC/HTTP destinations are not available. [src6]
• Principal propagation through SAP Cloud Connector requires matching user stores (IAS/IPS sync) -- mismatched users silently fail authorization checks. [src6]
• OAuth tokens from BTP Destination Service have configurable lifetimes, but the destination configuration caches tokens -- changing token lifetime requires destination recreation or cache flush. [src3]

Constraints

• Cloud Public Edition is Level A only: No classic ABAP development, no unreleased API access, no modifications. All extensions must use key user tools, ABAP Cloud (restricted language), or BTP side-by-side. [src3]
• ABAP Cloud restricts language syntax: No dynpro, no classic reports (WRITE), no direct SAP table access, no classic enhancements. Only released objects from the Cloudification Repository are accessible. [src1]
• Wrappers for unreleased APIs are Level B: The old Tier 2 pattern of wrapping unreleased objects in Standard ABAP and releasing them for ABAP Cloud is now Level B -- technically stable but not fully clean. [src1, src2]
• ATC can block transports: Level D findings can be configured to block transport requests in CI/CD pipelines. [src2, src5]
• BTP requires separate licensing: Side-by-side extensions on BTP are not included in the base S/4HANA license. BTP credits (CPEA or subscription) must be purchased separately. [src3]
• Released API coverage is incomplete: Not all SAP business objects have released APIs yet. Gaps exist especially in industry solutions, complex logistics, and finance sub-modules. [src7]
• ECC systems cannot be clean core: Clean Core applies only to S/4HANA. ECC customers must first migrate to S/4HANA, then remediate custom code. [src4]

Integration Pattern Decision Tree

START -- Organization wants clean core compliant extensions for SAP S/4HANA
|
+-- Which S/4HANA edition?
|   +-- Cloud Public Edition
|   |   +-- Only Level A allowed
|   |   +-- Key user extension? (custom fields, logic, forms)
|   |   |   +-- YES --> Custom Fields & Logic app, SAP Build Process Automation
|   |   |   +-- NO  --> Developer extension needed?
|   |   |       +-- On-stack logic, tight ERP integration --> ABAP Cloud (RAP, released BAdIs)
|   |   |       +-- Independent app, AI/ML, cross-system --> BTP side-by-side (CAP)
|   |   |       +-- Low-code workflow/app --> SAP Build Apps / Process Automation
|   |
|   +-- Cloud Private Edition or On-Premise
|       +-- New development?
|       |   +-- YES --> Target Level A (ABAP Cloud or BTP)
|       |   +-- NO  --> Existing custom code?
|       |       +-- Run ATC CLOUD_READINESS check
|       |       +-- Level A findings? --> Already clean, maintain
|       |       +-- Level B findings? --> Stable but plan migration to released APIs
|       |       +-- Level C findings? --> Monitor via Simplification Database, plan remediation
|       |       +-- Level D findings? --> Remediate immediately (highest risk)
|
+-- What type of extension?
|   +-- Simple configuration (fields, validations)
|   |   --> Key User Extensibility (Level A, no coding)
|   +-- Complex business logic, tight ERP coupling
|   |   --> ABAP Cloud on-stack (Level A) -- use released APIs/BAdIs only
|   |   --> If released API missing: use wrapper (Level B) + log gap for SAP
|   +-- Independent application, UI, or process
|   |   --> BTP side-by-side with CAP (Level A)
|   +-- AI/ML, advanced analytics, cross-system orchestration
|   |   --> BTP side-by-side (Level A) + SAP AI Core / HANA Cloud
|   +-- Legacy interface maintenance
|       --> Classify with ATC, plan migration path, target Level A
|
+-- Custom code migration (ECC or classic S/4HANA)?
    +-- Step 1: Run Custom Code Migration app against source system
    +-- Step 2: Analyze ATC findings by clean core level (A/B/C/D)
    +-- Step 3: Prioritize -- eliminate Level D first, then C, then B
    +-- Step 4: For each finding: keep + wrap (B) vs. rewrite (A) vs. retire
    +-- Step 5: New development in ABAP Cloud only

Quick Reference

Clean Core Levels at a Glance

Old 3-Tier to New A-D Mapping

Key User vs Developer vs Side-by-Side Extensibility

Step-by-Step Integration Guide

1. Assess existing custom code with ATC

Run the ABAP Test Cockpit with the CLOUD_READINESS check variant to classify all custom code objects by clean core level. [src5]

" In SAP GUI: transaction ATC or SE80 > ATC
" Or via BTP ABAP Environment for remote analysis:
" 1. Configure central ATC on BTP (recommended by SAP)
" 2. Connect source S/4HANA system via RFC
" 3. Run check variant CLOUD_READINESS against Z* / Y* namespaces
" 4. Export findings report (Excel or ALV)

Verify: ATC results show findings categorized as Informational (Level B), Warning (Level C), or Error (Level D). No findings = Level A compliant.

2. Build an on-stack ABAP Cloud extension (Level A)

Create a new development object using ABAP Cloud language version. Only released APIs are accessible. [src1]

" In ABAP Development Tools (Eclipse):
" 1. Create a new ABAP Package with language version "ABAP for Cloud Development"
" 2. All objects in this package are restricted to ABAP Cloud syntax

@AbapCatalog.viewEnhancementCategory: [#NONE]
@AccessControl.authorizationCheck: #CHECK
@EndUserText.label: 'Custom Sales Order View'
define view entity ZI_SalesOrderCustom
  as select from I_SalesOrder  " <-- released CDS view (Level A)
{
  key SalesOrder,
      SalesOrganization,
      SoldToParty,
      TotalNetAmount,
      TransactionCurrency
}
where SalesOrganization = '1000'

Verify: ATC run on the new object shows zero findings. Object deploys without transport errors.

3. Create a wrapper for an unreleased API (Level B, temporary)

When a released API does not exist for your use case, create a wrapper in Standard ABAP and release it for ABAP Cloud consumption. Plan to remove the wrapper once SAP releases the official API. [src1]

" Step 1: Create wrapper class in Standard ABAP (language version: Standard)
CLASS zcl_wrapper_example DEFINITION PUBLIC FINAL CREATE PUBLIC.
  PUBLIC SECTION.
    CLASS-METHODS get_material_data
      IMPORTING iv_matnr       TYPE matnr
      RETURNING VALUE(rs_data) TYPE mara.
ENDCLASS.

CLASS zcl_wrapper_example IMPLEMENTATION.
  METHOD get_material_data.
    SELECT SINGLE * FROM mara INTO rs_data WHERE matnr = iv_matnr.
  ENDMETHOD.
ENDCLASS.

" Step 2: Release wrapper class for ABAP Cloud: Properties > API State > Released
" Step 3: In ABAP Cloud code, consume the released wrapper
" Step 4: When SAP releases the API, replace wrapper with released API

Verify: ATC on the ABAP Cloud consumer shows Informational finding (Level B).

4. Build a BTP side-by-side extension with CAP

Create an independent application on SAP BTP that connects to S/4HANA via APIs. [src3, src6]

# Scaffold a CAP project
npm init -y
npm add @sap/cds @sap/cds-dk
npx cds init my-extension --add hana,approuter

# Import S/4HANA OData service definition
cd my-extension
npx cds import API_SALES_ORDER_SRV.edmx --as external

# Deploy to Cloud Foundry
cf login -a https://api.cf.<region>.hana.ondemand.com
npx cds build --production
cf push

Verify: cf apps shows the application running. API returns data from S/4HANA.

Code Examples

Python: Check released APIs via Cloudification Repository

# Input:  GitHub Cloudification Repository JSON
# Output: List of released objects matching a search term
import requests  # requests==2.31.0

CLOUDIFICATION_REPO_URL = (
    "https://raw.githubusercontent.com/SAP/abap-atc-cr-cv-s4hc/"
    "main/src/objectReleaseInfo_s4hc2408.json"
)

def search_released_objects(search_term: str, max_results: int = 20):
    resp = requests.get(CLOUDIFICATION_REPO_URL, timeout=30)
    resp.raise_for_status()
    data = resp.json()
    results = []
    term_lower = search_term.lower()
    for obj in data.get("objectReleaseInfo", []):
        obj_name = obj.get("objectName", "").lower()
        if term_lower in obj_name:
            results.append({
                "name": obj.get("objectName"),
                "type": obj.get("objectType"),
                "release_state": obj.get("releaseState"),
            })
            if len(results) >= max_results:
                break
    return results

released = search_released_objects("salesorder")
for obj in released:
    print(f"  {obj['type']:10s} {obj['name']:40s} [{obj['release_state']}]")

ABAP: Check if an object is released for ABAP Cloud

" Input:  Object name (class, CDS view, etc.)
" Output: Release state (released / not released / deprecated)

" Method 1: Use XCO library (available in ABAP Cloud)
DATA(lo_class) = xco_cp_abap=>class( 'CL_SOME_SAP_CLASS' ).
DATA(lv_release_state) = lo_class->content( )->get_release_state( ).
" Returns: if_xco_ar_release_state=>co_released

" Method 2: Use Cloudification Repository Viewer (Fiori app)
" App ID: F5670 - ABAP Cloud Readiness

" Method 3: ATC Check (most comprehensive)
" Transaction ATC > Run with CLOUD_READINESS variant

Data Mapping

Extension Pattern to Clean Core Level Mapping

Data Type Gotchas

• ABAP Cloud uses strict typing -- implicit type conversions common in classic ABAP (e.g., MOVE between incompatible types) are not allowed. [src1]
• Released APIs may return different field names than the underlying database table columns (e.g., released CDS I_SalesOrder.SalesOrder vs table VBAK-VBELN). Always use the released API field names. [src7]
• CDS views in ABAP Cloud expose SAP HANA types (NVARCHAR, DECIMAL) differently than classic dictionary types (CHAR, CURR). Field length mismatches can cause silent truncation. [src1]

Error Handling & Failure Points

Common ATC / Clean Core Errors

Failure Points in Production

• Custom code migration underestimates scope: ATC findings often multiply during detailed analysis -- a 500-object assessment can reveal 5,000+ individual findings. Fix: Run ATC early in project planning, not during build phase. [src5]
• Wrapper proliferation: Creating too many Level B wrappers creates a "shadow API" layer that is expensive to maintain and track. Fix: Maintain a wrapper registry with SAP Influence request numbers; set quarterly review cadence. [src1]
• BTP extension loses connectivity to S/4HANA: Destination Service tokens expire, Cloud Connector tunnels drop, or Communication Arrangement deactivated during upgrade. Fix: Implement health check endpoints; set up BTP Alert Notification Service for destination failures. [src3]
• ATC variant mismatch between dev and CI/CD: Development system uses a different ATC check variant than the CI/CD pipeline, causing findings to appear only at transport time. Fix: Standardize on SAP-delivered CLOUD_READINESS variant across all systems. [src5]
• Key user extensions break after upgrade: Custom fields using customer logic (BRFplus rules) can reference fields that change in new S/4HANA releases. Fix: Test key user extensions in sandbox system before production upgrade. [src6]

Anti-Patterns

Wrong: Wrapping every unreleased object into Level B

" BAD -- creating hundreds of wrappers to make classic code "technically" compliant
" This creates unmanageable technical debt and a shadow API layer
CLASS zcl_wrap_mara DEFINITION PUBLIC CREATE PUBLIC.
  PUBLIC SECTION.
    CLASS-METHODS get IMPORTING iv TYPE matnr RETURNING VALUE(rs) TYPE mara.
ENDCLASS.
CLASS zcl_wrap_bseg DEFINITION PUBLIC CREATE PUBLIC.
  PUBLIC SECTION.
    CLASS-METHODS get IMPORTING iv TYPE belnr_d RETURNING VALUE(rs) TYPE bseg.
ENDCLASS.
" ... 200 more wrappers ...

Correct: Evaluate each gap and choose the right strategy

" GOOD -- decision tree for each unreleased object:
" 1. Does a released API exist? --> Use it (Level A)
" 2. Is the functionality still needed? --> Maybe retire the custom code
" 3. Can it be rebuilt as a BTP extension? --> Side-by-side (Level A)
" 4. No alternative exists? --> Create ONE wrapper, log SAP Influence request,
"    set review date, and document in wrapper registry

Wrong: Building new classic ABAP without checking released alternatives

" BAD -- developer creates a classic report because "that's how we always did it"
REPORT zsd_order_list.
SELECT * FROM vbak INTO TABLE @DATA(lt_orders)
  WHERE erdat >= @sy-datum - 30.
LOOP AT lt_orders INTO DATA(ls_order).
  WRITE: / ls_order-vbeln, ls_order-erdat, ls_order-netwr.
ENDLOOP.

Correct: Use ABAP Cloud with RAP and released CDS views

" GOOD -- same requirement, Level A compliant
" 1. Create a CDS view consuming released I_SalesOrder
" 2. Expose via RAP service binding (OData V4)
" 3. Build Fiori Elements list report (zero UI code)

@EndUserText.label: 'Recent Sales Orders'
define view entity ZC_RecentSalesOrders
  as select from I_SalesOrder
{
  key SalesOrder,
      CreationDate,
      TotalNetAmount,
      TransactionCurrency
}
where CreationDate >= $session.system_date - 30

Common Pitfalls

• Confusing "clean" with "no custom code": Clean Core does not mean zero customization. It means all customizations use released APIs and sanctioned extension points. Fix: Use the extension decision tree: key user > ABAP Cloud > BTP side-by-side. [src4]
• Skipping the ATC assessment: Starting custom code migration without running ATC first leads to uncontrolled scope. Fix: Run ATC with CLOUD_READINESS variant on all Z*/Y* objects as the first project activity. [src5]
• Assuming all BAPIs are Level B: Some classic BAPIs access internal objects that make them Level C. Fix: Check each BAPI against the Cloudification Repository. [src7]
• Not accounting for BTP licensing costs: Side-by-side extensions require BTP credits which can add 15-30% to total project cost. Fix: Include BTP licensing in the business case. Use SAP Discovery Center to estimate credit consumption. [src3]
• Ignoring the Simplification Database (SDB): The SDB tracks SAP internal object changes across releases. Level C objects that change in SDB will break during upgrades. Fix: Subscribe to SDB notifications for all Level C objects in your landscape. [src2]
• Building complex extensions as key user config: Key user extensibility is for simple fields, validations, and forms -- not complex business logic. Fix: If the extension requires ABAP code, external API calls, or complex data models, use developer extensibility or BTP. [src6]

Diagnostic Commands

" Check ATC findings for a specific package
" Transaction: ATC
" 1. Create/select check variant: CLOUD_READINESS
" 2. Object scope: Package = Z_MY_PACKAGE (including subpackages)
" 3. Execute > Review findings by priority (Error > Warning > Info)

" Check released status of a specific object
" Transaction: SE80 or ADT (Eclipse)
" Navigate to object > Properties > API State
" Released = Level A compatible

" Check Clean Core Dashboard metrics
" SAP for Me > Clean Core Dashboard (S/4HANA Cloud Private Edition)

" Cloudification Repository (programmatic check)
" GitHub: https://github.com/SAP/abap-atc-cr-cv-s4hc

# Check Cloudification Repository for a specific object (command line)
curl -s "https://raw.githubusercontent.com/SAP/abap-atc-cr-cv-s4hc/main/src/objectReleaseInfo_s4hc2408.json" \
  | python3 -c "
import json, sys
data = json.load(sys.stdin)
term = 'salesorder'
for obj in data.get('objectReleaseInfo', []):
    if term.lower() in obj.get('objectName', '').lower():
        print(f\"{obj['objectType']:10s} {obj['objectName']:40s} [{obj['releaseState']}]\")
"

Version History & Compatibility

Deprecation Policy

SAP does not deprecate clean core levels -- they are cumulative and backward-compatible. SAP commits to a 2-year deprecation notice for any released API that will be removed. The Cloudification Repository on GitHub is updated with each S/4HANA release. [src1, src7]

When to Use / When Not to Use

Important Caveats

• The A-D level concept was introduced in August 2025 and is still being adopted across SAP's own documentation. Some older SAP materials still reference the 3-tier model (Tier 1/2/3). When in doubt, refer to the ABAP Extensibility Guide (August 2025 Update). [src1]
• Clean core compliance is a spectrum, not binary. Most large S/4HANA landscapes will have a mix of Level A, B, and C code. The goal is continuous improvement toward Level A, not immediate perfection. [src4]
• The Cloudification Repository coverage varies significantly by S/4HANA functional area. Finance and Sales have the most released APIs; Industry Solutions, Plant Maintenance, and Quality Management have significant gaps as of early 2026. [src7]
• BTP side-by-side extensions introduce operational complexity (separate deployment, monitoring, networking) that may not be justified for simple extensions. Key user extensibility or ABAP Cloud on-stack should be preferred when the extension is tightly coupled to ERP data. [src3]
• SAP's Clean Core Dashboard (in SAP for Me) is currently available only for S/4HANA Cloud Private Edition productive systems. On-premise customers must rely on local ATC reports for compliance tracking. [src2]