Tier 2 Quarantine Wrapper: Step-by-Step Architecture Guide

In modern SAP S/4HANA (Cloud Private Edition and On-Premise), enterprise development teams must migrate towards Language Version 5 (ABAP Cloud). However, many standard SAP objects and classic BAPIs do not yet have a direct C1-released public interface.

The official SAP 3-Tier Extensibility Model introduces Tier 2 (Cloud API Enablement) specifically to solve this challenge.

🏛️ The Architecture Principle

┌─────────────────────────────────────────────────────────────┐
│ Tier 1: ABAP Cloud Business Logic (Language Version 5)       │
│ - Strict ABAP Cloud rules                                   │
│ - Modern RAP Business Objects & CDS View Entities           │
└───────────────────────────┬─────────────────────────────────┘
                            │ Calls Released Wrapper Contract
                            ▼
┌─────────────────────────────────────────────────────────────┐
│ Tier 2: Quarantine Wrapper (Language Version: Standard)      │
│ - Package: Z_TIER2_QUARANTINE (Clean Core Governance)       │
│ - Encapsulates non-released BAPI / Table / Function Module  │
│ - Exposes strictly typed, clean C1-compatible interface     │
└───────────────────────────┬─────────────────────────────────┘
                            │ Calls Classic Unreleased Logic
                            ▼
┌─────────────────────────────────────────────────────────────┐
│ Classic SAP Core (Unreleased Tables & Function Modules)     │
│ - BAPI_SALESORDER_SIMULATE, VBAK, VBAP, BSEG                │
└─────────────────────────────────────────────────────────────┘

💻 Concrete Implementation Pattern

Step 1: Define the Clean Wrapper Interface

INTERFACE zif_tier2_sales_wrapper
  PUBLIC.

  TYPES:
    BEGIN OF ty_order_header,
      sales_org  TYPE c LENGTH 4,
      distr_chan TYPE c LENGTH 2,
      division   TYPE c LENGTH 2,
      doc_type   TYPE c LENGTH 4,
    END OF ty_order_header,

    BEGIN OF ty_order_item,
      material TYPE c LENGTH 40,
      quantity TYPE p LENGTH 7 DECIMALS 3,
    END OF ty_order_item,

    tt_order_items TYPE STANDARD TABLE OF ty_order_item WITH DEFAULT KEY,

    BEGIN OF ty_simulation_result,
      net_value TYPE p LENGTH 8 DECIMALS 2,
      currency  TYPE c LENGTH 5,
      is_valid  TYPE abap_bool,
    END OF ty_simulation_result.

  METHODS simulate_sales_order
    IMPORTING
      is_header       TYPE ty_order_header
      it_items        TYPE tt_order_items
    RETURNING
      VALUE(rs_result) TYPE ty_simulation_result
    RAISING
      cx_clean_core_quarantine_error.

ENDINTERFACE.

Step 2: Implement the Quarantine Class (Standard ABAP with Clean Boundary)

CLASS zcl_tier2_sales_quarantine DEFINITION
  PUBLIC
  FINAL
  CREATE PUBLIC.

  PUBLIC SECTION.
    INTERFACES zif_tier2_sales_wrapper.
    ALIASES simulate_sales_order FOR zif_tier2_sales_wrapper~simulate_sales_order.

  PROTECTED SECTION.
  PRIVATE SECTION.
ENDCLASS.

CLASS zcl_tier2_sales_quarantine IMPLEMENTATION.

  METHOD zif_tier2_sales_wrapper~simulate_sales_order.
    DATA: ls_bapi_header TYPE bapisdhead,
          lt_bapi_items  TYPE STANDARD TABLE OF bapisditem,
          lt_bapi_return TYPE STANDARD TABLE OF bapiret2.

    " Map clean typed input to classic legacy structure
    ls_bapi_header-doc_type   = is_header-doc_type.
    ls_bapi_header-sales_org  = is_header-sales_org.
    ls_bapi_header-distr_chan = is_header-distr_chan.
    ls_bapi_header-division   = is_header-division.

    LOOP AT it_items INTO DATA(ls_item).
      APPEND VALUE #( material = ls_item-material
                      target_qty = ls_item-quantity ) TO lt_bapi_items.
    ENDLOOP.

    " Isolated classic call inside Tier 2 quarantine
    CALL FUNCTION 'BAPI_SALESORDER_SIMULATE'
      EXPORTING
        order_header_in = ls_bapi_header
      TABLES
        order_items_in  = lt_bapi_items
        return          = lt_bapi_return.

    " Process return contract and sanitize exceptions
    LOOP AT lt_bapi_return INTO DATA(ls_ret) WHERE type CA 'EA'.
      RAISE EXCEPTION TYPE cx_clean_core_quarantine_error
        EXPORTING
          textid = cx_clean_core_quarantine_error=>classic_bapi_failed
          msgv1  = ls_ret-message.
    ENDLOOP.

    rs_result-is_valid = abap_true.
  ENDMETHOD.

ENDCLASS.

Step 3: Consume from Tier 1 (ABAP Cloud RAP Behavior Pool)

In Tier 1, code is strictly compiled under Language Version 5: * Direct CALL FUNCTION 'BAPI_...' is a hard compilation syntax error. * Direct SELECT FROM vbak is a hard compilation syntax error. * Instead, Tier 1 instantiates zif_tier2_sales_wrapper:

" Compiled with ABAP Cloud (Language Version 5)
CLASS lcl_sales_order_handler DEFINITION INHERITING FROM cl_abap_behavior_handler.
  PRIVATE SECTION.
    METHODS validateOrder FOR VALIDATE ON SAVE
      IMPORTING keys FOR SalesOrder~validateOrder.
ENDCLASS.

CLASS lcl_sales_order_handler IMPLEMENTATION.
  METHOD validateOrder.
    DATA(lo_wrapper) = CAST zif_tier2_sales_wrapper( 
      zcl_tier2_factory=>get_sales_wrapper( ) 
    ).

    TRY.
        DATA(ls_sim) = lo_wrapper->simulate_sales_order( ... ).
      CATCH cx_clean_core_quarantine_error INTO DATA(lx_err).
        APPEND VALUE #( %msg = new_message_with_text( lx_err->get_text( ) ) ) 
               TO reported-salesorder.
    ENDTRY.
  ENDMETHOD.
ENDCLASS.

🎯 Clean Core Governance Rules for Tier 2

1. Explicit Quarantine Package: All Tier 2 wrappers must live in dedicated packages (e.g., Z_TIER2_*) marked in ATC (ABAP Test Cockpit).
2. Successor Deprecation Contract: When SAP releases an official C1 API successor, the Tier 2 wrapper class is replaced internally without modifying any Tier 1 consumers.
3. No Database Writes: Tier 2 wrappers must never execute direct raw DB updates (UPDATE / INSERT) on SAP standard tables. All persistence must go through transactional APIs.

📚 Complete Engineering Publications

• 📦 The Complete Clean Core & SAP BTP Enterprise Suite — 95-Page master PDF guide, 40 Retina diagrams, 61 production-grade code listings, and Notion workspace.
• 📚 The Definitive Guide to ABAP Cloud (Amazon Paperback & Kindle).
• 📄 Download the Free 19-Page Sample PDF.