The 3-Tier Model in ABAP Cloud: Structured Migration from Classic ABAP

Why a Tier Model?

Migration from Classic ABAP to ABAP Cloud is not a task that can be accomplished overnight. Most companies have millions of lines of custom code that need to be modernized step by step. The 3-tier model offers a structured approach for this:

Clear separation between cloud-ready and legacy code
Controlled migration without big-bang risk
Reusability of existing functionality through wrappers
ATC compliance through clean layer separation

The Three Tiers at a Glance

┌─────────────────────────────────────────────────────────┐
│ TIER-1: ABAP Cloud                                      │
│ ───────────────────                                     │
│ • New developments                                      │
│ • RAP Business Objects                                  │
│ • Only Released APIs                                    │
│ • ABAP Cloud language version                           │
│ • Future-proof & cloud-ready                            │
└─────────────────────┬───────────────────────────────────┘
                      │ Calls only via Released APIs
                      ▼
┌─────────────────────────────────────────────────────────┐
│ TIER-2: API Wrapper                                     │
│ ───────────────────                                     │
│ • Encapsulates Classic ABAP functionality               │
│ • Provides Released APIs (C1 Contract)                  │
│ • Bridge between Cloud and Classic                      │
│ • Contains transformation logic                         │
└─────────────────────┬───────────────────────────────────┘
                      │ Internal calls
                      ▼
┌─────────────────────────────────────────────────────────┐
│ TIER-3: Classic ABAP                                    │
│ ───────────────────                                     │
│ • Existing legacy code                                  │
│ • Non-released APIs                                     │
│ • Direct DB access                                      │
│ • Gradually migrated or phased out                      │
└─────────────────────────────────────────────────────────┘

TIER-1: ABAP Cloud

TIER-1 is the top layer and contains exclusively ABAP Cloud-compliant code. All new developments are done here, and strict rules apply:

Characteristics of TIER-1

Language version: ABAP for Cloud Development
APIs: Only Released APIs (C1 Contract)
Programming model: RAP (ABAP RESTful Application Programming Model)
Development environment: ABAP Development Tools (ADT)

Flight Booking Example: RAP Business Object

" TIER-1: CDS View for flight bookings (ABAP Cloud)
@AccessControl.authorizationCheck: #CHECK
@EndUserText.label: 'Flight Booking'
define root view entity ZI_FlightBooking
  as select from zflight_book
{
  key booking_id     as BookingId,
      flight_id      as FlightId,
      customer_id    as CustomerId,
      booking_date   as BookingDate,
      @Semantics.amount.currencyCode: 'CurrencyCode'
      price          as Price,
      currency_code  as CurrencyCode,
      booking_status as BookingStatus
}

The corresponding behavior definition defines the business logic:

" TIER-1: Behavior Definition
managed implementation in class zbp_i_flightbooking unique;
strict ( 2 );

define behavior for ZI_FlightBooking alias FlightBooking
persistent table zflight_book
lock master
authorization master ( instance )
{
  create;
  update;
  delete;

  " Action to confirm the booking
  action confirmBooking result [1] $self;

  " Validation of booking data
  validation validateCustomer on save
    { field CustomerId; }

  " Mapping for legacy fields
  mapping for zflight_book
  {
    BookingId     = booking_id;
    FlightId      = flight_id;
    CustomerId    = customer_id;
    BookingDate   = booking_date;
    Price         = price;
    CurrencyCode  = currency_code;
    BookingStatus = booking_status;
  }
}

For more on RAP and Business Objects, see the article RAP Basics.

TIER-2: API Wrapper

TIER-2 is the bridge between ABAP Cloud and Classic ABAP. Wrapper classes are created here that encapsulate classic functionality and provide it as Released APIs.

Characteristics of TIER-2

Language version: Standard ABAP (Classic)
API status: Released (C1 Contract)
Task: Encapsulation and transformation
ATC check: Must be clean for release

Flight Booking Example: API Wrapper

" TIER-2: Wrapper class for flight data access
" API Status: Released (C1 Contract)
CLASS zcl_flight_api DEFINITION
  PUBLIC
  FINAL
  CREATE PUBLIC.

  PUBLIC SECTION.
    TYPES:
      BEGIN OF ty_flight_info,
        flight_id    TYPE zflight_id,
        carrier_id   TYPE s_carr_id,
        connection   TYPE s_conn_id,
        flight_date  TYPE s_date,
        seats_free   TYPE s_seatsocc,
        price        TYPE s_price,
        currency     TYPE s_currcode,
      END OF ty_flight_info,
      tt_flight_info TYPE STANDARD TABLE OF ty_flight_info WITH EMPTY KEY.

    " Released API for TIER-1
    CLASS-METHODS get_available_flights
      IMPORTING
        iv_carrier    TYPE s_carr_id OPTIONAL
        iv_date_from  TYPE s_date OPTIONAL
        iv_date_to    TYPE s_date OPTIONAL
      RETURNING
        VALUE(rt_flights) TYPE tt_flight_info
      RAISING
        cx_flight_not_found.

    CLASS-METHODS check_seat_availability
      IMPORTING
        iv_flight_id  TYPE zflight_id
        iv_seats      TYPE i
      RETURNING
        VALUE(rv_available) TYPE abap_bool.

  PRIVATE SECTION.
    " Internal helper for TIER-3 access
    CLASS-METHODS _fetch_from_legacy
      IMPORTING
        iv_carrier   TYPE s_carr_id OPTIONAL
      RETURNING
        VALUE(rt_data) TYPE tt_flight_info.
ENDCLASS.

CLASS zcl_flight_api IMPLEMENTATION.
  METHOD get_available_flights.
    " Calls TIER-3 logic and transforms data
    DATA(lt_legacy_data) = _fetch_from_legacy( iv_carrier ).

    " Filtering and preparation for cloud consumers
    LOOP AT lt_legacy_data INTO DATA(ls_flight).
      IF ( iv_date_from IS INITIAL OR ls_flight-flight_date >= iv_date_from )
         AND ( iv_date_to IS INITIAL OR ls_flight-flight_date <= iv_date_to ).
        APPEND ls_flight TO rt_flights.
      ENDIF.
    ENDLOOP.

    IF rt_flights IS INITIAL.
      RAISE EXCEPTION TYPE cx_flight_not_found.
    ENDIF.
  ENDMETHOD.

  METHOD check_seat_availability.
    " Wrapper for legacy availability check
    DATA(lo_legacy) = NEW zcl_flight_legacy( ).
    rv_available = lo_legacy->check_seats(
      iv_flight_id = iv_flight_id
      iv_seats     = iv_seats
    ).
  ENDMETHOD.

  METHOD _fetch_from_legacy.
    " TIER-3 call - non-released APIs encapsulated
    " Direct access to SFLIGHT (not released)
    SELECT flight_id, carrid, connid, fldate, seatsocc, price, currency
      FROM sflight
      WHERE carrid = @iv_carrier OR @iv_carrier IS INITIAL
      INTO CORRESPONDING FIELDS OF TABLE @rt_data.
  ENDMETHOD.
ENDCLASS.

TIER-3: Classic ABAP

TIER-3 contains the existing legacy code that is gradually modernized or phased out. This code uses non-released APIs and direct database access.

Characteristics of TIER-3

Language version: Standard ABAP (Classic)
APIs: Non-released, internal SAP objects
Access: Direct DB access, BAPIs, Function Modules
Goal: Migration to TIER-1 or encapsulation through TIER-2

Flight Booking Example: Legacy Code

" TIER-3: Legacy class (only called by TIER-2)
CLASS zcl_flight_legacy DEFINITION
  PUBLIC
  FINAL
  CREATE PUBLIC.

  PUBLIC SECTION.
    METHODS check_seats
      IMPORTING
        iv_flight_id TYPE zflight_id
        iv_seats     TYPE i
      RETURNING
        VALUE(rv_available) TYPE abap_bool.

    METHODS book_flight_legacy
      IMPORTING
        iv_flight_id  TYPE zflight_id
        iv_customer   TYPE kunnr
        iv_seats      TYPE i
      EXPORTING
        ev_booking_id TYPE zbook_id
      RAISING
        cx_booking_failed.
ENDCLASS.

CLASS zcl_flight_legacy IMPLEMENTATION.
  METHOD check_seats.
    " Direct access to non-released table
    SELECT SINGLE seatsmax, seatsocc
      FROM sflight
      WHERE flight_id = @iv_flight_id
      INTO @DATA(ls_flight).

    IF sy-subrc = 0.
      rv_available = xsdbool( ls_flight-seatsmax - ls_flight-seatsocc >= iv_seats ).
    ENDIF.
  ENDMETHOD.

  METHOD book_flight_legacy.
    " Legacy BAPI call
    CALL FUNCTION 'BAPI_FLIGHT_BOOKING_CREATE'
      EXPORTING
        flight_id      = iv_flight_id
        customer       = iv_customer
        seats_required = iv_seats
      IMPORTING
        booking_number = ev_booking_id
      EXCEPTIONS
        flight_full    = 1
        OTHERS         = 2.

    IF sy-subrc <> 0.
      RAISE EXCEPTION TYPE cx_booking_failed.
    ENDIF.
  ENDMETHOD.
ENDCLASS.

For detailed information on the distinction between Classic and Cloud ABAP, see ABAP Cloud vs Classic ABAP.

The Authorization Object S_ABPLNGVS

A central element for controlling language versions is the authorization object S_ABPLNGVS. It controls which ABAP language version a developer may use in which packages.

Fields of the Authorization Object

Field	Meaning	Values
`ACTIVITY`	Activity	`01` (Create), `02` (Change), `03` (Display)
`DEVCLASS`	Package	Package name or `*` for all
`ABPLNGVS`	Language version	`STANDARD`, `ABAP_FOR_CLOUD_DEVELOPMENT`

Example Configuration

Role: Z_ABAP_CLOUD_DEVELOPER
─────────────────────────────────
S_ABPLNGVS:
  ACTIVITY: 01, 02, 03
  DEVCLASS: ZT1_*
  ABPLNGVS: ABAP_FOR_CLOUD_DEVELOPMENT

S_ABPLNGVS:
  ACTIVITY: 01, 02, 03
  DEVCLASS: ZT2_*, ZT3_*
  ABPLNGVS: STANDARD

This configuration allows:

ABAP Cloud development only in packages with prefix ZT1_
Classic ABAP in packages with prefix ZT2_ and ZT3_

Practical Tips for Package Organization

A well-thought-out package structure is crucial for the successful implementation of the 3-tier model.

Recommended Naming Convention

Z<PROJECT>_<TIER>_<AREA>

Examples:
─────────────────────────────────────────────
ZFB_T1_BOOKING     → TIER-1, Flight Booking (ABAP Cloud)
ZFB_T1_REPORTING   → TIER-1, Reporting (ABAP Cloud)
ZFB_T2_FLIGHT_API  → TIER-2, Flight API Wrapper
ZFB_T2_CUSTOMER    → TIER-2, Customer API Wrapper
ZFB_T3_LEGACY      → TIER-3, Legacy Code
ZFB_T3_MIGRATION   → TIER-3, Objects to be migrated

Package Structure for Flight Booking

$ZFB (Superpackage)
├── ZFB_T1 (TIER-1 Main Package)
│   ├── ZFB_T1_BOOKING
│   │   ├── ZI_FlightBooking (CDS Entity)
│   │   ├── ZBP_I_FlightBooking (Behavior Impl.)
│   │   └── ZUI_FlightBooking_O4 (Service Binding)
│   ├── ZFB_T1_CUSTOMER
│   │   └── ... (Customer Management)
│   └── ZFB_T1_REPORTING
│       └── ... (Reports)
│
├── ZFB_T2 (TIER-2 Main Package)
│   ├── ZFB_T2_FLIGHT_API
│   │   ├── ZCL_FLIGHT_API (Released Wrapper)
│   │   └── ZIF_FLIGHT_API (Interface)
│   └── ZFB_T2_PRICING
│       └── ZCL_PRICING_API (Pricing Calculation)
│
└── ZFB_T3 (TIER-3 Main Package)
    ├── ZFB_T3_LEGACY
    │   ├── ZCL_FLIGHT_LEGACY
    │   └── ZFLIGHT_BOOKING_FORM (old Report)
    └── ZFB_T3_DEPRECATED
        └── ... (deprecated objects)

Set Language Version per Package

In Package Properties in ADT:

ZFB_T1_BOOKING:
  Properties → ABAP Language Version → "ABAP for Cloud Development"
  → Compiler enforces ABAP Cloud rules!

ZFB_T2_FLIGHT_API:
  Properties → ABAP Language Version → "Standard ABAP"
  → Allows Classic ABAP, but API must be released

ZFB_T3_LEGACY:
  Properties → ABAP Language Version → "Standard ABAP"
  → Full freedom, but only used internally

Software Component Structure

For larger projects, organization in software components is recommended:

" Software components for flight booking system
"
" Component: ZFLIGHTBOOKING
" ───────────────────────────────────────────
" Transport Layer: ZDEV
" Delivery Unit: ZFLIGHTBOOKING_DU
"
" Structure:
" ├── Application Layer (TIER-1)
" │   └── Package: ZFB_T1 (ABAP Cloud)
" │
" ├── API Layer (TIER-2)
" │   └── Package: ZFB_T2 (Standard + Released)
" │
" └── Legacy Layer (TIER-3)
"     └── Package: ZFB_T3 (Standard, not released)

Dependency Rules

┌─────────────────────────────────────────────────────────┐
│                    Allowed Calls                         │
├─────────────────────────────────────────────────────────┤
│ TIER-1 → TIER-2    ✅ (via Released APIs)               │
│ TIER-1 → TIER-3    ❌ (forbidden - ATC error!)          │
│ TIER-2 → TIER-3    ✅ (internal encapsulation)          │
│ TIER-3 → TIER-2    ⚠️ (possible, but not recommended)   │
│ TIER-3 → TIER-1    ❌ (circular dependency)             │
└─────────────────────────────────────────────────────────┘

Migration Strategy: From TIER-3 to TIER-1

The long-term strategy is the gradual migration from TIER-3 to TIER-1:

Phase 1: Identification
─────────────────────────
• Analyze TIER-3 code
• Run ATC checks
• Document dependencies

Phase 2: Wrapper (TIER-2)
─────────────────────────
• API wrapper for critical functions
• Define Released APIs
• Write tests

Phase 3: Migration (TIER-1)
─────────────────────────
• New RAP implementation
• Replace TIER-2 wrapper
• Decommission legacy code

Phase 4: Cleanup
─────────────────────────
• Delete TIER-3 code
• Remove TIER-2 wrapper
• Only TIER-1 remains

For a detailed migration guide, see ABAP Cloud Migration Guide.

Conclusion

The 3-tier model provides a structured approach for migration to ABAP Cloud:

TIER-1 (ABAP Cloud): Future-proof new developments
TIER-2 (API Wrapper): Bridge to the legacy world
TIER-3 (Classic ABAP): Legacy code to be migrated

Through clear package organization with T1/T2/T3 prefixes, the authorization object S_ABPLNGVS, and consistent API encapsulation, gradual modernization succeeds without risk.

Important: SAP has since introduced the Clean Core Level Concept (A-D) as a simplified alternative that reduces the complexity of the 3-tier model. Evaluate both approaches and choose the one that fits your project.