... END OF BLOCK`. --- ### 8. Program Events in Report Programs - **INITIALIZATION**: Executes first when opening a report program, used for initializing defaults. - **AT SELECTION-SCREEN**: Triggers when user interacts with or submits the selection screen, ideal for input validation. - **START-OF-SELECTION**: Kicks off upon pressing Execute (**F8**), containing core business processing and data queries. --- ### 9. Operations, Date/Time Arithmetic & System Variables - **Arithmetic Operations**: Uses standard operators (`+`, `-`, `*`, `/`), integer division (`DIV`), modulo (`MOD`), and square root (`SQRT`). - **Date (D) & Time (T) Calculations**: Automatically calculates date/time rollovers (e.g., adding 1 day to `20231231` yields `20240101`). Substring offset access uses `<var>+<offset>(<length>)`. - **Key System Variables (sy-)**: - `sy-subrc`: Return code of the previous statement (`0` = success, non-zero e.g., `4` = failure). - `sy-tabix`: Current line index inside an internal table loop (`LOOP AT`). - `sy-datum`: Current system date. - `sy-uzeit`: Current system time. - `sy-uname`: Logged-in user name. - `sy-langu`: Logged-in language. - `sy-tcode`: Current transaction code. - `sy-repid`: Current program ID. --- ### 10. Debugging Capabilities - **ABAP Debugger**: Allows setting breakpoints to step line-by-line (using **F6** to step over, **F8** to continue) to monitor real-time data transformations and diagnose runtime dumps or logic errors. 23:T800,ABAP Basic Statements 1. Basic Syntax Rules & Comments - Statement Termination: Every ABAP statement must end with a period (\\.\\). A statement can span across multiple lines until a period is encountered. - Case Insensitivity: ABAP code is case-insensitive; keywords, additions, and operands can be written in uppercase or lowercase. - Comments: - An asterisk (\) at the very first position of a line comments out the entire line. - A double quote (\\"\\) comments out everything from that position to the end of the line. - Chained Statements: Multiple statements repeating the same keyword can be chained using a colon (\\:\\) and separated by commas (\\,\\) (e.g., WRITE: var1, var2.). --- 2. Data Objects & Type Declarations - Data Objects: ABAP distinguishes between Variables (DATA), Constants (CONSTANTS), and Literals (text in '...', string in ... , or numbers). - Variable Declaration: Declared using DATA <variablename TYPE <datatype with an optional VALUE addition. To copy the type of an existing data object, use LIKE. - Local vs. Global Types: - Local Data Types (TYPES): Defined locally within a program. If a local type shares the same name as a global type, the local definition takes precedence. - Global Data Types: Created and managed system-wide via the ABAP Dictionary (transaction code SE11). - Predefined Data Types: - Complete Data Types (fixed length): D (Date - 8 characters YYYYMMDD), T (Time - 6 characters HHMMSS), I (Integer - 4 bytes, range -2^31 to +2^31), STRING (dynamic character string). - Incomplete Data Types (length required): C (Character), N (Numeric text), and P (Packed number - used for calculations/currencies with DECIMALS specification). - Internal Tables: Declared using DATA <tablename TYPE TABLE OF <linetype to hold lists of structured data. --- 3. Coding Convension - Custom Type: GT, GTS, GTT\ - Constant: GC\ - Global variables: GD\ - Work Area (Structure): GS\ - Internal Table: GT\ - Local variables: LD\ - Local work area: LS\ - Local internal table: LT\ - Selection-screen Parameter: P\24:T7f3,## ABAP Basic Statements ### 1. Basic Syntax Rules & Comments - **Statement Termination**: Every ABAP statement must end with a **period (\*\***.\***\*)**. A statement can span across multiple lines until a period is encountered. - **Case Insensitivity**: ABAP code is case-insensitive; keywords, additions, and operands can be written in uppercase or lowercase. - **Comments**: - An **asterisk** (\*) at the very first position of a line comments out the entire line. - A **double quote (\*\***"\***\*)** comments out everything from that position to the end of the line. - **Chained Statements**: Multiple statements repeating the same keyword can be chained using a **colon (\*\***:\***\*)** and separated by **commas (\*\***,\***\*)** (e.g., `WRITE: var1, var2.`). --- ### 2. Data Objects & Type Declarations - **Data Objects**: ABAP distinguishes between **Variables** (`DATA`), **Constants** (`CONSTANTS`), and **Literals** (text in `'...'`, string in `` `...` ``, or numbers). - **Variable Declaration**: Declared using `DATA <variable_name> TYPE <data_type>` with an optional `VALUE` addition. To copy the type of an existing data object, use `LIKE`. - **Local vs. Global Types**: - **Local Data Types** (`TYPES`): Defined locally within a program. If a local type shares the same name as a global type, the local definition takes **precedence**. - **Global Data Types**: Created and managed system-wide via the **ABAP Dictionary** (transaction code `SE11`). - **Predefined Data Types**: - **Complete Data Types** (fixed length): `D` (Date - 8 characters `YYYYMMDD`), `T` (Time - 6 characters `HHMMSS`), `I` (Integer - 4 bytes, range -2^31 to +2^31), `STRING` (dynamic character string). - **Incomplete Data Types** (length required): `C` (Character), `N` (Numeric text), and `P` (Packed number - used for calculations/currencies with `DECIMALS` specification). - **Internal Tables**: Declared using `DATA <table_name> TYPE TABLE OF <line_type>` to hold lists of structured data. --- ### 3. Coding Convension25:T22f5, ## 1. System Overview & Architecture The **ABAP Data Dictionary (DDIC)**, managed via Transaction Code **`SE11`**, is an integrated database management framework embedded within the SAP ABAP application server. It acts as a database abstraction layer positioned between SAP application programs and the underlying Relational Database Management System (RDBMS) such as Oracle or Microsoft SQL Server. ``` +-------------------------------------------------------+ | SAP Application Layer | | (ABAP Programs, SE38, SE80) | +-------------------------------------------------------+ | v +-------------------------------------------------------+ | ABAP Data Dictionary (SE11) | | (Domains, Data Elements, Structures, Tables, Views) | +-------------------------------------------------------+ | v (Auto-generated DDL / Objects) +-------------------------------------------------------+ | Underlying RDBMS Layer | | (Oracle, MS SQL Server, SAP HANA) | +-------------------------------------------------------+ ``` ### Key Functional Capabilities - **Database Independence**: Eliminates the requirement for developers to write platform-specific SQL Data Definition Language (DDL) scripts. - **Centralized Object Reuse**: Enables system-wide definition and reuse of global data types, database tables, views, and search helps. - **Active Runtime Catalog**: Database table structures defined in the DDIC are compiled directly into physical database objects upon activation. --- ## 2. Elementary Data Type Architecture: Domain vs. Data Element ![[../images/domain-data-element.png]] Data field definitions in the ABAP Dictionary decouple **technical parameters** from **business semantics** through a two-tier architecture comprising **Domains** and **Data Elements**. ![[../images/domain-data-element-1.png]] ### 2.1 Domain (Technical Attribute Layer) - **Definition**: Defines the physical and technical attributes of a data field. - **Technical Parameters**: - Built-in Data Type (e.g., `CHAR`, `NUMC`, `DEC`, `DATS`, `TIMS`). - Field Length and **Output Length** (accounts for formatting characters such as decimal points, currency signs, or negative indicators). - Case Sensitivity toggle (`Lower Case` / `Case Sensitive`). - **Value Restrictions**: - **Fixed Values (Value Range)**: Hardcoded valid single values or interval ranges enforced at domain level. - **Value Table**: Points to a master check table containing allowable key entries. ### 2.2 Data Element (Semantic Attribute Layer) - **Definition**: Defines the business meaning and contextual usage of a data object. - **Semantic Attributes**: - **UI Field Labels**: Defines Short, Medium, Long, and Heading labels displayed across screens and report columns. - **F1 Help Documentation**: Links to detailed documentation created via the documentation editor for end-user assistance. - **Relationship**: References a Domain to inherit technical attributes. A single Domain can be referenced by multiple Data Elements (e.g., Domain `S_CITY` referenced by Data Elements `S_FROMCIT` and `S_TOCITY`). - **Naming Conventions**: Domains and Data Elements reside in distinct object namespaces and can share identical names, though project guidelines typically utilize prefixes (e.g., `DO_` for domains, `DE_` for data elements). ### Example: ## ![[../images/domain-data-element-2.png]] ## 3. Composite Data Objects & Database Tables ### 3.1 Structures - **Definition**: Reusable, structured type definitions comprising a sequence of named components/fields. - **Behavior**: Structures do **not** persist data in the physical database. - **Applications**: - Used in ABAP programs to instantiate **Work Areas** (single-row structures). - Included directly within database table definitions via the **`INCLUDE`** statement to standardize field groups across multiple tables. ### 3.2 Data Categories in SAP 1. **Master Data**: Core entity records modified infrequently (e.g., Customer, Vendor, Material, Employee). 2. **Transactional Data**: High-volume operational transaction records (e.g., Sales Orders, Purchase Orders, Accounting Documents). 3. **Configuration Data**: System customization parameters established during project setup (e.g., Currency Codes, Payment Terms). 4. **System Data**: System administration and administrative runtime logs. ### 3.3 Database Table Types | Table Type | Description & Physical Mapping | | :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Transparent Table** | **1-to-1 Mapping**: Each transparent table defined in `SE11` corresponds to exactly one physical table in the database. | | **Pooled Table** | **N-to-1 Mapping**: Multiple logical pooled tables consolidated into a single physical table in the database; used primarily by system tables. | | **Cluster Table** | **N-to-1 Mapping**: Multiple logical cluster tables combined into a single database cluster table (e.g., `BSEG`); optimized for complex structural documents, considered legacy in SAP HANA. | | **Table Type** | **Global Memory Type**: A DDIC object defining internal table types used for ABAP program execution, containing no database persistence. | ### 3.4 Relational Features - **Primary Key**: Uniquely identifies each record in a database table. Key fields cannot be edited directly after record insertion. - **Client Dependency (`MANDT` / `CLIENT`)**: Automatic client separation is achieved by defining the primary key field `MANDT` (Data Element `MANDT`), ensuring data isolation per system client. - **Foreign Keys & Check Tables**: Foreign key field definitions map fields to a **Check Table** to maintain relational data integrity and auto-generate F4 input validation. --- ## 4. Database Views & Core Data Services (CDS) Views are logical definitions that join fields across one or more tables without duplicating physical data. ### 4.1 Classic DDIC Views (`SE11`) 1. **Database View**: Implements standard inner joins across database tables for read access. 2. **Maintenance View**: Configures table joins specifically to power Table Maintenance Generators (TMG) for administrative data entry. 3. **Projection View**: Selects a subset of fields from a single table to mask unwanted attributes. 4. **Help View**: Serves as the data selection foundation for Search Helps. ### 4.2 Core Data Services (CDS) Views - **Architecture**: Modern, code-based data modeling tool defined inside Eclipse ADT using SQL DDL syntax. - **Integration**: Automatically generates a underlying classic SQL View (limited to 16 characters) accessible via standard `SE11` and `SE16N` queries. --- ## 5. Input Assistance & Data Inspection ### 5.1 Search Help (F4 Help) Provides user assistance dialogs during UI field input. - **Elementary Search Help**: Defines a single search path, specifying the selection method (table/view), input/output parameters, and hit list layout. - **Collective Search Help**: Combines multiple Elementary Search Helps into a single tabbed dialog interface. ### 5.2 Data Inspection Utilities - **`SE16`**: Classic ABAP Workbench data browser utility; supports ALV Grid display via user parameter adjustments. - **`SE16N`**: Enhanced application data browser providing field filtering and record inspection capabilities. --- ## 6. Technical Settings & Performance Guidelines Every database table created in `SE11` requires technical settings configuration prior to activation: - **Delivery Class**: Specifies table data maintenance rules and client transport behavior (e.g., `A` for Application Master/Transaction data, `C` for Customizing). - **Data Class**: Determines physical database space allocation: - `APPL0`: Master Data. - `APPL1`: Transactional Data. - `USER`: User-specific datasets. - **Size Category**: Configures initial database extent allocation based on expected row count ranges. - **Buffering & Logging**: Enables application server memory caching for static tables or logs change operations. - **Secondary Indexes**: Additional index structures created on non-key columns to accelerate read performance; must be balanced against maintenance overhead during insert/update operations. ![[../images/domain-data-element-3.png]] 26:Ta28,1. System Overview & Architecture The ABAP Data Dictionary (DDIC), managed via Transaction Code SE11, is an integrated database management framework embedded within the SAP ABAP application server. It acts as a database abstraction layer positioned between SAP application programs and the underlying Relational Database Management System (RDBMS) such as Oracle or Microsoft SQL Server. +-------------------------------------------------------+ | SAP Application Layer | | (ABAP Programs, SE38, SE80) | +-------------------------------------------------------+ | v +-------------------------------------------------------+ | ABAP Data Dictionary (SE11) | | (Domains, Data Elements, Structures, Tables, Views) | +-------------------------------------------------------+ | v (Auto-generated DDL / Objects) +-------------------------------------------------------+ | Underlying RDBMS Layer | | (Oracle, MS SQL Server, SAP HANA) | +-------------------------------------------------------+ Key Functional Capabilities - Database Independence: Eliminates the requirement for developers to write platform-specific SQL Data Definition Language (DDL) scripts. - Centralized Object Reuse: Enables system-wide definition and reuse of global data types, database tables, views, and search helps. - Active Runtime Catalog: Database table structures defined in the DDIC are compiled directly into physical database objects upon activation. --- 2. Elementary Data Type Architecture: Domain vs. Data Element ![[../images/domain-data-element.png]] Data field definitions in the ABAP Dictionary decouple technical parameters from business semantics through a two-tier architecture comprising Domains and Data Elements. ![[../images/domain-data-element-1.png]] 2.1 Domain (Technical Attribute Layer) - Definition: Defines the physical and technical attributes of a data field. - Technical Parameters: - Built-in Data Type (e.g., CHAR, NUMC, DEC, DATS, TIMS). - Field Length and Output Length (accounts for formatting characters such as decimal points, currency signs, or negative indicators). - Case Sensitivity toggle (Lower Case / Case Sensitive). - Value Restrictions: - Fixed Values (Value Range): Hardcoded valid single values or interval ranges enforced at domain level. - Value Table: Points to a master check table containing allowable key entries. 2.2 Data Element (Semantic Attribute Layer) - Definition: Defines the business meaning and contextual usage of a data object. - Semantic Attributes: - UI Field Labels: Defines Short, Medium, Long, and Heading labels displayed across screens and report columns. -27:Tabf,## 1. System Overview & Architecture The **ABAP Data Dictionary (DDIC)**, managed via Transaction Code **`SE11`**, is an integrated database management framework embedded within the SAP ABAP application server. It acts as a database abstraction layer positioned between SAP application programs and the underlying Relational Database Management System (RDBMS) such as Oracle or Microsoft SQL Server. ``` +-------------------------------------------------------+ | SAP Application Layer | | (ABAP Programs, SE38, SE80) | +-------------------------------------------------------+ | v +-------------------------------------------------------+ | ABAP Data Dictionary (SE11) | | (Domains, Data Elements, Structures, Tables, Views) | +-------------------------------------------------------+ | v (Auto-generated DDL / Objects) +-------------------------------------------------------+ | Underlying RDBMS Layer | | (Oracle, MS SQL Server, SAP HANA) | +-------------------------------------------------------+ ``` ### Key Functional Capabilities - **Database Independence**: Eliminates the requirement for developers to write platform-specific SQL Data Definition Language (DDL) scripts. - **Centralized Object Reuse**: Enables system-wide definition and reuse of global data types, database tables, views, and search helps. - **Active Runtime Catalog**: Database table structures defined in the DDIC are compiled directly into physical database objects upon activation. --- ## 2. Elementary Data Type Architecture: Domain vs. Data Element ![[../images/domain-data-element.png]] Data field definitions in the ABAP Dictionary decouple **technical parameters** from **business semantics** through a two-tier architecture comprising **Domains** and **Data Elements**. ![[../images/domain-data-element-1.png]] ### 2.1 Domain (Technical Attribute Layer) - **Definition**: Defines the physical and technical attributes of a data field. - **Technical Parameters**: - Built-in Data Type (e.g., `CHAR`, `NUMC`, `DEC`, `DATS`, `TIMS`). - Field Length and **Output Length** (accounts for formatting characters such as decimal points, currency signs, or negative indicators). - Case Sensitivity toggle (`Lower Case` / `Case Sensitive`). - **Value Restrictions**: - **Fixed Values (Value Range)**: Hardcoded valid single values or interval ranges enforced at domain level. - **Value Table**: Points to a master check table containing allowable key entries. ### 2.2 Data Element (Semantic Attribute Layer)28:T201d, ## 1. Architecture & Execution Model **Open SQL** is an embedded subset of ANSI SQL fully integrated into the ABAP programming language. It acts as an abstraction layer between application programs and the underlying database management system (DBMS). ``` +-------------------------------------------------------+ | ABAP Application Layer | | (Open SQL Statements / SE38) | +-------------------------------------------------------+ | v (ABAP Syntax Check & Compilation) +-------------------------------------------------------+ | ABAP Database Interface | | (Translates Open SQL into Native SQL DML) | +-------------------------------------------------------+ | v (Database-Specific SQL Execution) +-------------------------------------------------------+ | Underlying RDBMS Layer | | (Oracle, MS SQL Server, SAP HANA) | +-------------------------------------------------------+ ``` ### 1.1 Key Architectural Properties - **Database Independence**: Open SQL statements are uniform across all supported database platforms. The **Database Interface** automatically converts Open SQL statements into the platform-specific **Native SQL** required by the underlying RDBMS (e.g., Oracle, MS SQL Server). - **Integrated Syntax Validation**: Because Open SQL is a native component of the ABAP language, the ABAP compiler validates SQL syntax directly during program compilation. - **Open SQL vs. Native SQL**: - **Open SQL**: Portable, database-agnostic, statically syntax-checked by the ABAP IDE, and automatically managed by the database interface. - **Native SQL**: Executes database-specific DML/DDL scripts directly. It bypasses the Database Interface, sacrificing portability and static compile-time syntax checks. - **Legacy Table Declarations**: The obsolete `TABLES <table>` statement implicitly creates a structure/work area sharing the table's name. Modern ABAP standards explicitly discourage this statement in favor of explicit type definitions. --- ## 2. Fundamental Query Syntax & Row Selection A standard Open SQL data retrieval statement consists of four core clauses: `SELECT`, `FROM`, `INTO`, and `WHERE`. ```abap SELECT <fields> FROM <table> INTO <target> WHERE <conditions>. ``` ### 2.1 Filtering & Evaluation (`WHERE`) - **Conditional Operators**: Supports standard comparison operators (`=`, `<`, `>`, `<=`, `>=`, `<>`), string pattern matching (`CP`, `CF`), range operators (`BETWEEN`, `IN`), and logical connectors (`AND`, `OR`, `NOT`). - **Selection Tables**: The `IN` operator evaluates field values against selection tables or range tables. ### 2.2 Row-Limiting Techniques - **`SELECT SINGLE`**: - Fetches a single record matching the query criteria. - **Best Practice**: Pass the complete primary key in the `WHERE` clause to guarantee deterministic behavior. - Does not open a database loop and does not require an `ENDSELECT` statement. - **`UP TO n ROWS`**: - Limits the result set to `n` rows. - **Best Practice**: Recommended over `SELECT SINGLE` when filtering on partial key fields. - Requires an `ENDSELECT` statement when selecting row-by-row into a work area. ### 2.3 Result Ordering & Deduplication - **`ORDER BY`**: Guarantees output row ordering. Can sort by `PRIMARY KEY` or by specific columns using `ASCENDING` or `DESCENDING` modifiers. - **`DISTINCT`**: Eliminates duplicate result rows prior to populating the target data object. ### 2.4 System Fields - **`sy-subrc`**: Returns `0` if the query successfully retrieves data, and `4` if no matching records are found. - **`sy-dbcnt`**: Contains the total count of records retrieved or processed by the query. --- ## 3. Aggregation & Grouping Open SQL provides built-in aggregation functions to perform calculations directly on the database engine prior to returning results. | Aggregation Function | Description | | :------------------------------ | :-------------------------------------------------------- | | `COUNT( * )` / `COUNT( field )` | Returns the total count of rows or non-null field values. | | `MAX( field )` | Identifies the maximum value in a column. | | `MIN( field )` | Identifies the minimum value in a column. | | `SUM( field )` | Calculates the total sum of a numeric column. | | `AVG( field )` | Computes the average value of a numeric column. | ### 3.1 Grouping Requirement (`GROUP BY`) When an Open SQL statement includes both scalar columns and aggregate functions in the `SELECT` clause, **all non-aggregated columns must be explicitly listed in the `GROUP BY` clause**. ```abap SELECT carrid, MAX( flytime ), MIN( flytime ) FROM spfli INTO (lv_carrid, lv_max_time, lv_min_time) GROUP BY carrid. ``` --- ## 4. Target Data Objects & Mapping Strategies Data retrieved via Open SQL can be mapped into single-row **Work Areas** or multi-row **Internal Tables**. ``` positional mapping (INTO TABLE): Database Columns: [ MANDT ] [ CARRID ] [ CONNID ] [ COUNTRYFR ] | | | | Target Structure: [ MANDT ] [ CARRID ] [ CONNID ] [ COUNTRYFR ] name-based mapping (INTO CORRESPONDING FIELDS OF TABLE): Database Columns: [ CARRID ] [ CONNID ] [ COUNTRYFR ] | | | +-----------+------------+ (Matches by Name) | Target Structure: [ STATUS ] [ CARRID ] [ CONNID ] [ COUNTRYFR ] ``` ### 4.1 Target Object Comparison | Feature | Work Area (`STRUCTURE`) | Internal Table (`INTERNAL TABLE`) | | :---------------- | :------------------------------------------------- | :---------------------------------------------- | | **Capacity** | Holds a single row of data at a time. | Holds multi-row datasets in application memory. | | **Access Syntax** | Direct field component selection (`<wa>-<field>`). | Iterated using `LOOP AT <itab> INTO <wa>`. | | **Target Clause** | `INTO <work_area>`. | `INTO TABLE <internal_table>`. | ### 4.2 Positional Mapping vs. Name-Based Mapping - **`INTO TABLE <itab>`**: Transfers column data sequentially based on field positions. If the target structure layout differs from the `SELECT` clause field order, data misalignment or truncation occurs. - **`INTO CORRESPONDING FIELDS OF TABLE <itab>`**: Matches database table columns to internal table fields strictly by **field name**, ignoring structural field sequence. Unmapped target fields remain set to their initial values. --- ## 5. Multi-Table Operations & Advanced Filtering ### 5.1 Relational Joins (`JOIN`) Joins combine records across multiple database tables within a single database request. Fields are qualified using tilde syntax (`<table>~<field>` or `<alias>~<field>`). - **`INNER JOIN`**: Returns combined records only when join conditions match in both left and right tables. - **`LEFT OUTER JOIN`**: Returns all rows from the left table. If no matching row exists in the right table, right-table fields are populated with type-specific initial values. ```abap SELECT header~vbeln, header~kunnr, item~posnr, item~matnr FROM vbak AS header INNER JOIN vbap AS item ON header~vbeln = item~vbeln INTO TABLE @DATA(lt_orders). ``` ### 5.2 Internal Table Filtering (`FOR ALL ENTRIES IN`) The `FOR ALL ENTRIES IN` clause evaluates an Open SQL query against all entries in a pre-populated driver internal table. - **Behavior**: Replaces large, complex database joins by using in-memory driver tables as filter criteria. - **Syntax**: ```abap SELECT doc_type, company_code, doc_num FROM bkpf INTO TABLE lt_headers FOR ALL ENTRIES IN lt_filter_tab WHERE doc_type = lt_filter_tab-doc_type. ``` --- 29:T9e1,1. Architecture & Execution Model Open SQL is an embedded subset of ANSI SQL fully integrated into the ABAP programming language. It acts as an abstraction layer between application programs and the underlying database management system (DBMS). +-------------------------------------------------------+ | ABAP Application Layer | | (Open SQL Statements / SE38) | +-------------------------------------------------------+ | v (ABAP Syntax Check & Compilation) +-------------------------------------------------------+ | ABAP Database Interface | | (Translates Open SQL into Native SQL DML) | +-------------------------------------------------------+ | v (Database-Specific SQL Execution) +-------------------------------------------------------+ | Underlying RDBMS Layer | | (Oracle, MS SQL Server, SAP HANA) | +-------------------------------------------------------+ 1.1 Key Architectural Properties - Database Independence: Open SQL statements are uniform across all supported database platforms. The Database Interface automatically converts Open SQL statements into the platform-specific Native SQL required by the underlying RDBMS (e.g., Oracle, MS SQL Server). - Integrated Syntax Validation: Because Open SQL is a native component of the ABAP language, the ABAP compiler validates SQL syntax directly during program compilation. - Open SQL vs. Native SQL: - Open SQL: Portable, database-agnostic, statically syntax-checked by the ABAP IDE, and automatically managed by the database interface. - Native SQL: Executes database-specific DML/DDL scripts directly. It bypasses the Database Interface, sacrificing portability and static compile-time syntax checks. - Legacy Table Declarations: The obsolete TABLES <table statement implicitly creates a structure/work area sharing the table's name. Modern ABAP standards explicitly discourage this statement in favor of explicit type definitions. --- 2. Fundamental Query Syntax & Row Selection A standard Open SQL data retrieval statement consists of four core clauses: SELECT, FROM, INTO, and WHERE. abap SELECT <fields FROM <table INTO <target WHERE <conditions. 2.1 Filtering & Evaluation (WHERE) - Conditional Operators: Supports standard comparison operators (=, <, , <=, =, <), string pattern matching (CP, CF), range operators (BETWEEN, IN), and logical connectors (AND, OR, NOT). - Selection Tables: The IN operator evaluates field values against selection tables or range tables. 2.2 Row-Limiting Techniques - SELECT SINGLE: - Fetches a single record matching the query2a:Tb38,## 1. Architecture & Execution Model **Open SQL** is an embedded subset of ANSI SQL fully integrated into the ABAP programming language. It acts as an abstraction layer between application programs and the underlying database management system (DBMS). ``` +-------------------------------------------------------+ | ABAP Application Layer | | (Open SQL Statements / SE38) | +-------------------------------------------------------+ | v (ABAP Syntax Check & Compilation) +-------------------------------------------------------+ | ABAP Database Interface | | (Translates Open SQL into Native SQL DML) | +-------------------------------------------------------+ | v (Database-Specific SQL Execution) +-------------------------------------------------------+ | Underlying RDBMS Layer | | (Oracle, MS SQL Server, SAP HANA) | +-------------------------------------------------------+ ``` ### 1.1 Key Architectural Properties - **Database Independence**: Open SQL statements are uniform across all supported database platforms. The **Database Interface** automatically converts Open SQL statements into the platform-specific **Native SQL** required by the underlying RDBMS (e.g., Oracle, MS SQL Server). - **Integrated Syntax Validation**: Because Open SQL is a native component of the ABAP language, the ABAP compiler validates SQL syntax directly during program compilation. - **Open SQL vs. Native SQL**: - **Open SQL**: Portable, database-agnostic, statically syntax-checked by the ABAP IDE, and automatically managed by the database interface. - **Native SQL**: Executes database-specific DML/DDL scripts directly. It bypasses the Database Interface, sacrificing portability and static compile-time syntax checks. - **Legacy Table Declarations**: The obsolete `TABLES <table>` statement implicitly creates a structure/work area sharing the table's name. Modern ABAP standards explicitly discourage this statement in favor of explicit type definitions. --- ## 2. Fundamental Query Syntax & Row Selection A standard Open SQL data retrieval statement consists of four core clauses: `SELECT`, `FROM`, `INTO`, and `WHERE`. ```abap SELECT <fields> FROM <table> INTO <target> WHERE <conditions>. ``` ### 2.1 Filtering & Evaluation (`WHERE`) - **Conditional Operators**: Supports standard comparison operators (`=`, `<`, `>`, `<=`, `>=`, `<>`), string pattern matching (`CP`, `CF`), range operators (`BETWEEN`, `IN`), and logical connectors (`AND`, `OR`, `NOT`). - **Selection Tables**: The `IN` operator evaluates field values against selection tables or range tables. ### 2.2 Row-Limiting Techniques2b:T6055, ## 1. Mental Model: Type, Structure, Work Area, and Internal Table Do not treat these as four equivalent objects. ```text TYPES declaration defines a type; it does not hold runtime values │ ├── DATA structure one structured data object │ └── may serve as a work area │ └── DATA internal table zero or more lines of one line type ``` ### 1.1 Structured type A structured type defines named components and their types. `TYPES` creates a type, not a runtime data object. ```abap TYPES: BEGIN OF ty_flight, carrier_id TYPE c LENGTH 3, connection_id TYPE n LENGTH 4, city_from TYPE c LENGTH 40, city_to TYPE c LENGTH 40, price TYPE p LENGTH 8 DECIMALS 2, currency TYPE c LENGTH 3, END OF ty_flight. ``` The type can be local, defined globally in a class/interface, or supplied by a released Dictionary/CDS artifact. `SE11` is a classic Dictionary maintenance tool, not the definition of the ABAP concept itself. ### 1.2 Structure data object `DATA` instantiates a data object and therefore allocates runtime state. ```abap DATA flight TYPE ty_flight. ``` The word **structure** can mean either a structured type or a structured data object, depending on context. Say which one you mean in technical explanations. ### 1.3 Work area A **work area** is a role played by a single data object when a table statement copies one line into it or reads a line from it. It is not a separate ABAP type category. ```abap DATA flight TYPE ty_flight. LOOP AT flights INTO flight. " flight is the work area for this loop ENDLOOP. ``` ### 1.4 Internal table An internal table is an in-memory ABAP data object containing zero or more lines. Its type is defined by: 1. line type; 2. table category; 3. primary table key; 4. optional secondary table keys. It is not a database table and is not persisted by `COMMIT WORK`. Its lifetime follows the lifetime and scope of its owning ABAP data object. ```abap TYPES ty_flights TYPE STANDARD TABLE OF ty_flight WITH EMPTY KEY. DATA flights TYPE ty_flights. ``` ### 1.5 Database boundary ```text Database table / CDS entity │ SELECT ▼ Internal table in ABAP application-server memory │ processing ▼ INSERT / UPDATE / MODIFY / DELETE or EML, when explicitly executed ``` Changing an internal-table line does not automatically update a database table or a RAP business object. --- ## 2. Complete, Reusable Example Types The examples below use explicit keys so their behavior is visible. ```abap TYPES: BEGIN OF ty_flight, carrier_id TYPE c LENGTH 3, connection_id TYPE n LENGTH 4, city_from TYPE c LENGTH 40, city_to TYPE c LENGTH 40, price TYPE p LENGTH 8 DECIMALS 2, currency TYPE c LENGTH 3, END OF ty_flight. TYPES ty_flights_seq TYPE STANDARD TABLE OF ty_flight WITH EMPTY KEY. TYPES ty_flights_sorted TYPE SORTED TABLE OF ty_flight WITH UNIQUE KEY primary_key COMPONENTS carrier_id connection_id. TYPES ty_flights_hashed TYPE HASHED TABLE OF ty_flight WITH UNIQUE KEY primary_key COMPONENTS carrier_id connection_id. DATA flights_seq TYPE ty_flights_seq. DATA flights_sorted TYPE ty_flights_sorted. DATA flights_hashed TYPE ty_flights_hashed. ``` `WITH EMPTY KEY` is a deliberate statement: the standard table is being used as a sequence, not as a keyed collection. --- ## 3. Table Categories Big-O values below are useful mental models, not promises about every kernel, row width, cache state, or access form. | Category | Primary organization | Primary-key uniqueness | Efficient access | Typical use | | ---------------- | ------------------------------------------ | ---------------------- | ----------------------------------------------------------- | ---------------------------------------------------- | | `STANDARD TABLE` | Primary index in insertion order | Non-unique or empty | Index access; sequential processing | Append-heavy lists, ordered processing, small tables | | `SORTED TABLE` | Primary index always sorted by primary key | Unique or non-unique | Left-aligned primary-key access, approximately `O(log n)` | Range reads and frequent ordered key access | | `HASHED TABLE` | Hash administration; no primary index | Must be unique | Complete primary-key equality, approximately `O(1)` average | Fast exact lookup by a unique key | ### 3.1 Standard table - Fast append and index access. - A normal key search is linear unless an appropriate secondary key or a valid binary-search pattern is used. - The primary key does not enforce uniqueness. - Prefer `WITH EMPTY KEY` when the table is intentionally only a sequence. ### 3.2 Sorted table - Lines are always maintained in ascending primary-key order. - The primary key may be unique or non-unique. - Optimized access requires the search components to form a usable left-aligned part of the sorted key. - It supports index access because it is an index table. For a key `(carrier_id, connection_id)`, searching by `carrier_id` can use the sorted prefix; searching only by `connection_id` cannot use that primary-key prefix efficiently. ### 3.3 Hashed table - The primary key must be unique. - Best for equality lookup using the complete hash key. - No primary index access such as `INDEX 1`. - Partial-key and range searches do not receive the main hash advantage. ### 3.4 Selection rule ```text Need stable index/insertion order or mostly append/loop? → STANDARD Need sorted traversal, ranges, or prefix-key lookup? → SORTED Need exact lookup by one complete unique key? → HASHED Need several access paths? → Add justified secondary keys; do not copy the table automatically ``` --- ## 4. Primary and Secondary Table Keys A table key is not merely documentation. It determines uniqueness, access optimization, ordering for sorted keys, and maintenance cost. ### 4.1 Secondary-key example ```abap TYPES ty_flights_multi TYPE STANDARD TABLE OF ty_flight WITH EMPTY KEY WITH UNIQUE HASHED KEY by_connection COMPONENTS carrier_id connection_id WITH NON-UNIQUE SORTED KEY by_route COMPONENTS city_from city_to. ``` ```abap READ TABLE flights_multi WITH TABLE KEY by_connection COMPONENTS carrier_id = 'LH' connection_id = '0400' INTO DATA(flight). LOOP AT flights_multi INTO DATA(route_flight) USING KEY by_route WHERE city_from = 'FRANKFURT'. " Uses the named sorted access path when the condition fits the key ENDLOOP. ``` ### 4.2 Secondary-key trade-off Secondary keys can make reads much faster, but they require extra memory and must be maintained when table content changes. Add one only for a demonstrated access pattern, not “for performance” in the abstract. --- ## 5. Assignment and Name-Based Mapping The original claim that normal assignment can silently “misalign” fields is too broad. ABAP checks assignment compatibility and applies the defined assignment rules. It does not simply scramble fields because their names differ. Use direct assignment when source and target types are compatible: ```abap target = source. ``` Use `CORRESPONDING` when the desired contract is name-based component mapping: ```abap DATA(target) = CORRESPONDING ty_target( source MAPPING target_id = source_id ). ``` Use the statement form when updating an existing target: ```abap MOVE-CORRESPONDING source TO target. ``` Unmatched target components keep or receive values according to the exact statement/operator variant. Check `BASE`, `MAPPING`, `EXCEPT`, and deep-mapping semantics when preservation matters. --- ## 6. Constructing and Adding Lines ### 6.1 Constructor expressions ```abap flights_seq = VALUE #( ( carrier_id = 'LH' connection_id = '0400' city_from = 'FRANKFURT' city_to = 'NEW YORK' price = '800.00' currency = 'EUR' ) ( carrier_id = 'SQ' connection_id = '0012' city_from = 'SINGAPORE' city_to = 'TOKYO' price = '650.00' currency = 'SGD' ) ). ``` ### 6.2 `APPEND` `APPEND` adds at the end of an index table. It is natural for a standard table. ```abap APPEND VALUE #( carrier_id = 'VN' connection_id = '0030' city_from = 'HO CHI MINH CITY' city_to = 'TOKYO' ) TO flights_seq. ``` Although `APPEND` is possible for sorted index tables, the new line must fit after the existing last line and obey key uniqueness. Otherwise the operation fails at runtime. Prefer semantic insertion for sorted tables. ### 6.3 `INSERT ... INTO TABLE` This key-based form works with all table categories and lets the table choose the physical position. ```abap INSERT VALUE #( carrier_id = 'LH' connection_id = '0400' ) INTO TABLE flights_sorted. IF sy-subrc = 4. " Duplicate unique key; no line inserted ENDIF. ``` For a standard table, use `INSERT ... INDEX index` only when position has business meaning. --- ## 7. Reading One Line Safely ### 7.1 `READ TABLE ... INTO`: copy the row ```abap READ TABLE flights_sorted WITH TABLE KEY primary_key COMPONENTS carrier_id = 'LH' connection_id = '0400' INTO DATA(flight). IF sy-subrc = 0. " flight is a copy ENDIF. ``` Modifying `flight` does not modify the table until it is written back. ### 7.2 `READ TABLE ... ASSIGNING`: alias the row ```abap READ TABLE flights_sorted WITH TABLE KEY primary_key COMPONENTS carrier_id = 'LH' connection_id = '0400' ASSIGNING FIELD-SYMBOL(<flight>). IF sy-subrc = 0. <flight>-price = '825.00'. " Changes the table line directly ENDIF. ``` A field symbol is an alias to an assigned data object, not a separately copied row. It must be assigned before dereferencing. ### 7.3 `REFERENCE INTO`: retain a data reference ```abap READ TABLE flights_sorted WITH TABLE KEY primary_key COMPONENTS carrier_id = 'LH' connection_id = '0400' REFERENCE INTO DATA(flight_ref). IF sy-subrc = 0. flight_ref->price = '825.00'. ENDIF. ``` ### 7.4 Table expressions ```abap TRY. DATA(lh_price) = flights_sorted[ carrier_id = 'LH' connection_id = '0400' ]-price. CATCH cx_sy_itab_line_not_found. " Handle the missing row ENDTRY. ``` A failed table expression normally raises `CX_SY_ITAB_LINE_NOT_FOUND`; it does not simply set `sy-subrc` like `READ TABLE`. For existence only: ```abap IF line_exists( flights_sorted[ carrier_id = 'LH' connection_id = '0400' ] ). " Do not perform a second lookup unless the row content is also needed ENDIF. ``` Use one `READ TABLE`, assignment, or reference when the next step needs the line; `line_exists` followed by a second read repeats the lookup. ### 7.5 System fields For common `READ TABLE` forms, `sy-subrc = 0` means a line was found and `sy-subrc = 4` commonly means no matching line was found. For index tables, `sy-tabix` can identify the affected or current primary/secondary index, but its meaning depends on the statement and key used. Hashed primary-key access has no primary table index. Table expressions do not generally set `sy-subrc` and do not generally update `sy-tabix`; use their expression/exception semantics instead. Never rely on a system field without tying it to the immediately preceding statement. --- ## 8. Iteration: Copy, Alias, or Reference | Form | Row handling | Use when | | ------------------------- | ------------------------------------------- | ------------------------------------------ | | `LOOP ... INTO` | Copies each row | Readability or independent copy is desired | | `LOOP ... ASSIGNING` | Assigns a field symbol to the current row | Direct mutation or avoiding row copies | | `LOOP ... REFERENCE INTO` | Returns a data reference to the current row | A reference must be passed or retained | ```abap LOOP AT flights_seq INTO DATA(flight_copy) WHERE city_from = 'FRANKFURT'. " Changes to flight_copy do not automatically change flights_seq ENDLOOP. LOOP AT flights_seq ASSIGNING FIELD-SYMBOL(<flight_row>) WHERE city_from = 'FRANKFURT'. <flight_row>-price += 25. " Direct table-line modification ENDLOOP. ``` `ASSIGNING` can avoid copying wide or deep rows, but do not claim it is always faster in a meaningful way. Choose it first for semantics—direct mutation—and measure performance where it matters. The primary-key components of sorted and hashed tables are protected from changes that would invalidate their administration. Delete and reinsert a line when its primary identity must change. --- ## 9. Modifying Lines ### 9.1 Modify by table key ```abap DATA changed_flight TYPE ty_flight. changed_flight-carrier_id = 'LH'. changed_flight-connection_id = '0400'. changed_flight-price = '850.00'. MODIFY TABLE flights_sorted FROM changed_flight. IF sy-subrc <> 0. " No row matched the primary key ENDIF. ``` ### 9.2 Modify selected components ```abap MODIFY flights_seq FROM VALUE #( price = '700.00' currency = 'EUR' ) TRANSPORTING price currency WHERE carrier_id = 'LH'. ``` ### 9.3 Modify by field symbol ```abap LOOP AT flights_seq ASSIGNING FIELD-SYMBOL(<flight>) WHERE carrier_id = 'LH'. <flight>-price *= '0.95'. ENDLOOP. ``` No `MODIFY` is needed in the last example because `<flight>` aliases the table line. By contrast, a changed work-area copy from `LOOP ... INTO` must be written back explicitly, normally with a clear key or index. --- ## 10. Deleting and Clearing ```abap DELETE flights_seq INDEX 1. DELETE flights_sorted USING KEY primary_key WHERE carrier_id = 'LH'. DELETE TABLE flights_hashed WITH TABLE KEY primary_key COMPONENTS carrier_id = 'LH' connection_id = '0400'. ``` ### 10.1 Remove duplicates `DELETE ADJACENT DUPLICATES` removes only neighboring duplicates according to the comparison. For a standard table, sort into the required adjacency first. ```abap SORT flights_seq BY city_from city_to. DELETE ADJACENT DUPLICATES FROM flights_seq COMPARING city_from city_to. ``` The sort fields and comparison fields must express the same intended identity. ### 10.2 `CLEAR` versus `FREE` ```abap CLEAR flights_seq. " Remove rows; retain initial allocation for reuse FREE flights_seq. " Remove rows and release the initial table allocation ``` Use `CLEAR` when the table will probably be filled again soon. Use `FREE` when releasing a large table's allocation is useful. The ABAP runtime still owns the details of dynamic memory management; do not assume an operating-system memory change at that exact statement. --- ## 11. Sorting and Binary Search ```abap SORT flights_seq BY carrier_id connection_id. READ TABLE flights_seq WITH KEY carrier_id = 'LH' connection_id = '0400' BINARY SEARCH INTO DATA(flight). ``` For `BINARY SEARCH` to be correct, the standard table must already be sorted in ascending order with a compatible leading field sequence. If later code changes the order, the search contract silently becomes fragile. Prefer a sorted table or named sorted secondary key when repeated optimized key access is part of the data model. Use one-off `SORT` plus `BINARY SEARCH` only when the local lifecycle makes the ordering invariant obvious. --- ## 12. Aggregation with `COLLECT` `COLLECT` finds a line using the internal table's **primary key**. If found, it adds the source's numeric non-key components to the existing line. If not found, it inserts the line. ```abap TYPES: BEGIN OF ty_route_total, city_from TYPE c LENGTH 40, city_to TYPE c LENGTH 40, revenue TYPE decfloat34, END OF ty_route_total. TYPES ty_route_totals TYPE HASHED TABLE OF ty_route_total WITH UNIQUE KEY primary_key COMPONENTS city_from city_to. DATA route_totals TYPE ty_route_totals. LOOP AT flights_seq INTO DATA(flight). COLLECT VALUE ty_route_total( city_from = flight-city_from city_to = flight-city_to revenue = flight-price ) INTO route_totals. ENDLOOP. ``` All components outside the primary key must be numeric for this aggregation form. An explicit sorted or hashed key makes the aggregation identity and lookup behavior clearer than relying on a standard table's implicit standard key. Do not confuse ABAP `COLLECT` with database aggregation. When a large dataset can be aggregated correctly by the database, prefer `SELECT ... GROUP BY` so fewer rows cross into application-server memory. --- ## 13. Modern Group Processing Prefer `LOOP AT ... GROUP BY` over legacy control-break processing when writing new code. Grouping is explicit and does not depend on physical component order or temporary masking of work-area fields. ```abap LOOP AT flights_seq INTO DATA(flight) GROUP BY ( carrier_id = flight-carrier_id members = GROUP SIZE ) ASSIGNING FIELD-SYMBOL(<carrier_group>). DATA(total_price) = REDUCE decfloat34( INIT total = CONV decfloat34( 0 ) FOR member IN GROUP <carrier_group> NEXT total += member-price ). " <carrier_group>-carrier_id, <carrier_group>-members, total_price ENDLOOP. ``` Grouping happens in two phases: ABAP assigns rows to group keys, then iterates over the groups. Member iteration uses `LOOP AT GROUP` or `FOR ... IN GROUP`. ### 13.1 Modern table transformations Constructor and iteration expressions can make pure transformations concise: ```abap DATA(lh_flights) = VALUE ty_flights_seq( FOR flight IN flights_seq WHERE ( carrier_id = 'LH' ) ( flight ) ). ``` Use expression syntax when it makes the transformation clearer. A conventional loop is still appropriate when error handling, tracing, or several side effects would make one expression difficult to understand. --- ## 14. Legacy Constructs You Must Recognize ### 14.1 Header lines ```abap " Obsolete — recognize it; do not introduce it DATA old_flights TYPE STANDARD TABLE OF ty_flight WITH HEADER LINE. ``` This declaration creates both: ```text old_flights implicit single-line header area old_flights[] internal table body ``` That name collision makes statements ambiguous: ```abap CLEAR old_flights. " Historically addresses the header line CLEAR old_flights[]. " Addresses the table body ``` Header-line declarations are obsolete and are not allowed in classes. Modern code uses an explicit table plus an explicit work area, inline declaration, or field symbol. ### 14.2 `AT NEW`, `AT END OF`, and `SUM` Legacy control-break events include: - `AT FIRST` - `AT NEW component` - `AT END OF component` - `AT LAST` They depend on the processing order and on the component order of the row structure. During classic control-break blocks, character-like components to the right of the break component can be represented by asterisks and other components can receive initial values temporarily. This behavior is one reason the code is difficult to maintain. When reading old code: 1. inspect the row-type component order; 2. inspect the table's actual processing order; 3. identify the exact break component; 4. check which values are valid inside the event block; 5. inspect any `SUM` behavior carefully. For new code, prefer explicit `GROUP BY` and `REDUCE`. --- ## 15. Database and RAP Boundaries ### 15.1 Avoid `SELECT` inside a loop ```abap " Avoid repeated database round trips LOOP AT requests INTO DATA(request). SELECT SINGLE ... WHERE request_uuid = @request-request_uuid ... ENDLOOP. ``` Prefer set-oriented retrieval using a join, association, subquery, range, or a carefully guarded `FOR ALL ENTRIES`, depending on the problem and release. When using `FOR ALL ENTRIES`: - guard against an initial driver table; - select only necessary columns; - understand duplicate elimination and key semantics; - measure against a join or other set-oriented alternative. ### 15.2 Internal table versus RAP transactional buffer RAP method parameters and EML results are represented using generated internal table types, but the RAP transactional buffer is a framework-managed business object state. It is not identical to one local variable such as `DATA(items)`. ```text Local internal table variable → ordinary ABAP runtime data RAP transactional buffer → framework-managed pending BO changes, addressed through EML ``` Changing a local EML result table does not change the business object. Use `MODIFY ENTITIES` when the BO state must change. --- ## 16. Performance Rules That Survive Interviews 1. **Choose the table category from access patterns.** Do not choose hashed only because the dataset is “large.” 2. **Use the key explicitly.** Optimized lookup depends on the key and search components actually used. 3. **Keep processing set-oriented.** Avoid repeated database access inside internal-table loops. 4. **Avoid unnecessary row copies.** Use `ASSIGNING` or `REFERENCE INTO` when direct access is the intended semantic, especially for wide/deep rows. 5. **Do not over-index.** Secondary keys consume memory and add mutation cost. 6. **Do not sort repeatedly.** If sorted access is a stable requirement, model it with a sorted table or secondary key. 7. **Push suitable filtering and aggregation to the database.** Internal tables are not a replacement for SQL execution on large persisted datasets. 8. **Measure material paths.** Runtime depends on row count, width, mutation frequency, selectivity, and release—not only theoretical complexity. --- ## 17. Common Failure Modes | Symptom | Likely cause | Correction | | ----------------------------------- | ----------------------------------------------------------- | ------------------------------------------------ | | Lookup is still slow | Search does not use a suitable primary/secondary key | Name the key and align the search components | | `BINARY SEARCH` misses a row | Standard table is not sorted compatibly | Sort correctly or model a sorted key | | Duplicate insert fails | Unique sorted/hashed key already exists | Handle `sy-subrc` or choose non-unique semantics | | Table expression dumps | Row is absent and exception/default was not handled | Use `TRY`, `OPTIONAL`, or `READ TABLE` | | Work-area change is lost | `LOOP ... INTO` created a copy | Write it back or use `ASSIGNING` intentionally | | Sorted/hashed key cannot be changed | Direct mutation would invalidate primary-key administration | Delete and reinsert with the new identity | | Duplicate deletion misses rows | Equal comparison values are not adjacent | Sort by the comparison identity first | | `COLLECT` groups unexpectedly | Primary table key does not match aggregation identity | Define an explicit unique key | | RAP BO did not change | Only a local result internal table was modified | Use EML `MODIFY ENTITIES` | --- ## 18. Compact Decision and Syntax Sheet ```text Declare a sequence STANDARD TABLE ... WITH EMPTY KEY Repeated ordered/range access SORTED TABLE ... WITH [NON-]UNIQUE KEY ... Exact unique lookup HASHED TABLE ... WITH UNIQUE KEY ... Read a copy READ TABLE ... INTO ... Read and mutate the row READ TABLE ... ASSIGNING ... Read with a durable reference READ TABLE ... REFERENCE INTO ... Expression lookup itab[ key = value ] Existence only line_exists( itab[ key = value ] ) Insert by table semantics INSERT line INTO TABLE itab Aggregate by explicit primary key COLLECT line INTO itab Group modern ABAP data LOOP AT itab ... GROUP BY ... ``` ### Useful whole-table operations ```abap " Value-copy one compatible table target_flights = source_flights. " Append all source lines APPEND LINES OF source_flights TO target_flights. " Current number of lines DATA(line_count) = lines( target_flights ). " Older statement form still encountered DESCRIBE TABLE target_flights LINES DATA(described_count). ``` 2c:T774,1. Mental Model: Type, Structure, Work Area, and Internal Table Do not treat these as four equivalent objects. text TYPES declaration defines a type; it does not hold runtime values │ ├── DATA structure one structured data object │ └── may serve as a work area │ └── DATA internal table zero or more lines of one line type 1.1 Structured type A structured type defines named components and their types. TYPES creates a type, not a runtime data object. abap TYPES: BEGIN OF tyflight, carrierid TYPE c LENGTH 3, connectionid TYPE n LENGTH 4, cityfrom TYPE c LENGTH 40, cityto TYPE c LENGTH 40, price TYPE p LENGTH 8 DECIMALS 2, currency TYPE c LENGTH 3, END OF tyflight. The type can be local, defined globally in a class/interface, or supplied by a released Dictionary/CDS artifact. SE11 is a classic Dictionary maintenance tool, not the definition of the ABAP concept itself. 1.2 Structure data object DATA instantiates a data object and therefore allocates runtime state. abap DATA flight TYPE tyflight. The word structure can mean either a structured type or a structured data object, depending on context. Say which one you mean in technical explanations. 1.3 Work area A work area is a role played by a single data object when a table statement copies one line into it or reads a line from it. It is not a separate ABAP type category. abap DATA flight TYPE tyflight. LOOP AT flights INTO flight. " flight is the work area for this loop ENDLOOP. 1.4 Internal table An internal table is an in-memory ABAP data object containing zero or more lines. Its type is defined by: 1. line type; 2. table category; 3. primary table key; 4. optional secondary table keys. It is not a database table and is not persisted by COMMIT WORK. Its lifetime follows the lifetime and scope of its owning ABAP data object. abap TYPES tyflights TYPE STANDARD TABLE OF tyflight WITH EMPTY KEY. DATA flights2d:T80f,## 1. Mental Model: Type, Structure, Work Area, and Internal Table Do not treat these as four equivalent objects. ```text TYPES declaration defines a type; it does not hold runtime values │ ├── DATA structure one structured data object │ └── may serve as a work area │ └── DATA internal table zero or more lines of one line type ``` ### 1.1 Structured type A structured type defines named components and their types. `TYPES` creates a type, not a runtime data object. ```abap TYPES: BEGIN OF ty_flight, carrier_id TYPE c LENGTH 3, connection_id TYPE n LENGTH 4, city_from TYPE c LENGTH 40, city_to TYPE c LENGTH 40, price TYPE p LENGTH 8 DECIMALS 2, currency TYPE c LENGTH 3, END OF ty_flight. ``` The type can be local, defined globally in a class/interface, or supplied by a released Dictionary/CDS artifact. `SE11` is a classic Dictionary maintenance tool, not the definition of the ABAP concept itself. ### 1.2 Structure data object `DATA` instantiates a data object and therefore allocates runtime state. ```abap DATA flight TYPE ty_flight. ``` The word **structure** can mean either a structured type or a structured data object, depending on context. Say which one you mean in technical explanations. ### 1.3 Work area A **work area** is a role played by a single data object when a table statement copies one line into it or reads a line from it. It is not a separate ABAP type category. ```abap DATA flight TYPE ty_flight. LOOP AT flights INTO flight. " flight is the work area for this loop ENDLOOP. ``` ### 1.4 Internal table An internal table is an in-memory ABAP data object containing zero or more lines. Its type is defined by: 1. line type; 2. table category; 3. primary table key; 4. optional secondary table keys. It is not a database table and is not persisted by `COMMIT WORK`. Its lifetime follows the lifetime and scope of its owning ABAP data object.2e:T809d, ## 1. The Four Levels of Modularization The word **module** is ambiguous. First identify what is being separated. ```text Repository / deployment organization Package and software component │ Architectural contract Class, interface, released API │ Callable processing block Method, function module, legacy FORM routine │ Source-text organization INCLUDE ``` | Level | Main question | Examples | | ---------------------- | --------------------------------------------------------------- | ------------------------------------- | | Package boundary | Which objects belong, depend on one another, and move together? | Package, software component | | Architectural boundary | What stable responsibility and contract are exposed? | Interface, global class, released API | | Procedure boundary | What inputs enter, what outputs leave, and what can fail? | Method, function module, `FORM` | | Source organization | In which source unit is this text maintained? | `INCLUDE` program | Splitting 2,000 lines into ten includes improves navigation, but does not by itself reduce shared state, coupling, side effects, or test difficulty. --- ## 2. Modern Decision Guide | Need | Preferred construct | Why | | -------------------------------------------------- | -------------------------------------------------- | ----------------------------------------------------------- | | Business/domain logic in new development | Instance method behind an interface | Encapsulation, substitution, testing, dependency injection | | Stateless utility with no substitutable dependency | Static method, used selectively | Simple call without object state | | One calculated result | Functional method with `RETURNING` | Natural expression-oriented call | | Existing classic reusable API | Existing function module | Preserve the supported contract; wrap when useful | | RFC or update-task infrastructure that requires it | Appropriately configured function module | Function modules provide these classic runtime capabilities | | Organizing a large legacy program | Include program | Source separation only | | Reading old procedural code | `FORM`/`PERFORM` | Compatibility and controlled refactoring | | New RAP business logic | Behavior implementation method plus helper classes | Framework contract plus testable domain logic | Default rule for new code: ```text Interface → class → small cohesive methods ``` Do not introduce a function module or `FORM` merely because code must be reused. --- ## 3. Methods: The Primary Modern Procedure A method belongs to a class or interface. It has a statically known signature, visibility, parameter directions, typing, and exception contract. ### 3.1 Instance method ```abap INTERFACE zif_amount_calculator PUBLIC. METHODS calculate_net_amount IMPORTING quantity TYPE decfloat34 unit_price TYPE decfloat34 RETURNING VALUE(net_amount) TYPE decfloat34. ENDINTERFACE. CLASS zcl_amount_calculator DEFINITION PUBLIC FINAL CREATE PUBLIC. PUBLIC SECTION. INTERFACES zif_amount_calculator. ENDCLASS. CLASS zcl_amount_calculator IMPLEMENTATION. METHOD zif_amount_calculator~calculate_net_amount. net_amount = quantity * unit_price. ENDMETHOD. ENDCLASS. ``` Call: ```abap DATA(calculator) = NEW zcl_amount_calculator( ). DATA(net_amount) = calculator->zif_amount_calculator~calculate_net_amount( quantity = CONV decfloat34( '3' ) unit_price = CONV decfloat34( '12.50' ) ). ``` The interface expresses the consumer contract. The class expresses one implementation. Calling through the interface makes replacement and testing possible. ### 3.2 Static method ```abap CLASS-METHODS normalize_status IMPORTING raw_status TYPE string RETURNING VALUE(status) TYPE string. ``` Call: ```abap DATA(status) = zcl_status_helper=>normalize_status( raw_status ). ``` Static methods are suitable for genuinely stateless operations. Excessive static dependencies behave like globals: they are difficult to substitute and can make isolated tests harder. ### 3.3 Visibility | Visibility | Meaning | | ------------------- | ------------------------------------------- | | `PUBLIC SECTION` | Callable by external consumers | | `PROTECTED SECTION` | Accessible to the class and subclasses | | `PRIVATE SECTION` | Internal implementation detail of the class | Expose the smallest useful public contract. Test public behavior; do not make every helper public merely to call it from a test. ### 3.4 Functional methods A functional method has exactly one `RETURNING` parameter and can appear in an expression. ```abap METHODS calculate_total IMPORTING items TYPE ztt_order_item RETURNING VALUE(total) TYPE decfloat34. DATA(total) = calculator->calculate_total( items ). ``` The return value is completely typed and passed by value. Use `EXPORTING` or `CHANGING` parameters only when the procedure naturally produces several outputs or intentionally updates caller-owned state. --- ## 4. Method Interfaces and Parameter Directions Directions are named from the **callee's** perspective. | Formal parameter in method | Callee meaning | Caller clause | | -------------------------- | -------------------------------------------------- | ------------------------------------------------ | | `IMPORTING` | Method receives input | `EXPORTING` or omitted in functional call syntax | | `EXPORTING` | Method produces output | `IMPORTING` | | `CHANGING` | Method receives and returns the same logical value | `CHANGING` | | `RETURNING` | Functional result | Operand position or `RECEIVING` | Example: ```abap METHODS determine_status IMPORTING current_quantity TYPE i EXPORTING reason TYPE string CHANGING status TYPE string. service->determine_status( EXPORTING current_quantity = quantity IMPORTING reason = DATA(reason) CHANGING status = status ). ``` The caller's keywords are not an arbitrary “inversion.” Both sides describe the same flow from their own perspective. ### 4.1 Optional and default parameters Method input and changing parameters can be optional or have defaults where the language permits. ```abap METHODS format_amount IMPORTING amount TYPE decfloat34 currency TYPE c LENGTH 3 DEFAULT 'EUR' show_currency TYPE abap_bool OPTIONAL RETURNING VALUE(text) TYPE string. ``` Inside a procedure, `IS SUPPLIED` distinguishes an omitted optional parameter from one supplied with its type-initial value. Use optional parameters carefully. Too many independent options often indicate that the method has several responsibilities or needs a parameter object. --- ## 5. Parameter Passing: Reference, Value, and Value-Result Parameter direction and parameter passing are different dimensions. ```text Direction: IMPORTING / EXPORTING / CHANGING / RETURNING Passing: by reference / by value / value-result behavior ``` ### 5.1 Pass by reference The formal parameter refers to the actual parameter. No independent parameter copy is created for the procedure contract. - Changes through an output-capable reference parameter affect the caller. - Aliasing can create side effects when the same object is reachable through several paths. - Input parameters should be treated as inputs according to their contract. ### 5.2 Pass by value `VALUE(parameter)` creates a local formal parameter. Input values are copied in; output-capable values are copied back only when procedure processing completes successfully. For large or deep data, do not assume an immediate physical copy of every byte: the ABAP runtime can optimize copying internally. Choose semantics first and measure important paths. ### 5.3 Value-result For an output-capable `VALUE(...)` parameter, the procedure works on a local value and transfers the result to the caller at successful completion. If an exception ends the procedure before successful completion, that copy-back does not occur. ### 5.4 Prefer intention-revealing interfaces ```text Input only → IMPORTING One new result → RETURNING Several new results → EXPORTING or a result structure Intentional in/out → CHANGING ``` Do not use `CHANGING` as a convenient substitute for designing a result. --- ## 6. Class-Based Exceptions Declare failures that the caller can reasonably handle. ```abap METHODS submit_request IMPORTING request_uuid TYPE sysuuid_x16 RAISING zcx_request_invalid zcx_request_unauthorized. ``` ```abap TRY. service->submit_request( request_uuid ). CATCH zcx_request_invalid INTO DATA(invalid_error). DATA(message) = invalid_error->get_text( ). CATCH zcx_request_unauthorized INTO DATA(auth_error). message = auth_error->get_text( ). ENDTRY. ``` Use class-based exceptions for exceptional failure paths. Do not return a Boolean plus an unrelated global message when the caller needs structured error information. In RAP behavior methods, follow the generated `FAILED` and `REPORTED` contract for business-operation failures instead of replacing it with an arbitrary exception design. --- ## 7. Includes: Source Organization, Not Encapsulation An include program is an ABAP repository source object that cannot be compiled independently. `INCLUDE name.` incorporates its source into the compilation unit of the including program. ```abap REPORT zorder_report. INCLUDE zorder_report_top. " declarations INCLUDE zorder_report_sel. " selection screen INCLUDE zorder_report_cls. " local classes ``` Conceptually: ```text Main source + included source units ↓ activation/compilation One compilation unit ``` ### 7.1 What an include does - Splits a large source into separately maintained source units. - Participates in the including program's compilation and syntax context. - Can organize declarations, procedural blocks, local classes, or event logic. - Cannot execute independently. ### 7.2 What an include does not do - It does not define a callable interface merely by being an include. - It does not create a runtime call or stack frame. - It does not isolate global variables from the including program. - It does not make logic reusable in the architectural sense. - It does not automatically improve unit testability. Declarations in an include have the visibility and scope produced by their position in the combined program. Source order therefore matters. ### 7.3 Parameters An include itself has no parameter interface. A method or legacy `FORM` written inside an include can have parameters because that procedure—not the include— defines the call boundary. ### 7.4 Activation An include must be syntax-checked in a compilation-unit context. When it changes, activate the include and affected owning repository objects as a consistent change set. Do not claim that an include is independently compiled or that every include change always requires a manual activation of every main program; tooling and dependency handling vary by development environment. ### 7.5 Reuse warning SAP recommends assigning an include program to one compilation unit. Reusing the same include across unrelated programs creates hidden dependencies on global declarations, program type, source order, and event context. Extract a class or interface when reuse is the real requirement. --- ## 8. Subroutines: Legacy `FORM` and `PERFORM` SAP classifies subroutines as obsolete. You must recognize and safely maintain them in classic code, but use methods for new designs. ```abap PERFORM calculate_net USING quantity unit_price CHANGING net_amount. FORM calculate_net USING quantity TYPE decfloat34 unit_price TYPE decfloat34 CHANGING net_amount TYPE decfloat34. net_amount = quantity * unit_price. ENDFORM. ``` At `PERFORM`, control enters the `FORM`, executes it, and returns after the call. ### 8.1 Scope - A subroutine is implemented outside classes. - It normally belongs to its program's procedural context. - It can directly access that program's global data, which creates hidden input and output channels. - Data declared inside the `FORM` is local to a call; `STATICS` data persists across calls in the relevant internal session. `PERFORM ... IN PROGRAM` can call a subroutine in another program, but creates a fragile cross-program dependency. Do not use it as a modern public API. ### 8.2 Subroutine parameter passing | Declaration | Passing behavior | Caller effect | | ------------------- | -------------------- | ---------------------------------------------------------------- | | `USING p` | Reference by default | A write can affect caller state, despite the input-oriented name | | `USING VALUE(p)` | Value | Local copy; caller is not changed | | `CHANGING p` | Reference by default | Writes immediately affect caller state | | `CHANGING VALUE(p)` | Value-result | Local value copied back after successful completion | `USING` and `CHANGING` communicate intent; `VALUE(...)` determines value passing. A reference-passed `USING` parameter is not protected from writes by the language in the same way a strong immutable contract would be, so treat it as read-only by convention. ### 8.3 Typing Without explicit typing, a subroutine formal parameter is generically typed as `any`. This defers useful checks and allows failures to appear at runtime. ```abap " Avoid in maintained code FORM process USING input. " Better legacy form FORM process USING input TYPE ty_request. ``` Subroutines do not support modern optional/default parameter interfaces. Static calls should pass the declared parameter sequence exactly. Dynamic subroutine calls weaken static checks further and introduce injection risk if an external value controls the procedure/program name. ### 8.4 Obsolete `TABLES` parameters ```abap " Obsolete — recognize, do not introduce FORM process TABLES rows STRUCTURE zs_row. ``` Use typed `USING` or `CHANGING` parameters while maintaining a `FORM`, and use a class method when refactoring the design. ```abap TYPES ty_requests TYPE STANDARD TABLE OF ty_request WITH EMPTY KEY. FORM process USING requests TYPE ty_requests. " Read-only by convention ENDFORM. ``` --- ## 9. Function Modules A function module is a globally named procedure implemented inside a function group. Classic maintenance uses transaction `SE37`; function groups can be inspected with `SE80` or ADT tooling, depending on the environment. ```text Function group (function pool) ├── global data shared by its function modules ├── generated and developer-managed includes ├── Function Module A └── Function Module B ``` The function module has a public interface. The function group's global data is shared state within the loaded function pool and can make behavior order- dependent if misused. ### 9.1 Call direction Consider an illustrative custom function module whose interface imports an ID and exports a result: ```abap CALL FUNCTION 'Z_READ_REQUEST_STATUS' EXPORTING request_uuid = request_uuid IMPORTING status = status EXCEPTIONS not_found = 1 OTHERS = 2. IF sy-subrc <> 0. " Handle classic exception result ENDIF. ``` | Function-module interface | Caller uses | Flow | | ------------------------- | ------------------------------ | ------------------------ | | `IMPORTING request_uuid` | `EXPORTING request_uuid = ...` | Caller → function module | | `EXPORTING status` | `IMPORTING status = ...` | Function module → caller | | `CHANGING data` | `CHANGING data = ...` | Both directions | This is the same callee/caller perspective used for method calls. ### 9.2 Interface typing and runtime checks Function module names and interfaces are resolved at runtime by `CALL FUNCTION`, even when the name is a literal. Incorrect names, missing parameters, unknown parameters, length conflicts, and type conflicts therefore lead to dynamic-call exceptions or runtime errors such as: - `CALL_FUNCTION_NOT_FOUND` - `CALL_FUNCTION_PARM_MISSING` - `CALL_FUNCTION_PARM_UNKNOWN` - `CALL_FUNCTION_CONFLICT_TYPE` - `CALL_FUNCTION_CONFLICT_LENG` The sample's generic `ILLEGAL_TYPE_PARAM` label is not the useful diagnostic name for ordinary function-module parameter mismatches. Read the actual short dump and identify the formal and actual parameter types. ### 9.3 Optional parameters Unlike `FORM` routines, function module importing and changing parameters can be optional or have default values. Exporting parameters are optional to the caller. The function module can use `parameter IS SUPPLIED` where supported to distinguish omission from an initial value. ### 9.4 Exceptions #### Classic non-class-based exception ```abap CALL FUNCTION 'Z_READ_REQUEST_STATUS' EXPORTING request_uuid = request_uuid IMPORTING status = status EXCEPTIONS not_found = 1 OTHERS = 2. CASE sy-subrc. WHEN 0. " Success WHEN 1. " NOT_FOUND WHEN OTHERS. " Another mapped exception ENDCASE. ``` The numeric values are assigned by the caller. `sy-subrc = 1` has meaning only because this particular call maps `not_found = 1`. #### Class-based exception If the function module declares class-based exceptions, handle them with `TRY ... CATCH` according to its interface. ```abap TRY. CALL FUNCTION 'Z_READ_REQUEST_STATUS_NEW' EXPORTING request_uuid = request_uuid IMPORTING status = status. CATCH zcx_request_not_found INTO DATA(error). DATA(message) = error->get_text( ). ENDTRY. ``` SAP considers non-class-based exceptions a compatibility mechanism. Do not define them for new general-purpose APIs when a class-based contract is available and supported by the invocation type. ### 9.5 Obsolete `TABLES` interface parameters The `TABLES` parameter style is legacy and reference-based. New interfaces use typed importing, exporting, changing, or returning parameters. Be especially careful with RFC restrictions: remote-enabled interfaces have serialization and type constraints beyond local calls. --- ## 10. Specialized Function-Module Runtime Modes Function modules remain important where the platform explicitly requires their runtime capabilities. ### 10.1 Remote-enabled function module (RFC) ```abap CALL FUNCTION 'Z_REMOTE_OPERATION' DESTINATION destination EXPORTING input = input IMPORTING output = output EXCEPTIONS system_failure = 1 MESSAGE system_message communication_failure = 2 MESSAGE communication_message OTHERS = 3. ``` RFC introduces a serialization and communication boundary. Never pass an untrusted external string directly as a dynamic function or destination name. Validate allowlisted values and use supported communication configuration. ### 10.2 Update function module ```abap CALL FUNCTION 'Z_WRITE_AUDIT' IN UPDATE TASK EXPORTING audit_entry = audit_entry. ``` An update function module registers work for update processing associated with the SAP LUW. It has strict interface and execution rules. Do not replace an ordinary method call with `IN UPDATE TASK` merely to make it asynchronous. ### 10.3 Background/asynchronous mechanisms Classic asynchronous RFC, background tasks, bgRFC, qRFC, application jobs, and events solve different reliability and sequencing problems. “Function module” alone does not imply remote, asynchronous, or transactional behavior; the call variant and module attributes matter. --- ## 11. Other Legacy Processing Blocks ### 11.1 Macros ```abap DEFINE set_status. &1-status = &2. END-OF-DEFINITION. ``` Macros are source-level substitution constructs with positional placeholders, not typed procedures. They can obscure control flow and tooling. Recognize them in old code; prefer methods for new logic. ### 11.2 Dialog modules ```abap MODULE validate_screen_input INPUT. " Classic dynpro PAI logic ENDMODULE. ``` `MODULE ... ENDMODULE` processing blocks are called by classic screen flow logic (`PBO`/`PAI`). They are relevant to dynpro maintenance, not a preferred general-purpose reuse mechanism. ### 11.3 Event blocks Blocks such as `START-OF-SELECTION` define framework-driven program events. They are entry points, not reusable APIs. Keep them thin and delegate coherent logic to methods. --- ## 12. Scope and State | Location | Typical lifetime/visibility | Main risk | | -------------------------- | -------------------------------- | ------------------------------------------- | | Method local `DATA` | One invocation | Low; explicit local state | | Instance attribute | Object lifetime | Hidden mutation if responsibility is broad | | Static/class attribute | Internal-session/class lifetime | Global-style coupling and test interference | | Program global data | Program/internal-session context | Hidden inputs and outputs across procedures | | Function-group global data | Loaded function-pool context | Calls depend on prior calls/state | | `STATICS` local data | Retained across procedure calls | Surprising state and test-order dependence | The phrase “local data is freed immediately on exit” is an oversimplification. Local names leave scope at procedure exit, but referenced objects, shared data, runtime optimizations, and garbage collection determine physical memory lifetime. Prefer explicit parameters and returned results over procedure access to global state. --- ## 13. Refactoring a `FORM` into a Class ### 13.1 Legacy form ```abap DATA orders TYPE ztt_order. DATA total TYPE decfloat34. FORM calculate_total. LOOP AT orders INTO DATA(order). total += order-net_amount. ENDLOOP. ENDFORM. ``` Hidden contract: ```text Input: global orders Output: global total Failure: undocumented ``` ### 13.2 First safe step: expose the contract ```abap FORM calculate_total USING orders TYPE ztt_order CHANGING total TYPE decfloat34. CLEAR total. LOOP AT orders INTO DATA(order). total += order-net_amount. ENDLOOP. ENDFORM. ``` ### 13.3 Modern result: functional method ```abap METHODS calculate_total IMPORTING orders TYPE ztt_order RETURNING VALUE(total) TYPE decfloat34. METHOD calculate_total. total = REDUCE decfloat34( INIT sum = CONV decfloat34( 0 ) FOR order IN orders NEXT sum += order-net_amount ). ENDMETHOD. ``` The improvement is not the shorter syntax. The method has an explicit input, one explicit result, no dependency on program global state, and a contract that can live behind an interface. --- ## 14. Testable Modular Design Merely extracting code into a method does not make it testable. A method that calls the database, system date, authorization, external service, and output UI directly still has many hidden dependencies. ```text Application service ├── zif_order_repository ├── zif_authorization ├── zif_clock └── pure amount/status policy ``` Inject dependencies through a constructor or factory-visible seam: ```abap METHODS constructor IMPORTING repository TYPE REF TO zif_order_repository authorization TYPE REF TO zif_order_authorization. ``` Then ABAP Unit tests can supply doubles implementing those interfaces. ### Design properties - **High cohesion:** one module owns one closely related responsibility. - **Low coupling:** consumers depend on small contracts, not implementation globals. - **Explicit dependencies:** database, time, authorization, and external calls are visible. - **Explicit effects:** mutation and persistence are not hidden in a “helper.” - **Stable abstraction:** names express business intent, not implementation steps such as `do_processing_2`. --- ## 15. Transaction Ownership A reusable procedure should not issue `COMMIT WORK` or `ROLLBACK WORK` unless its documented contract truly owns the complete SAP LUW. Otherwise it can prematurely commit changes made by its caller. ```text Caller/application boundary starts orchestration ├── validate ├── calculate ├── persist/register changes └── decide transaction completion ``` This is especially important when wrapping legacy function modules: inspect whether the called API performs commits, registers update tasks, sends messages, or mutates function-group global state. --- ## 16. Modularization in RAP ### 16.1 Framework entry points A RAP behavior pool is an ABAP class pool. The framework calls generated handler/saver method signatures based on the behavior definition. ```text Behavior definition declares operation/action/validation/determination ↓ RAP runtime invokes generated behavior-handler method ↓ Behavior method orchestrates EML and domain helpers ``` Do not rename generated method parameters or invent an unrelated callable name; the framework contract determines the signature. ### 16.2 Keep behavior methods thin enough ```abap METHOD validate_customer. " 1. Read required BO state with EML " 2. Delegate pure/customer-existence decision where useful " 3. Fill FAILED and REPORTED according to RAP contract ENDMETHOD. ``` Good extraction candidates include: - deterministic calculations; - state-transition policies; - message construction; - adapters around released external APIs; - repository/query logic with a test seam. Keep `%tky`, `%cid`, `%is_draft`, `FAILED`, `MAPPED`, and `REPORTED` handling at the RAP boundary unless a dedicated helper abstraction genuinely improves it. ### 16.3 Transaction rule Do not execute `COMMIT WORK` inside RAP behavior implementation. RAP owns the save sequence and transaction boundary. A legacy function module that commits internally is therefore dangerous to call from a RAP interaction/save flow. ### 16.4 Local mode is not modularization `IN LOCAL MODE` changes EML authorization/feature-control handling inside the current BO implementation context. It does not make the called logic a separate module and does not bypass validations or the transactional buffer. --- ## 17. ABAP Cloud and Clean-Core Boundary ABAP Cloud uses a restricted language version and released APIs to provide lifecycle-stable development. For new cloud-ready code: - use classes, interfaces, and methods; - use ADT as the development environment; - depend only on objects released for the required contract; - check API State, not merely whether an object exists; - avoid obsolete syntax such as `FORM`/`PERFORM`; - do not call an unreleased classic function module directly from clean-core code; - wrap permitted classic dependencies only within an intentional migration tier in applicable private/on-premise scenarios. A function module is not automatically forbidden because it is old, and a class is not automatically clean-core because it is object-oriented. The decisive questions are release state, allowed language version, and stability contract. --- ## 18. Naming Guidance Prefixes such as `iv_`, `ev_`, `cv_`, `lt_`, and `gt_` are team conventions, not ABAP language requirements. Use names that expose intent: ```abap METHODS calculate_total IMPORTING items TYPE ztt_order_item RETURNING VALUE(total) TYPE decfloat34. ``` This is usually clearer than encoding every implementation detail: ```abap METHODS calc IMPORTING it_data TYPE ztt_order_item RETURNING VALUE(rv_val) TYPE decfloat34. ``` Follow the project's agreed style consistently, but do not mistake prefixes for encapsulation or type safety. --- ## 19. Common Failure Modes | Symptom | Likely cause | Diagnostic direction | | ----------------------------------------- | ------------------------------------------------------------------- | -------------------------------------------------------------- | | Changing an include breaks several places | Shared source depends on different globals/contexts | Use where-used list; establish each compilation-unit contract | | `PERFORM` call dumps or behaves strangely | Parameter sequence/type mismatch or hidden globals | Compare caller/callee order and explicit types | | Function module call dumps | Missing, unknown, length-conflicting, or type-conflicting parameter | Read ST22 dump and compare SE37 interface with actual values | | `sy-subrc` handling is wrong | Caller mapped classic exceptions differently or checked too late | Read the exact `EXCEPTIONS` mapping immediately after the call | | Unit test depends on execution order | Static, global, `STATICS`, or function-group state | Reset/extract state; inject dependency | | Helper unexpectedly commits data | Procedure owns hidden transaction control | Inspect `COMMIT WORK`, update-task, RFC, and called APIs | | RAP transaction becomes inconsistent | Legacy call commits or bypasses BO contract | Keep transaction under RAP and use released/compatible APIs | | “Reusable” method cannot be reused | It reads globals, UI state, or database implicitly | Make inputs, outputs, effects, and dependencies explicit | | Static utility is impossible to fake | Consumer depends directly on static implementation | Introduce a small interface and instance collaborator | --- ## 20. Technical Review Workflow When reviewing a modularization problem: 1. **Identify the construct:** include, method, function module, `FORM`, macro, screen module, or event block. 2. **Identify the owner:** program, class, interface, function group, package, or framework. 3. **Write the real contract:** inputs, outputs, exceptions/messages, database effects, global state, commits, and external calls. 4. **Check call resolution:** static method, dynamic method, local/external `PERFORM`, local FM, RFC, update task, or framework callback. 5. **Check typing and parameter passing:** direction, reference/value, optional parameters, table types, and aliasing. 6. **Check lifecycle:** local invocation, object state, class/global state, function-group state, or internal session. 7. **Check test seam:** can dependencies be substituted without a real database, clock, authorization, or remote system? 8. **Check transaction ownership:** who is allowed to save, commit, or roll back? 9. **Check release contract:** is the dependency permitted in the target ABAP language version and API contract? 10. **Refactor by risk:** first expose hidden parameters and effects, then move behavior behind a method/interface. --- ## 21. Compact Syntax Sheet ```text Instance method object->method( ... ) Static method class=>method( ... ) Functional result DATA(result) = object->method( input ) Class-based failure TRY ... CATCH cx_... ENDTRY Include source INCLUDE source_name. Legacy subroutine PERFORM routine USING ... CHANGING ... FORM routine USING ... CHANGING ... ENDFORM. Function module CALL FUNCTION 'NAME' EXPORTING ... IMPORTING ... CHANGING ... EXCEPTIONS ... Remote function call CALL FUNCTION 'NAME' DESTINATION destination ... Update registration CALL FUNCTION 'NAME' IN UPDATE TASK ... ``` 2f:T93e,1. The Four Levels of Modularization The word module is ambiguous. First identify what is being separated. text Repository / deployment organization Package and software component │ Architectural contract Class, interface, released API │ Callable processing block Method, function module, legacy FORM routine │ Source-text organization INCLUDE | Level | Main question | Examples | | ---------------------- | --------------------------------------------------------------- | ------------------------------------- | | Package boundary | Which objects belong, depend on one another, and move together? | Package, software component | | Architectural boundary | What stable responsibility and contract are exposed? | Interface, global class, released API | | Procedure boundary | What inputs enter, what outputs leave, and what can fail? | Method, function module, FORM | | Source organization | In which source unit is this text maintained? | INCLUDE program | Splitting 2,000 lines into ten includes improves navigation, but does not by itself reduce shared state, coupling, side effects, or test difficulty. --- 2. Modern Decision Guide | Need | Preferred construct | Why | | -------------------------------------------------- | -------------------------------------------------- | ----------------------------------------------------------- | | Business/domain logic in new development | Instance method behind an interface | Encapsulation, substitution, testing, dependency injection | | Stateless utility with no substitutable dependency | Static method, used selectively | Simple call without object state | | One calculated result | Functional method with RETURNING | Natural expression-oriented call | | Existing classic reusable API | Existing function module | Preserve the supported contract; wrap when useful | | RFC or update-task infrastructure that requires it | Appropriately configured function module | Function modules provide these classic runtime capabilities | | Organizing a large legacy program | Include program | Source separation only | | Reading old procedural code | FORM/PERFORM | Compatibility and controlled refactoring | | New RAP business logic | Behavior implementation method plus helper classes | Framework contract plus testable domain logic | Default rule for new code: text Interface → class → small cohesive methods Do30:Tc2b,## 1. The Four Levels of Modularization The word **module** is ambiguous. First identify what is being separated. ```text Repository / deployment organization Package and software component │ Architectural contract Class, interface, released API │ Callable processing block Method, function module, legacy FORM routine │ Source-text organization INCLUDE ``` | Level | Main question | Examples | | ---------------------- | --------------------------------------------------------------- | ------------------------------------- | | Package boundary | Which objects belong, depend on one another, and move together? | Package, software component | | Architectural boundary | What stable responsibility and contract are exposed? | Interface, global class, released API | | Procedure boundary | What inputs enter, what outputs leave, and what can fail? | Method, function module, `FORM` | | Source organization | In which source unit is this text maintained? | `INCLUDE` program | Splitting 2,000 lines into ten includes improves navigation, but does not by itself reduce shared state, coupling, side effects, or test difficulty. --- ## 2. Modern Decision Guide | Need | Preferred construct | Why | | -------------------------------------------------- | -------------------------------------------------- | ----------------------------------------------------------- | | Business/domain logic in new development | Instance method behind an interface | Encapsulation, substitution, testing, dependency injection | | Stateless utility with no substitutable dependency | Static method, used selectively | Simple call without object state | | One calculated result | Functional method with `RETURNING` | Natural expression-oriented call | | Existing classic reusable API | Existing function module | Preserve the supported contract; wrap when useful | | RFC or update-task infrastructure that requires it | Appropriately configured function module | Function modules provide these classic runtime capabilities | | Organizing a large legacy program | Include program | Source separation only | | Reading old procedural code | `FORM`/`PERFORM` | Compatibility and controlled refactoring | | New RAP business logic | Behavior implementation method plus helper classes | Framework contract plus testable domain logic | Default rule for new code:31:T7fb5, ## 1. The Correct Overall Mental Model A classic executable report is **event-driven**. Source-code position does not mean that ABAP simply executes every line from top to bottom. The ABAP runtime framework raises events and calls the matching event blocks. The selection screen also creates a loop: ```text Program requested │ ▼ Program loaded into internal session, if not already loaded │ ├─ global/static initialization performed by runtime └─ LOAD-OF-PROGRAM event block, if defined │ ▼ INITIALIZATION │ ▼ AT SELECTION-SCREEN OUTPUT selection-screen PBO │ ▼ Selection screen displayed │ ▼ User action │ ├─ F4 help ───────────────► ON VALUE-REQUEST FOR field │ │ │ └─ redisplay loop │ ├─ F1 help ───────────────► ON HELP-REQUEST FOR field │ │ │ └─ redisplay loop │ ├─ Enter / pushbutton / │ radio USER-COMMAND ────► selection-screen PAI events │ │ │ └─ AT SELECTION-SCREEN OUTPUT │ → redisplay │ └─ Execute F8 ─────────────► selection-screen PAI validation │ ├─ validation error │ └─ OUTPUT → redisplay │ └─ validation succeeds └─ START-OF-SELECTION │ ├─ report application logic ├─ END-OF-SELECTION, if defined └─ output/list processing ``` The straight-line version from the initial draft omitted the redisplay cycle. `AT SELECTION-SCREEN OUTPUT` can run many times; `INITIALIZATION` normally runs once for that report execution before the standard selection screen first appears. --- ## 2. Report Source Layout Versus Runtime Order A maintainable report can be arranged like this: ```abap REPORT zsales_order_report. " Global declarations and selection-screen definition TABLES sscrfields. PARAMETERS: p_open RADIOBUTTON GROUP mode DEFAULT 'X' USER-COMMAND mode, p_all RADIOBUTTON GROUP mode. SELECT-OPTIONS s_order FOR vbak-vbeln. CLASS lcl_application DEFINITION FINAL. PUBLIC SECTION. CLASS-METHODS run. ENDCLASS. CLASS lcl_application IMPLEMENTATION. METHOD run. " Application orchestration ENDMETHOD. ENDCLASS. INITIALIZATION. " One-time selection defaults AT SELECTION-SCREEN OUTPUT. " Dynamic screen attributes before each display AT SELECTION-SCREEN. " Cross-field/action validation START-OF-SELECTION. lcl_application=>run( ). ``` The physical order improves readability, but runtime execution is determined by events. Each event block begins with an event keyword and ends at the next processing block or the end of the program; there is no `END-...` statement. Keep event blocks thin and delegate application logic to methods. This prevents the report framework, selection-screen state, database logic, and output logic from becoming one inseparable procedure. ### 2.1 Declaration-scope trap Most event blocks are not ordinary procedures. Declarations written inside them belong to the compilation unit's global declarations and remain visible in subsequent processing blocks. Selection-screen and logical-database event blocks are special runtime implementations that can allow local declarations, but a consistent design should still put working data inside called methods. ```abap START-OF-SELECTION. DATA result TYPE string. " Do not assume method-local lifecycle semantics lcl_application=>run( ). ``` The safe architectural rule is not “declare globals inside an event.” It is “use the event as a thin framework adapter and work locally inside methods.” --- ## 3. Phase 1 — Program Load ### 3.1 What “load” means When the executable program is first needed in an internal session, its load is made available and its global data context is initialized. Programs already loaded in the same internal session need not be loaded again simply because a procedure is called again. Do not confuse: ```text Repository activation/generation creates or updates executable program load Runtime loading brings the program into an internal session for execution ``` ### 3.2 `LOAD-OF-PROGRAM` Contrary to the draft statement, this is a definable event block: ```abap LOAD-OF-PROGRAM. " Rarely needed in an ordinary report ``` It is the program constructor event and occurs when the program is loaded into an internal session. It is not the normal place for user defaults or report business processing. Typical guidance: - Use declaration-time initialization for simple constants/default state. - Use `INITIALIZATION` for initial selection-screen values. - Use constructors for object initialization. - Avoid database updates, user interaction, commits, or large queries in `LOAD-OF-PROGRAM`. ### 3.3 Why it may run less often than expected `LOAD-OF-PROGRAM` is associated with loading the program, not every selection-screen redisplay. If the program remains loaded in the internal session, repeated calls or interactions do not imply repeated program-load events. --- ## 4. Phase 2 — `INITIALIZATION` `INITIALIZATION` occurs before the standard selection screen is first processed for the report execution. ```abap PARAMETERS p_date TYPE sy-datum. INITIALIZATION. p_date = sy-datum. ``` Good uses: - calculate initial date ranges; - choose a sensible initial radio button; - initialize selection-screen texts or pushbutton labels; - supply lightweight defaults that should occur once. Avoid: - repeatedly controlling whether a field is visible or editable; - expensive report data selection; - changing database state; - authorization enforcement that must also protect background execution or non-screen entry points. ### 4.1 `DEFAULT` versus `INITIALIZATION` ```abap PARAMETERS p_status TYPE c LENGTH 1 DEFAULT 'O'. ``` Use declaration `DEFAULT` for a static initial value. Use `INITIALIZATION` when the starting value requires runtime calculation. ### 4.2 Why not put dynamic screen logic here? `INITIALIZATION` does not run on every redisplay. If screen input readiness depends on the currently selected radio button, use `AT SELECTION-SCREEN OUTPUT`. Also distinguish an initial proposal from the effective runtime selection. Selection variants, SPA/GPA memory values, `SUBMIT` parameters, or previous user input can influence values later in the screen lifecycle. When debugging, inspect the value at `AT SELECTION-SCREEN OUTPUT` and again in PAI instead of assuming the value assigned during `INITIALIZATION` is still effective. --- ## 5. Phase 3 — Selection-Screen PBO `AT SELECTION-SCREEN OUTPUT` is the Process Before Output event of the selection screen. It runs directly before the screen is displayed and can run repeatedly. ```abap PARAMETERS: p_file RADIOBUTTON GROUP mode DEFAULT 'X' USER-COMMAND mode, p_order RADIOBUTTON GROUP mode, p_path TYPE string LOWER CASE MODIF ID fil, p_vbeln TYPE vbak-vbeln MODIF ID ord. AT SELECTION-SCREEN OUTPUT. LOOP AT SCREEN. CASE screen-group1. WHEN 'FIL'. screen-active = xsdbool( p_file = abap_true ). WHEN 'ORD'. screen-active = xsdbool( p_order = abap_true ). ENDCASE. MODIFY SCREEN. ENDLOOP. ``` `MODIF ID fil` is represented in `SCREEN-GROUP1` as uppercase `FIL`. ### 5.1 Common `SCREEN` fields | Field | Purpose | | --------------------------------------- | ----------------------------------------- | | `SCREEN-GROUP1` | Modification group from `MODIF ID` | | `SCREEN-ACTIVE` | Combined active/inactive control | | `SCREEN-INPUT` | Input enabled/disabled | | `SCREEN-INVISIBLE` | Visible/hidden behavior | | `SCREEN-REQUIRED` | Visual/required-state control | | `SCREEN-DISPLAY_3D` or other attributes | Release/UI-specific presentation controls | Always execute `MODIFY SCREEN` for a changed row of the special `SCREEN` table. ### 5.2 Idempotence rule Implement output logic so the correct screen state is recalculated from the current selection values on every PBO. Do not rely on the event running only once or on the previous display state. --- ## 6. Phase 4 — Screen Display and User Action After PBO, the selection screen is sent to the presentation layer. The user can enter values, request help, choose a command, press Enter, or execute. The action determines the next event path. “User does something” is therefore not one event. | User action | Important event path | | ------------------------------------------ | ------------------------------------------------------------- | | Press F4 on a field | `ON VALUE-REQUEST FOR field` | | Press F1 on a field | `ON HELP-REQUEST FOR field` | | Change radio/checkbox with `USER-COMMAND` | Selection-screen PAI; then redisplay | | Press a custom selection-screen pushbutton | Selection-screen PAI; then usually redisplay | | Press Enter | Selection-screen PAI; then redisplay | | Press Execute F8 | Selection-screen PAI; if valid, leave screen and start report | | Press Back/Exit/Cancel | Exit-command handling and screen termination path | --- ## 7. F4 Value Help: `ON VALUE-REQUEST` Use a custom value-request event only when Dictionary/search-help behavior does not already provide the correct F4 help. ```abap AT SELECTION-SCREEN ON VALUE-REQUEST FOR p_path. p_path = lcl_file_dialog=>choose_file( ). ``` Flow: ```text User presses F4 on p_path → AT SELECTION-SCREEN ON VALUE-REQUEST FOR p_path → custom logic proposes/sets a value → selection screen is displayed again ``` This is not the report's business validation event and does not proceed to `START-OF-SELECTION`. ### 7.1 Prefer metadata-driven value help If the parameter refers to a DDIC field with a search help, check table, or fixed domain values, the runtime can often supply value help automatically. Do not replace correct metadata with unnecessary custom F4 code. ### 7.2 Security rule Value help narrows or proposes input; it is not authorization enforcement and does not guarantee that submitted input is valid. Validate the final value and perform authorization checks at the execution boundary. --- ## 8. F1 Help: `ON HELP-REQUEST` ```abap AT SELECTION-SCREEN ON HELP-REQUEST FOR p_path. lcl_help=>show_path_explanation( ). ``` Use this only when standard field/documentation help is insufficient. Like F4, it is a help request, not successful report execution. --- ## 9. Radio Buttons and `USER-COMMAND` Changing a radio button does **not** necessarily cause an immediate server round trip. Associate a function code when the selection should trigger dynamic screen modification: ```abap PARAMETERS: p_file RADIOBUTTON GROUP mode DEFAULT 'X' USER-COMMAND mode, p_order RADIOBUTTON GROUP mode. ``` The command is assigned to the group through the first declared radio button. On selection: ```text Radio selection changes → function code MODE is sent → selection-screen PAI events run → AT SELECTION-SCREEN OUTPUT recalculates field state → screen is redisplayed ``` Access the function code through `SSCRFIELDS-UCOMM` in classic code: ```abap TABLES sscrfields. AT SELECTION-SCREEN. CASE sscrfields-ucomm. WHEN 'MODE'. " Usually no business execution here; allow redisplay ENDCASE. ``` Radio-button user commands are well suited to screen adaptation, not to running the main report. F8 remains the normal transition to report execution. --- ## 10. Phase 5 — Selection-Screen PAI and Validation PAI transfers input from the screen and raises the relevant `AT SELECTION-SCREEN` events. Think of validation as layers from narrow to broad. ```text Field or selection-criterion checks → end-of-multiple-selection checks → radio-button-group checks → block checks → generic AT SELECTION-SCREEN command/cross-field check ``` The exact triggered subset depends on the screen fields and user action. ### 10.1 Validate one parameter ```abap AT SELECTION-SCREEN ON p_vbeln. IF p_order = abap_true AND p_vbeln IS INITIAL. MESSAGE e001(zreport) WITH 'Enter a sales order'. ENDIF. ``` Use for a rule local to that field. A radio-button field is validated with the group event rather than an individual field event. ### 10.2 Validate a radio-button group ```abap AT SELECTION-SCREEN ON RADIOBUTTON GROUP mode. IF p_file = abap_false AND p_order = abap_false. MESSAGE e002(zreport) WITH 'Choose a mode'. ENDIF. ``` ### 10.3 Validate a block ```abap SELECTION-SCREEN BEGIN OF BLOCK criteria WITH FRAME TITLE text-t01. PARAMETERS p_vbeln TYPE vbak-vbeln. SELECT-OPTIONS s_date FOR sy-datum. SELECTION-SCREEN END OF BLOCK criteria. AT SELECTION-SCREEN ON BLOCK criteria. IF p_vbeln IS INITIAL AND s_date[] IS INITIAL. MESSAGE e003(zreport) WITH 'Enter an order or date range'. ENDIF. ``` ### 10.4 Validate a complete `SELECT-OPTIONS` criterion ```abap AT SELECTION-SCREEN ON END OF s_date. LOOP AT s_date ASSIGNING FIELD-SYMBOL(<date_range>). IF <date_range>-option = 'BT' AND <date_range>-low > <date_range>-high. MESSAGE e004(zreport) WITH 'Invalid date interval'. ENDIF. ENDLOOP. ``` The selection criterion is a range-like table containing `SIGN`, `OPTION`, `LOW`, and `HIGH`. Validate the whole selection table when intervals or multiple rows interact. ### 10.5 Generic `AT SELECTION-SCREEN` ```abap AT SELECTION-SCREEN. CASE sscrfields-ucomm. WHEN 'ONLI'. " Common Execute function code; verify in target context lcl_selection_validator=>validate( file_mode = p_file path = p_path order = p_vbeln ). WHEN 'MODE'. " Dynamic mode switch; return to screen ENDCASE. ``` Use the generic event for cross-field validation and command handling. Do not hard-code a function code without confirming the actual selection-screen context. --- ## 11. Validation Failure and Redisplay An error message during selection-screen validation prevents the transition to `START-OF-SELECTION` and returns control to the selection screen. ```text Execute F8 → PAI validation → MESSAGE E → validation stops → AT SELECTION-SCREEN OUTPUT → corrected screen displayed ``` This is why `AT SELECTION-SCREEN OUTPUT` must tolerate repeated execution. `OBLIGATORY` provides basic required-input checking, but it does not replace cross-field business validation, existence checks, or authorization checks. ### 11.1 Message types are context-sensitive `MESSAGE E`, `W`, `I`, `S`, `A`, and `X` do not have one universal control-flow meaning independent of their processing context. In selection-screen PAI, error messages can return the user to input. In other report phases, the same message type can have a different runtime consequence. Diagnose the event and dialog context, not only the letter. --- ## 12. Exit Commands Back, Exit, and Cancel are exit-type commands. Use the specialized event only when cleanup or confirmation is genuinely necessary: ```abap AT SELECTION-SCREEN ON EXIT-COMMAND. " Avoid validation that traps the user on a screen they are leaving ``` This event is designed to handle exit commands before ordinary selection-screen validation prevents leaving because of invalid field content. Do not perform report business processing here. --- ## 13. Phase 6 — `START-OF-SELECTION` After the user chooses Execute and selection-screen processing succeeds, the runtime raises `START-OF-SELECTION`. ```abap START-OF-SELECTION. lcl_application=>run( ). ``` This is the report's standard processing block and should usually be its thin application entry point. Typical application flow: ```text START-OF-SELECTION → create application/service objects → enforce execution authorization → convert selection-screen globals into an input structure → read data set-wise → apply business rules → prepare result model → render output ``` ### 13.1 Implicit `START-OF-SELECTION` Executable statements written before the first explicit processing block are assigned to an implicit `START-OF-SELECTION` block. If no explicit event blocks exist, all functional statements form the implicit standard event. Avoid this confusing layout: ```abap REPORT zbad_layout. DATA value TYPE i. value = 10. " Implicit START-OF-SELECTION START-OF-SELECTION. value += 1. " A separate explicit event block ``` Prefer an explicit event keyword and a thin method call so runtime placement is obvious. --- ## 14. `END-OF-SELECTION` Historically, `END-OF-SELECTION` marks processing after a logical database has finished supplying rows through `GET` events. ```abap END-OF-SELECTION. " Final processing after logical-database selection ``` Without a logical database, it follows standard selection processing but often adds no useful architectural boundary. Do not use it simply because its name sounds like the required end of every report. A modern report can orchestrate its complete flow from a method called at `START-OF-SELECTION`. --- ## 15. Logical-Database Events Older reports can be linked to a logical database and receive node data through events such as: ```abap GET node. " Process one logical-database node instance GET node LATE. " Process after subordinate nodes ``` Conceptual runtime: ```text START-OF-SELECTION → logical database reads nodes → GET parent → GET child → GET parent LATE → END-OF-SELECTION ``` Recognize this in legacy reports. For new data access, prefer explicit Open SQL, CDS entities, and released APIs according to the target development model. --- ## 16. Output and List Events ### 16.1 Simple/classic list `WRITE` produces classic list output. Page/list processing can raise events such as: - `TOP-OF-PAGE` - `END-OF-PAGE` - `AT LINE-SELECTION` - `AT USER-COMMAND` Interactive list events happen after initial report processing, in response to the user acting on the displayed list. They are not part of the selection- screen validation sequence. ### 16.2 ALV/SALV For tabular results, ALV/SALV typically provides sorting, filtering, totals, layout variants, and event callbacks. Keep retrieval and business logic independent from the chosen renderer so they can be tested without a GUI. ```text Selection model → application service → result table → ALV adapter ``` --- ## 17. Complete Worked Flow ```abap REPORT zorder_extract. TABLES sscrfields. PARAMETERS: p_order RADIOBUTTON GROUP mode DEFAULT 'X' USER-COMMAND mode, p_file RADIOBUTTON GROUP mode, p_vbeln TYPE vbak-vbeln MODIF ID ord, p_path TYPE string LOWER CASE MODIF ID fil. INITIALIZATION. p_order = abap_true. AT SELECTION-SCREEN OUTPUT. LOOP AT SCREEN. CASE screen-group1. WHEN 'ORD'. screen-active = xsdbool( p_order = abap_true ). WHEN 'FIL'. screen-active = xsdbool( p_file = abap_true ). ENDCASE. MODIFY SCREEN. ENDLOOP. AT SELECTION-SCREEN ON VALUE-REQUEST FOR p_path. p_path = lcl_file_dialog=>choose_file( ). AT SELECTION-SCREEN. IF sscrfields-ucomm = 'ONLI'. IF p_order = abap_true AND p_vbeln IS INITIAL. MESSAGE e001(zreport) WITH 'Enter a sales order'. ENDIF. IF p_file = abap_true AND p_path IS INITIAL. MESSAGE e002(zreport) WITH 'Choose a file'. ENDIF. ENDIF. START-OF-SELECTION. lcl_application=>run( order_mode = p_order order = p_vbeln file_mode = p_file path = p_path ). ``` ### 17.1 Initial display ```text Program begins → INITIALIZATION selects order mode → OUTPUT activates p_vbeln and deactivates p_path → screen displayed ``` ### 17.2 User selects file mode ```text USER-COMMAND MODE → AT SELECTION-SCREEN handles round trip → OUTPUT deactivates p_vbeln and activates p_path → screen displayed again ``` ### 17.3 User presses F4 on path ```text F4 → ON VALUE-REQUEST FOR p_path → dialog result assigned → screen displayed again ``` ### 17.4 User presses Execute without a path ```text F8 / ONLI → AT SELECTION-SCREEN → MESSAGE E → START-OF-SELECTION does not run → OUTPUT → screen displayed for correction ``` ### 17.5 User presses Execute with valid input ```text F8 / ONLI → AT SELECTION-SCREEN validation succeeds → START-OF-SELECTION → lcl_application=>run( ) → result output ``` --- ## 18. Dialog, Background, and `SUBMIT` Are Different Entry Modes The main diagram describes an interactive SAP GUI execution. Reports can also run through a background job or `SUBMIT`. ### 18.1 Background job A job normally receives saved selection values through a variant and has no interactive user available for F4 help, popups, or correction dialogs. ```abap IF sy-batch = abap_true. " Use background-safe logging/output; never require a frontend file dialog ENDIF. ``` Selection-screen UI convenience is therefore not a reliable business-security boundary. Validate the effective execution input and authorization in a background-safe application layer. ### 18.2 `SUBMIT` ```abap SUBMIT ztarget_report WITH p_vbeln = order AND RETURN. ``` `SUBMIT` starts an executable program and supplies selection values. Additions such as `VIA SELECTION-SCREEN`, `USING SELECTION-SET`, background-job options, and list export change the invocation behavior. Dynamic report names are a security risk when they originate externally. Use an allowlist and proper authorization checks. ### 18.3 Design consequence Do not place core business rules only in F4 handlers, screen PBO, or GUI-only validation. Extract an application service that can receive the same input from dialog, job, test, or another allowed entry point. --- ## 19. Selection Screen Versus Application Validation | Concern | Selection-screen layer | Application/domain layer | | --------------------------- | -------------------------- | ---------------------------------------- | | Enable/disable a field | Yes | No | | Show F4 help | Yes | No | | Basic cross-field usability | Yes | Often repeated as invariant if important | | Authorization to read order | May provide early feedback | Must enforce before protected access | | Business invariant | Helpful early feedback | Must be authoritative | | Database consistency | No | Persistence/transaction boundary | | Background-safe execution | Not guaranteed | Required | This parallels RAP: UI metadata and value help improve interaction, while the backend business object must still enforce invariants and authorization. --- ## 20. Program Structure Recommendation ```text Executable report ├── selection-screen declarations ├── INITIALIZATION initial UI defaults ├── AT SELECTION-SCREEN OUTPUT dynamic UI state ├── AT SELECTION-SCREEN ... early input feedback └── START-OF-SELECTION thin application entry │ ▼ Application class ├── authorization ├── input validation ├── query/repository ├── domain transformation └── output adapter ``` Use includes only for source organization when necessary. They do not replace the method/class boundaries described in the [ABAP Modularization reference](./abap-modularization-technical-reference.md). Use explicit internal-table types and access patterns from the [ABAP Internal Tables reference](./abap-internal-tables-technical-reference.md). --- ## 21. Transaction and Side-Effect Rules - Do not update persistent business data during `INITIALIZATION` or screen PBO. - F4/F1 handlers should provide help, not perform commits. - Separate report/query output from update transactions where possible. - If the report performs updates, document authorization, locking, validation, update API, commit ownership, restart behavior, and audit logging. - Do not call `COMMIT WORK` inside a reusable helper that does not own the whole SAP LUW. - A report that calls a BAPI/function module must inspect whether that API performs commits or expects the caller to commit. - For RAP business objects, use EML and allow RAP to own its transaction model; do not reproduce RAP save behavior in a classic report. --- ## 22. Debugging and Operations Map | Need | Classic tool/transaction | Evidence | | --------------------------- | ------------------------------------------------------- | ------------------------------------------- | | Execute/test report | `SE38` or `SA38` | Selection values, event behavior, output | | Repository navigation | `SE80` or ADT | Program, includes, classes, where-used | | Debug event sequence | ADT/SAP GUI debugger | Breakpoints in each event block; call stack | | Analyze short dump | `ST22` | Runtime error, source position, call stack | | Runtime performance | `SAT` | Call hierarchy and ABAP runtime cost | | SQL trace | `ST05` | SQL statements, executions, rows, duration | | System-wide SQL aggregation | `SQLM` where available | Repeated SQL workload evidence | | Background execution | `SM37` | Job step, variant, spool, status, job log | | Authorization failure | `SU53` immediately after failure; trace when authorized | Failed authorization objects/fields | | Application log | `SLG1` when the report writes application logs | Durable business/technical messages | ### 22.1 Event-flow debugging sequence 1. Set breakpoints in `LOAD-OF-PROGRAM`, `INITIALIZATION`, `AT SELECTION-SCREEN OUTPUT`, the relevant field/value-help event, generic `AT SELECTION-SCREEN`, and `START-OF-SELECTION`. 2. Start a new execution context and record which breakpoints occur. 3. Trigger a radio-button user command and observe the PAI → PBO redisplay loop. 4. Trigger F4 and distinguish its request path. 5. Execute once with invalid input and prove that `START-OF-SELECTION` is not reached. 6. Execute with valid input and inspect the transition to the application method. 7. Repeat in background only after removing GUI-dependent assumptions. --- ## 23. Common Misinterpretations | Misinterpretation | Correction | | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | “ABAP executes a report top to bottom.” | The runtime invokes event blocks according to the report and screen lifecycle. | | “`LOAD-OF-PROGRAM` is implicit and cannot be defined.” | It is a definable program-constructor event, though rarely needed in an ordinary report. | | “`INITIALIZATION` runs before every display.” | It initializes before the first standard-screen processing; PBO can repeat. | | “Changing any radio button immediately triggers an event.” | Immediate round trip requires an associated `USER-COMMAND` or another screen command. | | “F4 executes `AT SELECTION-SCREEN` like F8.” | Custom F4 uses `ON VALUE-REQUEST`; it does not start report execution. | | “`OUTPUT` means report result output.” | `AT SELECTION-SCREEN OUTPUT` is selection-screen PBO before display. | | “Every `AT SELECTION-SCREEN` event always runs.” | The triggered variants depend on fields and the user's action. | | “F8 directly calls `START-OF-SELECTION`.” | Selection-screen PAI and validation must succeed first. | | “`END-OF-SELECTION` is mandatory.” | It is especially meaningful with logical databases and is not required for every report. | | “A required screen field enforces the business rule everywhere.” | Screen checks do not replace application authorization and invariants. | | “Report event blocks are local procedures.” | Most event blocks work with compilation-unit global data; keep them thin. | | “The same interactive flow occurs in background.” | Background processing has no user-driven F4 or correction loop. | --- ## 24. Compact Event Reference | Event | Frequency/trigger | Main responsibility | | -------------------------------- | ------------------------------------------------- | -------------------------------------- | | `LOAD-OF-PROGRAM` | When program is loaded into internal session | Rare program-constructor logic | | `INITIALIZATION` | Before first standard selection-screen processing | Initial selection defaults | | `AT SELECTION-SCREEN OUTPUT` | Before every relevant display | Dynamic screen attributes | | `... ON VALUE-REQUEST FOR field` | User presses F4 | Custom value help | | `... ON HELP-REQUEST FOR field` | User presses F1 | Custom field help | | `... ON field` | Selection-screen PAI for field | Field validation | | `... ON END OF selcrit` | Whole selection criterion available | Multiple/range validation | | `... ON RADIOBUTTON GROUP group` | Radio group processed in PAI | Group validation | | `... ON BLOCK block` | Block processed in PAI | Related-field validation | | `AT SELECTION-SCREEN` | General PAI event | Command and cross-field validation | | `... ON EXIT-COMMAND` | Exit-type command | Safe leave/cleanup behavior | | `START-OF-SELECTION` | Selection processing succeeded | Main application entry | | `GET node` | Logical database provides node | Legacy logical-database row processing | | `END-OF-SELECTION` | Selection/logical DB processing completes | Legacy/final report processing | | List events | User/page activity on classic list | Classic output interaction | --- 32:T9dd,1. The Correct Overall Mental Model A classic executable report is event-driven. Source-code position does not mean that ABAP simply executes every line from top to bottom. The ABAP runtime framework raises events and calls the matching event blocks. The selection screen also creates a loop: text Program requested │ ▼ Program loaded into internal session, if not already loaded │ ├─ global/static initialization performed by runtime └─ LOAD-OF-PROGRAM event block, if defined │ ▼ INITIALIZATION │ ▼ AT SELECTION-SCREEN OUTPUT selection-screen PBO │ ▼ Selection screen displayed │ ▼ User action │ ├─ F4 help ───────────────► ON VALUE-REQUEST FOR field │ │ │ └─ redisplay loop │ ├─ F1 help ───────────────► ON HELP-REQUEST FOR field │ │ │ └─ redisplay loop │ ├─ Enter / pushbutton / │ radio USER-COMMAND ────► selection-screen PAI events │ │ │ └─ AT SELECTION-SCREEN OUTPUT │ → redisplay │ └─ Execute F8 ─────────────► selection-screen PAI validation │ ├─ validation error │ └─ OUTPUT → redisplay │ └─ validation succeeds └─ START-OF-SELECTION │ ├─ report application logic ├─ END-OF-SELECTION, if defined └─ output/list processing The straight-line version from the initial draft omitted the redisplay cycle. AT SELECTION-SCREEN OUTPUT can run many times; INITIALIZATION normally runs once for that report execution before the standard selection screen first appears. --- 2. Report Source Layout Versus Runtime Order A maintainable report can be arranged like this: abap REPORT zsalesorderreport. " Global declarations and selection-screen definition TABLES sscrfields. PARAMETERS: popen RADIOBUTTON GROUP mode DEFAULT 'X' USER-COMMAND mode, pall RADIOBUTTON GROUP mode. SELECT-OPTIONS sorder FOR vbak-vbeln. CLASS lclapplication DEFINITION FINAL. PUBLIC SECTION. CLASS-METHODS run. ENDCLASS. CLASS lclapplication IMPLEMENTATION. METHOD run. " Application orchestration ENDMETHOD. ENDCLASS. INITIALIZATION. " One-time selection defaults AT SELECTION-SCREEN OUTPUT. " Dynamic screen attributes before each display AT SELECTION-SCREEN. " Cross-field/action validation START-OF-SELECTION. lclapplication=run( ). The physical order improves readability, but runtime execution is determined by events. Each event block begins with an event keyword and ends at the next processing block or the end of33:Tc52,## 1. The Correct Overall Mental Model A classic executable report is **event-driven**. Source-code position does not mean that ABAP simply executes every line from top to bottom. The ABAP runtime framework raises events and calls the matching event blocks. The selection screen also creates a loop: ```text Program requested │ ▼ Program loaded into internal session, if not already loaded │ ├─ global/static initialization performed by runtime └─ LOAD-OF-PROGRAM event block, if defined │ ▼ INITIALIZATION │ ▼ AT SELECTION-SCREEN OUTPUT selection-screen PBO │ ▼ Selection screen displayed │ ▼ User action │ ├─ F4 help ───────────────► ON VALUE-REQUEST FOR field │ │ │ └─ redisplay loop │ ├─ F1 help ───────────────► ON HELP-REQUEST FOR field │ │ │ └─ redisplay loop │ ├─ Enter / pushbutton / │ radio USER-COMMAND ────► selection-screen PAI events │ │ │ └─ AT SELECTION-SCREEN OUTPUT │ → redisplay │ └─ Execute F8 ─────────────► selection-screen PAI validation │ ├─ validation error │ └─ OUTPUT → redisplay │ └─ validation succeeds └─ START-OF-SELECTION │ ├─ report application logic ├─ END-OF-SELECTION, if defined └─ output/list processing ``` The straight-line version from the initial draft omitted the redisplay cycle. `AT SELECTION-SCREEN OUTPUT` can run many times; `INITIALIZATION` normally runs once for that report execution before the standard selection screen first appears. --- ## 2. Report Source Layout Versus Runtime Order A maintainable report can be arranged like this: ```abap REPORT zsales_order_report. " Global declarations and selection-screen definition TABLES sscrfields. PARAMETERS: p_open RADIOBUTTON GROUP mode DEFAULT 'X' USER-COMMAND mode, p_all RADIOBUTTON GROUP mode. SELECT-OPTIONS s_order FOR vbak-vbeln. CLASS lcl_application DEFINITION FINAL. PUBLIC SECTION. CLASS-METHODS run. ENDCLASS. CLASS lcl_application IMPLEMENTATION. METHOD run. " Application orchestration ENDMETHOD. ENDCLASS. INITIALIZATION. " One-time selection defaults AT SELECTION-SCREEN OUTPUT. " Dynamic screen attributes before each display AT SELECTION-SCREEN. " Cross-field/action validation START-OF-SELECTION. lcl_application=>run( ). ```34:T7d7b, ## 1. What ALV Is — and Is Not ALV, the SAP List Viewer, is a presentation framework for structured datasets. It can supply standard user functions such as sorting, filtering, totals, subtotals, layouts, printing, and export. ```text Database / CDS / released API │ ▼ Application reads, authorizes, and derives data │ ▼ Internal table = report output model │ ▼ ALV renders List, Grid, or Tree │ ▼ User sorts, filters, selects, navigates, or edits ``` ALV does **not** by itself: - read the correct business data; - authorize a user to see or change that data; - enforce business invariants; - persist edited cells; - fix duplicate rows caused by an incorrect SQL join; - turn a classic report into a Fiori or RAP application. Think of ALV as the report's **view and interaction adapter**. The internal table is its input model; application methods own the business behavior. --- ## 2. End-to-End Runtime Flow For a read-only executable report using SALV: ```text Program/report starts │ ▼ Selection-screen lifecycle │ defaults → dynamic PBO → user input → validation ▼ START-OF-SELECTION │ ├─ authorize requested scope ├─ read through an appropriate CDS view/API/Open SQL ├─ calculate and map the output model └─ return an internal table │ ▼ CL_SALV_TABLE=>FACTORY │ ├─ configure functions, columns, sorts, layout, events └─ DISPLAY │ ▼ User sorts/filters/totals/exports or triggers navigation ``` For an editable GUI grid, the display is only half the workflow: ```text Application internal table │ ▼ CL_GUI_ALV_GRID display │ ▼ User edits a frontend cell │ ├─ REGISTER_EDIT_EVENT / DATA_CHANGED └─ CHECK_CHANGED_DATA transfers/checks pending frontend changes │ ▼ Application validates values and authorization │ ├─ invalid → protocol/message; do not save └─ valid → released update API / BAPI / application service / EML │ ▼ transaction owner commits │ ▼ refresh application data and ALV ``` The decisive point is: **an editable cell is not a database update**. `CHECK_CHANGED_DATA` is part of synchronizing/validating the grid state; it is not persistence. --- ## 3. The Three Presentation Shapes People often say “ALV list, grid, and tree.” These are presentation shapes, not three levels of the same report. | Shape | Data relationship | Best fit | Typical technology | | -------- | ------------------------------------------------ | ---------------------------------------- | -------------------------------------------------------------------------- | | **List** | Flat rows or classic two-level sequential output | Printing, spool, legacy reports | Classic ALV list; `CL_SALV_HIERSEQ_TABLE` for two-level header/item output | | **Grid** | Flat two-dimensional table | Interactive analysis; optionally editing | `CL_SALV_TABLE` or `CL_GUI_ALV_GRID` | | **Tree** | Nodes with explicit parent/child relationships | Hierarchy navigation | `CL_SALV_TREE` or `CL_GUI_ALV_TREE` | SAP's ALV object model names the core structural forms more precisely: - `CL_SALV_TABLE`: simple, two-dimensional table; - `CL_SALV_HIERSEQ_TABLE`: hierarchical-sequential header/item list; - `CL_SALV_TREE`: arbitrary tree structure. Therefore, “list versus grid” can also describe the **rendering technology** of a simple table, while table versus hierarchy describes the **data shape**. Ask which meaning a colleague intends before choosing a class. ### 3.1 List view A list-oriented result is appropriate when printable sequential output matters more than rich cell interaction. It is also the conceptually safer direction for a background job that must create spool output. For the SALV simple-table model, the factory's `LIST_DISPLAY` choice selects a classic list-style rendering instead of the normal fullscreen grid rendering: ```abap cl_salv_table=>factory( EXPORTING list_display = abap_true IMPORTING r_salv_table = DATA(alv) CHANGING t_table = output ). alv->display( ). ``` This is an important distinction: `CL_SALV_TABLE` identifies the simple two-dimensional **data model**; `LIST_DISPLAY` influences its **display mode**. Always test printing and background behavior on the target release rather than inferring it only from the class name. Classic APIs such as `REUSE_ALV_LIST_DISPLAY` and `REUSE_ALV_GRID_DISPLAY_LVC` still appear in existing systems. Their `SLIS_*` and `LVC_*` metadata must be understood for maintenance, but new OO-oriented code should normally consider the ALV object model first when its capabilities fit. ### 3.2 Grid view A grid displays a flat table with columns and rows. Choose: - `CL_SALV_TABLE` for concise, mostly read-only reporting; - `CL_GUI_ALV_GRID` when you need editable cells, detailed grid events, a custom toolbar, or precise embedding in a screen/container. ### 3.3 Tree view A tree represents real hierarchy. Each node has identity and a relationship to a parent node. Sorting a flat table and indenting text does not create a sound tree model. Examples: ```text Sales Order 50000123 ├─ Item 10 │ ├─ Schedule line 1 │ └─ Schedule line 2 └─ Item 20 └─ Schedule line 1 ``` Use `CL_SALV_TREE` for a high-level tree display and `CL_GUI_ALV_TREE` when the application needs lower-level control. Use `CL_SALV_HIERSEQ_TABLE` when the model is exactly two sequential levels, such as header and items, rather than an arbitrary-depth tree. --- ## 4. Selection Guide | Requirement | Recommended starting point | Reason | | --------------------------------------- | -------------------------------------------- | ---------------------------------------- | | Quick read-only flat report | `CL_SALV_TABLE` | Minimal setup and standard ALV functions | | Editable cells | `CL_GUI_ALV_GRID` | Supported grid edit/event lifecycle | | Custom toolbar and fine-grained events | `CL_GUI_ALV_GRID` | Direct Control Framework integration | | Arbitrary parent/child hierarchy | `CL_SALV_TREE` | Node-oriented hierarchy model | | Highly customized hierarchy control | `CL_GUI_ALV_TREE` | Lower-level tree behavior | | Exactly header + item sequential levels | `CL_SALV_HIERSEQ_TABLE` | Matches the two-level data shape | | Background/spool-oriented output | List/spool-safe design | GUI controls require a frontend | | Very large HANA-backed result | Consider ALV with IDA, if available/released | Pushes paging/filtering toward HANA | Do not choose `CL_GUI_ALV_GRID` merely because it is more powerful. Its screen, container, frontend-state, event, and lifetime responsibilities are real complexity. --- ## 5. The Output Internal Table Is a View Model Do not send a persistence table to ALV merely because it already has fields. Define the output grain and only expose columns that serve the report. ```abap TYPES: BEGIN OF ty_order_output, sales_order TYPE vbak-vbeln, sold_to_party TYPE vbak-kunnr, overall_status TYPE c LENGTH 1, net_amount TYPE p LENGTH 15 DECIMALS 2, currency TYPE waers, END OF ty_order_output, ty_order_output_tab TYPE STANDARD TABLE OF ty_order_output WITH EMPTY KEY. ``` The model should contain: - the business key needed for navigation or update; - display values at one explicitly chosen grain; - currency/unit reference fields for amounts and quantities; - optional technical style/color fields required by an editable grid; - no sensitive fields merely “hidden” from the initial layout. Hiding a field with `NO_OUT` or a saved layout is presentation, not security. Protect the read before building the output table, and assume export/layout features can reveal any field supplied to the frontend. ### 5.1 Preserve the grain If one order header is joined to ten items and the header amount repeats ten times, ALV totals will correctly total the rows it received—and produce the wrong business answer. Fix the query/output grain rather than blaming ALV. --- ## 6. `CL_SALV_TABLE`: Read-Only Table with Minimal Ceremony `CL_SALV_TABLE` is the normal first choice for a flat display-only report. The factory receives the output internal table, creates the ALV model, and returns the main SALV object. ```abap CLASS lcl_output DEFINITION FINAL. PUBLIC SECTION. CLASS-METHODS display CHANGING orders TYPE ty_order_output_tab. ENDCLASS. CLASS lcl_output IMPLEMENTATION. METHOD display. TRY. cl_salv_table=>factory( IMPORTING r_salv_table = DATA(alv) CHANGING t_table = orders ). alv->get_functions( )->set_all( abap_true ). alv->get_columns( )->set_optimize( abap_true ). alv->get_display_settings( )->set_striped_pattern( abap_true ). alv->display( ). CATCH cx_salv_msg INTO DATA(error). MESSAGE error->get_text( ) TYPE 'E'. ENDTRY. ENDMETHOD. ENDCLASS. ``` Typical caller: ```abap START-OF-SELECTION. DATA(orders) = lcl_order_query=>execute( sales_orders = s_vbeln[] ). lcl_output=>display( CHANGING orders = orders ). ``` ### 6.1 What SALV owns SALV offers subobjects for configuration: ```text CL_SALV_TABLE ├─ GET_FUNCTIONS( ) standard toolbar functions ├─ GET_COLUMNS( ) column collection ├─ GET_SORTS( ) initial sorting ├─ GET_AGGREGATIONS( ) totals/aggregations ├─ GET_SELECTIONS( ) selection behavior/state ├─ GET_DISPLAY_SETTINGS( ) general appearance ├─ GET_LAYOUT( ) layout variants └─ GET_EVENT( ) SALV events ``` ### 6.2 Configure one column ```abap TRY. DATA(columns) = alv->get_columns( ). DATA(column) = columns->get_column( 'NET_AMOUNT' ). column->set_short_text( 'Net' ). column->set_medium_text( 'Net Amount' ). column->set_long_text( 'Sales Order Net Amount' ). CATCH cx_salv_not_found. " Programming/configuration mismatch: field is not in the output model ENDTRY. ``` Names passed to SALV refer to the ABAP component names in the output line type, usually interpreted in uppercase. A DDIC-backed component lets ALV reuse field labels, conversion exits, value help, and type semantics more reliably than an unrelated primitive type. ### 6.3 SALV editing boundary The supported `CL_SALV_TABLE` public model is display-oriented. Do not rely on release-dependent or unsupported tricks that extract an underlying GUI grid to make SALV editable. If editing is a real requirement, choose `CL_GUI_ALV_GRID` and implement the complete edit, validation, authorization, and persistence lifecycle explicitly. --- ## 7. SALV Events: Navigation, Not Business Trust A SALV double-click can navigate to an order detail, but the row number is only presentation state. After users sort and filter, row position is not a stable business identity. Conceptual event-handler shape: ```abap CLASS lcl_salv_handler DEFINITION FINAL. PUBLIC SECTION. METHODS on_double_click FOR EVENT double_click OF cl_salv_events_table IMPORTING row column. ENDCLASS. ``` Registration: ```abap DATA(events) = alv->get_event( ). DATA(handler) = NEW lcl_salv_handler( ). SET HANDLER handler->on_double_click FOR events. ``` Keep the handler object alive for as long as the ALV can raise events. In the handler: 1. resolve the selected row against the current output model; 2. extract its business key; 3. recheck authorization and current state; 4. call an application navigation/action method. Never treat “the user could see or select row 5” as authorization to update the business object represented by row 5. --- ## 8. `CL_GUI_ALV_GRID`: Control-Based Grid Architecture `CL_GUI_ALV_GRID` is a SAP GUI Control Framework control. It requires a parent container and therefore participates in a dynpro's PBO/PAI lifecycle. ```text Executable report │ └─ CALL SCREEN 0100 │ ├─ PBO: create custom container once │ create grid once │ register handlers once │ first display once │ ├─ SAP GUI: user interacts with grid │ └─ PAI: synchronize changes and process command then return to PBO for refresh ``` Screen 0100 normally contains a Custom Control element named, for example, `ALV_CONTAINER`. ### 8.1 Persistent controller attributes The grid, container, event handler, and output table must outlive a single PBO method call. Keep them as suitable program-global references or, preferably, attributes of a screen-controller object. ```abap DATA: container TYPE REF TO cl_gui_custom_container, grid TYPE REF TO cl_gui_alv_grid, output TYPE ty_order_output_tab, field_catalog TYPE lvc_t_fcat, layout TYPE lvc_s_layo. ``` ### 8.2 PBO: create once, refresh later ```abap MODULE status_0100 OUTPUT. SET PF-STATUS 'MAIN'. IF grid IS INITIAL. container = NEW cl_gui_custom_container( container_name = 'ALV_CONTAINER' ). grid = NEW cl_gui_alv_grid( i_parent = container ). " Register event handlers here, before user interaction grid->set_table_for_first_display( EXPORTING is_layout = layout CHANGING it_outtab = output it_fieldcatalog = field_catalog ). ELSE. grid->refresh_table_display( is_stable = VALUE lvc_s_stbl( row = abap_true col = abap_true ) ). ENDIF. ENDMODULE. ``` SAP documents `SET_TABLE_FOR_FIRST_DISPLAY` as the initial binding operation. Call `REFRESH_TABLE_DISPLAY` when only the data changes. Repeat the initial call only when the output structure changes. ### 8.3 PAI: process commands ```abap MODULE user_command_0100 INPUT. CASE sy-ucomm. WHEN 'SAVE'. lcl_screen_controller=>save( ). WHEN 'BACK' OR 'EXIT' OR 'CANC'. LEAVE TO SCREEN 0. ENDCASE. ENDMODULE. ``` The GUI status decides which function codes exist. The ALV grid can also raise toolbar and `USER_COMMAND` events for grid-specific functions. --- ## 9. Field Catalog: Structural and UI Metadata `CL_GUI_ALV_GRID` commonly uses `LVC_T_FCAT`, whose line type is `LVC_S_FCAT`. Important fields include: | Field | Meaning | | -------------------------- | ------------------------------------------------ | | `FIELDNAME` | Component in the output line type | | `COLTEXT`, `SCRTEXT_S/M/L` | Column labels | | `KEY` | Visually identifies a key column | | `NO_OUT` | Initially hides a column; not a security control | | `EDIT` | Makes a cell/column input-enabled in the grid | | `HOTSPOT` | Enables hotspot interaction | | `CHECKBOX` | Displays a checkbox-compatible field | | `DO_SUM` | Requests totals where supported | | `REF_TABLE`, `REF_FIELD` | Reuses DDIC metadata | | `CFIELDNAME` | Currency-reference component for an amount | | `QFIELDNAME` | Unit-reference component for a quantity | You can let the grid derive metadata from a single DDIC structure by passing `I_STRUCTURE_NAME`, or pass an explicit field catalog for a local/mixed output type and custom UI behavior. Example helper: ```abap APPEND VALUE lvc_s_fcat( fieldname = 'NET_AMOUNT' coltext = 'Net Amount' cfieldname = 'CURRENCY' do_sum = abap_true ) TO field_catalog. ``` Metadata names must match the actual output structure. A field catalog does not map database fields into differently named ABAP components; build that mapping when selecting or transforming the output model. --- ## 10. Editable Grid Lifecycle Setting `EDIT = abap_true` only changes the frontend interaction. A complete edit flow has five separate responsibilities. ### 10.1 Enable and register ```abap grid->register_edit_event( i_event_id = cl_gui_alv_grid=>mc_evt_modified ). SET HANDLER handler->on_data_changed FOR grid. ``` Common grid events include `DATA_CHANGED`, `DATA_CHANGED_FINISHED`, `DOUBLE_CLICK`, `HOTSPOT_CLICK`, `TOOLBAR`, and `USER_COMMAND`. ### 10.2 Validate pending changes Before a Save command uses the output table, synchronize pending frontend edits: ```abap DATA valid TYPE abap_bool. grid->check_changed_data( IMPORTING e_valid = valid ). CHECK valid = abap_true. ``` This is especially important when a user types into a cell and immediately presses Save without first leaving the cell or pressing Enter. ### 10.3 Separate UI checks from business checks The `DATA_CHANGED` handler can give immediate feedback about syntax, domains, or cross-cell relationships. The application service must still enforce: - current authorization; - optimistic-lock/version rules; - business invariants; - current database state; - transactional consistency. Client-side or ALV-event validation is not a security boundary. ### 10.4 Persist explicitly Use the system's supported change contract: for example a released API, BAPI, application service, or EML for a RAP BO. Do not perform an arbitrary direct table update simply because the grid output resembles the table. The transaction owner decides the commit/rollback boundary. Reusable methods should not casually issue `COMMIT WORK` when their caller owns the larger unit of work. ### 10.5 Re-read and refresh After successful persistence, re-read authoritative state when calculations, status changes, locks, or other users may have changed the record. Then refresh the grid while preserving row/column stability where appropriate. --- ## 11. Row Index Versus Business Identity ALV selection APIs frequently return display row indexes. Sorting and filtering can change what an index refers to. ```text Unsafe assumption: selected index 3 = database record originally loaded at index 3 Safe flow: current selected index → current output row → immutable business key → fresh authorization/state check → business operation ``` For SD-style data, carry `VBELN`, `POSNR`, and `ETENR` at the appropriate grain even if some technical key columns are not initially prominent. For a RAP BO, carry its actual entity key; an ALV row number is not `%tky`. --- ## 12. List and Background Processing `CL_GUI_ALV_GRID` needs the SAP GUI Control Framework and a frontend container. It is not a background-processing output mechanism. For a report that also runs as a job, design output behind an interface: ```text Application produces typed result table │ ├─ dialog renderer → SALV/grid ├─ job renderer → spool/list or file └─ test renderer → assertions on result table ``` In background: - there is no user-driven grid interaction; - frontend-dependent controls are unavailable; - selection variants supply input; - operational evidence belongs in job log, spool, application log, or a deliberately produced file. Do not assume that a SALV call automatically provides the exact background spool behavior the business needs. Test the chosen display mode in the target release and execution environment. --- ## 13. Tree Data Modeling A tree has two distinct concerns: ```text Hierarchy model Display data ------------------------------ -------------------------- node key node text parent/related node key amount/status/attributes relationship type icons and column values ``` With `CL_SALV_TREE`, the application creates nodes individually, relates each node to a parent or sibling, and assigns the node's data row. Node keys are ALV technical identities; keep business keys separately for navigation. Choose a tree only when users need to reason about containment or dependency. If they mainly compare amounts across many orders, a flat grid grouped and sorted by order is usually easier to scan. ### Tree risks - one cyclic or missing parent breaks hierarchy construction; - eager expansion of a huge tree overwhelms users and memory; - totals across levels can double count parent and child values; - a selected node key is still not authorization; - loading every deep child before it is expanded can be unnecessarily costly. --- ## 14. Currency, Quantity, Totals, and Semantics An amount without its currency and a quantity without its unit are incomplete business values. For a grid field catalog, connect amount/quantity components to the output components holding currency/unit via `CFIELDNAME` and `QFIELDNAME`. Prefer DDIC reference fields where available. Do not total values across different currencies merely because ALV permits a numeric total. Either: - group/subtotal by currency; - convert using an explicit business rule and date/rate type; - suppress a meaningless grand total. The same principle applies to incompatible quantity units. --- ## 15. Layout Variants ALV layouts can store presentation preferences such as column order, width, visibility, sorting, filtering, and totals. Variant identity is commonly described using `DISVARIANT` values such as report and handle, with save scope controlled by the ALV API. Keep three ideas separate: ```text Selection variant → input parameters and select-options ALV layout variant → result presentation Business variant → domain-specific configuration, if any ``` An ALV layout filter does not reduce the database query or replace read authorization. The data may already have reached the frontend before the user hides it. When changing an output structure, test existing saved layouts. Renamed or removed columns can make old variants behave unexpectedly. --- ## 16. Performance Model ALV can sort and filter its supplied dataset, but it cannot undo an over-fetching query. ```text Best order of responsibility: 1. database/API restricts rows and columns 2. application derives the exact report grain 3. ALV provides interactive presentation operations ``` For performance diagnosis: 1. measure the data-access phase separately from rendering; 2. inspect SQL with SQL Monitor/ST05 when appropriate; 3. check row count and output width; 4. look for joins that multiply rows; 5. avoid expensive per-row database queries; 6. consider HANA-oriented ALV with IDA for supported large-data scenarios; 7. test frontend rendering and export separately. `CL_SALV_GUI_TABLE_IDA` can support database-oriented paging/filtering on HANA in systems where the class and data source are suitable. It is not a drop-in reason to ignore data authorization, released-object rules, or the target system's API state. --- ## 17. Authorization and Data Protection Apply authorization before sensitive data enters the ALV output model. ```text Wrong boundary: SELECT everything → send to ALV → hide unauthorized column Correct boundary: authorize scope → select allowed data/fields → build output → display ``` For an action or save, authorize again against the current record and requested operation. Read authorization does not imply update, delete, approve, or export authorization. Also consider: - spreadsheet/local-file export; - print/spool access; - saved layout variants; - personal data displayed in diagnostic columns; - transaction navigation from double-click/hotspot events. --- ## 18. Error and Message Design Handle errors at the layer that understands them: | Error | Owning layer | Example response | | ------------------------------ | ---------------------------------- | ------------------------------------------ | | Invalid selection interval | Selection-screen/application input | Field/cross-field message | | User cannot read company code | Authorization/application service | Reject before output | | SALV column not found | ALV configuration | Developer-facing handling/log | | Invalid edited amount | Grid handler + business service | Cell protocol and no save | | Record changed by another user | Persistence/business API | Conflict message and refresh | | Database/API failure | Data-access layer | Logged technical cause + safe user message | An empty result is not always an error. Distinguish “no matching authorized records” from a broken query or swallowed exception. --- ## 19. Common Failure Patterns | Symptom | Likely cause | Diagnostic move | | ----------------------------------- | -------------------------------------- | --------------------------------------------- | | Empty ALV | Query/filter/auth produced no rows | Inspect result table before display | | Wrong/missing columns | Field catalog and line type disagree | Compare `FIELDNAME` with actual components | | Amount displayed without currency | Missing DDIC/currency reference | Set reference metadata/`CFIELDNAME` | | Total is multiplied | Header repeated by item/schedule join | Reconstruct result grain before ALV | | Edit disappears on Save | Pending frontend edit not synchronized | Call `CHECK_CHANGED_DATA` and inspect handler | | Edit appears saved but DB unchanged | Only output internal table changed | Trace explicit persistence call/transaction | | Grid resets on every action | Grid recreated in every PBO | Create once; refresh subsequently | | Handler stops firing | Handler reference went out of scope | Keep handler alive with the control | | Wrong record opened after sort | Original index treated as identity | Resolve current row and use business key | | Background job fails | GUI control requires frontend | Use a background-safe renderer | | Hidden data appears in export | UI hiding treated as security | Do not send unauthorized fields | | Refresh jumps/loses context | Unstable refresh | Use stable row/column options where suitable | --- ## 20. Classic ALV APIs Versus Modern Direction | Technology | Status/use | Main concern | | ------------------------------ | ---------------------------------------------- | ------------------------------------------ | | `REUSE_ALV_LIST_DISPLAY` | Common legacy list reports | Procedural callback and `SLIS_*` patterns | | `REUSE_ALV_GRID_DISPLAY(_LVC)` | Common legacy grid reports | Function-module callbacks and global state | | `CL_SALV_TABLE` | Preferred concise OO display where it fits | Read-only/public display model | | `CL_GUI_ALV_GRID` | Appropriate for rich classic GUI control needs | More lifecycle and event responsibility | | RAP + Fiori elements | Service/UI architecture, not ALV | CDS/behavior/OData/UI annotation lifecycle | When maintaining a legacy report, improve boundaries without rewriting solely for fashion. Extract authorization, query, transformation, and update logic from callbacks first. Then the renderer can be replaced independently if the business case justifies it. --- ## 21. SD Technical-Consultant Example Suppose a report shows sales-order schedule fulfillment. ### Output grain One row per sales order item schedule line: ```text VBELN + POSNR + ETENR ``` ### Flow ```text Selection: sales org, document/date range, status │ ├─ authorize organizational scope ├─ read released CDS/API or appropriate classic source ├─ construct one row per schedule line ├─ preserve order/item/schedule keys ├─ derive open quantity without mixing units └─ render read-only with CL_SALV_TABLE ``` A double-click can navigate to display the business document after a fresh authorization check. If the requirement becomes “mass-change requested dates,” that is not just `EDIT = X`: choose `CL_GUI_ALV_GRID`, capture changes, validate SD rules, call a supported sales-order change contract, handle conflicts and messages, and refresh authoritative results. In clean-core design, prefer released CDS views/APIs and verify API State in the target release. Directly updating `VBAK`, `VBAP`, or `VBEP` is not a valid business update mechanism. --- ## 22. Tools and Debugging Landmarks | Tool/object | Use | | ------------------------------ | --------------------------------------------------- | | `SE38` / `SA38` | Execute or inspect classic reports, where available | | ADT debugger | Break before display, handlers, and save service | | `SE24` | Inspect class interfaces in classic systems | | `DWDM`, `SE83`, `BCALV*` demos | Explore installed Control Framework examples | | `ST22` | Analyze runtime dumps | | `SAT` | Separate query/transformation/rendering time | | `ST05`, SQL Monitor | Diagnose data access, not ALV formatting | | `SU53` / authorization trace | Diagnose authorization failure appropriately | | `SM37` and `SP01` | Background job and spool evidence | Availability and recommended tools vary by edition and authorization. A demo program illustrates an API; it is not automatically a production architecture. --- ## 23. Implementation Checklist ### Before coding - What is one output row? - Is the result flat, exactly two-level, or an arbitrary hierarchy? - Is it read-only or genuinely transactional? - Must it run in background? - Which fields and rows may the user read/export? - What is the supported data/change API in this system edition? ### For `CL_SALV_TABLE` - Build a typed, authorized result table. - Call `FACTORY`, configure subobjects, then `DISPLAY`. - Keep event handlers alive. - Resolve navigation through business keys, not row indexes. - Do not use unsupported SALV-edit hacks. ### For `CL_GUI_ALV_GRID` - Create a custom screen and parent container. - Keep container, grid, handler, and output alive. - Call `SET_TABLE_FOR_FIRST_DISPLAY` once. - Register required events. - Synchronize pending edits before Save. - Validate and authorize in the business layer. - Persist through the supported contract. - Re-read and call `REFRESH_TABLE_DISPLAY`. - Provide a separate output path for background processing. --- 35:T850,1. What ALV Is — and Is Not ALV, the SAP List Viewer, is a presentation framework for structured datasets. It can supply standard user functions such as sorting, filtering, totals, subtotals, layouts, printing, and export. text Database / CDS / released API │ ▼ Application reads, authorizes, and derives data │ ▼ Internal table = report output model │ ▼ ALV renders List, Grid, or Tree │ ▼ User sorts, filters, selects, navigates, or edits ALV does not by itself: - read the correct business data; - authorize a user to see or change that data; - enforce business invariants; - persist edited cells; - fix duplicate rows caused by an incorrect SQL join; - turn a classic report into a Fiori or RAP application. Think of ALV as the report's view and interaction adapter. The internal table is its input model; application methods own the business behavior. --- 2. End-to-End Runtime Flow For a read-only executable report using SALV: text Program/report starts │ ▼ Selection-screen lifecycle │ defaults → dynamic PBO → user input → validation ▼ START-OF-SELECTION │ ├─ authorize requested scope ├─ read through an appropriate CDS view/API/Open SQL ├─ calculate and map the output model └─ return an internal table │ ▼ CLSALVTABLE=FACTORY │ ├─ configure functions, columns, sorts, layout, events └─ DISPLAY │ ▼ User sorts/filters/totals/exports or triggers navigation For an editable GUI grid, the display is only half the workflow: text Application internal table │ ▼ CLGUIALVGRID display │ ▼ User edits a frontend cell │ ├─ REGISTEREDITEVENT / DATACHANGED └─ CHECKCHANGEDDATA transfers/checks pending frontend changes │ ▼ Application validates values and authorization │ ├─ invalid → protocol/message; do not save └─ valid → released update API / BAPI / application service / EML │ ▼ transaction owner commits │ ▼ refresh application data and ALV The decisive point is: an editable cell is not a database update. CHECKCHANGEDDATA is part of synchronizing/validating the grid state; it is not persistence. --- 3. The36:T92f,## 1. What ALV Is — and Is Not ALV, the SAP List Viewer, is a presentation framework for structured datasets. It can supply standard user functions such as sorting, filtering, totals, subtotals, layouts, printing, and export. ```text Database / CDS / released API │ ▼ Application reads, authorizes, and derives data │ ▼ Internal table = report output model │ ▼ ALV renders List, Grid, or Tree │ ▼ User sorts, filters, selects, navigates, or edits ``` ALV does **not** by itself: - read the correct business data; - authorize a user to see or change that data; - enforce business invariants; - persist edited cells; - fix duplicate rows caused by an incorrect SQL join; - turn a classic report into a Fiori or RAP application. Think of ALV as the report's **view and interaction adapter**. The internal table is its input model; application methods own the business behavior. --- ## 2. End-to-End Runtime Flow For a read-only executable report using SALV: ```text Program/report starts │ ▼ Selection-screen lifecycle │ defaults → dynamic PBO → user input → validation ▼ START-OF-SELECTION │ ├─ authorize requested scope ├─ read through an appropriate CDS view/API/Open SQL ├─ calculate and map the output model └─ return an internal table │ ▼ CL_SALV_TABLE=>FACTORY │ ├─ configure functions, columns, sorts, layout, events └─ DISPLAY │ ▼ User sorts/filters/totals/exports or triggers navigation ``` For an editable GUI grid, the display is only half the workflow: ```text Application internal table │ ▼ CL_GUI_ALV_GRID display │ ▼ User edits a frontend cell │ ├─ REGISTER_EDIT_EVENT / DATA_CHANGED └─ CHECK_CHANGED_DATA transfers/checks pending frontend changes │ ▼ Application validates values and authorization │ ├─ invalid → protocol/message; do not save └─ valid → released update API / BAPI / application service / EML │ ▼ transaction owner commits │ ▼ refresh application data and ALV ```37:Tc28b, # SAP SD Order-to-Cash — Technical Architecture This document describes the technical structure and runtime boundaries of the SAP Sales and Distribution Order-to-Cash process. Its purpose is to connect the business-document chain to document grain, persistence landmarks, posting effects, document flow, diagnostic evidence, and clean-core integration contracts. The central architectural principle is: > Order-to-Cash is a graph of independently meaningful business documents and > postings. It is not one large database record, one status field, or one > transactional aggregate. This reference distinguishes three contexts: - **Classic SAP ERP and SAP S/4HANA on-premise/private edition**, where SAP GUI transactions and direct table inspection may be available for authorized diagnosis. - **SAP S/4HANA Cloud Public Edition**, where Fiori applications, configuration activities, and released APIs are the normal operational contracts. - **Clean-core extension development**, where released CDS entities, business objects, events, and APIs should be preferred over dependencies on internal persistence. Primary SAP sources: - [SAP Help — Sales Documents](https://help.sap.com/docs/SAP_S4HANA_CLOUD/a376cd9ea00d476b96f18dea1247e6a5/aa64b65334e6b54ce10000000a174cb4.html) - [SAP Learning — Navigating the Order-to-Cash Process Steps](https://learning.sap.com/courses/discovering-the-basics-of-sap-s-4hana-sales/executing-sales-order-management_cad9dfbe-bafc-4ed9-ac2e-6fd8422430e4) - [SAP Help — Sales Order Item Schedule Line](https://help.sap.com/docs/SAP_S4HANA_CLOUD/03c04db2a7434731b7fe21dca77440da/37df44581efca007e10000000a441470.html) - [SAP Help — Goods Issue](https://help.sap.com/docs/SAP_S4HANA_CLOUD/aff0b3f5f46c42a2b2c0fabfc233bab2/64f81a71edf5490ab522a829be075827.html?locale=en-US&version=LATEST) - [SAP Help — Billing Data Flow](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/ed84b70c199d4470ae2e5ccb93b2e45b/e26fb6535fe6b74ce10000000a174cb4.html) - [SAP Help — Displaying Goods Issue Documents](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/c7894a248ca14f74aca67f97528e5ad7/f91bbf53d25ab64ce10000000a174cb4.html) - [SAP Help — Delivery Document CDS View](https://help.sap.com/docs/SAP_S4HANA_CLOUD/c0c54048d35849128be8e872df5bea6d/e2966bcba73a455299b4937151dfd0a3.html) --- ## 1. Scope and System Boundaries ### 1.1 Core process The common sell-from-stock flow can be represented as: ```text Optional presales Core execution Inquiry → Quotation → Sales Order → Outbound Delivery → PGI → Billing → Payment ``` The technical meaning is clearer when the process is expressed as state transitions: ```text Customer interest ↓ Commercial offer ↓ Accepted demand and fulfillment intent ↓ Warehouse execution document ↓ Inventory and value posting ↓ Customer invoice and receivable ↓ Cash receipt and clearing ``` Inquiry and quotation are optional presales documents. Returns, credit memos, third-party sales, intercompany sales, milestone billing, consignment, and make-to-order processes follow different branches. The architecture in this document is therefore a baseline, not a claim that every SD transaction follows one identical path. SAP describes sales, delivery, and billing documents as individual documents that participate in a larger process flow and can be created with reference to predecessors. That reference copies relevant information and records process lineage; it does not merge all documents into one object. See [SAP Help — Sales Documents](https://help.sap.com/docs/SAP_S4HANA_CLOUD/a376cd9ea00d476b96f18dea1247e6a5/aa64b65334e6b54ce10000000a174cb4.html). ### 1.2 Responsibility boundaries | Boundary | Primary responsibility | New fact established | | ----------------- | ------------------------------------------------------ | -------------------------------------------------------- | | Presales | Sales | Interest or an offer is recorded | | Sales Order | Sales/order management | Accepted demand and commercial context are recorded | | Outbound Delivery | Shipping/warehouse execution | Deliverable quantities are organized for execution | | Post Goods Issue | Shipping, Inventory Management, accounting integration | Goods have left; stock and value effects are posted | | Billing | Billing and accounting integration | Customer invoice and accounting consequences are created | | Incoming payment | Financial Accounting | Cash is posted and an open receivable can be cleared | These are separate boundaries because they have different owners, validations, posting effects, reversal procedures, authorizations, and audit histories. ### 1.3 Architectural layers ```text User interaction SAP GUI transaction / Fiori app / external consumer │ ▼ Business operation create order / create delivery / post GI / create billing / post payment │ ▼ Application logic determination / copy control / validation / status / authorization │ ▼ Persistence and postings SD documents / material document / journal entry / clearing information │ ▼ Integration and analytics released API / CDS / event / IDoc / process flow / reporting ``` The persistence tables are implementation landmarks. The business operation is the contract. Creating a row that resembles an order or delivery is not equivalent to executing the corresponding SAP business operation. --- ## 2. End-to-End Document Lifecycle ### 2.1 Lifecycle matrix | Stage | Technical object | What becomes true | What remains unproven | | ----------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------- | | Inquiry | Sales document | Customer interest or request for information is recorded | No formal offer or accepted order | | Quotation | Sales document | A commercial offer with validity and terms exists | Customer acceptance is not guaranteed | | Sales Order | Sales document | Product, quantity, partner, price, date, and fulfillment intent are recorded | Delivery, PGI, invoice, and payment | | Outbound Delivery | Delivery document | Shipping execution has a document for quantities, dates, picking, packing, and goods movement | Goods issue may not be posted | | PGI | Material and accounting posting connected to delivery | Goods departure, stock reduction, and relevant value effects are recorded | Customer billing and cash receipt | | Billing | Billing document plus accounting integration | Invoice values are recorded and normally transferred to accounting | Incoming cash | | Incoming Payment | FI journal entry and clearing process | Cash receipt is recorded and can clear the open customer item | Completion of every other branch or open item | ### 2.2 Inquiry and quotation Inquiry and quotation normally use the sales-document architecture. They may contain header and item data and can participate in reference chains. They do not represent inventory movement or customer receivable postings. The quotation is best understood as a versioned commercial offer. Its validity, prices, quantities, and conditions can be copied into a subsequent order under configured rules. The subsequent Sales Order is still its own business document, with its own current values and lifecycle. ### 2.3 Sales Order A Sales Order is a transactional snapshot assembled from user input, partner and material master data, reference documents, pricing condition data, Customizing, and runtime determinations. Its main technical responsibilities include: - establish the commercial parties and Sales Area; - identify products or services and total demand; - determine item and schedule-line processing behavior; - determine price and commercial terms; - schedule and confirm quantities and dates; - provide a source for delivery- or order-related subsequent processing; - maintain processing status and document flow. Saving the Sales Order does not post physical goods movement. It records demand and instructions that subsequent processes can consume. ### 2.4 Outbound Delivery The Outbound Delivery is an execution document, not merely a visual plan. It organizes delivery-relevant quantities for shipping and supports processes such as picking, packing, batch/serial handling, route or shipping data, and PGI. Delivery creation can copy data from one or more due predecessor items under copy-control, combination, and split rules. The resulting delivery has its own header/item identity and status. Changing the order afterward does not imply that every copied delivery value dynamically changes. ### 2.5 Post Goods Issue PGI is the decisive physical posting boundary for the ordinary outbound sell-from-stock flow. SAP states that goods issue confirms that the goods have left the company and reduces warehouse stock. If posted data must be corrected, the normal flow is to reverse the goods issue, change the delivery, and post again. See [SAP Help — Goods Issue](https://help.sap.com/docs/SAP_S4HANA_CLOUD/aff0b3f5f46c42a2b2c0fabfc233bab2/64f81a71edf5490ab522a829be075827.html?locale=en-US&version=LATEST). PGI can create or update evidence across component boundaries: ```text Outbound Delivery │ ├─ goods-movement status and actual GI information ├─ material document / inventory quantity effect ├─ value and accounting consequences, when applicable └─ document-flow relationship ``` The goods issue document is not merely another Sales Order child. SAP identifies it as belonging to Materials Management and Financial Accounting while still being navigable from the delivery flow. See [Displaying Goods Issue Documents](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/c7894a248ca14f74aca67f97528e5ad7/f91bbf53d25ab64ce10000000a174cb4.html). ### 2.6 Billing A Billing Document is created from a billable predecessor such as a delivery or Sales Order, depending on item billing relevance and process design. Data is copied under billing copy-control rules. For delivery-related billing, SAP gives the representative behavior that quantities can be copied from the delivery while prices can be copied from the Sales Order. Pricing may also be redetermined according to the configured pricing type. See [SAP Help — Billing Data Flow](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/ed84b70c199d4470ae2e5ccb93b2e45b/e26fb6535fe6b74ce10000000a174cb4.html). The Billing Document is a distinct SD business document. Its accounting transfer normally creates the financial evidence for receivable, revenue, tax, and related postings according to configuration. ### 2.7 Incoming payment Incoming payment belongs primarily to Financial Accounting. It records the cash receipt and applies clearing logic to one or more open customer items. ```text Billing document ↓ Customer receivable/open item ↓ Incoming payment posting ↓ Full, partial, residual, or other configured clearing result ``` Payment must not be modeled as “a field sent back to the Sales Order.” It is a financial posting with its own document identity, posting date, currency, accounts, clearing state, and possible exceptions. One payment can relate to multiple invoices, and one invoice can be settled through several payments or adjustments. --- ## 3. Business Events Versus Document Creation ### 3.1 A document records intent or execution at a specific boundary The existence of a document proves only the fact owned by that document. ```text Sales Order exists proves: demand and commercial/fulfillment intent were recorded does not prove: stock moved Outbound Delivery exists proves: shipping execution document was created does not prove: PGI was posted Billing Document exists proves: billing document was created does not prove: customer paid Payment document exists proves: payment posting exists does not automatically prove: every invoice/order branch is complete ``` This prevents a common diagnostic error: interpreting a planning or execution document as proof that a later posting occurred. ### 3.2 Posting boundaries Posting establishes a committed accounting or inventory fact. It typically has stronger reversal and audit requirements than changing an unposted operational document. | Operation | Nature | Typical correction model | | ---------------------------------- | ------------------------------ | -------------------------------------------------- | | Change open Sales Order | Transaction-document change | Edit through supported Sales Order operation | | Change unposted delivery | Execution-document change | Edit through delivery operation, subject to status | | Reverse PGI | Reversal posting | Create reversal effect, correct delivery, repost | | Cancel billing | Cancellation/reversal document | Preserve traceable reversal relationship | | Reset clearing/reverse FI document | Financial correction | Execute authorized FI reversal/reset process | Direct deletion or overwriting of posted persistence would destroy lineage and violate component-level invariants. ### 3.3 Save is not universal business completion Every document has a local save boundary, but Order-to-Cash completion is a cross-document interpretation. ```text Sales Order saved ≠ delivery complete Delivery saved ≠ goods issued PGI posted ≠ billed Billing posted ≠ paid Payment received ≠ every order item complete ``` A process can contain partial deliveries, partial billing, rejected items, returns, credit/debit documents, disputes, and residual open items. Completion must therefore be evaluated at the correct document/item/quantity grain. --- ## 4. Sales Document Header, Item, and Schedule-Line Grain ### 4.1 Structural hierarchy ```text Sales Document Header one commercial document ├── Item 0010 one product/service line │ ├── Schedule Line 0001 one dated quantity requirement/result │ └── Schedule Line 0002 another dated quantity requirement/result └── Item 0020 └── Schedule Line 0001 ``` The placement rule is: > Store or expose a value at the broadest grain where it remains true without > changing its business meaning. ### 4.2 Level responsibilities | Level | Technical grain | Responsibility | Representative values | | ------------- | ----------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | Header | One sales document | Shared commercial context | Document type, Sales Area, Sold-to Party, order date, document currency, overall state | | Item | One line inside the document | Product/service demand and line processing | Material, total ordered quantity, sales unit, Plant, item category, price/net value, rejection reason | | Schedule line | One dated quantity segment inside an item | Requirement, confirmation, and logistics participation by date | Requested date/quantity, confirmed date/quantity, schedule-line category, delivery relevance, movement instructions | SAP defines a Sales Order schedule line as the subdivision of an item according to date and quantity. Multiple partial deliveries can therefore be represented by multiple schedule lines. See [SAP Help — Item Schedule Line](https://help.sap.com/docs/SAP_S4HANA_CLOUD/03c04db2a7434731b7fe21dca77440da/37df44581efca007e10000000a441470.html). ### 4.3 Classic key structure Ignoring the client column for readability: ```text VBAK key: VBELN VBAP key: VBELN + POSNR VBEP key: VBELN + POSNR + ETENR ``` The keys are nested identities: - `VBELN` identifies the sales document. - `POSNR` identifies an item within that document. - `ETENR` identifies a schedule-line record within that item. `ETENR` is not a quantity or date. It identifies the row that contains dated quantity information. ### 4.4 Correct join path ```text VBAK-VBELN = VBAP-VBELN VBAP-VBELN + VBAP-POSNR = VBEP-VBELN + VBEP-POSNR ``` Joining `VBEP` using only `VBELN` mixes schedule lines from every item in the document. A syntactically valid SQL join can therefore be semantically wrong. ### 4.5 Header-to-item propagation Selected header values can be proposed or copied into item fields. This is not object-oriented inheritance and is not necessarily a live reference. ```text Header payment terms: 30 days ↓ copied/proposed Item 0010: 30 days Item 0020: 45 days explicit permitted exception ``` If the header later changes, the behavior is field- and process-specific. An item exception may remain unchanged. Diagnose the stored item value and the relevant copy/redetermination behavior rather than assuming that the UI displays one shared header variable. ### 4.6 Child-to-parent aggregation Information also moves upward: ```text Schedule-line results → item processing summary Item values → header totals Item statuses → overall document status ``` An overall status is compressed information. It is useful for selection and navigation but does not explain which child caused a partial state. Diagnosis must move from header summary to item and schedule-line evidence. --- ## 5. Quantity and Status Propagation ### 5.1 Quantity vocabulary | Quantity | Meaning | Grain warning | | ------------------ | ----------------------------------------------------------------------------- | --------------------------------------- | | Ordered quantity | Total customer demand for one Sales Order item | Item total | | Requested quantity | Demand requested for a particular date | Commonly schedule-line/date context | | Confirmed quantity | Quantity SAP currently commits for a date after scheduling/availability logic | Promise, not execution | | Delivery quantity | Quantity included in a delivery item | Delivery-document grain | | Picked quantity | Quantity physically staged/picked according to warehouse process | Does not alone prove PGI | | GI quantity | Quantity posted as goods issue | Material-document/posting evidence | | Billed quantity | Quantity represented in billing according to billing basis | Billing-item grain | | Open quantity | Remaining quantity eligible for a defined next step | Must name which “open” measure is meant | “Open quantity” is not one universal stored fact. It can mean, for example, open order demand, open confirmed quantity for delivery, unpicked delivery quantity, or unbilled quantity. Every technical report must define the formula, source grain, status exclusions, unit, and process boundary. ### 5.2 Partial-flow example Customer demand: ```text Sales Order 50000123 / Item 0010 Ordered quantity: 10 EA Schedule Line 0001 Confirmed: 6 EA on 10 Sep Schedule Line 0002 Confirmed: 4 EA on 17 Sep ``` After the first branch is delivered, PGI-posted, and billed: ```text Ordered: 10 EA Confirmed: 10 EA across two dates Delivered: 6 EA PGI-posted: 6 EA Billed: 6 EA Open for later: 4 EA, assuming no rejection or cancellation ``` The exact number of schedule lines and status representation depends on runtime results and configuration. The invariant is the separation of demand, commitment, execution, posting, and billing. ### 5.3 Status is evidence, but not always sufficient proof Examples of useful delivery status families include: | Status family | Header landmark | Item landmark | Meaning | | -------------- | --------------- | ------------- | ---------------------------------- | | Picking | `LIKP-KOSTK` | `LIPS-KOSTA` | Progress of required picking | | Goods movement | `LIKP-WBSTK` | `LIPS-WBSTA` | Progress of goods-movement posting | Status fields support diagnosis, but decisive posting evidence is stronger: ```text PGI proof hierarchy 1. Material/goods-issue document and delivery relationship 2. Actual GI date and completed goods-movement state 3. Inventory/value/accounting effects where applicable 4. User message or visible delivery existence alone — insufficient ``` SAP S/4HANA simplified SD status persistence by moving status fields from the separate `VBUK` and `VBUP` tables into corresponding document header/item tables. Compatibility behavior and older-system documentation can still expose legacy names, so code must be checked against the exact target release. The safe extension contract is a released CDS/API rather than assumptions about a legacy status table. See SAP's [S/4HANA Simplification List](https://help.sap.com/doc/pdfa4322f56824ae221e10000000a4450e5/1511%20001/en-US/SIMPL_OP1511_FPS01.pdf). ### 5.4 Status aggregation is not arithmetic only An overall state such as “partially processed” is not necessarily calculated by simply summing quantities. Rejections, relevance indicators, blocks, document categories, and completion rules influence whether a child participates in the summary. For diagnostics: ```text Overall header status ↓ Relevant item statuses ↓ Schedule-line/delivery/billing quantities and states ↓ Document-flow and posting evidence ``` --- ## 6. SD Document Flow and Predecessor–Successor Relationships ### 6.1 Document flow is a graph The simple diagram appears linear: ```text Order → Delivery → Billing ``` The real process is a graph: ```text Quotation ↓ Sales Order Item 0010 ├─ Delivery A Item 0010 → PGI A → Invoice A └─ Delivery B Item 0010 → PGI B → Invoice B Sales Order Item 0020 └─ rejected; no delivery ``` Several orders can also be combined into a delivery when combination criteria permit it, while a single order can split into multiple deliveries or invoices. The correct cardinality is therefore frequently one-to-many or many-to-many across stages. ### 6.2 `VBFA` as a classic lineage landmark `VBFA` represents SD predecessor/successor document relationships. Important classic fields include: | Field | Meaning | | ---------------------------------------------- | ------------------------------- | | `VBELV` | Preceding SD document | | `POSNV` | Preceding SD document item | | `VBTYP_V` or release-equivalent category field | Preceding document category | | `VBELN` | Subsequent SD document | | `POSNN` | Subsequent SD document item | | `VBTYP_N` or release-equivalent category field | Subsequent document category | | `STUFE` | Document-flow level information | SAP S/4HANA simplified `VBFA` and extended the SD document-category model. Avoid encoding old one-character category assumptions into new integrations. ### 6.3 Reference field versus document-flow graph A delivery item can contain direct predecessor references such as `LIPS-VGBEL/VGPOS`. These tell how that item was created. `VBFA`, by contrast, represents broader predecessor/successor lineage across document categories. ```text Direct source reference useful for: immediate originating document/item Document-flow relationship useful for: traversing the wider process graph ``` Neither should be treated as a reason to update the predecessor or successor table directly. ### 6.4 Process flow versus full document flow Modern Fiori process-flow visualizations can deliberately show the documents most relevant to a particular business role. The full document flow can contain additional related documents. SAP notes that a process flow viewed from a Sales Order can differ from one viewed from a Billing Document even though both refer to the same broader process. See [SAP Help — Manage Billing Documents Process Flow](https://help.sap.com/docs/SAP_S4HANA_CLOUD/a376cd9ea00d476b96f18dea1247e6a5/e097b4d95c9946d49f48bba5ddfd61b3.html). Therefore: ```text UI process flow = role-oriented visualization Document flow = business-document lineage VBFA = classic persistence landmark for SD relationships ``` ### 6.5 Document flow is not RAP composition RAP composition expresses lifecycle ownership inside one business-object aggregate: ```text SalesOrderRequest └── Items └── Schedules ``` SD document flow links separate aggregates and postings: ```text Sales Order ──reference/flow──> Delivery ──flow──> Billing ``` A Billing Document should not be modeled as a composition child deleted with a Sales Order. It has independent identity, authorization, accounting effects, status, reversal behavior, and retention requirements. --- ## 7. Core Persistence Landmarks ### 7.1 Persistence map The following tables are classic technical landmarks for authorized diagnosis. They are not stable public update interfaces. | Process object | Header landmark | Item/detail landmark | Representative grain | | ---------------------------- | --------------- | -------------------------------------------- | ------------------------------------------------------------ | | Sales document | `VBAK` | `VBAP` | `VBELN`; `VBELN + POSNR` | | Sales schedule line | — | `VBEP` | `VBELN + POSNR + ETENR` | | Delivery | `LIKP` | `LIPS` | `VBELN`; `VBELN + POSNR` | | Billing document | `VBRK` | `VBRP` | `VBELN`; `VBELN + POSNR` | | SD document flow | — | `VBFA` | Predecessor/successor document-item relationship | | Material document in S/4HANA | — | `MATDOC` | Material-document item context | | Accounting document | `BKPF` | `BSEG`; universal-journal detail in `ACDOCA` | Company code, fiscal year, accounting document, line context | The repeated field name `VBELN` does not mean all tables contain the same business object. Its meaning is scoped by the table/document category. ### 7.2 Sales Order persistence ```text VBAK: one sales-document header ├─ document type and category ├─ Sales Area ├─ Sold-to/commercial context ├─ document currency/dates └─ header-level state VBAP: one sales-document item ├─ material/product ├─ item category ├─ ordered quantity and unit ├─ Plant/shipping data └─ item-level value and state VBEP: one schedule line ├─ schedule-line number/category ├─ requested/confirmed date and quantity context └─ fulfillment-control data ``` Additional partner, business-data, text, pricing, and status information can reside in other structures. The three-table model is the structural spine, not the complete Sales Order data model. ### 7.3 Delivery persistence ```text LIKP: delivery header ├─ delivery type ├─ shipping point ├─ dates ├─ partners └─ overall execution/status information LIPS: delivery item ├─ material and delivery quantity ├─ Plant/storage location/batch context ├─ predecessor reference ├─ picking and goods-movement information └─ movement-type and status context ``` A delivery row proves that delivery creation occurred. To prove PGI, correlate delivery status and actual GI information with the material/goods-issue document and relevant posting effects. ### 7.4 Billing persistence ```text VBRK: billing header ├─ billing type/category ├─ payer and dates ├─ currency/accounting references └─ header status VBRP: billing item ├─ billed product/quantity ├─ reference document/item ├─ item values └─ billing relevance/result context ``` Pricing-result details in SAP S/4HANA are associated with `PRCD_ELEMENTS`; older code commonly references `KONV`. Pricing persistence is covered in the separate Sales Document Control and Pricing reference. ### 7.5 Material and accounting evidence In SAP S/4HANA, `MATDOC` is the central material-document line-item persistence landmark. Financial postings use the accounting-document model, with `ACDOCA` as the Universal Journal line-item store and classic document header/context such as `BKPF` still relevant. Do not join these areas only by visually similar identifiers. Use documented reference keys, document flow, released CDS associations, or application APIs. ### 7.6 S/4HANA data-model changes Relevant simplifications include: - status fields moved from separate `VBUK`/`VBUP` persistence into relevant SD document header/item tables; - `VBFA` document-flow simplification; - extended SD document-category semantics; - material-document consolidation centered on `MATDOC`; - financial line-item consolidation in the Universal Journal. Legacy names can still surface through compatibility views, extractors, or old documentation. A technical design must declare its system release and avoid treating compatibility behavior as a future-stable integration contract. --- ## 8. Grain-Safe Query and Reporting Design ### 8.1 The parent-measure multiplication trap Suppose one Sales Order header stores a total of `1,000`, with two items and two schedule lines per item: ```text 1 VBAK row → 2 VBAP rows → 4 VBEP rows ``` After a flat join, the header value appears four times: | Order | Item | Schedule line | Repeated header total | | ------ | ---- | ------------- | --------------------: | | 500001 | 0010 | 0001 | 1,000 | | 500001 | 0010 | 0002 | 1,000 | | 500001 | 0020 | 0001 | 1,000 | | 500001 | 0020 | 0002 | 1,000 | `SUM(HeaderTotal)` returns `4,000`, although the database join itself is technically valid. The governing rule is: > Aggregate a measure at the grain where the measure is defined. ### 8.2 Safe strategies - Read one header measure per `VBELN`. - Aggregate schedule-line quantities to item grain before joining them to item measures. - Aggregate item values to header grain before combining them with header measures. - Include currency and unit semantics in grouping/conversion logic. - Define whether rejected, cancelled, blocked, reversed, or statistically irrelevant rows participate. - Use released analytical CDS content when it already defines the required semantics. `SUM(DISTINCT HeaderTotal)` is not a general correction. Two different orders can legitimately have the same total, causing valid values to be removed. ### 8.3 Choose one explicit report grain Examples: ```text One row per Sales Order key: Sales Order One row per Sales Order Item key: Sales Order + Item One row per Schedule Line key: Sales Order + Item + Schedule Line One row per Order-to-Cash relationship key: predecessor + predecessor item + successor + successor item + category ``` A report that mixes these grains without an explicit bridge/aggregation design will eventually produce duplicate counts, misleading totals, or ambiguous statuses. ### 8.4 Currency and unit correctness An amount without its currency and a quantity without its unit is incomplete. Do not add `10 EA` to `10 KG`, or total document values across currencies without a documented conversion date, exchange-rate type, and target currency. ```text Measure + unit/currency + grain + relevance rule + time semantics = interpretable result ``` --- ## 9. Classic Transaction Map These transactions are on-premise/private-edition landmarks and depend on role, release, and system configuration. Public Cloud uses available Fiori apps and configuration activities instead of assuming these SAP GUI entry points. | Purpose | Classic transaction | Technical boundary | | --------------------------------------- | ------------------------------------------------ | --------------------------------------------- | | Create/change/display Sales Order | `VA01` / `VA02` / `VA03` | Sales document | | List Sales Orders | `VA05` | Sales-document selection/reporting | | Create/change/display Outbound Delivery | `VL01N` / `VL02N` / `VL03N` | Delivery execution | | Delivery monitor/due processing | `VL06O` and related delivery due-list processing | Delivery eligibility and collective execution | | Reverse goods movement for delivery | `VL09` | PGI reversal boundary | | Create/change/display Billing Document | `VF01` / `VF02` / `VF03` | Billing | | Display accounting document | `FB03` | FI document evidence | | Display customer line items | `FBL5N` | Receivable/open and cleared item analysis | | Post incoming payment | `F-28` | Classic FI incoming-payment processing | Transaction availability does not define the API contract. A custom application should not simulate `VA01` by updating `VBAK`, or simulate `VL02N` PGI by updating delivery status. ### 9.1 Diagnostic navigation pattern ```text Sales Order display ↓ document flow Delivery display ↓ document flow / goods-issue evidence Material and accounting documents ↓ Billing document and accounting document ↓ Customer open/cleared item evidence ``` The UI is the starting point for business context. Persistence inspection then confirms grain and state. Posting documents provide the strongest evidence. --- ## 10. Released CDS and API Boundaries ### 10.1 Contract hierarchy ```text Best extension/integration boundary released business object / API / event ↓ released CDS entity for supported read scenario ↓ internal table inspection for authorized diagnosis ↓ Worst write boundary direct update of SAP application tables ``` “Released” is system- and release-specific. Verify API State in the target system and the current SAP Business Accelerator Hub/API documentation before choosing an object. ### 10.2 Sales Order API hierarchy The Sales Order A2X OData V2 family commonly exposes a hierarchy such as: ```text A_SalesOrder └── A_SalesOrderItem └── A_SalesOrderScheduleLine ``` SAP documents `A_SalesOrderScheduleLine` as the item schedule-line entity and supports navigation from an order item to its schedule lines in the applicable API. The `A_` prefix is a delivered entity naming convention, not an ABAP language requirement. Service versions can use different names; always inspect the service metadata. ### 10.3 Delivery read model SAP documents `I_DeliveryDocument` as a released basic interface CDS view for delivery objects, including attributes such as delivery number, shipping point, dates, partners, and overall statuses. Authorization remains part of the consumption context. See [SAP Help — Delivery Document CDS View](https://help.sap.com/docs/SAP_S4HANA_CLOUD/c0c54048d35849128be8e872df5bea6d/e2966bcba73a455299b4937151dfd0a3.html). A released read view does not automatically authorize a write. Delivery creation, picking confirmation, PGI, reversal, and other operations need the specific supported business API for that operation and release. ### 10.4 BAPI, IDoc, OData, and event boundaries | Contract | Interaction style | Typical fit | Architectural caution | | -------------- | ---------------------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------- | | BAPI | Usually synchronous business operation | Classic/on-premise integration and application calls | Check release status, return messages, transaction ownership, and modern alternatives | | IDoc | Asynchronous persisted message | Decoupled reliable business-message exchange | Monitor status, retries, duplicates, partner profile, and business idempotency | | OData/API | Synchronous service contract | Cloud-ready business access and Fiori/API consumers | Respect version, ETags, business errors, scope, and API limits | | Business event | Asynchronous notification | Inform consumers that a business fact occurred | Event is not necessarily a full state-transfer payload | | CDS entity | Read/analytical semantic model, depending on release | Queries, analytics, and supported read scenarios | Released read access is not write authorization | For example, a Sales Order BAPI asks SAP application logic to create/change a business object. An order IDoc represents a persisted integration message that is processed asynchronously. Neither should be confused with directly inserting rows into Sales Order tables. ### 10.5 Direct table updates are invalid business operations Do not directly update: ```text VBAK / VBAP / VBEP LIKP / LIPS VBRK / VBRP VBFA MATDOC ACDOCA ``` These tables participate in application invariants, status propagation, document flow, pricing, inventory valuation, accounting, change tracking, authorization, output, and integration. Updating one table cannot reproduce the complete operation and can corrupt cross-component consistency. --- ## 11. Technical Diagnostic Flow ### 11.1 Universal sequence ```text Business symptom ↓ Identify exact document and item grain ↓ Capture actual stored/runtime result ↓ Traverse predecessor and successor documents ↓ Verify decisive posting evidence ↓ Reconstruct master data and configuration inputs ↓ Inspect logs/messages/authorizations/integration ↓ Investigate enhancements or custom code last ``` This sequence prevents configuration or code changes from being used to explain a symptom that actually came from transaction input, data grain, missing master data, an unexecuted posting, or a different document branch. ### 11.2 Missing or unexpected downstream document When a delivery or billing document is missing: 1. Capture the exact predecessor `VBELN + POSNR` and expected quantity. 2. Inspect rejection, completion, block, and relevance state. 3. Inspect every schedule line, including confirmed quantity/date and delivery relevance. 4. Check whether the item is due in the selected horizon and organizational scope. 5. Check document flow for an already-created or differently split successor. 6. Verify copy-control requirements and successor type. 7. Inspect application logs and authorization failures. 8. Only then inspect exits, BAdIs, custom logic, or inbound payloads. ### 11.3 “Delivery exists, but stock did not change” ```text Delivery identity ↓ Goods-movement status and actual GI date ↓ Material/goods-issue document in document flow ↓ MATDOC/released material-document view ↓ Stock quantity/value and accounting evidence ``` If the material document does not exist, delivery creation alone is not proof of PGI. If it exists, check reversal documents and posting dates before concluding that current stock should still show the original effect. ### 11.4 “Billing exists, but payment is still open” ```text Billing document ↓ Accounting transfer/reference ↓ Customer receivable/open item ↓ Incoming payment document ↓ Clearing document/date or residual/partial state ``` The defect may be no payment, unmatched payment, partial payment, residual item, currency/difference handling, clearing reset, or a different payer/account—not a missing Sales Order update. ### 11.5 Technical evidence record A strong technical incident note records: ```text System/release and client Business process variant Document + item + schedule-line keys Expected versus actual state Predecessor/successor identities Relevant quantities with units Amounts with currencies Status evidence Posting document evidence Configuration/master-data inputs Application log/message identifiers Enhancement/custom-code evidence, if reached ``` --- ## 12. RAP Architecture Transfer ### 12.1 Honest aggregate boundary A portfolio Sales Order Request can use composition for lifecycle-dependent children: ```text SalesOrderRequest aggregate root ├── composition [0..*] → Items product/service demand │ ├── composition [0..*] → Schedules simplified dated promises │ ├── association → Product │ └── association → Plant ├── composition [0..*] → OrderPartners order-specific role assignments ├── association → BusinessPartner └── association → SalesArea ``` Product, Plant, Business Partner, and Sales Area exist independently and are therefore associations rather than lifecycle-owned children. ### 12.2 Do not model the entire O2C chain as one RAP aggregate ```text Incorrect ownership idea SalesOrderRequest └── Delivery └── Billing └── Payment Better boundary SalesOrderRequest BO ──handoff/reference/event──> Fulfillment capability ──reference/status snapshot─> External successor documents ``` Delivery, material movement, billing, and payment have independent transactional and reversal lifecycles. If a portfolio cannot connect to a real S/4HANA Sales or Delivery API, represent the boundary honestly as a simulated handoff or integration adapter rather than claiming to perform standard SD PGI. ### 12.3 CDS and persistence Custom RAP CDS entities can expose the same database persistence used by ABAP, but a CDS model is not a separate database. During a RAP transaction, EML can also observe unsaved transactional-buffer state that an ordinary database `SELECT` does not automatically represent. The analogy to SD is useful: ```text RAP transactional buffer ≠ committed database state Confirmed schedule line ≠ executed PGI state Editable UI value ≠ persisted business operation ``` Every layer represents a different degree of commitment. --- ## 13. Technical Insights and Common Misinterpretations ### 13.1 The process is a graph, not a pipeline row The happy path is drawn as a line for teaching, but partial fulfillment, combination, splitting, returns, cancellations, and financial clearing create a graph. Data models and reports must support branching rather than assume one order equals one delivery equals one invoice. ### 13.2 Document existence and posting evidence are different An Outbound Delivery is strong evidence of shipping execution preparation but not of goods issue. A Billing Document is strong evidence of invoicing but not of cash receipt. Diagnose the business event through its posting document and status evidence. ### 13.3 Confirmation is commitment, not physical movement Confirmed quantity answers what SAP currently commits for a date. Delivery and PGI answer what was operationally processed and physically posted. Combining these as one “fulfilled quantity” hides important failure states. ### 13.4 Copying is not a live foreign-key projection Successor documents copy and redetermine data under business rules. The copied value can intentionally differ from the current predecessor or master data. Always inspect the value stored in the affected document and its copy-control context. ### 13.5 Status is a summary, not the cause An overall status compresses child results. It helps locate a problem but does not replace inspection of the item, schedule line, delivery, billing, posting, or clearing record that produced it. ### 13.6 Database correctness includes grain SQL can be syntactically and relationally valid while producing a wrong business total. Every quantity and amount must be interpreted with its document level, unit/currency, relevance rules, and time semantics. ### 13.7 Persistence knowledge is not write authorization Knowing that Sales Order headers are represented in `VBAK` does not authorize a program to update `VBAK`. Table knowledge supports diagnosis; released business operations preserve application invariants. ### 13.8 Component boundaries explain reversal flows PGI belongs to an inventory/accounting posting boundary even though Shipping initiates it from the delivery. Billing creates a separate billing/accounting boundary. Payment is a financial clearing boundary. Separate reversal operations exist because later documents cannot safely be erased by editing an earlier Sales Order. ### 13.9 Clean core is a contract decision Clean core does not mean a consultant must forget classic tables. It means the extension or integration contract should use released, lifecycle-stable interfaces. Classic tables and transactions remain valuable evidence in authorized on-premise/private-edition diagnosis. ### 13.10 A portfolio must label simulation honestly A custom RAP action named `SubmitForFulfillment` can demonstrate aggregate validation, authorization, messaging, events, and integration architecture. It does not become standard SD delivery or PGI unless it calls an appropriate released S/4HANA contract and the real downstream posting succeeds. --- ## 14. Compact Technical Map ```text SALES DOCUMENT VBAK (VBELN) └── VBAP (VBELN, POSNR) └── VBEP (VBELN, POSNR, ETENR) │ │ delivery relevance, due processing, copy control ▼ DELIVERY LIKP (VBELN) └── LIPS (VBELN, POSNR) │ │ picking / packing / PGI ▼ MATERIAL & VALUE POSTING MATDOC + accounting evidence │ ▼ BILLING VBRK (VBELN) └── VBRP (VBELN, POSNR) │ ▼ FINANCIAL ACCOUNTING BKPF / BSEG / ACDOCA customer open item → payment → clearing CROSS-DOCUMENT LINEAGE VBFA: predecessor document/item → successor document/item SUPPORTED EXTENSION BOUNDARY Released CDS / business object / OData API / BAPI / IDoc / event INVALID WRITE BOUNDARY Direct updates to SAP application persistence ``` The compact map is intentionally layered. The header/item/schedule hierarchy describes ownership inside a Sales document. `VBFA` describes lineage between documents. `MATDOC` and accounting persistence prove postings in other components. Released interfaces provide the supported integration boundary. 38:T905,SAP SD Order-to-Cash — Technical Architecture This document describes the technical structure and runtime boundaries of the SAP Sales and Distribution Order-to-Cash process. Its purpose is to connect the business-document chain to document grain, persistence landmarks, posting effects, document flow, diagnostic evidence, and clean-core integration contracts. The central architectural principle is: Order-to-Cash is a graph of independently meaningful business documents and postings. It is not one large database record, one status field, or one transactional aggregate. This reference distinguishes three contexts: - Classic SAP ERP and SAP S/4HANA on-premise/private edition, where SAP GUI transactions and direct table inspection may be available for authorized diagnosis. - SAP S/4HANA Cloud Public Edition, where Fiori applications, configuration activities, and released APIs are the normal operational contracts. - Clean-core extension development, where released CDS entities, business objects, events, and APIs should be preferred over dependencies on internal persistence. Primary SAP sources: - SAP Help — Sales Documents - SAP Learning — Navigating the Order-to-Cash Process Steps - SAP Help — Sales Order Item Schedule Line - SAP Help — Goods Issue - SAP Help — Billing Data Flow - SAP Help — Displaying Goods Issue Documents - SAP Help — Delivery Document CDS View --- 1. Scope and System Boundaries 1.1 Core process The common sell-from-stock flow can be represented as: text Optional presales Core execution Inquiry → Quotation → Sales Order → Outbound Delivery → PGI → Billing → Payment The technical meaning is clearer when the process is expressed as state transitions: text Customer interest ↓ Commercial offer ↓ Accepted demand and fulfillment intent ↓ Warehouse execution document ↓ Inventory and value posting ↓ Customer invoice and receivable ↓ Cash receipt and clearing Inquiry and quotation are optional presales documents. Returns, credit memos, third-party sales, intercompany sales, milestone billing, consignment, and make-to-order processes follow different branches. The architecture in this document is therefore a baseline, not a claim that every SD transaction follows one identical path. SAP describes sales, delivery, and billing39:Tb7d,# SAP SD Order-to-Cash — Technical Architecture This document describes the technical structure and runtime boundaries of the SAP Sales and Distribution Order-to-Cash process. Its purpose is to connect the business-document chain to document grain, persistence landmarks, posting effects, document flow, diagnostic evidence, and clean-core integration contracts. The central architectural principle is: > Order-to-Cash is a graph of independently meaningful business documents and > postings. It is not one large database record, one status field, or one > transactional aggregate. This reference distinguishes three contexts: - **Classic SAP ERP and SAP S/4HANA on-premise/private edition**, where SAP GUI transactions and direct table inspection may be available for authorized diagnosis. - **SAP S/4HANA Cloud Public Edition**, where Fiori applications, configuration activities, and released APIs are the normal operational contracts. - **Clean-core extension development**, where released CDS entities, business objects, events, and APIs should be preferred over dependencies on internal persistence. Primary SAP sources: - [SAP Help — Sales Documents](https://help.sap.com/docs/SAP_S4HANA_CLOUD/a376cd9ea00d476b96f18dea1247e6a5/aa64b65334e6b54ce10000000a174cb4.html) - [SAP Learning — Navigating the Order-to-Cash Process Steps](https://learning.sap.com/courses/discovering-the-basics-of-sap-s-4hana-sales/executing-sales-order-management_cad9dfbe-bafc-4ed9-ac2e-6fd8422430e4) - [SAP Help — Sales Order Item Schedule Line](https://help.sap.com/docs/SAP_S4HANA_CLOUD/03c04db2a7434731b7fe21dca77440da/37df44581efca007e10000000a441470.html) - [SAP Help — Goods Issue](https://help.sap.com/docs/SAP_S4HANA_CLOUD/aff0b3f5f46c42a2b2c0fabfc233bab2/64f81a71edf5490ab522a829be075827.html?locale=en-US&version=LATEST) - [SAP Help — Billing Data Flow](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/ed84b70c199d4470ae2e5ccb93b2e45b/e26fb6535fe6b74ce10000000a174cb4.html) - [SAP Help — Displaying Goods Issue Documents](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/c7894a248ca14f74aca67f97528e5ad7/f91bbf53d25ab64ce10000000a174cb4.html) - [SAP Help — Delivery Document CDS View](https://help.sap.com/docs/SAP_S4HANA_CLOUD/c0c54048d35849128be8e872df5bea6d/e2966bcba73a455299b4937151dfd0a3.html) --- ## 1. Scope and System Boundaries ### 1.1 Core process The common sell-from-stock flow can be represented as: ```text Optional presales Core execution Inquiry → Quotation → Sales Order → Outbound Delivery → PGI → Billing → Payment ``` The technical meaning is clearer when the process is expressed as state transitions: ```text Customer interest ↓ Commercial offer ↓ Accepted demand and fulfillment intent ↓ Warehouse execution document ↓ Inventory and value posting ↓ Customer invoice and receivable ↓ Cash receipt and clearing ```3a:T9e4e, # SAP SD Organizational Structure and Master Data — Technical Reference This document explains how SAP Sales and Distribution combines organizational configuration and reusable master data to establish a valid processing context for a sales transaction. It connects business meaning to classic persistence landmarks, maintenance transactions, runtime determination, diagnostic technique, RAP modeling, and clean-core boundaries. The central technical principle is: > Organizational structure defines where a transaction is permitted to run; > master data supplies reusable facts for that context; the Sales Order stores > the resulting transactional values. This reference distinguishes three environments: - **SAP S/4HANA on-premise or private edition**, where SAP GUI transactions, IMG activities, and authorized table inspection are common diagnostic tools. - **SAP S/4HANA Cloud Public Edition**, where Fiori applications and configuration activities replace many classic transaction-code paths. - **Clean-core extension development**, where released CDS entities, business objects, events, and APIs are contracts; internal tables are not. Primary SAP sources: - [SAP Learning — Identifying Organizational Units in SAP S/4HANA Sales](https://learning.sap.com/courses/exploring-sap-s-4hana-sales-essentials/identifying-organizational-units-in-sap-s-4hana-sales_ddb48d1e-1f57-46bd-8d13-d8e4ef6d0560) - [SAP Learning — Maintaining Organizational Units for Delivery Processing](https://learning.sap.com/courses/configuring-delivery-processing-in-sap-s-4hana-sales/maintaining-the-organizational-units-for-delivery-processing) - [SAP Learning — Managing Business Partners](https://learning.sap.com/courses/customizing-core-settings-in-financial-accounting-in-sap-s4hana/managing-business-partners) - [SAP Learning — Identifying the Source of Data in a Sales Document](https://learning.sap.com/courses/fundamental-customizing-in-sap-s-4hana-sales/identifying-the-source-of-data-in-a-sales-document) - [SAP Learning — Applying the Partner Function Concept](https://learning.sap.com/courses/fundamental-customizing-in-sap-s-4hana-sales/applying-the-partner-function-concept) - [SAP Help — Creating Customer-Material Information Records](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/7b24a64d9d0941bda1afa753263d9e39/3f8bc95360267214e10000000a174cb4.html) - [SAP Help — Business Partner Address](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/74b0b157c81944ffaac6ebc07245b9dc/e84813a97a3645b38b41d374a17ae713.html) --- ## 1. The Runtime Model ### 1.1 Three kinds of data participate in one order ```text Organizational configuration Which legal and commercial units may work together? │ ▼ Master data Who is the customer? What is sold? Which context-specific defaults apply? │ ▼ Sales Order transaction Which values were proposed, derived, copied, overridden, and accepted now? ``` These layers are related but not interchangeable: | Layer | Examples | Lifecycle | Technical role | | ---------------------------- | ------------------------------------------------------------------------------------- | ------------------------------ | -------------------------------------------------- | | Organizational configuration | Company Code, Sales Organization, Sales Area, Plant assignment | Relatively stable Customizing | Defines permitted processing contexts | | Master data | Business Partner, customer segments, product/material, customer-material relationship | Reusable across transactions | Supplies identities, classifications, and defaults | | Transaction data | Sales Order header, items, partners, schedule lines | Created for one business event | Records the actual agreement and processing state | A Sales Order does not continuously calculate every displayed field by joining the latest master data. During creation or redetermination, the application obtains values from several sources and places the accepted result in the document. This is essential for traceability: a later master-data change must not silently rewrite the commercial meaning of every historical order. ### 1.2 Configuration graph, not a flat list SAP does not merely check whether each code exists. It checks whether the required assignments and combinations exist. ```text Company Code └── Sales Organization ├── Distribution Channel │ └── forms Distribution Chain └── Division └── completes Sales Area Distribution Chain ── permits ── Plant Plant + Shipping Condition + Loading Group ── determines ── Shipping Point ``` For example, a Sales Organization, Distribution Channel, and Division may each be valid individually while their exact Sales Area combination is invalid. This is why technical diagnosis must reconstruct the full runtime key rather than validate codes one at a time. --- ## 2. Company Code and Sales Organization ### 2.1 Company Code The Company Code is an independent accounting unit for which a complete set of financial statements can be produced. In an SD process it establishes the legal and Financial Accounting context behind the selling organization. Typical responsibilities include: - accounting currency and fiscal-year context; - customer receivables and reconciliation-account processing; - tax and legal reporting context; - accounting documents generated through SD integration. The Company Code is not “the highest level of the whole SAP system.” SAP has other enterprise structures and higher grouping concepts. Its precise meaning is the smallest organizational unit for complete external accounting. ### 2.2 Sales Organization The Sales Organization is the central commercial unit in Sales and Distribution. It is responsible for selling and distributing products or services and is commonly used to control commercial reporting, master-data segments, and sales-document processing. Standard assignment rule: ```text One Company Code ──< many Sales Organizations One Sales Organization ──> exactly one Company Code ``` This relationship makes the commercial operation accountable to one legal accounting unit. It does not imply that every sales document in a Company Code shares the same route to market, product division, pricing, or fulfillment location. --- ## 3. Sales Area and Distribution Chain ### 3.1 Sales Area The Sales Area is the exact commercial context in which a sales transaction is processed: ```text Sales Organization + Distribution Channel + Division = Sales Area ``` Each component answers a different question: | Component | Meaning | Example | | -------------------- | -------------------------------- | --------------------------- | | Sales Organization | Which commercial unit sells? | Domestic Sales | | Distribution Channel | Through which route to market? | Wholesale, retail, online | | Division | Which product or service family? | Finished goods, spare parts | Two recurring misinterpretations should be avoided: - A Distribution Channel is a commercial route to market, not a truck route or shipping method. - A Division classifies a product/service range; it is not the individual material being ordered. The Sales Area scopes important customer sales data, partner determination, sales-document processing, and reporting. A valid combination must be configured explicitly. ### 3.2 Distribution Chain The Distribution Chain is the smaller combination: ```text Sales Organization + Distribution Channel = Distribution Chain ``` It omits Division. This distinction matters because some assignments and master-data views—such as material sales data and the assignment of a Plant for sales processing—are organized by Sales Organization and Distribution Channel rather than by the full Sales Area. ### 3.3 Example ```text Sales Organization: 1000 Domestic Sales Distribution Channel: 10 Direct Sales Division: 00 Cross-division products Distribution Chain: 1000 / 10 Sales Area: 1000 / 10 / 00 ``` The combination `1000 / 10 / 00` can be valid while `1000 / 20 / 00` is not, even if channel `20` exists elsewhere. The assignment is part of the business rule. --- ## 4. Plant and Shipping Point ### 4.1 Plant A Plant represents an operational location used by logistics. Depending on the business it can represent manufacturing, distribution, inventory, service, or another operational site. The Plant is deliberately not part of the Sales Area formula: - Sales Area defines the commercial selling context. - Plant defines an operational sourcing or fulfillment context. - One commercial route may use different Plants according to material, customer, stock, geography, or business rules. A Plant is assigned to a Company Code for valuation and accounting purposes. For Sales processing, a Plant must also be permitted for the relevant Distribution Chain. That assignment makes the Plant available as a possible delivering location; it does not prove that a specific order can be delivered. ### 4.2 Shipping Point A Shipping Point is the organizational unit responsible for shipping execution. It can represent a loading ramp, mail depot, express station, or other dispatch unit. SAP permits many-to-many assignment between Plants and Shipping Points, but an individual outbound delivery is processed by one Shipping Point. Therefore a different determined Shipping Point can be a delivery-split cause. The standard determination inputs are: ```text Delivering Plant + Shipping Condition + Loading Group = Shipping Point ``` Representative sources are: - delivering Plant: determined from customer/material/document context; - shipping condition: customer sales data or a document-type override; - loading group: material/product sales-general Plant data. The determination is performed for the Sales Order item because different items may use different Plants or loading requirements. ### 4.3 Permission is not determination These checks answer different questions: | Check | Meaning | | ------------------------------------- | ----------------------------------------------------- | | Distribution Chain ↔ Plant assignment | May this sales route use this Plant? | | Plant ↔ Shipping Point assignment | May this Shipping Point serve this Plant? | | Shipping-point determination | Which Shipping Point results for these exact inputs? | | ATP and scheduling | Can quantity be confirmed, and for what date? | | Delivery due processing | Is the item currently eligible for delivery creation? | Passing an organizational assignment does not guarantee ATP confirmation, delivery creation, picking, or PGI. --- ## 5. Sales Office and Sales Group A Sales Office represents a geographical or organizational sales location. A Sales Group represents a responsible team or group of employees within the sales organization, often within a Sales Office. They support responsibility assignment, reporting, and operational ownership, but they are not components of the Sales Area key. This separation lets one commercial model scale across multiple offices and teams without creating a different Sales Area for every reporting unit. ```text Sales Area Responsibility dimensions SO + Channel + Division Sales Office → Sales Group → Sales Employee ``` Do not infer from this that Sales Office and Sales Group are unimportant. Depending on configuration and reporting requirements, they can influence defaulting, authorizations, workflow, output, or analytics. They simply do not define the Sales Area itself. --- ## 6. Business Partner and Customer Data ### 6.1 Business Partner as the leading object In SAP S/4HANA, Business Partner is the leading master-data object for parties that can act as customers, suppliers, persons, or organizations. Customer and supplier integration synchronizes the relevant application-specific views. Three concepts must remain separate: | Concept | Purpose | Examples | | ---------------- | ------------------------------------------ | -------------------------------- | | BP Category | Fundamental nature of the party | Person, Organization, Group | | BP Role | Application-specific view and fields | FI Customer, Customer | | Partner Function | Responsibility in one business transaction | Sold-to, Ship-to, Bill-to, Payer | A BP Category is not a transaction role. A BP Role does not say which party receives one particular shipment. Partner Function supplies that transactional meaning. ### 6.2 Customer data segments Customer information is separated according to organizational validity: | Segment | Scope | Representative content | Classic landmark | | ------------ | ----------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------- | | General | Client-wide identity | Name, address, communication, search data | `KNA1`; BP identity also uses BP persistence such as `BUT000` | | Company Code | One customer in one accounting unit | Reconciliation account, payment methods, dunning, correspondence | `KNB1` | | Sales Area | One customer in SO/channel/division | Sales, shipping, billing, partner, pricing-related defaults | `KNVV` | The same customer can therefore be valid for one Company Code or Sales Area and missing or blocked in another. “The customer exists” is not enough evidence that the customer is usable in a given order. Typical S/4HANA customer roles include: - `FLCU00` — FI Customer, supplying Company Code/accounting context; - `FLCU01` — Customer, supplying Sales Area/sales context. Exact required roles, fields, and synchronization behavior depend on the solution scope and release. ### 6.3 Address identity and time dependency A Business Partner can have multiple addresses, address usages, and validity periods. A delivery address and billing address need not be identical. Modern multiple-address handling can determine address-dependent Sales Area data and propagate it into a newly created or changed sales document. This introduces two separate identities: ```text Business Partner identity ≠ Business Partner address identity ``` Released APIs can require a Business Partner address UUID when a specific address must be selected. Technical designs should not assume that a BP number always implies exactly one timeless address. The document behavior also depends on the operation. Changing the selected address in an existing document can redetermine address-dependent fields. A later master-data change does not mean that all old transactions become live views of the new address. The target release and address-handling configuration must be checked before making historical-data assumptions. --- ## 7. Partner Functions and Partner Determination ### 7.1 Four core customer partner functions | Partner function | Business responsibility | | ---------------- | ----------------------------------- | | Sold-to Party | Places or owns the commercial order | | Ship-to Party | Receives the goods or service | | Bill-to Party | Receives the invoice | | Payer | Pays the receivable | One Business Partner may perform all four functions. Alternatively, several partners can divide them—for example, headquarters places the order, a branch receives the goods, a shared-services entity receives invoices, and a treasury entity pays. In classic persistence and configuration, internal keys are often language- independent values inherited from German terminology, for example `AG`, `WE`, `RE`, and `RG`. APIs may expose semantic values such as sold-to or ship-to, or other codes depending on the contract. Integration logic must use the values defined by the released interface, not assume that a UI label is the stored key. ### 7.2 Partner determination Partner determination controls which partner functions are: - proposed from customer/BP relationships; - required or optional; - allowed at header or item level; - unique or repeatable; - changeable during document processing. The result is transaction data. Sales-document partner assignments are stored separately from the reusable Business Partner master because the same party can have different responsibilities in different orders. ```text BP/customer relationships + partner procedure + document context │ ▼ Sales-document partner rows ``` `VBPA` is a classic persistence landmark for sales-document partners. It is useful when diagnosing what was stored, but partner determination should be changed through supported configuration rather than direct table updates. --- ## 8. Product and Material Master Organizational Views ### 8.1 One material, several scopes The product/material master is not one flat record. Its views are organized by the business scope in which attributes are valid. | Scope | Representative content | Classic landmark | | -------------------- | ------------------------------------------------------------------------- | ---------------- | | Client/general | Material type, base unit, cross-application identity | `MARA` | | Description/language | Material descriptions | `MAKT` | | Distribution Chain | Sales unit, item-category group, sales status, delivering-plant proposals | `MVKE` | | Plant | MRP, procurement, availability, loading, planning | `MARC` | | Storage Location | Storage-location stock and operational data | `MARD` | | Units of measure | Alternative units and conversions | `MARM` | | Valuation | Valuation and price-control data | `MBEW` | The appropriate record grain matters. Reading `MARA` proves that the material exists globally; it does not prove that Sales data exists for the order's Distribution Chain or that Plant data exists for the delivering Plant. ### 8.2 Fields reused by later determinations Important examples include: - `MVKE-MTPOS`: item-category group used in item-category determination; - `MARC-DISMM`: MRP type used in schedule-line-category determination; - `MARC-LADGR`: loading group used in Shipping Point determination. These are inputs, not final decisions. The application combines them with document context and Customizing to select the result. ```text Material master classification + document context + configuration assignment = runtime document value ``` --- ## 9. Customer-Material Information Record A customer-material information record describes a relationship between one customer and one internal material in a particular commercial context. It is more specific than either master alone. Representative key context: ```text Customer + Sales Organization + Distribution Channel + Internal Material = Customer-material relationship ``` Typical content includes: - the customer's own material number and description; - customer-specific delivery agreements or tolerances; - customer-material text; - other customer/material-specific shipping information. The classic table landmark is `KNMT`; common classic transactions are `VD51` for creation, `VD52` for change, and `VD53` for display. Current S/4HANA releases can also provide Fiori maintenance applications. This record does not replace the product/material master. It maps customer- specific commercial language and agreements to an internal material that must already exist. --- ## 10. Sales Order Data-Provenance Pipeline ### 10.1 Sources A Sales Order can receive values from several independent sources: ```text Reference document ─────┐ Customer/BP master ─────┤ Material master ────────┤ Customer-material data ─┤ Condition records ──────┤──> determination and validation ──> order fields Customizing ────────────┤ Existing document data ─┤ User or interface input ┘ ``` No universal precedence rule covers every field. Each field has its own proposal, copy, override, redetermination, and validation behavior. Examples: - Sales Area may come from the entry context or reference document. - partner functions may be proposed from BP/customer relationships. - Plant may be proposed from customer-material, customer, or material context and may then be changed if permitted. - item category is determined from document type, material item-category group, item usage, and higher-level item category. - pricing is executed using pricing-procedure and condition-technique inputs. - schedule-line category uses item category and MRP type. ### 10.2 A practical provenance record When diagnosing a wrong field, capture this chain: | Evidence | Meaning | | ------------------------------ | ---------------------------------------------------- | | Actual stored value | What the transaction finally contains | | Source candidates | Master, reference document, Customizing, input, code | | Exact organizational key | Scope under which each source was read | | Determination sequence | Which source or rule had priority for this field | | Override/redetermination event | Why the original proposal may have changed | | Enhancement point or extension | Whether custom logic altered standard output | This is stronger than asking only, “Which table contains the field?” The same field name can exist at several grains and represent a source, copied snapshot, or calculated result. --- ## 11. Copy Semantics and Transactional Snapshots ### 11.1 Proposal is not live inheritance When master data proposes a value into a Sales Order, the order normally stores its own transactional value. The conceptual relationship is: ```text Master value at determination time │ copy / derive / validate ▼ Sales Order value │ └── remains part of this transaction unless explicitly changed ``` Changing master data later normally affects newly created or explicitly redetermined transactions. It does not retroactively rewrite all existing orders. This rule protects: - commercial traceability; - auditability; - stable downstream processing; - explanation of what the customer and seller agreed at that time. ### 11.2 Exceptions require field-specific analysis Some values can be redetermined when a relevant document field changes. Address-dependent Sales data is one example: selecting a different BP address can cause the application to propose different Incoterms or a different Plant. Pricing, texts, dates, partners, and output can have their own copy and redetermination controls. Therefore, “master data never changes an existing order” is too broad. The precise statement is: > Existing orders are transactional records, not live master-data projections; > however, supported change operations may deliberately redetermine selected > fields according to their configuration and application logic. --- ## 12. Classic Persistence Landmarks The following objects are useful for authorized diagnosis in classic or on-premise/private-edition environments. They are not clean-core integration contracts. ### 12.1 Organizational Customizing | Object | Typical meaning | | ------- | ----------------------------------------------------------- | | `T001` | Company Code definition | | `TVKO` | Sales Organization definition and related settings | | `TVTW` | Distribution Channel definition | | `TSPA` | Division definition | | `TVTA` | Valid Sales Area combinations | | `T001W` | Plant definition | | `TVKWZ` | Plant assignment to Sales Organization/Distribution Channel | | `TVST` | Shipping Point definition | | `TVSWZ` | Shipping Point assignment to Plant | | `TVSTZ` | Shipping Point determination combinations | | `TVBUR` | Sales Office definition | | `TVKGR` | Sales Group definition | Some relationships are technically represented through additional tables or valuation-area logic rather than one intuitive foreign-key field. The IMG and data dictionary should be used to confirm the exact implementation in the target release. ### 12.2 Business Partner and customer | Object | Typical meaning | | -------- | ---------------------------------------------------------- | | `BUT000` | General Business Partner identity | | `BUT020` | BP address assignment | | `ADRC` | Address details referenced by address number | | `KNA1` | General customer data | | `KNB1` | Customer Company Code data | | `KNVV` | Customer Sales Area data | | `KNVP` | Customer master partner functions by Sales Area | | `VBPA` | Partner assignments copied/determined for a sales document | BP/customer synchronization is handled by Customer/Vendor Integration in S/4HANA. Directly changing these tables can break consistency between the leading BP object and customer application data. ### 12.3 Product/material and relationship records | Object | Grain | | ------ | ------------------------------------------------- | | `MARA` | Material/client | | `MAKT` | Material/language | | `MVKE` | Material/Sales Organization/Distribution Channel | | `MARC` | Material/Plant | | `MARD` | Material/Plant/Storage Location | | `MARM` | Material/alternative unit | | `MBEW` | Material/valuation area/valuation type context | | `KNMT` | Customer/material/commercial relationship context | The correct join keys follow the grain. Joining only on material number can multiply or mix Sales Organization, Plant, language, unit, or valuation rows. --- ## 13. Classic Maintenance and Diagnostic Transactions These are common SAP GUI landmarks for classic/on-premise environments. Exact availability and navigation vary by release, installed scope, and authorization. For configuration work, prefer the IMG path in the target system over memorizing a transaction code without its business activity. | Area | Common landmark | Purpose | | ---------------------------- | ---------------------- | --------------------------------------------- | | Company Code | `OX02` | Define or inspect Company Codes | | Sales Organization | `OVX5` | Define Sales Organizations | | Distribution Channel | `OVXB` | Define Distribution Channels | | Division | `OVXA` | Define Divisions | | Sales Area | `OVXG` | Set up valid Sales Areas | | Sales Org → Company Code | `OVX3` | Maintain assignment | | Plant → Distribution Chain | `OVXK` | Assign Plant to Sales Org/Channel | | Shipping Point → Plant | `OVXC` | Maintain permitted assignments | | Shipping Point determination | `OVL2` | Maintain Plant/condition/loading-group result | | Business Partner | `BP` | Maintain BP roles and customer data | | Product/material | `MM01`, `MM02`, `MM03` | Create, change, display material | | Customer-material info | `VD51`, `VD52`, `VD53` | Create, change, display relationship | | Partner determination | `VOPA` | Configure partner procedures and assignments | | Sales Order | `VA01`, `VA02`, `VA03` | Create, change, display transaction result | SAP S/4HANA Cloud Public Edition uses configuration activities and Fiori apps; the same business concept may not expose a classic transaction. --- ## 14. Organizational-Key Diagnosis ### 14.1 Diagnostic sequence For an error such as “customer/material not maintained,” “Plant not allowed,” or “Shipping Point not determined,” follow the runtime dependency from broad context to exact input: ```text 1. Capture the failing document and item ↓ 2. Record the exact Sales Area and document type ↓ 3. Verify customer/BP role and organizational segments ↓ 4. Verify material Distribution Chain and Plant views ↓ 5. Verify organizational assignments ↓ 6. Reconstruct determination inputs and result ↓ 7. Check blocks, validity, status, authorization, and enhancements ``` ### 14.2 Evidence checklist | Area | Evidence to capture | | ----------------- | ------------------------------------------------------------- | | Sales context | Sales Org, Distribution Channel, Division, order type | | Partner | BP/customer number, function, selected address, required role | | Product | material number, Sales Org/Channel view, Plant view, units | | Plant | proposed/stored Plant and Distribution Chain assignment | | Shipping Point | Plant, shipping condition, loading group, determined result | | Relationship data | customer-material record and organizational key | | Runtime result | actual header/item/partner/schedule-line values | | Extensions | user exits, BAdIs, custom determination, interface mapping | ### 14.3 Diagnose the actual grain Suppose material `M-100` works in Sales Area `1000/10/00` but fails in `1000/20/00`. The global material record is not the first suspect because the same material already works elsewhere. The diagnostic focus should move to: - `MVKE` data for the failing Distribution Chain; - customer `KNVV` data for the failing Sales Area; - Plant assignment to that Distribution Chain; - condition and determination records scoped by the failing key; - blocks or validity specific to that context. This is the reusable troubleshooting pattern: > When behavior differs by organization, compare organizationally scoped data > before investigating global identity data or custom code. --- ## 15. RAP Modeling Translation ### 15.1 Ownership versus reference An SD-style RAP model should distinguish lifecycle ownership from reusable references: ```text SalesOrderRequest aggregate ownership ├── composition [0..*] Items │ └── composition [0..*] Schedules └── composition [0..*] OrderPartners Item ───────── association ─────────> Product OrderPartner ─ association ─────────> BusinessPartner Request ───── association ──────────> SalesArea / Plant reference ``` The reasoning is: - Item, Schedule, and OrderPartner rows describe this one request and normally lose their lifecycle meaning when the request is deleted. - Product, Business Partner, Plant, and organizational reference entities exist independently and are therefore associations, not compositions. `OrderPartner` can still be a composition even though it points to a Business Partner. It owns the transaction-specific fact “this BP performs this function in this request,” not the Business Partner master itself. ### 15.2 Snapshot versus live display A custom RAP application must decide deliberately which data is stored and which is dereferenced live: | Design | Benefit | Risk | | ------------------------------------------------------------- | ------------------------------------------- | ------------------------------------------------- | | Store only BP/Product key and display live association fields | Simple and always shows current master data | Historical display can drift after master changes | | Copy selected descriptive/commercial fields into transaction | Preserves what was accepted at the time | Requires clear redetermination/change rules | | Store key plus explicit snapshot fields | Separates identity from historical evidence | More fields and lifecycle logic | An association such as `_Customer.Name` is not automatically a historical snapshot. If auditability matters, the design needs explicit snapshot fields or a released standard document API that already owns those semantics. ### 15.3 Validation and determination responsibilities Representative RAP responsibilities are: - determination proposes a Plant or copies transaction currency; - validation rejects an invalid Business Partner, product, Sales Area, or organizational combination; - feature control restricts changes based on state; - authorization checks whether the user may perform the operation; - value help assists selection but does not replace backend validation. These rules belong in the business object, not only in Fiori annotations, because EML, APIs, tests, and alternate projections must receive the same protection. --- ## 16. Clean-Core and Integration Boundaries ### 16.1 Tables are landmarks, not APIs Classic tables help an authorized consultant inspect persistence. They are not stable contracts for extension or integration. Avoid designs that: - update `KNA1`, `KNVV`, `MARA`, `MVKE`, or Customizing tables directly; - expose broad table joins as public APIs without business semantics; - assume an internal table layout will remain stable across releases; - bypass BP/CVI consistency or application validations. Prefer: - released Business Partner and Product APIs; - released CDS views with the required supported capability; - released transactional business objects and EML in ABAP Cloud; - documented events or integration services; - application configuration through supported activities. Availability and release status must be checked in the target system. A CDS entity that exists is not necessarily released for every use case. ### 16.2 Read model versus write contract ```text Read/analytics released CDS view or analytical query Transactional write released API / RAP BO / documented business operation Internal diagnosis authorized app, transaction, trace, or table inspection ``` A released read model does not automatically authorize updates. Conversely, an API can execute business logic that cannot be reproduced safely by inserting database rows. ### 16.3 Extension ownership Before copying standard SD concepts into a custom RAP application, define the boundary: - If SAP S/4HANA owns the real Sales Order, extend or consume the released standard contract when possible. - If the RAP object is a request or pre-order, keep its lifecycle separate and hand off to S/4HANA through an explicit integration boundary. - Do not label a simplified custom amount derivation as complete SD pricing or a request aggregate as a standard SAP Sales Order. --- ## 17. Technical Insights and Common Misinterpretations ### 17.1 Existence is weaker than usability ```text BP exists ≠ customer role exists ≠ Company Code segment exists ≠ Sales Area segment exists ≠ partner function is valid in this document Material exists ≠ Distribution Chain sales view exists ≠ Plant view exists ≠ Plant is permitted for the Distribution Chain ≠ quantity can be confirmed ``` ### 17.2 Assignment is weaker than successful execution Organizational assignment establishes permission and reachability. Execution still depends on master data, determination, status, blocks, availability, authorization, and transaction-specific rules. ### 17.3 Master data supplies facts; the document owns the transaction The Business Partner owns reusable party identity. The Product owns reusable product identity. The Sales Order owns the fact that a particular partner, address, material, quantity, price, and date were accepted in this transaction. ### 17.4 Organizational keys explain many “same data, different result” cases If the same customer and material behave differently across orders, compare the full Sales Area, Distribution Chain, Plant, address, and document-type context. The changed behavior is often correct because a more specific master-data or configuration record applies. ### 17.5 The most specific record is not universally the winner Customer-material data is more relationship-specific than customer-only or material-only data, but field precedence is application-specific. The correct technical explanation names the field, its source sequence, and the event that triggered determination or redetermination. --- ## 18. Compact Technical Map ```text LEGAL CONTEXT Company Code │ 1:n ▼ COMMERCIAL CONTEXT Sales Organization + Distribution Channel + Division = Sales Area Sales Organization + Distribution Channel = Distribution Chain │ ├── scopes customer and material sales data └── permits Plant assignment │ ▼ FULFILLMENT CONTEXT Plant + Shipping Condition + Loading Group = Shipping Point REUSABLE MASTER DATA Business Partner ├── general identity/address ├── FI Customer / Company Code data └── Customer / Sales Area data Product/Material ├── general identity ├── Distribution Chain sales data └── Plant planning/loading data Customer-Material └── customer-specific material identity and agreements TRANSACTIONAL RESULT Sales Order ├── header: Sales Area and commercial context ├── partners: sold-to / ship-to / bill-to / payer ├── items: material, Plant, quantity, price, behavior └── schedule lines: confirmed quantity and date ``` The map should be read from top to bottom: configuration permits the context, master data supplies scoped inputs, application logic determines values, and the Sales Order records the resulting transaction. 3b:T9d0,SAP SD Organizational Structure and Master Data — Technical Reference This document explains how SAP Sales and Distribution combines organizational configuration and reusable master data to establish a valid processing context for a sales transaction. It connects business meaning to classic persistence landmarks, maintenance transactions, runtime determination, diagnostic technique, RAP modeling, and clean-core boundaries. The central technical principle is: Organizational structure defines where a transaction is permitted to run; master data supplies reusable facts for that context; the Sales Order stores the resulting transactional values. This reference distinguishes three environments: - SAP S/4HANA on-premise or private edition, where SAP GUI transactions, IMG activities, and authorized table inspection are common diagnostic tools. - SAP S/4HANA Cloud Public Edition, where Fiori applications and configuration activities replace many classic transaction-code paths. - Clean-core extension development, where released CDS entities, business objects, events, and APIs are contracts; internal tables are not. Primary SAP sources: - SAP Learning — Identifying Organizational Units in SAP S/4HANA Sales - SAP Learning — Maintaining Organizational Units for Delivery Processing - SAP Learning — Managing Business Partners - SAP Learning — Identifying the Source of Data in a Sales Document - SAP Learning — Applying the Partner Function Concept - SAP Help — Creating Customer-Material Information Records - SAP Help — Business Partner Address --- 1. The Runtime Model 1.1 Three kinds of data participate in one order text Organizational configuration Which legal and commercial units may work together? │ ▼ Master data Who is the customer? What is sold? Which context-specific defaults apply? │ ▼ Sales Order transaction Which values were proposed, derived, copied, overridden, and accepted now? These layers are related but not interchangeable: | Layer | Examples | Lifecycle | Technical role | | ---------------------------- | ------------------------------------------------------------------------------------- | ------------------------------ | -------------------------------------------------- | | Organizational configuration | Company Code, Sales Organization, Sales Area, Plant assignment | Relatively stable Customizing | Defines permitted processing contexts | | Master data | Business Partner, customer segments, product/material, customer-material relationship |3c:Tbf1,# SAP SD Organizational Structure and Master Data — Technical Reference This document explains how SAP Sales and Distribution combines organizational configuration and reusable master data to establish a valid processing context for a sales transaction. It connects business meaning to classic persistence landmarks, maintenance transactions, runtime determination, diagnostic technique, RAP modeling, and clean-core boundaries. The central technical principle is: > Organizational structure defines where a transaction is permitted to run; > master data supplies reusable facts for that context; the Sales Order stores > the resulting transactional values. This reference distinguishes three environments: - **SAP S/4HANA on-premise or private edition**, where SAP GUI transactions, IMG activities, and authorized table inspection are common diagnostic tools. - **SAP S/4HANA Cloud Public Edition**, where Fiori applications and configuration activities replace many classic transaction-code paths. - **Clean-core extension development**, where released CDS entities, business objects, events, and APIs are contracts; internal tables are not. Primary SAP sources: - [SAP Learning — Identifying Organizational Units in SAP S/4HANA Sales](https://learning.sap.com/courses/exploring-sap-s-4hana-sales-essentials/identifying-organizational-units-in-sap-s-4hana-sales_ddb48d1e-1f57-46bd-8d13-d8e4ef6d0560) - [SAP Learning — Maintaining Organizational Units for Delivery Processing](https://learning.sap.com/courses/configuring-delivery-processing-in-sap-s-4hana-sales/maintaining-the-organizational-units-for-delivery-processing) - [SAP Learning — Managing Business Partners](https://learning.sap.com/courses/customizing-core-settings-in-financial-accounting-in-sap-s4hana/managing-business-partners) - [SAP Learning — Identifying the Source of Data in a Sales Document](https://learning.sap.com/courses/fundamental-customizing-in-sap-s-4hana-sales/identifying-the-source-of-data-in-a-sales-document) - [SAP Learning — Applying the Partner Function Concept](https://learning.sap.com/courses/fundamental-customizing-in-sap-s-4hana-sales/applying-the-partner-function-concept) - [SAP Help — Creating Customer-Material Information Records](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/7b24a64d9d0941bda1afa753263d9e39/3f8bc95360267214e10000000a174cb4.html) - [SAP Help — Business Partner Address](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/74b0b157c81944ffaac6ebc07245b9dc/e84813a97a3645b38b41d374a17ae713.html) --- ## 1. The Runtime Model ### 1.1 Three kinds of data participate in one order ```text Organizational configuration Which legal and commercial units may work together? │ ▼ Master data Who is the customer? What is sold? Which context-specific defaults apply? │ ▼ Sales Order transaction Which values were proposed, derived, copied, overridden, and accepted now? ``` These layers are related but not interchangeable:3d:Tae7a, # SAP SD Sales Document Control and Pricing — Technical Reference This document explains how SAP Sales and Distribution controls a Sales Order at header, item, and schedule-line level and how the condition technique builds the document-specific pricing result. It connects business grain to determination inputs, Customizing, runtime persistence, diagnostic evidence, RAP concepts, and clean-core boundaries. The central technical principle is: > First identify the grain and the selected control object. Then distinguish > how that object was determined from what its definition makes it do. This reference distinguishes three environments: - **SAP S/4HANA on-premise or private edition**, where SAP GUI transactions, IMG activities, Pricing Analysis, and authorized table inspection are common diagnostic tools. - **SAP S/4HANA Cloud Public Edition**, where Fiori applications and configuration activities provide the supported paths and may add features such as flexible item-category determination. - **Clean-core extension development**, where released CDS entities, business objects, and APIs are contracts; classic tables and Customizing views are diagnostic landmarks rather than integration interfaces. Primary SAP sources: - [SAP Help — How Sales Documents Are Controlled](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/7b24a64d9d0941bda1afa753263d9e39/c264b65334e6b54ce10000000a174cb4.html) - [SAP Learning — Configuring a Sales Document Type](https://learning.sap.com/courses/fundamental-customizing-in-sap-s-4hana-sales/configuring-a-sales-document-type) - [SAP Learning — Configuring an Item Category](https://learning.sap.com/courses/fundamental-customizing-in-sap-s-4hana-sales/configuring-an-item-category-1) - [SAP Help — Determining Sales Document Item Categories](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/7b24a64d9d0941bda1afa753263d9e39/dc89c95360267214e10000000a174cb4.html) - [SAP Learning — Assigning Schedule Line Categories](https://learning.sap.com/courses/fundamental-customizing-in-sap-s-4hana-sales/assigning-schedule-line-categories) - [SAP Learning — Introducing the Condition Technique](https://learning.sap.com/courses/configuring-pricing-in-sap-s-4hana-sales/introducing-the-condition-technique_dce0f313-dee6-470e-8851-3f1773cb5d45) - [SAP Help — Pricing Information and Analysis](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/4dd8cb7b1c484b4b93af84d00f60fdb8/918dc95360267214e10000000a174cb4.html) - [SAP Help — Sales Order Item Pricing Element](https://help.sap.com/docs/SAP_S4HANA_CLOUD/03c04db2a7434731b7fe21dca77440da/abf59161a5734e0393d30c5fa2f41053.html) --- ## 1. Sales Document Runtime Architecture ### 1.1 The control chain ```text Header Sales document type │ supplies whole-transaction context ▼ Item Item category │ supplies product/service-line behavior ▼ Schedule line Schedule-line category │ supplies dated-quantity fulfillment behavior ▼ Subsequent processing delivery, requirements, procurement, goods movement, billing ``` The three controls cooperate, but they answer different questions: | Level | Business scope | Main control object | Stored result | | ------------- | ----------------------------- | ---------------------- | ------------- | | Header | One commercial transaction | Sales document type | `VBAK-AUART` | | Item | One product/service line | Item category | `VBAP-PSTYV` | | Schedule line | One quantity/date subdivision | Schedule-line category | `VBEP-ETTYP` | In common business speech, “line” often means Sales Order item or line item. Technically, always clarify the grain because a Sales Order item can itself contain several schedule lines and pricing-element rows. ### 1.2 Definition, assignment, and transaction result These are three different objects: ```text Category definition Describes what a category does Determination assignment Maps runtime inputs to a proposed category Selected transaction result Stores the category actually used in this document ``` Example: ```text VOV7 / TVAP → defines item category TAN VOV4 / T184 → proposes TAN for OR + NORM + blank + blank VBAP-PSTYV → stores the item category selected for Item 10 ``` A maintenance transaction changes reusable configuration. A selected transaction result records which value one business document contains. They must not be described as the same thing. ### 1.3 The primary diagnostic split ```text Unexpected category in the document → reconstruct the determination input and assignment Expected category, unexpected processing behavior → inspect the selected category's definition and dependent configuration ``` This split prevents unnecessary custom-code investigation. Standard determination must first be explained with runtime evidence. --- ## 2. Header, Item, and Schedule-Line Grain ### 2.1 Placement rule Place a value at the broadest level where it remains true without losing business meaning: ```text Entire commercial transaction → Header One product or service → Item One quantity on one date → Schedule line ``` | Level | Representative fields | | ------------- | ----------------------------------------------------------------------------------------------------- | | Header | document type, Sales Area, sold-to party, customer reference, document currency, overall value/status | | Item | material, ordered quantity, sales unit, Plant, item category, rejection reason, net value | | Schedule line | requested date/quantity, confirmed date/quantity, schedule category, delivery block | Screen position does not prove technical grain. A field shown in a page header can be an aggregate, and a visually repeated value can be stored separately at item level. ### 2.2 Classic persistence and keys | Level | Table landmark | Key excluding client | One row represents | | ------------- | -------------- | ----------------------- | ---------------------------------- | | Header | `VBAK` | `VBELN` | One sales-document header | | Item | `VBAP` | `VBELN + POSNR` | One item in the document | | Schedule line | `VBEP` | `VBELN + POSNR + ETENR` | One dated-quantity row in the item | ```text VBAK-VBELN = VBAP-VBELN VBAP-VBELN + VBAP-POSNR = VBEP-VBELN + VBEP-POSNR ``` `ETENR` identifies the schedule line. It is not the requested date or quantity. ### 2.3 Downward propagation and upward aggregation Selected header values can be copied or propagated into item fields, and an item may hold a permitted exception. This is not dynamic inheritance. ```text Header default ──copy/propagate──> aligned item value │ └── item-specific override, if allowed ``` Results also roll upward: ```text Schedule confirmations → item fulfillment state Item values → header total Item statuses → overall document status ``` Overall status is a summary, not proof that every child is in the same state. ### 2.4 Wrong-grain joins If one item has two schedule lines, joining `VBAP` to `VBEP` produces two rows for that item. Its item net value is repeated. ```text Item 10 net value: 1,000 Schedule 0001 → joined item value 1,000 Schedule 0002 → joined item value 1,000 Naive SUM → 2,000 incorrect ``` Aggregate a measure at its native grain before joining it to a lower grain. The same rule applies when joining pricing-element rows to items. --- ## 3. Sales Document Type ### 3.1 Responsibility The Sales Document Type describes the overall commercial transaction, such as an inquiry, quotation, standard order, return, or credit memo request. It can control or propose: - the broad sales-document category; - number-range and general document behavior; - delivery and billing blocks; - requested-delivery-date and other defaults; - messages or checks for reference and master data; - proposed follow-on delivery or billing document types; - the document pricing procedure used later in pricing-procedure determination. It does not fully determine the behavior of every item. The item category and schedule-line category provide lower-grain controls. ### 3.2 Technical map ```text Maintenance: VOV8 Configuration table: TVAK Transaction result: VBAK-AUART ``` `AUART` identifies the Sales Document Type. Standard code `OR` commonly means a standard Sales Order. The code is configuration, not an ABAP keyword, and a customer can copy a standard type into a `Z...` type with different behavior. SAP recommends creating a custom document type by copying a similar tested type because many dependent assignments reference it. A copied code must still be reviewed; copying does not prove that every inherited setting fits the new business process. --- ## 4. Item Category ### 4.1 Responsibility An Item Category controls how one product or service line participates in the sales process. It can influence: - whether pricing is relevant; - whether and how the item is billed; - whether business data may differ from the header; - whether the line represents a material, service, value, or text item; - the incompletion procedure; - whether schedule lines are allowed; - behavior of main items and subitems; - delivery relevance for items without schedule lines. The determination inputs select an Item Category. The Item Category definition then controls the line. Selection and behavior are distinct stages. ### 4.2 Standard determination formula ```text Sales document type + material item-category group + item usage + higher-level item category = proposed item category ``` | Input | Meaning | Common technical clue | | ---------------------------- | ------------------------------------------------------- | ---------------------------------------------------------- | | Sales document type | Whole-document transaction context | `VBAK-AUART` | | Material item-category group | General sales-processing classification of the material | `MVKE-MTPOS`, scoped by Sales Org/Channel | | Item usage | Special purpose in the current document | Often blank for an ordinary stock item | | Higher-level item category | Processing context from a parent item | Relevant to free goods, BOM components, and other subitems | ### 4.3 `OR + NORM + blank + blank → TAN` The common standard illustration means: | Code | Meaning in the example | | --------------------------- | -------------------------------------------------------- | | `OR` | Standard Sales Order document type | | `NORM` | Normal-item item-category group from material sales data | | blank usage | No specialized item usage applies | | blank higher-level category | Standalone item, not a subitem | | `TAN` | Standard order item category proposed by the assignment | ```text OR supplies order context NORM supplies material processing classification blank says no special usage blank says no parent-item context TAN is the configured default result ``` This is an example, not a universal invariant. The assignment can differ by system configuration. In supported Public Cloud scenarios, flexible item- category determination can additionally use configured business rules when the feature and prerequisites apply. ### 4.4 Main item and subitem example ```text Item 10 Material M1 100 EA normal priced item Item 20 Material M1 10 EA free-of-charge subitem Higher-level item = 10 ``` The higher-level Item Category lets the determination distinguish a subitem from an unrelated standalone item even when both use the same material. ### 4.5 Technical map ```text Determine/assign: VOV4 Assignment table: T184 Define behavior: VOV7 Definition table: TVAP Selected result: VBAP-PSTYV Master-data input: MVKE-MTPOS ``` The customer number is not one of the four standard item-category determination keys. Customer context can influence other data and newer flexible rule scenarios, but it should not be inserted into the classic formula. --- ## 5. Schedule-Line Category ### 5.1 Responsibility A Schedule-Line Category controls how one dated quantity participates in fulfillment. It can influence: - delivery relevance; - transfer of requirements; - availability checking; - the movement type used by a later goods movement; - automatic procurement or purchase-requisition behavior; - schedule-line delivery blocks. The Item Category must permit schedule lines before schedule-line control can participate. ### 5.2 Two-step determination ```text Attempt 1: Item category + MRP type Attempt 2: Item category + blank MRP type fallback ──────────────────────────────────────────────────── Result: proposed schedule-line category ``` The MRP type is Plant-specific material data, commonly `MARC-DISMM`. Therefore, the runtime Plant from the affected item is part of the diagnostic context even though Plant is not displayed as a direct key in `VOV5`. ### 5.3 Technical map ```text Determine/assign: VOV5 Assignment table: TVEPZ Define behavior: VOV6 Definition table: TVEP Selected result: VBEP-ETTYP Master-data input: MARC-DISMM ``` The assignment can also specify alternative Schedule-Line Categories that the user is allowed to select instead of the proposal. ### 5.4 Delivery relevance nuance For an ordinary item with schedule lines, schedule-line configuration is central to delivery relevance of the dated quantity. The Item Category's delivery-relevance indicator is particularly used for delivery-relevant items without schedule lines, such as certain text items. Therefore neither of these absolute claims is safe: ```text “Only the item category controls delivery relevance.” “Only the schedule-line category controls delivery relevance.” ``` The correct answer begins with whether the item has schedule lines and then identifies the relevant control. ### 5.5 Movement type is a future posting rule ```text Schedule category contains movement-type control ≠ Inventory has already changed ``` Saving the Sales Order records demand and processing instructions. Inventory changes only when the logistics process executes an applicable goods movement, normally at Post Goods Issue for an outbound sell-from-stock scenario. --- ## 6. Complete Sales-Document Control Map | Purpose | Maintenance | Configuration landmark | Runtime result | | -------------------------------- | ----------- | ---------------------- | ------------------------ | | Define Sales Document Type | `VOV8` | `TVAK` | `VBAK-AUART` | | Determine Item Category | `VOV4` | `T184` | proposes `VBAP-PSTYV` | | Define Item Category | `VOV7` | `TVAP` | behavior of `VBAP-PSTYV` | | Determine Schedule-Line Category | `VOV5` | `TVEPZ` | proposes `VBEP-ETTYP` | | Define Schedule-Line Category | `VOV6` | `TVEP` | behavior of `VBEP-ETTYP` | Compact memory map: ```text VOV8 defines the header transaction VOV4 finds the Item Category VOV7 defines the Item Category VOV5 finds the Schedule-Line Category VOV6 defines the Schedule-Line Category ``` All `VOV...` transactions are related to SD configuration, but they do not all configure the same object. The prefix alone is not a diagnostic explanation. Always name the IMG activity and the affected runtime result. --- ## 7. Pricing Architecture ### 7.1 Why pricing is not one material price The transaction price can depend on: - customer or customer group; - product or product hierarchy; - Sales Area; - ordered quantity and scale; - pricing date and validity interval; - currency and unit of measure; - negotiated discounts; - freight, surcharge, promotion, and tax; - exclusion, requirement, formula, or manual entry; - document and billing repricing rules. SAP therefore uses the condition technique: reusable configuration and condition master data produce document-specific pricing-element rows. ### 7.2 Two separate pricing pipelines ```text PIPELINE A — SELECT THE PRICING PROCEDURE Sales Organization + Distribution Channel + Division + Document Pricing Procedure + Customer Pricing Procedure = Pricing Procedure PIPELINE B — EXECUTE THE PRICING PROCEDURE Pricing Procedure → Step / counter → Condition Type → Access Sequence → Condition Table key → Valid Condition Record → Rate / base / unit / scale / formula → Document Pricing Element ``` Pipeline A answers **which calculation framework applies**. Pipeline B answers **how that framework calculated the item**. --- ## 8. Pricing-Procedure Determination ### 8.1 Inputs ```text Sales Area = Sales Organization + Distribution Channel + Division Document Pricing Procedure ← Sales Document Type ← classic clue TVAK-KALVG Customer Pricing Procedure ← sold-to party Sales Area data ← classic clue KNVV-KALKS Selected Pricing Procedure ← determination configured in OVKK ← common document clue VBAK-KALSM ``` The input is not simply “customer plus material.” Customer/material keys are commonly used later by a condition-table access; they do not replace pricing- procedure determination. ### 8.2 Technical map | Object | Landmark | Purpose | | ------------------------- | ------------------------------------- | ------------------------------------------------------------------ | | Procedure determination | `OVKK` / `T683V` | Map Sales Area and two procedure indicators to a pricing procedure | | Document procedure source | `VOV8` / `TVAK-KALVG` | Supply indicator from Sales Document Type | | Customer procedure source | BP/customer sales data / `KNVV-KALKS` | Supply indicator for sold-to in the Sales Area | | Selected result | `VBAK-KALSM` | Record the procedure used by the document | If the wrong pricing procedure was selected, tracing its condition records is premature. First reconstruct all five inputs and prove the `OVKK` result. --- ## 9. Condition-Technique Components ### 9.1 Responsibility map | Component | Responsibility | Not the same as | | ----------------- | ---------------------------------------------------------------------------- | ------------------------------------ | | Pricing Procedure | Orders condition types and step-level calculation controls | A customer's maintained price | | Condition Type | Represents one concept such as price, discount, freight, surcharge, or tax | The actual rate | | Access Sequence | Searches condition tables in priority order for one automatic Condition Type | The procedure's condition-type order | | Condition Table | Defines the fields forming one search key | A record containing a rate | | Condition Record | Stores rate, validity, currency/unit, and scales for one key value | The calculated document result | | Pricing Element | Stores how the condition participated in one document | Reusable master data | The most important distinction is: ```text Pricing Procedure sequence = calculation order across Condition Types Access Sequence = record-search order inside one Condition Type ``` ### 9.2 Specific-to-general access ```text Access 10 Sales Org + Customer + Material ↓ no applicable record Access 20 Customer Price Group + Material ↓ no applicable record Access 30 Sales Org + Material ↓ record found Result use the applicable general material record ``` The order preserves commercial priority. A negotiated customer/material record normally deserves priority over a general material fallback. An unsuccessful specific access can be expected behavior rather than an error. ### 9.3 Condition table versus condition record ```text Condition table definition Key fields: Sales Org + Customer + Material Condition record instance 1000 + C100 + M200 90 EUR per 1 EA Valid 01 Jan–31 Dec ``` Generated `Axxx` tables commonly index condition records using the configured key and point to condition-record identity such as `KNUMH`. The number and key layout are configuration-dependent. A record can exist but not apply because: - the access was never executed; - runtime key values differ; - the pricing date is outside validity; - an earlier access already satisfied the search; - the condition was excluded or made inactive; - unit, currency, scale, or other control does not match the expectation. --- ## 10. Pricing-Procedure Row Controls ### 10.1 Step and counter The step controls sequence. The counter distinguishes multiple entries at the same step. ```text Step 10 / Counter 0 → base price Step 20 / Counter 0 → discount Step 30 / Counter 0 → subtotal Step 40 / Counter 0 → freight Step 50 / Counter 0 → tax ``` The actual procedure can contain more complex bases, subtotals, statistical rows, exclusions, and formulas. ### 10.2 Important controls | Control | Technical meaning | | ------------------------------- | ------------------------------------------------------------------------------------------------- | | Requirement | Routine decides whether the row is processed in the current context | | Manual | Condition is intended for manual input rather than ordinary automatic access | | Mandatory | The condition is expected; absence can affect completeness or messages according to configuration | | Statistical | Condition is calculated and retained without normal contribution to net value | | From/To | References earlier steps as a calculation or subtotal range | | Subtotal | Stores an intermediate result for subsequent use | | Alternative base formula | Replaces the ordinary condition base | | Alternative calculation formula | Replaces ordinary condition-value calculation | Statistical does not mean useless. A statistical condition can support cost, credit, analytics, or another downstream purpose. ### 10.3 Inactive is not draft An inactive pricing condition is a result row that does not currently contribute to the effective calculation. It can have been found and then deactivated through exclusion or competing-condition logic. ```text Material discount: 5% found, inactive Customer discount: 10% found, active Rule: retain only the better discount ``` This is unrelated to a RAP draft, which is a persisted editing state for a business-object instance. --- ## 11. Rate, Base, Unit, Scale, and Value ### 11.1 Core arithmetic concepts ```text Condition rate = maintained amount or percentage Condition base = amount or quantity affected by the rate Condition value = calculated contribution in this document ``` Percentage example: ```text Rate: 10% Base: 1,000 EUR Value: -100 EUR ``` Pricing-unit example: ```text Rate: 100 EUR Pricing unit: 10 Condition unit: EA Meaning: 100 EUR per 10 EA 20 EA → 200 EUR ``` The numerical rate is incomplete without its currency, unit, pricing unit, and scale context. ### 11.2 Pricing-result fields | Field | Meaning | Diagnostic use | | ------- | ------------------------------------------- | ----------------------------------------- | | `KSCHL` | Condition Type | Identify the pricing concept | | `KBETR` | Condition rate | Compare with the master record/scale | | `KAWRT` | Condition base value | Verify quantity, amount, or base formula | | `KWERT` | Condition value | Verify calculated document contribution | | `KPEIN` | Pricing unit | Interpret rate per 1, 10, 100, and so on | | `KMEIN` | Condition unit | Interpret unit to which the rate applies | | `KNUMH` | Condition-record reference where applicable | Trace selected master record | | `KSTAT` | Statistical indicator | Explain net-value participation | | `KINAK` | Inactive context | Explain why a found row is ineffective | | `KHERK` | Condition origin | Help identify how the row entered pricing | Diagnostic split: ```text Wrong KBETR → record, scale, conversion, or manual rate Wrong KAWRT → quantity, amount, or alternative-base logic Wrong KPEIN/KMEIN → pricing-unit or UoM interpretation Inputs correct but KWERT wrong → formula, sign, conversion, or rounding ``` --- ## 12. Pricing Configuration and Master-Data Landmarks ### 12.1 Classic maintenance transactions | Transaction | Responsibility | | ---------------------- | ---------------------------------------------------------------------------------------- | | `OVKK` | Determine the Sales pricing procedure | | `V/08` | Define procedure steps, counters, Condition Types, requirements, subtotals, and formulas | | `V/06` | Define Condition Type behavior and assign its Access Sequence | | `V/07` | Define ordered accesses and Condition Tables in an Access Sequence | | `V/03`, `V/04`, `V/05` | Create, change, and display classic Condition Table definitions | | `VK11`, `VK12`, `VK13` | Create, change, and display condition records | `VK13` displays condition master data. It is not the Sales Order Pricing Analysis technical view. ```text Pricing Analysis technical view → what fields and values the runtime searched VK13 → what condition record was maintained ``` Diagnosis compares them. ### 12.2 Configuration tables | Object | Classic landmark | Meaning | | ------------------------------- | ----------------- | ---------------------------------------- | | Pricing-procedure determination | `T683V` | Input combination selects procedure | | Pricing-procedure steps | `T683S` | Step/counter and row controls | | Condition Type | `T685` | Condition-Type definition | | Access Sequence | `T682I` / `T682Z` | Accesses and access fields | | Condition Table | generated `Axxx` | Business-key index for condition records | ```text T683V selects procedure T683S orders and controls calculation steps T685 defines the Condition Type T682I/Z defines the record-search strategy Axxx indexes condition records by configured business key ``` These objects must not be updated directly. Use authorized Customizing or master-data applications and transport configuration through the landscape. --- ## 13. Document Pricing-Result Persistence ### 13.1 S/4HANA result model ```text VBAK-KNUMV = PRCD_ELEMENTS-KNUMV ``` One document pricing result contains items, procedure steps, and potentially several entries at one step. A useful classic technical grain is: ```text KNUMV + KPOSN + STUNR + ZAEHK ``` | Field | Identifies | | ------- | ---------------------------------------------------------------------------- | | `KNUMV` | Pricing result for a business document | | `KPOSN` | Item within that pricing result; header context can use a header-level value | | `STUNR` | Procedure step | | `ZAEHK` | Entry/counter within the step | `PRCD_ELEMENTS` stores the document result, not the reusable condition master record. Joining it to `VBAP` creates multiple rows per Sales Order item. ### 13.2 `KONV` versus `PRCD_ELEMENTS` ```text SAP ERP KONV → traditional persisted document pricing result SAP S/4HANA PRCD_ELEMENTS → persisted pricing result KONV → compatibility/application structure role, not old persistence ``` It is inaccurate to say that `KONV` can never appear in S/4HANA code. The precise statement is that `PRCD_ELEMENTS` replaced it in the database persistence role. Neither object should become a new clean-core integration contract. ### 13.3 Result-grain aggregation risk ```text Sales Order Item 10: net value 1,000 Pricing row PR00: 1,200 Pricing row K004: -100 Pricing row K007: -100 Join result repeats Item.NetValue three times. SUM(Item.NetValue) = 3,000 incorrect ``` Use pricing-element values for pricing analysis and item values for item-level reporting. Aggregate each measure at its own grain before combining them. --- ## 14. Pricing Analysis Failure Classes Pricing Analysis should classify the failure before the consultant searches tables or enhancements. | Runtime state | Meaning | Primary investigation | | ----------------------------------- | --------------------------------------------- | ------------------------------------------------------------ | | Condition Type skipped | Procedure control prevented processing | Requirement, manual-only setting, context, procedure row | | Access executed, no record found | No applicable record matched | Runtime key, pricing date, validity, condition master | | Record found but condition inactive | Condition was considered but made ineffective | Exclusion, competition, manual replacement, limits | | Active condition, wrong value | Selection succeeded but calculation differs | Rate, base, scale, unit, formula, sign, conversion, rounding | ```text Skipped → procedure control Not found → access key and record Inactive → exclusion or competition Wrong value → calculation inputs ``` “The record exists in `VK13`” does not prove that it applied. Pricing Analysis must show that the expected Condition Type and access were executed with the expected runtime key and date. --- ## 15. End-to-End Pricing Diagnostic Algorithm ### 15.1 Capture the exact grain In `VA03` or the corresponding Fiori application, capture: - Sales Order `VBELN` and item `POSNR`; - expected and actual net value; - expected and actual Condition Type/rate; - Sales Area, sold-to party, material, quantity, unit, currency, and pricing date. Do not begin from a screenshot containing only the final total. ### 15.2 Confirm item eligibility Inspect: - selected Item Category `VBAP-PSTYV`; - whether the Item Category is pricing relevant; - rejection, incompletion, status, or special item behavior; - manual changes or reference-document copying. ### 15.3 Prove pricing-procedure selection ```text Sales Area + TVAK-KALVG + KNVV-KALKS → OVKK / T683V → expected Pricing Procedure → compare with VBAK-KALSM ``` If the procedure is wrong, stop and diagnose its inputs or determination. ### 15.4 Verify procedure and Condition Type In `V/08`, prove that the expected Condition Type exists at the expected step/counter and inspect requirement, manual, mandatory, statistical, subtotal, and formula controls. In `V/06`, prove its assigned Access Sequence and Condition-Type behavior. ### 15.5 Trace the Access Sequence Use Pricing Analysis to inspect each access in order: ```text Condition Type processing status ├── no → procedure/requirement/manual control └── yes ↓ Expected-access execution status ├── no → access requirement or earlier exclusive success └── yes ↓ Condition-record search result ├── no → compare runtime key/date with condition record └── yes ↓ Condition activity status ├── no → exclusion/competition/inactive reason └── yes → validate calculation ``` ### 15.6 Compare runtime key with condition master From Pricing Analysis technical data, record the actual search values. Compare them with `VK13` or the supported condition-record application: - Condition Type; - full Condition Table key; - valid-from and valid-to dates; - rate and currency; - pricing unit and Condition Unit; - quantity/value scale and selected tier. ### 15.7 Validate the calculation Inspect `KBETR`, `KAWRT`, `KWERT`, `KPEIN`, `KMEIN`, formulas, sign, conversion, and rounding. A correct record selection does not prove correct arithmetic. ### 15.8 Widen only after standard logic is explained Then investigate: - manual conditions; - condition exclusion; - reference-document copy and repricing type; - user exits, BAdIs, formulas, or custom routines; - external pricing integration; - API payload behavior; - release-specific features. The evidence chain should explain exactly where observed behavior diverges: ```text grain → eligibility → procedure → step → access → record → calculation → result ``` --- ## 16. Item- and Schedule-Category Diagnostic Algorithms ### 16.1 Wrong Item Category ```text 1. Capture VBAK-AUART and VBAP-PSTYV 2. Read MVKE-MTPOS for the exact Sales Org/Channel 3. Capture item usage 4. Capture higher-level Item Category when it is a subitem 5. Reconstruct the exact VOV4 / T184 combination 6. Compare proposed, allowed alternatives, and actual result 7. If result is expected, inspect behavior in VOV7 / TVAP 8. Only then inspect enhancements or flexible determination ``` ### 16.2 Correct schedule category but no requirements transfer ```text 1. Identify VBELN + POSNR + ETENR 2. Capture VBAP-PSTYV and VBEP-ETTYP 3. Read MARC-DISMM for the exact Material and Plant 4. Verify exact Item Category/MRP Type assignment in VOV5 5. Verify blank-MRP fallback if exact assignment is absent 6. Inspect selected category in VOV6 7. Check requirements-transfer and availability controls 8. Check status, blocks, dates, and dependent configuration 9. Widen to custom code only after standard evidence is complete ``` ### 16.3 Configuration result versus execution evidence | Configuration says | It proves | It does not prove | | ------------------------------------ | ----------------------------------------------- | ------------------------------------- | | Item is pricing relevant | Pricing may run for the item | Correct Condition Record was selected | | Schedule line transfers requirements | Demand transfer is configured | ATP confirmed the requested quantity | | Movement type is assigned | Later goods movement has a posting rule | PGI occurred | | Item is billing relevant | Subsequent billing is permitted by that control | Billing document exists | --- ## 17. Sales Order Pricing Versus Billing Pricing A Billing Document can copy or redetermine pricing according to copy-control pricing type and process design. Potential differences include: - different pricing date; - updated Condition Records or validity; - actual billed quantity and scale; - exchange-rate or currency handling; - tax redetermination; - copied or redetermined manual conditions; - selected pricing type in copy control. ```text Sales Order pricing result ≠ guaranteed identity Billing Document pricing result ``` Before classifying a difference as a defect, capture the document flow, reference relationship, pricing dates, source/target pricing elements, billed quantity, and copy-control pricing type. --- ## 18. RAP Translation and Portfolio Boundary ### 18.1 SD determination versus RAP determination | Concept | Purpose | Mechanism | | ------------------------- | ------------------------------------------------------ | ---------------------------------------------------- | | SD category determination | Select configured category from business inputs | Customizing assignment such as `VOV4` or `VOV5` | | SD pricing determination | Select and execute pricing configuration and records | Condition technique | | RAP determination | Automatically derive BO fields after declared triggers | Behavior definition and behavior-pool implementation | | RAP validation | Reject inconsistent BO state | Behavior definition and behavior pool | ```text SD: OR + NORM + blank + blank → TAN RAP: RequestedQuantity changes → recalculate NetAmount ``` The shared word “determination” does not make these mechanisms equivalent. ### 18.2 `deriveAmounts` is not the SD condition technique A simple RAP portfolio calculation can be: ```text RequestedQuantity × UnitPrice → Item.NetAmount Σ Item.NetAmount → Request.TotalAmount ``` Standard SD pricing is: ```text Procedure determination → Condition Types → Access Sequences → Condition Records → rates, bases, units, scales, formulas → discounts, freight, tax, exclusion → document pricing result ``` The RAP calculation is credible for an SD-inspired order request, but it must not be presented as a reimplementation of standard SAP Sales pricing. ### 18.3 Safe portfolio evolution The custom BO can expose an explicit pricing status: ```text Estimated → custom request-level calculation Priced by S/4HANA → result returned by a released Sales Order/pricing contract ``` Keep the integration behind an adapter so the custom domain model does not depend directly on `PRCD_ELEMENTS`, `KONV`, or generated `Axxx` tables. --- ## 19. Clean-Core Access and Extension Rules ### 19.1 Persistence is not a write interface Never repair a pricing or category symptom by directly updating: - `VBAK`, `VBAP`, or `VBEP`; - `PRCD_ELEMENTS` or condition master tables; - `TVAK`, `TVAP`, `TVEP`, `T184`, or other Customizing tables. Such writes bypass business logic, dependent updates, authorization, consistency, transport governance, and compatibility contracts. ### 19.2 Preferred contracts Use, as available and released in the target system: - Sales Order business objects and APIs for transactional operations; - released CDS views for supported read and analytical use cases; - Sales Order item-pricing-element API nodes for pricing-result consumption; - supported pricing configuration and condition-record applications; - released enhancement points for additional fields or rules. Release status and supported capability must be checked in the target system. An entity can exist without being released for Cloud development or without supporting transactional writes. ### 19.3 Cloud configuration distinction Public Cloud commonly exposes configuration activities through SAP Central Business Configuration or the supported configuration environment rather than classic transactions. Flexible Item Category Determination can supplement standard assignment in supported scenarios by evaluating configured business rules. This does not invalidate the classic four-input model. It means the diagnostic record must include edition, release, activated feature, and business-rule result before concluding that `T184` alone explains the selected category. --- ## 20. Technical Insights and Common Misinterpretations ### 20.1 Category code does not explain behavior by itself `TAN` is a selected classification. Its effective behavior comes from the definition and dependent settings in the target system. Never diagnose only from the label “standard item.” ### 20.2 Material classification does not fully determine the item `NORM` supplies one input. Document type, usage, and higher-level category allow the same material to participate differently across commercial contexts. ### 20.3 A valid Condition Record is not necessarily applicable Applicability requires that the correct procedure and Condition Type execute the expected access with matching runtime keys and pricing date, and that the result remains active. ### 20.4 A selected price is not a material-master property Pricing elements belong to the document result. They can depend on customer, date, quantity, currency, commercial agreements, and calculation controls that do not belong to the material alone. ### 20.5 Selection, calculation, and posting are separate boundaries ```text Category selected → classification result Price calculated → document commercial result Delivery created → execution document exists PGI posted → inventory movement occurred Billing posted → invoice/accounting boundary occurred ``` Evidence from one boundary must not be used to claim that a later boundary has completed. ### 20.6 Configuration before customization The strongest diagnostic order is: ```text Capture actual grain → prove stored result → reconstruct inputs → prove assignment → inspect definition → inspect dependent master/configuration → investigate custom code ``` This is not an assumption that custom code is harmless. It is an evidence strategy that first explains standard runtime behavior and gives custom-code analysis precise input/output expectations. --- ## 21. Compact Technical Map ```text SALES DOCUMENT CONTROL Header VOV8 / TVAK → Sales Document Type → VBAK-AUART │ ▼ Item Category determination VBAK-AUART + MVKE-MTPOS + item usage + higher-level Item Category → VOV4 / T184 → VBAP-PSTYV → behavior in VOV7 / TVAP │ ▼ Schedule-Line Category determination VBAP-PSTYV + MARC-DISMM for Material/Plant → VOV5 / TVEPZ, then blank-MRP fallback → VBEP-ETTYP → behavior in VOV6 / TVEP PRICING CONTROL Sales Area + TVAK-KALVG + KNVV-KALKS → OVKK / T683V → VBAK-KALSM Pricing Procedure │ ▼ V/08 / T683S procedure step → V/06 / T685 Condition Type → V/07 / T682I/Z Access Sequence → generated Axxx Condition Table key → matching valid Condition Record → rate + base + unit + scale + formula → PRCD_ELEMENTS document result ``` Read both maps in the same order: capture the stored result, reconstruct the inputs that selected it, inspect the reusable definition that controls its behavior, and only then widen the investigation. 3e:T927,SAP SD Sales Document Control and Pricing — Technical Reference This document explains how SAP Sales and Distribution controls a Sales Order at header, item, and schedule-line level and how the condition technique builds the document-specific pricing result. It connects business grain to determination inputs, Customizing, runtime persistence, diagnostic evidence, RAP concepts, and clean-core boundaries. The central technical principle is: First identify the grain and the selected control object. Then distinguish how that object was determined from what its definition makes it do. This reference distinguishes three environments: - SAP S/4HANA on-premise or private edition, where SAP GUI transactions, IMG activities, Pricing Analysis, and authorized table inspection are common diagnostic tools. - SAP S/4HANA Cloud Public Edition, where Fiori applications and configuration activities provide the supported paths and may add features such as flexible item-category determination. - Clean-core extension development, where released CDS entities, business objects, and APIs are contracts; classic tables and Customizing views are diagnostic landmarks rather than integration interfaces. Primary SAP sources: - SAP Help — How Sales Documents Are Controlled - SAP Learning — Configuring a Sales Document Type - SAP Learning — Configuring an Item Category - SAP Help — Determining Sales Document Item Categories - SAP Learning — Assigning Schedule Line Categories - SAP Learning — Introducing the Condition Technique - SAP Help — Pricing Information and Analysis - SAP Help — Sales Order Item Pricing Element --- 1. Sales Document Runtime Architecture 1.1 The control chain text Header Sales document type │ supplies whole-transaction context ▼ Item Item category │ supplies product/service-line behavior ▼ Schedule line Schedule-line category │ supplies dated-quantity fulfillment behavior ▼ Subsequent processing delivery, requirements, procurement, goods movement, billing The three controls cooperate, but they answer different questions: | Level | Business scope | Main control object | Stored result | | ------------- | ----------------------------- | ---------------------- | ------------- | | Header | One commercial transaction | Sales document type | VBAK-AUART | | Item | One product/service line |3f:Tc56,# SAP SD Sales Document Control and Pricing — Technical Reference This document explains how SAP Sales and Distribution controls a Sales Order at header, item, and schedule-line level and how the condition technique builds the document-specific pricing result. It connects business grain to determination inputs, Customizing, runtime persistence, diagnostic evidence, RAP concepts, and clean-core boundaries. The central technical principle is: > First identify the grain and the selected control object. Then distinguish > how that object was determined from what its definition makes it do. This reference distinguishes three environments: - **SAP S/4HANA on-premise or private edition**, where SAP GUI transactions, IMG activities, Pricing Analysis, and authorized table inspection are common diagnostic tools. - **SAP S/4HANA Cloud Public Edition**, where Fiori applications and configuration activities provide the supported paths and may add features such as flexible item-category determination. - **Clean-core extension development**, where released CDS entities, business objects, and APIs are contracts; classic tables and Customizing views are diagnostic landmarks rather than integration interfaces. Primary SAP sources: - [SAP Help — How Sales Documents Are Controlled](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/7b24a64d9d0941bda1afa753263d9e39/c264b65334e6b54ce10000000a174cb4.html) - [SAP Learning — Configuring a Sales Document Type](https://learning.sap.com/courses/fundamental-customizing-in-sap-s-4hana-sales/configuring-a-sales-document-type) - [SAP Learning — Configuring an Item Category](https://learning.sap.com/courses/fundamental-customizing-in-sap-s-4hana-sales/configuring-an-item-category-1) - [SAP Help — Determining Sales Document Item Categories](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/7b24a64d9d0941bda1afa753263d9e39/dc89c95360267214e10000000a174cb4.html) - [SAP Learning — Assigning Schedule Line Categories](https://learning.sap.com/courses/fundamental-customizing-in-sap-s-4hana-sales/assigning-schedule-line-categories) - [SAP Learning — Introducing the Condition Technique](https://learning.sap.com/courses/configuring-pricing-in-sap-s-4hana-sales/introducing-the-condition-technique_dce0f313-dee6-470e-8851-3f1773cb5d45) - [SAP Help — Pricing Information and Analysis](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/4dd8cb7b1c484b4b93af84d00f60fdb8/918dc95360267214e10000000a174cb4.html) - [SAP Help — Sales Order Item Pricing Element](https://help.sap.com/docs/SAP_S4HANA_CLOUD/03c04db2a7434731b7fe21dca77440da/abf59161a5734e0393d30c5fa2f41053.html) --- ## 1. Sales Document Runtime Architecture ### 1.1 The control chain ```text Header Sales document type │ supplies whole-transaction context ▼ Item Item category │ supplies product/service-line behavior ▼ Schedule line Schedule-line category │ supplies dated-quantity fulfillment behavior ▼ Subsequent processing delivery, requirements, procurement, goods movement, billing ``` The three controls cooperate, but they answer different questions:40:Te148, # SAP SD Fulfillment, Posting, and Integration — Technical Reference This document explains the technical execution path from a delivery-relevant Sales Order through Outbound Delivery, picking, packing, Post Goods Issue (PGI), billing, accounting, payment clearing, and external integration. It connects business-document boundaries to configuration, persistence, application logs, interfaces, reversals, diagnostic evidence, and clean-core extension design. The central technical principle is: > A planned or created document proves intent at its own boundary. Only the > corresponding posting document and consistent process state prove that a > physical or financial event occurred. This reference distinguishes three environments: - **SAP S/4HANA on-premise or private edition**, where SAP GUI transactions, IMG activities, and authorized persistence inspection are common diagnostic tools. - **SAP S/4HANA Cloud Public Edition**, where Fiori applications, configuration activities, released APIs, and communication arrangements are the normal operational contracts. - **Clean-core extension development**, where internal SD, MM, and FI tables are diagnostic landmarks—not write interfaces or lifecycle-stable APIs. Primary SAP sources: - [SAP Learning — Processing Outbound Deliveries](https://learning.sap.com/courses/configuring-delivery-processing-in-sap-s-4hana-sales/processing-outbound-deliveries) - [SAP Learning — Posting a Goods Issue](https://learning.sap.com/courses/configuring-delivery-processing-in-sap-s-4hana-sales/posting-a-goods-issue) - [SAP Help — Shipping Points](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/c7894a248ca14f74aca67f97528e5ad7/5d1bbf53d25ab64ce10000000a174cb4.html) - [SAP Help — Goods Issue](https://help.sap.com/docs/SAP_S4HANA_CLOUD/aff0b3f5f46c42a2b2c0fabfc233bab2/64f81a71edf5490ab522a829be075827.html) - [SAP Help — Outbound Delivery API Operations](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/2f36056ae9a044bba55bcbad204b7bc5/a4c5d84ecef2494985883829a24e393c.html) - [SAP Learning — Billing and Integration to SAP S/4HANA Finance](https://learning.sap.com/courses/exploring-sap-s-4hana-sales-essentials/executing-the-billing-process-and-the-integration-to-sap-s-4hana-finance_e2dd5db3-73c3-4cda-8ad5-1e7f39f04fba) - [SAP Help — Canceling Billing Documents](https://help.sap.com/docs/SAP_S4HANA_CLOUD/a376cd9ea00d476b96f18dea1247e6a5/2a70b6535fe6b74ce10000000a174cb4.html) - [SAP Help — IDoc Inbound Processing](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/7b24a64d9d0941bda1afa753263d9e39/4b4c8e091c300a93e10000000a421937.html) --- ## 1. Execution Boundaries ### 1.1 Baseline sell-from-stock flow ```text Sales Order accepted demand and commercial intent │ ▼ Outbound Delivery shipping execution object │ ├── picking ├── packing └── warehouse execution │ ▼ Post Goods Issue inventory and relevant value posting │ ▼ Billing Document customer invoice and FI transfer │ ▼ Incoming Payment and Clearing cash receipt and receivable settlement ``` This is a baseline, not a universal sequence. Third-party sales, services, intercompany processing, consignment, returns, pro forma billing, EWM-managed warehouses, and other scenarios use different branches. ### 1.2 Each boundary proves one fact | Evidence | Fact established | Fact not established | | ---------------------------- | ------------------------------------------ | ---------------------------------------- | | Sales Order exists | Demand and processing intent were recorded | Goods were shipped | | Outbound Delivery exists | Shipping execution document was created | Picking or PGI completed | | Picking complete | Required warehouse staging was recorded | Inventory was posted out | | PGI material document exists | Goods issue posting occurred | Customer was billed or paid | | Billing Document exists | Billing transaction was created | FI transfer and payment always succeeded | | FI customer open item exists | Receivable was posted | Incoming cash was matched and cleared | | Payment document exists | Cash-related posting occurred | The intended invoice was fully cleared | The technical investigation must move to the evidence owned by the failing boundary rather than infer later events from an earlier document. ### 1.3 State transition versus data creation ```text Create Delivery → new delivery aggregate Pick → update warehouse/delivery execution state Pack → create or update handling-unit assignment Post GI → create posting documents and update delivery state Create Billing → new billing aggregate and possible FI posting Receive Payment → new FI posting and clearing relationship ``` These operations require business logic. Directly inserting or updating a row cannot reproduce their cross-component effects. --- ## 2. From Sales Order to Delivery Due Processing ### 2.1 Delivery eligibility A Sales Order item becomes relevant to delivery processing only when its transactional and configured conditions permit it. Typical evidence includes: - item and schedule-line delivery relevance; - confirmed quantity remaining for delivery; - material and Plant data; - Shipping Point and route/shipping context; - relevant delivery date within the due-list horizon; - no blocking or rejection state preventing delivery; - sufficient completion of required document data; - no successor delivery already consuming the due quantity. ```text Configured relevance + confirmed open quantity + due date in selection horizon + valid organizational/shipping data + no effective block or completion = candidate for delivery due processing ``` The due list is a selection and work-processing mechanism. Absence from it does not by itself prove a program defect. ### 2.2 Quantity separation | Measure | Grain | Meaning | | ------------------ | ---------------------------- | ------------------------------------------- | | Ordered quantity | Sales Order item | Total customer demand | | Confirmed quantity | Schedule line/date | Quantity currently committed | | Delivery quantity | Delivery item | Quantity placed into one execution document | | Picked quantity | Delivery/warehouse execution | Quantity staged for dispatch | | GI quantity | Material-document item | Quantity physically posted out | | Billed quantity | Billing item | Quantity used by billing basis | “Open quantity” must be qualified: ```text Open order quantity Open confirmed quantity for delivery Unpicked delivery quantity Unposted GI quantity Unbilled quantity ``` Each measure has a different source, relevance rule, and unit context. ### 2.3 Classic navigation | Operation | Common classic landmark | | ------------------------------------- | ----------------------- | | Create delivery with order reference | `VL01N` | | Process delivery due list | `VL10*` family | | Outbound Delivery Monitor | `VL06O` | | Display Sales Order and document flow | `VA03` | Public Cloud uses role-specific Fiori apps and background processing rather than assuming the same transaction set. --- ## 3. Delivery Creation, Combination, and Split ### 3.1 Delivery creation Delivery creation copies and determines data into a new business document. It does not turn a Sales Order item into a delivery row. ```text Due predecessor item/schedule quantity + copy-control requirements + delivery type and item behavior + combination/split criteria + runtime determinations = Outbound Delivery header and items ``` The new delivery has its own identity, ownership, authorization, status, change restrictions, and reversal path. ### 3.2 Many predecessors can combine Compatible Sales Order items can be grouped into one delivery when all combination-relevant values permit it. ```text Order A / Item 10 ─┐ ├──> Delivery 800001 Order B / Item 20 ─┘ ``` Typical commonality requirements include the same Shipping Point and Ship-to Party, plus compatible route, delivery timing, and other delivery-header data. The exact split-relevant set depends on process and release. ### 3.3 One predecessor can split ```text Sales Order Item 10 ├── Delivery 800001 for 6 EA └── Delivery 800025 for 4 EA ``` Split causes can include: - different Shipping Points; - different Ship-to Parties or addresses; - incompatible routes or delivery dates; - different delivery types or header-relevant data; - capacity, warehouse, or business-process decisions; - custom split logic or enhancements. The correct diagnostic action is to compare the actual split-relevant values and application split analysis—not guess from document count. ### 3.4 Copy control Copy control governs whether and how predecessor data is transferred to a successor. It can include: - permitted source/target document combinations; - header- and item-level copy requirements; - data-transfer routines; - quantity and completion behavior; - document-flow updates. Common classic landmarks include: | Flow | Classic transaction | | ------------------------------- | ------------------- | | Sales document → Sales document | `VTAA` | | Sales document → Delivery | `VTLA` | | Sales document → Billing | `VTFA` | | Delivery → Billing | `VTFL` | | Billing → Billing | `VTFF` | Copy control is not a database-copy command. It is application configuration executed during successor creation. --- ## 4. Outbound Delivery Data Model ### 4.1 Header and item grain ```text LIKP — Outbound Delivery header key: VBELN │ └── LIPS — Outbound Delivery item key: VBELN + POSNR ``` Representative fields include: | Meaning | Classic clue | Grain | | ---------------------- | ---------------------------------- | --------------------------------------------------- | | Delivery type | `LIKP-LFART` | Header | | Shipping Point | `LIKP-VSTEL` | Header result; derived from compatible item context | | Planned GI date | `LIKP-WADAT` | Header expectation | | Actual GI date | `LIKP-WADAT_IST` | Header posting result clue | | Delivery item category | `LIPS-PSTYV` | Item | | Delivery quantity | `LIPS-LFIMG` with unit | Item | | Picked quantity | `LIPS-PIKMG` with its unit context | Item | | Movement type proposal | `LIPS-BWART` | Item posting instruction | | Immediate predecessor | `LIPS-VGBEL + LIPS-VGPOS` | Item source reference | `LF` is a common standard delivery type and `601` a common sell-from-stock goods issue movement type. Both are configurable examples, not universal constants. ### 4.2 Direct predecessor versus document flow ```text LIPS-VGBEL / VGPOS → immediate source document/item copied into this delivery item VBFA → broader predecessor/successor graph across SD document categories ``` The direct reference and document-flow graph have related but different purposes. A robust trace can use both. ### 4.3 Delivery control configuration Common classic landmarks include: | Purpose | Transaction | Configuration clue | | ----------------------------------- | ----------- | ------------------------------------------ | | Define delivery type | `OVLK` | delivery-header behavior | | Define delivery item category | `OVLP` | delivery-item behavior | | Shipping Point determination | `OVL2` | Plant + shipping condition + loading group | | Sales order → delivery copy control | `VTLA` | source/target copying behavior | The selected delivery type and item category are transaction data. The maintenance transactions define reusable behavior. --- ## 5. Picking, Packing, and Warehouse Execution ### 5.1 Different execution facts | Activity | Business meaning | Technical result | | ---------------- | --------------------------------------------------------- | ---------------------------------------------------------------------- | | Picking | Remove and stage required stock from a warehouse location | Picking quantity/status or warehouse-task confirmation | | Packing | Assign products to physical shipping units | Handling Units and packaging relationships | | Loading/shipping | Prepare transport departure | Delivery/shipment execution state according to process | | PGI | Record goods departure in Inventory Management | Material document, status, date, and accounting effects where relevant | Packing is not required in every process. Picking can be controlled in the delivery directly, through Lean Warehouse Management, classic Warehouse Management, Stock Room Management, or Extended Warehouse Management. ### 5.2 Warehouse architecture changes the route ```text Simple delivery execution Delivery → record picking → PGI EWM-managed execution LE delivery → EWM delivery objects → warehouse tasks → pick/pack/stage → EWM goods issue → confirmation to LE delivery and ERP postings ``` The exact document chain differs, but the boundary remains the same: warehouse task completion and picking status are not themselves Inventory Management goods-issue posting. ### 5.3 Handling Units A Handling Unit combines packaging material with packed goods. Classic persistence landmarks include `VEKP` for HU header and `VEPO` for HU items, but their use depends on scenario and architecture. ```text Delivery item quantity └── packed into Handling Unit ├── packaging material ├── contained product quantity └── identification/status ``` Use supported HU and warehouse APIs for integration. Direct table updates cannot safely maintain nested packing, status, serial/batch, and warehouse relationships. ### 5.4 Picking status versus goods-movement status | Status family | Header clue | Item clue | Meaning | | -------------- | ------------ | ------------ | ----------------------- | | Picking | `LIKP-KOSTK` | `LIPS-KOSTA` | Picking progress | | Goods movement | `LIKP-WBSTK` | `LIPS-WBSTA` | Goods-movement progress | ```text Picking complete + goods movement not started ``` is a valid intermediate state. It proves warehouse staging but not stock posting. --- ## 6. Post Goods Issue ### 6.1 PGI as the decisive posting boundary For a common delivery-related sell-from-stock process, PGI records that the goods left the company and produces the Inventory Management posting. ```text Before PGI Delivery exists Quantity can be picked and packed Movement type is only an instruction After successful PGI Material document exists Delivery goods-movement state is updated Actual GI date is recorded Inventory quantity is reduced Relevant inventory-value/accounting effects exist Delivery-related billing can normally continue ``` PGI must be executed through the application operation. Writing the actual GI date or goods-movement status would not create the material and accounting documents. ### 6.2 Typical accounting effect For a valuated stock sale, a simplified posting is: ```text Debit Cost of Goods Sold Credit Inventory ``` Actual accounts and controlling/profitability effects depend on valuation, movement type, account determination, account assignment, ledger design, and process variant. The example is conceptual, not a universal journal template. PGI accounting and billing accounting are separate: ```text PGI posting inventory and cost-side effect Billing posting customer receivable, revenue, and tax-side effect ``` ### 6.3 Proof hierarchy | Observation | Evidential strength | | ------------------------------------------------- | ------------------------------------------------ | | Delivery exists | proves delivery creation only | | Picked quantity complete | proves picking state only | | Movement type `601` present | proves proposed/configured posting behavior only | | Actual GI date and completed goods-movement state | strong delivery-side evidence | | Related material document and line item | decisive posting evidence | | Consistent inventory and accounting effects | corroborating cross-component evidence | A successful UI message or HTTP status should be correlated with the resulting business-document identity and state before downstream work is triggered. ### 6.4 Material-document persistence in S/4HANA ```text SAP ERP model MKPF material-document header MSEG material-document item SAP S/4HANA persistence MATDOC central material-document line-item persistence compatibility views preserve selected legacy read semantics ``` A common material-document identity uses document number, year, and item context. Use released material-document CDS views or APIs for clean-core access rather than binding new code to `MATDOC` layout. ### 6.5 PGI API operation In supported releases, `API_OUTBOUND_DELIVERY_SRV` exposes a `PostGoodsIssue` operation. SAP documents that the Delivery Document is mandatory and the current ETag is required. ```text GET delivery/current ETag → validate local intent → POST PostGoodsIssue with If-Match → inspect HTTP/business result → reread delivery and posting evidence ``` The ETag prevents a caller from posting against a stale delivery version. It does not replace business validation, authorization, idempotency, or posting evidence. --- ## 7. Reversing Goods Issue ### 7.1 Reversal preserves history If PGI data is wrong, the normal correction is: ```text Reverse PGI → create reversing material/accounting effects → restore delivery to an editable process state as permitted → correct delivery data → post PGI again ``` The classic landmark is `VL09`. Reversal does not delete the original posting or rewrite history. It creates compensating evidence and updates process state. ### 7.2 Reversal dependency checks Later documents can restrict reversal. Before reversing PGI, inspect: - subsequent Billing Documents; - warehouse/EWM state; - period and posting-date controls; - batch, serial number, and stock availability implications; - authorization and business-process restrictions. If billing already exists, the required sequence commonly starts by canceling the downstream billing result before reversing PGI. The precise sequence is process- and configuration-dependent. ### 7.3 Reversal is not negative direct SQL ```text Original posting + reversal posting = auditable correction chain Direct overwrite/delete = lost lineage and inconsistency ``` This pattern repeats in billing and FI clearing. --- ## 8. Billing Eligibility and Creation ### 8.1 Order-related and delivery-related billing ```text Order-related billing Sales Order item → Billing Document Delivery-related billing Outbound Delivery item → Billing Document ``` The Item Category, billing relevance, copy control, process status, quantity, and billing block determine how an item participates. Physical products are commonly delivery-related; services and other processes can be order-related. ### 8.2 Billing due processing Typical eligibility evidence includes: - billing relevance of the source item; - billable quantity or value; - required predecessor processing state; - billing date in the selection horizon; - no effective billing block; - complete required billing data; - no existing successor already consuming the billable basis. Classic landmarks: | Operation | Transaction | | --------------------------------- | ----------- | | Create Billing Document | `VF01` | | Process billing due list | `VF04` | | Background billing | `VF06` | | Display Billing Document | `VF03` | | Display blocked billing documents | `VFX3` | ### 8.3 Billing combination and split Compatible source items can combine into one Billing Document. Differences in billing-header criteria can cause a split, for example payer, billing date, payment terms, destination country, Incoterms, or other configured data. ```text Several deliveries ──compatible billing data──> one invoice One delivery ──incompatible billing data──────> several invoices ``` Use Billing Split Analysis and compare actual header-relevant values. Do not assume one delivery must always create one invoice. ### 8.4 Billing copy control and pricing `VTFL` commonly maintains Delivery-to-Billing copy control, while `VTFA` maintains Sales-Document-to-Billing copy control. Copy control can govern: - source and target document combinations; - copying requirements and data-transfer routines; - quantity/value basis; - pricing type and repricing behavior; - update of document flow. A Billing Document may copy or redetermine pricing according to the pricing type. Its result therefore need not be numerically identical to the Sales Order pricing result. --- ## 9. Billing Data Model and Cancellation ### 9.1 Persistence grain ```text VBRK — Billing Document header key: VBELN │ └── VBRP — Billing Document item key: VBELN + POSNR ``` Related landmarks include: | Object | Purpose | | ----------------- | ----------------------------------------------------- | | `VBPA` | Billing-document partner rows among other SD partners | | `VBFA` | Predecessor/successor document flow | | `PRCD_ELEMENTS` | S/4HANA document pricing-result rows | | `BKPF` / `ACDOCA` | Accounting header/context and Universal Journal lines | The repeated field `VBELN` is scoped by table and document category. A Sales Order number, delivery number, and billing number are different identities even where field names are shared. ### 9.2 Billing type and account determination Common classic configuration landmarks include: | Purpose | Transaction | | ------------------------------------- | ----------- | | Define Billing Types | `VOFA` | | Delivery → Billing copy control | `VTFL` | | Sales document → Billing copy control | `VTFA` | | Revenue account determination | `VKOA` | Revenue account determination commonly combines organizational and account- assignment context such as: ```text Chart of accounts + Sales Organization + customer account-assignment group + material account-assignment group + account key from pricing procedure = G/L account ``` The actual access combination and result are configuration-dependent. Typical master-data clues include `KNVV-KTGRD` for customer account-assignment group and `MVKE-KTGRM` for material account-assignment group. ### 9.3 Typical billing accounting effect For a normal customer invoice, a simplified view is: ```text Debit Customer receivable Credit Revenue Credit Output tax, where applicable ``` Saving a standard billing document commonly transfers data to Financial Accounting automatically. Exceptions include pro forma documents, posting blocks, account-determination failures, closed periods, and other process controls. Billing-document existence alone therefore does not prove successful FI transfer. ### 9.4 Billing cancellation The classic transaction is `VF11`. Cancellation creates a cancellation Billing Document; it does not delete the original invoice. ```text Original Billing Document → Cancellation Billing Document → offsetting FI entry when accounting transfer applies → predecessor can become open for correct rebilling ``` SAP's Billing Document API also exposes a cancellation action in supported releases and requires ETag handling. A cancellation response must be correlated with the cancellation document and accounting status. --- ## 10. Financial Accounting and Incoming Payment ### 10.1 Billing creates a receivable, not payment ```text Billing posting → customer open item / receivable Incoming payment → cash or bank-clearing posting → matching and clearing against open item ``` The Sales Order does not become “paid” by receiving a field update from FI. Payment and clearing are Financial Accounting transactions with their own document identities and states. ### 10.2 Common payment outcomes | Outcome | Meaning | | -------------------- | ------------------------------------------------------------------------------ | | Full clearing | Payment settles the selected receivable completely | | Partial payment | Payment is posted while the original invoice remains open according to process | | Residual item | Original item is cleared and a new residual open item is created | | On-account payment | Payment is posted without immediate invoice matching | | Difference/write-off | Configured tolerance or reason handling resolves a difference | One payment can clear multiple invoices, and one invoice can be settled by multiple payment-related postings. The relationship is not inherently one-to- one. ### 10.3 Classic navigation | Purpose | Common classic landmark | | ------------------------------------ | ------------------------------------------------------ | | Display accounting document | `FB03` | | Display customer line items | `FBL5N` | | Post incoming payment manually | `F-28` | | Electronic bank statement processing | release/process-specific applications and transactions | ### 10.4 Clearing evidence ```text Billing Document → accounting document reference → customer receivable line → clearing document/date or remaining open state → payment/bank posting ``` Payment status in an SD-oriented report should be derived from an authorized, documented FI source or released API/CDS model. A custom Boolean copied into an order can become stale and cannot represent partial or residual settlement. --- ## 11. Document Flow and Status Architecture ### 11.1 The process is a graph ```text Sales Order Item 10 ├── Delivery A → Material Document A → Invoice A └── Delivery B → Material Document B → Invoice B Invoice A ├── Payment 1 └── Cancellation or credit branch, when applicable ``` Several Sales Orders can also combine into one delivery or invoice. Order-to- Cash cannot be represented reliably as one foreign-key chain with one status. ### 11.2 `VBFA` as the SD relationship landmark Representative fields include: | Field | Meaning | | ------------------------ | ---------------------------------------- | | `VBELV` | Preceding SD document | | `POSNV` | Preceding item | | `VBELN` | Subsequent SD document | | `POSNN` | Subsequent item | | document-category fields | Classify predecessor and successor types | | `STUFE` | Document-flow level context | S/4HANA extended document-category semantics and simplified `VBFA`. New code should not hard-code old one-character assumptions without checking the target release. ### 11.3 Status is compressed evidence Overall statuses answer whether processing is open, partial, complete, or not relevant according to application rules. They do not explain the cause. ```text Overall status → item statuses → source and successor quantities → document-flow edges → posting documents ``` S/4HANA moved many SD status fields from separate `VBUK`/`VBUP` persistence into relevant document header/item tables. Compatibility artifacts can still surface legacy names. Released CDS/API status fields are safer extension contracts. ### 11.4 Reversed documents remain evidence Reversal and cancellation append corrective documents and status transitions. Reports must decide deliberately whether to show: - gross posted quantity/value; - reversing quantity/value; - net current effect; - original and reversal identities; - current process eligibility. Deleting reversed rows from a dataset can hide audit history; counting both as positive can overstate activity. --- ## 12. Cross-Component Persistence Map | Boundary | Header/primary landmark | Item/detail landmark | Native grain | | ---------------------------- | ----------------------- | -------------------------------------- | --------------------------------------- | | Sales Order | `VBAK` | `VBAP`, `VBEP` | order; item; schedule line | | Outbound Delivery | `LIKP` | `LIPS` | delivery; delivery item | | SD document flow | — | `VBFA` | predecessor/successor item relationship | | Handling Unit | `VEKP` | `VEPO` | HU; packed item | | Material document in S/4HANA | — | `MATDOC` | material-document line | | Billing Document | `VBRK` | `VBRP` | billing header; billing item | | Pricing result | — | `PRCD_ELEMENTS` | pricing document/item/step/counter | | Accounting | `BKPF` context | `ACDOCA`; classic views such as `BSEG` | journal-entry line | | IDoc | `EDIDC` | `EDID4`, `EDIDS` | message control; segment; status event | These tables do not form one safe flat join. Document categories, fiscal year, Company Code, item numbers, units, currencies, and one-to-many relationships must be respected. ### 12.1 Grain-safe reporting ```text Delivery item → may have several document-flow edges → may have several material-document lines → may contribute to several billing items Naive join → row multiplication → repeated quantities and values ``` Safe design: 1. Choose one output grain. 2. Aggregate each child source to that grain. 3. Preserve units, currencies, reversal signs, and relevance rules. 4. Join summarized results. 5. Reconcile against application totals. --- ## 13. Classic Transaction and Configuration Map These are on-premise/private-edition landmarks. Availability depends on release, role, activated scope, and warehouse architecture. ### 13.1 Operational transactions | Area | Common transaction | | ------------------------------ | --------------------------- | | Sales Order display | `VA03` | | Delivery create/change/display | `VL01N` / `VL02N` / `VL03N` | | Delivery due processing | `VL10*` | | Outbound Delivery Monitor | `VL06O` | | Reverse goods issue | `VL09` | | Billing create/change/display | `VF01` / `VF02` / `VF03` | | Billing due list | `VF04` | | Cancel Billing Document | `VF11` | | Display accounting document | `FB03` | | Display customer line items | `FBL5N` | | Post incoming payment | `F-28` | ### 13.2 Configuration transactions | Area | Common transaction | Responsibility | | ------------------------------- | ------------------ | ------------------------------------------------------------------ | | Shipping Point determination | `OVL2` | Plant + shipping condition + loading group result | | Delivery type | `OVLK` | Header-level delivery behavior | | Delivery item category | `OVLP` | Item-level delivery behavior | | Sales → Delivery copy control | `VTLA` | Eligibility and data transfer | | Delivery → Billing copy control | `VTFL` | Billing basis, routines, pricing type | | Sales → Billing copy control | `VTFA` | Order-related billing transfer | | Billing type | `VOFA` | Billing-header behavior and cancellation relation | | Revenue account determination | `VKOA` | Pricing/account-assignment context to G/L account | | Movement type control | `OMJJ` | Inventory movement behavior; cross-process impact requires caution | Always begin from the IMG activity and business requirement. Transaction codes are navigation shortcuts, not a substitute for configuration design and transport governance. --- ## 14. Missing Delivery Diagnostic Flow ### 14.1 Evidence sequence ```text Exact Sales Order item → item/schedule delivery relevance → confirmed quantity and requested/confirmed date → open quantity after existing successors → Plant, Shipping Point, route, and due-list selection → rejection, completion, block, and incompletion → copy-control requirement → application log and authorization → enhancements only after standard evidence ``` ### 14.2 Common cause classes | Cause class | Evidence | | -------------------------- | --------------------------------------------- | | Not due | relevant date outside selection horizon | | No open confirmed quantity | schedule-line and successor quantities | | Not delivery relevant | Item/Schedule-Line Category control | | Blocked or rejected | document/item/schedule state | | Missing shipping data | Plant, Shipping Point, route, partner/address | | Already processed | document flow and existing delivery quantity | | Copy requirement failed | copy-control routine and runtime data | | Authorization/job issue | application log, job log, authorization trace | Do not change due-list configuration merely because one item is absent. First prove the exact failing eligibility condition. --- ## 15. Unexpected Delivery Split Diagnostic Flow ```text 1. Identify all resulting delivery numbers and source items 2. Confirm quantities and source references 3. Compare Shipping Point and Ship-to Party/address 4. Compare route, delivery date, delivery type, and header-relevant values 5. Use available split analysis or application log 6. Verify copy-control and combination rules 7. Inspect warehouse/capacity process decisions 8. Investigate custom split logic only after the differing field is known ``` The strongest finding names the exact value that prevented combination: ```text Source Item A: Shipping Point 1000 Source Item B: Shipping Point 2000 Result: separate delivery headers required ``` “SAP decided to split” is not a technical root cause. --- ## 16. PGI Failure Diagnostic Flow ```text Delivery and exact item → picking/warehouse completion → delivery quantity, unit, batch, serial, stock type → Plant, storage location, movement type → posting date and open period → stock and negative-stock rules → account determination and valuation → delivery and goods-movement status → warehouse/EWM queues and application logs → authorization trace → custom code last ``` ### 16.1 Failure families | Failure family | Typical evidence | | --------------------- | -------------------------------------------------------------------- | | Warehouse incomplete | open warehouse tasks or picking status | | Quantity mismatch | delivery, picking, base-unit, or batch quantity conflict | | Master-data issue | missing valuation, serial/batch, storage, or account-assignment data | | Posting-period issue | FI/MM period or posting date message | | Stock issue | insufficient relevant stock or stock-type mismatch | | Account determination | missing G/L account or valuation combination | | Lock/concurrency | enqueue or stale ETag conflict | | Integration | queue, API, IDoc, tRFC, or middleware error | The exact message class, number, variables, application log, and document state are evidence. A paraphrase such as “PGI failed” is only the symptom. --- ## 17. Billing and Payment Diagnostic Flows ### 17.1 Source absent from billing due list ```text Source document/item → billing relevance and billing basis → required predecessor state → billable quantity/value → billing date and due-list horizon → billing block/incompletion → existing successor Billing Documents → VTFA or VTFL copy requirement → application log and authorization ``` ### 17.2 Billing Document exists but FI document is missing ```text Billing Document and posting status → pro forma versus accounting-relevant billing type → account-determination result in VKOA → customer and material account-assignment groups → posting date and FI period → tax and G/L account configuration → accounting interface/application log → correction and authorized release/reprocessing path ``` ### 17.3 Billing exists but receivable remains open ```text Billing → FI accounting document → customer line item → payment document → clearing document/date → partial/residual/on-account outcome → payer, currency, amount, reference, and tolerance ``` The open item may be correct because payment has not arrived, was posted on account, was only partial, or matched a different receivable. --- ## 18. Integration Contract Selection ### 18.1 Contract comparison | Contract | Style | Appropriate use | Main technical concerns | | -------------- | ---------------------------------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------- | | BAPI | Synchronous business operation, commonly RFC-enabled | Classic SAP-to-SAP or application call in supported systems | return messages, LUW ownership, commit, release status | | IDoc | Persisted asynchronous business message | Decoupled ALE/EDI and middleware exchange | statuses, retries, duplicates, partner profile, monitoring | | OData/REST API | Synchronous HTTP service contract | Cloud-ready transactional/read integration | authentication, CSRF, ETag, batching, version, business errors | | SOAP API | Contract-first service | Enterprise integrations where delivered | reliable messaging, faults, version, communication arrangement | | Business event | Asynchronous notification | Inform consumers that a business fact occurred | delivery guarantee, duplicate events, state retrieval, ordering | | CDS view | Semantic read model for supported capability | Read, analytics, extraction where released | authorization, extraction delta, grain, not a write API | ### 18.2 BAPI versus RFC RFC is the remote-call mechanism. A BAPI is a business-oriented method/API contract that is often implemented through an RFC-enabled function module. ```text RFC → how an ABAP callable unit can be invoked remotely BAPI → released/stable business operation in the classic Business Object model ``` A common classic Sales Order creation BAPI is `BAPI_SALESORDER_CREATEFROMDAT2`. Its availability does not automatically make it the preferred clean-core interface for every S/4HANA edition. Typical call responsibility: ```text Call BAPI → inspect every RETURN/BAPIRET2 message → treat error/abort messages as failure → call BAPI_TRANSACTION_COMMIT with WAIT on success → call BAPI_TRANSACTION_ROLLBACK on failure when appropriate → store returned business-document identity ``` Do not commit inside a reusable helper without an explicit transaction- ownership decision. The caller may need several operations in one SAP LUW. ### 18.3 API concurrency and evidence Released delivery and billing operations can require ETags. The correct flow is: ```text Read current representation and ETag → construct operation from current state → send If-Match and CSRF token as required → interpret HTTP and business error payload → persist correlation key → reread or consume event to confirm final state ``` HTTP `2xx` proves acceptance/success according to that API operation; it does not by itself replace the business evidence required by the application. Some operations return an empty body, making the correlation and reread especially important. --- ## 19. IDoc Architecture ### 19.1 Message Type, Basic Type, and extension ```text Message Type business meaning, such as order or invoice Basic Type hierarchical technical segment structure Extension customer-specific additional segments attached to a Basic Type ``` Common SD-oriented Message Type examples include: | Business exchange | Common Message Type example | | ----------------------------- | --------------------------- | | Order | `ORDERS` | | Order response | `ORDRSP` | | Advance shipping notification | `DESADV` | | Invoice | `INVOIC` | Basic Type versions such as `ORDERS05`, `DELVRY...`, or `INVOIC02` depend on the scenario, partner, release, and mapping contract. Message Type and Basic Type must not be used as synonyms. ### 19.2 Runtime records | Record | Classic table | Purpose | | -------------- | ------------- | --------------------------------------------------------------------- | | Control record | `EDIDC` | sender, receiver, Message Type, Basic Type, direction, current status | | Data records | `EDID4` | ordered segment payload instances | | Status records | `EDIDS` | append-only processing history and messages | ```text One EDIDC control record ├── many EDID4 segment records └── many EDIDS status-history records ``` An IDoc is an integration document, not the Sales Order, delivery, or invoice it may create. The application document has a separate identity. ### 19.3 Outbound flow ```text Application/output/change event → build IDoc control and data records → check WE20 outbound partner profile → resolve WE21 port/transport → dispatch through tRFC/qRFC/file/middleware path → record status history → receiver processes business message ``` ### 19.4 Inbound flow ```text Sender/middleware → IDoc received and persisted → partner/message profile recognized → inbound process code resolves processing logic → application function executes → business document created or application error recorded → IDoc status appended ``` SAP explicitly separates receipt/persistence of an inbound IDoc from later application processing. Successful technical receipt is therefore not proof that the Sales Order or other application document was posted. ### 19.5 Configuration and monitoring landmarks | Transaction | Purpose | | --------------- | --------------------------------------------------------- | | `WE20` | Partner profiles and inbound/outbound parameters | | `WE21` | Ports and technical transport destination | | `WE30` | IDoc Basic Type structure | | `WE31` | Segment type definition | | `WE42` | Inbound process code | | `WE57` | Function Module, Message Type, and Basic Type assignment | | `WE02` / `WE05` | Display and search IDocs/status history | | `BD87` | Controlled reprocessing of eligible IDocs | | `WE19` | Test tool; use only in a safe non-production test context | | `SM58` | tRFC backlog/error monitoring | | `SMQ1` / `SMQ2` | outbound/inbound qRFC queue monitoring | | `SLG1` | application-log analysis where the process writes logs | Common status examples include: | Status | Common meaning | | ------ | ------------------------------------------------ | | `03` | Outbound data passed to port | | `02` | Outbound error passing data to port | | `64` | Inbound IDoc ready for application processing | | `53` | Inbound application document posted successfully | | `51` | Inbound application posting error | Status meanings should be confirmed in the target system and scenario. Status `53` is strong IDoc-side evidence of successful application processing, but the created application-document identity should still be captured. ### 19.6 Safe reprocessing ```text Failed IDoc → inspect current and previous statuses → read exact application message → correct root cause in master data/configuration/application → assess duplicate/idempotency risk → reprocess through supported tool → confirm new status and business document ``` Never edit `EDIDC`, `EDID4`, or `EDIDS` directly to make a message appear successful. Repeated processing can create duplicate business documents unless the receiving logic and business keys are idempotent. --- ## 20. Integration Observability and Failure Isolation ### 20.1 Four failure domains ```text Caller/application request construction, mapping, credentials │ Transport/middleware HTTP, RFC, queue, routing, transformation │ SAP interface layer service activation, partner profile, deserialization, authorization │ SAP business application master data, configuration, validation, lock, posting, account determination ``` The same user symptom can originate in any domain. Record correlation IDs and business keys across all layers. ### 20.2 Minimum integration evidence ```text Source business key Interface contract and version Correlation/message/IDoc identifier Request timestamp and sender/receiver Sanitized request or mapped business fields Transport response/status SAP business messages Created or changed document identity Final application state/posting evidence Retry/reversal history ``` ### 20.3 Technical success versus business success | Observation | Interpretation | | ------------------------------------------ | ---------------------------------------------------------- | | HTTP connection succeeded | transport reached endpoint | | HTTP `2xx` returned | operation succeeded/was accepted according to API contract | | IDoc received | integration document persisted | | IDoc status `53` | inbound application processing reported success | | Business document number returned | application object identity exists | | Posting document and final state confirmed | decisive business boundary completed | An integration monitor should expose both technical status and business result. --- ## 21. RAP Portfolio and Standard SD Boundary ### 21.1 Aggregate ownership ```text Custom SalesOrderRequest BO ├── Items ├── Schedules └── OrderPartners Standard S/4HANA Sales Order ── independent aggregate Standard Outbound Delivery ── independent aggregate Material Document, Billing Document, FI documents ── separate postings/aggregates ``` Do not place Delivery, Billing, and Payment beneath the custom request as RAP composition children. They have separate identities, authorization, posting, retention, and reversal lifecycles. ### 21.2 Honest integration state model ```text Draft → Submitted → HandoffPending → HandoffSucceeded → ExternalOrderCreated → FulfillmentInProgress → Fulfilled / Failed / Reversed ``` The exact states should be based on events the custom application can prove. If the portfolio does not call a real released PGI operation, label the action as simulated fulfillment or handoff—not `PostGoodsIssue`. ### 21.3 Adapter boundary ```text RAP action SubmitToS4 → outbound port/interface → adapter maps custom request to released API contract → adapter records correlation and external identity → callback/event/polling updates integration projection ``` The domain logic should depend on a narrow port such as “submit order request” rather than on generated OData field names, BAPI structures, or IDoc segments. ### 21.4 Transaction boundary The local RAP save and remote S/4HANA transaction cannot usually be one atomic database transaction. ```text Local commit succeeds + remote call fails → recoverable integration state and retry required Remote creation succeeds + response is lost → idempotent lookup/correlation required before retry ``` Use an outbox/event or controlled orchestration approach when reliability matters. Never solve distributed failure by holding a database lock around a long remote call. --- ## 22. Clean-Core and Security Rules ### 22.1 Prohibited write shortcuts Do not directly update: ```text LIKP / LIPS VBFA MATDOC VBRK / VBRP PRCD_ELEMENTS BKPF / BSEG / ACDOCA EDIDC / EDID4 / EDIDS ``` These objects participate in application invariants, postings, status, document flow, output, change tracking, and integration. ### 22.2 Released contract selection Before selecting an API or CDS entity, verify: - API State/release status in the target system; - supported operation and business scenario; - communication scenario and authorization requirements; - edition and minimum release; - ETag, CSRF, batch/change-set, and error semantics; - update versus read-only capability; - rate, payload, and extensibility limitations. ### 22.3 Authorization layers ```text Business authorization operation allowed for user and organizational context Communication authorization technical client may call service/partner profile Data authorization caller may read the requested business data State/feature control operation permitted for current document state ``` A technically authenticated API client can still be correctly rejected by business authorization or document state. ### 22.4 Sensitive operational data Integration traces can contain customer data, addresses, prices, bank references, tokens, and internal identifiers. Store sanitized payloads where possible, restrict monitor access, and avoid copying secrets or full personal data into application logs. --- ## 23. Technical Insights and Common Misinterpretations ### 23.1 Delivery is execution, but not posting An Outbound Delivery is more than a plan because it owns warehouse/shipping execution. Its existence still does not prove PGI. ### 23.2 Picking and packing are operational states They prepare goods for dispatch. Neither reduces Inventory Management stock by itself. ### 23.3 Movement type is instruction, not evidence `LIPS-BWART = 601` can explain expected posting behavior. Only the executed material document proves the goods issue. ### 23.4 Billing and payment belong to different components Billing creates the customer invoice and normally the receivable. Incoming payment and clearing belong to FI and can have partial, residual, or on-account states. ### 23.5 Cancellation and reversal preserve audit history Corrective documents offset earlier effects. They do not erase the original transaction. ### 23.6 IDoc success is not transport success alone Inbound receipt, application posting, and resulting business-document identity are distinct checkpoints. An outbound sender status also cannot prove how the receiver completed its business process. ### 23.7 API success needs correlation Record the external document key and reread the resulting state. This protects against lost responses, duplicate retries, and false assumptions about posting. ### 23.8 Document flow is not composition Sales Order, Delivery, Material Document, Billing Document, and Payment are independent objects linked by reference and process flow. Deleting a root must not cascade across those legal and accounting records. ### 23.9 Status is navigation, posting document is proof Status accelerates selection and diagnosis. Posting documents and their reversal chain provide stronger event evidence. --- ## 24. Compact Technical Map ```text FULFILLMENT Sales Order item/schedule line delivery relevance + confirmed open quantity + due date + no block │ ▼ Delivery creation VTLA copy control + split/combination rules │ ▼ LIKP delivery header / LIPS delivery item pick → pack → warehouse execution │ ▼ PGI operation actual GI date + goods-movement status MATDOC material-document line inventory and relevant accounting effect BILLING AND FINANCE Delivery or Sales Order billable item VTFL or VTFA copy control + billing relevance + no block │ ▼ VBRK billing header / VBRP billing item PRCD_ELEMENTS pricing result │ ▼ VKOA revenue account determination FI journal entry / customer receivable │ ▼ Incoming payment full / partial / residual / on-account clearing state PROCESS LINEAGE VBFA predecessor/successor graph direct source references + statuses + reversal documents INTEGRATION BAPI synchronous classic business operation IDoc persisted asynchronous business message OData/API released HTTP operation with ETag/CSRF where required Event asynchronous notification followed by state retrieval Every path records correlation key → business document → final state → reversal/retry evidence ``` The map should be read boundary by boundary. At each transition, distinguish configuration that permits an operation, transaction state that prepares it, the application operation that executes it, and the document that proves its business effect. 41:T98d,SAP SD Fulfillment, Posting, and Integration — Technical Reference This document explains the technical execution path from a delivery-relevant Sales Order through Outbound Delivery, picking, packing, Post Goods Issue (PGI), billing, accounting, payment clearing, and external integration. It connects business-document boundaries to configuration, persistence, application logs, interfaces, reversals, diagnostic evidence, and clean-core extension design. The central technical principle is: A planned or created document proves intent at its own boundary. Only the corresponding posting document and consistent process state prove that a physical or financial event occurred. This reference distinguishes three environments: - SAP S/4HANA on-premise or private edition, where SAP GUI transactions, IMG activities, and authorized persistence inspection are common diagnostic tools. - SAP S/4HANA Cloud Public Edition, where Fiori applications, configuration activities, released APIs, and communication arrangements are the normal operational contracts. - Clean-core extension development, where internal SD, MM, and FI tables are diagnostic landmarks—not write interfaces or lifecycle-stable APIs. Primary SAP sources: - SAP Learning — Processing Outbound Deliveries - SAP Learning — Posting a Goods Issue - SAP Help — Shipping Points - SAP Help — Goods Issue - SAP Help — Outbound Delivery API Operations - SAP Learning — Billing and Integration to SAP S/4HANA Finance - SAP Help — Canceling Billing Documents - SAP Help — IDoc Inbound Processing --- 1. Execution Boundaries 1.1 Baseline sell-from-stock flow text Sales Order accepted demand and commercial intent │ ▼ Outbound Delivery shipping execution object │ ├── picking ├── packing └── warehouse execution │ ▼ Post Goods Issue inventory and relevant value posting │ ▼ Billing Document customer invoice and FI transfer │ ▼ Incoming Payment and Clearing cash receipt and receivable settlement This is a baseline, not a universal sequence. Third-party sales, services, intercompany processing, consignment, returns, pro forma billing, EWM-managed warehouses, and other scenarios use different branches. 1.2 Each boundary proves one fact | Evidence | Fact established | Fact not established | | ---------------------------- | ------------------------------------------ | ---------------------------------------- | | Sales Order exists42:Td67,# SAP SD Fulfillment, Posting, and Integration — Technical Reference This document explains the technical execution path from a delivery-relevant Sales Order through Outbound Delivery, picking, packing, Post Goods Issue (PGI), billing, accounting, payment clearing, and external integration. It connects business-document boundaries to configuration, persistence, application logs, interfaces, reversals, diagnostic evidence, and clean-core extension design. The central technical principle is: > A planned or created document proves intent at its own boundary. Only the > corresponding posting document and consistent process state prove that a > physical or financial event occurred. This reference distinguishes three environments: - **SAP S/4HANA on-premise or private edition**, where SAP GUI transactions, IMG activities, and authorized persistence inspection are common diagnostic tools. - **SAP S/4HANA Cloud Public Edition**, where Fiori applications, configuration activities, released APIs, and communication arrangements are the normal operational contracts. - **Clean-core extension development**, where internal SD, MM, and FI tables are diagnostic landmarks—not write interfaces or lifecycle-stable APIs. Primary SAP sources: - [SAP Learning — Processing Outbound Deliveries](https://learning.sap.com/courses/configuring-delivery-processing-in-sap-s-4hana-sales/processing-outbound-deliveries) - [SAP Learning — Posting a Goods Issue](https://learning.sap.com/courses/configuring-delivery-processing-in-sap-s-4hana-sales/posting-a-goods-issue) - [SAP Help — Shipping Points](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/c7894a248ca14f74aca67f97528e5ad7/5d1bbf53d25ab64ce10000000a174cb4.html) - [SAP Help — Goods Issue](https://help.sap.com/docs/SAP_S4HANA_CLOUD/aff0b3f5f46c42a2b2c0fabfc233bab2/64f81a71edf5490ab522a829be075827.html) - [SAP Help — Outbound Delivery API Operations](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/2f36056ae9a044bba55bcbad204b7bc5/a4c5d84ecef2494985883829a24e393c.html) - [SAP Learning — Billing and Integration to SAP S/4HANA Finance](https://learning.sap.com/courses/exploring-sap-s-4hana-sales-essentials/executing-the-billing-process-and-the-integration-to-sap-s-4hana-finance_e2dd5db3-73c3-4cda-8ad5-1e7f39f04fba) - [SAP Help — Canceling Billing Documents](https://help.sap.com/docs/SAP_S4HANA_CLOUD/a376cd9ea00d476b96f18dea1247e6a5/2a70b6535fe6b74ce10000000a174cb4.html) - [SAP Help — IDoc Inbound Processing](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/7b24a64d9d0941bda1afa753263d9e39/4b4c8e091c300a93e10000000a421937.html) --- ## 1. Execution Boundaries ### 1.1 Baseline sell-from-stock flow ```text Sales Order accepted demand and commercial intent │ ▼ Outbound Delivery shipping execution object │ ├── picking ├── packing └── warehouse execution │ ▼ Post Goods Issue inventory and relevant value posting │ ▼ Billing Document customer invoice and FI transfer │ ▼ Incoming Payment and Clearing cash receipt and receivable settlement ``` This is a baseline, not a universal sequence. Third-party sales, services, intercompany processing, consignment, returns, pro forma billing, EWM-managed warehouses, and other scenarios use different branches. ### 1.2 Each boundary proves one fact43:Tb453, # SAP RAP Architecture and End-to-End Runtime — Technical Reference This document explains the architecture and runtime of the ABAP RESTful Application Programming Model (RAP). It traces metadata, read, and transactional requests through CDS, behavior, service exposure, the RAP transactional buffer, the save sequence, and database persistence. The central technical principle is: > CDS defines the semantic data model, the behavior definition declares the > transactional contract, the behavior pool implements application-specific > behavior, and the service layer exposes a consumer-specific projection. The > RAP runtime coordinates these artifacts as one business-object contract. This reference focuses on architectural responsibility and runtime flow. Detailed CDS modeling, EML syntax, draft, authorization, business-rule implementation, UI annotations, and testing are developed in the remaining documents of the RAP technical-reference set. Primary SAP sources: - [SAP Help — ABAP RESTful Application Programming Model](https://help.sap.com/docs/abap-cloud/abap-rap/abap-restful-application-programming-model) - [SAP Learning — Exploring the Concept and Architecture of RAP](https://learning.sap.com/courses/building-transactional-apps-with-the-abap-restful-application-programming-model/exploring-the-concept-and-architecture-of-rap) - [SAP Help — RAP BO Runtime](https://help.sap.com/docs/abap-cloud/abap-rap/rap-bo-runtime) - [SAP Help — RAP Business Object Contract](https://help.sap.com/docs/abap-cloud/abap-rap/rap-business-object-contract) - [SAP Help — Entity Manipulation Language](https://help.sap.com/docs/abap-cloud/abap-rap/entity-manipulation-language-eml) - [SAP Help — Business Service](https://help.sap.com/docs/abap-cloud/abap-rap/business-service) - [SAP Help — Service Definition](https://help.sap.com/docs/abap-cloud/abap-rap/service-definition) - [SAP Help — OData V4 Service Binding Editor](https://help.sap.com/docs/abap-cloud/abap-development-tools-user-guide/using-service-binding-editor-for-odata-v4-service) --- ## 1. RAP in One Architectural View ### 1.1 Design-time stack ```text Consumer Fiori elements / external API client / ABAP EML consumer │ ▼ Business service exposure Service Binding + Service Definition │ ▼ Consumer projection CDS Projection + Behavior Projection + Metadata Extension │ ▼ RAP Business Object CDS root/composition model + Base Behavior Definition │ ▼ Behavior implementation Behavior Pool: handlers and saver where implementation is required │ ▼ Persistence and external capabilities Database tables / released APIs / legacy implementation ``` The stack is not a sequence of duplicate models. Each layer makes a different decision: | Layer | Primary decision | | ------------------ | ------------------------------------------------------------ | | Persistence | Where durable state is stored | | CDS data model | What the business data means and how entities relate | | Base behavior | Which operations and transactional rules the BO supports | | Behavior pool | How application-specific operations and rules execute | | Projection | Which data and behavior one consumer may use | | Service definition | Which CDS entities form one business service | | Service binding | Which protocol and service category expose that service | | Metadata extension | How a metadata-driven UI presents the service | | Consumer | Which operations are requested and how results are displayed | ### 1.2 Runtime services supplied by RAP Depending on the implementation type and declared features, RAP can coordinate: - query processing and OData query options; - typed standard and custom operations; - transactional buffering; - optimistic and pessimistic concurrency; - authorization and feature control; - draft lifecycle; - determinations, validations, actions, and prechecks; - message propagation; - save-sequence orchestration; - OData exposure and metadata generation. RAP is therefore not only an OData generator. It is a business-object runtime and programming model whose operations can also be consumed locally through EML without HTTP. ### 1.3 Provider and consumer sides ```text BO provider defines CDS + behavior + implementation guarantees the business-object contract BO consumer invokes exposed operations through OData or EML depends on the projected or released contract ``` An OData client is one possible consumer. A behavior implementation can also consume its own BO through local EML, and one ABAP component can consume a released BO interface through EML. --- ## 2. RAP Business Object ### 2.1 Aggregate structure A RAP Business Object is an entity tree with one root and optional composed children. ```text SalesOrderRequest root entity ├── Items composition child │ └── Schedules composition child └── OrderPartners composition child Item ───────────── association ─────────> Product OrderPartner ───── association ─────────> BusinessPartner ``` Composition expresses lifecycle ownership inside the aggregate. Association expresses a relationship to an independently meaningful entity or BO. The root provides the aggregate entry point and coordinates transaction-level concerns such as locking, authorization dependency, draft ownership, and total ETag behavior according to the model. ### 2.2 Data contract plus behavior contract ```text CDS entity tree fields + keys + associations + compositions + semantics Base Behavior Definition operations + field control + locks + authorization + ETags + actions + determinations + validations + draft + mapping Together RAP Business Object contract ``` A CDS entity without transactional behavior can still support a read model. A transactional RAP BO needs a behavior definition that states which changes are legal and how the runtime should coordinate them. ### 2.3 Aggregate consistency The aggregate boundary determines which state should change consistently in a single BO transaction. For an order request: - an Item normally cannot exist without its Request; - deleting the Request normally removes its lifecycle-owned Items; - Product and Customer remain independent; - root and children can participate in one transactional buffer and save sequence. The boundary should follow business ownership rather than screen layout or foreign-key existence alone. --- ## 3. Repository Artifact Responsibilities ### 3.1 Persistence table The database table stores durable state. It does not itself define: - business names and semantic associations; - transactional operations; - authorization behavior; - draft lifecycle; - OData exposure; - Fiori presentation. ```abap define table zsor_request { key client : abap.clnt not null; key request_uuid : sysuuid_x16 not null; request_number : abap.char(10); sold_to_party : abap.char(10); status : abap.char(2); total_amount : abap.curr(15,2); transaction_currency : abap.cuky; local_last_changed_at : abp_locinst_lastchange_tstmpl; } ``` The table is persistence, not the public business API. ### 3.2 Base CDS entity The base CDS entity gives persistence business meaning and defines BO topology. ```abap define root view entity ZI_SalesOrderRequest as select from zsor_request as Request composition [0..*] of ZI_SalesOrderItem as _Items association [0..1] to ZI_CustomerReference as _Customer on $projection.SoldToParty = _Customer.CustomerID { key Request.request_uuid as RequestUUID, Request.request_number as RequestNumber, Request.sold_to_party as SoldToParty, Request.status as Status, @Semantics.amount.currencyCode: 'TransactionCurrency' Request.total_amount as TotalAmount, Request.transaction_currency as TransactionCurrency, Request.local_last_changed_at as LocalLastChangedAt, _Items, _Customer } ``` `ZI_` is a customer naming convention. The prefix does not create an interface contract or behavior by itself. ### 3.3 Base Behavior Definition The base BDEF declares the reusable BO's transactional capabilities. ```abap managed implementation in class zbp_i_salesorderrequest unique; strict ( 2 ); define behavior for ZI_SalesOrderRequest alias SalesOrderRequest persistent table zsor_request lock master authorization master ( instance ) etag master LocalLastChangedAt { create; update; delete; field ( readonly ) RequestUUID, TotalAmount; field ( mandatory : create ) SoldToParty; association _Items { create; } } ``` The BDEF says what exists in the BO contract. It does not make every capability available to every service consumer. ### 3.4 Behavior pool The behavior pool is the ABAP class pool associated with a behavior definition. Its local handler classes implement application-specific interaction logic such as actions, determinations, validations, authorizations, and feature control. Saver logic participates where the implementation scenario requires it. ```text Behavior Definition declares action Submit │ ▼ Behavior Pool handler method implements Submit business logic ``` The behavior pool is not a service and does not link HTTP directly to the BDEF. The RAP runtime dispatches BO operations to it according to the behavior contract. ### 3.5 CDS projection A CDS projection defines a consumer-specific data shape over the reusable model. ```abap define root view entity ZC_SalesOrderRequest provider contract transactional_query as projection on ZI_SalesOrderRequest { key RequestUUID, RequestNumber, SoldToParty, Status, TotalAmount, TransactionCurrency, _Items : redirected to composition child ZC_SalesOrderItem, _Customer } ``` Redirection keeps navigation within the projected topology. Without proper redirection, navigation can target the underlying model rather than the corresponding consumer projection. Redirection does not “copy data” and its absence does not universally mean that fields become blank. ### 3.6 Behavior projection The behavior projection exposes selected base-BO behavior to one consumer. ```abap projection; strict ( 2 ); define behavior for ZC_SalesOrderRequest alias SalesOrderRequest { use create; use update; use delete; use association _Items { create; } use action Submit; } ``` Custom business logic is not implemented in the behavior projection. It stays in the base BO's behavior pool so every permitted consumer receives the same invariants. ### 3.7 Metadata extension A metadata extension commonly holds UI vocabulary annotations separately from the core CDS model. ```abap @Metadata.layer: #CORE annotate entity ZC_SalesOrderRequest with { @UI.lineItem: [{ position: 10 }] @UI.identification: [{ position: 10 }] RequestNumber; } ``` Metadata can control presentation, field grouping, value help, and UI actions. It must not be the only enforcement point for business invariants. ### 3.8 Service definition The service definition chooses which CDS entities form the protocol-agnostic business service. ```abap @EndUserText.label: 'Sales Order Request Service' define service ZUI_SALES_ORDER_REQUEST { expose ZC_SalesOrderRequest as SalesOrderRequests; expose ZC_SalesOrderItem as SalesOrderItems; expose ZI_CustomerReference as Customers; expose ZI_ProductReference as Products; } ``` Reference entities are exposed when the consumer needs to address or query them—for example through value help or navigation. An association in CDS does not automatically guarantee that every target is available as an entity set in the service. ### 3.9 Service binding The service binding attaches a service definition to a concrete protocol and service category, such as: - OData V4 UI; - OData V4 Web API; - another binding type supported by the target platform. One service definition can support multiple bindings or service versions. The binding owns protocol-level exposure; it does not implement domain logic. ### 3.10 Fiori elements or API client Fiori elements interprets OData metadata and annotations to generate floorplan behavior. An external API client reads the service document and metadata to construct requests. Both are consumers: ```text Consumer requests operation → RAP BO enforces business behavior → consumer renders success, state, and messages ``` The UI can improve usability but cannot replace BO validation or authorization. --- ## 4. Three Runtime Paths RAP is easier to reason about when metadata, query, and transactional paths are separated. ```text Metadata path describe entities, fields, annotations, navigation, and operations Query path retrieve data with filtering, sorting, paging, search, and authorization Transactional path execute create/update/delete/action in a RAP LUW and save accepted changes ``` A single Fiori screen can use all three paths, but they do not execute the same runtime work. --- ## 5. Metadata Request Path ### 5.1 Flow ```text Fiori elements or API client requests $metadata │ ▼ OData service binding identifies protocol/service version │ ▼ Service definition identifies exposed CDS entities │ ▼ Projection CDS and Behavior Projection define exposed shape/capabilities │ ▼ CDS annotations and metadata extensions contribute vocabulary │ ▼ OData metadata document returned to consumer ``` The metadata describes fields, types, entity sets, associations/navigation, actions, capabilities, and annotations according to the exposed contract. ### 5.2 Metadata is descriptive, not transactional execution When Fiori elements renders a column because of `@UI.lineItem`, the annotation has influenced presentation. It has not read a database row or executed an amount calculation. Likewise, a value-help annotation describes lookup behavior. Backend validation must still protect the business rule against direct OData, EML, and other consumers. ### 5.3 Metadata troubleshooting boundary ```text Annotation source → active CDS/metadata extension → service metadata → Fiori metadata cache → rendered control ``` If the expected annotation is absent from `$metadata`, debugging the browser layout first is premature. --- ## 6. Managed Query Path ### 6.1 OData read flow ```text Client GET + $select / $filter / $orderby / $top / $skip / $expand │ ▼ Service binding parses the OData request │ ▼ Service definition and projection identify entity/query contract │ ▼ RAP query runtime interprets requested fields and query options │ ▼ CDS query + access control + supported query semantics │ ▼ Optimized database query │ ▼ OData response serialized to the client ``` For a normal CDS-based managed query, the framework generates and executes the database query. The behavior pool is not automatically called merely because a client reads a list. Additional behavior-related calls can still occur for requested functions, instance features, authorizations, draft state, messages, or other declared capabilities. ### 6.2 Pushdown The query runtime can translate supported OData options into database work: ```text $filter → SQL filter $orderby → database ordering $top → result limit $skip → paging offset $select → required columns ``` This reduces data transfer and application-server processing. The exact query plan remains database- and model-dependent. ### 6.3 CDS access control CDS DCL can restrict which rows a user may read. It participates in the query path according to the access-control model. ```text Service exposure says the entity is reachable CDS access control says which rows are readable BO authorization says which operations are permitted ``` These are complementary controls. ### 6.4 Unmanaged query path When a CDS-backed SQL query is insufficient—for example when data comes from a remote service—a CDS custom entity can delegate retrieval to an ABAP class implementing the RAP query-provider interface. ```text OData query → CDS custom entity → IF_RAP_QUERY_PROVIDER implementation → remote/nonstandard data source → response object ``` In an unmanaged query, the developer must handle supported paging, sorting, filtering, total count, and authorization responsibilities correctly. It is not a shortcut around the managed query model. --- ## 7. Transactional Request Path ### 7.1 OData modification flow ```text Fiori or API request POST / PATCH / DELETE / action │ ▼ Service Binding protocol, request parsing, changeset boundary │ ▼ Service Definition + Projection exposed entity and permitted projected behavior │ ▼ Base Behavior Definition operation contract, field control, concurrency, authorization │ ▼ RAP interaction phase precheck / standard operation / handler / determination / action │ ▼ Transactional buffer current uncommitted BO state │ ▼ RAP save sequence finalization / validation / late numbering / persistence / cleanup │ ▼ Database commit or rollback │ ▼ MAPPED / FAILED / REPORTED and operation result returned to consumer ``` The exact callbacks depend on implementation type, operation, draft state, and declared behavior. The diagram is a responsibility map, not a promise that every hook runs for every request. ### 7.2 Projected operation first A base action can exist but remain unavailable through a given service if the Behavior Projection does not expose it. ```text Base BDEF declares Release + Behavior Projection uses Release + Service exposes the projected entity = OData consumer can discover/invoke Release, subject to controls ``` The projection narrows the contract; it does not duplicate the implementation. ### 7.3 Runtime entity name In EML: ```abap MODIFY ENTITIES OF ZI_SalesOrderRequest IN LOCAL MODE ENTITY SalesOrderItem UPDATE FIELDS ( NetAmount ) WITH CORRESPONDING #( items ). ``` `ZI_SalesOrderRequest` identifies the RAP BO through its root entity. `SalesOrderItem` identifies an entity or alias declared inside that BO's behavior definition. It is not a free-form operation name. ### 7.4 One root names the BO An EML statement uses `ENTITIES OF <root>` because operations are coordinated within the BO contract rooted at that entity. The selected `ENTITY` can still be a composed child. ```text BO identifier: ZI_SalesOrderRequest Selected node: SalesOrderItem Operation: UPDATE ``` This is why a child update is written as an operation “of” the root BO. --- ## 8. RAP BO Runtime Phases ### 8.1 Interaction phase SAP divides BO runtime into an interaction phase and a save sequence. During the interaction phase, consumers invoke operations and the BO maintains the current transaction state in its buffer. ```text Initial persisted state │ ▼ CREATE / UPDATE / DELETE / ACTION │ ├── field and operation control ├── authorization / feature checks ├── prechecks where declared ├── determinations and action logic └── messages and failures │ ▼ Current transactional-buffer state ``` Multiple operations can participate in one RAP Logical Unit of Work (LUW) before persistence. ### 8.2 Transactional buffer The transactional buffer represents the current BO state including accepted, unsaved changes. ```text Database state at transaction start + buffered creates + buffered updates - buffered deletes = current transactional state ``` Every transactional RAP BO requires a buffer. In managed RAP, the framework provides it. In unmanaged RAP, the provider assumes responsibility for the essential implementation, including correct buffering semantics. ### 8.3 Save sequence The save sequence turns an acceptable buffered state into durable state. Representative stages are: ```text FINALIZE last permitted final calculations/changes before save checks complete │ ▼ CHECK_BEFORE_SAVE validations and consistency checks can reject the save │ ▼ ADJUST_NUMBERS final keys assigned for late-numbered instances where applicable │ ▼ SAVE persist accepted state │ ▼ CLEANUP release/reset transaction resources ``` The actual framework callbacks vary between managed, unmanaged, and additional save scenarios. Application code must respect the phase contract; late errors after the point of no return can cause runtime failure rather than ordinary business rejection. ### 8.4 Successful save ```text Buffered state accepted → persistence operations succeed → database transaction commits → response returns keys/results/messages → buffer is cleaned up ``` ### 8.5 Rejected save ```text Validation or check-before-save failure → failed instances and messages returned → persistence does not commit for the failed transactional request → consumer retains or corrects editable state according to scenario ``` For draft-enabled BOs, the invalid draft can remain persisted and editable while activation of that draft is rejected. Draft semantics are separate from ordinary transient buffering. --- ## 9. Three States That Must Not Be Confused | State | Durable | Cross-session | Purpose | | -------------------- | ------- | ------------- | --------------------------------------- | | Transactional buffer | No | No | Hold current changes inside RAP LUW | | Draft persistence | Yes | Yes | Preserve an unfinished editable version | | Active persistence | Yes | Yes | Store committed official business state | ```text Transactional buffer temporary transaction memory Draft persistent editing state managed through RAP draft lifecycle Active database state committed business data ``` A draft still uses a transactional buffer while a request modifies it. Draft does not replace the buffer. ### 9.1 SQL versus EML visibility An ordinary ABAP SQL `SELECT` reads database state. It does not automatically represent unsaved changes in the RAP transactional buffer. ```text SELECT from persistence → committed database representation READ ENTITIES → BO operation and transactional-state semantics ``` Behavior implementations should use EML when they need the current BO state, especially when calculations depend on changes made earlier in the same RAP LUW. --- ## 10. Managed, Unmanaged, and Additional Save ### 10.1 Managed implementation Managed RAP is appropriate when framework-managed transactional processing and persistence fit the business object. RAP can provide: - standard create, update, delete, and create-by-association processing; - managed transactional buffer; - persistence mapping; - locking and ETag support as declared; - save orchestration. The developer still owns: - the CDS and behavior model; - domain actions; - determinations and validations; - authorization and feature-control implementation; - field control and business messages; - tests and operational behavior. Managed does not mean “no ABAP” or “all business logic is generated.” ### 10.2 Unmanaged implementation Unmanaged RAP is appropriate when an existing implementation, legacy business logic, remote source, or nonstandard persistence mechanism must remain authoritative. The developer implements more of the interaction and save responsibilities, including correct transactional buffering, standard operations, and persistence orchestration according to the BO contract. ```text Managed framework owns generic transactional mechanics Unmanaged application provider owns essential transactional mechanics ``` Unmanaged is not inherently more powerful or more professional. It carries more responsibility and should be selected because the integration boundary requires it. ### 10.3 Managed with additional or unmanaged save Hybrid variants let the managed interaction phase coexist with application- specific save work. They are useful when the normal managed buffer is valuable but persistence must also invoke a legacy API, write extra durable data, or perform another supported save responsibility. The selected variant must follow the platform's exact release-specific contract. It must not perform uncontrolled commits inside BO implementation. ### 10.4 Draft is an independent choice ```text Managed or unmanaged = who implements transaction mechanics Draft or non-draft = whether a persistent editing lifecycle is provided ``` These are different architectural dimensions. --- ## 11. Entity Manipulation Language ### 11.1 Purpose EML is part of the ABAP language and provides type-safe access to RAP BO operations without using HTTP. ```text OData consumer → service contract → RAP BO ABAP consumer → EML → RAP BO ``` Both paths reach the business-object contract, although service projections, authorization context, and permitted EML modes can differ. ### 11.2 Main statement families ```text READ ENTITIES read instances, associations, functions, permissions MODIFY ENTITIES create, update, delete, create by association, execute actions COMMIT ENTITIES trigger the RAP save sequence for external/non-RAP consumption ROLLBACK ENTITIES discard RAP LUW changes and reset the transactional buffer ``` ### 11.3 Consumer EML example ```abap MODIFY ENTITIES OF ZI_SalesOrderRequest ENTITY SalesOrderRequest CREATE FIELDS ( SoldToParty TransactionCurrency ) WITH VALUE #( ( %cid = 'REQ_1' SoldToParty = 'C1000' TransactionCurrency = 'EUR' ) ) MAPPED DATA(mapped) FAILED DATA(failed) REPORTED DATA(reported). IF failed IS INITIAL. COMMIT ENTITIES RESPONSE OF ZI_SalesOrderRequest FAILED DATA(commit_failed) REPORTED DATA(commit_reported). ENDIF. ``` The consumer checks interaction-phase and commit responses separately. A successful `MODIFY` only means the change entered the RAP transaction; it does not itself prove database persistence. ### 11.4 `IN LOCAL MODE` Inside its own behavior pool, a BO implementation can use EML `IN LOCAL MODE` to call its BO directly. According to the operation, local mode bypasses controls such as: - authorization checks; - feature control; - prechecks; - CDS access control for applicable reads; - readonly restrictions for internal derived-field updates. It remains within RAP transactional processing. It is not a general privilege for external callers and is not available merely because two BOs participate in the same transaction. ```text Own behavior pool + own BO → IN LOCAL MODE can be valid External/cross-BO consumer → consume the published/released contract and controls ``` Using local mode creates a responsibility: internal logic must preserve the invariants that consumer-facing controls normally protect. --- ## 12. Typed RAP Responses ### 12.1 `MAPPED` `MAPPED` returns key mapping, especially from a content identifier such as `%cid` to the assigned transactional or final key. ```text Caller temporary identity %cid → RAP-created instance identity ``` It does not map CDS field names to database-column names. Persistence mapping belongs to the behavior model. ### 12.2 `FAILED` `FAILED` identifies instances for which an operation or save could not complete. It controls transactional outcome for those instances according to the RAP contract. ```text FAILED entry = this entity instance did not pass the requested processing ``` ### 12.3 `REPORTED` `REPORTED` carries messages and related information for consumers. A reported message by itself is not universally the mechanism that rejects an operation. The failure marker and RAP contract determine failure; the message explains the outcome. ```text FAILED → affected instance failed REPORTED → explanation, severity, field highlighting, state area ``` Warning and success messages can also be reported without rejecting the operation. ### 12.4 Action result An action can return an updated entity or custom result through its declared result contract. ```abap result = VALUE #( FOR request IN requests ( %tky = request-%tky %param = request ) ). ``` `%tky` correlates the response with the precise transactional instance. It can contain more transactional identity context than the visible persistent key, including draft identity where relevant. --- ## 13. Transaction Ownership and Commit ### 13.1 Framework-managed service request When OData invokes a RAP BO, the RAP framework owns request and changeset transaction orchestration. Behavior implementation code must not issue its own `COMMIT WORK` or `COMMIT ENTITIES` inside the handler. ```text OData changeset → framework collects operations → interaction phase → save sequence → one controlled commit or rollback ``` ### 13.2 External EML consumer An ABAP report, class, or test consuming a BO through EML owns the RAP LUW boundary and normally uses `COMMIT ENTITIES` to persist successful changes. ```text MODIFY ENTITIES → inspect FAILED and REPORTED → COMMIT ENTITIES → inspect commit FAILED and REPORTED ``` ### 13.3 Behavior implementation Inside a behavior pool: - use EML to request additional BO operations when allowed; - do not independently commit; - let the framework preserve atomicity across affected BOs; - propagate failures and messages through RAP response structures. An explicit commit inside reusable business logic would split the transaction and prevent the framework from rolling the entire request back consistently. --- ## 14. Authorization, Feature, and Field-Control Boundaries These controls answer different runtime questions: | Control | Responsibility | | ------------------------ | ------------------------------------------------------------ | | CDS access control | Restrict readable data according to DCL model | | Global authorization | Decide user permission independent of one instance | | Instance authorization | Decide user permission using instance context | | Global feature control | Enable/disable capability globally at runtime | | Instance feature control | Enable/disable operation or field for current instance state | | Static field control | Declare readonly or mandatory characteristics in BDEF | | Dynamic field control | Return instance-specific field behavior where supported | | Validation | Reject inconsistent business state | ```text User may update orders → authorization Released order cannot be edited → feature/state control Requested quantity must be positive → validation ``` Disabling a button is not security. A direct OData or EML consumer must still be constrained by the BO contract. --- ## 15. Activation, Publishing, Transport, and Deployment ### 15.1 Activation Activation creates or updates the active repository version of an ABAP development object after syntax and dependency checks. RAP artifacts depend on one another, so activation is usually performed from lower-level persistence and CDS artifacts toward behavior and service exposure. ```text Table → base CDS → projection CDS → BDEF and behavior implementation → Behavior Projection → metadata extension → service definition → service binding ``` Activation is not end-user deployment and does not automatically publish every service endpoint. ### 15.2 Service publishing Publishing a service binding makes the configured service/version accessible in the current ABAP system according to its platform and authorization setup. ```text Active Service Definition + active Service Binding + publish = reachable service endpoint in that system ``` The preview is a consumer of that endpoint. “Local publish” means local to the current ABAP system/tenant, not execution on the developer's laptop. ### 15.3 Transport A transport moves repository and configuration changes through the system landscape. It does not mean that an independently built Fiori application has already been deployed to its frontend runtime or that every target-system service is configured and authorized. ### 15.4 Deployment Deployment delivers a separately packaged application to its runtime, for example a standalone Fiori application. Generated Fiori preview, service publication, ABAP transport, and frontend deployment are related but different lifecycle steps. ### 15.5 ADT and execution location RAP development can be performed in ABAP Development Tools in Eclipse. ADT is the development client; activation, OData execution, ABAP runtime, and database access occur in the connected ABAP system. ```text Developer machine Eclipse / ADT source editor and repository tools │ ▼ ABAP system active repository + RAP runtime + application server │ ▼ Configured database persistence read by ABAP SQL and CDS ``` CDS does not use a separate database from ABAP. It models data in the database connected to the ABAP system, subject to the CDS source and runtime contract. --- ## 16. End-to-End Sales Order Request Trace ### 16.1 Read a list ```text 1. Fiori elements obtains OData metadata 2. UI builds a List Report from annotations 3. UI sends GET with filter/select/order/paging options 4. Service Binding resolves the service version 5. Projection determines exposed fields and navigation 6. RAP managed query evaluates CDS, query options, and access control 7. Database returns matching rows 8. OData serializes the projected result 9. Fiori renders the list ``` ### 16.2 Create a request with items ```text 1. Consumer sends root CREATE and item create-by-association 2. Projection contract permits the exposed operations 3. Base BDEF supplies field/operation/authorization contract 4. RAP assigns early UUIDs when configured 5. Managed runtime places root and items in transactional buffer 6. Determinations initialize or derive BO-owned values 7. MAPPED correlates client identifiers with instance keys 8. Save is requested at the request/changeset boundary 9. On-save validations inspect current aggregate state 10. Accepted instances persist atomically 11. FAILED/REPORTED and created keys return to consumer ``` ### 16.3 Submit action ```text 1. UI annotation exposes an action button 2. Behavior Projection exposes Submit 3. Client invokes bound OData action for selected instance 4. RAP resolves %tky and checks authorization/feature control 5. Behavior Pool Submit method executes 6. Method reads current BO state through EML 7. Invalid transition appends FAILED and REPORTED 8. Valid transition updates Status through local EML 9. Transactional buffer holds updated state 10. Save sequence validates and persists 11. Action result and messages return to UI 12. Side-effect metadata can instruct UI to reread affected fields ``` The UI annotation causes discoverability and rendering. The action contract and behavior pool own the business transition. ### 16.4 Derived amount update ```text RequestedQuantity or UnitPrice changes → determination trigger → read current Item state from transactional buffer → calculate Item.NetAmount → update derived field through local EML → recalculate parent TotalAmount from current Items → buffer contains consistent aggregate → side effect tells UI which values to refresh → save sequence persists accepted result ``` The side effect does not calculate the amount. It describes which consumer data became stale after backend logic ran. --- ## 17. Runtime Diagnostics by Layer ### 17.1 Universal trace ```text Observed symptom → identify metadata, query, interaction, or save path → capture exact entity, operation, key/%tky, and payload → inspect projected capability → inspect base behavior contract → inspect behavior implementation when it participates → inspect FAILED, REPORTED, HTTP error, and application log → inspect transactional versus persistent state → inspect service/cache/UI only at its responsible boundary ``` ### 17.2 UI field or action missing ```text Metadata extension / CDS annotation → active projection → exposed entity in Service Definition → active/published Service Binding → $metadata contains annotation/capability → Fiori cache and floorplan interpretation ``` For an action, also verify: ```text Base BDEF declaration → Behavior Projection use action → action annotation → feature-control result → authorization result ``` ### 17.3 Read returns no rows ```text OData request and filter values → correct entity set and service version → projection filters/parameters → CDS associations and join cardinality → DCL/access control → database data and client context → unmanaged query implementation if applicable ``` An entity exposed in a service can correctly return no rows because DCL denies all data. ### 17.4 Modification rejected before handler logic Possible earlier boundaries include: - operation not exposed by Behavior Projection; - readonly or mandatory field contract; - authorization or feature control; - precheck; - stale ETag; - invalid payload/type or missing key; - draft/active instance mismatch. The absence of a breakpoint hit in an action or validation does not prove that the request reached that implementation method. ### 17.5 Modify succeeds but save fails ```text Interaction-phase MODIFY accepted → current change exists in transactional buffer → save-sequence validation/check fails → COMMIT ENTITIES or OData changeset fails → database remains unchanged ``` Inspect both interaction and commit response structures. The final business error can be returned only when save is attempted. ### 17.6 Database is unchanged ```text Verify operation response → verify save boundary occurred → verify validation/late-numbering/save messages → verify correct client and persistence table → verify draft versus active instance → verify rollback or failed changeset ``` Do not add direct SQL writes to “fix” a missing save. That bypasses the BO contract and hides the actual transaction error. --- ## 18. Performance and Correctness Boundaries ### 18.1 RAP requests are set-oriented Handler methods receive tables of keys or instances because one request can process several entities. Implementations should avoid assuming one row. ```text keys table → bulk EML read → set-based lookup/calculation → bulk EML modify → correlated FAILED/REPORTED/result rows ``` ### 18.2 Avoid database reads per entity Poor pattern: ```text LOOP over keys SELECT one row SELECT reference row MODIFY one entity ENDLOOP ``` Preferred direction: ```text READ ENTITIES for all keys → extract distinct reference keys → one set-oriented lookup → process in memory → one bulk MODIFY ENTITIES ``` ### 18.3 Read the correct state Business logic depending on current transaction changes should read via EML, not assume the database already contains earlier modifications. ### 18.4 Idempotent determinations The runtime does not guarantee a simple user-imagined order across all determinations. Derived-value logic should be safe when triggered repeatedly and should converge to the same result for the same BO state. ### 18.5 No commits in handlers Independent commits break RAP atomicity and can leave partial cross-entity or cross-BO results. The framework or external EML consumer owns the save boundary. --- ## 19. Clean-Core and Release Contracts ### 19.1 Internal existence is not release A CDS entity, class, or function can exist in the system without being released for Cloud development or stable cross-component consumption. ```text Exists in repository ≠ released API ≠ permitted in ABAP Cloud ≠ stable across upgrades ``` Check API State and supported capabilities in the target system. ### 19.2 BO interface versus ordinary service projection A formal RAP BO interface can use a projection with provider contract `transactional_interface` and a Behavior Definition Interface to provide a lifecycle-stable cross-component contract. An ordinary service projection commonly uses `transactional_query` and shapes one business service. Naming a CDS entity `ZI_...` does not automatically make it a released RAP BO interface. ```text Base BO → optional released BO interface for cross-component stability → service-specific projection for OData consumer ``` ### 19.3 Extension hierarchy Preferred extension dependencies move toward released contracts: ```text Released BO interface / API / event → custom adapter or extension → custom service projection Avoid direct dependency on SAP internal table or unreleased implementation class ``` ### 19.4 Protocol does not define the domain boundary OData V4, EML, and events are consumption mechanisms. Aggregate ownership, business rules, and transaction boundaries should be defined from the domain and provider contract first. --- ## 20. Common Architectural Misinterpretations ### 20.1 CDS is not only a database view CDS can define semantic elements, associations, compositions, annotations, authorization relevance, and BO topology in addition to database projection. ### 20.2 The behavior pool is not the service It implements BO behavior. Service Definition and Service Binding expose a projected contract through a protocol. ### 20.3 The Behavior Projection contains no domain implementation It selects capabilities for a consumer. The base behavior pool remains the implementation owner. ### 20.4 `REPORTED` does not universally reject an operation It transports messages. `FAILED`, validation outcome, and RAP transaction semantics determine rejection. ### 20.5 Managed RAP is not zero-code CRUD The framework supplies generic transaction mechanics, while the developer owns the domain model, rules, security implementation, messages, and tests. ### 20.6 Transactional buffer is not draft The buffer is temporary LUW state used by every transactional BO. Draft is a persistent editing version with its own lifecycle. ### 20.7 Service publication is not application deployment Publication exposes an endpoint in the ABAP system. Transport and frontend deployment solve different lifecycle problems. ### 20.8 OData is not required for local BO consumption EML invokes RAP BO operations directly from ABAP and preserves the declared BO contract according to the consumption mode. ### 20.9 Direct SQL does not participate in RAP state automatically Database reads do not automatically include unsaved transactional-buffer data, and direct writes bypass RAP behavior. ### 20.10 UI control is not backend protection Annotations and disabled buttons improve interaction. Authorization, validation, and feature control must protect the BO for every consumer. --- ## 21. Compact Architecture Map ```text DESIGN TIME Persistence table durable columns and technical keys │ ▼ Base CDS root + compositions + associations semantic data model and aggregate topology │ ├── Base BDEF │ transactional contract │ │ │ └── Behavior Pool │ custom interaction/save implementation │ ▼ CDS Projection + Behavior Projection consumer-specific data and capability contract │ ├── Metadata Extension │ UI vocabulary and presentation │ ▼ Service Definition exposed entity set │ ▼ Service Binding OData protocol, category, version, publication RUNTIME — METADATA Client → Binding → Service → Projection/Behavior metadata → $metadata RUNTIME — QUERY Client GET → Binding → projected query contract → RAP query runtime + DCL → CDS/SQL or unmanaged query provider → response RUNTIME — MODIFY Client or EML consumer → projected/released BO operation → Base BDEF controls → Behavior Pool/framework interaction logic → transactional buffer → save sequence → database commit or rollback → MAPPED / FAILED / REPORTED / result STATE Transactional buffer temporary LUW state Draft persistence durable editable state Active persistence durable committed business state ``` The architecture should always be read in two directions: ```text Design persistence → semantic model → behavior → projection → service Diagnosis client symptom → service metadata/request → projection → BO contract → runtime phase → buffer/save → persistence ``` That two-way trace is the foundation for implementing and debugging every other RAP feature. 44:T8e4,SAP RAP Architecture and End-to-End Runtime — Technical Reference This document explains the architecture and runtime of the ABAP RESTful Application Programming Model (RAP). It traces metadata, read, and transactional requests through CDS, behavior, service exposure, the RAP transactional buffer, the save sequence, and database persistence. The central technical principle is: CDS defines the semantic data model, the behavior definition declares the transactional contract, the behavior pool implements application-specific behavior, and the service layer exposes a consumer-specific projection. The RAP runtime coordinates these artifacts as one business-object contract. This reference focuses on architectural responsibility and runtime flow. Detailed CDS modeling, EML syntax, draft, authorization, business-rule implementation, UI annotations, and testing are developed in the remaining documents of the RAP technical-reference set. Primary SAP sources: - SAP Help — ABAP RESTful Application Programming Model - SAP Learning — Exploring the Concept and Architecture of RAP - SAP Help — RAP BO Runtime - SAP Help — RAP Business Object Contract - SAP Help — Entity Manipulation Language - SAP Help — Business Service - SAP Help — Service Definition - SAP Help — OData V4 Service Binding Editor --- 1. RAP in One Architectural View 1.1 Design-time stack text Consumer Fiori elements / external API client / ABAP EML consumer │ ▼ Business service exposure Service Binding + Service Definition │ ▼ Consumer projection CDS Projection + Behavior Projection + Metadata Extension │ ▼ RAP Business Object CDS root/composition model + Base Behavior Definition │ ▼ Behavior implementation Behavior Pool: handlers and saver where implementation is required │ ▼ Persistence and external capabilities Database tables / released APIs / legacy implementation The stack is not a sequence of duplicate models. Each layer makes a different decision: | Layer | Primary decision | | ------------------ | ------------------------------------------------------------ | | Persistence | Where durable state is stored | | CDS data model | What the business data means and how entities relate | | Base behavior | Which operations and transactional rules the45:Tbf3,# SAP RAP Architecture and End-to-End Runtime — Technical Reference This document explains the architecture and runtime of the ABAP RESTful Application Programming Model (RAP). It traces metadata, read, and transactional requests through CDS, behavior, service exposure, the RAP transactional buffer, the save sequence, and database persistence. The central technical principle is: > CDS defines the semantic data model, the behavior definition declares the > transactional contract, the behavior pool implements application-specific > behavior, and the service layer exposes a consumer-specific projection. The > RAP runtime coordinates these artifacts as one business-object contract. This reference focuses on architectural responsibility and runtime flow. Detailed CDS modeling, EML syntax, draft, authorization, business-rule implementation, UI annotations, and testing are developed in the remaining documents of the RAP technical-reference set. Primary SAP sources: - [SAP Help — ABAP RESTful Application Programming Model](https://help.sap.com/docs/abap-cloud/abap-rap/abap-restful-application-programming-model) - [SAP Learning — Exploring the Concept and Architecture of RAP](https://learning.sap.com/courses/building-transactional-apps-with-the-abap-restful-application-programming-model/exploring-the-concept-and-architecture-of-rap) - [SAP Help — RAP BO Runtime](https://help.sap.com/docs/abap-cloud/abap-rap/rap-bo-runtime) - [SAP Help — RAP Business Object Contract](https://help.sap.com/docs/abap-cloud/abap-rap/rap-business-object-contract) - [SAP Help — Entity Manipulation Language](https://help.sap.com/docs/abap-cloud/abap-rap/entity-manipulation-language-eml) - [SAP Help — Business Service](https://help.sap.com/docs/abap-cloud/abap-rap/business-service) - [SAP Help — Service Definition](https://help.sap.com/docs/abap-cloud/abap-rap/service-definition) - [SAP Help — OData V4 Service Binding Editor](https://help.sap.com/docs/abap-cloud/abap-development-tools-user-guide/using-service-binding-editor-for-odata-v4-service) --- ## 1. RAP in One Architectural View ### 1.1 Design-time stack ```text Consumer Fiori elements / external API client / ABAP EML consumer │ ▼ Business service exposure Service Binding + Service Definition │ ▼ Consumer projection CDS Projection + Behavior Projection + Metadata Extension │ ▼ RAP Business Object CDS root/composition model + Base Behavior Definition │ ▼ Behavior implementation Behavior Pool: handlers and saver where implementation is required │ ▼ Persistence and external capabilities Database tables / released APIs / legacy implementation ``` The stack is not a sequence of duplicate models. Each layer makes a different decision:46:Tab25, # SAP RAP CDS Data Modeling and Projection Design — Technical Reference This document explains how ABAP CDS defines the structural and semantic model of a RAP business object and how CDS projection views adapt that model for a specific consumer. It focuses on entity boundaries, keys, compositions, associations, cardinality, semantic annotations, projection contracts, and navigation topology. The central design principle is: > The base CDS model describes the reusable business object and its > relationships. A CDS projection selects and adapts that model for one > consumption scenario. Neither layer replaces the behavior definition, which > owns the transactional capabilities and business rules. Primary SAP sources: - [SAP Help — Defining the Data Model in CDS Views](https://help.sap.com/docs/abap-cloud/abap-rap/defining-data-model-in-cds-views) - [SAP Help — CDS View Entities](https://help.sap.com/docs/abap-cloud/abap-data-models/cds-view-entities-8b3e8e8b8797432abecd7d1fbb6d5c12) - [SAP Help — Associations](https://help.sap.com/docs/abap-cloud/abap-data-models/cds-associations) - [SAP Help — Projection Views](https://help.sap.com/docs/abap-cloud/abap-data-models/cds-projection-views) - [SAP Help — Creating CDS View Entities for RAP](https://help.sap.com/docs/abap-cloud/abap-rap/creating-cds-view-entities) - [SAP Help — CDS Annotations for RAP](https://help.sap.com/docs/abap-cloud/abap-rap/cds-annotations) --- ## 1. Position of CDS in RAP ```text Database tables or released data sources │ ▼ Base CDS view entities fields, keys, aliases, compositions, associations, semantics │ ├──────── Base Behavior Definition │ operations and transactional contract │ ▼ CDS projection views consumer-specific field and navigation shape │ ├──────── Behavior Projection │ consumer-visible operations │ ├──────── Metadata Extension │ presentation metadata │ ▼ Service Definition and Service Binding ``` CDS is responsible for the data model. It can express: - entity elements and their ABAP Dictionary types; - semantic keys exposed by the entity; - aliases that give technical columns business-oriented names; - calculations supported by the CDS language; - root, child, and reference relationships; - semantic dependencies such as amount/currency and quantity/unit; - reusable navigation paths; - annotations consumed by the ABAP runtime and other frameworks. CDS does not by itself implement: - create, update, or delete behavior; - validations, determinations, actions, or feature control; - transactional buffering and save handling; - a custom authorization decision for a modification; - an OData endpoint. Those responsibilities belong to other RAP artifacts. --- ## 2. Persistence Model Versus Semantic Model ### 2.1 Database table A database table is the durable storage contract. It normally contains: - technical keys; - foreign-key columns; - business data; - administrative fields; - ETag timestamps; - internal processing fields; - fields needed by persistence but not every consumer. Example: ```abap define table zsor_request { key client : abap.clnt not null; key request_uuid : sysuuid_x16 not null; request_number : abap.char(10); sold_to_party : abap.char(10); status : abap.char(1); total_amount : abap.curr(15,2); transaction_currency : abap.cuky; internal_processing_code: abap.char(4); created_by : abp_creation_user; created_at : abp_creation_tstmpl; last_changed_at : abp_lastchange_tstmpl; local_last_changed_at : abp_locinst_lastchange_tstmpl; } ``` The table proves how values are stored. It does not fully explain what the business object means, which rows belong to one aggregate, or which fields a consumer should see. ### 2.2 Base CDS view entity A CDS view entity creates a reusable semantic layer over the data source: ```abap define root view entity ZI_SalesOrderRequest as select from zsor_request as Request { key Request.request_uuid as RequestUUID, Request.request_number as RequestNumber, Request.sold_to_party as SoldToParty, Request.status as Status, Request.total_amount as TotalAmount, Request.transaction_currency as TransactionCurrency, Request.last_changed_at as LastChangedAt, Request.local_last_changed_at as LocalLastChangedAt } ``` The CDS entity: - exposes business-oriented names; - selects only the columns required by the model; - can attach semantics and relationships; - provides a typed source for behavior and projections; - decouples consumers from the physical table layout. The CDS view does not copy data out of the table. It is a repository definition that the runtime translates into database access when queried. ### 2.3 Why the layers must remain separate ```text Persistence concern Semantic/consumer concern ───────────────────────────────── ───────────────────────────────── How is the value stored? What does the value mean? Which technical column exists? Which business name is stable? Which administrative field exists? Does this consumer need the field? How are rows physically keyed? How are BO nodes navigated? ``` Exposing a database table directly makes its storage design part of the consumer contract. A CDS layer allows the persistence structure to evolve behind a more stable semantic interface. --- ## 3. View Entities and Their Elements ### 3.1 Basic syntax ```abap @EndUserText.label: 'Sales Order Request' @AccessControl.authorizationCheck: #CHECK define root view entity ZI_SalesOrderRequest as select from zsor_request as Request { key Request.request_uuid as RequestUUID, Request.request_number as RequestNumber, Request.status as Status } ``` Key parts: | Construct | Meaning | | -------------------- | ------------------------------------------------- | | `define view entity` | Defines a CDS view entity | | `root` | Marks the root of a RAP composition tree | | `as select from` | Defines the data source | | `key` | Declares an element as part of the CDS entity key | | `as RequestUUID` | Assigns a semantic alias | | annotations | Add technical or semantic metadata | `root` is a modeling statement. It says that this entity may anchor a RAP business-object composition tree. It does not automatically create behavior. ### 3.2 CDS keys are not a substitute for database integrity The CDS key describes how consumers and frameworks identify the result rows. It should match the actual uniqueness of the result. ```text Database primary key enforces uniqueness in persisted rows CDS entity key declares the identity of rows exposed by the CDS entity ``` Declaring a field with `key` does not repair a query that returns duplicates. If joins, path expressions, or incorrect cardinalities multiply rows, the model is still incorrect even though the select list contains a key declaration. For a UUID-based root, the technical key is commonly a `RAW(16)` UUID exposed through a data element such as `sysuuid_x16`. A separate human-readable order number can remain a business identifier rather than the technical key. ### 3.3 Aliases and persistence mapping Aliases improve meaning: ```abap Request.sold_to_party as SoldToParty ``` If the CDS element names differ from the persistence column names, a managed behavior definition can use a mapping block: ```abap mapping for zsor_request { RequestUUID = request_uuid; RequestNumber = request_number; SoldToParty = sold_to_party; TotalAmount = total_amount; TransactionCurrency = transaction_currency; } ``` This mapping belongs to the behavior definition. It is different from the RAP response parameter `MAPPED`, which reports preliminary-to-final key mappings during EML processing. --- ## 4. Designing the Business-Object Aggregate ### 4.1 Aggregate boundary A RAP business object is normally modeled as a tree: ```text SalesOrderRequest root └── SalesOrderItem composition child └── RequestedSchedule composition grandchild ``` The root is the transactional entry point and consistency boundary. It often owns: - aggregate status; - aggregate totals; - lifecycle transitions; - locking and authorization dependencies; - navigation to all owned child nodes. The decisive question for a child is existential dependency: the child has no business meaning outside its parent aggregate. ### 4.2 Composition A composition is a specialized association that defines ownership and a parent-child lifecycle dependency. ```abap define root view entity ZI_SalesOrderRequest as select from zsor_request as Request composition [0..*] of ZI_SalesOrderItem as _Items { key Request.request_uuid as RequestUUID, _Items } ``` The root exposes the composition in its element list. The cardinality `[0..*]` means that one request may relate to zero, one, or many items. The composition states structure and ownership. Transactional operations on the child are still declared in the behavior definition, for example creation by association from the parent. ### 4.3 Association to parent The child completes the composition relationship with a to-parent association: ```abap define view entity ZI_SalesOrderItem as select from zsor_item as Item association to parent ZI_SalesOrderRequest as _Request on $projection.RequestUUID = _Request.RequestUUID { key Item.item_uuid as ItemUUID, Item.request_uuid as RequestUUID, Item.product as Product, _Request } ``` Important details: - the target is the parent CDS entity; - the `ON` condition connects the child's parent key to the root key; - `$projection.RequestUUID` refers to the element name exposed by this CDS entity, not the database column name; - the association must be published in the element list for navigation; - the association alias is later used by behavior and projection artifacts. For a deeper tree, a child can also carry an explicit association to the root when root navigation is required. The direct `association to parent` still points to the immediate parent node. ### 4.4 Composition is not an ordinary foreign-key link ```text Composition SalesOrderRequest ─owns─> SalesOrderItem child lifecycle depends on parent Association SalesOrderRequest ─refers to─> Customer target has an independent lifecycle ``` An item is a composition child because an order item without its request has no meaning in this use case. Customer, Product, Plant, and Sales Area are normally associations because those targets exist independently and are reused by many transactions. Do not choose composition merely because the database contains a foreign key. Choose it because the domain says the parent owns the target's lifecycle. --- ## 5. Associations to Independent Entities ### 5.1 Definition ```abap association [0..1] to ZI_CustomerReference as _Customer on $projection.SoldToParty = _Customer.CustomerID ``` ```abap association [0..1] to ZI_ProductReference as _Product on $projection.Product = _Product.ProductID ``` An association defines a reusable relationship. It behaves like a declared join that is instantiated when a consumer follows the association or requests a target field through a path expression. ### 5.2 Publishing versus consuming an association Publishing the association: ```abap { key Request.request_uuid as RequestUUID, Request.sold_to_party as SoldToParty, _Customer } ``` Consuming a target field through a path: ```abap { key Request.request_uuid as RequestUUID, Request.sold_to_party as SoldToParty, _Customer.CustomerName as CustomerName } ``` These have different effects: | Form | Effect | | ------------------------ | -------------------------------------------------------------------- | | `_Customer` | Publishes a navigation relationship | | `_Customer.CustomerName` | Adds a target field to the current result and causes join processing | Associations can reduce unnecessary joins because navigation is instantiated on demand. They do not guarantee good performance by themselves; deep paths, incorrect cardinalities, and wide consumption can still produce expensive SQL. ### 5.3 Association naming An underscore prefix such as `_Customer` is the established ABAP CDS convention for an association alias. The underscore communicates navigation rather than scalar data. It is a convention, not the business identity of the target. ### 5.4 Referential validity An association describes how a target is found. It does not automatically reject an invalid foreign-key value during a transactional save. ```text CDS association navigation and query relationship Value help assists selection and can support consumer validation metadata RAP validation enforces the business rule and can reject the save ``` If every submitted request must refer to an existing Customer, implement that invariant in backend behavior even when the UI provides a Customer value help. --- ## 6. Cardinality ### 6.1 Meaning Cardinality documents how many target rows may match one source row. | Numeric form | Meaning from one source instance | | ------------ | -------------------------------- | | `[0..1]` | Zero or one target | | `[1..1]` | Exactly one target is expected | | `[0..*]` | Zero, one, or many targets | | `[1..*]` | One or many targets are expected | Examples: ```abap association [0..1] to ZI_CustomerReference as _Customer ... composition [0..*] of ZI_SalesOrderItem as _Items ``` ### 6.2 Cardinality is a model assertion, not general validation `[0..1]` does not mean RAP will automatically reject two matching rows. It states what the model expects and can influence syntax checks, generated SQL, and optimizer decisions. The actual data and `ON` condition must satisfy the declaration. If a declared to-one association returns multiple targets, consumers can receive unstable or unexpected results and database optimizations may be based on a false model. ### 6.3 Cardinality does not determine ownership Both of these relationships can use `[0..*]`: ```text Order ─composition→ Items Customer ─association→ Addresses ``` The number of targets does not decide whether the relationship is a composition. Ownership and lifecycle dependency decide that. ### 6.4 Optional during editing versus required business state A `[0..1]` Customer association permits the relationship to be absent from a modeling perspective. That can support incomplete creation or draft editing. It does not express a rule such as “Customer is mandatory when Status is Submitted.” That state-dependent rule belongs in behavior validation. ```text Structural possibility Customer relationship may be empty while editing Business invariant Customer must be valid before submission or activation ``` --- ## 7. Complete Base CDS Aggregate Example ### 7.1 Root entity ```abap @EndUserText.label: 'Sales Order Request' @AccessControl.authorizationCheck: #CHECK define root view entity ZI_SalesOrderRequest as select from zsor_request as Request composition [0..*] of ZI_SalesOrderItem as _Items association [0..1] to ZI_CustomerReference as _Customer on $projection.SoldToParty = _Customer.CustomerID { key Request.request_uuid as RequestUUID, Request.request_number as RequestNumber, Request.sold_to_party as SoldToParty, Request.status as Status, @Semantics.amount.currencyCode: 'TransactionCurrency' Request.total_amount as TotalAmount, Request.transaction_currency as TransactionCurrency, Request.internal_processing_code as InternalProcessingCode, @Semantics.systemDateTime.createdAt: true Request.created_at as CreatedAt, @Semantics.user.createdBy: true Request.created_by as CreatedBy, @Semantics.systemDateTime.lastChangedAt: true Request.last_changed_at as LastChangedAt, @Semantics.systemDateTime.localInstanceLastChangedAt: true Request.local_last_changed_at as LocalLastChangedAt, _Items, _Customer } ``` ### 7.2 Child entity ```abap @EndUserText.label: 'Sales Order Request Item' @AccessControl.authorizationCheck: #CHECK define view entity ZI_SalesOrderItem as select from zsor_item as Item association to parent ZI_SalesOrderRequest as _Request on $projection.RequestUUID = _Request.RequestUUID association [0..1] to ZI_ProductReference as _Product on $projection.Product = _Product.ProductID { key Item.item_uuid as ItemUUID, Item.request_uuid as RequestUUID, Item.product as Product, @Semantics.quantity.unitOfMeasure: 'QuantityUnit' Item.requested_quantity as RequestedQuantity, Item.quantity_unit as QuantityUnit, @Semantics.amount.currencyCode: 'TransactionCurrency' Item.unit_price as UnitPrice, @Semantics.amount.currencyCode: 'TransactionCurrency' Item.net_amount as NetAmount, Item.transaction_currency as TransactionCurrency, Item.local_last_changed_at as LocalLastChangedAt, _Request, _Product } ``` ### 7.3 Structural interpretation ```text ZI_SalesOrderRequest key: RequestUUID owns: _Items references: _Customer aggregate values: Status, TotalAmount concurrency value: LocalLastChangedAt ZI_SalesOrderItem key: ItemUUID belongs to: _Request references: _Product entered values: Product, RequestedQuantity derived candidates: UnitPrice, NetAmount, TransactionCurrency ``` “Entered” and “derived” in the last diagram are design classifications. CDS has no `[entered]` or `[derived]` element syntax. The behavior definition marks consumer restrictions such as `readonly`, and determinations implement the derivation. --- ## 8. Semantic Annotations ### 8.1 Amount and currency ```abap @Semantics.amount.currencyCode: 'TransactionCurrency' Item.net_amount as NetAmount, Item.transaction_currency as TransactionCurrency ``` This metadata declares that `NetAmount` must be interpreted together with `TransactionCurrency`. Consumers can use it for formatting, decimal handling, metadata generation, and display. It does not: - convert one currency to another; - retrieve a price condition; - calculate `NetAmount`; - guarantee that header and item currencies match; - validate that the currency key exists. Those require business logic, a released conversion capability, or validation as appropriate. ### 8.2 Quantity and unit ```abap @Semantics.quantity.unitOfMeasure: 'QuantityUnit' Item.requested_quantity as RequestedQuantity, Item.quantity_unit as QuantityUnit ``` The annotation makes the quantity/unit dependency explicit. It does not perform unit conversion or availability checking. ### 8.3 Administrative timestamps Typical managed RAP administrative fields include: ```abap @Semantics.systemDateTime.createdAt: true CreatedAt, @Semantics.user.createdBy: true CreatedBy, @Semantics.systemDateTime.lastChangedAt: true LastChangedAt, @Semantics.systemDateTime.localInstanceLastChangedAt: true LocalLastChangedAt ``` Their exact use depends on the behavior definition. For example, an ETag must be declared in behavior; annotating a timestamp alone does not activate ETag concurrency control. ### 8.4 Annotation responsibility Annotations are metadata interpreted by a particular framework or runtime. Their presence does not imply arbitrary application logic. ```text Semantic annotation describes meaning or framework relationship Behavior implementation computes, validates, or changes transactional state ``` --- ## 9. CDS Projection Views ### 9.1 Purpose A projection view adapts a base CDS entity for a defined scenario: ```text Reusable base model RequestUUID, RequestNumber, SoldToParty, Status, TotalAmount, InternalProcessingCode, admin fields, relationships │ ▼ Customer-facing UI projection RequestUUID, RequestNumber, SoldToParty, Status, TotalAmount, relationships needed by UI ``` The projection decides which fields and associations are visible through that projection. It does not erase excluded fields from the base entity or table. ### 9.2 Transactional query projection ```abap @EndUserText.label: 'Sales Order Request Consumption' @AccessControl.authorizationCheck: #CHECK define root view entity ZC_SalesOrderRequest provider contract transactional_query as projection on ZI_SalesOrderRequest { key RequestUUID, RequestNumber, SoldToParty, Status, TotalAmount, TransactionCurrency, LocalLastChangedAt, _Items : redirected to composition child ZC_SalesOrderItem, _Customer } ``` `transactional_query` identifies the projection as a service-consumption layer for a transactional RAP business object. Current CDS syntax expects the provider contract to be stated explicitly. ### 9.3 Child projection ```abap @EndUserText.label: 'Sales Order Request Item Consumption' @AccessControl.authorizationCheck: #CHECK define view entity ZC_SalesOrderItem provider contract transactional_query as projection on ZI_SalesOrderItem { key ItemUUID, RequestUUID, Product, RequestedQuantity, QuantityUnit, UnitPrice, NetAmount, TransactionCurrency, LocalLastChangedAt, _Request : redirected to parent ZC_SalesOrderRequest, _Product } ``` The child projection must use `as projection on` and a provider contract just like the root projection. Omitting `as projection on ZI_SalesOrderItem` does not define a projection. ### 9.4 Base versus projection responsibility | Concern | Base CDS | CDS projection | | ----------------------- | ------------------------------------------ | ------------------------------------------------- | | BO node identity | Defines reusable entity key | Projects the required key | | Aggregate topology | Defines composition and parent association | Redirects topology to projected nodes | | Independent references | Defines reusable associations | Exposes or omits them for the consumer | | Internal field | Can retain it for implementation | Can omit it from the consumer contract | | Amount/unit semantics | Usually defined close to reusable field | Inherited or adapted when supported | | Transactional operation | Not a CDS concern | Not a CDS concern; behavior projection exposes it | | UI layout | Not a base-model concern | Usually placed in metadata extension | --- ## 10. Projection Redirection ### 10.1 Why redirection exists The base root composition points to the base child: ```text ZI_SalesOrderRequest._Items ──> ZI_SalesOrderItem ``` The consumer should navigate within the projected graph: ```text ZC_SalesOrderRequest._Items ──> ZC_SalesOrderItem ZC_SalesOrderItem._Request ───> ZC_SalesOrderRequest ``` Redirection rewires the projected relationship to the corresponding projected entity. ### 10.2 Syntax Root to child: ```abap _Items : redirected to composition child ZC_SalesOrderItem ``` Child to parent: ```abap _Request : redirected to parent ZC_SalesOrderRequest ``` Ordinary association redirection, when a projected target is required, uses an appropriate redirected association form supported by the projection model. ### 10.3 What redirection does not do Redirection does not: - copy records between base and projection entities; - create child rows; - calculate target data; - map a field to a persistence column; - make a blank database relationship valid; - implement cascade deletion. The base and projection views still operate over the same underlying business data. Redirection changes the navigation contract visible from the projection. ### 10.4 Missing redirection is not universally “blank data” The actual consequence depends on the artifact and syntax. Common outcomes include activation errors, an inconsistent projected composition, navigation to an unintended base target, or missing service navigation. It is inaccurate to treat “blank data” as the universal result. Diagnose the metadata target and projected topology rather than assuming the persistence rows disappeared. --- ## 11. Projection Provider Contracts Projection views support different use cases. The provider contract makes the intended contract explicit. | Provider contract | Main purpose | | ------------------------- | ----------------------------------------------------- | | `transactional_query` | Consumer/service projection of a transactional RAP BO | | `transactional_interface` | Stable BO interface intended for reuse and release | | `analytical_query` | Analytical query projection | These contracts are not interchangeable labels. ### 11.1 Transactional query Use for a consumer-specific service projection: ```abap define root view entity ZC_SalesOrderRequest provider contract transactional_query as projection on ZI_SalesOrderRequest ``` This projection can be paired with a behavior projection and exposed through a service definition. ### 11.2 Transactional interface Use when defining a formal BO interface intended as a stable reusable contract: ```abap define root view entity ZI_SalesOrderRequestAPI provider contract transactional_interface as projection on ZI_SalesOrderRequest ``` A formal RAP BO interface also requires the corresponding behavior-interface artifacts and release decisions. Merely naming a regular base entity `ZI_...` does not make it a released BO interface. ### 11.3 Naming conventions do not establish semantics Common project naming: ```text ZI_* interface/base-style CDS entity ZC_* consumption/service projection ZR_* root or reuse-oriented entity in some projects ``` These prefixes help humans but do not control RAP. The DDL syntax, provider contract, behavior definitions, and release contract establish the technical role. --- ## 12. Field Exposure and Information Boundaries ### 12.1 Excluding internal fields The base entity may need an internal processing field: ```abap Request.internal_processing_code as InternalProcessingCode ``` The service projection can omit it: ```abap define root view entity ZC_SalesOrderRequest provider contract transactional_query as projection on ZI_SalesOrderRequest { key RequestUUID, RequestNumber, SoldToParty, Status, TotalAmount, TransactionCurrency } ``` Omission reduces the field surface of this projection. It does not by itself establish the entire security model. DCL, modification authorization, released API boundaries, and service configuration must also be designed correctly. ### 12.2 Projection as consumer contract Create separate projections when consumers require genuinely different contracts: ```text Processor UI projection editable business fields, internal workflow status, processor actions Requester UI projection requester-visible fields and requester actions Integration API projection stable machine contract, API-safe navigation, no UI-only design ``` Avoid creating projections that differ only cosmetically if one stable contract and metadata extension would be sufficient. Every public contract creates lifecycle and compatibility responsibilities. ### 12.3 Do not put business invariants in the projection A projection can omit a field or operation, but another EML consumer or projection might still reach the base BO. Therefore rules such as these belong to base behavior: - submitted request must contain at least one valid item; - item product must exist; - requested quantity must be positive; - total amount must equal the sum of item amounts; - status transition must follow the permitted state machine. Projection is exposure. Behavior is enforcement. --- ## 13. Entered, Derived, and Technical Fields Classify every element before implementing the model: | Classification | Example | Source of truth | Typical behavior | | ----------------- | -------------------- | ----------------------- | ----------------------------------- | | Entered | `SoldToParty` | Consumer input | Editable, validated | | Entered | `RequestedQuantity` | Consumer input | Mandatory on create, validated | | Derived | `UnitPrice` | Pricing/reference logic | Read-only, determined | | Derived | `NetAmount` | Quantity × price logic | Read-only, determined | | Aggregate-derived | `TotalAmount` | Sum of item amounts | Read-only, determined from children | | Lifecycle | `Status` | BO state machine | Changed by controlled action | | Technical | `RequestUUID` | Numbering/framework | Read-only, generated | | Administrative | `LocalLastChangedAt` | RAP runtime | Read-only, ETag candidate | The CDS model exposes the typed fields. The behavior definition and behavior pool turn this classification into executable controls. Incorrect pseudo-syntax: ```abap TotalAmount [derived] UnitPrice [entered] ``` RAP does not use these brackets. A real implementation combines: ```text CDS element + behavior field control + determination/validation/action + UI metadata where useful ``` --- ## 14. Access Control Boundary ### 14.1 Authorization-check annotation ```abap @AccessControl.authorizationCheck: #CHECK ``` This annotation tells CDS access control how access to the entity should be handled. A DCL role can restrict result rows when that entity is accessed as the authorization-relevant entity. It is not equivalent to RAP modification authorization. ```text CDS DCL Which rows can the user read through this CDS access? RAP authorization control May the user create, update, delete, or execute this operation? ``` ### 14.2 Access control is evaluated at the accessed entity Do not assume a lower CDS entity's DCL is automatically inherited through every higher-level CDS entity. Define and test authorization at the actual consumption entity and service boundary. ### 14.3 Association exposure and data exposure Publishing `_Customer` allows consumers to request navigation if the service exposes a reachable target. It is therefore part of the information surface. Review associations with the same care as scalar fields. --- ## 15. Query Semantics and Performance ### 15.1 Association-on-demand does not remove SQL cost ```text Association only exposed no target join required until consumer uses navigation/path Target field selected through path database join is generated ``` Evaluate the generated query when a projection contains: - multiple to-many paths; - calculated elements over joined data; - filters on associated entities; - large text/value-help targets; - nested expansions from OData; - associations whose declared cardinality does not match data. ### 15.2 To-many joins can change result grain Suppose one item has two schedule lines: ```text Item 10 NetAmount 100 Schedule 1 Schedule 2 ``` Joining item to schedule-line grain yields two rows containing the same item amount. A naïve sum returns 200 instead of 100. The problem is not fixed by declaring the item key in CDS. The query must aggregate at the correct grain or separate item and schedule-line measures. ### 15.3 Prefer explicit grain For each entity, document: ```text One row represents: one Sales Order Request item Key: ItemUUID Parent identity: RequestUUID Expected association multiplicity: one Product, many Schedules ``` Most CDS duplication defects are grain defects disguised as join defects. ### 15.4 Measure before denormalizing Do not copy Customer or Product master fields into the transactional CDS model solely to avoid associations. Copy data only when the transaction must preserve a historical snapshot or the domain explicitly owns that value. Otherwise use released associations and diagnose the actual SQL plan before denormalizing. --- ## 16. Clean-Core and Released-Source Design In ABAP Cloud, use released CDS entities, released RAP BO interfaces, and other released APIs as dependencies. A technically reachable classic table or class is not automatically an allowed clean-core dependency. ```text Custom RAP BO ├── own persistence tables ├── released Customer/Product reference CDS entities ├── released conversion or business APIs └── explicit projection and release contract ``` For an SD-inspired portfolio model, distinguish clearly between: - a custom training object that resembles a Sales Order Request; - a projection over released SAP business data; - a released transactional SAP BO interface used through EML; - direct access to classic SD persistence such as `VBAK` or `VBAP`. These are different architectures. Do not present a custom RAP aggregate as an extension of the standard SAP Sales Order unless the target system and released extension contracts actually support that design. --- ## 17. Activation and Dependency Order A practical bottom-up activation sequence is: ```text 1. Data elements/domains and database tables 2. Independent reference CDS entities 3. Child base CDS entities where dependencies allow 4. Root base CDS and completed composition topology 5. Base behavior definition and behavior pool 6. Child projection views 7. Root projection and redirections 8. Behavior projection 9. Metadata extension 10. Service definition and service binding ``` Circular root/child CDS dependencies are handled by the ADT activation process and the repository object's supported creation flow. Activate related objects together when necessary. Activation: - performs syntax and dependency checks; - creates an active repository version; - does not publish an OData endpoint; - does not transport the artifact to another system; - does not deploy a separate Fiori application. --- ## 18. Technical Diagnostics ### 18.1 Field is missing from OData metadata Trace from the service inward: ```text Service Definition Is the intended projection entity exposed? │ ▼ CDS Projection Is the field in the projection list? │ ▼ Base CDS Does the field exist and activate with the expected type? │ ▼ Service Binding Is the correct active service version published? ``` If the field exists in the base entity but not the projection, omission is working as designed. ### 18.2 Navigation target is incorrect or absent Check: 1. root composition exists and is exposed in the base entity; 2. child contains the correct `association to parent`; 3. projection root redirects to the projected composition child; 4. projection child redirects to the projected parent; 5. both projected nodes are exposed where the service requires them; 6. service metadata points to the projected entity set; 7. `ON` conditions use the correct projected keys. Do not begin by inspecting database rows if the navigation is absent from `$metadata`; that is first a modeling or exposure defect. ### 18.3 Duplicate root or item rows Check: 1. the declared row grain; 2. key uniqueness in the actual query result; 3. to-many associations consumed as path fields; 4. joins missing part of their conditions; 5. incorrect cardinality declarations; 6. language-dependent text joins without a language condition; 7. aggregation after a one-to-many expansion. ### 18.4 Association returns no target Check: ```text Source foreign-key value → target key format and conversion → complete ON condition → client/language/context fields → target data exists → DCL visibility → service target exposure ``` An empty association target is not automatically a redirection problem. ### 18.5 Amount displays incorrectly Verify: 1. amount field type and decimal definition; 2. currency element type; 3. exact annotation element name and case; 4. both fields are projected; 5. metadata contains the semantic dependency; 6. stored currency/value pair is internally consistent; 7. no missing currency conversion is being mistaken for formatting. ### 18.6 Consumer can edit a derived field The fix is not a CDS marker. Check the base behavior field control and behavior projection, then verify the service metadata. Keep the derivation in one backend behavior path so UI, API, and EML consumers observe the same result. --- ## 19. Common Modeling Errors ### 19.1 Defining the child as another root Incorrect: ```abap define root view entity ZI_SalesOrderItem ... ``` Use a non-root view entity with `association to parent` when Item is owned by the Sales Order Request aggregate. ### 19.2 Using singular composition cardinality for a collection Incorrect for a normal order: ```abap composition [0..1] of ZI_SalesOrderItem as _Items ``` Use `[0..*]` when the root may contain multiple items. ### 19.3 Exposing an association name that was never defined Incorrect: ```abap _SalesOrderRequest, _Product ``` when the definitions use `_Request` and contain no `_Product` association. Association aliases must be consistent across the definition, select list, behavior model, projection, and code. ### 19.4 Repeating scalar fields Incorrect: ```abap Request.status as Status, Status, ``` The first line already defines the projected element. A duplicate element name causes an activation problem. ### 19.5 Referencing persistence aliases inside a projection Incorrect: ```abap define root view entity ZC_SalesOrderRequest as projection on ZI_SalesOrderRequest { Request.request_uuid as RequestUUID } ``` The projection source is `ZI_SalesOrderRequest`, so project its element names: ```abap { key RequestUUID, RequestNumber } ``` ### 19.6 Treating semantic annotations as calculations `@Semantics.amount.currencyCode` does not calculate an amount. Declare a RAP determination or use another appropriate calculation source. ### 19.7 Assuming a value help enforces the invariant A consumer can bypass the UI. Preserve the value help for usability and enforce the rule through backend validation. ### 19.8 Treating projection omission as complete security Omitting a field narrows one contract. It does not replace DCL, RAP authorization, released-object governance, or secure service design. ### 19.9 Treating cardinality as observed row count Cardinality is a statement of the expected relationship, not a live counter. Test the data and `ON` condition before relying on it. ### 19.10 Treating names as framework configuration `ZI_`, `ZC_`, `_Items`, and `_Customer` communicate intent but do not activate RAP features. Keywords, provider contracts, behavior definitions, and service artifacts provide the executable contract. --- ## 20. Design Review Checklist ### Base model - Each entity has a documented row grain. - CDS keys match the actual result uniqueness. - Technical column aliases express stable business meaning. - The root represents the aggregate consistency boundary. - Owned children use composition. - Each composition child has the correct association to parent. - Independent master/reference objects use ordinary associations. - Association `ON` conditions include the complete identity. - Cardinalities describe real data expectations. - Amount/currency and quantity/unit pairs are modeled together. - Technical and administrative fields are available where behavior needs them. ### Projection model - Provider contract is explicit. - Only consumer-relevant fields and associations are exposed. - Keys required for identity remain projected. - Root/child associations are redirected to projected nodes. - Internal fields are omitted unless the consumer genuinely needs them. - The projection does not attempt to enforce base business invariants. - A separate projection exists only when it represents a real contract. ### Runtime and operations - DCL is defined and tested at the actual accessed entity. - Behavior field control protects derived and technical fields. - Backend validation protects reference integrity and state-dependent rules. - To-many navigation does not silently change the result grain. - Generated SQL and OData expansions are measured for important access paths. - Dependencies use released APIs when ABAP Cloud or clean-core rules require it. --- ## 21. Compact Model Map ```text PERSISTENCE zsor_request zsor_item request_uuid item_uuid request_number request_uuid sold_to_party product status requested_quantity total_amount unit_price currency net_amount │ │ ▼ ▼ BASE CDS BUSINESS OBJECT ZI_SalesOrderRequest ZI_SalesOrderItem root child key RequestUUID key ItemUUID composition _Items ───────────────────> association to parent _Request association _Customer association _Product TotalAmount + Currency Quantity + Unit NetAmount + Currency │ │ ▼ ▼ CONSUMER PROJECTION ZC_SalesOrderRequest ZC_SalesOrderItem transactional_query transactional_query selected fields selected fields _Items redirected ───────────────────> projected child <──────────────── _Request redirected │ ▼ BEHAVIOR PROJECTION + SERVICE EXPOSURE ``` The model should be read as three separate decisions: ```text Composition decides ownership. Association decides navigation to an independent entity. Projection decides which part of the reusable model a consumer receives. ``` 47:T8df,SAP RAP CDS Data Modeling and Projection Design — Technical Reference This document explains how ABAP CDS defines the structural and semantic model of a RAP business object and how CDS projection views adapt that model for a specific consumer. It focuses on entity boundaries, keys, compositions, associations, cardinality, semantic annotations, projection contracts, and navigation topology. The central design principle is: The base CDS model describes the reusable business object and its relationships. A CDS projection selects and adapts that model for one consumption scenario. Neither layer replaces the behavior definition, which owns the transactional capabilities and business rules. Primary SAP sources: - SAP Help — Defining the Data Model in CDS Views - SAP Help — CDS View Entities - SAP Help — Associations - SAP Help — Projection Views - SAP Help — Creating CDS View Entities for RAP - SAP Help — CDS Annotations for RAP --- 1. Position of CDS in RAP text Database tables or released data sources │ ▼ Base CDS view entities fields, keys, aliases, compositions, associations, semantics │ ├──────── Base Behavior Definition │ operations and transactional contract │ ▼ CDS projection views consumer-specific field and navigation shape │ ├──────── Behavior Projection │ consumer-visible operations │ ├──────── Metadata Extension │ presentation metadata │ ▼ Service Definition and Service Binding CDS is responsible for the data model. It can express: - entity elements and their ABAP Dictionary types; - semantic keys exposed by the entity; - aliases that give technical columns business-oriented names; - calculations supported by the CDS language; - root, child, and reference relationships; - semantic dependencies such as amount/currency and quantity/unit; - reusable navigation paths; - annotations consumed by the ABAP runtime and other frameworks. CDS does not by itself implement: - create, update, or delete behavior; - validations, determinations, actions, or feature control; - transactional buffering and save handling; - a custom authorization decision for a modification; - an OData endpoint. Those responsibilities belong to other RAP artifacts. --- 2.48:Tbd2,# SAP RAP CDS Data Modeling and Projection Design — Technical Reference This document explains how ABAP CDS defines the structural and semantic model of a RAP business object and how CDS projection views adapt that model for a specific consumer. It focuses on entity boundaries, keys, compositions, associations, cardinality, semantic annotations, projection contracts, and navigation topology. The central design principle is: > The base CDS model describes the reusable business object and its > relationships. A CDS projection selects and adapts that model for one > consumption scenario. Neither layer replaces the behavior definition, which > owns the transactional capabilities and business rules. Primary SAP sources: - [SAP Help — Defining the Data Model in CDS Views](https://help.sap.com/docs/abap-cloud/abap-rap/defining-data-model-in-cds-views) - [SAP Help — CDS View Entities](https://help.sap.com/docs/abap-cloud/abap-data-models/cds-view-entities-8b3e8e8b8797432abecd7d1fbb6d5c12) - [SAP Help — Associations](https://help.sap.com/docs/abap-cloud/abap-data-models/cds-associations) - [SAP Help — Projection Views](https://help.sap.com/docs/abap-cloud/abap-data-models/cds-projection-views) - [SAP Help — Creating CDS View Entities for RAP](https://help.sap.com/docs/abap-cloud/abap-rap/creating-cds-view-entities) - [SAP Help — CDS Annotations for RAP](https://help.sap.com/docs/abap-cloud/abap-rap/cds-annotations) --- ## 1. Position of CDS in RAP ```text Database tables or released data sources │ ▼ Base CDS view entities fields, keys, aliases, compositions, associations, semantics │ ├──────── Base Behavior Definition │ operations and transactional contract │ ▼ CDS projection views consumer-specific field and navigation shape │ ├──────── Behavior Projection │ consumer-visible operations │ ├──────── Metadata Extension │ presentation metadata │ ▼ Service Definition and Service Binding ``` CDS is responsible for the data model. It can express: - entity elements and their ABAP Dictionary types; - semantic keys exposed by the entity; - aliases that give technical columns business-oriented names; - calculations supported by the CDS language; - root, child, and reference relationships; - semantic dependencies such as amount/currency and quantity/unit; - reusable navigation paths; - annotations consumed by the ABAP runtime and other frameworks. CDS does not by itself implement: - create, update, or delete behavior; - validations, determinations, actions, or feature control; - transactional buffering and save handling; - a custom authorization decision for a modification; - an OData endpoint.49:Ta9fa, # SAP RAP Behavior Modeling and Implementation — Technical Reference This document explains how a RAP business object becomes transactional. It covers the base behavior definition, behavior projection, managed and unmanaged implementation choices, behavior pools, standard operations, field control, determinations, validations, actions, prechecks, feature control, EML, and RAP response structures. The central implementation principle is: > The behavior definition declares what the business object can do. The RAP > runtime enforces the declared contract and supplies framework behavior. The > behavior pool implements only the application-specific logic required by > that contract. The behavior projection selects which capabilities a consumer > may use. Primary SAP sources: - [SAP Help — Defining Standard Behavior](https://help.sap.com/docs/abap-cloud/abap-rap/defining-standard-behavior) - [SAP Help — Implementing Behavior](https://help.sap.com/docs/abap-cloud/abap-rap/implementing-behavior-of-business-object) - [SAP Help — Projecting Behavior](https://help.sap.com/docs/abap-cloud/abap-rap/projecting-behavior) - [SAP Help — Determinations](https://help.sap.com/docs/abap-cloud/abap-rap/determinations) - [SAP Help — Validation Implementation](https://help.sap.com/docs/abap-cloud/abap-rap/validation-implementation) - [SAP Help — Action Runtime](https://help.sap.com/docs/abap-cloud/abap-rap/action-runtime) - [SAP Help — Feature Control](https://help.sap.com/docs/abap-cloud/abap-rap/implementation-contract-feature-control) --- ## 1. Position of Behavior in RAP ```text CDS data model entities, fields, composition tree, associations │ ▼ Base Behavior Definition transactional capabilities and implementation contract │ ├──────── RAP managed runtime │ generic CRUD, buffer, mapping, │ locking and ETag support │ └──────── Behavior Pool custom rules and operations │ ▼ Behavior Projection capabilities exposed for one consumer │ ▼ OData service or EML consumer ``` The behavior definition, often abbreviated as BDEF, is attached to the CDS business-object model. It declares: - managed, unmanaged, projection, or interface behavior; - standard create, update, and delete operations; - create-by-association for child nodes; - persistence tables and field mappings; - locks and ETags; - static and dynamic field characteristics; - determinations and validations; - actions and functions; - authorization and feature-control hooks; - draft behavior where applicable. The BDEF contains declarations, not the ABAP implementation of custom business logic. --- ## 2. Base Behavior Definition Versus Behavior Projection ### 2.1 Base behavior definition The base BDEF defines the reusable transactional contract: ```abap managed implementation in class zbp_i_salesorderrequest unique; strict ( 2 ); define behavior for ZI_SalesOrderRequest alias SalesOrderRequest persistent table zsor_request lock master authorization master ( instance ) etag master LocalLastChangedAt { create; update; delete; association _Items { create; } field ( numbering : managed, readonly ) RequestUUID; field ( readonly ) RequestNumber, Status, TotalAmount, LocalLastChangedAt; field ( mandatory : create ) SoldToParty; determination DeriveAmounts on modify { create; field TransactionCurrency; } validation ValidateCustomer on save { create; field SoldToParty; } action ( features : instance ) Submit result [1] $self; mapping for zsor_request { RequestUUID = request_uuid; RequestNumber = request_number; SoldToParty = sold_to_party; Status = status; TotalAmount = total_amount; TransactionCurrency = transaction_currency; LocalLastChangedAt = local_last_changed_at; } } define behavior for ZI_SalesOrderItem alias SalesOrderItem persistent table zsor_item lock dependent by _Request authorization dependent by _Request etag master LocalLastChangedAt { update; delete; field ( numbering : managed, readonly ) ItemUUID; field ( readonly ) RequestUUID, UnitPrice, NetAmount, TransactionCurrency, LocalLastChangedAt; field ( mandatory : create ) Product, RequestedQuantity; determination DeriveItemAmount on modify { create; field RequestedQuantity, UnitPrice; } validation ValidateProduct on save { create; field Product; } validation ValidateQuantity on save { create; field RequestedQuantity; } association _Request; association _Product; mapping for zsor_item { ItemUUID = item_uuid; RequestUUID = request_uuid; Product = product; RequestedQuantity = requested_quantity; QuantityUnit = quantity_unit; UnitPrice = unit_price; NetAmount = net_amount; TransactionCurrency = transaction_currency; LocalLastChangedAt = local_last_changed_at; } } ``` ### 2.2 Behavior projection The behavior projection selects capabilities from the underlying BO for one consumption contract: ```abap projection; strict ( 2 ); define behavior for ZC_SalesOrderRequest alias SalesOrderRequest use etag { use create; use update; use delete; use action Submit; use association _Items { create; } } define behavior for ZC_SalesOrderItem alias SalesOrderItem use etag { use update; use delete; use association _Request; use association _Product; } ``` The projection does not contain the implementation of `Submit`, a validation, or a determination. It can only expose behavior supported by the underlying contract. ### 2.3 Responsibility boundary | Artifact | Technical responsibility | | ------------------- | -------------------------------------- | | Base CDS | Entity data model and relationships | | Base BDEF | Reusable transactional contract | | Behavior pool | Custom ABAP implementation | | CDS projection | Consumer-visible fields and navigation | | Behavior projection | Consumer-visible operations | | Metadata extension | UI presentation and action placement | A field being present in a CDS projection does not make it editable. Editability is governed by behavior field control and the exposed operation contract. --- ## 3. Behavior Entity Aliases ```abap define behavior for ZI_SalesOrderRequest alias SalesOrderRequest ``` `SalesOrderRequest` is the BDEF entity alias. EML uses it to identify a node inside the business object: ```abap READ ENTITIES OF ZI_SalesOrderRequest IN LOCAL MODE ENTITY SalesOrderRequest ... ``` The alias is not random at the call site. `ENTITY UpdateRequest` is valid only if `UpdateRequest` is the declared alias of a BO entity in that behavior contract. One CDS entity belongs to one base behavior contract. Defining the same CDS entity twice with aliases such as `Travel` and `UpdateTravel` does not create two independent behavior modes. Different business operations are declared as operations or actions on the one entity behavior: ```abap define behavior for ZI_Travel alias Travel { update; action AcceptTravel result [1] $self; action RejectTravel result [1] $self; } ``` --- ## 4. Managed and Unmanaged Implementation ### 4.1 Managed behavior Managed RAP supplies generic transactional processing for standard operations. Depending on the model and declarations, the framework handles: - standard create, update, and delete; - create-by-association; - transactional buffering; - persistence mapping; - managed UUID numbering; - lock handling; - ETag handling; - orchestration of determinations, validations, and save processing. The developer still owns: - the CDS and behavior model; - field control; - validations and determinations; - actions and functions; - authorization and feature control; - business messages; - integration with other BOs or released APIs; - tests and operational diagnostics. Managed does not mean “no ABAP.” It means the framework owns generic CRUD and transaction mechanics while application code owns business-specific behavior. ### 4.2 Unmanaged behavior Unmanaged RAP is appropriate when the application must control the operational implementation, commonly because it: - reuses an existing transactional API or legacy business object; - has persistence that does not fit managed table handling; - requires custom buffering or locking; - maps operations to BAPIs, function modules, or other released capabilities; - has an established save protocol that RAP must wrap. The developer implements operation handlers such as create, update, delete, read-by-association, create-by-association, and locking as required by the contract. Unmanaged does not mean direct SQL is automatically appropriate. The wrapped application contract, released APIs, LUW rules, and clean-core restrictions still apply. ### 4.3 Additional save Managed with additional save keeps managed interaction and persistence while allowing controlled save-phase additions such as writing an audit record or outbox entry. It is not a reason to duplicate ordinary managed table updates. Detailed save-sequence and additional-save design belongs to the transaction and draft reference. ### 4.4 Selection guide ```text New custom persistence with standard CRUD → managed Existing released transactional API owns the real operation → unmanaged wrapper or façade Managed persistence plus controlled post-save integration record → managed with additional save, where supported and appropriate ``` Choose by ownership of transaction mechanics, not by which syntax appears shorter. --- ## 5. Strict Mode ```abap strict ( 2 ); ``` Strict mode applies the current RAP contract rules and syntax restrictions to the behavior definition and its implementation. It improves consistency and helps prevent reliance on obsolete or ambiguous behavior patterns. Strict mode does not provide: - CRUD; - validation; - determination; - authorization; - locking; - persistence; - business correctness. Those features still require the corresponding implementation type and declarations. Use the strongest strict mode supported by the target ABAP release and keep the behavior artifacts internally consistent. --- ## 6. Standard Operations and Child Creation ### 6.1 Root operations ```abap create; update; delete; ``` These lines add standard operations to the BO contract. In a managed BO, the framework can implement their generic persistence behavior. ### 6.2 Create-by-association A composition child is created through its parent relationship: ```abap define behavior for ZI_SalesOrderRequest alias SalesOrderRequest { association _Items { create; } } ``` The child behavior normally does not declare standalone `create`: ```abap define behavior for ZI_SalesOrderItem alias SalesOrderItem { update; delete; association _Request; } ``` This preserves aggregate ownership: ```text Create Request root create Create Item for Request create by association through SalesOrderRequest._Items Create Item with no Request not part of the BO contract ``` ### 6.3 Operation declaration is not consumer exposure An operation must pass through both layers: ```text Base BDEF declares update │ ▼ Behavior Projection uses update │ ▼ Consumer sees update capability ``` If the base BDEF supports `delete` but the behavior projection omits `use delete`, that service consumer cannot request delete through that projection. --- ## 7. Persistence and Mapping ### 7.1 Persistent table ```abap define behavior for ZI_SalesOrderItem alias SalesOrderItem persistent table zsor_item ``` The persistent-table declaration connects a managed entity to durable storage. It does not mean every CDS element is automatically writable. Field control, mapping, and framework-managed fields still apply. ### 7.2 Mapping block ```abap mapping for zsor_item { ItemUUID = item_uuid; RequestUUID = request_uuid; Product = product; RequestedQuantity = requested_quantity; QuantityUnit = quantity_unit; UnitPrice = unit_price; NetAmount = net_amount; TransactionCurrency = transaction_currency; } ``` The left side is the CDS element. The right side is the persistence field. This mapping is unrelated to EML `MAPPED` output: ```text BDEF mapping for table CDS field name ↔ persistence column name EML MAPPED response client correlation ID ↔ generated/final entity key ``` ### 7.3 Read-only and generated fields Technical UUID: ```abap field ( numbering : managed, readonly ) ItemUUID; ``` Managed early numbering assigns the key during the create interaction so the new instance can be addressed immediately. A `RAW(16)` UUID is a common key type for this pattern. Read-only means the external consumer cannot change the field. The framework or behavior implementation may still set it through its defined internal mechanism. --- ## 8. Field Characteristics ### 8.1 Read-only ```abap field ( readonly ) RequestNumber, TotalAmount, LocalLastChangedAt; ``` Use read-only for fields whose source of truth is the framework or backend logic. Examples include technical keys, administrative timestamps, calculated amounts, and controlled status fields. ### 8.2 Mandatory on create ```abap field ( mandatory : create ) SoldToParty, TransactionCurrency; ``` This describes a structural create requirement to RAP consumers. It is not a substitute for semantic validation. ```text mandatory : create field must be supplied as part of creation contract validation supplied value must satisfy a business invariant ``` For example, `SoldToParty` can be supplied but reference a nonexistent or blocked Customer. Backend validation must still reject that state. ### 8.3 Dynamic field control Field mutability can depend on instance state: ```abap field ( features : instance ) SoldToParty, TransactionCurrency; ``` The behavior pool returns permission markers from an instance-feature method. A submitted request can make commercial fields read-only while a draft request keeps them editable. Dynamic field control represents availability, not authorization. If the rule depends on user identity or permission, implement authorization control. --- ## 9. Behavior Pool Architecture ### 9.1 Global container and local classes A behavior pool is a special global ABAP class declared for the behavior of a root CDS entity. Its relevant implementation normally resides in local classes: ```abap CLASS lhc_SalesOrderRequest DEFINITION INHERITING FROM cl_abap_behavior_handler. PRIVATE SECTION. METHODS DeriveAmounts FOR DETERMINE ON MODIFY IMPORTING keys FOR SalesOrderRequest~DeriveAmounts. METHODS ValidateCustomer FOR VALIDATE ON SAVE IMPORTING keys FOR SalesOrderRequest~ValidateCustomer. METHODS Submit FOR MODIFY IMPORTING keys FOR ACTION SalesOrderRequest~Submit RESULT result. METHODS GetInstanceFeatures FOR INSTANCE FEATURES IMPORTING keys REQUEST requested_features FOR SalesOrderRequest RESULT result. ENDCLASS. ``` Handler classes inherit from `CL_ABAP_BEHAVIOR_HANDLER`. Saver classes inherit from the appropriate RAP saver base class when the implementation type requires save callbacks. ### 9.2 Framework invocation The application does not instantiate `lhc_SalesOrderRequest` directly. RAP generates and invokes the handler signatures from BDEF declarations. ```text BDEF action Submit │ ▼ generates contract METHODS Submit FOR MODIFY ... │ ▼ runtime dispatch RAP calls handler when consumer invokes action ``` ### 9.3 Do not keep transaction state in handler instance attributes Handler and saver instances can be reinstantiated during nested calls. Do not assume an instance attribute written by one method will remain available to a later method. Use: - RAP transactional state; - EML reads and modifications; - method-local data; - defined saver mechanisms; - dedicated stable helper abstractions where appropriate. Do not use behavior-handler instance memory as an undocumented transaction buffer. ### 9.4 Keep orchestration separate from domain calculation A strong behavior method has two layers: ```text RAP adapter layer read keys and BO state call domain calculation write changes through EML map failures and messages Domain helper calculate amount evaluate status transition validate date interval ``` Pure calculations are easier to unit-test when separated from EML orchestration. --- ## 10. Determinations ### 10.1 Purpose A determination automatically modifies BO state when declared trigger conditions occur. ```abap determination DeriveItemAmount on modify { create; field RequestedQuantity, UnitPrice; } ``` Typical uses: - calculate `NetAmount` after quantity or price changes; - copy root currency to a newly created child; - derive a default status; - update a root aggregate from child data. A determination is not a guard. It changes or derives state. ### 10.2 Runtime requirements Determinations must be designed for RAP runtime semantics: - execution order between separate determinations is not fixed; - each determination must work independently; - repeated execution under the same state must give the same result; - trigger fields must include every input that can change the calculation; - logic must work for active and draft keys when the BO supports both; - a determination does not have a `FAILED` response like a validation. Avoid two determinations that silently depend on one another: ```text Determination A calculates Item.NetAmount Determination B assumes A already ran and calculates Request.TotalAmount ``` Because ordering is not guaranteed, either make B read a state that is always valid or centralize the dependent derivation in one orchestrated calculation. ### 10.3 Business flow for item amount derivation ```text 1. Consumer changes quantity or unit price. 2. RAP places the change in the transactional buffer. 3. Trigger condition invokes DeriveItemAmount. 4. Handler reads current item state from the buffer. 5. Domain logic calculates quantity × price. 6. Handler updates NetAmount in local mode. 7. Consumer receives or rereads the derived value. 8. Save validation later decides whether the complete BO is valid. ``` ### 10.4 Representative implementation ```abap METHOD DeriveItemAmount. READ ENTITIES OF ZI_SalesOrderRequest IN LOCAL MODE ENTITY SalesOrderItem FIELDS ( RequestedQuantity UnitPrice ) WITH CORRESPONDING #( keys ) RESULT DATA(items). MODIFY ENTITIES OF ZI_SalesOrderRequest IN LOCAL MODE ENTITY SalesOrderItem UPDATE FIELDS ( NetAmount ) WITH VALUE #( FOR item IN items ( %tky = item-%tky NetAmount = item-RequestedQuantity * item-UnitPrice ) ) REPORTED DATA(update_reported). reported = CORRESPONDING #( DEEP update_reported ). ENDMETHOD. ``` Code-to-business mapping: | Code | Business meaning | | ---------------------------------- | ------------------------------------------------------------------ | | `READ ENTITIES ... IN LOCAL MODE` | Read the current item values within this BO transaction | | `FIELDS (...)` | Fetch only calculation inputs | | `WITH CORRESPONDING #( keys )` | Convert the trigger-key table into the typed EML request shape | | `RESULT DATA(items)` | Hold current buffered item state | | `UPDATE FIELDS ( NetAmount )` | Restrict the internal modification to the derived field | | `VALUE #( FOR item IN items ... )` | Construct one update row per item explicitly | | `%tky = item-%tky` | Preserve the exact transactional identity, including draft context | | `REPORTED` | Preserve messages returned by nested EML processing | `WITH VALUE #( ... )` is used because the update payload must be constructed: it contains transactional identity plus a newly calculated value. ### 10.5 Why `ENTITIES OF` names the root ```abap MODIFY ENTITIES OF ZI_SalesOrderRequest ENTITY SalesOrderItem ``` `ZI_SalesOrderRequest` identifies the business-object behavior contract. `SalesOrderItem` identifies one entity alias inside that BO. This is correct even though the operation changes an item rather than the root. --- ## 11. Validations ### 11.1 Purpose A validation checks the BO state and rejects invalid instances during save processing. ```abap validation ValidateCustomer on save { create; field SoldToParty; } ``` Typical invariants: - Customer or Product reference must exist; - quantity must be positive; - requested date must be permitted; - submitted request must contain at least one valid item; - status transition must not violate the lifecycle; - item and root currencies must be consistent. ### 11.2 Determination versus validation ```text Determination derives or changes BO state result: modified buffer and optional messages Validation evaluates whether BO state is acceptable result: pass, or FAILED plus REPORTED messages ``` Do not use a determination merely to reject an invalid value. Do not use a validation to calculate a field that must remain derived throughout editing. ### 11.3 Validation business flow ```text 1. Consumer requests save. 2. RAP invokes validations whose triggers apply. 3. Handler reads current BO state through local EML. 4. Handler obtains trusted reference data if required. 5. Each invalid instance is appended to FAILED. 6. A consumer-facing message is appended to REPORTED. 7. RAP rejects the affected save and retains or rolls back state according to the transaction/draft lifecycle. ``` ### 11.4 Simplified Customer validation ```abap METHOD ValidateCustomer. READ ENTITIES OF ZI_SalesOrderRequest IN LOCAL MODE ENTITY SalesOrderRequest FIELDS ( SoldToParty ) WITH CORRESPONDING #( keys ) RESULT DATA(requests). LOOP AT requests INTO DATA(request). APPEND VALUE #( %tky = request-%tky %state_area = 'VALIDATE_CUSTOMER' ) TO reported-SalesOrderRequest. SELECT SINGLE FROM ZI_CustomerReference FIELDS CustomerID WHERE CustomerID = @request-SoldToParty INTO @DATA(customer_id). IF request-SoldToParty IS INITIAL OR customer_id IS INITIAL. APPEND VALUE #( %tky = request-%tky ) TO failed-SalesOrderRequest. APPEND VALUE #( %tky = request-%tky %state_area = 'VALIDATE_CUSTOMER' %msg = NEW zcm_salesorderrequest( severity = if_abap_behv_message=>severity-error textid = zcm_salesorderrequest=>customer_unknown customerid = request-SoldToParty ) %element-SoldToParty = if_abap_behv=>mk-on ) TO reported-SalesOrderRequest. ENDIF. ENDLOOP. ENDMETHOD. ``` For many instances, collect distinct non-initial Customer IDs and issue one set-oriented read instead of `SELECT SINGLE` inside the loop. The simplified version exposes the control flow; the production version should avoid N+1 database access. ### 11.5 Meaning of response components ```text failed-SalesOrderRequest marks the exact instances whose operation must fail reported-SalesOrderRequest carries state messages and field markers for the consumer ``` Appending only a message to `REPORTED` does not necessarily reject an operation. `FAILED` is the validation failure signal. For authorization methods, returned authorization values decide whether the operation is allowed. --- ## 12. RAP Messages ### 12.1 Message class role A behavior message class commonly: - inherits from `CX_STATIC_CHECK`; - implements `IF_ABAP_BEHV_MESSAGE`; - implements T100 message interfaces; - defines text IDs and placeholder attributes; - receives severity and business values in its constructor. Example construction: ```abap %msg = NEW zcm_salesorderrequest( severity = if_abap_behv_message=>severity-error textid = zcm_salesorderrequest=>customer_unknown customerid = request-SoldToParty ) ``` The message object converts a technical failure into a stable, localizable business message. ### 12.2 `%tky` `%tky` is the transactional key generated by the RAP type system. It identifies the exact entity instance in the current transactional context. In a draft-enabled BO, it also carries draft identity information such as `%is_draft`. Prefer `%tky` in behavior logic when matching and returning instances. A plain business key may not distinguish active from draft state. ### 12.3 `%state_area` `%state_area` groups a state message by validation or business concern: ```abap %state_area = 'VALIDATE_CUSTOMER' ``` A message row with the same `%tky` and `%state_area` but no `%msg` clears older state messages for that area before the current validation result is reported. This prevents an old “Customer unknown” error from remaining after the user corrects the Customer. ### 12.4 `%element` ```abap %element-SoldToParty = if_abap_behv=>mk-on ``` The field marker connects the message to a specific element. Metadata-driven consumers can highlight the field rather than displaying only a document-level error. ### 12.5 `%msg` `%msg` carries the RAP message object. It can be used for error, warning, information, or success messages where the contract permits. It is not limited to failed cases. --- ## 13. Actions ### 13.1 Purpose An action is a named, non-standard modifying operation that expresses business intent: ```abap action ( features : instance ) Submit result [1] $self; action ( features : instance ) Cancel result [1] $self; ``` Actions are preferable to exposing arbitrary status editing: ```text Direct Status update consumer chooses any raw value Submit action backend evaluates transition, changes status, derives dependent state, returns messages, and exposes a stable business command ``` ### 13.2 Submit workflow ```text 1. Consumer invokes Submit for selected request keys. 2. RAP dispatches to the Submit handler. 3. Handler reads current buffered request and item state. 4. Handler checks action-specific preconditions. 5. Invalid instances are returned in FAILED with REPORTED messages. 6. Valid instances are updated through EML in local mode. 7. Handler rereads the changed instances. 8. Handler builds `result` using `%tky` and `%param`. 9. RAP later runs save validations and the save sequence. ``` ### 13.3 Representative action implementation ```abap METHOD Submit. MODIFY ENTITIES OF ZI_SalesOrderRequest IN LOCAL MODE ENTITY SalesOrderRequest UPDATE FIELDS ( Status ) WITH VALUE #( FOR key IN keys ( %tky = key-%tky Status = zif_sor_status=>submitted ) ) FAILED failed REPORTED reported. READ ENTITIES OF ZI_SalesOrderRequest IN LOCAL MODE ENTITY SalesOrderRequest ALL FIELDS WITH CORRESPONDING #( keys ) RESULT DATA(requests). result = VALUE #( FOR request IN requests ( %tky = request-%tky %param = request ) ). ENDMETHOD. ``` The first EML request changes buffered state. The read retrieves the resulting representation. `%param` carries the action result declared as `$self`. ### 13.4 Why update uses `VALUE` and read uses `CORRESPONDING` ```abap WITH VALUE #( FOR key IN keys ( %tky = key-%tky Status = ... ) ) ``` The update payload contains a new value that does not already exist in `keys`, so the method constructs rows explicitly. ```abap WITH CORRESPONDING #( keys ) ``` The read request only needs matching key components already present in `keys`, so a name-based type conversion is sufficient. The choice follows the required payload, not a special update-versus-read syntax rule. --- ## 14. Prechecks and Save Validations ### 14.1 Precheck A precheck evaluates a modify request before the requested change is accepted into transactional state. It is useful when the incoming delta itself must be rejected early. Examples: - prevent an update to an immutable external reference; - reject a requested operation based on the before-image and incoming values; - avoid accepting a change that must never enter the buffer. ### 14.2 Validation on save An on-save validation evaluates the coherent BO state before persistence. It is appropriate for invariants that depend on multiple fields or child instances. Examples: - submitted request must contain at least one valid item; - begin date must not be after end date; - aggregate total must match item state; - Customer/Product references must be valid at save time. ### 14.3 Boundary ```text Precheck incoming request + relevant current state rejects before accepting the modification Validation on save resulting transactional BO state rejects before persistence ``` A precheck does not “pass data to a validation.” They are separate runtime contracts. Use each at the phase where its evidence is available. --- ## 15. Feature Control ### 15.1 Purpose Feature control determines whether fields, standard operations, associations, actions, or functions are available. It can be global or instance-specific. ```abap action ( features : instance ) Submit result [1] $self; ``` Representative implementation: ```abap METHOD GetInstanceFeatures. READ ENTITIES OF ZI_SalesOrderRequest IN LOCAL MODE ENTITY SalesOrderRequest FIELDS ( Status ) WITH CORRESPONDING #( keys ) RESULT DATA(requests). result = VALUE #( FOR request IN requests ( %tky = request-%tky %action-Submit = COND #( WHEN request-Status = zif_sor_status=>draft THEN if_abap_behv=>fc-o-enabled ELSE if_abap_behv=>fc-o-disabled ) ) ). ENDMETHOD. ``` The consumer can disable or hide Submit for an already submitted request, and the RAP runtime receives the operation permission state. ### 15.2 Feature control versus validation Feature control improves affordance and prevents unavailable operations from being offered. Validation remains necessary for save-time invariants and race-resistant backend enforcement. ### 15.3 Feature control versus authorization ```text Feature control Is Submit meaningful for this object state? Authorization Is this user permitted to Submit? ``` An action can be enabled by status and still unauthorized for the current user. Both conditions must pass. --- ## 16. EML Inside Behavior Implementations ### 16.1 Why EML is used Behavior logic should work with the current BO transaction, including unsaved changes. EML provides typed access to that state: ```abap READ ENTITIES OF ZI_SalesOrderRequest IN LOCAL MODE ... MODIFY ENTITIES OF ZI_SalesOrderRequest IN LOCAL MODE ... ``` Ordinary SQL primarily sees database persistence. It does not automatically represent the latest RAP transactional buffer state. ### 16.2 `IN LOCAL MODE` Inside the implementation of the same BO, `IN LOCAL MODE` enables internal BO orchestration and bypasses selected external controls such as authorization, feature control, and prechecks according to the EML contract. It does not mean: - a draft is created; - changes are already committed; - validations never run; - the database is updated immediately; - arbitrary data corruption is acceptable. The implementation becomes responsible for preserving the invariant while using this privileged internal path. ### 16.3 Do not issue commit in a behavior handler Behavior code participates in the RAP transaction controlled by the consumer and framework. Do not execute `COMMIT WORK` or `COMMIT ENTITIES` inside the behavior pool to finalize only part of the operation. An external EML consumer owns its transaction boundary: ```abap MODIFY ENTITIES OF ZI_SalesOrderRequest ... FAILED DATA(failed) REPORTED DATA(reported). IF failed IS INITIAL. COMMIT ENTITIES RESPONSE OF ZI_SalesOrderRequest FAILED DATA(commit_failed) REPORTED DATA(commit_reported). ENDIF. ``` --- ## 17. Typed RAP Responses ### 17.1 `MAPPED` `MAPPED` associates preliminary identities or client correlation IDs with keys assigned during create processing. Typical use: ```text Consumer sends %cid = 'REQ_1' Managed early numbering assigns RequestUUID MAPPED returns %cid ↔ RequestUUID ``` It is not a persistence field-name mapping. ### 17.2 `FAILED` `FAILED` identifies entity instances for which an operation could not be completed. Its cause may be validation, authorization, missing data, conflict, or an implementation-specific failure. ### 17.3 `REPORTED` `REPORTED` communicates messages associated with instances, state areas, or elements. A reported row can explain a failure, clear a prior state message, or provide non-error feedback. ### 17.4 Action `result` An action result is separate from the generic response structures: ```abap result = VALUE #( ( %tky = request-%tky %param = request ) ). ``` `%param` contains the result type declared by the action. With `result [1] $self`, it contains the returned entity representation. ### 17.5 Response interpretation ```text MAPPED Which generated key belongs to which create request? FAILED Which instance did not complete the operation? REPORTED What should the consumer be told about an instance or field? result What business result did the action/function return? ``` --- ## 18. Aggregate Business Logic ### 18.1 Sales Order Request invariants A coherent custom request aggregate can use these rules: ```text Request Customer must be valid before submission. Submitted request must contain at least one valid Item. TotalAmount equals the sum of Item.NetAmount. Item Product must exist. RequestedQuantity must be positive. TransactionCurrency follows the Request currency. NetAmount is derived, not entered. ``` ### 18.2 Single derivation path Keep one authoritative path for each calculated value: ```text RequestedQuantity or UnitPrice changes │ ▼ derive Item.NetAmount │ ▼ aggregate Request.TotalAmount ``` If UI code, action code, and determination code each calculate the amount, their formulas will eventually diverge. The UI should display and refresh the backend-derived result rather than become another source of truth. ### 18.3 Child deletion Deletion requires special care because fields needed for aggregation may no longer be readable after the child has been removed from the buffer. Design the trigger and key flow so the parent identity is available before or as part of the delete processing, then recompute the parent from the surviving buffered children. Avoid subtracting an assumed old amount without reliable before-image data. Re-aggregation from current authoritative state is usually safer when the aggregate size permits it. ### 18.4 UI refresh A determination updates backend transactional state. A Fiori client does not continuously reread every dependent field. Declare appropriate side effects or return/reread affected data so `NetAmount` and `TotalAmount` refresh after their inputs change. Side effects control refresh behavior; they do not perform the calculation. --- ## 19. Runtime Flow by Operation ### 19.1 Managed create ```text Consumer CREATE → projection allows create → RAP checks external contract → managed numbering assigns UUID → instance enters transactional buffer → on-modify determinations run → consumer receives interaction response and key mapping → save requested → on-save validations run → framework persists mapped fields → commit succeeds or save is rejected ``` ### 19.2 Managed update ```text Consumer UPDATE → entity and ETag identify current instance → authorization/feature/field controls apply → update enters buffer → determinations react to changed fields → save validations inspect final BO state → framework writes changed persistence state ``` ### 19.3 Action ```text Consumer invokes Submit → behavior projection exposes action → RAP checks action authorization and feature state → handler runs → handler reads/modifies through local EML → handler returns FAILED/REPORTED/result → save sequence validates and persists valid state ``` ### 19.4 Validation failure ```text Save requested → ValidateCustomer reads SoldToParty → target not found → %tky appended to FAILED → error object appended to REPORTED → field marker identifies SoldToParty → save of affected instance is rejected → consumer receives actionable business message ``` --- ## 20. Technical Diagnostics ### 20.1 Create or Edit button is missing Check in this order: ```text Base BDEF operation declaration → Behavior Projection `use` declaration → CDS projection/service exposure → active OData metadata → authorization and feature-control result → UI metadata and client cache ``` Do not add another action before proving which contract layer omitted the standard operation. ### 20.2 Determination does not run Verify: 1. determination is declared on the correct entity; 2. operation or field trigger includes the actual changed input; 3. handler signature matches the generated contract; 4. behavior pool is assigned and active; 5. modification reaches this BO rather than a different projection/interface; 6. handler reads current state with the correct `%tky`; 7. nested EML does not produce ignored `REPORTED` messages; 8. consumer refresh behavior is not hiding a successful calculation. ### 20.3 Validation does not block save Verify: 1. validation is `on save` with the correct triggers; 2. invalid entity `%tky` is appended to the correct `FAILED-<entity>` table; 3. validation reads buffered state rather than stale persistence; 4. reference query is not accidentally empty because of type conversion or access control; 5. the consumer actually requests save/activation; 6. only writing `REPORTED` was not mistaken for marking a failure. ### 20.4 Action changes status but returns old data Check that the action: 1. updates through EML; 2. preserves failures from the update; 3. rereads after the modification; 4. fills `result-%tky` and `result-%param` from the reread state; 5. does not read the database before the buffer is saved. ### 20.5 Child creation fails Check: ```text Root composition exists → Base BDEF association permits create → Behavior projection uses association create → request uses create-by-association payload → parent transactional key is valid → child mapping and numbering are correct ``` Do not add standalone child `create` to bypass aggregate ownership. ### 20.6 Derived fields are editable Check base BDEF `field ( readonly )`, dynamic field control if used, behavior projection, active metadata, and client cache. A semantic CDS annotation does not make a field read-only. ### 20.7 Duplicate or recursive determination execution Inspect trigger fields and nested local EML. A determination that updates one of its own trigger fields can retrigger itself. Make the operation idempotent, update only when the derived value actually differs, and avoid hidden ordering dependencies. --- ## 21. Implementation Review Checklist ### Behavior contract - Implementation type matches ownership of CRUD and save mechanics. - `strict ( 2 )` is used where supported. - Each CDS node has one clear BDEF alias. - Root owns create and child creation occurs by association. - Persistent tables and mappings are complete and correctly oriented. - Framework-generated and derived fields are read-only to consumers. - Structural mandatory fields are declared without replacing semantic validation. - Locks, ETags, and authorization dependencies follow aggregate ownership. ### Business logic - Determinations derive state and are idempotent. - Determination triggers cover every calculation input. - Separate determinations do not depend on execution order. - Validations append invalid instances to `FAILED`. - `REPORTED` messages identify state area and field where useful. - Actions express business intent rather than raw status editing. - Feature control depends on object state; authorization depends on user permission. - All invariants are enforced at the reusable BO layer. ### ABAP implementation - Behavior methods use EML for current transactional BO state. - Internal EML uses `IN LOCAL MODE` intentionally. - `%tky` is preserved across reads, writes, results, and messages. - Set-oriented reference reads replace database access inside large loops. - Nested EML failures and messages are propagated. - Handler attributes are not used as a persistent transaction buffer. - No commit is issued inside the behavior pool. - Pure domain calculations are separated from RAP orchestration where useful. ### Consumer contract - Behavior projection exposes only intended operations. - CDS field exposure and behavior editability are consistent. - Side effects refresh fields affected by backend derivation. - OData metadata is verified after activation and publication. - API consumers receive stable action results and actionable messages. --- ## 22. Compact Behavior Map ```text BASE BDEF SalesOrderRequest create / update / delete association _Items { create } readonly RequestUUID, TotalAmount, timestamps mandatory:create SoldToParty determination DeriveAmounts validation ValidateCustomer action Submit feature + authorization hooks │ ▼ BEHAVIOR POOL Handler methods DeriveAmounts read buffer → calculate → local EML update ValidateCustomer read buffer → check reference → FAILED/REPORTED Submit change status → reread → action result GetFeatures inspect status → enabled/disabled │ ▼ RAP TRANSACTION interaction buffer → determinations → action/standard-operation responses → on-save validations → managed/unmanaged save processing │ ▼ BEHAVIOR PROJECTION use create / update / delete use action Submit use association _Items { create } │ ▼ CONSUMER ``` The behavior layer should always be read as four separate decisions: ```text BDEF declares capability. Runtime supplies framework mechanics. Behavior pool implements business-specific logic. Behavior projection exposes selected capability. ``` 4a:T975,SAP RAP Behavior Modeling and Implementation — Technical Reference This document explains how a RAP business object becomes transactional. It covers the base behavior definition, behavior projection, managed and unmanaged implementation choices, behavior pools, standard operations, field control, determinations, validations, actions, prechecks, feature control, EML, and RAP response structures. The central implementation principle is: The behavior definition declares what the business object can do. The RAP runtime enforces the declared contract and supplies framework behavior. The behavior pool implements only the application-specific logic required by that contract. The behavior projection selects which capabilities a consumer may use. Primary SAP sources: - SAP Help — Defining Standard Behavior - SAP Help — Implementing Behavior - SAP Help — Projecting Behavior - SAP Help — Determinations - SAP Help — Validation Implementation - SAP Help — Action Runtime - SAP Help — Feature Control --- 1. Position of Behavior in RAP text CDS data model entities, fields, composition tree, associations │ ▼ Base Behavior Definition transactional capabilities and implementation contract │ ├──────── RAP managed runtime │ generic CRUD, buffer, mapping, │ locking and ETag support │ └──────── Behavior Pool custom rules and operations │ ▼ Behavior Projection capabilities exposed for one consumer │ ▼ OData service or EML consumer The behavior definition, often abbreviated as BDEF, is attached to the CDS business-object model. It declares: - managed, unmanaged, projection, or interface behavior; - standard create, update, and delete operations; - create-by-association for child nodes; - persistence tables and field mappings; - locks and ETags; - static and dynamic field characteristics; - determinations and validations; - actions and functions; - authorization and feature-control hooks; - draft behavior where applicable. The BDEF contains declarations, not the ABAP implementation of custom business logic. --- 2. Base Behavior Definition Versus Behavior Projection 2.1 Base behavior definition The base BDEF defines the reusable transactional contract: abap managed implementation in class zbpisalesorderrequest unique; strict ( 2 ); define behavior for ZISalesOrderRequest alias SalesOrderRequest persistent table zsorrequest lock master4b:Tcb5,# SAP RAP Behavior Modeling and Implementation — Technical Reference This document explains how a RAP business object becomes transactional. It covers the base behavior definition, behavior projection, managed and unmanaged implementation choices, behavior pools, standard operations, field control, determinations, validations, actions, prechecks, feature control, EML, and RAP response structures. The central implementation principle is: > The behavior definition declares what the business object can do. The RAP > runtime enforces the declared contract and supplies framework behavior. The > behavior pool implements only the application-specific logic required by > that contract. The behavior projection selects which capabilities a consumer > may use. Primary SAP sources: - [SAP Help — Defining Standard Behavior](https://help.sap.com/docs/abap-cloud/abap-rap/defining-standard-behavior) - [SAP Help — Implementing Behavior](https://help.sap.com/docs/abap-cloud/abap-rap/implementing-behavior-of-business-object) - [SAP Help — Projecting Behavior](https://help.sap.com/docs/abap-cloud/abap-rap/projecting-behavior) - [SAP Help — Determinations](https://help.sap.com/docs/abap-cloud/abap-rap/determinations) - [SAP Help — Validation Implementation](https://help.sap.com/docs/abap-cloud/abap-rap/validation-implementation) - [SAP Help — Action Runtime](https://help.sap.com/docs/abap-cloud/abap-rap/action-runtime) - [SAP Help — Feature Control](https://help.sap.com/docs/abap-cloud/abap-rap/implementation-contract-feature-control) --- ## 1. Position of Behavior in RAP ```text CDS data model entities, fields, composition tree, associations │ ▼ Base Behavior Definition transactional capabilities and implementation contract │ ├──────── RAP managed runtime │ generic CRUD, buffer, mapping, │ locking and ETag support │ └──────── Behavior Pool custom rules and operations │ ▼ Behavior Projection capabilities exposed for one consumer │ ▼ OData service or EML consumer ``` The behavior definition, often abbreviated as BDEF, is attached to the CDS business-object model. It declares: - managed, unmanaged, projection, or interface behavior; - standard create, update, and delete operations; - create-by-association for child nodes; - persistence tables and field mappings; - locks and ETags; - static and dynamic field characteristics; - determinations and validations; - actions and functions; - authorization and feature-control hooks; - draft behavior where applicable. The BDEF contains declarations, not the ABAP implementation of custom business logic. --- ## 2. Base Behavior Definition Versus Behavior Projection ### 2.1 Base behavior definition The base BDEF defines the reusable transactional contract: ```abap managed implementation in class zbp_i_salesorderrequest unique; strict ( 2 );4c:T9e36, # SAP RAP Transactions, Draft, and Concurrency — Technical Reference This document explains how RAP manages state from the first modification until database commit. It covers the interaction phase, transactional buffer, save sequence, draft persistence, draft actions, pessimistic locks, entity ETags, total ETags, early and late numbering, and transaction ownership. The central runtime principle is: > Every RAP modification first participates in a framework-controlled > transaction. The transactional buffer holds the current logical BO state; > the save sequence validates and persists that state. Draft adds a durable > editing version, but it does not replace the transactional buffer or the save > sequence used by each request. Primary SAP sources: - [SAP Help — RAP BO Runtime](https://help.sap.com/docs/abap-cloud/abap-rap/rap-bo-runtime) - [SAP Help — Save Sequence Runtime](https://help.sap.com/docs/abap-cloud/abap-rap/save-sequence-runtime) - [SAP Help — Draft Runtime](https://help.sap.com/docs/abap-cloud/abap-rap/draft-runtime) - [SAP Help — Pessimistic Concurrency Control](https://help.sap.com/docs/abap-cloud/abap-rap/pessimistic-concurrency-control-locking) - [SAP Help — Optimistic Concurrency Control](https://help.sap.com/docs/abap-cloud/abap-rap/optimistic-concurrency-control) - [SAP Help — Total ETag](https://help.sap.com/docs/ABAP_PLATFORM_NEW/fc4c71aa50014fd1b43721701471913d/f5e8548c241b43ab82bceec030b5dc9a.html) - [SAP Help — Numbering](https://help.sap.com/docs/abap-cloud/abap-rap/numbering) --- ## 1. RAP Transaction Model ### 1.1 Two runtime phases ```text INTERACTION PHASE Consumer request → authorization / feature / precheck controls → create, update, delete, or action → transactional buffer changes → on-modify determinations → interaction response save requested │ ▼ SAVE SEQUENCE FINALIZE → CHECK_BEFORE_SAVE → point of no return → ADJUST_NUMBERS when late numbering is used → SAVE / managed persistence → database commit → CLEANUP ``` The interaction phase can contain multiple operations. Those operations build one coherent logical transaction before persistence. The save sequence begins only when the consumer or service runtime closes the transaction with a save request. ### 1.2 RAP logical unit of work A RAP LUW is the framework-controlled unit in which one or more business objects participate in a transaction. Its boundary is not owned by an individual behavior method. ```text External EML consumer MODIFY ENTITIES ... MODIFY ENTITIES ... COMMIT ENTITIES OData consumer sends transactional request/batch RAP service runtime owns save and commit orchestration Behavior implementation participates in the current RAP LUW must not commit independently ``` This enables RAP to validate all participating BOs and either persist the coherent result or reject the transaction. --- ## 2. Transactional Buffer ### 2.1 Purpose The transactional buffer contains the current BO state during interaction. It includes requested changes that have not yet reached active database persistence. ```text Database before request Status = Open TotalAmount = 100 Transactional buffer after local changes Status = Submitted TotalAmount = 130 Database until successful save Status = Open TotalAmount = 100 ``` The buffer allows determinations, validations, actions, and several EML operations to work on one coherent in-progress state. ### 2.2 Buffer is not a draft ```text Transactional buffer temporary state inside the current RAP transaction required for draft and non-draft modifications discarded when its LUW ends or rolls back Draft persistence durable editable state stored in draft tables survives stateless requests and interrupted UI sessions has a managed active/draft lifecycle Active persistence committed business state stored in active tables ``` A draft request still has an interaction buffer. At the end of that request, the save sequence persists the current editable state to the draft table. Later activation uses another RAP transaction to transfer validated draft state into active persistence. ### 2.3 Read the current state with EML Behavior code normally uses local EML: ```abap READ ENTITIES OF ZI_SalesOrderRequest IN LOCAL MODE ENTITY SalesOrderRequest ALL FIELDS WITH CORRESPONDING #( keys ) RESULT DATA(requests). ``` This reads the BO state known to RAP, including unsaved modifications in the current transaction. Ordinary SQL reads database persistence. It does not automatically merge the RAP transactional buffer into the result. ### 2.4 Local mode is not a persistence mode `IN LOCAL MODE` means the BO implementation accesses its own transactional contract internally while bypassing selected external checks. It does not mean “write locally to the database,” “create a draft,” or “commit immediately.” --- ## 3. Interaction Phase ### 3.1 Managed update flow ```text 1. Consumer sends entity key, changed fields, and ETag where required. 2. RAP resolves the projection operation to the base BO. 3. Authorization, feature control, field control, and prechecks apply. 4. RAP locks the relevant lock-master instance. 5. Requested values enter the transactional buffer. 6. Triggered determinations update derived buffered values. 7. FAILED and REPORTED responses are returned for interaction failures. 8. No active database commit has occurred yet. ``` ### 3.2 Multiple modifications see one logical state ```abap MODIFY ENTITIES OF ZI_SalesOrderRequest ENTITY SalesOrderRequest UPDATE FIELDS ( TransactionCurrency ) WITH VALUE #( ( %tky = request_key TransactionCurrency = 'USD' ) ) ENTITY SalesOrderItem UPDATE FIELDS ( RequestedQuantity ) WITH VALUE #( ( %tky = item_key RequestedQuantity = 5 ) ) FAILED DATA(failed) REPORTED DATA(reported). ``` Determinations and later validations should evaluate the resulting BO state, not independently reread stale active values. ### 3.3 Interaction failure versus save failure ```text Interaction failure operation cannot enter or complete in the buffer examples: authorization denied, invalid key, failed precheck Save failure buffered state cannot be persisted coherently examples: on-save validation failed, ETag conflict, persistence error ``` Both can return typed RAP responses, but they occur at different points and have different diagnostic evidence. --- ## 4. Save Sequence ### 4.1 Overall order ```text Successful interaction modifications │ ▼ FINALIZE last permitted buffered modifications │ ▼ CHECK_BEFORE_SAVE consistency checks and managed validations │ failure ─┴─ success │ │ ▼ ▼ cleanup/failure POINT OF NO RETURN response │ ▼ ADJUST_NUMBERS if required │ ▼ SAVE / SAVE_MODIFIED │ ▼ database commit │ ▼ CLEANUP ``` The exact framework callbacks depend on managed, unmanaged, draft, additional save, and release-specific features. The conceptual boundaries remain stable. ### 4.2 `FINALIZE` `FINALIZE` is the first save-sequence step and the last point where BO data can be modified in the transactional buffer. Managed BOs perform final derivation through applicable determinations. An unmanaged saver can implement a `FINALIZE` callback. After `FINALIZE`, modifying EML is not permitted in later saver methods. Appropriate use: - final calculations requiring all transactionally involved BO state; - resolving values that can only be finalized when save begins; - cross-BO finalization designed within RAP save rules. Do not defer ordinary interactive derivations to `FINALIZE` if the consumer needs to see them while editing. ### 4.3 `CHECK_BEFORE_SAVE` This step establishes whether the complete transaction can be saved. In managed BOs, on-save validations provide the consistency checks. In unmanaged scenarios, the saver implementation supplies the corresponding check. ```text Check succeeds for every involved BO → point of no return Any involved BO returns failed instances → save sequence is rejected before persistence ``` No recoverable business validation should be postponed beyond this boundary. ### 4.4 Point of no return After all pre-save checks succeed, RAP reaches the point of no return. From this boundary onward, providers must guarantee successful completion of the save sequence. Do not place predictable business rejection logic after this point. Failures there represent technical or contract defects rather than normal user correction flow. ### 4.5 `ADJUST_NUMBERS` This phase assigns final keys when late numbering is used and maps preliminary identities to final keys. It occurs after the point of no return so gap-sensitive numbers are consumed only for a transaction already accepted for saving. ### 4.6 `SAVE` and managed persistence The save step persists buffered BO state: - managed RAP writes mapped entity state to persistent tables; - unmanaged RAP invokes provider save implementation; - managed additional save invokes the relevant additional-save contract; - multiple involved BOs must obey RAP save-order and consistency rules. The provider must not execute an independent database commit inside the saver. The RAP transaction manager owns the commit. ### 4.7 `CLEANUP` Cleanup removes provider-specific transactional buffer state and releases resources after save completion or rollback processing as defined by the implementation contract. `CLEANUP_FINALIZE` is available for cleanup when `FINALIZE` or `CHECK_BEFORE_SAVE` fails, particularly where cross-BO finalization created provider-side state that must be revoked. --- ## 5. Transaction Ownership and Commit ### 5.1 External EML consumer ```abap MODIFY ENTITIES OF ZI_SalesOrderRequest ENTITY SalesOrderRequest CREATE FIELDS ( SoldToParty TransactionCurrency ) WITH VALUE #( ( %cid = 'REQUEST_1' SoldToParty = '100000' TransactionCurrency = 'USD' ) ) MAPPED DATA(mapped) FAILED DATA(failed) REPORTED DATA(reported). IF failed IS INITIAL. COMMIT ENTITIES RESPONSE OF ZI_SalesOrderRequest FAILED DATA(commit_failed) REPORTED DATA(commit_reported). ELSE. ROLLBACK ENTITIES. ENDIF. ``` `MODIFY ENTITIES` changes RAP transactional state. `COMMIT ENTITIES` requests the save sequence and transaction completion. ### 5.2 Behavior implementation Inside a behavior handler: ```abap MODIFY ENTITIES OF ZI_SalesOrderRequest IN LOCAL MODE ... ``` The handler participates in the current consumer-owned transaction. It must not call: ```abap COMMIT WORK. COMMIT ENTITIES. ROLLBACK WORK. ``` Independent commit would split the atomic business transaction and can leave one part durable when another part fails. ### 5.3 OData service consumer The service runtime maps OData modification requests and change sets to RAP interaction and save handling. The Fiori application does not directly commit database tables. ```text Fiori Save / OData change set → RAP interaction → RAP save sequence → ABAP database transaction commit → OData response ``` --- ## 6. Draft Architecture ### 6.1 Why draft exists REST communication is stateless across requests. A user can edit an object over many interactions, navigate away, lose a frontend session, or resume from another device. A purely in-memory transaction cannot safely span that period. Draft provides a durable editing version: ```text Active tables official committed business state Draft tables persisted unfinished editing state plus draft administration RAP draft runtime controls transitions, identity, ownership, locks, ETags, and activation ``` ### 6.2 Draft table per BO entity Each draft-enabled entity in the composition tree normally has corresponding draft persistence because each node can contain editable state. ```text zsor_request ↔ zsor_request_d zsor_item ↔ zsor_item_d ``` Draft tables contain business fields, entity keys, and RAP draft administration fields, commonly through the standard draft administration include. Representative structure: ```abap define table zsor_request_d { key client : abap.clnt not null; key request_uuid : sysuuid_x16 not null; request_number : abap.char(10); sold_to_party : abap.char(10); status : abap.char(1); total_amount : abap.curr(15,2); transaction_currency : abap.cuky; local_last_changed_at: abp_locinst_lastchange_tstmpl; "%admin" : include sych_bdl_draft_admin_inc; } ``` Use the ADT quick fix/generator for a draft table instead of hand-maintaining a structure that can drift from the active entity. ### 6.3 Do not access draft tables directly Application code should not use direct SQL as the business interface to draft tables. Direct access bypasses: - active/draft identity; - draft ownership and administration; - lock and total-ETag checks; - draft action lifecycle; - behavior validations and determinations; - composition consistency; - framework evolution of draft persistence. Use EML or OData against the draft-enabled BO contract. --- ## 7. Draft-Enabled Behavior Definition ### 7.1 Base BDEF ```abap managed implementation in class zbp_i_salesorderrequest unique; strict ( 2 ); with draft; define behavior for ZI_SalesOrderRequest alias SalesOrderRequest persistent table zsor_request draft table zsor_request_d lock master total etag LastChangedAt authorization master ( instance ) etag master LocalLastChangedAt { create; update; delete; association _Items { create; with draft; } draft action Resume; draft action Edit; draft action Activate optimized; draft action Discard; draft determine action Prepare { validation ValidateCustomer; validation ValidateSubmittedRequest; validation SalesOrderItem~ValidateProduct; validation SalesOrderItem~ValidateQuantity; } field ( numbering : managed, readonly ) RequestUUID; field ( readonly ) LastChangedAt, LocalLastChangedAt; } define behavior for ZI_SalesOrderItem alias SalesOrderItem persistent table zsor_item draft table zsor_item_d lock dependent by _Request authorization dependent by _Request etag master LocalLastChangedAt { update; delete; association _Request { with draft; } association _Product; field ( numbering : managed, readonly ) ItemUUID; field ( readonly ) RequestUUID, LocalLastChangedAt; } ``` Important distinctions: - `with draft` enables draft behavior for the BO; - `draft table` declares node-specific draft persistence; - `total etag` belongs to the lock-master/root entity; - each composition path is explicitly marked `with draft` under strict mode; - `Prepare` lists checks to execute for draft preparation/activation; - ordinary reference associations such as `_Product` do not become owned draft nodes. ### 7.2 Behavior projection ```abap projection; strict ( 2 ); define behavior for ZC_SalesOrderRequest alias SalesOrderRequest use etag { use create; use update; use delete; use association _Items { create; with draft; } use action Resume; use action Edit; use action Activate; use action Discard; use action Prepare; } define behavior for ZC_SalesOrderItem alias SalesOrderItem use etag { use update; use delete; use association _Request { with draft; } use association _Product; } ``` The consumer receives draft capabilities only when the base BO and projection contracts expose them correctly. --- ## 8. Active, New-Draft, and Edit-Draft State ### 8.1 Active instance ```text Active table row exists Draft table row may or may not exist Represents current official business state ``` ### 8.2 New draft ```text Draft table row exists No corresponding active row exists Represents a new object not yet activated ``` If the new draft is discarded, no active instance remains because one never existed. ### 8.3 Edit draft ```text Active row exists Draft row exists in parallel Draft began as a copy of active state Further edits affect draft state Active remains unchanged until activation ``` The active and edit-draft instances share business identity but differ by the draft indicator and lifecycle metadata. ### 8.4 `%is_draft` RAP typed keys include draft identity: ```abap %tky business/entity key components %is_draft ``` In OData, the corresponding technical distinction is represented through `IsActiveEntity`. Preserving `%tky` in EML reads, updates, messages, and results prevents behavior logic from accidentally reading the active version while processing a draft. --- ## 9. Draft Actions ### 9.1 `Edit` Purpose: ```text Active instance → lock active aggregate → copy active aggregate state to draft persistence → return editable draft identity ``` The active instance remains. Edits are applied to the draft version. `Edit` is not a generic field update and does not activate code in the ABAP repository. ### 9.2 `Prepare` Purpose: ```text Current draft state → run listed determinations and validations → return state messages and failures → keep result as draft ``` `Prepare` checks readiness for activation. It does not by itself transfer the draft to active persistence. The `draft determine action Prepare` explicitly lists the determinations and validations that should be executed. Activation can execute Prepare processing as part of its lifecycle. ### 9.3 `Activate` Purpose: ```text Draft state → prepare/check as required → verify concurrency against active state → run active save sequence → create or update active persistence → delete draft state after success ``` For a new draft, activation creates the first active instance. For an edit draft, activation updates the corresponding active instance. If activation fails validation, the draft remains available for correction; invalid data does not become active. ### 9.4 `Discard` Purpose: ```text Edit draft delete draft version keep existing active version unchanged New draft delete draft version no active version exists ``` Discard is destructive for the unfinished draft state. It does not create a recoverable “discarded version” that `Resume` can restore. ### 9.5 `Resume` Purpose: ```text Existing draft survives after exclusive lock expires → reacquire lock on corresponding active aggregate → compare remembered total ETag with current active total ETag → continue editing if active state is still compatible ``` Resume continues an existing draft. It does not restore a discarded or deleted draft. --- ## 10. Draft Composition Consistency ### 10.1 `with draft` ```abap association _Items { create; with draft; } association _Request { with draft; } ``` Draft-enabled BO-internal navigation keeps all nodes in the same active/draft context: ```text Navigate from active Request → active Items Navigate from draft Request → draft Items Create Item through draft Request → draft Item ``` Without consistent draft navigation, a user could edit a draft root while accidentally reading or creating active children, breaking aggregate consistency. ### 10.2 Independent reference associations Customer and Product reference entities usually remain active reference data: ```text Draft Request ─association→ active Customer reference Draft Item ─association→ active Product reference ``` They are not draft-owned merely because the draft transaction refers to them. --- ## 11. Pessimistic Concurrency: Locks ### 11.1 Purpose Pessimistic concurrency prevents simultaneous modification by acquiring an exclusive enqueue lock before modifying an existing instance. ```text User A requests modification → lock acquired User B requests conflicting modification → lock collision → request rejected while A owns lock ``` Locks prevent concurrent editing. They do not prove that a client is modifying the exact version it previously read; that is the ETag responsibility. ### 11.2 Lock master and dependent ```abap define behavior for ZI_SalesOrderRequest lock master define behavior for ZI_SalesOrderItem lock dependent by _Request ``` The root is the aggregate lock master. Modifying an Item resolves its parent Request and locks the relevant aggregate, so related root and child changes are protected together. ```text Request A + its Items → one lock-master scope Request B + its Items → separate lock-master scope ``` ### 11.3 Managed and unmanaged lock handling Managed RAP can implement standard lock behavior from the BDEF declaration. Unmanaged RAP requires provider implementation, normally using the SAP enqueue lock concept and returning lock failures through RAP responses. ### 11.4 Lock limitations A lock: - does not validate a business rule; - does not replace a database uniqueness constraint; - does not automatically prevent two creates with the same externally supplied key before an existing instance is available to lock; - does not replace an ETag check; - does not make a long-running database transaction acceptable. --- ## 12. Optimistic Concurrency: Entity ETags ### 12.1 Purpose An entity ETag represents a version of entity state known to the OData consumer. ```text Client reads entity with ETag V1 │ Other client changes entity → current ETag V2 │ First client sends update with V1 │ RAP compares V1 with V2 → mismatch → reject ``` This prevents lost updates based on stale client state. ### 12.2 BDEF declaration ```abap etag master LocalLastChangedAt ``` or, for a dependent entity: ```abap etag dependent by _Request ``` An ETag master owns its ETag field. An ETag-dependent entity uses the ETag of a reachable master according to the declared association. ### 12.3 Reliable ETag update The field must change reliably whenever the protected entity state changes. Managed RAP can maintain correctly annotated administrative timestamps. Unmanaged providers must implement reliable updates themselves. ```abap @Semantics.systemDateTime.localInstanceLastChangedAt: true Request.local_last_changed_at as LocalLastChangedAt ``` Declaring `etag master` without reliably changing the value creates false concurrency safety. ### 12.4 Lock versus ETag ```text Lock prevents a conflicting writer during the current lock lifetime ETag rejects a write based on a stale previously read version ``` RAP transactional services use both forms because they address different race conditions. --- ## 13. Total ETag ### 13.1 Purpose The total ETag is a root-level version of the complete active business object used by draft concurrency transitions. ```abap lock master total etag LastChangedAt ``` It protects an edit draft from silently overwriting active changes made after the draft's exclusive lock expired. ### 13.2 Aggregate scope ```text Request root changes → total ETag changes Relevant Item child changes → total ETag changes Resume/Activate edit draft → remembered total ETag compared with current active total ETag ``` The total ETag is not a receipt proving that “the previous change applied successfully.” It is active aggregate version evidence used for optimistic concurrency. ### 13.3 Entity ETag versus total ETag | Control | Scope | Main use | | ----------- | -------------------------------------- | -------------------------------------------------------- | | Entity ETag | One entity or declared ETag dependency | Protect an OData modification against stale entity state | | Total ETag | Complete active draft-enabled BO | Protect active/draft transitions after lock expiry | Draft table administration also maintains draft-specific last-change evidence to prevent stale edits of the same draft from different clients. ### 13.4 Root field annotation A managed total-ETag timestamp is commonly annotated: ```abap @Semantics.systemDateTime.lastChangedAt: true Request.last_changed_at as LastChangedAt ``` It must also be present in persistence mapping when CDS and table field names differ. The total ETag can remain an internal field and does not always need to be exposed in the service projection. --- ## 14. Draft Lock Lifecycle ### 14.1 Exclusive phase When an edit draft is created, RAP locks the corresponding active aggregate. For the exclusive lock period, another user cannot modify that active instance. ```text Edit action → create draft → exclusive lock on active aggregate → draft owner edits ``` ### 14.2 Optimistic phase The exclusive lock cannot remain forever across stateless interaction. After its configured lifetime expires, the draft can still persist while the active instance becomes available under optimistic control. ```text Draft still exists Exclusive lock expired Total ETag remembers active version at draft boundary ``` ### 14.3 Resume conflict ```text Draft remembered total ETag = V1 Current active total ETag = V2 Resume attempts lock + comparison V1 ≠ V2 → conflict → stale draft cannot continue as if active were unchanged ``` The application should return a clear concurrency message and guide the user toward reviewing current active data rather than hiding the conflict. --- ## 15. Numbering ### 15.1 Identity timing ```text Early numbering key assigned during create interaction new instance is addressable before save Late numbering final key assigned after point of no return useful when final business number should be consumed only for accepted save ``` Key timing is independent from whether a field is called an “order number.” A BO can use a technical UUID early and assign a human-readable business number late. ### 15.2 Managed internal early numbering ```abap field ( numbering : managed, readonly ) RequestUUID; ``` Managed early numbering: - is available for managed BO UUID keys with ABAP type `RAW(16)`; - assigns the UUID during `CREATE`; - lets the draft and child instances reference the root immediately; - returns generated identity through RAP key mapping; - requires no custom numbering handler. Draft does not universally require every key to use this exact strategy, but a stable early technical key is especially practical for draft composition navigation. ### 15.3 Unmanaged early numbering ```abap define behavior for ZI_SalesOrderRequest early numbering ``` The behavior pool implements a `FOR NUMBERING` method invoked during create or create-by-association. The provider must guarantee uniqueness under concurrent requests and return assigned keys in `MAPPED`. For sequential business numbers, use a proper number-range or equivalent released concurrency-safe mechanism. “Read MAX and add one” is not safe under parallel creation without additional synchronization. ### 15.4 Late numbering Late numbering assigns final key values in `ADJUST_NUMBERS` after the point of no return. Appropriate uses can include legally or operationally controlled document numbers where gaps must be minimized according to the actual requirement. Trade-offs: - earlier interaction must use preliminary identity; - parent/child key relationships must be remapped correctly; - `MAPPED` results become central; - provider must guarantee save success after consuming final numbers; - error handling becomes more constrained after the point of no return. ### 15.5 Technical UUID plus business number ```text RequestUUID technical immutable key managed early numbering used for composition and transactional identity RequestNumber human-facing business identifier can be assigned by controlled application logic at the required phase ``` Separating the two reduces the pressure to use a mutable or late-assigned business identifier as the relational key of the entire aggregate. --- ## 16. `MAPPED`, `%cid`, and Transactional Identity ### 16.1 Create correlation ```abap WITH VALUE #( ( %cid = 'REQUEST_1' SoldToParty = '100000' TransactionCurrency = 'USD' ) ) MAPPED DATA(mapped) ``` The consumer supplies `%cid` as a request-local correlation identifier. RAP returns the assigned key in `mapped-SalesOrderRequest`. ### 16.2 Child correlation Deep or create-by-association requests use correlation IDs to connect newly created instances before final keys are known. Preserve the exact generated types rather than manually constructing partial key structures. ### 16.3 `%tky` `%tky` identifies an existing or newly addressed entity in its current transactional context. In a draft BO it includes the draft indicator. ```text Business key alone RequestUUID Transactional identity RequestUUID + draft/active context + framework key components ``` Use `%tky` across local reads, modifications, validation failures, messages, and action results. --- ## 17. Managed, Unmanaged, and Additional Save ### 17.1 Managed save The framework owns ordinary persistence based on: - persistent and draft tables; - CDS fields and BDEF mappings; - managed administrative fields; - validations and determinations; - lock, ETag, and numbering declarations. Application code should not duplicate standard table inserts or updates. ### 17.2 Unmanaged saver An unmanaged provider implements save-sequence methods appropriate to its contract, commonly including: ```abap CLASS lsc_SalesOrderRequest DEFINITION INHERITING FROM cl_abap_behavior_saver. PROTECTED SECTION. METHODS finalize REDEFINITION. METHODS check_before_save REDEFINITION. METHODS adjust_numbers REDEFINITION. METHODS save REDEFINITION. METHODS cleanup REDEFINITION. METHODS cleanup_finalize REDEFINITION. ENDCLASS. ``` Implement only callbacks required by the design. Later saver phases cannot use modifying EML to reopen interaction processing. ### 17.3 Additional save Additional save supplements managed persistence with an allowed secondary save effect. Suitable designs are durable and idempotent, such as an audit record or transactional outbox entry tied to the same commit. Unsafe design: ```text SAVE calls remote HTTP service remote system commits local database later fails systems disagree ``` Prefer a durable local outbox/event record in the RAP transaction, followed by asynchronous delivery with retry and idempotency. ### 17.4 Point-of-no-return discipline After the point of no return: - no normal user-correctable validation should fail; - final numbering must be concurrency-safe; - persistence must be guaranteed by the provider contract; - external side effects must not create an uncoordinated partial commit; - cleanup must release provider resources reliably. --- ## 18. Failure and Recovery Flows ### 18.1 Validation failure during activation ```text Draft contains invalid Product → user invokes Prepare or Activate → ValidateProduct appends Item %tky to FAILED → REPORTED carries field message → activation rejected → active data remains unchanged → draft remains available for correction ``` ### 18.2 Entity ETag conflict ```text Client sends stale ETag → RAP compares current entity version → mismatch → modification rejected before overwriting newer state → client must reread and reconcile ``` ### 18.3 Total ETag conflict on resume ```text Draft lock expired Active aggregate changed elsewhere → Resume reacquires lock → total ETag mismatch → stale draft cannot resume normally → user reviews current active version ``` ### 18.4 Technical failure after point of no return This indicates that the provider could not honor the save guarantee. Diagnose: - unmanaged save implementation; - key collision or unsafe numbering; - direct database constraint violation; - forbidden remote side effect; - incorrect persistence mapping; - save-order dependency between BOs; - uncaught exception or runtime error. Do not convert such defects into a generic validation message without fixing the violated save contract. ### 18.5 Discard flow ```text User discards edit draft → draft rows and administration removed → active row remains unchanged → draft editing state cannot be resumed ``` --- ## 19. End-to-End Sales Order Request Traces ### 19.1 Create a new draft request ```text 1. UI sends CREATE for draft root. 2. Managed early numbering assigns RequestUUID. 3. Initial values enter transactional buffer. 4. Determinations set defaults. 5. Save sequence persists state to zsor_request_d. 6. Active zsor_request has no corresponding row yet. 7. UI can return later using draft identity. ``` ### 19.2 Add a draft item ```text 1. UI creates by association through draft Request._Items. 2. ItemUUID is assigned early. 3. Parent RequestUUID and draft context are preserved. 4. Product/quantity enter buffer. 5. Determinations derive currency, price, and NetAmount. 6. Root TotalAmount is recomputed. 7. Save sequence persists Item and Request draft state. 8. No active Item is created yet. ``` ### 19.3 Activate the new request ```text 1. UI invokes Prepare/Activate. 2. Listed validations inspect complete draft aggregate. 3. Customer and Products are valid; quantity is positive. 4. Final determinations produce coherent totals. 5. Concurrency and save checks succeed. 6. Managed save creates active Request and Items. 7. Draft rows are removed. 8. Active aggregate becomes the official state. ``` ### 19.4 Edit an active request ```text 1. UI reads active Request and its ETag. 2. Edit verifies version and creates edit draft. 3. Active aggregate is exclusively locked. 4. Active Request and owned Items are represented in draft context. 5. User changes quantity; derivations update draft totals. 6. Active values remain unchanged during editing. 7. Activate validates and replaces active state atomically. 8. Draft is deleted after success. ``` --- ## 20. Technical Diagnostics ### 20.1 Draft button or edit flow is absent Check: ```text Base BDEF `with draft` → draft tables for every owned entity → total ETag on root → draft actions declared → BO-internal associations `with draft` → behavior projection uses draft actions → service binding and current metadata → Fiori draft support ``` ### 20.2 Draft changes appear in active data too early Check whether: - application code writes active tables directly; - an unmanaged save maps draft requests to the wrong persistence; - `%is_draft` was lost when reconstructing keys; - a helper uses SQL rather than current BO context; - navigation reaches active rather than draft child instances; - a custom action intentionally modifies active data. ### 20.3 Draft navigation returns no Items Check: 1. root composition and child parent association; 2. `with draft` on BO-internal relationships; 3. CDS projection redirection; 4. child draft table and key mapping; 5. `%is_draft` in EML keys; 6. service metadata and expansion path. ### 20.4 Activation fails with no useful message Check: - validations append exact `%tky` to `FAILED`; - `REPORTED` contains a message object and field marker; - validation is listed in `Prepare` when early feedback is expected; - nested EML `REPORTED` data is propagated; - late save failure is not being mislabeled as validation; - service/client logs contain the full RAP response. ### 20.5 Lock conflict Capture: - root business key and child key if applicable; - user/session owning the lock; - lock-master resolution path; - draft owner and draft age; - enqueue table evidence; - exact requested operation; - whether the lock is exclusive or the draft is in optimistic phase. Do not disable locking to make the symptom disappear. ### 20.6 ETag conflict Capture: ```text ETag read by client ETag sent in modification current ETag in active/draft entity operation timestamp and competing change entity ETag declaration and update annotation ``` An ETag conflict is normally evidence that concurrency protection worked. The consumer should reread and reconcile rather than retry the stale update blindly. ### 20.7 Total ETag does not change after child update Check: - root total-ETag field annotation; - persistence mapping; - managed administrative update behavior; - child is inside the same composition tree; - unmanaged provider updates aggregate version correctly; - update actually passed through RAP rather than direct SQL; - the field read is active total ETag rather than local entity timestamp. ### 20.8 Number collision Check: - early versus late numbering declaration; - managed UUID field type is `RAW(16)`; - custom `FOR NUMBERING` returns every required key in `MAPPED`; - number-range locking/concurrency; - preliminary-to-final parent/child remapping; - database uniqueness evidence; - unsafe `MAX + 1` logic. --- ## 21. Transaction and Draft Review Checklist ### Transaction model - Behavior code reads current state through EML where buffered data matters. - Interaction and save failures are diagnosed separately. - No handler or saver commits independently. - Predictable validation completes before the point of no return. - `FINALIZE` is the last phase that modifies buffered BO state. - Save implementation can guarantee success after pre-save checks. - Cross-BO save order and atomicity are explicit. ### Draft model - Draft is required by the user workflow, not enabled automatically everywhere. - Every draft-owned entity has correct generated draft persistence. - Application logic never treats draft tables as public SQL interfaces. - Active/draft identity is preserved through `%tky` and `%is_draft`. - Composition navigation stays within active or draft context. - `Prepare` lists the checks needed before activation. - `Discard` and `Resume` semantics are correctly represented to users. ### Concurrency - Root and dependent locks match aggregate ownership. - Entity ETags change reliably for every protected modification. - Draft root has a total ETag covering the aggregate. - Lock conflicts and ETag conflicts produce distinct diagnostics. - Consumers reread on stale-version conflicts rather than force overwrite. ### Numbering - Technical identity and business document number are separated where useful. - Managed UUID numbering uses the required type and read-only contract. - Custom numbering is concurrency-safe. - Late numbering occurs only after all normal rejection checks. - `MAPPED` preserves correlation and parent/child identity. --- ## 22. Compact Runtime Map ```text NON-DRAFT MODIFY Client reads V1 → sends modification + ETag V1 → RAP lock + ETag check → interaction buffer → determinations → save request → FINALIZE → CHECK_BEFORE_SAVE → point of no return → numbering/save → active database V2 → cleanup DRAFT EDIT Active V1 → Edit → active lock + draft copy → repeated draft modifications → each request saves durable draft state → Prepare validates draft → Activate compares concurrency state → active save sequence → Active V2 → draft removed CONCURRENCY Lock prevents simultaneous modification during lock lifetime Entity ETag rejects a write based on stale entity state Total ETag rejects stale active/draft transition for the aggregate STATE Transactional buffer temporary current RAP LUW state Draft persistence durable unfinished editing state Active persistence durable official business state ``` The transaction layer should always be understood through four boundaries: ```text Buffer is not persistence. Draft is not the transactional buffer. Prepare is not activation. Reported information is not automatically a rejected operation. ``` 4d:T8a8,SAP RAP Transactions, Draft, and Concurrency — Technical Reference This document explains how RAP manages state from the first modification until database commit. It covers the interaction phase, transactional buffer, save sequence, draft persistence, draft actions, pessimistic locks, entity ETags, total ETags, early and late numbering, and transaction ownership. The central runtime principle is: Every RAP modification first participates in a framework-controlled transaction. The transactional buffer holds the current logical BO state; the save sequence validates and persists that state. Draft adds a durable editing version, but it does not replace the transactional buffer or the save sequence used by each request. Primary SAP sources: - SAP Help — RAP BO Runtime - SAP Help — Save Sequence Runtime - SAP Help — Draft Runtime - SAP Help — Pessimistic Concurrency Control - SAP Help — Optimistic Concurrency Control - SAP Help — Total ETag - SAP Help — Numbering --- 1. RAP Transaction Model 1.1 Two runtime phases text INTERACTION PHASE Consumer request → authorization / feature / precheck controls → create, update, delete, or action → transactional buffer changes → on-modify determinations → interaction response save requested │ ▼ SAVE SEQUENCE FINALIZE → CHECKBEFORESAVE → point of no return → ADJUSTNUMBERS when late numbering is used → SAVE / managed persistence → database commit → CLEANUP The interaction phase can contain multiple operations. Those operations build one coherent logical transaction before persistence. The save sequence begins only when the consumer or service runtime closes the transaction with a save request. 1.2 RAP logical unit of work A RAP LUW is the framework-controlled unit in which one or more business objects participate in a transaction. Its boundary is not owned by an individual behavior method. text External EML consumer MODIFY ENTITIES ... MODIFY ENTITIES ... COMMIT ENTITIES OData consumer sends transactional request/batch RAP service runtime owns save and commit orchestration Behavior implementation participates in the current RAP LUW must not commit independently This enables RAP to validate all participating4e:Taed,# SAP RAP Transactions, Draft, and Concurrency — Technical Reference This document explains how RAP manages state from the first modification until database commit. It covers the interaction phase, transactional buffer, save sequence, draft persistence, draft actions, pessimistic locks, entity ETags, total ETags, early and late numbering, and transaction ownership. The central runtime principle is: > Every RAP modification first participates in a framework-controlled > transaction. The transactional buffer holds the current logical BO state; > the save sequence validates and persists that state. Draft adds a durable > editing version, but it does not replace the transactional buffer or the save > sequence used by each request. Primary SAP sources: - [SAP Help — RAP BO Runtime](https://help.sap.com/docs/abap-cloud/abap-rap/rap-bo-runtime) - [SAP Help — Save Sequence Runtime](https://help.sap.com/docs/abap-cloud/abap-rap/save-sequence-runtime) - [SAP Help — Draft Runtime](https://help.sap.com/docs/abap-cloud/abap-rap/draft-runtime) - [SAP Help — Pessimistic Concurrency Control](https://help.sap.com/docs/abap-cloud/abap-rap/pessimistic-concurrency-control-locking) - [SAP Help — Optimistic Concurrency Control](https://help.sap.com/docs/abap-cloud/abap-rap/optimistic-concurrency-control) - [SAP Help — Total ETag](https://help.sap.com/docs/ABAP_PLATFORM_NEW/fc4c71aa50014fd1b43721701471913d/f5e8548c241b43ab82bceec030b5dc9a.html) - [SAP Help — Numbering](https://help.sap.com/docs/abap-cloud/abap-rap/numbering) --- ## 1. RAP Transaction Model ### 1.1 Two runtime phases ```text INTERACTION PHASE Consumer request → authorization / feature / precheck controls → create, update, delete, or action → transactional buffer changes → on-modify determinations → interaction response save requested │ ▼ SAVE SEQUENCE FINALIZE → CHECK_BEFORE_SAVE → point of no return → ADJUST_NUMBERS when late numbering is used → SAVE / managed persistence → database commit → CLEANUP ``` The interaction phase can contain multiple operations. Those operations build one coherent logical transaction before persistence. The save sequence begins only when the consumer or service runtime closes the transaction with a save request. ### 1.2 RAP logical unit of work A RAP LUW is the framework-controlled unit in which one or more business objects participate in a transaction. Its boundary is not owned by an individual behavior method. ```text External EML consumer MODIFY ENTITIES ... MODIFY ENTITIES ... COMMIT ENTITIES OData consumer sends transactional request/batch RAP service runtime owns save and commit orchestration4f:T95c8, # SAP RAP Service Exposure and Fiori Elements — Technical Reference This document explains how a reusable RAP business object becomes a consumer-facing OData service and a metadata-driven SAP Fiori elements application. It covers service projections, behavior projections, metadata extensions, value helps, side effects, service definitions, service bindings, OData V4 UI and Web API contracts, publication, and runtime diagnosis. The central exposure principle is: > A service projection defines the data and behavior contract for one > consumption scenario. A service definition groups the entities exposed by > that contract. A service binding chooses the protocol and service category. > UI annotations describe presentation; they do not implement or secure the > underlying business rules. Primary SAP sources: - [SAP Help — Business Object Projection](https://help.sap.com/docs/abap-cloud/abap-rap/business-object-projection-6e7a10d30b74412a9482a80b0b88e005-194) - [SAP Help — Metadata-Driven UI Annotations](https://help.sap.com/docs/abap-cloud/abap-rap/defining-cds-annotations-for-metadata-driven-uis) - [SAP Help — Providing Value Help](https://help.sap.com/docs/abap-cloud/abap-rap/providing-value-help-for-selection-fields) - [SAP Help — Side Effects](https://help.sap.com/docs/abap-cloud/abap-rap/side-effects) - [SAP Help — Service Definition](https://help.sap.com/docs/abap-cloud/abap-rap/service-definition) - [SAP Help — Business Service](https://help.sap.com/docs/abap-cloud/abap-rap/business-service) - [SAP Help — OData V4 Service Binding Editor](https://help.sap.com/docs/abap-cloud/abap-development-tools-user-guide/using-service-binding-editor-for-odata-v4-service) --- ## 1. Consumer-Facing RAP Stack ```text Reusable RAP BO Base CDS + Base BDEF + Behavior Pool │ ▼ Service Projection CDS Projection + Behavior Projection │ ├──────── Metadata Extension │ UI semantics │ ▼ Service Definition entity exposure and service aliases │ ▼ Service Binding OData V4 UI / OData V4 Web API / other supported type │ ▼ Published endpoint and metadata │ ┌─────────┴─────────┐ ▼ ▼ Fiori elements UI External API consumer ``` Each artifact makes a different decision: | Artifact | Decision | | ------------------- | ----------------------------------------------------------- | | CDS projection | Which fields and relationships this consumer sees | | Behavior projection | Which BO capabilities this consumer may call | | Metadata extension | How a metadata-driven UI presents the model | | Service definition | Which CDS entities belong to the service | | Service binding | Which protocol and service category expose it | | Fiori application | How users navigate and interact with the published contract | The service layer does not replace the BO. It exposes a selected view of it. --- ## 2. Business Object Projection ### 2.1 Purpose A BO projection adapts a reusable business object for one service use case. ```text Base SalesOrderRequest BO create, update, delete, Submit, Cancel, Approve, internal fields │ ┌──────────────┼────────────────┐ ▼ ▼ ▼ Requester UI Processor UI Integration API Create Approve stable machine fields Edit draft Reject Submit Submit internal status no UI-only annotations ``` The base BO remains the invariant and transaction boundary. Each projection can narrow fields, navigation, and operations. ### 2.2 CDS projection ```abap @EndUserText.label: 'Sales Order Request UI' @AccessControl.authorizationCheck: #CHECK @Metadata.allowExtensions: true define root view entity ZC_SalesOrderRequest provider contract transactional_query as projection on ZI_SalesOrderRequest { key RequestUUID, RequestNumber, SoldToParty, Status, TotalAmount, TransactionCurrency, LocalLastChangedAt, _Items : redirected to composition child ZC_SalesOrderItem, _Customer } ``` The projection: - exposes consumer-relevant fields; - redirects the composition to projected child nodes; - can add consumer-specific aliases and annotations where supported; - omits implementation-only fields; - forms the data side of the service contract. `transactional_query` means this projection is intended as a transactional service-consumption layer. It does not mean the entity is read-only. ### 2.3 Behavior projection ```abap projection; strict ( 2 ); define behavior for ZC_SalesOrderRequest alias SalesOrderRequest use etag { use create; use update; use delete; use action Submit; use association _Items { create; with draft; } use action Resume; use action Edit; use action Activate; use action Discard; use action Prepare; } define behavior for ZC_SalesOrderItem alias SalesOrderItem use etag { use update; use delete; use association _Request { with draft; } use association _Product; } ``` The behavior projection exposes capabilities already supported by the underlying BO. Omitting `use action Submit` prevents this projection's OData consumer from calling the base action. ### 2.4 Projection is not business-rule enforcement Omitting `TotalAmount` or `Cancel` can narrow one service. Another projection or EML consumer may still reach the base BO. Therefore these rules remain in base behavior: - Customer must be valid; - quantity must be positive; - calculated amount must be consistent; - only permitted status transitions may be saved; - user must be authorized for the operation. Projection decides exposure. Base behavior guarantees correctness. --- ## 3. Metadata Extensions ### 3.1 Purpose A metadata extension, or MDE, stores annotations separately from the CDS data definition: ```abap @Metadata.layer: #CORE @UI.headerInfo: { typeName: 'Sales Order Request', typeNamePlural: 'Sales Order Requests', title: { type: #STANDARD, value: 'RequestNumber' }, description: { value: 'SoldToParty' } } annotate entity ZC_SalesOrderRequest with { ... } ``` This separation keeps the reusable semantic/query model readable while allowing the UI contract to evolve in its own repository object. ### 3.2 Enabling extensions The annotated CDS entity normally allows metadata extensions: ```abap @Metadata.allowExtensions: true define root view entity ZC_SalesOrderRequest ... ``` The effective annotation set can include: - annotations declared directly on source entities; - propagated annotations; - annotations declared on the projection; - annotations from metadata extensions at defined layers. Use ADT's Active Annotations view when the runtime result differs from the source file being inspected. ### 3.3 Metadata layers `@Metadata.layer` participates in annotation layering and precedence. Select the layer that matches ownership of the artifact rather than using one value for every extension without understanding its purpose. In a custom application, `#CORE` commonly represents the application owner's base UI semantics. Partner and customer adaptation layers have different ownership expectations where supported. ### 3.4 Metadata extension does not execute ABAP An MDE can: - place fields in a list report or object page; - define labels, importance, facets, and action placement; - describe text and value-help behavior; - hide a field from a generated UI; - instruct a client about refresh dependencies. It cannot: - calculate `NetAmount`; - reject an invalid Customer as a universal BO invariant; - authorize a user; - commit a transaction; - update a database table; - create a service endpoint. --- ## 4. Core Fiori Elements Annotations ### 4.1 `@UI.lineItem` Controls columns or actions in a list/table presentation: ```abap @UI.lineItem: [ { position: 10, importance: #HIGH } ] RequestNumber; ``` Typical use: ```text List report table RequestNumber | Customer | Status | TotalAmount ``` `position` establishes relative order. `importance` helps responsive clients decide what to retain when screen space becomes constrained. ### 4.2 `@UI.identification` Defines fields or actions associated with the object identity/detail area: ```abap @UI.identification: [ { position: 10 } ] RequestNumber; ``` It is commonly rendered on an object page, but exact rendering remains a consumer responsibility. ### 4.3 `@UI.selectionField` Defines fields proposed for the filter bar: ```abap @UI.selectionField: [ { position: 10 } ] Status; ``` This makes the field available prominently for selection. It does not add a backend authorization restriction. ### 4.4 `@UI.facet` Defines object-page sections and navigation structure: ```abap @UI.facet: [ { id: 'General', purpose: #STANDARD, type: #IDENTIFICATION_REFERENCE, label: 'General Information', position: 10 }, { id: 'Items', purpose: #STANDARD, type: #LINEITEM_REFERENCE, label: 'Items', position: 20, targetElement: '_Items' } ] RequestUUID; ``` The Item facet requires a valid projected composition and service navigation. An annotation cannot compensate for a broken `_Items` relationship. ### 4.5 `@UI.fieldGroup` Groups related fields into a reusable UI collection: ```abap @UI.fieldGroup: [ { qualifier: 'Commercial', position: 10 } ] SoldToParty; ``` A facet can reference the qualified group to form an object-page section. ### 4.6 `@UI.hidden` ```abap @UI.hidden: true LocalLastChangedAt; ``` This removes the field from ordinary generated presentation. The field can still remain in OData metadata and be used technically, for example as an ETag. UI hiding is not a security control. --- ## 5. Complete Root Metadata Example ```abap @Metadata.layer: #CORE @UI.headerInfo: { typeName: 'Sales Order Request', typeNamePlural: 'Sales Order Requests', title: { type: #STANDARD, value: 'RequestNumber' }, description: { value: 'Status' } } annotate entity ZC_SalesOrderRequest with { @UI.facet: [ { id: 'General', purpose: #STANDARD, type: #IDENTIFICATION_REFERENCE, label: 'General Information', position: 10 }, { id: 'Items', purpose: #STANDARD, type: #LINEITEM_REFERENCE, label: 'Items', position: 20, targetElement: '_Items' } ] RequestUUID; @UI: { lineItem: [ { position: 10, importance: #HIGH } ], identification: [ { position: 10 } ] } @EndUserText.label: 'Request' RequestNumber; @UI: { lineItem: [ { position: 20, importance: #HIGH } ], identification: [ { position: 20 } ], selectionField: [ { position: 10 } ] } @EndUserText.label: 'Sold-to Party' SoldToParty; @UI: { lineItem: [ { position: 30, importance: #HIGH } ], identification: [ { position: 30 } ], selectionField: [ { position: 20 } ] } Status; @UI: { lineItem: [ { position: 40, importance: #HIGH } ], identification: [ { position: 40 } ] } TotalAmount; @UI.hidden: true RequestUUID; @UI.hidden: true LocalLastChangedAt; } ``` The amount/currency relationship should already exist in the CDS semantic model. The UI annotation places `TotalAmount`; it does not need to recreate the calculation. --- ## 6. Child Metadata and Composition Rendering ```abap @Metadata.layer: #CORE annotate entity ZC_SalesOrderItem with { @UI.lineItem: [ { position: 10, importance: #HIGH } ] Product; @UI.lineItem: [ { position: 20, importance: #HIGH } ] RequestedQuantity; @UI.lineItem: [ { position: 30, importance: #MEDIUM } ] UnitPrice; @UI.lineItem: [ { position: 40, importance: #HIGH } ] NetAmount; @UI.hidden: true ItemUUID; @UI.hidden: true RequestUUID; @UI.hidden: true LocalLastChangedAt; } ``` For the object page to render editable Items correctly, all of these layers must align: ```text Base CDS composition → base BDEF create-by-association → projected CDS redirection → projected BDEF association create → service entity exposure/navigation → root facet targets `_Items` → child has `@UI.lineItem` ``` A problem at any layer can appear as a missing table, missing Create button, empty navigation, or read-only child section. --- ## 7. UI Actions ### 7.1 Action placement The action must exist in base behavior and be used in the behavior projection. Metadata can then place it: ```abap @UI.lineItem: [ { type: #FOR_ACTION, dataAction: 'Submit', label: 'Submit', position: 50 } ] RequestNumber; ``` Action naming in metadata must match the service-visible action name, including any projection aliasing or external naming. ### 7.2 End-to-end action visibility ```text Base BDEF action Submit │ ▼ Behavior Projection use action Submit │ ▼ OData metadata action import/bound action contract │ ▼ UI annotation #FOR_ACTION + dataAction │ ▼ Fiori button ``` ### 7.3 Feature control Instance feature control can disable Submit when Status is already Submitted. The UI consumes the result and adjusts affordance. Backend behavior remains the source of truth; do not implement the state rule only as frontend visibility. --- ## 8. Texts and Text Arrangement ### 8.1 Code and description Business fields often contain a compact key and a human-readable text: ```text Product = HT-1000 ProductName = Notebook Basic 15 ``` CDS associations and text annotations allow consumers to present both without copying the text into transactional persistence. ### 8.2 Text arrangement ```abap @UI.textArrangement: #TEXT_LAST Product; ``` Possible arrangements depend on supported metadata and can favor: - key only; - text only; - text followed by key; - key followed by text. The annotation controls presentation. It does not change the stored Product ID. ### 8.3 Historical snapshot boundary Use a live association when the UI should show the current master-data text. Persist a copied description only when the transaction has a genuine historical snapshot requirement. Those are different domain semantics. --- ## 9. Value Help ### 9.1 Purpose A value help connects an input field to a lookup provider: ```abap @Consumption.valueHelpDefinition: [ { entity: { name: 'ZI_CustomerValueHelp', element: 'CustomerID' } } ] SoldToParty; ``` The consumer can query the provider, display key/text/filter columns, and copy the selected key into `SoldToParty`. ### 9.2 Provider model ```abap @EndUserText.label: 'Customer Value Help' @ObjectModel.resultSet.sizeCategory: #XS define view entity ZI_CustomerValueHelp as select from ZI_CustomerReference { key CustomerID, CustomerName, CountryCode } ``` A good value-help provider has: - stable key element; - useful descriptive text; - fields required for search/filter/display; - correct authorization behavior; - an appropriate result-set shape and size strategy; - no accidental exposure of sensitive master data. ### 9.3 Service exposure The value-help provider must be reachable through the service contract when the consumer needs to query it. In many RAP OData services, that means exposing the provider entity in the service definition: ```abap expose ZI_CustomerValueHelp as CustomerValueHelp; ``` Defining the annotation alone does not publish an entity set. ### 9.4 `useForValidation: true` ```abap @Consumption.valueHelpDefinition: [ { entity: { name: 'ZI_CustomerValueHelp', element: 'CustomerID' }, useForValidation: true } ] SoldToParty; ``` This marks the value-help definition for validation of user input. Supported consumer/framework processing can check entered values against the provider's allowed result set. It does not replace a RAP behavior validation when: - validity depends on Status, date, Sales Area, role, or other BO state; - the rule must protect direct EML and every service projection; - the provider list is a convenience subset rather than the domain truth; - the rule requires a precise backend error message; - security or transactional consistency is involved; - the referenced object can change between input and save. Use value-help validation for the lookup constraint and backend validation for the durable business invariant. ### 9.5 Additional binding A value help can pass context fields into or out of the provider, for example filtering Product by Sales Organization or returning a related Unit. Model those bindings explicitly and ensure their fields are exposed in the service metadata. Do not hide a missing business determination inside a value-help side effect. Returned values should have a clearly owned source of truth. --- ## 10. Why a Service Definition May Expose Reference Entities Representative Travel service: ```abap define service ZUI_TRAVEL { expose ZC_Travel as Travel; expose ZC_Booking as Booking; expose ZI_AgencyVH as Agency; expose ZI_CustomerVH as Customer; expose ZI_FlightVH as Flight; expose I_Currency as Currency; expose I_Country as Country; } ``` Reference entities can be exposed because the consumer needs them for: - value-help queries; - text retrieval; - direct navigation targets; - filtering or autocomplete; - dependent lookup fields; - service metadata relationships; - an API operation that legitimately reads the reference collection. Do not expose every CDS association automatically. Expose an entity when the service contract requires it and when its authorization/data surface is safe. The correct rule is broader than “expose it only when it appears as a scalar field in the projection.” A provider may need exposure even when used through value help or navigation rather than displayed as a root field. --- ## 11. Service Definition ### 11.1 Responsibility A service definition is a protocol-independent repository object that groups the CDS entities exposed by one business service. ```abap @EndUserText.label: 'Sales Order Request UI Service' @ObjectModel.leadingEntity.name: 'ZC_SalesOrderRequest' define service ZUI_SALESORDERREQUEST { expose ZC_SalesOrderRequest as SalesOrderRequests; expose ZC_SalesOrderItem as SalesOrderItems; expose ZI_CustomerValueHelp as Customers; expose ZI_ProductValueHelp as Products; expose I_Currency as Currencies; } ``` The service definition decides: - which entity models belong to this service; - their service-visible aliases; - the primary/leading entity where declared; - which navigation and lookup targets can become reachable. It does not decide: - whether the service uses OData V2 or V4; - whether it is a UI service or Web API; - the HTTP endpoint URL; - how CRUD is implemented; - whether the current user is authorized; - whether the service is published. ### 11.2 Service aliases ```abap expose ZC_SalesOrderRequest as SalesOrderRequests; ``` The alias decouples the external entity-set name from the CDS technical object name. Choose a stable consumer-oriented name and treat changes as API contract changes. ### 11.3 Complete service graph For a composition-based UI, expose all nodes needed by the business service. The root alone is not always sufficient when child entity sets, navigation, metadata, or value helps must be reachable. At the same time, exposure should be minimal. Every extra entity adds: - metadata and compatibility surface; - possible direct query access; - authorization and performance responsibility; - maintenance and release obligations. --- ## 12. Service Binding ### 12.1 Responsibility A service binding assigns the service definition to a supported protocol and service category. ```text Service Definition protocol-independent model │ ├── OData V4 UI binding ├── OData V4 Web API binding └── another supported binding type ``` One service definition can be used by multiple bindings when the same service contract is appropriate. If UI and integration consumers require materially different fields, operations, versioning, or lifecycle promises, use separate projections and often separate service definitions rather than forcing one oversized contract. ### 12.2 OData V4 UI Designed for metadata-driven user interfaces such as Fiori elements. It consumes UI annotations, draft metadata, actions, value helps, side effects, messages, field control, and navigation. ### 12.3 OData V4 Web API Designed for machine-to-machine consumption. Its contract should emphasize: - stable external names; - explicit operation semantics; - controlled versioning; - predictable messages and HTTP outcomes; - API authorization; - idempotency and concurrency behavior; - minimal UI-specific metadata. A UI projection is not automatically a good public API merely because both use OData V4. ### 12.4 OData V2 and `@OData.publish: true` Older examples often use OData V2 or `@OData.publish: true`. Current RAP design normally favors explicit service definitions and bindings because they provide a clearer service contract, category, protocol choice, versioning, and publication lifecycle. Do not copy an older workshop's V2 binding solely because the sample predates OData V4 support. Confirm the target ABAP release and consumer requirement. --- ## 13. Metadata Request Runtime ```text Fiori client requests $metadata │ ▼ Published Service Binding │ ▼ Service Definition exposed entity aliases and relationships │ ▼ CDS Projection + Behavior Projection fields, navigation, actions, field/ETag/draft contract │ ▼ Metadata Extension + annotations line items, facets, labels, value help, side effects │ ▼ OData metadata document │ ▼ Fiori elements generates list/object-page behavior ``` No behavior-pool method is normally called merely to compile static metadata. Dynamic feature or authorization requests occur when the client asks for the corresponding runtime permissions or data. ### 13.1 Metadata caching After changing CDS, behavior projection, or annotations: - activate all dependent artifacts; - verify the intended service version is published; - inspect live `$metadata` rather than only source code; - refresh or clear relevant client metadata caches; - confirm the browser is calling the expected endpoint. Many apparent annotation defects are stale-metadata defects. --- ## 14. Query and Navigation Runtime ### 14.1 List report read ```text Fiori GET SalesOrderRequests → OData V4 binding → service entity alias → CDS transactional query projection → CDS access control and query runtime → database query → OData response → lineItem rendering ``` The normal CDS-backed query path does not require a behavior-pool read method for a managed query. ### 14.2 Object-page navigation ```text Select one Request → GET by key → object-page identification/facets rendered → expand or navigate `_Items` → projected composition target → child query → child line items rendered ``` ### 14.3 Value-help request ```text User opens SoldToParty value help → metadata identifies provider entity/element → client queries Customers entity set → DCL and service authorization apply → search/filter/order/page options processed → key and text returned → selected CustomerID copied to SoldToParty ``` The provider may return no values because of authorization or filters even when the underlying table contains records. --- ## 15. Side Effects ### 15.1 Purpose Side effects describe which fields, entities, permissions, or messages should be refreshed after a source value or action changes. ```text RequestedQuantity changes → determination recalculates NetAmount → root aggregation recalculates TotalAmount → side-effect metadata tells UI what to reread ``` The determination performs the calculation. The side effect synchronizes the consumer presentation with backend state. ### 15.2 Representative declaration Exact supported syntax depends on the BDEF and target release, but the model is: ```abap side effects { field RequestedQuantity affects field NetAmount; field UnitPrice affects field NetAmount; action Submit affects field Status, permissions ( action Submit ); } ``` Cross-entity dependencies can require association or entity targets supported by the release and service protocol. ### 15.3 Side effects are not determinations ```text Determination changes backend BO state Side effect declares consumer refresh dependency ``` If a side effect exists but no backend logic updates `NetAmount`, the reread returns the same value. If determination exists but side effects are missing, the backend state can be correct while the UI continues showing an old value. --- ## 16. Security Boundaries ### 16.1 UI hiding `@UI.hidden: true` controls presentation. A malicious or custom client can still inspect or request an OData property if the service exposes it and the protocol permits access. ### 16.2 Projection omission Omitting `InternalProcessingCode` from the CDS projection removes it from that service contract. This is stronger than UI hiding but still does not replace authorization for remaining fields and operations. ### 16.3 CDS DCL DCL restricts readable rows for the CDS entity where it is applied. Test the actual consumption entity; do not assume access controls automatically propagate through every view stack. ### 16.4 RAP authorization RAP authorization controls create, update, delete, associations, actions, and other modifying capabilities based on the current user and context. ### 16.5 Value-help security A value-help entity is a query surface. Apply appropriate authorization and expose only the columns needed for selection. Do not treat lookup data as automatically harmless. ```text UI annotation presentation Projection contract surface DCL read-row restriction RAP authorization modify-operation permission Backend validation business invariant ``` All five can be required in one service. --- ## 17. Activate, Publish, Transport, and Deploy ### 17.1 Activate Creates the active repository version after syntax and dependency checks. ```text CDS/MDE/BDEF/service source → Activate in ADT → active ABAP repository object ``` Activation does not make an OData endpoint externally available by itself. ### 17.2 Publish Publishing a service binding enables/registers the service endpoint in the connected ABAP system according to that environment's lifecycle. ```text Active service definition + binding → Publish → callable local system endpoint/version ``` ### 17.3 Transport Transport moves repository and configuration artifacts through the system landscape, for example development to quality to production. Local publication status and environment-specific service setup can still require lifecycle handling in each target system. ### 17.4 Deploy Deployment often refers to delivering a separate frontend application to its runtime or making a complete solution available. It is not a synonym for ABAP artifact activation. ```text Activate repository code becomes active in one ABAP system Publish service endpoint becomes available in that system Transport artifacts move between ABAP systems Deploy separate application/content reaches its target runtime ``` --- ## 18. Fiori Elements Preview The service-binding editor can launch a Fiori elements preview for suitable UI services. Preview is valuable for validating: - entity-set availability; - list report columns; - object-page facets; - composition navigation; - value helps; - draft actions; - action placement; - field control and messages; - side-effect refresh. Preview is not a substitute for a production Fiori application. It does not prove: - launchpad role/catalog configuration; - semantic-object and target-mapping correctness; - production authorization roles; - frontend deployment and routing; - accessibility and UX review; - API compatibility; - performance under real volume. --- ## 19. End-to-End Sales Order Request UI Flow ### 19.1 Open list report ```text 1. Browser loads Fiori elements application. 2. Client requests OData `$metadata`. 3. Service binding resolves ZUI_SALESORDERREQUEST. 4. Metadata describes SalesOrderRequests, Items, actions, value helps, and UI. 5. Client requests SalesOrderRequests with query options. 6. RAP query runtime reads ZC_SalesOrderRequest under DCL. 7. `@UI.lineItem` fields form the table. ``` ### 19.2 Create request draft ```text 1. Create visibility comes from projected behavior. 2. Client creates a draft root. 3. Managed RAP assigns RequestUUID and persists draft state. 4. Object page uses headerInfo and identification annotations. 5. SoldToParty value help queries the exposed Customers provider. 6. Item facet navigates through projected `_Items` composition. ``` ### 19.3 Change quantity ```text 1. UI PATCH changes RequestedQuantity on draft Item. 2. Behavior determination recalculates NetAmount and TotalAmount. 3. Side-effect metadata tells UI to reread affected fields. 4. Refreshed values are formatted with unit/currency semantics. 5. No active business data changes until activation. ``` ### 19.4 Submit ```text 1. Action exists in base BDEF and behavior pool. 2. Behavior projection exposes Submit. 3. UI annotation renders the action button. 4. Instance feature control enables it for eligible Status. 5. RAP authorization checks the user's permission. 6. Handler changes buffered state and returns action result/messages. 7. Draft Prepare/Activate validations protect final persistence. 8. UI refreshes Status and action permissions. ``` --- ## 20. Technical Diagnostics ### 20.1 Entity is absent from the service Check: ```text CDS projection active → service definition `expose` → correct service alias → service binding references intended definition/version → binding published → live `$metadata` → client endpoint and cache ``` ### 20.2 Field is absent Check: 1. base CDS element; 2. CDS projection list; 3. active metadata annotations; 4. service metadata property; 5. UI annotation placement; 6. client personalization and cache. If the property is absent from `$metadata`, the defect is before UI rendering. ### 20.3 Create/Edit/Delete button is missing Check: 1. base BDEF operation; 2. behavior projection `use` declaration; 3. draft actions if draft is enabled; 4. dynamic feature result; 5. RAP authorization result; 6. current service metadata; 7. Fiori page mode and client cache. ### 20.4 Action button is missing Trace: ```text Base action declaration → behavior-pool method → behavior projection `use action` → service-visible action name → `@UI.lineItem` or `@UI.identification` action annotation → feature control → live metadata ``` ### 20.5 Item facet is empty Check: - root facet `targetElement` spelling; - projected composition redirection; - child projection and service exposure; - active/draft navigation context; - parent/child keys and `ON` condition; - DCL on child query; - whether Items exist in the relevant active/draft state. ### 20.6 Value-help icon or values are missing Check: 1. active `@Consumption.valueHelpDefinition`; 2. exact provider entity and element names; 3. provider exposed/reachable in the service; 4. provider appears in `$metadata`; 5. DCL/authorization permits provider rows; 6. additional-binding fields exist and contain values; 7. search/filter metadata and data types are compatible; 8. browser calls the expected endpoint. ### 20.7 Value accepted by UI but save fails This can be correct when value help and business validation enforce different rules. Capture: - selected provider row; - `useForValidation` setting; - current BO Status, Sales Area, date, and other context; - backend validation message; - whether the reference changed between selection and save. The business validation remains authoritative. ### 20.8 Derived value changes in backend but not UI Check: ```text Determination actually updates buffer → nested EML messages/failures → side-effect source field/action → affected target field/entity → target property exposed → UI reread network request → response value and metadata cache ``` ### 20.9 Works in preview but not launchpad Inspect the application-level delivery chain: - deployed frontend application/component; - destination and service URL; - OData service activation/publication in the target system; - launchpad catalog and role; - semantic object and action; - target mapping; - user frontend/backend authorizations; - cache and gateway error logs; - transport completeness. Preview proves the local service/UI metadata path, not the full launchpad setup. --- ## 21. UI and API Contract Design ### 21.1 Separate contracts when promises differ ```text UI service draft editing UI annotations role-specific actions user-facing state messages Web API versioned stable schema machine-oriented operation names explicit concurrency requirements integration authorization minimal navigation and lookup surface ``` Reusing one service definition can be appropriate for closely aligned consumers. Separate projections are appropriate when the contract lifecycle and exposed capabilities differ materially. ### 21.2 Avoid exposing implementation details Do not expose: - internal processing codes without a consumer contract; - raw administrative fields that consumers do not need; - direct write access to derived fields; - unrestricted master-data lookup collections; - legacy persistence names as public API names; - actions whose semantics are not stable. ### 21.3 Versioning Treat service aliases, field types, nullability, actions, navigation paths, and message behavior as compatibility surface. A published Web API requires a stronger compatibility policy than a private preview service. --- ## 22. Exposure Review Checklist ### Projection - CDS projection contains only consumer-relevant fields and navigation. - `transactional_query` provider contract is explicit. - Compositions and parents redirect to projected nodes. - Behavior projection exposes only required operations and actions. - Derived/internal fields have consistent behavior and visibility. - UI and API consumers use separate contracts when their promises differ. ### Metadata - UI annotations are stored in metadata extensions where practical. - Header, line item, identification, filters, and facets reflect the entity grain. - Item facet targets a valid projected composition. - Technical fields are hidden for presentation but retained when runtime needs them. - Action metadata matches the service-visible action name. - Text associations and arrangements do not change stored identity. ### Value help and side effects - Lookup provider exposes only needed, authorized fields. - Provider and key element are reachable in the service. - `useForValidation` is used intentionally and not confused with BO validation. - Additional bindings pass complete context. - Determinations calculate; side effects trigger consumer refresh. - Cross-entity refresh is verified through actual network responses. ### Service - Service definition exposes the complete required graph and no accidental entities. - External aliases are stable and consumer-oriented. - Binding type matches UI or API use. - Intended service version is active and published. - Live `$metadata` is reviewed after changes. - Transport and frontend deployment requirements are documented separately. ### Security - UI hiding is never treated as access control. - Projection omission, DCL, RAP authorization, and validation are all applied at their proper boundaries. - Value-help endpoints are treated as data APIs. - Preview and launchpad authorization are tested independently. --- ## 23. Compact Exposure Map ```text BASE RAP BO ZI_SalesOrderRequest + Base BDEF + Behavior Pool reusable data, operations, invariants, transaction handling │ ▼ SERVICE PROJECTION ZC_SalesOrderRequest CDS fields/navigation Projection BDEF use CRUD/actions/draft Metadata Extension lineItem/facet/value help/action/side effect │ ▼ SERVICE DEFINITION SalesOrderRequests SalesOrderItems Customers value help Products value help Currencies │ ▼ SERVICE BINDING OData V4 UI Fiori elements metadata-driven application OData V4 Web API machine-oriented integration contract │ ▼ RUNTIME $metadata contract and annotations GET CDS query + DCL PATCH/POST/action RAP behavior + authorization + transaction value-help GET lookup provider query side-effect reread synchronize UI with backend derivation ``` The consumer layer should always be read through five separate concerns: ```text Projection narrows the reusable BO. Metadata describes presentation. Service definition selects entity exposure. Service binding selects protocol and service category. Backend behavior and authorization protect correctness. ``` 50:T89e,SAP RAP Service Exposure and Fiori Elements — Technical Reference This document explains how a reusable RAP business object becomes a consumer-facing OData service and a metadata-driven SAP Fiori elements application. It covers service projections, behavior projections, metadata extensions, value helps, side effects, service definitions, service bindings, OData V4 UI and Web API contracts, publication, and runtime diagnosis. The central exposure principle is: A service projection defines the data and behavior contract for one consumption scenario. A service definition groups the entities exposed by that contract. A service binding chooses the protocol and service category. UI annotations describe presentation; they do not implement or secure the underlying business rules. Primary SAP sources: - SAP Help — Business Object Projection - SAP Help — Metadata-Driven UI Annotations - SAP Help — Providing Value Help - SAP Help — Side Effects - SAP Help — Service Definition - SAP Help — Business Service - SAP Help — OData V4 Service Binding Editor --- 1. Consumer-Facing RAP Stack text Reusable RAP BO Base CDS + Base BDEF + Behavior Pool │ ▼ Service Projection CDS Projection + Behavior Projection │ ├──────── Metadata Extension │ UI semantics │ ▼ Service Definition entity exposure and service aliases │ ▼ Service Binding OData V4 UI / OData V4 Web API / other supported type │ ▼ Published endpoint and metadata │ ┌─────────┴─────────┐ ▼ ▼ Fiori elements UI External API consumer Each artifact makes a different decision: | Artifact | Decision | | ------------------- | ----------------------------------------------------------- | | CDS projection | Which fields and relationships this consumer sees | | Behavior projection | Which BO capabilities this consumer may call | | Metadata extension | How a metadata-driven UI presents the model | | Service definition | Which CDS entities belong to the service | | Service binding | Which protocol and service category expose it | | Fiori application | How users navigate and interact with the published contract | The service layer does not replace51:Ta1a,# SAP RAP Service Exposure and Fiori Elements — Technical Reference This document explains how a reusable RAP business object becomes a consumer-facing OData service and a metadata-driven SAP Fiori elements application. It covers service projections, behavior projections, metadata extensions, value helps, side effects, service definitions, service bindings, OData V4 UI and Web API contracts, publication, and runtime diagnosis. The central exposure principle is: > A service projection defines the data and behavior contract for one > consumption scenario. A service definition groups the entities exposed by > that contract. A service binding chooses the protocol and service category. > UI annotations describe presentation; they do not implement or secure the > underlying business rules. Primary SAP sources: - [SAP Help — Business Object Projection](https://help.sap.com/docs/abap-cloud/abap-rap/business-object-projection-6e7a10d30b74412a9482a80b0b88e005-194) - [SAP Help — Metadata-Driven UI Annotations](https://help.sap.com/docs/abap-cloud/abap-rap/defining-cds-annotations-for-metadata-driven-uis) - [SAP Help — Providing Value Help](https://help.sap.com/docs/abap-cloud/abap-rap/providing-value-help-for-selection-fields) - [SAP Help — Side Effects](https://help.sap.com/docs/abap-cloud/abap-rap/side-effects) - [SAP Help — Service Definition](https://help.sap.com/docs/abap-cloud/abap-rap/service-definition) - [SAP Help — Business Service](https://help.sap.com/docs/abap-cloud/abap-rap/business-service) - [SAP Help — OData V4 Service Binding Editor](https://help.sap.com/docs/abap-cloud/abap-development-tools-user-guide/using-service-binding-editor-for-odata-v4-service) --- ## 1. Consumer-Facing RAP Stack ```text Reusable RAP BO Base CDS + Base BDEF + Behavior Pool │ ▼ Service Projection CDS Projection + Behavior Projection │ ├──────── Metadata Extension │ UI semantics │ ▼ Service Definition entity exposure and service aliases │ ▼ Service Binding OData V4 UI / OData V4 Web API / other supported type │ ▼ Published endpoint and metadata │ ┌─────────┴─────────┐ ▼ ▼ Fiori elements UI External API consumer ``` Each artifact makes a different decision:52:T95c8, # SAP RAP Service Exposure and Fiori Elements — Technical Reference This document explains how a reusable RAP business object becomes a consumer-facing OData service and a metadata-driven SAP Fiori elements application. It covers service projections, behavior projections, metadata extensions, value helps, side effects, service definitions, service bindings, OData V4 UI and Web API contracts, publication, and runtime diagnosis. The central exposure principle is: > A service projection defines the data and behavior contract for one > consumption scenario. A service definition groups the entities exposed by > that contract. A service binding chooses the protocol and service category. > UI annotations describe presentation; they do not implement or secure the > underlying business rules. Primary SAP sources: - [SAP Help — Business Object Projection](https://help.sap.com/docs/abap-cloud/abap-rap/business-object-projection-6e7a10d30b74412a9482a80b0b88e005-194) - [SAP Help — Metadata-Driven UI Annotations](https://help.sap.com/docs/abap-cloud/abap-rap/defining-cds-annotations-for-metadata-driven-uis) - [SAP Help — Providing Value Help](https://help.sap.com/docs/abap-cloud/abap-rap/providing-value-help-for-selection-fields) - [SAP Help — Side Effects](https://help.sap.com/docs/abap-cloud/abap-rap/side-effects) - [SAP Help — Service Definition](https://help.sap.com/docs/abap-cloud/abap-rap/service-definition) - [SAP Help — Business Service](https://help.sap.com/docs/abap-cloud/abap-rap/business-service) - [SAP Help — OData V4 Service Binding Editor](https://help.sap.com/docs/abap-cloud/abap-development-tools-user-guide/using-service-binding-editor-for-odata-v4-service) --- ## 1. Consumer-Facing RAP Stack ```text Reusable RAP BO Base CDS + Base BDEF + Behavior Pool │ ▼ Service Projection CDS Projection + Behavior Projection │ ├──────── Metadata Extension │ UI semantics │ ▼ Service Definition entity exposure and service aliases │ ▼ Service Binding OData V4 UI / OData V4 Web API / other supported type │ ▼ Published endpoint and metadata │ ┌─────────┴─────────┐ ▼ ▼ Fiori elements UI External API consumer ``` Each artifact makes a different decision: | Artifact | Decision | | ------------------- | ----------------------------------------------------------- | | CDS projection | Which fields and relationships this consumer sees | | Behavior projection | Which BO capabilities this consumer may call | | Metadata extension | How a metadata-driven UI presents the model | | Service definition | Which CDS entities belong to the service | | Service binding | Which protocol and service category expose it | | Fiori application | How users navigate and interact with the published contract | The service layer does not replace the BO. It exposes a selected view of it. --- ## 2. Business Object Projection ### 2.1 Purpose A BO projection adapts a reusable business object for one service use case. ```text Base SalesOrderRequest BO create, update, delete, Submit, Cancel, Approve, internal fields │ ┌──────────────┼────────────────┐ ▼ ▼ ▼ Requester UI Processor UI Integration API Create Approve stable machine fields Edit draft Reject Submit Submit internal status no UI-only annotations ``` The base BO remains the invariant and transaction boundary. Each projection can narrow fields, navigation, and operations. ### 2.2 CDS projection ```abap @EndUserText.label: 'Sales Order Request UI' @AccessControl.authorizationCheck: #CHECK @Metadata.allowExtensions: true define root view entity ZC_SalesOrderRequest provider contract transactional_query as projection on ZI_SalesOrderRequest { key RequestUUID, RequestNumber, SoldToParty, Status, TotalAmount, TransactionCurrency, LocalLastChangedAt, _Items : redirected to composition child ZC_SalesOrderItem, _Customer } ``` The projection: - exposes consumer-relevant fields; - redirects the composition to projected child nodes; - can add consumer-specific aliases and annotations where supported; - omits implementation-only fields; - forms the data side of the service contract. `transactional_query` means this projection is intended as a transactional service-consumption layer. It does not mean the entity is read-only. ### 2.3 Behavior projection ```abap projection; strict ( 2 ); define behavior for ZC_SalesOrderRequest alias SalesOrderRequest use etag { use create; use update; use delete; use action Submit; use association _Items { create; with draft; } use action Resume; use action Edit; use action Activate; use action Discard; use action Prepare; } define behavior for ZC_SalesOrderItem alias SalesOrderItem use etag { use update; use delete; use association _Request { with draft; } use association _Product; } ``` The behavior projection exposes capabilities already supported by the underlying BO. Omitting `use action Submit` prevents this projection's OData consumer from calling the base action. ### 2.4 Projection is not business-rule enforcement Omitting `TotalAmount` or `Cancel` can narrow one service. Another projection or EML consumer may still reach the base BO. Therefore these rules remain in base behavior: - Customer must be valid; - quantity must be positive; - calculated amount must be consistent; - only permitted status transitions may be saved; - user must be authorized for the operation. Projection decides exposure. Base behavior guarantees correctness. --- ## 3. Metadata Extensions ### 3.1 Purpose A metadata extension, or MDE, stores annotations separately from the CDS data definition: ```abap @Metadata.layer: #CORE @UI.headerInfo: { typeName: 'Sales Order Request', typeNamePlural: 'Sales Order Requests', title: { type: #STANDARD, value: 'RequestNumber' }, description: { value: 'SoldToParty' } } annotate entity ZC_SalesOrderRequest with { ... } ``` This separation keeps the reusable semantic/query model readable while allowing the UI contract to evolve in its own repository object. ### 3.2 Enabling extensions The annotated CDS entity normally allows metadata extensions: ```abap @Metadata.allowExtensions: true define root view entity ZC_SalesOrderRequest ... ``` The effective annotation set can include: - annotations declared directly on source entities; - propagated annotations; - annotations declared on the projection; - annotations from metadata extensions at defined layers. Use ADT's Active Annotations view when the runtime result differs from the source file being inspected. ### 3.3 Metadata layers `@Metadata.layer` participates in annotation layering and precedence. Select the layer that matches ownership of the artifact rather than using one value for every extension without understanding its purpose. In a custom application, `#CORE` commonly represents the application owner's base UI semantics. Partner and customer adaptation layers have different ownership expectations where supported. ### 3.4 Metadata extension does not execute ABAP An MDE can: - place fields in a list report or object page; - define labels, importance, facets, and action placement; - describe text and value-help behavior; - hide a field from a generated UI; - instruct a client about refresh dependencies. It cannot: - calculate `NetAmount`; - reject an invalid Customer as a universal BO invariant; - authorize a user; - commit a transaction; - update a database table; - create a service endpoint. --- ## 4. Core Fiori Elements Annotations ### 4.1 `@UI.lineItem` Controls columns or actions in a list/table presentation: ```abap @UI.lineItem: [ { position: 10, importance: #HIGH } ] RequestNumber; ``` Typical use: ```text List report table RequestNumber | Customer | Status | TotalAmount ``` `position` establishes relative order. `importance` helps responsive clients decide what to retain when screen space becomes constrained. ### 4.2 `@UI.identification` Defines fields or actions associated with the object identity/detail area: ```abap @UI.identification: [ { position: 10 } ] RequestNumber; ``` It is commonly rendered on an object page, but exact rendering remains a consumer responsibility. ### 4.3 `@UI.selectionField` Defines fields proposed for the filter bar: ```abap @UI.selectionField: [ { position: 10 } ] Status; ``` This makes the field available prominently for selection. It does not add a backend authorization restriction. ### 4.4 `@UI.facet` Defines object-page sections and navigation structure: ```abap @UI.facet: [ { id: 'General', purpose: #STANDARD, type: #IDENTIFICATION_REFERENCE, label: 'General Information', position: 10 }, { id: 'Items', purpose: #STANDARD, type: #LINEITEM_REFERENCE, label: 'Items', position: 20, targetElement: '_Items' } ] RequestUUID; ``` The Item facet requires a valid projected composition and service navigation. An annotation cannot compensate for a broken `_Items` relationship. ### 4.5 `@UI.fieldGroup` Groups related fields into a reusable UI collection: ```abap @UI.fieldGroup: [ { qualifier: 'Commercial', position: 10 } ] SoldToParty; ``` A facet can reference the qualified group to form an object-page section. ### 4.6 `@UI.hidden` ```abap @UI.hidden: true LocalLastChangedAt; ``` This removes the field from ordinary generated presentation. The field can still remain in OData metadata and be used technically, for example as an ETag. UI hiding is not a security control. --- ## 5. Complete Root Metadata Example ```abap @Metadata.layer: #CORE @UI.headerInfo: { typeName: 'Sales Order Request', typeNamePlural: 'Sales Order Requests', title: { type: #STANDARD, value: 'RequestNumber' }, description: { value: 'Status' } } annotate entity ZC_SalesOrderRequest with { @UI.facet: [ { id: 'General', purpose: #STANDARD, type: #IDENTIFICATION_REFERENCE, label: 'General Information', position: 10 }, { id: 'Items', purpose: #STANDARD, type: #LINEITEM_REFERENCE, label: 'Items', position: 20, targetElement: '_Items' } ] RequestUUID; @UI: { lineItem: [ { position: 10, importance: #HIGH } ], identification: [ { position: 10 } ] } @EndUserText.label: 'Request' RequestNumber; @UI: { lineItem: [ { position: 20, importance: #HIGH } ], identification: [ { position: 20 } ], selectionField: [ { position: 10 } ] } @EndUserText.label: 'Sold-to Party' SoldToParty; @UI: { lineItem: [ { position: 30, importance: #HIGH } ], identification: [ { position: 30 } ], selectionField: [ { position: 20 } ] } Status; @UI: { lineItem: [ { position: 40, importance: #HIGH } ], identification: [ { position: 40 } ] } TotalAmount; @UI.hidden: true RequestUUID; @UI.hidden: true LocalLastChangedAt; } ``` The amount/currency relationship should already exist in the CDS semantic model. The UI annotation places `TotalAmount`; it does not need to recreate the calculation. --- ## 6. Child Metadata and Composition Rendering ```abap @Metadata.layer: #CORE annotate entity ZC_SalesOrderItem with { @UI.lineItem: [ { position: 10, importance: #HIGH } ] Product; @UI.lineItem: [ { position: 20, importance: #HIGH } ] RequestedQuantity; @UI.lineItem: [ { position: 30, importance: #MEDIUM } ] UnitPrice; @UI.lineItem: [ { position: 40, importance: #HIGH } ] NetAmount; @UI.hidden: true ItemUUID; @UI.hidden: true RequestUUID; @UI.hidden: true LocalLastChangedAt; } ``` For the object page to render editable Items correctly, all of these layers must align: ```text Base CDS composition → base BDEF create-by-association → projected CDS redirection → projected BDEF association create → service entity exposure/navigation → root facet targets `_Items` → child has `@UI.lineItem` ``` A problem at any layer can appear as a missing table, missing Create button, empty navigation, or read-only child section. --- ## 7. UI Actions ### 7.1 Action placement The action must exist in base behavior and be used in the behavior projection. Metadata can then place it: ```abap @UI.lineItem: [ { type: #FOR_ACTION, dataAction: 'Submit', label: 'Submit', position: 50 } ] RequestNumber; ``` Action naming in metadata must match the service-visible action name, including any projection aliasing or external naming. ### 7.2 End-to-end action visibility ```text Base BDEF action Submit │ ▼ Behavior Projection use action Submit │ ▼ OData metadata action import/bound action contract │ ▼ UI annotation #FOR_ACTION + dataAction │ ▼ Fiori button ``` ### 7.3 Feature control Instance feature control can disable Submit when Status is already Submitted. The UI consumes the result and adjusts affordance. Backend behavior remains the source of truth; do not implement the state rule only as frontend visibility. --- ## 8. Texts and Text Arrangement ### 8.1 Code and description Business fields often contain a compact key and a human-readable text: ```text Product = HT-1000 ProductName = Notebook Basic 15 ``` CDS associations and text annotations allow consumers to present both without copying the text into transactional persistence. ### 8.2 Text arrangement ```abap @UI.textArrangement: #TEXT_LAST Product; ``` Possible arrangements depend on supported metadata and can favor: - key only; - text only; - text followed by key; - key followed by text. The annotation controls presentation. It does not change the stored Product ID. ### 8.3 Historical snapshot boundary Use a live association when the UI should show the current master-data text. Persist a copied description only when the transaction has a genuine historical snapshot requirement. Those are different domain semantics. --- ## 9. Value Help ### 9.1 Purpose A value help connects an input field to a lookup provider: ```abap @Consumption.valueHelpDefinition: [ { entity: { name: 'ZI_CustomerValueHelp', element: 'CustomerID' } } ] SoldToParty; ``` The consumer can query the provider, display key/text/filter columns, and copy the selected key into `SoldToParty`. ### 9.2 Provider model ```abap @EndUserText.label: 'Customer Value Help' @ObjectModel.resultSet.sizeCategory: #XS define view entity ZI_CustomerValueHelp as select from ZI_CustomerReference { key CustomerID, CustomerName, CountryCode } ``` A good value-help provider has: - stable key element; - useful descriptive text; - fields required for search/filter/display; - correct authorization behavior; - an appropriate result-set shape and size strategy; - no accidental exposure of sensitive master data. ### 9.3 Service exposure The value-help provider must be reachable through the service contract when the consumer needs to query it. In many RAP OData services, that means exposing the provider entity in the service definition: ```abap expose ZI_CustomerValueHelp as CustomerValueHelp; ``` Defining the annotation alone does not publish an entity set. ### 9.4 `useForValidation: true` ```abap @Consumption.valueHelpDefinition: [ { entity: { name: 'ZI_CustomerValueHelp', element: 'CustomerID' }, useForValidation: true } ] SoldToParty; ``` This marks the value-help definition for validation of user input. Supported consumer/framework processing can check entered values against the provider's allowed result set. It does not replace a RAP behavior validation when: - validity depends on Status, date, Sales Area, role, or other BO state; - the rule must protect direct EML and every service projection; - the provider list is a convenience subset rather than the domain truth; - the rule requires a precise backend error message; - security or transactional consistency is involved; - the referenced object can change between input and save. Use value-help validation for the lookup constraint and backend validation for the durable business invariant. ### 9.5 Additional binding A value help can pass context fields into or out of the provider, for example filtering Product by Sales Organization or returning a related Unit. Model those bindings explicitly and ensure their fields are exposed in the service metadata. Do not hide a missing business determination inside a value-help side effect. Returned values should have a clearly owned source of truth. --- ## 10. Why a Service Definition May Expose Reference Entities Representative Travel service: ```abap define service ZUI_TRAVEL { expose ZC_Travel as Travel; expose ZC_Booking as Booking; expose ZI_AgencyVH as Agency; expose ZI_CustomerVH as Customer; expose ZI_FlightVH as Flight; expose I_Currency as Currency; expose I_Country as Country; } ``` Reference entities can be exposed because the consumer needs them for: - value-help queries; - text retrieval; - direct navigation targets; - filtering or autocomplete; - dependent lookup fields; - service metadata relationships; - an API operation that legitimately reads the reference collection. Do not expose every CDS association automatically. Expose an entity when the service contract requires it and when its authorization/data surface is safe. The correct rule is broader than “expose it only when it appears as a scalar field in the projection.” A provider may need exposure even when used through value help or navigation rather than displayed as a root field. --- ## 11. Service Definition ### 11.1 Responsibility A service definition is a protocol-independent repository object that groups the CDS entities exposed by one business service. ```abap @EndUserText.label: 'Sales Order Request UI Service' @ObjectModel.leadingEntity.name: 'ZC_SalesOrderRequest' define service ZUI_SALESORDERREQUEST { expose ZC_SalesOrderRequest as SalesOrderRequests; expose ZC_SalesOrderItem as SalesOrderItems; expose ZI_CustomerValueHelp as Customers; expose ZI_ProductValueHelp as Products; expose I_Currency as Currencies; } ``` The service definition decides: - which entity models belong to this service; - their service-visible aliases; - the primary/leading entity where declared; - which navigation and lookup targets can become reachable. It does not decide: - whether the service uses OData V2 or V4; - whether it is a UI service or Web API; - the HTTP endpoint URL; - how CRUD is implemented; - whether the current user is authorized; - whether the service is published. ### 11.2 Service aliases ```abap expose ZC_SalesOrderRequest as SalesOrderRequests; ``` The alias decouples the external entity-set name from the CDS technical object name. Choose a stable consumer-oriented name and treat changes as API contract changes. ### 11.3 Complete service graph For a composition-based UI, expose all nodes needed by the business service. The root alone is not always sufficient when child entity sets, navigation, metadata, or value helps must be reachable. At the same time, exposure should be minimal. Every extra entity adds: - metadata and compatibility surface; - possible direct query access; - authorization and performance responsibility; - maintenance and release obligations. --- ## 12. Service Binding ### 12.1 Responsibility A service binding assigns the service definition to a supported protocol and service category. ```text Service Definition protocol-independent model │ ├── OData V4 UI binding ├── OData V4 Web API binding └── another supported binding type ``` One service definition can be used by multiple bindings when the same service contract is appropriate. If UI and integration consumers require materially different fields, operations, versioning, or lifecycle promises, use separate projections and often separate service definitions rather than forcing one oversized contract. ### 12.2 OData V4 UI Designed for metadata-driven user interfaces such as Fiori elements. It consumes UI annotations, draft metadata, actions, value helps, side effects, messages, field control, and navigation. ### 12.3 OData V4 Web API Designed for machine-to-machine consumption. Its contract should emphasize: - stable external names; - explicit operation semantics; - controlled versioning; - predictable messages and HTTP outcomes; - API authorization; - idempotency and concurrency behavior; - minimal UI-specific metadata. A UI projection is not automatically a good public API merely because both use OData V4. ### 12.4 OData V2 and `@OData.publish: true` Older examples often use OData V2 or `@OData.publish: true`. Current RAP design normally favors explicit service definitions and bindings because they provide a clearer service contract, category, protocol choice, versioning, and publication lifecycle. Do not copy an older workshop's V2 binding solely because the sample predates OData V4 support. Confirm the target ABAP release and consumer requirement. --- ## 13. Metadata Request Runtime ```text Fiori client requests $metadata │ ▼ Published Service Binding │ ▼ Service Definition exposed entity aliases and relationships │ ▼ CDS Projection + Behavior Projection fields, navigation, actions, field/ETag/draft contract │ ▼ Metadata Extension + annotations line items, facets, labels, value help, side effects │ ▼ OData metadata document │ ▼ Fiori elements generates list/object-page behavior ``` No behavior-pool method is normally called merely to compile static metadata. Dynamic feature or authorization requests occur when the client asks for the corresponding runtime permissions or data. ### 13.1 Metadata caching After changing CDS, behavior projection, or annotations: - activate all dependent artifacts; - verify the intended service version is published; - inspect live `$metadata` rather than only source code; - refresh or clear relevant client metadata caches; - confirm the browser is calling the expected endpoint. Many apparent annotation defects are stale-metadata defects. --- ## 14. Query and Navigation Runtime ### 14.1 List report read ```text Fiori GET SalesOrderRequests → OData V4 binding → service entity alias → CDS transactional query projection → CDS access control and query runtime → database query → OData response → lineItem rendering ``` The normal CDS-backed query path does not require a behavior-pool read method for a managed query. ### 14.2 Object-page navigation ```text Select one Request → GET by key → object-page identification/facets rendered → expand or navigate `_Items` → projected composition target → child query → child line items rendered ``` ### 14.3 Value-help request ```text User opens SoldToParty value help → metadata identifies provider entity/element → client queries Customers entity set → DCL and service authorization apply → search/filter/order/page options processed → key and text returned → selected CustomerID copied to SoldToParty ``` The provider may return no values because of authorization or filters even when the underlying table contains records. --- ## 15. Side Effects ### 15.1 Purpose Side effects describe which fields, entities, permissions, or messages should be refreshed after a source value or action changes. ```text RequestedQuantity changes → determination recalculates NetAmount → root aggregation recalculates TotalAmount → side-effect metadata tells UI what to reread ``` The determination performs the calculation. The side effect synchronizes the consumer presentation with backend state. ### 15.2 Representative declaration Exact supported syntax depends on the BDEF and target release, but the model is: ```abap side effects { field RequestedQuantity affects field NetAmount; field UnitPrice affects field NetAmount; action Submit affects field Status, permissions ( action Submit ); } ``` Cross-entity dependencies can require association or entity targets supported by the release and service protocol. ### 15.3 Side effects are not determinations ```text Determination changes backend BO state Side effect declares consumer refresh dependency ``` If a side effect exists but no backend logic updates `NetAmount`, the reread returns the same value. If determination exists but side effects are missing, the backend state can be correct while the UI continues showing an old value. --- ## 16. Security Boundaries ### 16.1 UI hiding `@UI.hidden: true` controls presentation. A malicious or custom client can still inspect or request an OData property if the service exposes it and the protocol permits access. ### 16.2 Projection omission Omitting `InternalProcessingCode` from the CDS projection removes it from that service contract. This is stronger than UI hiding but still does not replace authorization for remaining fields and operations. ### 16.3 CDS DCL DCL restricts readable rows for the CDS entity where it is applied. Test the actual consumption entity; do not assume access controls automatically propagate through every view stack. ### 16.4 RAP authorization RAP authorization controls create, update, delete, associations, actions, and other modifying capabilities based on the current user and context. ### 16.5 Value-help security A value-help entity is a query surface. Apply appropriate authorization and expose only the columns needed for selection. Do not treat lookup data as automatically harmless. ```text UI annotation presentation Projection contract surface DCL read-row restriction RAP authorization modify-operation permission Backend validation business invariant ``` All five can be required in one service. --- ## 17. Activate, Publish, Transport, and Deploy ### 17.1 Activate Creates the active repository version after syntax and dependency checks. ```text CDS/MDE/BDEF/service source → Activate in ADT → active ABAP repository object ``` Activation does not make an OData endpoint externally available by itself. ### 17.2 Publish Publishing a service binding enables/registers the service endpoint in the connected ABAP system according to that environment's lifecycle. ```text Active service definition + binding → Publish → callable local system endpoint/version ``` ### 17.3 Transport Transport moves repository and configuration artifacts through the system landscape, for example development to quality to production. Local publication status and environment-specific service setup can still require lifecycle handling in each target system. ### 17.4 Deploy Deployment often refers to delivering a separate frontend application to its runtime or making a complete solution available. It is not a synonym for ABAP artifact activation. ```text Activate repository code becomes active in one ABAP system Publish service endpoint becomes available in that system Transport artifacts move between ABAP systems Deploy separate application/content reaches its target runtime ``` --- ## 18. Fiori Elements Preview The service-binding editor can launch a Fiori elements preview for suitable UI services. Preview is valuable for validating: - entity-set availability; - list report columns; - object-page facets; - composition navigation; - value helps; - draft actions; - action placement; - field control and messages; - side-effect refresh. Preview is not a substitute for a production Fiori application. It does not prove: - launchpad role/catalog configuration; - semantic-object and target-mapping correctness; - production authorization roles; - frontend deployment and routing; - accessibility and UX review; - API compatibility; - performance under real volume. --- ## 19. End-to-End Sales Order Request UI Flow ### 19.1 Open list report ```text 1. Browser loads Fiori elements application. 2. Client requests OData `$metadata`. 3. Service binding resolves ZUI_SALESORDERREQUEST. 4. Metadata describes SalesOrderRequests, Items, actions, value helps, and UI. 5. Client requests SalesOrderRequests with query options. 6. RAP query runtime reads ZC_SalesOrderRequest under DCL. 7. `@UI.lineItem` fields form the table. ``` ### 19.2 Create request draft ```text 1. Create visibility comes from projected behavior. 2. Client creates a draft root. 3. Managed RAP assigns RequestUUID and persists draft state. 4. Object page uses headerInfo and identification annotations. 5. SoldToParty value help queries the exposed Customers provider. 6. Item facet navigates through projected `_Items` composition. ``` ### 19.3 Change quantity ```text 1. UI PATCH changes RequestedQuantity on draft Item. 2. Behavior determination recalculates NetAmount and TotalAmount. 3. Side-effect metadata tells UI to reread affected fields. 4. Refreshed values are formatted with unit/currency semantics. 5. No active business data changes until activation. ``` ### 19.4 Submit ```text 1. Action exists in base BDEF and behavior pool. 2. Behavior projection exposes Submit. 3. UI annotation renders the action button. 4. Instance feature control enables it for eligible Status. 5. RAP authorization checks the user's permission. 6. Handler changes buffered state and returns action result/messages. 7. Draft Prepare/Activate validations protect final persistence. 8. UI refreshes Status and action permissions. ``` --- ## 20. Technical Diagnostics ### 20.1 Entity is absent from the service Check: ```text CDS projection active → service definition `expose` → correct service alias → service binding references intended definition/version → binding published → live `$metadata` → client endpoint and cache ``` ### 20.2 Field is absent Check: 1. base CDS element; 2. CDS projection list; 3. active metadata annotations; 4. service metadata property; 5. UI annotation placement; 6. client personalization and cache. If the property is absent from `$metadata`, the defect is before UI rendering. ### 20.3 Create/Edit/Delete button is missing Check: 1. base BDEF operation; 2. behavior projection `use` declaration; 3. draft actions if draft is enabled; 4. dynamic feature result; 5. RAP authorization result; 6. current service metadata; 7. Fiori page mode and client cache. ### 20.4 Action button is missing Trace: ```text Base action declaration → behavior-pool method → behavior projection `use action` → service-visible action name → `@UI.lineItem` or `@UI.identification` action annotation → feature control → live metadata ``` ### 20.5 Item facet is empty Check: - root facet `targetElement` spelling; - projected composition redirection; - child projection and service exposure; - active/draft navigation context; - parent/child keys and `ON` condition; - DCL on child query; - whether Items exist in the relevant active/draft state. ### 20.6 Value-help icon or values are missing Check: 1. active `@Consumption.valueHelpDefinition`; 2. exact provider entity and element names; 3. provider exposed/reachable in the service; 4. provider appears in `$metadata`; 5. DCL/authorization permits provider rows; 6. additional-binding fields exist and contain values; 7. search/filter metadata and data types are compatible; 8. browser calls the expected endpoint. ### 20.7 Value accepted by UI but save fails This can be correct when value help and business validation enforce different rules. Capture: - selected provider row; - `useForValidation` setting; - current BO Status, Sales Area, date, and other context; - backend validation message; - whether the reference changed between selection and save. The business validation remains authoritative. ### 20.8 Derived value changes in backend but not UI Check: ```text Determination actually updates buffer → nested EML messages/failures → side-effect source field/action → affected target field/entity → target property exposed → UI reread network request → response value and metadata cache ``` ### 20.9 Works in preview but not launchpad Inspect the application-level delivery chain: - deployed frontend application/component; - destination and service URL; - OData service activation/publication in the target system; - launchpad catalog and role; - semantic object and action; - target mapping; - user frontend/backend authorizations; - cache and gateway error logs; - transport completeness. Preview proves the local service/UI metadata path, not the full launchpad setup. --- ## 21. UI and API Contract Design ### 21.1 Separate contracts when promises differ ```text UI service draft editing UI annotations role-specific actions user-facing state messages Web API versioned stable schema machine-oriented operation names explicit concurrency requirements integration authorization minimal navigation and lookup surface ``` Reusing one service definition can be appropriate for closely aligned consumers. Separate projections are appropriate when the contract lifecycle and exposed capabilities differ materially. ### 21.2 Avoid exposing implementation details Do not expose: - internal processing codes without a consumer contract; - raw administrative fields that consumers do not need; - direct write access to derived fields; - unrestricted master-data lookup collections; - legacy persistence names as public API names; - actions whose semantics are not stable. ### 21.3 Versioning Treat service aliases, field types, nullability, actions, navigation paths, and message behavior as compatibility surface. A published Web API requires a stronger compatibility policy than a private preview service. --- ## 22. Exposure Review Checklist ### Projection - CDS projection contains only consumer-relevant fields and navigation. - `transactional_query` provider contract is explicit. - Compositions and parents redirect to projected nodes. - Behavior projection exposes only required operations and actions. - Derived/internal fields have consistent behavior and visibility. - UI and API consumers use separate contracts when their promises differ. ### Metadata - UI annotations are stored in metadata extensions where practical. - Header, line item, identification, filters, and facets reflect the entity grain. - Item facet targets a valid projected composition. - Technical fields are hidden for presentation but retained when runtime needs them. - Action metadata matches the service-visible action name. - Text associations and arrangements do not change stored identity. ### Value help and side effects - Lookup provider exposes only needed, authorized fields. - Provider and key element are reachable in the service. - `useForValidation` is used intentionally and not confused with BO validation. - Additional bindings pass complete context. - Determinations calculate; side effects trigger consumer refresh. - Cross-entity refresh is verified through actual network responses. ### Service - Service definition exposes the complete required graph and no accidental entities. - External aliases are stable and consumer-oriented. - Binding type matches UI or API use. - Intended service version is active and published. - Live `$metadata` is reviewed after changes. - Transport and frontend deployment requirements are documented separately. ### Security - UI hiding is never treated as access control. - Projection omission, DCL, RAP authorization, and validation are all applied at their proper boundaries. - Value-help endpoints are treated as data APIs. - Preview and launchpad authorization are tested independently. --- ## 23. Compact Exposure Map ```text BASE RAP BO ZI_SalesOrderRequest + Base BDEF + Behavior Pool reusable data, operations, invariants, transaction handling │ ▼ SERVICE PROJECTION ZC_SalesOrderRequest CDS fields/navigation Projection BDEF use CRUD/actions/draft Metadata Extension lineItem/facet/value help/action/side effect │ ▼ SERVICE DEFINITION SalesOrderRequests SalesOrderItems Customers value help Products value help Currencies │ ▼ SERVICE BINDING OData V4 UI Fiori elements metadata-driven application OData V4 Web API machine-oriented integration contract │ ▼ RUNTIME $metadata contract and annotations GET CDS query + DCL PATCH/POST/action RAP behavior + authorization + transaction value-help GET lookup provider query side-effect reread synchronize UI with backend derivation ``` The consumer layer should always be read through five separate concerns: ```text Projection narrows the reusable BO. Metadata describes presentation. Service definition selects entity exposure. Service binding selects protocol and service category. Backend behavior and authorization protect correctness. ``` 53:T89e,SAP RAP Service Exposure and Fiori Elements — Technical Reference This document explains how a reusable RAP business object becomes a consumer-facing OData service and a metadata-driven SAP Fiori elements application. It covers service projections, behavior projections, metadata extensions, value helps, side effects, service definitions, service bindings, OData V4 UI and Web API contracts, publication, and runtime diagnosis. The central exposure principle is: A service projection defines the data and behavior contract for one consumption scenario. A service definition groups the entities exposed by that contract. A service binding chooses the protocol and service category. UI annotations describe presentation; they do not implement or secure the underlying business rules. Primary SAP sources: - SAP Help — Business Object Projection - SAP Help — Metadata-Driven UI Annotations - SAP Help — Providing Value Help - SAP Help — Side Effects - SAP Help — Service Definition - SAP Help — Business Service - SAP Help — OData V4 Service Binding Editor --- 1. Consumer-Facing RAP Stack text Reusable RAP BO Base CDS + Base BDEF + Behavior Pool │ ▼ Service Projection CDS Projection + Behavior Projection │ ├──────── Metadata Extension │ UI semantics │ ▼ Service Definition entity exposure and service aliases │ ▼ Service Binding OData V4 UI / OData V4 Web API / other supported type │ ▼ Published endpoint and metadata │ ┌─────────┴─────────┐ ▼ ▼ Fiori elements UI External API consumer Each artifact makes a different decision: | Artifact | Decision | | ------------------- | ----------------------------------------------------------- | | CDS projection | Which fields and relationships this consumer sees | | Behavior projection | Which BO capabilities this consumer may call | | Metadata extension | How a metadata-driven UI presents the model | | Service definition | Which CDS entities belong to the service | | Service binding | Which protocol and service category expose it | | Fiori application | How users navigate and interact with the published contract | The service layer does not replace54:Ta1a,# SAP RAP Service Exposure and Fiori Elements — Technical Reference This document explains how a reusable RAP business object becomes a consumer-facing OData service and a metadata-driven SAP Fiori elements application. It covers service projections, behavior projections, metadata extensions, value helps, side effects, service definitions, service bindings, OData V4 UI and Web API contracts, publication, and runtime diagnosis. The central exposure principle is: > A service projection defines the data and behavior contract for one > consumption scenario. A service definition groups the entities exposed by > that contract. A service binding chooses the protocol and service category. > UI annotations describe presentation; they do not implement or secure the > underlying business rules. Primary SAP sources: - [SAP Help — Business Object Projection](https://help.sap.com/docs/abap-cloud/abap-rap/business-object-projection-6e7a10d30b74412a9482a80b0b88e005-194) - [SAP Help — Metadata-Driven UI Annotations](https://help.sap.com/docs/abap-cloud/abap-rap/defining-cds-annotations-for-metadata-driven-uis) - [SAP Help — Providing Value Help](https://help.sap.com/docs/abap-cloud/abap-rap/providing-value-help-for-selection-fields) - [SAP Help — Side Effects](https://help.sap.com/docs/abap-cloud/abap-rap/side-effects) - [SAP Help — Service Definition](https://help.sap.com/docs/abap-cloud/abap-rap/service-definition) - [SAP Help — Business Service](https://help.sap.com/docs/abap-cloud/abap-rap/business-service) - [SAP Help — OData V4 Service Binding Editor](https://help.sap.com/docs/abap-cloud/abap-development-tools-user-guide/using-service-binding-editor-for-odata-v4-service) --- ## 1. Consumer-Facing RAP Stack ```text Reusable RAP BO Base CDS + Base BDEF + Behavior Pool │ ▼ Service Projection CDS Projection + Behavior Projection │ ├──────── Metadata Extension │ UI semantics │ ▼ Service Definition entity exposure and service aliases │ ▼ Service Binding OData V4 UI / OData V4 Web API / other supported type │ ▼ Published endpoint and metadata │ ┌─────────┴─────────┐ ▼ ▼ Fiori elements UI External API consumer ``` Each artifact makes a different decision:55:T5d84, ### Càng cố gắng, tôi thấy mình càng đứng yên Bản thân tôi không phải người dễ bỏ cuộc, tuy nhiên lần này tôi cảm nhận rõ bản thân đang quá tải. Có lẽ cảm giác burnout không đến từ một khoảnh khắc, mà nó được tích tụ sau một thời gian dài mọi thứ liên tục diễn ra không như mong đợi. Tôi có vài trải nghiệm không được tốt lắm ở công ty gần nhất tôi làm việc, tôi vẫn nhớ như in cái cảm giác vào ngày cuối cùng làm việc ở đó, thay vì lo sợ hành trình sắp tới sẽ ra sao, tôi lại thấy bình yên đến lạ, như trút được gánh nặng vậy. Tôi cũng không vội đi tìm việc mới, thử nghiệm làm vài mô hình “startup 1 người” mà mình đã nghĩ đến trước đó. Tôi cũng nhận triển khai các mô hình AI Automation, n8n trên thị trường freelance và học một ngách mới - SAP. Tôi sẽ kể chi tiết hơn trong một bài viết khác. Nghề nghiệp của tôi thay đổi quá nhanh, tôi cũng cố gắng chạy theo, học liên tục để không bị outdate, nhưng tôi phải thừa nhận, mình không đuổi kịp với tốc độ phát triển của các công cụ AI. Nhu cầu khách hàng cũng giảm mạnh vì giờ đây AI đã đủ thông minh để triển khai được thứ họ muốn chỉ với vài prompt, không cần một người đứng trung gian như mình. Dù đã dành rất nhiều thời gian và công sức, kết quả vẫn không đạt được như kỳ vọng. Dần dần, tôi bắt đầu tự hỏi những gì mình đang làm có thật sự mang lại ý nghĩa gì không. Sau những cú trượt dài của mình, tôi gom phần năng lượng còn lại để lên chiến lược cho các buổi phỏng vấn, quay về môi trường công sở trước đó; khi thị trường có cung lớn hơn cầu thì kế hoạch của tôi là làm sao để mình nổi bật nhất trong đống hồ sơ ứng viên. Thay vì chỉ gửi một chiếc CV nhàm chán thì tôi gửi hẳn một cái web kèm với video giới thiệu trên đó. Và nó thật sự hiệu quả, nó đã giúp tôi bước chân vào được 3 buổi phỏng vấn trong thị trường đang bão hoà này. Tôi nhận được offer. Có lẽ đây là điều duy nhất diễn ra đúng với kỳ vọng của tôi trong khoảng thời gian gần đây. Tôi vui và nhẹ nhõm, nhưng niềm vui ấy không đủ để lập tức lấp đầy sự mệt mỏi đã tích tụ từ trước. Cảm giác mệt mỏi không bùng lên dữ dội mà âm thầm rút cạn năng lượng của tôi. Thêm nữa là thời gian khó khăn này, tôi không cảm nhận được ai xung quanh đồng cảm với tôi cả. Tôi không còn muốn bắt đầu một dự án mới, không muốn tiếp tục cố gắng, thậm chí chẳng còn hứng thú với những điều mình từng rất thích. Tôi vẫn có thể làm việc, vẫn có thể tiếp tục chạy, nhưng bên trong chỉ còn lại sự chán chường và trống rỗng. Có lẽ đó là lúc tôi nhận ra: mình cần dừng lại một chút. ### Không kế hoạch, không kỳ vọng, cứ thế mà đi Tôi bắt đầu nghĩ đến chuyện rời khỏi Sài Gòn một vài ngày. Không phải để tìm kiếm cảm hứng, chữa lành hay trở về với một phiên bản tốt hơn của chính mình. Tôi chỉ muốn đi đâu đó đủ xa khỏi những con đường quen thuộc, tạm rời màn hình, công việc và những suy nghĩ cứ lặp đi lặp lại trong đầu. Nói vui một chút, tôi muốn đi “chạm cỏ”, nhưng lần này phải là cỏ ở một thành phố khác. Trước đây, mỗi khi đi đâu, làm gì, tôi thường lên kế hoạch rất kỹ: sẽ xuất phát lúc nào, ở đâu, ăn gì, ghé những địa điểm nào và phải làm được bao nhiêu thứ trong một ngày. Nhưng phần lớn các chuyến đi lại không diễn ra đúng như những gì tôi hình dung. Lần này tôi quyết định không chuẩn bị một lịch trình cụ thể. Không có danh sách những nơi nhất định phải đến, cũng không suy nghĩ mục tiêu gì nhiều. Tôi chỉ mang theo những thứ cần thiết, chọn một điểm đến rồi lên đường. Mệt thì dừng, thích nơi nào thì ở lại lâu hơn, thấy một con đường thú vị thì rẽ vào. Thậm chí tôi còn không biết trưa hôm đó ăn gì hay tối ngủ ở đâu nữa. Tôi vốn là một người không giỏi ứng biến, có lẽ vì thế trước đây tôi luôn muốn lên kế hoạch để cố gắng kiểm soát mọi thứ. Nhưng tôi nhận ra một điều, càng lên kế hoạch kỹ thì mình sẽ mang một sự kỳ vọng rất lớn. Chính vì lẽ đó, tôi thường cảm thấy hụt hẫng, thất vọng khá nhiều khi mọi thứ bị chệch khỏi đường ray. Và lần này, khi để mọi thứ tự nhiên xảy ra, tôi lại có ấn tượng tốt hơn về những nơi mà tôi không kỳ vọng nhiều ban đầu. Tuy nhiên, tôi cũng đặt ra vài luật cho mình: không được ngủ thiếu giấc vì đi dài ngày, không chạy khuya, mệt thì nghỉ, không ráng, tuân thủ tốc độ trong mức kiểm soát, thậm chí nơi nào đẹp thì dừng lại ngắm cảnh một tí, đến nơi trễ một tí cũng được, chả ảnh hưởng đến ai. Và đây cũng là lý do tôi thích đi một mình. ### Rời thành phố, bắt đầu hành trình Tôi bắt đầu hành trình từ Sài Gòn và lựa chọn sẽ đi theo cung đường biển. Dù sao đây cũng là một chuyến đi để giải toả, chạy mãi trên quốc lộ cùng với xe tải và lượng lớn xe khác, có lẽ chỉ khiến tôi mệt thêm. Tôi muốn nhìn thấy biển, muốn cảm nhận không khí trong lành thêm một tí gió trên đường; không biết sao nhưng mỗi lần đứng trước sự to lớn của thiên nhiên, tôi đều cảm thấy mình nhỏ bé và mọi lo âu của mình cũng được thu hẹp lại. Điểm đến đầu tiên tôi chọn là Bàu Trắng. Đây không phải lần đầu tôi đến nơi này. Trong chuyến đi trước, tôi đã bị hút hồn bởi khung cảnh nơi đây, lúc mà bãi biển đột nhiên xuất hiện trước mắt, cảnh vật như thay đổi ngay tức khắc, tiếp đến là con đường thẳng tắp với một bên là đồi cát trải dài và một bên là biển xanh, cảnh tượng nếu tôi ngồi trên xe khách, chắc khó mà cảm nhận được. ![[../images/healing-bau-trang.jpeg]] Tôi nghỉ chân một lát, ăn quán ăn địa phương, ghé vào ngẫu nhiên, chọn một món ăn đơn giản, nhưng bất ngờ là rất hợp khẩu vị. Nghỉ chân xong, tôi tiếp tục tiến thẳng. Rời Bàu Trắng, tôi tiếp tục hướng về Ninh Thuận. Dù đây là một chuyến đi không được lên kế hoạch, nhưng tôi cũng có một danh sách các nơi mà mình đã muốn đến từ lâu. Qua những hình ảnh trên mạng, con đường hiện ra một vùng biển xanh, tiếp đến là dãy núi khô cằn, sỏi đá, mang một vẻ đẹp hoang sơ rất riêng. Tôi đã biết đến cung đường này từ khá lâu nhưng chưa từng có dịp tự mình chạy qua. Vì thế, Ninh Thuận trở thành điểm tiếp theo của hành trình. ### 13 km dài nhất trong chuyến đi Nhưng chuyến đi không kế hoạch cũng đồng nghĩa với việc tôi phải sẵn sàng cho những chuyện ngoài dự tính. Trên đường đi, chiếc xe bắt đầu gặp vấn đề: hụp ga, máy yếu và cứ chạy được một lúc lại tắt. Cảm giác lúc ấy giống như xe sắp hết xăng, dù trong bình vẫn còn. Ban đầu, tôi nghĩ có thể do chạy đường dài khiến máy quá nóng nên tìm một tiệm sửa xe gần đó để kiểm tra và thay nhớt. Đây là lần đầu tôi gặp sự cố lớn vậy, khá bế tắc cho một chuyến solo trip. Nhưng thay nhớt xong, tình hình vẫn không khá hơn. Chiếc xe tiếp tục hụp ga, còn tiệm sửa cũng không có đủ dụng cụ để kiểm tra kỹ. Tôi nghĩ mình xong rồi. Tôi định tìm một nhà nghỉ gần đó và ở lại qua đêm. Nhưng rồi lại nghĩ, nếu ở đây thì sáng hôm sau tôi vẫn không biết phải xử lý chiếc xe thế nào. Anh chủ tiệm khuyên tôi nên cố chạy thêm khoảng 12 km vào trung tâm Phan Rí để nghỉ ngơi và cũng dễ sửa loại xe của tôi hơn. Tôi cố đèo người bạn đồng hành của mình đi tiếp, tốc độ có lúc lên được 40km/h xong hụp xuống 10 km/h, cảm giác như xe không có xăng vậy, có thể tắt máy bất cứ lúc nào. Tôi cố được 3km thì bỏ cuộc và quyết định nhờ sự trợ giúp. May mắn là tôi đã gặp anh Thiện. Anh dùng chiếc Wave của mình đẩy chiếc xe của tôi suốt gần 10 km còn lại vào trung tâm Phan Rí. Khung cảnh một chiếc Wave nhỏ đẩy một chiếc xe to hơn chạy dọc đường chắc nhìn từ bên ngoài cũng khá vui. Chiếc xe đầu tiên của tôi cũng là Wave, nó gợi nhớ cho tôi phết. Tôi ngủ lại ở một nhà nghỉ ngẫu nhiên tại Phan Rí, và vì tôi cũng không áp lực thời gian trong chuyến đi nên sự cố này cũng không quá làm ảnh hưởng tinh thần của mình, chỉ là không biết xe mình đang bị gì thôi. Sáng hôm sau tôi mang xe mình đến HEAD Hưng Thịnh, tôi là khách hàng đầu tiên, vừa mở cửa là tôi đã đẩy xe vào rồi. | | | | ------------------------------------ | ------------------------------------ | | ![[../images/healing-sua-xe-1.jpeg]] | ![[../images/healing-sua-xe-2.jpeg]] | Tôi miêu tả vấn đề, các anh kỹ thuật bắt đầu khám. Mở tung bugi đến bơm xăng rồi hỏi tôi có bơm xăng đểu không nữa (từ lúc có xăng e10 thì vấn đề này tôi không chắc), rút xăng ra, đổ xăng mới vào, và tình trạng vẫn thế. Không lẽ phải kết thúc hành trình và đưa xe về Sài Gòn sao ta. Sau khoảng 1h30p khám thì các anh mở kim phun xăng ra và phát hiện nó đã bị cháy. Cuối cùng đã tìm ra vấn đề. Nhưng vấn đề mới là tại HEAD không có linh kiện để thay, tôi lại tiếp tục ngồi chờ linh kiện được mang đến. Tôi mất tổng cộng 3h30p để ra khỏi tiệm sửa xe, các anh bảo đây là cái kim phun cuối cùng trong các chi nhánh ở đây. May mắn là xe tôi đã tiếp tục chạy được rồi. Tiếp tục hành trình thôi. Trên đường đi thì tôi suy nghĩ khá nhiều, là việc mình gặp sự cố ở đây cũng không hẳn là xui xẻo, vì nó chưa dẫn đến một hậu quả gì quá nghiêm trọng cả, tưởng tượng nếu xe tôi gặp sự cố trên Đèo Bảo Lộc thì…. đó thật sự là thảm hoạ. Đây cũng là bài học kinh nghiệm cho tôi trong những lần đi sau. ### Phía cuối đường mòn là biển Tôi tiếp tục lên đường khám phá Ninh Thuận. Ban đầu là dọc con đường biển, tiến thẳng đến Vĩnh Hy, nhưng đột nhiên tôi nhớ đến Công viên đá, vẫn còn sớm nên tôi đổi lịch trình khám phá nơi này. Đường vào không hề dễ đi, phần lớn là đường mòn với nhiều đất và sỏi đá, tôi phải chạy thật chậm và tập trung quan sát, xung quanh cũng không có người, nói thật là tôi cũng hơi sợ, nhất là lại vừa gặp sự cố với xe. Nhưng khi đến nơi, tôi biết quãng đường khó khăn ấy hoàn toàn xứng đáng. Trước mắt tôi là một không gian rộng lớn và gần như nguyên sơ: những khối đá với đủ hình dáng nằm rải rác bên bờ biển, phía trước là mặt nước kéo dài đến tận chân trời. Không hàng quán, không những công trình đông đúc, chỉ có đá, biển, gió và âm thanh của sóng. Đứng trên những vách đá nhìn ra biển, một lần nữa tôi cảm thấy mình thật nhỏ bé trước thiên nhiên. Nhưng sự nhỏ bé ấy không khiến tôi thấy lạc lõng. Ngược lại, nó làm những suy nghĩ vốn rất nặng nề trong đầu bỗng trở nên nhẹ hơn. Khá bất ngờ vì rất ít người ở đó, có lẽ là đi trong tuần, tôi thoải mái quay video rồi, làm đủ trò ở đấy. ![[../images/healing-cong-vien-da.jpg]] Sau khoảng 2 tiếng ở đây thì tôi chạy đến làng chài Vĩnh Hy, với mong muốn được thả lỏng nhìn cuộc sống thường ngày của một làng chài và dự định tối sẽ tá túc ở đây. Vịnh Vĩnh Hy trong suy nghĩ của tôi là một nơi cực kỳ thanh bình, là nơi mưu sinh của các cô chú làng chài, là hình ảnh mà tôi thường thấy trong những quyển sách giáo khoa. Khi đến nơi, tôi có hơi hụt hẫng, làng chài không to như tôi nghĩ, chỉ nằm gọn trên một con đường, khung cảnh nhìn ra thì rất thơ mộng, tôi bị hút hồn bởi những hình ảnh này trên truyền thông. Tuy nhiên, để bảo là khám phá thì, không có gì mấy. Cảm giác hụt hẫng có lẽ đến từ việc tôi đã kỳ vọng nhiều quá. Hoặc tôi đã tiếp cận Vĩnh Hy sai cách, hẹn Vĩnh Hy lần sau, chắc có lẽ ra khơi cùng dân địa phương sẽ mang lại trải nghiệm tốt hơn. ![[../images/healing-vinh-hy.jpg]] Tôi thay đổi ý định, đi tiếp, tôi tìm ngẫu nhiên trên Map và thấy Bãi Thùng cách tôi 20p đi xe, không suy nghĩ nhiều, tôi lên đường. Lại lần nữa, tôi lại rẽ vào một con đường gồ gề sỏi đá, cấp độ còn khó hơn trước. Độ dốc cao hơn, dễ ngã hơn, tôi cũng không biết phía trước là gì, thôi kệ đi tiếp. Băng qua chông gai ấy thì tôi đang đứng sát vách của biển. À ra đây là bãi tắm, biển trong vắt, tôi đi 1 mình nên không dám xuống tắm, xung quanh tôi cũng có 2-3 gia đình đi nghỉ mát ở đây. Tôi ngồi ở đó, không làm gì, chỉ hít thở, mặc kệ xung quanh luôn. Lúc đó đã khoảng gần 5 giờ chiều rồi, ngồi một lúc thì phải đứng dậy đi tiếp để tìm chỗ ngủ tối nay. Đi ra con đường sỏi đá lúc nãy, bây giờ là game khó hơn, chạy lên dốc nhưng đường là sỏi, không có độ bám. Sợ té nên tôi đi từ từ, nhưng xui sao chệch bánh phát, tôi xoè ngay đó. Hahah, biết ngay mà, xe tôi bị gãy gác chân trước và may mắn là tôi không sao, tinh thần cũng còn vững lắm, vẫn muốn đi tiếp. Tôi vẫn chưa quyết được là nên ở đâu tối nay. Quay lại Vịnh Vĩnh Hy thì cũng được nhưng tôi không có ấn tượng tốt. Tôi search map và thấy mình cách Nha Trang 2 tiếng chạy xe nữa. Đi luôn, tôi quyết định sẽ ngủ lại tại thành phố biển Nha Trang. ### Hóa ra đi du lịch không phức tạp đến thế Điểm dừng chân tiếp theo của tôi là thành phố Nha Trang. Trước chuyến đi này, tôi chỉ biết về nơi đây qua báo đài và lời kể của những người xung quanh. Vì là một thành phố du lịch nổi tiếng, tôi luôn mặc định rằng chi phí ăn ở tại Nha Trang chắc hẳn sẽ khá đắt đỏ. Nhưng khi thực sự đến đây, mọi thứ lại trái ngược với những gì tôi từng nghĩ. Ngay trong đêm, tôi mở Agoda và tìm một chỗ nghỉ gần biển. Không mất quá nhiều thời gian, tôi đặt được một căn phòng ngay trên đường Trần Phú, chỉ cách biển vài trăm mét đi bộ, với mức giá chưa đến 300.000 đồng. Phòng ốc cực kỳ sạch sẽ và không thiếu bất kỳ một tiện nghi nào, đầy đủ máy lạnh, máy sấy tóc, TV. Khoảnh khắc ấy khiến tôi nhận ra đôi khi chính những suy nghĩ và giả định của mình đã khiến việc đi du lịch trở nên khó khăn hơn thực tế. Tôi từng nghĩ một chuyến đi cần được chuẩn bị thật kỹ, phải đặt phòng từ sớm và dự trù rất nhiều chi phí. Nhưng lần này, ngay cả khi quyết định mọi thứ vào phút cuối, tôi vẫn tìm được một nơi ở sạch sẽ, gần biển và có mức giá hợp lý. Có lẽ sau chuyến đi này, tôi sẽ cho phép mình đi nhiều hơn. Không nhất thiết phải đợi đến khi có một kế hoạch hoàn hảo, một lịch trình chi tiết hay một khoản ngân sách thật lớn. Đôi khi, chỉ cần lên đường trước, những điều còn lại có thể đơn giản hơn mình tưởng rất nhiều. Nhận phòng xong, cả đêm tôi đi bộ quanh khu vực bãi biển Trần Phú. Nơi đây hiện đại hơn tôi nghĩ, có một nét đẹp rất có gu, cả con đường thẳng tấp mọc lên rất nhiều khách sạn, toà nhà trọc trời với nhiều màu sắc, cũng là trung tâm thành phố nhưng có lẽ tôi thích không khí ở đây hơn quận 1, Sài Gòn. Một điều bị sốc văn hoá ở Nha Trang là khắp nơi đều là chữ Nga và người Nga ở khắp nơi, tôi cứ tưởng người Trung Quốc nhiều hơn. Một tí hơi sốc cũng như hơi buồn, là người Việt mình cạnh tranh không bằng người nước ngoài ngay chính mảnh đất của mình. Có một thứ tôi rất thích ở người nước ngoài ở các địa điểm du lịch, là trông họ rất tận hưởng hành trình, chứ không phải chạy KPI check in nơi này nơi kia, nhìn thấy các anh chơi bóng chuyền ở bãi biển, thật sự mang lại một cảm giác rất tận hưởng. Sáng hôm sau, ngủ dậy, người tôi ê ẩm, tính sẽ xách xe chạy thêm nơi này nơi kia, nhưng không hiểu sao bị lười ghê luôn. Tôi đi bộ quanh khu vực tôi tá túc, đi tìm một quán ăn địa phương, một dĩa bánh căn đầy với giá 25k. Trời ơi, ở SG là dĩa này có giá 40k rồi, có ai đi du lịch mà tốn ít tiền hơn bình thường như tôi không. Tôi nhìn thấy một quán cà phê trông rất chill, tôi bước vào và gọi một ly cà phê đen, ngồi nhâm nhi như một người trưởng thành, hahah… Và tôi nghĩ cũng đã đến lúc đi tiếp rồi. Tạm biệt Nha Trang. ### Từ biển xanh đến thành phố trên cao Sau nhiều ngày men theo những cung đường biển, tôi bắt đầu muốn tìm đến một khung cảnh khác. Từ Nha Trang, tôi rời biển và bắt đầu đi về phía núi. Cảnh vật dọc đường cũng từ từ thay đổi. Những đoạn đường bằng phẳng nhường chỗ cho các con dốc và khúc cua nối tiếp nhau. Không khí dần mát hơn, cây cối xanh hơn, còn biển thì lùi lại phía sau. Càng lên cao, tôi càng cảm nhận rõ mình đang bước vào một chặng hoàn toàn khác của chuyến đi và Đà Lạt là điểm đến tiếp theo, cũng là điểm kết thúc hành trình trước khi về lại Sài Gòn. Nếu những ngày ở biển mang lại cảm giác tự do và rộng mở, Đà Lạt lại khiến mọi thứ chậm xuống. Đây không phải lần đầu tôi đến thành phố này, nhưng trong một hành trình không kế hoạch, Đà Lạt dường như mang một ý nghĩa khác. Tôi không còn muốn chạy đi thật nhiều nơi hay cố gắng hoàn thành một danh sách các điểm phải đến. Tôi chỉ muốn đi chậm giữa những con dốc, cảm nhận không khí se lạnh và nhịp sống thong thả nơi đây. Tôi chạy đến Thung Lũng Vàng, nơi có nhiều cây thông mang nét đẹp đậm chất Đà Lạt, cũng chụp được nhiều ảnh ở đây và quay được những đoạn rất cinematic. Xong, tôi đặt phòng cho nghỉ ngơi buổi chiều và sáng hôm sau. Tôi tiếp tục chọn phòng trên Agoda, và bất ngờ 1 lần nữa, phòng cách Hồ Xuân Hương 3p đi xe nhưng chỉ có giá 250k, tôi không mong đợi gì nhiều, nghĩ chắc phòng cũng bình thường, nhưng phòng rất xinh xắn, đáp ứng đầy đủ nhu cầu cơ bản của tôi. Tôi cho phép mình nghỉ ngơi cả buổi chiều không làm gì cả, ngủ 1 giấc trưa thật ngon rồi tính tiếp. Tôi cũng có vài địa điểm muốn đến nhưng chiều hôm đó tôi chỉ muốn đi dạo thôi, thế là tôi loanh quanh Hồ Xuân Hương và cũng quay được vài video deep deep ở đó. Buổi tối tôi có ghé Quảng trường Lâm Viên, ngồi uống 1 ly đậu nành nóng nghe saxophone, cũng sanh chảnh phết, haha. Tôi cũng hoà mình vào đám đông tại chợ để cảm nhận lại không khí của đám đông, tôi cô lập bản thân mình quá lâu rồi. Trút hết ưu phiền rồi quay lại homestay thôi. Tối đó tôi lên kế hoạch 4h30 sáng hôm sau đi săn mây, mà nửa muốn đi nửa không, vì trời vừa mưa, tôi không chắc đường lên có an toàn không nữa. Ngủ đến sáng, 4h tôi bật dậy, không hiểu sao lúc này tôi lười biếng ghê luôn, chả muốn đi đâu nữa, với lâu rồi tôi mới có cảm giác ngủ ngon như vậy, cuối cùng, tôi không nghĩ gì đến chuyện săn mây nữa, ngủ tiếp, giờ không ai cản được tôi đâu. Haha. Tầm 7h thì tôi dậy, lúc này là gần như tôi đã rất hài lòng về chuyến đi của mình rồi, tôi đi tìm đến một quán ăn bán bánh ướt lòng gà đặc trưng của Đà Lạt, xong mua 1 ly cà phê đen ra Hồ Xuân Hương ngồi nhâm nhi một lát rồi chào tạm biệt nơi này. ### Có những chuyến đi chỉ để được nghỉ Những tâm lý bất ổn của tôi, phần lớn đến từ việc nó không đạt được như kỳ vọng, hoặc là do sự thay đổi quá nhanh của thị trường làm tôi không thích ứng kịp, bị chơ vơ. Và tôi cũng nhận ra, khi đặt kỳ vọng quá nhiều thì tỷ lệ tôi bị hụt hẫng cũng nhiều hơn. Tôi học được cách chỉ nên kiểm soát những thứ mình có thể kiểm soát, chuyện gì tới nó sẽ tới, không cần nghiêm trọng hoá vấn đề. Chuyến đi này có những trục trặc ngoài ý muốn, may là vẫn chưa xảy ra vấn đề gì quá nghiêm trọng. Tuy nhiên, chính những điều đó làm chuyến đi này đáng nhớ hơn nhiều. Tôi liên tưởng chuyến đi này đến những việc xảy ra gần đây trong cuộc đời mình, rõ ràng phải có những chông gai, khó khăn thì mới tạo nên sự cứng rắn hiện tại. Một chuyến đi đáng nhớ. 56:T7c3,Càng cố gắng, tôi thấy mình càng đứng yên Bản thân tôi không phải người dễ bỏ cuộc, tuy nhiên lần này tôi cảm nhận rõ bản thân đang quá tải. Có lẽ cảm giác burnout không đến từ một khoảnh khắc, mà nó được tích tụ sau một thời gian dài mọi thứ liên tục diễn ra không như mong đợi. Tôi có vài trải nghiệm không được tốt lắm ở công ty gần nhất tôi làm việc, tôi vẫn nhớ như in cái cảm giác vào ngày cuối cùng làm việc ở đó, thay vì lo sợ hành trình sắp tới sẽ ra sao, tôi lại thấy bình yên đến lạ, như trút được gánh nặng vậy. Tôi cũng không vội đi tìm việc mới, thử nghiệm làm vài mô hình “startup 1 người” mà mình đã nghĩ đến trước đó. Tôi cũng nhận triển khai các mô hình AI Automation, n8n trên thị trường freelance và học một ngách mới - SAP. Tôi sẽ kể chi tiết hơn trong một bài viết khác. Nghề nghiệp của tôi thay đổi quá nhanh, tôi cũng cố gắng chạy theo, học liên tục để không bị outdate, nhưng tôi phải thừa nhận, mình không đuổi kịp với tốc độ phát triển của các công cụ AI. Nhu cầu khách hàng cũng giảm mạnh vì giờ đây AI đã đủ thông minh để triển khai được thứ họ muốn chỉ với vài prompt, không cần một người đứng trung gian như mình. Dù đã dành rất nhiều thời gian và công sức, kết quả vẫn không đạt được như kỳ vọng. Dần dần, tôi bắt đầu tự hỏi những gì mình đang làm có thật sự mang lại ý nghĩa gì không. Sau những cú trượt dài của mình, tôi gom phần năng lượng còn lại để lên chiến lược cho các buổi phỏng vấn, quay về môi trường công sở trước đó; khi thị trường có cung lớn hơn cầu57:T6d8,### Càng cố gắng, tôi thấy mình càng đứng yên Bản thân tôi không phải người dễ bỏ cuộc, tuy nhiên lần này tôi cảm nhận rõ bản thân đang quá tải. Có lẽ cảm giác burnout không đến từ một khoảnh khắc, mà nó được tích tụ sau một thời gian dài mọi thứ liên tục diễn ra không như mong đợi. Tôi có vài trải nghiệm không được tốt lắm ở công ty gần nhất tôi làm việc, tôi vẫn nhớ như in cái cảm giác vào ngày cuối cùng làm việc ở đó, thay vì lo sợ hành trình sắp tới sẽ ra sao, tôi lại thấy bình yên đến lạ, như trút được gánh nặng vậy. Tôi cũng không vội đi tìm việc mới, thử nghiệm làm vài mô hình “startup 1 người” mà mình đã nghĩ đến trước đó. Tôi cũng nhận triển khai các mô hình AI Automation, n8n trên thị trường freelance và học một ngách mới - SAP. Tôi sẽ kể chi tiết hơn trong một bài viết khác. Nghề nghiệp của tôi thay đổi quá nhanh, tôi cũng cố gắng chạy theo, học liên tục để không bị outdate, nhưng tôi phải thừa nhận, mình không đuổi kịp với tốc độ phát triển của các công cụ AI. Nhu cầu khách hàng cũng giảm mạnh vì giờ đây AI đã đủ thông minh để triển khai được thứ họ muốn chỉ với vài prompt, không cần một người đứng trung gian như mình. Dù đã dành rất nhiều thời gian và công sức, kết quả vẫn không đạt được như kỳ vọng. Dần dần, tôi bắt đầu tự hỏi những gì mình đang làm có thật sự mang lại ý nghĩa gì không.5:["$","main",null,{"className":"blog-module__JsT-Oq__blogRoot","children":[["$","$Lf",null,{}],["$","$L10",null,{"documents":[{"slug":"hello-world","language":"vi","title":"Chương 1. Hello World! Tôi đang học cách cảm nhận lại thế giới","part":"Part 1. Hello World","summary":"Tôi đã mất cả tỷ lần trì hoãn chỉ để đắn đo về việc xây dựng một khoảng lặng cho riêng mình. Thì bây giờ đây, chính là nó, JusteeSpace - một không gian, nơi tôi thoải mái ghi lại những câu chuyện, những trải nghiệm sống, là nơi lưu trữ, vừa mang tính cá nhân, vừa mang tính hệ thống. Một quyển nhật ký dành cho tôi ở phiên bản tương lai có thể xem lại những suy nghĩ, bài học mà tôi học được ở hiện tại.","category":"Personal","tags":["introduction"],"publishedAt":"2026-05-09","updatedAt":"$undefined","draft":false,"content":"$11","excerpt":"$12","previewContent":"## Điều gì đã thôi thúc tôi bắt đầu viết blog này?\n\nTôi vốn là một người không giỏi trong việc thể hiện cảm xúc, không giỏi trong việc diễn đạt và trình bày ý tưởng. Và nhìn lại quá khứ, điều đó đã cản trở tôi có thể dấn thân vào làm một việc gì đó hết mình. Những ngày tháng ngồi ở giảng đường Đại học, nếu như Giảng viên không trực tiếp gọi tôi thì có lẽ tôi cũng chả bao giờ phát biểu ý kiến, có lẽ là do sợ sai hay bị chê cười… haha… đúng là đần, mình là người trả tiền sử dụng dịch vụ mà, sợ cái đ’ gì chứ.\n\nCuộc sống của tôi cứ trôi qua êm đềm như vậy. Đến ngày tốt nghiệp, rồi cũng đi thực tập và may mắn có được công việc mà ở đó đã xây dựng lên nền tảng khá vững cho tôi. Bạn đã nghĩ cuộc sống của tôi như vậy là ổn, không có gì để chê đúng không, tốt nghiệp trường top (Bách Khoa), lại công việc ổn định. Cứ thế mà an nhàn đi, suy nghĩ làm gì.","connections":["who-am-i"],"readingMinutes":7,"languages":["vi"],"backlinks":[],"unresolvedReferences":[]},{"slug":"who-am-i","language":"vi","title":"Chương 2. Tôi là ai giữa thế giới này","part":"Part 1. Hello World","summary":"Tôi không định nghĩa bản thân bằng chức danh công việc, bằng những công nghệ mình thành thạo, hay bằng những con số vô hình trên màn hình máy tính. Bản thể của tôi là con người đã được hình thành dựa trên trải nghiệm sống, cách tôi phản ứng với những rào cản, hoài nghi của chính mình.","category":"Personal","tags":["introduction"],"publishedAt":"2026-05-12","updatedAt":"$undefined","draft":false,"content":"$13","excerpt":"$14","previewContent":"## Những thứ định nghĩa sự tồn tại của tôi\n\nMọi người thường nghĩ Dev bọn tôi chỉ biết có màn hình đen và những dòng code khô khan đúng không. Nhưng sau giờ làm, tôi lại ôm đàn, cầm máy ảnh đi lang thang, hoặc ngồi dựng một thước phim ngắn. Tôi còn chả biết có ai giống mình như vậy không. Blog này sinh ra vì tôi không muốn những mảnh ghép đó bị tách rời.\n\nTôi là một cựu sinh viên Bách Khoa K18, chuyên ngành Khoa học máy tính. Vâng, sau 5 năm trầy trật trên giảng đường, cuối cùng tôi cũng có thể tự tin giới thiệu mình là một Kỹ sư máy tính. Nhưng quay ngược thời gian vào thời điểm chọn ngành, bản thân tôi còn chả định nghĩa được 'kỹ sư' là gì. Tôi chỉ biết là xung quanh mọi người ca ngợi nó lắm, nào là ra trường lương nghìn đô, nào là tạo ra nhiều đột phá công nghệ. Năm đó, tôi cũng là một trong số ít học sinh của trường đỗ vào Bách Khoa, cảm giác bước đi mặt vênh lên trời, 'oách xà lách' vô cùng, và cái niềm tự hào âm ỉ ấy tôi vẫn giữ mãi cho đến tận bây giờ.","connections":["nothing-change-if-nothing-change"],"readingMinutes":6,"languages":["vi"],"backlinks":["hello-world"],"unresolvedReferences":[]},{"slug":"nothing-change-if-nothing-change","language":"vi","title":"Chương 3. Không có gì thay đổi nếu không có gì thay đổi","part":"Part 1. Hello World","summary":"Ai trong chúng ta cũng mong muốn trở thành phiên bản tốt hơn của chính mình, nhưng ít ai sẵn sàng thay đổi","category":"Personal","tags":["motivation"],"publishedAt":"2026-05-15","updatedAt":"$undefined","draft":false,"content":"$15","excerpt":"$16","previewContent":"## Chúng ta đang quá tham lam\n\nMạng xã hội ngày nay dựng lên những khung cảnh quá hoàn hảo: một đứa trẻ phát âm tiếng Anh chuẩn bản xứ, những người trẻ chưa đầy ba mươi đã sở hữu nhà riêng, xe sang hay tự do tài chính. Chúng ta lướt qua những lát cắt ấy mỗi ngày và vô tình rơi vào một cái bẫy tâm lý nguy hiểm: nhìn vào kết quả của người khác và gán nó làm tiêu chuẩn cho bản thân.\n\nNhưng sự thật là, những gì bạn thấy chưa chắc đã là 100% sự thật, có những bí mật đằng sau mà bạn chưa nhìn rõ, mọi trạng thái ở hiện tại đều có nguyên do của nó.\nĐằng sau một đứa trẻ nói tiếng Anh lưu khoát có thể là một gia đình có điều kiện, được đầu tư học trường quốc tế và tiếp xúc với ngoại ngữ từ lúc còn chưa sõi tiếng mẹ đẻ. Đằng sau một sự thành công sớm là những nguồn lực ngầm về tài chính, mối quan hệ hoặc xuất phát điểm vượt trội. Tất nhiên vẫn sẽ tồn tại vài trường hợp xuất chúng, nhưng tỷ lệ là dưới 1%.","connections":[],"readingMinutes":6,"languages":["vi"],"backlinks":["who-am-i"],"unresolvedReferences":[]},{"slug":"sap-switching","language":"vi","title":"Chương 1. Từ Kỹ Sư Phần Mềm Đến Hành Trình Mới Với SAP","part":"Part 2. Cú chuyển mình trong sự nghiệp","summary":"Từ 1 software engineer với kỹ năng Database Optimizing và Blockchain, vì sao tôi lại muốn bắt đầu hành trình mới với SAP","category":"Personal","tags":["sap"],"publishedAt":"2026-05-20","updatedAt":"$undefined","draft":false,"content":"$17","excerpt":"$18","previewContent":"## Bước đi chập chững từ các công ty khởi nghiệp\n\nTôi có nhiều năm làm việc với các công ty start up và may mắn được cọ xát với nhiều công nghệ mới, được nhúng tay khá sâu vào các dự án, như là trực tiếp sửa đổi / thiết kế lại hệ thống database của một ứng dụng đang chạy production và kết quả được cải thiện tương đối chỉ với vài kỹ năng cơ bản về Index và partitioning.","connections":["sap-foundation"],"readingMinutes":5,"languages":["vi"],"backlinks":[],"unresolvedReferences":[]},{"slug":"sap-foundation","language":"vi","title":"Chương 2. Đặt nền móng","part":"Part 2. Cú chuyển mình trong sự nghiệp","summary":"Định nghĩa tư duy, lên kế hoạch học tập để xây dựng nền móng vững chắc","category":"Personal","tags":["sap","foundation"],"publishedAt":"2026-05-27","updatedAt":"$undefined","draft":false,"content":"$19","excerpt":"$1a","previewContent":"$1b","connections":["sap-concepts"],"readingMinutes":7,"languages":["vi"],"backlinks":["sap-switching"],"unresolvedReferences":[]},{"slug":"sap-concepts","language":"vi","title":"Chương 3. Hiểu rõ hơn về các khái niệm trong SAP","part":"Part 2. Cú chuyển mình trong sự nghiệp","summary":"Cái nhìn toàn diện về hệ sinh thái SAP, từ tính năng cốt lõi, ngôn ngữ lập trình, hệ thống phân hệ đến cơ chế vận hành chi tiết của kiến trúc 3 lớp R/3 và Application Server.","category":"Personal","tags":["sap","foundation"],"publishedAt":"2026-06-01","updatedAt":"$undefined","draft":false,"content":"$1c","excerpt":"$1d","previewContent":"$1e","connections":["sap-abap"],"readingMinutes":3,"languages":["vi"],"backlinks":["sap-foundation"],"unresolvedReferences":[]},{"slug":"sap-abap","language":"vi","title":"Chương 4. ABAP Fundamentals: Bước Chân Vào Tầng Xử Lý Logic","part":"Part 2. Cú chuyển mình trong sự nghiệp","summary":"Những bài học đầu tiên về Technical trong SAP","category":"Personal","tags":["sap","foundation","abap"],"publishedAt":"2026-06-07","updatedAt":"$undefined","draft":false,"content":"$1f","excerpt":"$20","previewContent":"$21","connections":["sap-abap-1","sap-abap-2","sap-abap-3","sap-abap-4","sap-abap-5","sap-abap-6","sap-abap-7","sap-sd"],"readingMinutes":2,"languages":["vi"],"backlinks":["sap-concepts"],"unresolvedReferences":[]},{"slug":"sap-abap-1","language":"en","title":"ABAP BASIC Statements","part":"ABAP","summary":"ABAP Basic Statements","category":"Technical","tags":["sap","abap"],"publishedAt":"2026-06-10","updatedAt":"$undefined","draft":false,"content":"$22","excerpt":"$23","previewContent":"$24","connections":[],"readingMinutes":5,"languages":["en"],"backlinks":["sap-abap"],"unresolvedReferences":[]},{"slug":"sap-abap-2","language":"en","title":"ABAP Data Dictionary","part":"ABAP","summary":"ABAP Data Dictionary","category":"Technical","tags":["sap","abap"],"publishedAt":"2026-06-17","updatedAt":"$undefined","draft":false,"content":"$25","excerpt":"$26","previewContent":"$27","connections":[],"readingMinutes":5,"languages":["en"],"backlinks":["sap-abap"],"unresolvedReferences":[]},{"slug":"sap-abap-3","language":"en","title":"ABAP Open SQL","part":"ABAP","summary":"ABAP Open SQL","category":"Technical","tags":["sap","abap"],"publishedAt":"2026-06-24","updatedAt":"$undefined","draft":false,"content":"$28","excerpt":"$29","previewContent":"$2a","connections":[],"readingMinutes":5,"languages":["en"],"backlinks":["sap-abap"],"unresolvedReferences":[]},{"slug":"sap-abap-4","language":"en","title":"ABAP Internal Table","part":"ABAP","summary":"ABAP Internal Table","category":"Technical","tags":["sap","abap"],"publishedAt":"2026-06-28","updatedAt":"$undefined","draft":false,"content":"$2b","excerpt":"$2c","previewContent":"$2d","connections":[],"readingMinutes":16,"languages":["en"],"backlinks":["sap-abap"],"unresolvedReferences":[]},{"slug":"sap-abap-5","language":"en","title":"SAP ABAP Modularization","part":"ABAP","summary":"SAP ABAP Modularization","category":"Technical","tags":["sap","abap"],"publishedAt":"2026-07-06","updatedAt":"$undefined","draft":false,"content":"$2e","excerpt":"$2f","previewContent":"$30","connections":[],"readingMinutes":19,"languages":["en"],"backlinks":["sap-abap"],"unresolvedReferences":[]},{"slug":"sap-abap-6","language":"en","title":"SAP ABAP Classical Report","part":"ABAP","summary":"SAP ABAP Classical Report","category":"Technical","tags":["sap","abap"],"publishedAt":"2026-07-13","updatedAt":"$undefined","draft":false,"content":"$31","excerpt":"$32","previewContent":"$33","connections":[],"readingMinutes":18,"languages":["en"],"backlinks":["sap-abap"],"unresolvedReferences":[]},{"slug":"sap-abap-7","language":"en","title":"SAP ABAP ALV Report","part":"ABAP","summary":"SAP ABAP ALV Report","category":"Technical","tags":["sap","abap"],"publishedAt":"2026-07-21","updatedAt":"$undefined","draft":false,"content":"$34","excerpt":"$35","previewContent":"$36","connections":[],"readingMinutes":19,"languages":["en"],"backlinks":["sap-abap"],"unresolvedReferences":[]},{"slug":"sap-sd","language":"vi","title":"Chương 5. Bài toàn vận hành doanh nghiệp về luồng bán hàng và phân phối","part":"Part 2. Cú chuyển mình trong sự nghiệp","summary":"Hiểu được cú pháp ABAP, nắm vững cấu trúc tầng Application hay kiến trúc Data Dictionary mới chỉ là bước đầu. Kiến thức kỹ thuật của tôi sẽ trở nên vô dụng nếu như không được sử dụng để giải quyết một vấn đề cụ thể. Thay vì bắt tay vào code ngay một ứng dụng SAP, tôi chọn cách hiểu bức tranh nghiệp vụ toàn cảnh. Khi đã có cái nhìn rõ ràng hơn về nghiệp vụ các module, tôi sẽ hiểu rõ những gì mình đang làm hơn. Hơn nữa vào thời điểm hiện tại, AI có thể hỗ trợ rất nhiều trong kỹ thuật, hiểu rõ nghiệp vụ sẽ tăng tốc quá trình làm việc đáng kể. Bước đầu về nghiệp vụ, tôi chọn bắt đầu với module SD (Sales & Distribution) — trái tim vận hành doanh thu của mọi tổ chức.","category":"Personal","tags":["sap","sd"],"publishedAt":"2026-07-28","updatedAt":"$undefined","draft":false,"content":"\nSD (Sales & Distribution) giải quyết đúng một bài toán cốt lõi của doanh nghiệp: Làm sao để bán được hàng, giao được hàng và thu được tiền về tài khoản mà không bị thất thoát hay nghẽn quy trình.\nNghiệp vụ SD xoay quanh chuỗi quy trình kinh điển gọi là Order-to-Cash (O2C) bắt đầu từ bước khách hàng có sự quan tâm về sản phẩm, hỏi giá, thông tin đến ghi nhận đơn hàng đến bước thanh toán, kết thúc vòng đời đơn hàng.\n\n### Order To Cash Architecture\n\n[Đọc tiếp: Order To Cash Architecture →](/blog/sap-sd-1-o2c)\n\n### Organization and Master Data\n\n[Đọc tiếp: Organization and Master Data →](/blog/sap-sd-2-organization)\n\n### Sale Document Control and Pricing\n\n[Đọc tiếp: Document Control and Pricing →](/blog/sap-sd-3-sale-document)\n\n### Fulfillment, Posting, and Integration\n\n[Đọc tiếp: Fulfillment, Posting, and Integration →](/blog/sap-sd-4-fulfilment-posting-integration)\n\n### SAP RAP\n\n[Đọc tiếp: SAP RAP →](/blog/sap-rap)\n","excerpt":"SD (Sales & Distribution) giải quyết đúng một bài toán cốt lõi của doanh nghiệp: Làm sao để bán được hàng, giao được hàng và thu được tiền về tài khoản mà không bị thất thoát hay nghẽn quy trình. Nghiệp vụ SD xoay quanh chuỗi quy trình kinh điển gọi là Order-to-Cash (O2C) bắt đầu từ bước khách hàng có sự quan tâm về sản phẩm, hỏi giá, thông tin đến ghi nhận đơn hàng đến bước thanh toán, kết thúc vòng đời đơn hàng. Order To Cash Architecture Đọc tiếp: Order To Cash Architecture → Organization and Master Data Đọc tiếp: Organization and Master Data → Sale Document Control and Pricing Đọc tiếp: Document Control and Pricing → Fulfillment, Posting, and Integration Đọc tiếp: Fulfillment, Posting, and Integration → SAP RAP Đọc tiếp: SAP RAP →","previewContent":"SD (Sales & Distribution) giải quyết đúng một bài toán cốt lõi của doanh nghiệp: Làm sao để bán được hàng, giao được hàng và thu được tiền về tài khoản mà không bị thất thoát hay nghẽn quy trình.\nNghiệp vụ SD xoay quanh chuỗi quy trình kinh điển gọi là Order-to-Cash (O2C) bắt đầu từ bước khách hàng có sự quan tâm về sản phẩm, hỏi giá, thông tin đến ghi nhận đơn hàng đến bước thanh toán, kết thúc vòng đời đơn hàng.\n\n### Order To Cash Architecture\n\n[Đọc tiếp: Order To Cash Architecture →](/blog/sap-sd-1-o2c)\n\n### Organization and Master Data\n\n[Đọc tiếp: Organization and Master Data →](/blog/sap-sd-2-organization)\n\n### Sale Document Control and Pricing\n\n[Đọc tiếp: Document Control and Pricing →](/blog/sap-sd-3-sale-document)\n\n### Fulfillment, Posting, and Integration\n\n[Đọc tiếp: Fulfillment, Posting, and Integration →](/blog/sap-sd-4-fulfilment-posting-integration)\n\n### SAP RAP\n\n[Đọc tiếp: SAP RAP →](/blog/sap-rap)","connections":["sap-sd-1-o2c","sap-sd-2-organization","sap-sd-3-sale-document","sap-sd-4-fulfilment-posting-integration","sap-rap"],"readingMinutes":1,"languages":["vi"],"backlinks":["sap-abap"],"unresolvedReferences":[]},{"slug":"sap-sd-1-o2c","language":"en","title":"SAP SD Order To Cash Overview","part":"ABAP","summary":"This document describes the technical structure and runtime boundaries of the SAP Sales and Distribution Order-to-Cash process. Its purpose is to connect the business-document chain to document grain, persistence landmarks, posting effects, document flow, diagnostic evidence, and clean-core integration contracts.","category":"Technical","tags":["sap","sd"],"publishedAt":"2026-07-30","updatedAt":"$undefined","draft":false,"content":"$37","excerpt":"$38","previewContent":"$39","connections":[],"readingMinutes":28,"languages":["en"],"backlinks":["sap-sd"],"unresolvedReferences":[]},{"slug":"sap-sd-2-organization","language":"en","title":"SAP SD Organizational and Master Data","part":"ABAP","summary":"This document explains how SAP Sales and Distribution combines organizational configuration and reusable master data to establish a valid processing context for a sales transaction. It connects business meaning to classic persistence landmarks, maintenance transactions, runtime determination, diagnostic technique, RAP modeling, and clean-core boundaries.","category":"Technical","tags":["sap","sd"],"publishedAt":"2026-08-06","updatedAt":"$undefined","draft":false,"content":"$3a","excerpt":"$3b","previewContent":"$3c","connections":[],"readingMinutes":23,"languages":["en"],"backlinks":["sap-sd"],"unresolvedReferences":[]},{"slug":"sap-sd-3-sale-document","language":"en","title":"SAP SD Document Control and Pricing","part":"ABAP","summary":"This document explains how SAP Sales and Distribution controls a Sales Order at header, item, and schedule-line level and how the condition technique builds the document-specific pricing result. It connects business grain to determination inputs, Customizing, runtime persistence, diagnostic evidence, RAP concepts, and clean-core boundaries.","category":"Technical","tags":["sap","sd"],"publishedAt":"2026-08-15","updatedAt":"$undefined","draft":false,"content":"$3d","excerpt":"$3e","previewContent":"$3f","connections":[],"readingMinutes":26,"languages":["en"],"backlinks":["sap-sd"],"unresolvedReferences":[]},{"slug":"sap-sd-4-fulfilment-posting-integration","language":"en","title":"SAP SD Fulfillment, Posting, and Integration","part":"ABAP","summary":"This document explains the technical execution path from a delivery-relevant Sales Order through Outbound Delivery, picking, packing, Post Goods Issue (PGI), billing, accounting, payment clearing, and external integration. It connects business-document boundaries to configuration, persistence, application logs, interfaces, reversals, diagnostic evidence, and clean-core extension design.","category":"Technical","tags":["sap","sd"],"publishedAt":"2026-08-22","updatedAt":"$undefined","draft":false,"content":"$40","excerpt":"$41","previewContent":"$42","connections":[],"readingMinutes":32,"languages":["en"],"backlinks":["sap-sd"],"unresolvedReferences":[]},{"slug":"sap-rap","language":"vi","title":"Chương 6. Triển khai nghiệp vụ với kiến trúc hệ thống chuẩn Clean Core - RAP","part":"Part 2. Cú chuyển mình trong sự nghiệp","summary":"Sau khi hiểu được một phần nghiệp vụ. Tôi chọn cách triển khai bài toán trên một giải pháp Backend hiện đại, không chỉ đơn thuần là một ALV report. Từ viết code thủ công đến kiến trúc xử lý hướng đối tượng, phân tầng rõ ràng và bám sát triết lý Clean Core","category":"Personal","tags":["sap","rap"],"publishedAt":"2026-08-25","updatedAt":"$undefined","draft":false,"content":"\n### SAP RAP Architecture and End-to-End Runtime\n\n[Đọc tiếp: SAP RAP Architecture and End-to-End Runtime→](/blog/sap-rap-1-architecture-to-e2e-runtime)\n\n### SAP RAP CDS Data Modeling and Projection Design\n\n[Đọc tiếp: SAP RAP CDS Data Modeling and Projection Design →](/blog/sap-rap-2-cds-data)\n\n### SAP RAP Behavior Modeling and Implementation\n\n[Đọc tiếp: SAP RAP Behavior Modeling and Implementation →](/blog/sap-rap-3-behavior-modeling)\n\n### SAP RAP Behavior Modeling and Implementation\n\n[Đọc tiếp: SAP Transactions, Draft, and Concurrency →](/blog/sap-rap-4-transaction-draft-concurrency)\n\n### SAP RAP Service Exposure and Fiori Elements\n\n[Đọc tiếp: SAP RAP Service Exposure and Fiori Elements →](/blog/sap-rap-5-service-exposure)\n\n### SAP RAP Security, Testing, and Production Readiness\n\n[Đọc tiếp: SAP RAP Security, Testing, and Production Readiness →](/blog/sap-rap-6-security-testing)\n","excerpt":"SAP RAP Architecture and End-to-End Runtime Đọc tiếp: SAP RAP Architecture and End-to-End Runtime→ SAP RAP CDS Data Modeling and Projection Design Đọc tiếp: SAP RAP CDS Data Modeling and Projection Design → SAP RAP Behavior Modeling and Implementation Đọc tiếp: SAP RAP Behavior Modeling and Implementation → SAP RAP Behavior Modeling and Implementation Đọc tiếp: SAP Transactions, Draft, and Concurrency → SAP RAP Service Exposure and Fiori Elements Đọc tiếp: SAP RAP Service Exposure and Fiori Elements → SAP RAP Security, Testing, and Production Readiness Đọc tiếp: SAP RAP Security, Testing, and Production Readiness →","previewContent":"### SAP RAP Architecture and End-to-End Runtime\n\n[Đọc tiếp: SAP RAP Architecture and End-to-End Runtime→](/blog/sap-rap-1-architecture-to-e2e-runtime)\n\n### SAP RAP CDS Data Modeling and Projection Design\n\n[Đọc tiếp: SAP RAP CDS Data Modeling and Projection Design →](/blog/sap-rap-2-cds-data)\n\n### SAP RAP Behavior Modeling and Implementation\n\n[Đọc tiếp: SAP RAP Behavior Modeling and Implementation →](/blog/sap-rap-3-behavior-modeling)\n\n### SAP RAP Behavior Modeling and Implementation\n\n[Đọc tiếp: SAP Transactions, Draft, and Concurrency →](/blog/sap-rap-4-transaction-draft-concurrency)\n\n### SAP RAP Service Exposure and Fiori Elements\n\n[Đọc tiếp: SAP RAP Service Exposure and Fiori Elements →](/blog/sap-rap-5-service-exposure)\n\n### SAP RAP Security, Testing, and Production Readiness\n\n[Đọc tiếp: SAP RAP Security, Testing, and Production Readiness →](/blog/sap-rap-6-security-testing)","connections":["sap-rap-1-architecture-to-e2e-runtime","sap-rap-2-cds-data","sap-rap-3-behavior-modeling","sap-rap-4-transaction-draft-concurrency","sap-rap-5-service-exposure","sap-rap-6-security-testing"],"readingMinutes":1,"languages":["vi"],"backlinks":["sap-sd"],"unresolvedReferences":[]},{"slug":"sap-rap-1-architecture-to-e2e-runtime","language":"en","title":"SAP RAP Architecture and End-to-End Runtime","part":"ABAP","summary":"This document explains the architecture and runtime of the ABAP RESTful Application Programming Model (RAP). It traces metadata, read, and transactional requests through CDS, behavior, service exposure, the RAP transactional buffer, the save sequence, and database persistence.","category":"Technical","tags":["sap","rap"],"publishedAt":"2026-08-30","updatedAt":"$undefined","draft":false,"content":"$43","excerpt":"$44","previewContent":"$45","connections":[],"readingMinutes":28,"languages":["en"],"backlinks":["sap-rap"],"unresolvedReferences":[]},{"slug":"sap-rap-2-cds-data","language":"en","title":"SAP RAP CDS Data Modeling and Projection Design","part":"RAP","summary":"This document explains how ABAP CDS defines the structural and semantic model of a RAP business object and how CDS projection views adapt that model for a specific consumer. It focuses on entity boundaries, keys, compositions, associations, cardinality, semantic annotations, projection contracts, and navigation topology.","category":"Technical","tags":["sap","rap"],"publishedAt":"2026-09-02","updatedAt":"$undefined","draft":false,"content":"$46","excerpt":"$47","previewContent":"$48","connections":[],"readingMinutes":24,"languages":["en"],"backlinks":["sap-rap"],"unresolvedReferences":[]},{"slug":"sap-rap-3-behavior-modeling","language":"en","title":"SAP RAP Behavior Modeling and Implementation","part":"RAP","summary":"This document explains how a RAP business object becomes transactional. It covers the base behavior definition, behavior projection, managed and unmanaged implementation choices, behavior pools, standard operations, field control, determinations, validations, actions, prechecks, feature control, EML, and RAP response structures.","category":"Technical","tags":["sap","rap"],"publishedAt":"2026-09-07","updatedAt":"$undefined","draft":false,"content":"$49","excerpt":"$4a","previewContent":"$4b","connections":[],"readingMinutes":26,"languages":["en"],"backlinks":["sap-rap"],"unresolvedReferences":[]},{"slug":"sap-rap-4-transaction-draft-concurrency","language":"en","title":"SAP RAP Transactions, Draft, and Concurrency","part":"RAP","summary":"This document explains how RAP manages state from the first modification until database commit. It covers the interaction phase, transactional buffer, save sequence, draft persistence, draft actions, pessimistic locks, entity ETags, total ETags, early and late numbering, and transaction ownership.","category":"Technical","tags":["sap","rap"],"publishedAt":"2026-09-10","updatedAt":"$undefined","draft":false,"content":"$4c","excerpt":"$4d","previewContent":"$4e","connections":[],"readingMinutes":25,"languages":["en"],"backlinks":["sap-rap"],"unresolvedReferences":[]},{"slug":"sap-rap-5-service-exposure","language":"en","title":"SAP RAP Service Exposure and Fiori Elements","part":"RAP","summary":"This document explains how a reusable RAP business object becomes a consumer-facing OData service and a metadata-driven SAP Fiori elements application. It covers service projections, behavior projections, metadata extensions, value helps, side effects, service definitions, service bindings, OData V4 UI and Web API contracts, publication, and runtime diagnosis.","category":"Technical","tags":["sap","rap"],"publishedAt":"2026-09-12","updatedAt":"$undefined","draft":false,"content":"$4f","excerpt":"$50","previewContent":"$51","connections":[],"readingMinutes":23,"languages":["en"],"backlinks":["sap-rap"],"unresolvedReferences":[]},{"slug":"sap-rap-6-security-testing","language":"en","title":"SAP RAP Service Exposure and Fiori Elements","part":"RAP","summary":"This document explains how a reusable RAP business object becomes a consumer-facing OData service and a metadata-driven SAP Fiori elements application. It covers service projections, behavior projections, metadata extensions, value helps, side effects, service definitions, service bindings, OData V4 UI and Web API contracts, publication, and runtime diagnosis.","category":"Technical","tags":["sap","rap"],"publishedAt":"2026-09-12","updatedAt":"$undefined","draft":false,"content":"$52","excerpt":"$53","previewContent":"$54","connections":[],"readingMinutes":23,"languages":["en"],"backlinks":["sap-rap"],"unresolvedReferences":[]},{"slug":"toi-di-tim-mot-khoang-dung","language":"vi","title":"Tôi đi tìm cho mình một khoảng dừng","part":"Part 3. Cuộn phim","summary":"Sau một thời gian dài chạy theo công việc, tính từ lúc tôi còn chưa tốt nghiệp Đại học đến bây giờ, tôi chưa có một kỳ nghỉ nào thật sự trọn vẹn cho riêng mình cả. Thời gian gần đây tôi cảm nhận rõ sự ‘burnout’ trong mình, tôi mất cảm xúc hay không còn hứng thú với những điều mình từng rất yêu thích. Thế là tôi quyết định xách con xe của mình, rời Sài Gòn, đi “chạm cỏ” ở một thành phố khác với không lịch trình và không có một sự kỳ vọng nào.","category":"Personal","tags":["introduction","journal","psychology"],"publishedAt":"2026-10-24","updatedAt":"$undefined","draft":false,"content":"$55","excerpt":"$56","previewContent":"$57","connections":[],"readingMinutes":19,"languages":["vi"],"backlinks":[],"unresolvedReferences":[]}],"initialDocument":"$undefined","language":"vi"}]]}] b:[["$","meta","0",{"charSet":"utf-8"}],["$","meta","1",{"name":"viewport","content":"width=device-width, initial-scale=1"}]] 58:I[27201,["/_next/static/immutable/chunks/33v8uwkv4wy50.js"],"IconMark"] 8:null d:[["$","title","0",{"children":"Graph | Thanh's Blog"}],["$","meta","1",{"name":"description","content":"Explore connections between technical and personal documents."}],["$","link","2",{"rel":"shortcut icon","href":"/images/favicon.webp"}],["$","link","3",{"rel":"icon","href":"/images/favicon.webp"}],["$","link","4",{"rel":"apple-touch-icon","href":"/images/favicon.webp"}],["$","$L58","5",{}]] </article></body></html>

1:"$Sreact.fragment" 2:I[39756,["/_next/static/immutable/chunks/33v8uwkv4wy50.js"],"default"] 3:I[37457,["/_next/static/immutable/chunks/33v8uwkv4wy50.js"],"default"] 4:I[2355,["/_next/static/immutable/chunks/33v8uwkv4wy50.js"],"Analytics"] 6:I[97367,["/_next/static/immutable/chunks/33v8uwkv4wy50.js"],"OutletBoundary"] 7:"$Sreact.suspense" a:I[97367,["/_next/static/immutable/chunks/33v8uwkv4wy50.js"],"ViewportBoundary"] c:I[97367,["/_next/static/immutable/chunks/33v8uwkv4wy50.js"],"MetadataBoundary"] e:I[68027,["/_next/static/immutable/chunks/33v8uwkv4wy50.js"],"default",1] :HL["/_next/static/immutable/chunks/1q8dcqrhcyrxp.css","style"] :HL["/_next/static/immutable/media/3e185f0c9c3d9cda-s.p.034pt8qm9y03o.woff2","font",{"crossOrigin":"","type":"font/woff2"}] :HL["/_next/static/immutable/media/43cf86ead64c3be9-s.p.1_u0d4buat6wq.woff2","font",{"crossOrigin":"","type":"font/woff2"}] :HL["/_next/static/immutable/chunks/1574stxo0s0gk.css","style"] 9:X 0:{"P":null,"c":["","blog","graph"],"q":"","i":false,"f":[[["",{"children":["blog",{"children":["graph",{"children":["__PAGE__",{},"$undefined","$undefined",4096]},"$undefined","$undefined",4096]},"$undefined","$undefined",4096]},"$undefined","$undefined",4112],[["$","$1","c",{"children":[[["$","link","0",{"rel":"stylesheet","href":"/_next/static/immutable/chunks/1q8dcqrhcyrxp.css","precedence":"next","crossOrigin":"$undefined","nonce":"$undefined"}],["$","script","script-0",{"src":"/_next/static/immutable/chunks/33v8uwkv4wy50.js","async":true,"nonce":"$undefined"}]],["$","html",null,{"className":"alegreya_a702697e-module__PsVypa__variable","lang":"en","children":["$","body",null,{"children":[["$","$L2",null,{"parallelRouterKey":"children","error":"$undefined","errorStyles":"$undefined","errorScripts":"$undefined","template":["$","$L3",null,{}],"templateStyles":"$undefined","templateScripts":"$undefined","notFound":[[["$","title",null,{"children":"404: This page could not be found."}],["$","div",null,{"style":{"fontFamily":"system-ui,\"Segoe UI\",Roboto,Helvetica,Arial,sans-serif,\"Apple Color Emoji\",\"Segoe UI Emoji\"","height":"100vh","textAlign":"center","display":"flex","flexDirection":"column","alignItems":"center","justifyContent":"center"},"children":["$","div",null,{"children":[["$","style",null,{"dangerouslySetInnerHTML":{"__html":"body{color:#000;background:#fff;margin:0}.next-error-h1{border-right:1px solid rgba(0,0,0,.3)}@media (prefers-color-scheme:dark){body{color:#fff;background:#000}.next-error-h1{border-right:1px solid rgba(255,255,255,.3)}}"}}],["$","h1",null,{"className":"next-error-h1","style":{"display":"inline-block","margin":"0 20px 0 0","padding":"0 23px 0 0","fontSize":24,"fontWeight":500,"verticalAlign":"top","lineHeight":"49px"},"children":404}],["$","div",null,{"style":{"display":"inline-block"},"children":["$","h2",null,{"style":{"fontSize":14,"fontWeight":400,"lineHeight":"49px","margin":0},"children":"This page could not be found."}]}]]}]}]],[]],"forbidden":"$undefined","unauthorized":"$undefined"}],["$","$L4",null,{}]]}]}]]}],{"children":[["$","$1","c",{"children":[null,["$","$L2",null,{"parallelRouterKey":"children","error":"$undefined","errorStyles":"$undefined","errorScripts":"$undefined","template":["$","$L3",null,{}],"templateStyles":"$undefined","templateScripts":"$undefined","notFound":"$undefined","forbidden":"$undefined","unauthorized":"$undefined"}]]}],{"children":[["$","$1","c",{"children":[null,["$","$L2",null,{"parallelRouterKey":"children","error":"$undefined","errorStyles":"$undefined","errorScripts":"$undefined","template":["$","$L3",null,{}],"templateStyles":"$undefined","templateScripts":"$undefined","notFound":"$undefined","forbidden":"$undefined","unauthorized":"$undefined"}]]}],{"children":[["$","$1","c",{"children":["$L5",[["$","link","0",{"rel":"stylesheet","href":"/_next/static/immutable/chunks/1574stxo0s0gk.css","precedence":"next","crossOrigin":"$undefined","nonce":"$undefined"}],["$","script","script-0",{"src":"/_next/static/immutable/chunks/2l4ck-u678up0.js","async":true,"nonce":"$undefined"}],["$","script","script-1",{"src":"/_next/static/immutable/chunks/37ed-dnvt263u.js","async":true,"nonce":"$undefined"}],["$","script","script-2",{"src":"/_next/static/immutable/chunks/3r8ratd_83ruq.js","async":true,"nonce":"$undefined"}]],["$","$L6",null,{"children":["$","$7",null,{"name":"Next.MetadataOutlet","children":"$@8"}]}]]}],{},null,false,null]},null,false,"$9"]},null,false,"$9"]},null,false,null],["$","$1","h",{"children":[null,["$","$La",null,{"children":"$Lb"}],["$","div",null,{"hidden":true,"children":["$","$Lc",null,{"children":["$","$7",null,{"name":"Next.Metadata","children":"$Ld"}]}]}],["$","meta",null,{"name":"next-size-adjust","content":""}]]}],false]],"m":"$undefined","G":["$e",[["$","link","0",{"rel":"stylesheet","href":"/_next/static/immutable/chunks/1q8dcqrhcyrxp.css","precedence":"next","crossOrigin":"$undefined","nonce":"$undefined"}]]],"S":false,"h":null,"r":"$undefined","s":"$undefined","a":"$undefined","l":"$undefined","p":"$undefined","d":"$undefined","b":"gdPg9NV3osZpY6Ild7pQx"} f:I[93963,["/_next/static/immutable/chunks/33v8uwkv4wy50.js","/_next/static/immutable/chunks/2l4ck-u678up0.js","/_next/static/immutable/chunks/37ed-dnvt263u.js","/_next/static/immutable/chunks/3r8ratd_83ruq.js"],"Header"] 10:I[20586,["/_next/static/immutable/chunks/33v8uwkv4wy50.js","/_next/static/immutable/chunks/2l4ck-u678up0.js","/_next/static/immutable/chunks/37ed-dnvt263u.js","/_next/static/immutable/chunks/3r8ratd_83ruq.js"],"GraphExplorer"] 9:C 11:T1f34, ## Điều gì đã thôi thúc tôi bắt đầu viết blog này? Tôi vốn là một người không giỏi trong việc thể hiện cảm xúc, không giỏi trong việc diễn đạt và trình bày ý tưởng. Và nhìn lại quá khứ, điều đó đã cản trở tôi có thể dấn thân vào làm một việc gì đó hết mình. Những ngày tháng ngồi ở giảng đường Đại học, nếu như Giảng viên không trực tiếp gọi tôi thì có lẽ tôi cũng chả bao giờ phát biểu ý kiến, có lẽ là do sợ sai hay bị chê cười… haha… đúng là đần, mình là người trả tiền sử dụng dịch vụ mà, sợ cái đ’ gì chứ. Cuộc sống của tôi cứ trôi qua êm đềm như vậy. Đến ngày tốt nghiệp, rồi cũng đi thực tập và may mắn có được công việc mà ở đó đã xây dựng lên nền tảng khá vững cho tôi. Bạn đã nghĩ cuộc sống của tôi như vậy là ổn, không có gì để chê đúng không, tốt nghiệp trường top (Bách Khoa), lại công việc ổn định. Cứ thế mà an nhàn đi, suy nghĩ làm gì. Sản phẩm ở công ty đầu tiên mà tôi làm việc, cuối cùng cũng đến được giai đoạn production, tôi hào hứng ở lại công ty ngồi countdown, ăn mừng vì app đã lên được App store. Nhưng những ngày sau đó lại là chuỗi ngày tát thẳng vào sự vui mừng ban đầu. Khi mà số lượng users sử dụng app tăng lên quá chậm, phần lớn còn vào vì chiến dịch give away… Chuỗi ngày fix bug gấp gáp trên production, hay gắn nhanh thêm nhiều tính năng vào để team sale có cái mà đi chào hàng, cố chạy đua mà không rõ đích đến. Mặc dù rất buồn nhưng tôi quyết định phải đi tìm bến đỗ mới để kết thúc chuỗi ngày vô nghĩa này, và khi ngồi xuống để viết lại CV, tôi rất khó để có thể viết portfolio mà không mở lại code để xem. Đấy là lúc tôi nhận ra kỹ năng viết không hề dễ, nếu không được rèn luyện, bạn sẽ rất khó để trình bày lại ý tưởng một cách súc tích mà vẫn thể hiện đầy đủ thông tin. Tính cách của developer thì phần lớn là hướng nội, chúng ta cứ âm thầm làm, nói thứ ngôn ngữ chỉ người trong ngành hiểu, và đôi khi bạn chỉ nói chuyện với những người ở trong circle của bạn. Sẽ có lúc bạn nhìn thấy những người có kỹ năng kém hơn bạn, nhưng họ lại có nhiều job hơn, lương cao hơn. Không nói ra nhưng trong lòng bạn vẫn thấy có điều gì đó sai trái, không công bằng. Không phải là do thế giới bất công đâu (à, có một chút). Tuy nhiên có một cái mà bạn không nhìn ra đó là họ giỏi hơn bạn về kỹ năng bán hàng, về kỹ năng trình bày vấn đề, họ giúp khách hàng hiểu giá trị công việc họ mang lại, hiểu rõ hơn về những gì họ đang làm. Và dĩ nhiên cơ hội tìm đến họ sẽ là cao hơn bạn. Khi bạn không biết giải thích, trình bày portfolio một cách rõ ràng, chả ai hiểu bạn đang làm gì cả. ## Cảm xúc và câu chuyện: Thứ AI không thể viết thay tôi Tốc độ phát triển AI 1-2 năm trở lại đây thật kinh khủng. việc nó gợi ý code để tôi ấn "Tab... Tab" hoàn thành một function đã thấy viễn tưởng lắm rồi. Vậy mà bây giờ, chỉ cần gõ một câu prompt ngắn, AI có thể hoàn thành cả một chương trình đơn giản, hay viết đầy đủ function, testcase trong module. Tôi không muốn bản thân mình phụ thuộc AI, nhưng số lượng task thì tăng dần và deadline ngày càng gần, khiến việc nếu không dùng AI nhiều thì không thể hoàn thành được. Một nghịch lý khi sử dụng AI là, tôi có thể làm được rất nhiều việc trong thời gian ngắn, tuy nhiên cảm giác tự tin của tôi thì giảm dần khi phản xạ đầu tiên của tôi khi nhận được task bây giờ là... gõ prompt. Đối với trải nghiệm cá nhân tôi, thì AI chỉ đang phóng đại khả năng hiện tại của bạn, chứ không thay bạn làm gì cả. Bằng chứng là đối với các task tôi đã nắm được cách làm, chỉ cần gõ vài prompt, lên plan thì AI làm xong rất nhanh, còn những task mà tôi không nắm rõ cách làm, tôi còn chả chắc chắn giải pháp mà AI đưa ra có thật sự là tốt không, mà cứ đọc xuôi tai là accept hết, tất nhiên đối với những task này thì thời gian hoàn thành lâu hơn hẳn những task trước. Nhưng có một điều không thể chối cãi là AI đã xoá bỏ kha khá những rào cản về mặt tiếp cận công nghệ. Trong thời đại AI, người thắng không phải là người chỉ có kỹ năng, người thắng sẽ là người biết cách học nhanh, nghĩ rõ và trình bày giá trị của bản thân ra ngoài. Và viết là kỹ năng giúp chúng ta thực hiện được cả 3 điều đấy. AI có thể tạo thông tin, nhưng không thể có trải nghiệm hay cảm xúc thực tế. Viết là cách duy nhất để gửi gắm cá tính, tư duy và trải nghiệm cá nhân. Kỹ thuật tốt giúp tạo ra sản phẩm, nhưng khả năng nói chuyện (storytelling) và truyền tải giá trị qua ngôn từ mới là thứ giúp khách hàng thực sự thấu hiểu, trân trọng và nhìn thấy giá trị của sản phẩm/dịch vụ đó. Viết chính là quá trình sắp xếp lại suy nghĩ, giúp tư duy mạch lạc và sắc bén hơn. ## Cấu trúc không gian - cách tôi phân bổ nội dung blog bằng 2 ngôn ngữ. Tôi sẽ cố gắng để các bài viết có đầy đủ cả hai ngôn ngữ: Tiếng Việt và Tiếng Anh. Cách viết là tôi sẽ viết một bài trên một ngôn ngữ gốc, sau đó dịch sang ngôn ngữ còn lại. Việc này giúp tôi review lại bài viết thêm một lần và chỉnh sửa lại những lỗ hỏng. Đối với các bài viết về Nhật ký, tôi sẽ viết bằng Tiếng Việt vì ngôn ngữ mẹ đẻ sẽ giúp tôi diễn đạt trọn vẹn sự tự nhiên, sâu sắc và cứ để cảm xúc dẫn mình đi mà không bị giới hạn bởi từ vựng. Vậy tại sao lại có chuyện viết bằng Tiếng Anh rồi dịch lại tiếng Việt ? Không phải vì tôi sính ngoại đâu. Do phần lớn các kiến thức tôi đều đọc bản gốc bằng Tiếng Anh, việc diễn giải thẳng bằng thuật ngữ kỹ thuật quốc tế sẽ chuẩn xác, dễ tra cứu và dễ trình bày suy nghĩ kỹ thuật một cách ngắn gọn. Với lại tôi có khả năng viết Tiếng Anh mà, tại sao không chứ…hehe. Các bài viết cũng sẽ không đứng đơn lẻ một mình, những thuật ngữ hay những bài viết liên quan sẽ tạo nên một liên kết cực kỳ bền vững, bạn có thể xem ở tab “Graph View” ## Những dòng chữ đầu tiên cho một chặng đường dài Hoàn thành luôn tốt hơn hoàn hảo. Việc nhấn nút _Publish_ cho bài viết này là bước đi đầu tiên giúp tôi bước ra khỏi sự trì hoãn của chính mình. Cảm ơn bạn đã đọc đến những dòng cuối cùng này. Hành trình viết và lưu trữ chính thức bắt đầu từ hôm nay. Chặng đường phía trước vẫn còn rất nhiều kiến trúc cần dựng và nhiều câu chuyện cần kể. [Đọc tiếp: Chương 2. Tôi là ai giữa thế giới này →](/blog/who-am-i) 12:T7a0,Điều gì đã thôi thúc tôi bắt đầu viết blog này? Tôi vốn là một người không giỏi trong việc thể hiện cảm xúc, không giỏi trong việc diễn đạt và trình bày ý tưởng. Và nhìn lại quá khứ, điều đó đã cản trở tôi có thể dấn thân vào làm một việc gì đó hết mình. Những ngày tháng ngồi ở giảng đường Đại học, nếu như Giảng viên không trực tiếp gọi tôi thì có lẽ tôi cũng chả bao giờ phát biểu ý kiến, có lẽ là do sợ sai hay bị chê cười… haha… đúng là đần, mình là người trả tiền sử dụng dịch vụ mà, sợ cái đ’ gì chứ. Cuộc sống của tôi cứ trôi qua êm đềm như vậy. Đến ngày tốt nghiệp, rồi cũng đi thực tập và may mắn có được công việc mà ở đó đã xây dựng lên nền tảng khá vững cho tôi. Bạn đã nghĩ cuộc sống của tôi như vậy là ổn, không có gì để chê đúng không, tốt nghiệp trường top (Bách Khoa), lại công việc ổn định. Cứ thế mà an nhàn đi, suy nghĩ làm gì. Sản phẩm ở công ty đầu tiên mà tôi làm việc, cuối cùng cũng đến được giai đoạn production, tôi hào hứng ở lại công ty ngồi countdown, ăn mừng vì app đã lên được App store. Nhưng những ngày sau đó lại là chuỗi ngày tát thẳng vào sự vui mừng ban đầu. Khi mà số lượng users sử dụng app tăng lên quá chậm, phần lớn còn vào vì chiến dịch give away… Chuỗi ngày fix bug gấp gáp trên production, hay gắn nhanh thêm nhiều tính năng vào để team sale có cái mà đi chào hàng, cố chạy đua mà không rõ đích đến. Mặc dù rất buồn nhưng tôi quyết định phải đi tìm bến đỗ mới để kết thúc chuỗi ngày vô nghĩa này, và khi ngồi xuống13:T1a0a, ## Những thứ định nghĩa sự tồn tại của tôi Mọi người thường nghĩ Dev bọn tôi chỉ biết có màn hình đen và những dòng code khô khan đúng không. Nhưng sau giờ làm, tôi lại ôm đàn, cầm máy ảnh đi lang thang, hoặc ngồi dựng một thước phim ngắn. Tôi còn chả biết có ai giống mình như vậy không. Blog này sinh ra vì tôi không muốn những mảnh ghép đó bị tách rời. Tôi là một cựu sinh viên Bách Khoa K18, chuyên ngành Khoa học máy tính. Vâng, sau 5 năm trầy trật trên giảng đường, cuối cùng tôi cũng có thể tự tin giới thiệu mình là một Kỹ sư máy tính. Nhưng quay ngược thời gian vào thời điểm chọn ngành, bản thân tôi còn chả định nghĩa được 'kỹ sư' là gì. Tôi chỉ biết là xung quanh mọi người ca ngợi nó lắm, nào là ra trường lương nghìn đô, nào là tạo ra nhiều đột phá công nghệ. Năm đó, tôi cũng là một trong số ít học sinh của trường đỗ vào Bách Khoa, cảm giác bước đi mặt vênh lên trời, 'oách xà lách' vô cùng, và cái niềm tự hào âm ỉ ấy tôi vẫn giữ mãi cho đến tận bây giờ. Thế nhưng, bước chân vào đại học chưa vui được bao lâu, cuộc đời đã vã cho tôi đôm đốp. Vốn xuất thân từ trường làng, tôi không đủ điều kiện tiếng Anh đầu vào của chương trình (IELTS 6.0) và bị xếp ngay vào lớp Pre-University. Thế giới của tôi lúc ấy bỗng chốc tối đen, vì đó là lần đầu tiên trong đời tôi thấm thía cảm giác thất bại. Cú sốc chưa dừng lại ở đó khi tôi bước vào phòng ký túc xá. Những đứa bạn bằng tuổi chung phòng toàn là 'quái vật': đứa thì giải Lý quốc gia, đứa thì IELTS 7.5 ôm bảng điểm sáng chói. Còn tôi? Chiếc IELTS 4.0 tròn trĩnh và một vốn tiếng Anh không thốt nổi một câu nên hồn. Nghĩ lại, vào thời điểm đó, cũng may là tôi có biết chút ít kỹ năng chơi đàn, việc kết bạn của mình đã trở nên dễ thở hơn. Tôi tự tập guitar từ năm tôi 15 tuổi, chỉ là lúc đấy nghỉ hè và không có gì làm nên tôi bảo ba mẹ là muốn học đàn, tôi muốn học piano, cơ mà số tiền tôi dành dụm được chỉ đủ mua guitar mà thôi (nghèo -\_-). Thế là tôi nghĩ thôi cũng được, đưa số tiền tích góp của mình cho anh hai mua về một cây guitar, giá của nó là 980k, không quá đắt nhưng vẫn là khoảng lớn dưới lăng kính của ba mẹ tôi (đến bây giờ tôi vẫn chưa thoải mái với việc chia sẻ giá trị thật những món đồ tôi sở hữu cho ba mẹ biết, có lẽ là khoảng cách thế hệ chăng, thời của bố mẹ, ăn no mặc ấm đã là hạnh phúc, làm sao hiểu được những mộng mơ nghệ thuật của tụi mình). Ngày nhận được cây đàn, tôi hào hứng gảy thử, để rồi nhận về một gáo nước lạnh: chả đánh được gì, cũng chả hiểu gì cả. Tại sao nó lại có 6 dây? Dây đầu tiên sao không phải nốt Đồ? Đã vậy bấm vào còn đau điếng cả tay. Tôi bất lực buông đàn, lòng thầm nghĩ: Có khi ngày xưa chọn piano lại đỡ khổ hơn..." Nhưng cũng may, 980k ngày ấy là một số tiền quá lớn đối với một đứa nhóc. Chính cái sự 'tiếc tiền' đó đã buộc tôi phải lì lợm ngồi lại với cây đàn. Tôi bắt đầu những chuỗi ngày nghiền ngẫm từng video hướng dẫn trên YouTube rồi lầm lũi thực hành. Từ những hợp âm bập bẹ đầu tiên, những bài nhạc đơn giản nhất, cho đến cả những kỹ thuật phức tạp sau này... tôi đều tự mình đi qua. Nghĩ lại, đó có lẽ là cột mốc đánh dấu thành quả tự học đầu tiên trong cuộc đời của tôi. Cho đến tận bây giờ, dù đã tốt nghiệp từ một ngôi trường đại học danh giá, tôi vẫn luôn tin rằng: Khả năng tự học mới chính là kỹ năng đáng giá nhất trong cuộc sống hiện đại, chứ không phải tấm bằng đại học. Tự học là thứ duy nhất cho bạn sự tự tin để tìm ra lời giải trong mọi tình huống, và quan trọng hơn cả, nó không bao giờ đặt ra giới hạn cho chính bản thân bạn. ## Nhãn dán nào cho tôi ? Tôi là ai giữa thế giới _Công nghệ_ và _Nghệ thuật_ ? Thật ra, bản thân tôi chưa bao giờ nghĩ quá nhiều về điều đó. Tôi chỉ đơn giản là làm những gì mình thích và thấy nên làm. Tôi đam mê công nghệ, thích đối mặt và giải quyết những bài toán hóc búa, và nó mang lại thu nhập cho tôi, giúp tôi mua được những món đồ tôi thích. Nhưng bên cạnh đó, tôi cũng yêu cái đẹp, yêu sự lãng mạn và bay bổng mà nghệ thuật mang lại. Đó cũng là lý do vì sao tôi ngồi xuống và bắt đầu gõ những dòng chữ này. Ngôn từ, suy cho cùng, có một sức mạnh to lớn hơn chúng ta tưởng tượng rất nhiều. Chúng ta thường có thói quen đóng khung giá trị của mình vào một cái nghề mỗi khi giới thiệu bản thân với ai đó. Nhưng hãy thử tưởng tượng, nếu một ngày vị trí đó không còn, cái nghề đó bỗng chốc biến mất, hoặc đơn giản là bạn đặt chân đến một vùng đất xa lạ nơi công việc ấy chưa từng tồn tại... lúc đó bạn sẽ định nghĩa bản thân mình như thế nào? Hay nói cách khác: Khi lột bỏ hết những danh xưng nghề nghiệp, bạn thực sự là ai? Đi qua nhiều lĩnh vực, tôi hiểu rằng mọi trải nghiệm đều bình đẳng như nhau. Gõ một dòng code hay bào một miếng gỗ phẳng, gảy một nhịp đàn hay bắt lấy một khung hình đẹp... mỗi khoảnh khắc đều mang lại cho tôi những rung động khác biệt. Tôi chọn không giới hạn mình trong bất kỳ định nghĩa nào, chỉ chọn tận hưởng cuộc đời này bằng mọi giác quan. Vì thế, cứ gọi tôi là Thanh – vậy là đủ. [Đọc tiếp: Chương 3. Không có gì thay đổi nếu không có gì thay đội →](/blog/nothing-change-if-nothing-change) 14:T7b0,Những thứ định nghĩa sự tồn tại của tôi Mọi người thường nghĩ Dev bọn tôi chỉ biết có màn hình đen và những dòng code khô khan đúng không. Nhưng sau giờ làm, tôi lại ôm đàn, cầm máy ảnh đi lang thang, hoặc ngồi dựng một thước phim ngắn. Tôi còn chả biết có ai giống mình như vậy không. Blog này sinh ra vì tôi không muốn những mảnh ghép đó bị tách rời. Tôi là một cựu sinh viên Bách Khoa K18, chuyên ngành Khoa học máy tính. Vâng, sau 5 năm trầy trật trên giảng đường, cuối cùng tôi cũng có thể tự tin giới thiệu mình là một Kỹ sư máy tính. Nhưng quay ngược thời gian vào thời điểm chọn ngành, bản thân tôi còn chả định nghĩa được 'kỹ sư' là gì. Tôi chỉ biết là xung quanh mọi người ca ngợi nó lắm, nào là ra trường lương nghìn đô, nào là tạo ra nhiều đột phá công nghệ. Năm đó, tôi cũng là một trong số ít học sinh của trường đỗ vào Bách Khoa, cảm giác bước đi mặt vênh lên trời, 'oách xà lách' vô cùng, và cái niềm tự hào âm ỉ ấy tôi vẫn giữ mãi cho đến tận bây giờ. Thế nhưng, bước chân vào đại học chưa vui được bao lâu, cuộc đời đã vã cho tôi đôm đốp. Vốn xuất thân từ trường làng, tôi không đủ điều kiện tiếng Anh đầu vào của chương trình (IELTS 6.0) và bị xếp ngay vào lớp Pre-University. Thế giới của tôi lúc ấy bỗng chốc tối đen, vì đó là lần đầu tiên trong đời tôi thấm thía cảm giác thất bại. Cú sốc chưa dừng lại ở đó khi tôi bước vào phòng ký túc xá. Những đứa bạn bằng tuổi chung phòng toàn là 'quái vật': đứa thì giải Lý quốc gia, đứa thì IELTS 7.5 ôm bảng điểm sáng chói. Còn tôi?15:T1a0c, ## Chúng ta đang quá tham lam Mạng xã hội ngày nay dựng lên những khung cảnh quá hoàn hảo: một đứa trẻ phát âm tiếng Anh chuẩn bản xứ, những người trẻ chưa đầy ba mươi đã sở hữu nhà riêng, xe sang hay tự do tài chính. Chúng ta lướt qua những lát cắt ấy mỗi ngày và vô tình rơi vào một cái bẫy tâm lý nguy hiểm: nhìn vào kết quả của người khác và gán nó làm tiêu chuẩn cho bản thân. Nhưng sự thật là, những gì bạn thấy chưa chắc đã là 100% sự thật, có những bí mật đằng sau mà bạn chưa nhìn rõ, mọi trạng thái ở hiện tại đều có nguyên do của nó. Đằng sau một đứa trẻ nói tiếng Anh lưu khoát có thể là một gia đình có điều kiện, được đầu tư học trường quốc tế và tiếp xúc với ngoại ngữ từ lúc còn chưa sõi tiếng mẹ đẻ. Đằng sau một sự thành công sớm là những nguồn lực ngầm về tài chính, mối quan hệ hoặc xuất phát điểm vượt trội. Tất nhiên vẫn sẽ tồn tại vài trường hợp xuất chúng, nhưng tỷ lệ là dưới 1%. Bạn cảm giác ghen tị với thành công của họ. Nhưng hành động của bạn là dành hàng giờ đồng hồ mỗi ngày chỉ để tiêu thụ nội dung và tiếp tục than vãn về cuộc sống hiện tại. Đợt rồi tôi có dịp được gặp lại những người bạn cũ thời cấp 3, cuộc trò chuyện đang rất vui vẻ thì đột nhiên có đứa bảo, "Chán quá tụi bây, tao làm ở chỗ đó mấy năm rồi mà chả thấy lên lương gì nhiều". Tôi mới hỏi lại nó là vậy công việc mày dạo này khó hơn trước à. Thì nó bảo, đâu vẫn thế thôi, mà tao làm được 4 năm rồi. Đoạn này tôi nghĩ thầm trong bụng thôi chứ cũng không nói ra, bro ở hiện tại làm việc y chang bro của 4 năm trước, vậy lý do gì mà người ta phải lên lương cho bro. Tôi dám cá là nếu tôi yêu cầu bạn liệt kê ra lợi ích của việc học tiếng anh, bạn sẽ kể ra được ít nhất là 10 đầu mục. Hay bạn biết rõ kiên trì tập gym sẽ được body đẹp hơn. Nhưng phần lớn chúng ta đều không làm những việc này. Không có quá nhiều người sẵn sàng trả giá để đạt được những gì họ thật sự muốn. ## Từ Nhận Thức Đến Hành Động: Kịch Bản Cho Sự Thay Đổi Chỉ ra sự thật phũ phàng này không phải để bạn chấp nhận số phận hay bỏ cuộc. Ý tôi là, mọi thứ trong cuộc sống này đều có thể thay đổi, chỉ là quy luật trao đổi luôn tồn tại. Nếu bạn không thể đầu tư bằng rất nhiều tiền của như người khác, bạn bắt buộc phải đầu tư bằng công sức và thời gian. Tiền bạc giúp rút ngắn chặng đường, nhưng sự kiên trì và kỷ luật cùng với sự toàn tâm mới là thứ có thể giúp bạn đạt được điều bạn muốn. Nếu thực sự muốn viết lại quy luật của chính mình, bạn phải bắt đầu thay đổi hành vi ngay từ hôm nay qua bốn bước chuyển biến rõ rệt. Đầu tiên, hãy phác thảo một hình mẫu cực kỳ cụ thể về phiên bản bạn muốn trở thành thay vì những ước muốn mơ hồ như "giỏi tiếng Anh" hay "có nhiều tiền". Hãy hình dung rõ bạn của phiên bản tưởng tượng đó làm công việc gì, giao tiếp ra sao và đối mặt với áp lực bằng thái độ thế nào. Tiếp theo, hãy biến mục tiêu khổng lồ đó thành một bài toán vận hành bằng cách xẻ nhỏ nó thành từng cột mốc theo năm, tháng, tuần và khép lại bằng những công việc cần hoàn thành mỗi ngày để tránh cảm giác bị ngợp. Khi đã có lộ trình, hãy dồn toàn bộ năng lượng để tập trung tuyệt đối vào hành động, ngừng tiêu thụ nội dung vô bổ của người khác cũng như ngừng than vãn về xuất phát điểm để hoàn thành trọn vẹn từng checklist nhỏ đã đề ra. Cuối cùng, hãy kiên trì theo đuổi mục tiêu trong âm thầm, bởi sự bứt phá chưa bao giờ đến sau một đêm mà là quả ngọt của vô số hành động đúng đắn được lặp đi lặp lại bền bỉ. Đừng kỳ vọng mọi thứ sẽ diễn ra tuyệt đối như những gì bạn đề ra, vì điều đó không xảy ra đâu. Mọi thứ đều có sai số, kế hoạch của bạn sẽ có những điều phi lý, hay có một biến số nào đó xuất hiện và làm mọi thứ rối tung. Nhưng không sao, chỉ cần bạn hành động, xem xét lại và sửa chữa, bạn sẽ tiến lên. ## Tự Viết Lại Kịch Bản Cho Chính Mình Nhưng lý thuyết thì lúc nào cũng đẹp đẽ, còn thực tế lại là một cuộc vật lộn âm thầm mỗi ngày. Bản thân tôi phải thú nhận rằng, việc chống chọi lại những cơn nghiện mạng xã hội hay thói quen trì hoãn chưa bao giờ là điều dễ dàng. Những tiếng chuông thông báo, những video ngắn cuốn hút vẫn luôn ở đó, sẵn sàng kéo tôi rời xa mục tiêu bất cứ lúc nào. Thay vì cố gắng đối đầu trực diện hay ép mình vào một kỷ luật thép phi thực tế, tôi chọn cách thỏa hiệp một cách thông minh với chính mình. Tôi tập trung giải quyết việc khó nhất và quan trọng nhất ngay vào đầu ngày. Đối với tôi, chiến thắng được buổi sáng đồng nghĩa với việc đã cầm chắc chiến thắng cho cả ngày hôm đó. Để rồi trong khoảng thời gian còn lại, nếu bản thân có lỡ sao nhãng hay lướt điện thoại một chút, tôi cũng không còn bị dằn dằn dội bởi cảm giác tội lỗi Chấp nhận những ngày mình không hoàn thành mục tiêu. Cuộc sống đôi khi có nhiều biến số mà ta không tài nào kiểm soát được, tôi cũng sẽ không tránh được những ngày buồn hay downmood, cả ngày vật vờ không làm được gì cả. Chấp nhận những khoảnh khắc yếu đuối của bản thân và khắc phục nó, bước tiếp. Hy vọng một ngày tôi sẽ được sống với hình ảnh mà tôi luôn hằng mong ước. 16:T799,Chúng ta đang quá tham lam Mạng xã hội ngày nay dựng lên những khung cảnh quá hoàn hảo: một đứa trẻ phát âm tiếng Anh chuẩn bản xứ, những người trẻ chưa đầy ba mươi đã sở hữu nhà riêng, xe sang hay tự do tài chính. Chúng ta lướt qua những lát cắt ấy mỗi ngày và vô tình rơi vào một cái bẫy tâm lý nguy hiểm: nhìn vào kết quả của người khác và gán nó làm tiêu chuẩn cho bản thân. Nhưng sự thật là, những gì bạn thấy chưa chắc đã là 100% sự thật, có những bí mật đằng sau mà bạn chưa nhìn rõ, mọi trạng thái ở hiện tại đều có nguyên do của nó. Đằng sau một đứa trẻ nói tiếng Anh lưu khoát có thể là một gia đình có điều kiện, được đầu tư học trường quốc tế và tiếp xúc với ngoại ngữ từ lúc còn chưa sõi tiếng mẹ đẻ. Đằng sau một sự thành công sớm là những nguồn lực ngầm về tài chính, mối quan hệ hoặc xuất phát điểm vượt trội. Tất nhiên vẫn sẽ tồn tại vài trường hợp xuất chúng, nhưng tỷ lệ là dưới 1%. Bạn cảm giác ghen tị với thành công của họ. Nhưng hành động của bạn là dành hàng giờ đồng hồ mỗi ngày chỉ để tiêu thụ nội dung và tiếp tục than vãn về cuộc sống hiện tại. Đợt rồi tôi có dịp được gặp lại những người bạn cũ thời cấp 3, cuộc trò chuyện đang rất vui vẻ thì đột nhiên có đứa bảo, "Chán quá tụi bây, tao làm ở chỗ đó mấy năm rồi mà chả thấy lên lương gì nhiều". Tôi mới hỏi lại nó là vậy công việc mày dạo này khó hơn trước à. Thì nó bảo, đâu vẫn thế thôi, mà tao làm được 4 năm rồi. Đoạn này tôi nghĩ thầm trong bụng thôi chứ17:T1616, ## Bước đi chập chững từ các công ty khởi nghiệp Tôi có nhiều năm làm việc với các công ty start up và may mắn được cọ xát với nhiều công nghệ mới, được nhúng tay khá sâu vào các dự án, như là trực tiếp sửa đổi / thiết kế lại hệ thống database của một ứng dụng đang chạy production và kết quả được cải thiện tương đối chỉ với vài kỹ năng cơ bản về Index và partitioning. Các bạn nghe mọi thứ như đang tiến triển rất tốt đúng không. Tuy nhiên, có một điều mà tôi băn khoăn mãi, nếu so thông số ở dạng tỷ lệ thì rất tốt, performance tăng nhanh hẳn 50%, nhưng tổng số users dùng các sản phẩm mà công ty tôi làm ra, dưới 1000 người. Hay 1 dự án blockchain, anh PM và Tech Lead của tôi luôn cố gắng tìm cách cải thiện cơ chế đồng thuận (consensus) để nâng cao tốc độ xử lý và có thể xử lý nhiều giao dịch hơn trong một giây; và cũng giống như dự án trước, số users sử dụng nền tảng của chúng tôi… không nhiều đến thế. Trong thâm tâm tôi luôn cảm thấy, việc nên ưu tiên trong giai đoạn này, là tập trung vào việc làm sao tăng được users, còn việc cải thiện performance trên một tập người dùng nhỏ, chỉ có giá trị trên mặt giấy tờ. Bản thân tôi cũng muốn ứng dụng của mình chạy mượt, đem lại trải nghiệm tốt cho người dùng chứ, nhưng mà một ứng dụng là công sức của một tập thể, có nhiều biến số mà tôi không thể kiểm soát được. Người dùng sản phẩm thì cạn dần, và khi doanh thu không đáp ứng được, kết quả là chả còn dự án nào tồn tại đến hiện tại. Khi dự án sập, tôi cảm giác như công sức trước đó của mình không mang lại nhiều ý nghĩa lắm ngoài việc hết tháng nhận tiền lương. ## Sự phát triển của AI và nhìn nhận thực tế của ngành Cùng với sự phát triển chóng mặt của AI, các kỹ năng tối ưu Database của tôi, thứ tôi luôn tự hào, giờ đây chỉ cần vài câu prompt, nó đã có thể hiểu rõ các liên kết trong database và đưa ra phương án tối ưu khá chính xác. Có 1 kỷ niệm khá vui mà AI tí nữa đã phá hỏng dự án lúc đó tôi đang làm, anh tech-lead hí hửng khoe với tôi là dùng AI đánh được index đầy đủ luôn, đến khi tôi check qua thì thấy 1 lỗi cực kỳ lớn, vì chỉ muốn tối ưu tốc độ đọc, AI đã tạo tới 7 index trên cùng một bảng. Tốc độ đọc nhanh hơn thật, nhưng giá phải trả là thời gian ghi bị chậm đi gấp 3–4 lần. Tôi vẫn rất ngưỡng mộ kiến thức của anh Tech Lead, tuy nhiên đâu có ai mà giỏi hết mọi mặt, cái mà tôi muốn nói ở đây là, do tôi có kiến thức về Database, tôi mới nhận ra vấn đề ở đó; để một ứng dụng được hình thành, thì cần nhiều kiến thức ở nhiều mảng, vậy câu hỏi là AI còn để lại ‘rác’ ở chỗ nào mà mình chưa nhận ra không, Đó chính là lúc nợ kỹ thuật (technical debt) xuất hiện. Một khi sự cố xảy ra mà không ai thật sự hiểu bản chất, đó sẽ là chuỗi ngày fix bug vô tận. Về ngách Software Engineer, cá nhân tôi thấy nhu cầu trên thị trường không còn nhiều nữa, vì bây giờ ai cũng có thể vibe code ra được một ứng dụng phục vụ được cho nhu cầu cá nhân của họ. Các kiến thức khó nhất khi làm software engineer là bảo mật, xử lý lượng đồng thời cao, hay tính nguyên tử của dữ liệu… bây giờ trở nên vô nghĩa khi họ chỉ dùng ứng dụng để phục vụ nhu cầu cá nhân, tôi đùa là họ có lưu trữ dữ liệu ở local storage đi chăng nữa cũng chả sao. ## Đi Tìm Bài Toán Ở Quy mô doanh nghiệp Khi tìm hiểu thì tôi biết được SAP vẫn tồn tại và giữ vị thế số 1 trong thị trường phần mềm quản trị doanh nghiệp (ERP) nhờ vào việc giải quyết bài toán phức tạp nhất của các tập đoàn lớn, kết nối, đồng bộ các quy trình vận hành, thứ mà tôi chưa được trải nghiệm ở các công ty start up trước đó. Các khách hàng đang sử dụng SAP là những cái tên mà nói ra ai cũng từng sử dụng sản phẩm của họ hoặc ít nhất là đã nghe qua: PepsiCo, Samsung, LG, Toyota,… vâng, rất nhiều công ty nằm trong S&P 500. Họ vẫn sẽ dùng SAP vì chi phí chuyển đổi hệ thống là cực kỳ khổng lồ. Làm việc với SAP, tôi không chỉ làm việc kỹ thuật khô khan, mà ở đấy tôi có cơ hội hiểu hơn về nghiệp vụ, về các quy trình chuẩn quốc tế tối ưu trong tài chính, chuỗi cung ứng, sản xuất đã được đóng gói sẵn, giúp các doanh nghiệp áp dụng ngay tiêu chuẩn của các tập đoàn hàng đầu thế giới. Đồng thời, nền tảng kỹ thuật trước đó giúp tôi tiếp thu domain mới rất nhanh: không mất nhiều thời gian để hiểu về CSDL HANA, CDS Views hay xây dựng ứng dụng chuẩn RESTful (RAP). [Đọc tiếp: Chương 2. Đặt nền móng →](/blog/sap-foundation) 18:T7c6,Bước đi chập chững từ các công ty khởi nghiệp Tôi có nhiều năm làm việc với các công ty start up và may mắn được cọ xát với nhiều công nghệ mới, được nhúng tay khá sâu vào các dự án, như là trực tiếp sửa đổi / thiết kế lại hệ thống database của một ứng dụng đang chạy production và kết quả được cải thiện tương đối chỉ với vài kỹ năng cơ bản về Index và partitioning. Các bạn nghe mọi thứ như đang tiến triển rất tốt đúng không. Tuy nhiên, có một điều mà tôi băn khoăn mãi, nếu so thông số ở dạng tỷ lệ thì rất tốt, performance tăng nhanh hẳn 50%, nhưng tổng số users dùng các sản phẩm mà công ty tôi làm ra, dưới 1000 người. Hay 1 dự án blockchain, anh PM và Tech Lead của tôi luôn cố gắng tìm cách cải thiện cơ chế đồng thuận (consensus) để nâng cao tốc độ xử lý và có thể xử lý nhiều giao dịch hơn trong một giây; và cũng giống như dự án trước, số users sử dụng nền tảng của chúng tôi… không nhiều đến thế. Trong thâm tâm tôi luôn cảm thấy, việc nên ưu tiên trong giai đoạn này, là tập trung vào việc làm sao tăng được users, còn việc cải thiện performance trên một tập người dùng nhỏ, chỉ có giá trị trên mặt giấy tờ. Bản thân tôi cũng muốn ứng dụng của mình chạy mượt, đem lại trải nghiệm tốt cho người dùng chứ, nhưng mà một ứng dụng là công sức của một tập thể, có nhiều biến số mà tôi không thể kiểm soát được. Người dùng sản phẩm thì cạn dần, và khi doanh thu không đáp ứng được, kết quả là chả còn dự án nào tồn tại đến hiện tại. Khi dự án sập, tôi cảm giác như công sức trước đó của mình không19:T205d, ## Tư duy và phương pháp dẫn đường Một hành trình hiệu quả không thể bắt đầu bằng sự cảm tính. Đề hành trình học tập của tôi trở nên rõ ràng và hiệu quả, không thể một mình tay không bắt giặc được, thứ tôi cần là một kế hoạch, một phương pháp và tư duy học tập đúng đắn. Tất nhiên là tôi sẽ không kỳ vọng mình sẽ đi đúng hướng ngay từ ban đầu. Tuy nhiên, tôi sẽ không cải thiện được nhiều nếu không có một thước đo thật sự là rõ ràng. ### Sử dụng lợi thế từ những gì sẵn có: Áp dụng tư duy của một Software Engineer, tôi biến việc học thành một "pipeline" tự động. Thay vì đọc hàng trăm tài liệu khô khan và cực khó nuốt. Tôi dùng AI để tóm tắt các khái niệm cốt lõi, phân tích từ các case study và tạo kịch bản thực hành các tình huống. Hệ thống cũng tạo ra các tài liệu dành cho việc ôn tập, tạo ra câu hỏi bắt buộc não phải chủ động truy xuất kiến thức, đánh giá lại hiệu quả và nhắc nhở ôn tập theo chu kỳ thời gian tối ưu. Bắt chước thay vì cố gắng sáng tạo ra một cái gì mới. Bây giờ trên Github có sẵn nhiều example mà tôi có thể làm theo, trước khi sáng tạo ra cái của riêng mình thì tôi phải trải qua giai đoạn học, hiểu, có thể giải thích và làm theo đã. ### Chiến lược thực chiến để sẵn sàng cho dự án Chấp nhận sự mơ hồ ban đầu, không hoảng sợ trước những thiết lập phức tạp hay lỗi hệ thống ban đầu; học cách sống chung và gỡ rối từng bước. Thay vì học vẹt các Transaction codes hay ý nghĩa từng fields trong bảng, tôi tiếp cận bằng cách luồng nghiệp vụ vào bài toán, phân tích một chuỗi End-to-End gồm những bước gì và triển khai hệ thống ra sao. **Quy tắc 80/20:** Thay vì cố gắng hiểu hết mọi thứ, tôi sẽ tập trung làm chủ 20% kiến thức nền tảng, nền móng vững chắc sẽ giúp tôi tự tin và có thể dễ dàng hơn trong việc tìm hiểu một kiến thức mới nằm trong 80% còn lại. Lý thuyết suông chỉ mang lại cảm giác hiểu giả tạo. Chả ai biết cách đi xe máy bằng cách xem Youtube cả. Việc bắt tay vào làm trực tiếp, hệ thống báo lỗi và tự tra cứu lỗi để sửa. Tôi đặt niềm tin tuyệt đối vào vòng lặp: Làm → Sửa sai → Cải thiện. Đây là con đường ngắn nhất để thẩm thấu kiến thức. Đối với SAP, thời gian đầu tôi sẽ tìm hiểu các syntax của ABAP, những tư duy, khác biệt so với ngôn ngữ lập trình khác, khi đã nắm được cách nó hoạt động, tôi sẽ dần chuyển mình sang học những concept, chương trình mới hơn như là RAP. ## Kiến trúc hệ thống: Giải mã ERP và các mảnh ghép trong SAP ### Về khái niệm ERP: Trong một doanh nghiệp tồn tại rất nhiều phòng ban làm việc với nhau. Mỗi phòng ban sử dụng một phần mềm riêng lẻ như bộ phận kho bãi dùng Excel để ghi chép, bộ phận bán hàng dùng một phần mềm CRM độc lập. Điều này dẫn đến việc dữ liệu bị phân tán, và mất nhiều thời gian, công sức đối soát để đảm bảo tính đúng đắn. _ERP (Enterprise Resource Planning - hệ thống quản trị_ nguồn lực doanh nghiệp). Đây là khái niệm chỉ rõ phần mềm vận hành, quản lý doanh nghiệp, đóng vai trò là một bộ não trung tâm, thu gom, chia sẻ dữ liệu tập trung trên một hệ thống duy nhất. Đảm bảo tính đồng nhất và chuẩn hoá dữ liệu giữa nhiều bộ phận trong cùng một doanh nghiệp. ### SAP - cái tên nổi bật nhất thế giới ERP ERP là tên gọi chung cho dòng giải pháp của doanh nghiệp, **SAP** (Systems, Applications, and Products in Data Processing) là đại diện lớn nhất trong thị trường này. Công ty Đức được thành lập 1972 và là một trong những công ty phần mềm lớn nhất thế giới. Sức mạnh của SAP không chỉ nằm ở công cụ phần mềm, mà là các quy chuẩn đã được đúc kết từ hàng vạn doanh nghiệp lớn nhất thế giới. Điểm đặc trưng của SAP là **tính chặt chẽ và tích hợp cực cao**: Mọi hành động diễn ra ở một khâu đều kéo theo các bút toán hoặc luồng dữ liệu tự động ở các khâu khác, giúp doanh nghiệp kiểm soát rủi ro gần như tuyệt đối. ### Các mảnh ghép cốt lõi: Hệ sinh thái Module trong SAP Để quản lý toàn bộ một tập đoàn phức tạp, SAP chia nhỏ hệ thống thành các **Module (Phân hệ)** đảm nhận từng nghiệp vụ chuyên biệt, nhưng tất cả đều kết nối khăng khít với nhau: ### Quản trị Tài chính & Kiểm soát (Finance & Controlling): - **FI (Financial Accounting):** Quản lý sổ cái, công nợ phải thu/phải trả, tài sản cố định và lập báo cáo tài chính chuẩn mực. - **CO (Controlling):** Quản lý chi phí nội bộ, tính giá thành sản phẩm và phân tích lợi nhuận. ### Chuỗi cung ứng & Vận hành (Supply Chain & Logistics): - **MM (Materials Management):** Quản lý Mua hàng (Procurement), định mức tồn kho và Nhập/Xuất/Kiểm kê Kho. - **SD (Sales and Distribution):** Quản lý Bán hàng, từ báo giá, đơn đặt hàng (Sales Order), giao hàng đến xuất hóa đơn cho khách. **PP (Production Planning):** Quản lý lập kế hoạch và điều độ sản xuất, định mức nguyên vật liệu (BOM). ### Quản lý Tài sản & Chất lượng (Asset & Quality): - **PM (Plant Maintenance):** Quản lý bảo trì, bảo dưỡng máy móc thiết bị nhà xưởng. - **QM (Quality Management):** Kiểm tra và quản lý chất lượng nguyên vật liệu đầu vào cũng như thành phẩm. ### Quản trị Nhân sự (Human Capital Management): - **HCM / SuccessFactors:** Quản lý sơ đồ tổ chức, chấm công, tính lương và tuyển dụng/đào tạo. ### Tập trung vào một mũi nhọn: tôi chọn bắt đầu SD Một lý do đơn giản khiến tôi chọn SD là vì tôi thấy nó gần gũi và những khái niệm khá gần với thực tế. Ai trong chúng ta cũng từng đóng vai là người mua hàng hoặc từng bán một cái gì đó (là sản phẩm hay kể cả là sức lao động). SD không đơn thuần là phân hệ quản lý bán hàng, mà nó chính là doanh thu của toàn bộ doanh nghiệp, nơi kết nối trực tiếp với thị trường, khách hàng và dòng tiền. Phân hệ này gồm nghiệp vụ end-to-end cực kỳ sống động vì nó bao phủ trọn vẹn hành trình từ báo giá đến khâu xuất hoá đơn, và cũng dễ mở rộng khi đây là điểm giao thao cực mạnh với các phân hệ khác: làm việc với MM ở quản lý tồn kho hay FI ngay thời điểm hóa đơn doanh thu được ghi nhận. **Định hướng chặng đường** Khép lại những trang lý thuyết ban đầu. Tôi nhận ra SAP không chỉ là một phần mềm khô khan, nó chính là xương sống vận hành, dòng chảy kết nối các nguồn lực giúp một doanh nghiệp tồn tại và vận hành trơn tru. Để làm chủ một hệ thống đồ sộ như SAP, không có lối tắt nào ngoài việc bắt đầu từ những bước đi nhỏ nhất. Hiểu một phần tư duy nghiệp vụ chỉ là bước đầu, hành trình tiếp theo sẽ là trực tiếp thao tác trên hệ thống, tôi sẽ bắt đầu bằng việc khám phá các kỹ thuật cơ bản trong SAP ABAP. [Đọc tiếp: Chương 3. Hiểu rõ hơn về các khái niệm trong SAP →](/blog/sap-concepts) 1a:T7c1,Tư duy và phương pháp dẫn đường Một hành trình hiệu quả không thể bắt đầu bằng sự cảm tính. Đề hành trình học tập của tôi trở nên rõ ràng và hiệu quả, không thể một mình tay không bắt giặc được, thứ tôi cần là một kế hoạch, một phương pháp và tư duy học tập đúng đắn. Tất nhiên là tôi sẽ không kỳ vọng mình sẽ đi đúng hướng ngay từ ban đầu. Tuy nhiên, tôi sẽ không cải thiện được nhiều nếu không có một thước đo thật sự là rõ ràng. Sử dụng lợi thế từ những gì sẵn có: Áp dụng tư duy của một Software Engineer, tôi biến việc học thành một "pipeline" tự động. Thay vì đọc hàng trăm tài liệu khô khan và cực khó nuốt. Tôi dùng AI để tóm tắt các khái niệm cốt lõi, phân tích từ các case study và tạo kịch bản thực hành các tình huống. Hệ thống cũng tạo ra các tài liệu dành cho việc ôn tập, tạo ra câu hỏi bắt buộc não phải chủ động truy xuất kiến thức, đánh giá lại hiệu quả và nhắc nhở ôn tập theo chu kỳ thời gian tối ưu. Bắt chước thay vì cố gắng sáng tạo ra một cái gì mới. Bây giờ trên Github có sẵn nhiều example mà tôi có thể làm theo, trước khi sáng tạo ra cái của riêng mình thì tôi phải trải qua giai đoạn học, hiểu, có thể giải thích và làm theo đã. Chiến lược thực chiến để sẵn sàng cho dự án Chấp nhận sự mơ hồ ban đầu, không hoảng sợ trước những thiết lập phức tạp hay lỗi hệ thống ban đầu; học cách sống chung và gỡ rối từng bước. Thay vì học vẹt các Transaction codes hay ý nghĩa từng fields trong bảng, tôi tiếp cận bằng cách luồng nghiệp vụ vào bài toán, phân tích một chuỗi End-to-End1b:T713,## Tư duy và phương pháp dẫn đường Một hành trình hiệu quả không thể bắt đầu bằng sự cảm tính. Đề hành trình học tập của tôi trở nên rõ ràng và hiệu quả, không thể một mình tay không bắt giặc được, thứ tôi cần là một kế hoạch, một phương pháp và tư duy học tập đúng đắn. Tất nhiên là tôi sẽ không kỳ vọng mình sẽ đi đúng hướng ngay từ ban đầu. Tuy nhiên, tôi sẽ không cải thiện được nhiều nếu không có một thước đo thật sự là rõ ràng. ### Sử dụng lợi thế từ những gì sẵn có: Áp dụng tư duy của một Software Engineer, tôi biến việc học thành một "pipeline" tự động. Thay vì đọc hàng trăm tài liệu khô khan và cực khó nuốt. Tôi dùng AI để tóm tắt các khái niệm cốt lõi, phân tích từ các case study và tạo kịch bản thực hành các tình huống. Hệ thống cũng tạo ra các tài liệu dành cho việc ôn tập, tạo ra câu hỏi bắt buộc não phải chủ động truy xuất kiến thức, đánh giá lại hiệu quả và nhắc nhở ôn tập theo chu kỳ thời gian tối ưu. Bắt chước thay vì cố gắng sáng tạo ra một cái gì mới. Bây giờ trên Github có sẵn nhiều example mà tôi có thể làm theo, trước khi sáng tạo ra cái của riêng mình thì tôi phải trải qua giai đoạn học, hiểu, có thể giải thích và làm theo đã. ### Chiến lược thực chiến để sẵn sàng cho dự án Chấp nhận sự mơ hồ ban đầu, không hoảng sợ trước những thiết lập phức tạp hay lỗi hệ thống ban đầu; học cách sống chung và gỡ rối từng bước.1c:T112d, ## Các tính năng nội bật của SAP - **Tính tích hợp (Integration):** Cho phép tất cả các phòng ban/chức năng dùng chung một hệ thống và chia sẻ chung dữ liệu. - **Đa ngôn ngữ (Multilingual):** Hỗ trợ hơn 40 ngôn ngữ (Anh, Đức, Thái, Trung...) giúp xóa bỏ rào cản ngôn ngữ. - **Cơ chế cấp phép dựa trên người dùng (User-based License Agreement):** Bắt buộc phải có tài khoản (Username/Password) được xác thực từ SAP Server mới có thể đăng nhập, giúp bảo mật dữ liệu và phân quyền chặt chẽ. ## Nền tảng công nghệ, ngôn ngữ & phân hệ - **SAP NetWeaver:** Là nền tảng công nghệ đóng vai trò như môi trường thực thi (_Runtime Environment_) cho toàn bộ hệ sinh thái ứng dụng của SAP (như SAP ERP, SAP CRM, SAP SRM, SAP PI). - **Ngôn ngữ ABAP:** Viết tắt của _Advanced Business Application Programming_ (hiện phổ biến là thế hệ thứ 4 - ABAP/4). Đây là ngôn ngữ lập trình riêng của SAP, nằm tại tầng Application Layer. - **Các phân hệ (Modules) trong SAP:** - _Functional Modules (Phân hệ nghiệp vụ):_ Gồm các module con như **SD** (Bán hàng & Phân phối), **MM** (Quản lý vật tư), **FI** (Tài chính).... - _Technical Modules (Phân hệ kỹ thuật):_ Gồm **SAP ABAP** (Lập trình), **SAP BI/BO** (Phục vụ làm báo cáo) và **SAP Basis**. - _SAP Basis:_ Đảm nhận vai trò quản trị, giám sát hệ thống 24/7, duy trì hệ thống không bị sự cố/crash và quản lý cấp quyền (User ID, password) ## Kiến trúc 3 lớp tổng quan (SAP R/3 Architecture) ![[../images/3-architecture.png]] 1. **Presentation Layer:** Tầng giao diện người dùng (tương tác trực tiếp qua SAP GUI). 2. **Application Layer:** Tầng ứng dụng/phát triển, chứa các chương trình lập trình bằng ABAP để xử lý logic. 3. **Database Layer:** Tầng cơ sở dữ liệu lưu trữ và truy xuất toàn bộ thông tin hệ thống. ![[../images/application-server-components.png]] 1. **Dispatcher (Bộ điều phối):** - Mọi yêu cầu (_input request_) gửi từ người dùng ở tầng Presentation Layer đều sẽ đi vào **Dispatcher** đầu tiên. - Dispatcher không trực tiếp xử lý ngay request mà đẩy toàn bộ vào một hàng chờ (**Queue**). 2. **Queue (Hàng chờ):** - Lưu giữ các request và sắp xếp thứ tự xử lý theo cơ chế **FIFO** (_First-In, First-Out_ - yêu cầu nào đến trước sẽ được lấy ra xử lý trước). 3. **Work Process (Tiến trình xử lý):** - Dispatcher sẽ lấy từng request từ Queue ra và gán cho một **Work Process** để thực thi. - **Nguyên tắc đơn nhiệm:** Một Work Process chỉ xử lý **duy nhất 1 request tại một thời điểm**. Nếu có nhiều yêu cầu, hệ thống phải xếp hàng xử lý tuần tự (đây là lý do khiến màn hình SAP GUI đôi khi bị xoay/loading lâu khi gặp chương trình nặng). 4. **Hai vùng bộ nhớ đệm quan trọng trong Work Process:** - **User Context:** Là vùng bộ nhớ đệm lưu trữ thông tin về người dùng đang làm việc (User ID, mật khẩu, thời gian đăng nhập, chương trình đang chạy, số lượng cửa sổ đang mở). Vùng bộ nhớ này chỉ tự động giải phóng khi người dùng **Thoát/Log out** khỏi tài khoản SAP. - **Roll Area:** Là vùng bộ nhớ đệm nhỏ dành riêng cho việc thực thi chương trình. Khi chương trình ABAP bắt đầu chạy, Roll Area được cấp phát để lưu trữ dữ liệu tính toán tạm thời và sẽ **giải phóng ngay lập tức** khi chương trình kết thúc. ### Quy trình xử lý hoàn chỉnh của một Request: **Presentation Layer** _(Gửi request)_ $\rightarrow$ **Dispatcher** $\rightarrow$ **Queue (FIFO)** $\rightarrow$ **Work Process** _(Xử lý kết hợp với_ **User Context** _&_ **Roll Area**_)_ $\leftrightarrow$ **Database Layer** _(Truy xuất/Lưu data)_ $\rightarrow$ Trả kết quả ngược lại **Presentation Layer** [Đọc tiếp: Chương 4. ABAP Fundamentals: Bước Chân Vào Tầng Xử Lý Logic →](/blog/sap-abap) 1d:T843,Các tính năng nội bật của SAP - Tính tích hợp (Integration): Cho phép tất cả các phòng ban/chức năng dùng chung một hệ thống và chia sẻ chung dữ liệu. - Đa ngôn ngữ (Multilingual): Hỗ trợ hơn 40 ngôn ngữ (Anh, Đức, Thái, Trung...) giúp xóa bỏ rào cản ngôn ngữ. - Cơ chế cấp phép dựa trên người dùng (User-based License Agreement): Bắt buộc phải có tài khoản (Username/Password) được xác thực từ SAP Server mới có thể đăng nhập, giúp bảo mật dữ liệu và phân quyền chặt chẽ. Nền tảng công nghệ, ngôn ngữ & phân hệ - SAP NetWeaver: Là nền tảng công nghệ đóng vai trò như môi trường thực thi (Runtime Environment) cho toàn bộ hệ sinh thái ứng dụng của SAP (như SAP ERP, SAP CRM, SAP SRM, SAP PI). - Ngôn ngữ ABAP: Viết tắt của Advanced Business Application Programming (hiện phổ biến là thế hệ thứ 4 - ABAP/4). Đây là ngôn ngữ lập trình riêng của SAP, nằm tại tầng Application Layer. - Các phân hệ (Modules) trong SAP: - Functional Modules (Phân hệ nghiệp vụ): Gồm các module con như SD (Bán hàng & Phân phối), MM (Quản lý vật tư), FI (Tài chính).... - Technical Modules (Phân hệ kỹ thuật): Gồm SAP ABAP (Lập trình), SAP BI/BO (Phục vụ làm báo cáo) và SAP Basis. - SAP Basis: Đảm nhận vai trò quản trị, giám sát hệ thống 24/7, duy trì hệ thống không bị sự cố/crash và quản lý cấp quyền (User ID, password) Kiến trúc 3 lớp tổng quan (SAP R/3 Architecture) ![[../images/3-architecture.png]] 1. Presentation Layer: Tầng giao diện người dùng (tương tác trực tiếp qua SAP GUI). 2. Application Layer: Tầng ứng dụng/phát triển, chứa các chương trình lập trình bằng ABAP để xử lý logic. 3. Database Layer: Tầng cơ sở dữ liệu lưu trữ và truy xuất toàn bộ thông tin hệ thống. ![[../images/application-server-components.png]] 1. Dispatcher (Bộ điều phối): - Mọi1e:T872,## Các tính năng nội bật của SAP - **Tính tích hợp (Integration):** Cho phép tất cả các phòng ban/chức năng dùng chung một hệ thống và chia sẻ chung dữ liệu. - **Đa ngôn ngữ (Multilingual):** Hỗ trợ hơn 40 ngôn ngữ (Anh, Đức, Thái, Trung...) giúp xóa bỏ rào cản ngôn ngữ. - **Cơ chế cấp phép dựa trên người dùng (User-based License Agreement):** Bắt buộc phải có tài khoản (Username/Password) được xác thực từ SAP Server mới có thể đăng nhập, giúp bảo mật dữ liệu và phân quyền chặt chẽ. ## Nền tảng công nghệ, ngôn ngữ & phân hệ - **SAP NetWeaver:** Là nền tảng công nghệ đóng vai trò như môi trường thực thi (_Runtime Environment_) cho toàn bộ hệ sinh thái ứng dụng của SAP (như SAP ERP, SAP CRM, SAP SRM, SAP PI). - **Ngôn ngữ ABAP:** Viết tắt của _Advanced Business Application Programming_ (hiện phổ biến là thế hệ thứ 4 - ABAP/4). Đây là ngôn ngữ lập trình riêng của SAP, nằm tại tầng Application Layer. - **Các phân hệ (Modules) trong SAP:** - _Functional Modules (Phân hệ nghiệp vụ):_ Gồm các module con như **SD** (Bán hàng & Phân phối), **MM** (Quản lý vật tư), **FI** (Tài chính).... - _Technical Modules (Phân hệ kỹ thuật):_ Gồm **SAP ABAP** (Lập trình), **SAP BI/BO** (Phục vụ làm báo cáo) và **SAP Basis**. - _SAP Basis:_ Đảm nhận vai trò quản trị, giám sát hệ thống 24/7, duy trì hệ thống không bị sự cố/crash và quản lý cấp quyền (User ID, password) ## Kiến trúc 3 lớp tổng quan (SAP R/3 Architecture) ![[../images/3-architecture.png]] 1. **Presentation Layer:** Tầng giao diện người dùng (tương tác trực tiếp qua SAP GUI). 2. **Application Layer:** Tầng ứng dụng/phát triển, chứa các chương trình lập trình bằng ABAP để xử lý logic. 3. **Database Layer:** Tầng cơ sở dữ liệu lưu trữ và truy xuất toàn bộ thông tin hệ thống. ![[../images/application-server-components.png]]1f:T783, Hiện tại SAP đang đẩy mạnh xu hướng hiện đại hóa với nền tảng Cloud, kiến trúc RESTful (RAP) và các ngôn ngữ như JavaScript, nhưng việc học ABAP ở thời điểm hiện tại vẫn còn nguyên giá trị. Đây là ngôn ngữ gốc ở tầng Core Backend trong SAP, các logic nghiệp vụ phức tạp trong hệ thống đều đã được viết và tối ưu bằng ABAP qua nhiều năm. Để tuỳ biến, vận hành hay mở rộng tính năng cho hệ thống, việc đọc hiểu các codebase cũ là không thể bỏ qua. Việc đập đi làm lại hoặc chuyển toàn bộ code lõi sang ngôn ngữ khác là bài toán vô cùng rủi ro và tốn kém hàng triệu USD. Do đó, nhu cầu duy trì, chuyển đổi hệ thống cũ (Legacy) sang SAP S/4HANA vẫn tạo ra nguồn cầu nhân lực ABAP cực kỳ ổn định. Về tài liệu chính thức, các bạn có thể xem tài liệu gốc của SAP: https://learning.sap.com/courses/learn-the-basics-of-abap-programming-on-sap-btp/introducing-abap-syntax_b815682e-9a5e-4372-a021-66ea71208746 Ở bài viết này, tôi sẽ viết như một bảng tổng hợp nhanh lại kiến thức. ### ABAP Basic Statements [Đọc tiếp: ABAP Basic Statements →](/blog/sap-abap-1) ### ABAP Data Dictionary [Đọc tiếp: ABAP Data Dictionary →](/blog/sap-abap-2) ### ABAP Open SQL [Đọc tiếp: ABAP Open SQL →](/blog/sap-abap-3) ### ABAP Internal Table [Đọc tiếp: ABAP Internal Table →](/blog/sap-abap-4) ### ABAP Modularization [Đọc tiếp: ABAP Modularization →](/blog/sap-abap-5) ### ABAP Classical Report [Đọc tiếp: ABAP Classical Report →](/blog/sap-abap-6) ### ABAP ALV Report [Đọc tiếp: ABAP ALV Report →](/blog/sap-abap-7) ### Đi sâu vào bài toán thực tế - SD Module [Đọc tiếp: Chương 5. SD Module →](/blog/sap-sd) 20:T6b3,Hiện tại SAP đang đẩy mạnh xu hướng hiện đại hóa với nền tảng Cloud, kiến trúc RESTful (RAP) và các ngôn ngữ như JavaScript, nhưng việc học ABAP ở thời điểm hiện tại vẫn còn nguyên giá trị. Đây là ngôn ngữ gốc ở tầng Core Backend trong SAP, các logic nghiệp vụ phức tạp trong hệ thống đều đã được viết và tối ưu bằng ABAP qua nhiều năm. Để tuỳ biến, vận hành hay mở rộng tính năng cho hệ thống, việc đọc hiểu các codebase cũ là không thể bỏ qua. Việc đập đi làm lại hoặc chuyển toàn bộ code lõi sang ngôn ngữ khác là bài toán vô cùng rủi ro và tốn kém hàng triệu USD. Do đó, nhu cầu duy trì, chuyển đổi hệ thống cũ (Legacy) sang SAP S/4HANA vẫn tạo ra nguồn cầu nhân lực ABAP cực kỳ ổn định. Về tài liệu chính thức, các bạn có thể xem tài liệu gốc của SAP: https://learning.sap.com/courses/learn-the-basics-of-abap-programming-on-sap-btp/introducing-abap-syntaxb815682e-9a5e-4372-a021-66ea71208746 Ở bài viết này, tôi sẽ viết như một bảng tổng hợp nhanh lại kiến thức. ABAP Basic Statements Đọc tiếp: ABAP Basic Statements → ABAP Data Dictionary Đọc tiếp: ABAP Data Dictionary → ABAP Open SQL Đọc tiếp: ABAP Open SQL → ABAP Internal Table Đọc tiếp: ABAP Internal Table → ABAP Modularization Đọc tiếp: ABAP Modularization → ABAP Classical Report Đọc tiếp: ABAP Classical Report → ABAP ALV Report Đọc tiếp: ABAP ALV Report → Đi sâu vào bài toán thực tế - SD Module Đọc tiếp: Chương 5. SD Module →21:T781,Hiện tại SAP đang đẩy mạnh xu hướng hiện đại hóa với nền tảng Cloud, kiến trúc RESTful (RAP) và các ngôn ngữ như JavaScript, nhưng việc học ABAP ở thời điểm hiện tại vẫn còn nguyên giá trị. Đây là ngôn ngữ gốc ở tầng Core Backend trong SAP, các logic nghiệp vụ phức tạp trong hệ thống đều đã được viết và tối ưu bằng ABAP qua nhiều năm. Để tuỳ biến, vận hành hay mở rộng tính năng cho hệ thống, việc đọc hiểu các codebase cũ là không thể bỏ qua. Việc đập đi làm lại hoặc chuyển toàn bộ code lõi sang ngôn ngữ khác là bài toán vô cùng rủi ro và tốn kém hàng triệu USD. Do đó, nhu cầu duy trì, chuyển đổi hệ thống cũ (Legacy) sang SAP S/4HANA vẫn tạo ra nguồn cầu nhân lực ABAP cực kỳ ổn định. Về tài liệu chính thức, các bạn có thể xem tài liệu gốc của SAP: https://learning.sap.com/courses/learn-the-basics-of-abap-programming-on-sap-btp/introducing-abap-syntax_b815682e-9a5e-4372-a021-66ea71208746 Ở bài viết này, tôi sẽ viết như một bảng tổng hợp nhanh lại kiến thức. ### ABAP Basic Statements [Đọc tiếp: ABAP Basic Statements →](/blog/sap-abap-1) ### ABAP Data Dictionary [Đọc tiếp: ABAP Data Dictionary →](/blog/sap-abap-2) ### ABAP Open SQL [Đọc tiếp: ABAP Open SQL →](/blog/sap-abap-3) ### ABAP Internal Table [Đọc tiếp: ABAP Internal Table →](/blog/sap-abap-4) ### ABAP Modularization [Đọc tiếp: ABAP Modularization →](/blog/sap-abap-5) ### ABAP Classical Report [Đọc tiếp: ABAP Classical Report →](/blog/sap-abap-6) ### ABAP ALV Report [Đọc tiếp: ABAP ALV Report →](/blog/sap-abap-7) ### Đi sâu vào bài toán thực tế - SD Module [Đọc tiếp: Chương 5. SD Module →](/blog/sap-sd)22:T196f, ## ABAP Basic Statements ### 1. Basic Syntax Rules & Comments - **Statement Termination**: Every ABAP statement must end with a **period (\*\***.\***\*)**. A statement can span across multiple lines until a period is encountered. - **Case Insensitivity**: ABAP code is case-insensitive; keywords, additions, and operands can be written in uppercase or lowercase. - **Comments**: - An **asterisk** (\*) at the very first position of a line comments out the entire line. - A **double quote (\*\***"\***\*)** comments out everything from that position to the end of the line. - **Chained Statements**: Multiple statements repeating the same keyword can be chained using a **colon (\*\***:\***\*)** and separated by **commas (\*\***,\***\*)** (e.g., `WRITE: var1, var2.`). --- ### 2. Data Objects & Type Declarations - **Data Objects**: ABAP distinguishes between **Variables** (`DATA`), **Constants** (`CONSTANTS`), and **Literals** (text in `'...'`, string in `` `...` ``, or numbers). - **Variable Declaration**: Declared using `DATA TYPE ` with an optional `VALUE` addition. To copy the type of an existing data object, use `LIKE`. - **Local vs. Global Types**: - **Local Data Types** (`TYPES`): Defined locally within a program. If a local type shares the same name as a global type, the local definition takes **precedence**. - **Global Data Types**: Created and managed system-wide via the **ABAP Dictionary** (transaction code `SE11`). - **Predefined Data Types**: - **Complete Data Types** (fixed length): `D` (Date - 8 characters `YYYYMMDD`), `T` (Time - 6 characters `HHMMSS`), `I` (Integer - 4 bytes, range -2^31 to +2^31), `STRING` (dynamic character string). - **Incomplete Data Types** (length required): `C` (Character), `N` (Numeric text), and `P` (Packed number - used for calculations/currencies with `DECIMALS` specification). - **Internal Tables**: Declared using `DATA TYPE TABLE OF ` to hold lists of structured data. --- ### 3. Coding Convension - **Custom Type**: GT*, GTS*, GTT\_ - **Constant**: GC\_ - **Global variables**: GD\_ - **Work Area (Structure)**: GS\_ - **Internal Table**: GT\_ - **Local variables**: LD\_ - **Local work area**: LS\_ - **Local internal table**: LT\_ - **Selection-screen Parameter**: P\_ - **Selection-screen Select-option**: S\_ - **Selection-screen Radio Button**: RB\_ - **Selection-screen Checkbox**: CB\_ - **Subroutines (Procedure)**: GET_DATA, SET_DATA - **Global class**: ZCL, YCL - **Local class**: LCL - **Class instance (object)**: O, LO - **Class methods**: GET_DATA, SET_DATA - **Class attributes**: no prefix --- ### 4. Control Structures & Loops - **Conditional Branching (IF)**: Implemented using `IF ... ELSEIF ... ELSE ... ENDIF`. - **Multi-way Branching (CASE)**: Implemented using `CASE WHEN ... WHEN OTHERS ... ENDCASE`. Each `WHEN` branch operates independently and exits automatically without requiring a `BREAK` statement. - **Logical Operators & Initial Check**: Conditions can be combined using `AND`, `OR`, `NOT`, and parenthetical grouping `()`. Use `IS INITIAL` to check if a variable holds its initial/uninitialized default value. - **Loops (DO / WHILE)**: Unconditional/conditional looping via `DO ... ENDDO` or `WHILE ... ENDWHILE`, exited using the `EXIT` statement. - **Internal Table Loop (LOOP AT)**: Iterates through internal tables via `LOOP AT INTO [WHERE ] ... ENDLOOP`. Supports pattern matching such as `CP` (Contains Pattern with wildcard `*`) or `CF`. --- ### 5. Output & Screen Formatting - **Output Command (WRITE)**: In classical report programs, `WRITE ` outputs data to the list screen. Advanced formatting uses `WRITE /() ` to specify newlines (`/`), starting position, and display length. - **Spacing & Dividers**: `SKIP ` skips blank lines, and `ULINE` draws horizontal divider lines. - **Multilingual Labels (Text Symbols)**: Avoid hardcoding text strings; use **Text Symbols** (`TEXT-xxx` or `text-001`) so labels can be translated into multiple system languages. --- ### 6. Message Handling - **Displaying Messages**: Triggered using `MESSAGE TYPE `. Message types include `S` (Success), `I` (Information), `W` (Warning), `E` (Error), `A` (Abort), and `X` (Exit / Exception). - **Message Class (SE91)**: Manages centralized messages and supports passing up to 4 dynamic parameters (`WITH var1 var2 var3 var4`) into placeholders (`&1` through `&4`). --- ### 7. Selection Screens & User Inputs - **Single Parameters (PARAMETERS)**: Generates single input fields (parameter names are limited to 8 characters). Additions include `OBLIGATORY` (mandatory field) and `DEFAULT `. - **Range Selection (SELECT-OPTIONS)**: Creates a range input control (`FROM` ... `TO`) using `SELECT-OPTIONS FOR `. - **Screen Blocks**: Encloses parameters in visual frames using `SELECTION-SCREEN BEGIN OF BLOCK WITH FRAME TITLE ... END OF BLOCK`. --- ### 8. Program Events in Report Programs - **INITIALIZATION**: Executes first when opening a report program, used for initializing defaults. - **AT SELECTION-SCREEN**: Triggers when user interacts with or submits the selection screen, ideal for input validation. - **START-OF-SELECTION**: Kicks off upon pressing Execute (**F8**), containing core business processing and data queries. --- ### 9. Operations, Date/Time Arithmetic & System Variables - **Arithmetic Operations**: Uses standard operators (`+`, `-`, `*`, `/`), integer division (`DIV`), modulo (`MOD`), and square root (`SQRT`). - **Date (D) & Time (T) Calculations**: Automatically calculates date/time rollovers (e.g., adding 1 day to `20231231` yields `20240101`). Substring offset access uses `<var>+<offset>(<length>)`. - **Key System Variables (sy-)**: - `sy-subrc`: Return code of the previous statement (`0` = success, non-zero e.g., `4` = failure). - `sy-tabix`: Current line index inside an internal table loop (`LOOP AT`). - `sy-datum`: Current system date. - `sy-uzeit`: Current system time. - `sy-uname`: Logged-in user name. - `sy-langu`: Logged-in language. - `sy-tcode`: Current transaction code. - `sy-repid`: Current program ID. --- ### 10. Debugging Capabilities - **ABAP Debugger**: Allows setting breakpoints to step line-by-line (using **F6** to step over, **F8** to continue) to monitor real-time data transformations and diagnose runtime dumps or logic errors. 23:T800,ABAP Basic Statements 1. Basic Syntax Rules & Comments - Statement Termination: Every ABAP statement must end with a period (\\.\\). A statement can span across multiple lines until a period is encountered. - Case Insensitivity: ABAP code is case-insensitive; keywords, additions, and operands can be written in uppercase or lowercase. - Comments: - An asterisk (\) at the very first position of a line comments out the entire line. - A double quote (\\"\\) comments out everything from that position to the end of the line. - Chained Statements: Multiple statements repeating the same keyword can be chained using a colon (\\:\\) and separated by commas (\\,\\) (e.g., WRITE: var1, var2.). --- 2. Data Objects & Type Declarations - Data Objects: ABAP distinguishes between Variables (DATA), Constants (CONSTANTS), and Literals (text in '...', string in ... , or numbers). - Variable Declaration: Declared using DATA <variablename TYPE <datatype with an optional VALUE addition. To copy the type of an existing data object, use LIKE. - Local vs. Global Types: - Local Data Types (TYPES): Defined locally within a program. If a local type shares the same name as a global type, the local definition takes precedence. - Global Data Types: Created and managed system-wide via the ABAP Dictionary (transaction code SE11). - Predefined Data Types: - Complete Data Types (fixed length): D (Date - 8 characters YYYYMMDD), T (Time - 6 characters HHMMSS), I (Integer - 4 bytes, range -2^31 to +2^31), STRING (dynamic character string). - Incomplete Data Types (length required): C (Character), N (Numeric text), and P (Packed number - used for calculations/currencies with DECIMALS specification). - Internal Tables: Declared using DATA <tablename TYPE TABLE OF <linetype to hold lists of structured data. --- 3. Coding Convension - Custom Type: GT, GTS, GTT\ - Constant: GC\ - Global variables: GD\ - Work Area (Structure): GS\ - Internal Table: GT\ - Local variables: LD\ - Local work area: LS\ - Local internal table: LT\ - Selection-screen Parameter: P\24:T7f3,## ABAP Basic Statements ### 1. Basic Syntax Rules & Comments - **Statement Termination**: Every ABAP statement must end with a **period (\*\***.\***\*)**. A statement can span across multiple lines until a period is encountered. - **Case Insensitivity**: ABAP code is case-insensitive; keywords, additions, and operands can be written in uppercase or lowercase. - **Comments**: - An **asterisk** (\*) at the very first position of a line comments out the entire line. - A **double quote (\*\***"\***\*)** comments out everything from that position to the end of the line. - **Chained Statements**: Multiple statements repeating the same keyword can be chained using a **colon (\*\***:\***\*)** and separated by **commas (\*\***,\***\*)** (e.g., `WRITE: var1, var2.`). --- ### 2. Data Objects & Type Declarations - **Data Objects**: ABAP distinguishes between **Variables** (`DATA`), **Constants** (`CONSTANTS`), and **Literals** (text in `'...'`, string in `` `...` ``, or numbers). - **Variable Declaration**: Declared using `DATA <variable_name> TYPE <data_type>` with an optional `VALUE` addition. To copy the type of an existing data object, use `LIKE`. - **Local vs. Global Types**: - **Local Data Types** (`TYPES`): Defined locally within a program. If a local type shares the same name as a global type, the local definition takes **precedence**. - **Global Data Types**: Created and managed system-wide via the **ABAP Dictionary** (transaction code `SE11`). - **Predefined Data Types**: - **Complete Data Types** (fixed length): `D` (Date - 8 characters `YYYYMMDD`), `T` (Time - 6 characters `HHMMSS`), `I` (Integer - 4 bytes, range -2^31 to +2^31), `STRING` (dynamic character string). - **Incomplete Data Types** (length required): `C` (Character), `N` (Numeric text), and `P` (Packed number - used for calculations/currencies with `DECIMALS` specification). - **Internal Tables**: Declared using `DATA <table_name> TYPE TABLE OF <line_type>` to hold lists of structured data. --- ### 3. Coding Convension25:T22f5, ## 1. System Overview & Architecture The **ABAP Data Dictionary (DDIC)**, managed via Transaction Code **`SE11`**, is an integrated database management framework embedded within the SAP ABAP application server. It acts as a database abstraction layer positioned between SAP application programs and the underlying Relational Database Management System (RDBMS) such as Oracle or Microsoft SQL Server. ``` +-------------------------------------------------------+ | SAP Application Layer | | (ABAP Programs, SE38, SE80) | +-------------------------------------------------------+ | v +-------------------------------------------------------+ | ABAP Data Dictionary (SE11) | | (Domains, Data Elements, Structures, Tables, Views) | +-------------------------------------------------------+ | v (Auto-generated DDL / Objects) +-------------------------------------------------------+ | Underlying RDBMS Layer | | (Oracle, MS SQL Server, SAP HANA) | +-------------------------------------------------------+ ``` ### Key Functional Capabilities - **Database Independence**: Eliminates the requirement for developers to write platform-specific SQL Data Definition Language (DDL) scripts. - **Centralized Object Reuse**: Enables system-wide definition and reuse of global data types, database tables, views, and search helps. - **Active Runtime Catalog**: Database table structures defined in the DDIC are compiled directly into physical database objects upon activation. --- ## 2. Elementary Data Type Architecture: Domain vs. Data Element ![[../images/domain-data-element.png]] Data field definitions in the ABAP Dictionary decouple **technical parameters** from **business semantics** through a two-tier architecture comprising **Domains** and **Data Elements**. ![[../images/domain-data-element-1.png]] ### 2.1 Domain (Technical Attribute Layer) - **Definition**: Defines the physical and technical attributes of a data field. - **Technical Parameters**: - Built-in Data Type (e.g., `CHAR`, `NUMC`, `DEC`, `DATS`, `TIMS`). - Field Length and **Output Length** (accounts for formatting characters such as decimal points, currency signs, or negative indicators). - Case Sensitivity toggle (`Lower Case` / `Case Sensitive`). - **Value Restrictions**: - **Fixed Values (Value Range)**: Hardcoded valid single values or interval ranges enforced at domain level. - **Value Table**: Points to a master check table containing allowable key entries. ### 2.2 Data Element (Semantic Attribute Layer) - **Definition**: Defines the business meaning and contextual usage of a data object. - **Semantic Attributes**: - **UI Field Labels**: Defines Short, Medium, Long, and Heading labels displayed across screens and report columns. - **F1 Help Documentation**: Links to detailed documentation created via the documentation editor for end-user assistance. - **Relationship**: References a Domain to inherit technical attributes. A single Domain can be referenced by multiple Data Elements (e.g., Domain `S_CITY` referenced by Data Elements `S_FROMCIT` and `S_TOCITY`). - **Naming Conventions**: Domains and Data Elements reside in distinct object namespaces and can share identical names, though project guidelines typically utilize prefixes (e.g., `DO_` for domains, `DE_` for data elements). ### Example: ## ![[../images/domain-data-element-2.png]] ## 3. Composite Data Objects & Database Tables ### 3.1 Structures - **Definition**: Reusable, structured type definitions comprising a sequence of named components/fields. - **Behavior**: Structures do **not** persist data in the physical database. - **Applications**: - Used in ABAP programs to instantiate **Work Areas** (single-row structures). - Included directly within database table definitions via the **`INCLUDE`** statement to standardize field groups across multiple tables. ### 3.2 Data Categories in SAP 1. **Master Data**: Core entity records modified infrequently (e.g., Customer, Vendor, Material, Employee). 2. **Transactional Data**: High-volume operational transaction records (e.g., Sales Orders, Purchase Orders, Accounting Documents). 3. **Configuration Data**: System customization parameters established during project setup (e.g., Currency Codes, Payment Terms). 4. **System Data**: System administration and administrative runtime logs. ### 3.3 Database Table Types | Table Type | Description & Physical Mapping | | :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Transparent Table** | **1-to-1 Mapping**: Each transparent table defined in `SE11` corresponds to exactly one physical table in the database. | | **Pooled Table** | **N-to-1 Mapping**: Multiple logical pooled tables consolidated into a single physical table in the database; used primarily by system tables. | | **Cluster Table** | **N-to-1 Mapping**: Multiple logical cluster tables combined into a single database cluster table (e.g., `BSEG`); optimized for complex structural documents, considered legacy in SAP HANA. | | **Table Type** | **Global Memory Type**: A DDIC object defining internal table types used for ABAP program execution, containing no database persistence. | ### 3.4 Relational Features - **Primary Key**: Uniquely identifies each record in a database table. Key fields cannot be edited directly after record insertion. - **Client Dependency (`MANDT` / `CLIENT`)**: Automatic client separation is achieved by defining the primary key field `MANDT` (Data Element `MANDT`), ensuring data isolation per system client. - **Foreign Keys & Check Tables**: Foreign key field definitions map fields to a **Check Table** to maintain relational data integrity and auto-generate F4 input validation. --- ## 4. Database Views & Core Data Services (CDS) Views are logical definitions that join fields across one or more tables without duplicating physical data. ### 4.1 Classic DDIC Views (`SE11`) 1. **Database View**: Implements standard inner joins across database tables for read access. 2. **Maintenance View**: Configures table joins specifically to power Table Maintenance Generators (TMG) for administrative data entry. 3. **Projection View**: Selects a subset of fields from a single table to mask unwanted attributes. 4. **Help View**: Serves as the data selection foundation for Search Helps. ### 4.2 Core Data Services (CDS) Views - **Architecture**: Modern, code-based data modeling tool defined inside Eclipse ADT using SQL DDL syntax. - **Integration**: Automatically generates a underlying classic SQL View (limited to 16 characters) accessible via standard `SE11` and `SE16N` queries. --- ## 5. Input Assistance & Data Inspection ### 5.1 Search Help (F4 Help) Provides user assistance dialogs during UI field input. - **Elementary Search Help**: Defines a single search path, specifying the selection method (table/view), input/output parameters, and hit list layout. - **Collective Search Help**: Combines multiple Elementary Search Helps into a single tabbed dialog interface. ### 5.2 Data Inspection Utilities - **`SE16`**: Classic ABAP Workbench data browser utility; supports ALV Grid display via user parameter adjustments. - **`SE16N`**: Enhanced application data browser providing field filtering and record inspection capabilities. --- ## 6. Technical Settings & Performance Guidelines Every database table created in `SE11` requires technical settings configuration prior to activation: - **Delivery Class**: Specifies table data maintenance rules and client transport behavior (e.g., `A` for Application Master/Transaction data, `C` for Customizing). - **Data Class**: Determines physical database space allocation: - `APPL0`: Master Data. - `APPL1`: Transactional Data. - `USER`: User-specific datasets. - **Size Category**: Configures initial database extent allocation based on expected row count ranges. - **Buffering & Logging**: Enables application server memory caching for static tables or logs change operations. - **Secondary Indexes**: Additional index structures created on non-key columns to accelerate read performance; must be balanced against maintenance overhead during insert/update operations. ![[../images/domain-data-element-3.png]] 26:Ta28,1. System Overview & Architecture The ABAP Data Dictionary (DDIC), managed via Transaction Code SE11, is an integrated database management framework embedded within the SAP ABAP application server. It acts as a database abstraction layer positioned between SAP application programs and the underlying Relational Database Management System (RDBMS) such as Oracle or Microsoft SQL Server. +-------------------------------------------------------+ | SAP Application Layer | | (ABAP Programs, SE38, SE80) | +-------------------------------------------------------+ | v +-------------------------------------------------------+ | ABAP Data Dictionary (SE11) | | (Domains, Data Elements, Structures, Tables, Views) | +-------------------------------------------------------+ | v (Auto-generated DDL / Objects) +-------------------------------------------------------+ | Underlying RDBMS Layer | | (Oracle, MS SQL Server, SAP HANA) | +-------------------------------------------------------+ Key Functional Capabilities - Database Independence: Eliminates the requirement for developers to write platform-specific SQL Data Definition Language (DDL) scripts. - Centralized Object Reuse: Enables system-wide definition and reuse of global data types, database tables, views, and search helps. - Active Runtime Catalog: Database table structures defined in the DDIC are compiled directly into physical database objects upon activation. --- 2. Elementary Data Type Architecture: Domain vs. Data Element ![[../images/domain-data-element.png]] Data field definitions in the ABAP Dictionary decouple technical parameters from business semantics through a two-tier architecture comprising Domains and Data Elements. ![[../images/domain-data-element-1.png]] 2.1 Domain (Technical Attribute Layer) - Definition: Defines the physical and technical attributes of a data field. - Technical Parameters: - Built-in Data Type (e.g., CHAR, NUMC, DEC, DATS, TIMS). - Field Length and Output Length (accounts for formatting characters such as decimal points, currency signs, or negative indicators). - Case Sensitivity toggle (Lower Case / Case Sensitive). - Value Restrictions: - Fixed Values (Value Range): Hardcoded valid single values or interval ranges enforced at domain level. - Value Table: Points to a master check table containing allowable key entries. 2.2 Data Element (Semantic Attribute Layer) - Definition: Defines the business meaning and contextual usage of a data object. - Semantic Attributes: - UI Field Labels: Defines Short, Medium, Long, and Heading labels displayed across screens and report columns. -27:Tabf,## 1. System Overview & Architecture The **ABAP Data Dictionary (DDIC)**, managed via Transaction Code **`SE11`**, is an integrated database management framework embedded within the SAP ABAP application server. It acts as a database abstraction layer positioned between SAP application programs and the underlying Relational Database Management System (RDBMS) such as Oracle or Microsoft SQL Server. ``` +-------------------------------------------------------+ | SAP Application Layer | | (ABAP Programs, SE38, SE80) | +-------------------------------------------------------+ | v +-------------------------------------------------------+ | ABAP Data Dictionary (SE11) | | (Domains, Data Elements, Structures, Tables, Views) | +-------------------------------------------------------+ | v (Auto-generated DDL / Objects) +-------------------------------------------------------+ | Underlying RDBMS Layer | | (Oracle, MS SQL Server, SAP HANA) | +-------------------------------------------------------+ ``` ### Key Functional Capabilities - **Database Independence**: Eliminates the requirement for developers to write platform-specific SQL Data Definition Language (DDL) scripts. - **Centralized Object Reuse**: Enables system-wide definition and reuse of global data types, database tables, views, and search helps. - **Active Runtime Catalog**: Database table structures defined in the DDIC are compiled directly into physical database objects upon activation. --- ## 2. Elementary Data Type Architecture: Domain vs. Data Element ![[../images/domain-data-element.png]] Data field definitions in the ABAP Dictionary decouple **technical parameters** from **business semantics** through a two-tier architecture comprising **Domains** and **Data Elements**. ![[../images/domain-data-element-1.png]] ### 2.1 Domain (Technical Attribute Layer) - **Definition**: Defines the physical and technical attributes of a data field. - **Technical Parameters**: - Built-in Data Type (e.g., `CHAR`, `NUMC`, `DEC`, `DATS`, `TIMS`). - Field Length and **Output Length** (accounts for formatting characters such as decimal points, currency signs, or negative indicators). - Case Sensitivity toggle (`Lower Case` / `Case Sensitive`). - **Value Restrictions**: - **Fixed Values (Value Range)**: Hardcoded valid single values or interval ranges enforced at domain level. - **Value Table**: Points to a master check table containing allowable key entries. ### 2.2 Data Element (Semantic Attribute Layer)28:T201d, ## 1. Architecture & Execution Model **Open SQL** is an embedded subset of ANSI SQL fully integrated into the ABAP programming language. It acts as an abstraction layer between application programs and the underlying database management system (DBMS). ``` +-------------------------------------------------------+ | ABAP Application Layer | | (Open SQL Statements / SE38) | +-------------------------------------------------------+ | v (ABAP Syntax Check & Compilation) +-------------------------------------------------------+ | ABAP Database Interface | | (Translates Open SQL into Native SQL DML) | +-------------------------------------------------------+ | v (Database-Specific SQL Execution) +-------------------------------------------------------+ | Underlying RDBMS Layer | | (Oracle, MS SQL Server, SAP HANA) | +-------------------------------------------------------+ ``` ### 1.1 Key Architectural Properties - **Database Independence**: Open SQL statements are uniform across all supported database platforms. The **Database Interface** automatically converts Open SQL statements into the platform-specific **Native SQL** required by the underlying RDBMS (e.g., Oracle, MS SQL Server). - **Integrated Syntax Validation**: Because Open SQL is a native component of the ABAP language, the ABAP compiler validates SQL syntax directly during program compilation. - **Open SQL vs. Native SQL**: - **Open SQL**: Portable, database-agnostic, statically syntax-checked by the ABAP IDE, and automatically managed by the database interface. - **Native SQL**: Executes database-specific DML/DDL scripts directly. It bypasses the Database Interface, sacrificing portability and static compile-time syntax checks. - **Legacy Table Declarations**: The obsolete `TABLES <table>` statement implicitly creates a structure/work area sharing the table's name. Modern ABAP standards explicitly discourage this statement in favor of explicit type definitions. --- ## 2. Fundamental Query Syntax & Row Selection A standard Open SQL data retrieval statement consists of four core clauses: `SELECT`, `FROM`, `INTO`, and `WHERE`. ```abap SELECT <fields> FROM <table> INTO <target> WHERE <conditions>. ``` ### 2.1 Filtering & Evaluation (`WHERE`) - **Conditional Operators**: Supports standard comparison operators (`=`, `<`, `>`, `<=`, `>=`, `<>`), string pattern matching (`CP`, `CF`), range operators (`BETWEEN`, `IN`), and logical connectors (`AND`, `OR`, `NOT`). - **Selection Tables**: The `IN` operator evaluates field values against selection tables or range tables. ### 2.2 Row-Limiting Techniques - **`SELECT SINGLE`**: - Fetches a single record matching the query criteria. - **Best Practice**: Pass the complete primary key in the `WHERE` clause to guarantee deterministic behavior. - Does not open a database loop and does not require an `ENDSELECT` statement. - **`UP TO n ROWS`**: - Limits the result set to `n` rows. - **Best Practice**: Recommended over `SELECT SINGLE` when filtering on partial key fields. - Requires an `ENDSELECT` statement when selecting row-by-row into a work area. ### 2.3 Result Ordering & Deduplication - **`ORDER BY`**: Guarantees output row ordering. Can sort by `PRIMARY KEY` or by specific columns using `ASCENDING` or `DESCENDING` modifiers. - **`DISTINCT`**: Eliminates duplicate result rows prior to populating the target data object. ### 2.4 System Fields - **`sy-subrc`**: Returns `0` if the query successfully retrieves data, and `4` if no matching records are found. - **`sy-dbcnt`**: Contains the total count of records retrieved or processed by the query. --- ## 3. Aggregation & Grouping Open SQL provides built-in aggregation functions to perform calculations directly on the database engine prior to returning results. | Aggregation Function | Description | | :------------------------------ | :-------------------------------------------------------- | | `COUNT( * )` / `COUNT( field )` | Returns the total count of rows or non-null field values. | | `MAX( field )` | Identifies the maximum value in a column. | | `MIN( field )` | Identifies the minimum value in a column. | | `SUM( field )` | Calculates the total sum of a numeric column. | | `AVG( field )` | Computes the average value of a numeric column. | ### 3.1 Grouping Requirement (`GROUP BY`) When an Open SQL statement includes both scalar columns and aggregate functions in the `SELECT` clause, **all non-aggregated columns must be explicitly listed in the `GROUP BY` clause**. ```abap SELECT carrid, MAX( flytime ), MIN( flytime ) FROM spfli INTO (lv_carrid, lv_max_time, lv_min_time) GROUP BY carrid. ``` --- ## 4. Target Data Objects & Mapping Strategies Data retrieved via Open SQL can be mapped into single-row **Work Areas** or multi-row **Internal Tables**. ``` positional mapping (INTO TABLE): Database Columns: [ MANDT ] [ CARRID ] [ CONNID ] [ COUNTRYFR ] | | | | Target Structure: [ MANDT ] [ CARRID ] [ CONNID ] [ COUNTRYFR ] name-based mapping (INTO CORRESPONDING FIELDS OF TABLE): Database Columns: [ CARRID ] [ CONNID ] [ COUNTRYFR ] | | | +-----------+------------+ (Matches by Name) | Target Structure: [ STATUS ] [ CARRID ] [ CONNID ] [ COUNTRYFR ] ``` ### 4.1 Target Object Comparison | Feature | Work Area (`STRUCTURE`) | Internal Table (`INTERNAL TABLE`) | | :---------------- | :------------------------------------------------- | :---------------------------------------------- | | **Capacity** | Holds a single row of data at a time. | Holds multi-row datasets in application memory. | | **Access Syntax** | Direct field component selection (`<wa>-<field>`). | Iterated using `LOOP AT <itab> INTO <wa>`. | | **Target Clause** | `INTO <work_area>`. | `INTO TABLE <internal_table>`. | ### 4.2 Positional Mapping vs. Name-Based Mapping - **`INTO TABLE <itab>`**: Transfers column data sequentially based on field positions. If the target structure layout differs from the `SELECT` clause field order, data misalignment or truncation occurs. - **`INTO CORRESPONDING FIELDS OF TABLE <itab>`**: Matches database table columns to internal table fields strictly by **field name**, ignoring structural field sequence. Unmapped target fields remain set to their initial values. --- ## 5. Multi-Table Operations & Advanced Filtering ### 5.1 Relational Joins (`JOIN`) Joins combine records across multiple database tables within a single database request. Fields are qualified using tilde syntax (`<table>~<field>` or `<alias>~<field>`). - **`INNER JOIN`**: Returns combined records only when join conditions match in both left and right tables. - **`LEFT OUTER JOIN`**: Returns all rows from the left table. If no matching row exists in the right table, right-table fields are populated with type-specific initial values. ```abap SELECT header~vbeln, header~kunnr, item~posnr, item~matnr FROM vbak AS header INNER JOIN vbap AS item ON header~vbeln = item~vbeln INTO TABLE @DATA(lt_orders). ``` ### 5.2 Internal Table Filtering (`FOR ALL ENTRIES IN`) The `FOR ALL ENTRIES IN` clause evaluates an Open SQL query against all entries in a pre-populated driver internal table. - **Behavior**: Replaces large, complex database joins by using in-memory driver tables as filter criteria. - **Syntax**: ```abap SELECT doc_type, company_code, doc_num FROM bkpf INTO TABLE lt_headers FOR ALL ENTRIES IN lt_filter_tab WHERE doc_type = lt_filter_tab-doc_type. ``` --- 29:T9e1,1. Architecture & Execution Model Open SQL is an embedded subset of ANSI SQL fully integrated into the ABAP programming language. It acts as an abstraction layer between application programs and the underlying database management system (DBMS). +-------------------------------------------------------+ | ABAP Application Layer | | (Open SQL Statements / SE38) | +-------------------------------------------------------+ | v (ABAP Syntax Check & Compilation) +-------------------------------------------------------+ | ABAP Database Interface | | (Translates Open SQL into Native SQL DML) | +-------------------------------------------------------+ | v (Database-Specific SQL Execution) +-------------------------------------------------------+ | Underlying RDBMS Layer | | (Oracle, MS SQL Server, SAP HANA) | +-------------------------------------------------------+ 1.1 Key Architectural Properties - Database Independence: Open SQL statements are uniform across all supported database platforms. The Database Interface automatically converts Open SQL statements into the platform-specific Native SQL required by the underlying RDBMS (e.g., Oracle, MS SQL Server). - Integrated Syntax Validation: Because Open SQL is a native component of the ABAP language, the ABAP compiler validates SQL syntax directly during program compilation. - Open SQL vs. Native SQL: - Open SQL: Portable, database-agnostic, statically syntax-checked by the ABAP IDE, and automatically managed by the database interface. - Native SQL: Executes database-specific DML/DDL scripts directly. It bypasses the Database Interface, sacrificing portability and static compile-time syntax checks. - Legacy Table Declarations: The obsolete TABLES <table statement implicitly creates a structure/work area sharing the table's name. Modern ABAP standards explicitly discourage this statement in favor of explicit type definitions. --- 2. Fundamental Query Syntax & Row Selection A standard Open SQL data retrieval statement consists of four core clauses: SELECT, FROM, INTO, and WHERE. abap SELECT <fields FROM <table INTO <target WHERE <conditions. 2.1 Filtering & Evaluation (WHERE) - Conditional Operators: Supports standard comparison operators (=, <, , <=, =, <), string pattern matching (CP, CF), range operators (BETWEEN, IN), and logical connectors (AND, OR, NOT). - Selection Tables: The IN operator evaluates field values against selection tables or range tables. 2.2 Row-Limiting Techniques - SELECT SINGLE: - Fetches a single record matching the query2a:Tb38,## 1. Architecture & Execution Model **Open SQL** is an embedded subset of ANSI SQL fully integrated into the ABAP programming language. It acts as an abstraction layer between application programs and the underlying database management system (DBMS). ``` +-------------------------------------------------------+ | ABAP Application Layer | | (Open SQL Statements / SE38) | +-------------------------------------------------------+ | v (ABAP Syntax Check & Compilation) +-------------------------------------------------------+ | ABAP Database Interface | | (Translates Open SQL into Native SQL DML) | +-------------------------------------------------------+ | v (Database-Specific SQL Execution) +-------------------------------------------------------+ | Underlying RDBMS Layer | | (Oracle, MS SQL Server, SAP HANA) | +-------------------------------------------------------+ ``` ### 1.1 Key Architectural Properties - **Database Independence**: Open SQL statements are uniform across all supported database platforms. The **Database Interface** automatically converts Open SQL statements into the platform-specific **Native SQL** required by the underlying RDBMS (e.g., Oracle, MS SQL Server). - **Integrated Syntax Validation**: Because Open SQL is a native component of the ABAP language, the ABAP compiler validates SQL syntax directly during program compilation. - **Open SQL vs. Native SQL**: - **Open SQL**: Portable, database-agnostic, statically syntax-checked by the ABAP IDE, and automatically managed by the database interface. - **Native SQL**: Executes database-specific DML/DDL scripts directly. It bypasses the Database Interface, sacrificing portability and static compile-time syntax checks. - **Legacy Table Declarations**: The obsolete `TABLES <table>` statement implicitly creates a structure/work area sharing the table's name. Modern ABAP standards explicitly discourage this statement in favor of explicit type definitions. --- ## 2. Fundamental Query Syntax & Row Selection A standard Open SQL data retrieval statement consists of four core clauses: `SELECT`, `FROM`, `INTO`, and `WHERE`. ```abap SELECT <fields> FROM <table> INTO <target> WHERE <conditions>. ``` ### 2.1 Filtering & Evaluation (`WHERE`) - **Conditional Operators**: Supports standard comparison operators (`=`, `<`, `>`, `<=`, `>=`, `<>`), string pattern matching (`CP`, `CF`), range operators (`BETWEEN`, `IN`), and logical connectors (`AND`, `OR`, `NOT`). - **Selection Tables**: The `IN` operator evaluates field values against selection tables or range tables. ### 2.2 Row-Limiting Techniques2b:T6055, ## 1. Mental Model: Type, Structure, Work Area, and Internal Table Do not treat these as four equivalent objects. ```text TYPES declaration defines a type; it does not hold runtime values │ ├── DATA structure one structured data object │ └── may serve as a work area │ └── DATA internal table zero or more lines of one line type ``` ### 1.1 Structured type A structured type defines named components and their types. `TYPES` creates a type, not a runtime data object. ```abap TYPES: BEGIN OF ty_flight, carrier_id TYPE c LENGTH 3, connection_id TYPE n LENGTH 4, city_from TYPE c LENGTH 40, city_to TYPE c LENGTH 40, price TYPE p LENGTH 8 DECIMALS 2, currency TYPE c LENGTH 3, END OF ty_flight. ``` The type can be local, defined globally in a class/interface, or supplied by a released Dictionary/CDS artifact. `SE11` is a classic Dictionary maintenance tool, not the definition of the ABAP concept itself. ### 1.2 Structure data object `DATA` instantiates a data object and therefore allocates runtime state. ```abap DATA flight TYPE ty_flight. ``` The word **structure** can mean either a structured type or a structured data object, depending on context. Say which one you mean in technical explanations. ### 1.3 Work area A **work area** is a role played by a single data object when a table statement copies one line into it or reads a line from it. It is not a separate ABAP type category. ```abap DATA flight TYPE ty_flight. LOOP AT flights INTO flight. " flight is the work area for this loop ENDLOOP. ``` ### 1.4 Internal table An internal table is an in-memory ABAP data object containing zero or more lines. Its type is defined by: 1. line type; 2. table category; 3. primary table key; 4. optional secondary table keys. It is not a database table and is not persisted by `COMMIT WORK`. Its lifetime follows the lifetime and scope of its owning ABAP data object. ```abap TYPES ty_flights TYPE STANDARD TABLE OF ty_flight WITH EMPTY KEY. DATA flights TYPE ty_flights. ``` ### 1.5 Database boundary ```text Database table / CDS entity │ SELECT ▼ Internal table in ABAP application-server memory │ processing ▼ INSERT / UPDATE / MODIFY / DELETE or EML, when explicitly executed ``` Changing an internal-table line does not automatically update a database table or a RAP business object. --- ## 2. Complete, Reusable Example Types The examples below use explicit keys so their behavior is visible. ```abap TYPES: BEGIN OF ty_flight, carrier_id TYPE c LENGTH 3, connection_id TYPE n LENGTH 4, city_from TYPE c LENGTH 40, city_to TYPE c LENGTH 40, price TYPE p LENGTH 8 DECIMALS 2, currency TYPE c LENGTH 3, END OF ty_flight. TYPES ty_flights_seq TYPE STANDARD TABLE OF ty_flight WITH EMPTY KEY. TYPES ty_flights_sorted TYPE SORTED TABLE OF ty_flight WITH UNIQUE KEY primary_key COMPONENTS carrier_id connection_id. TYPES ty_flights_hashed TYPE HASHED TABLE OF ty_flight WITH UNIQUE KEY primary_key COMPONENTS carrier_id connection_id. DATA flights_seq TYPE ty_flights_seq. DATA flights_sorted TYPE ty_flights_sorted. DATA flights_hashed TYPE ty_flights_hashed. ``` `WITH EMPTY KEY` is a deliberate statement: the standard table is being used as a sequence, not as a keyed collection. --- ## 3. Table Categories Big-O values below are useful mental models, not promises about every kernel, row width, cache state, or access form. | Category | Primary organization | Primary-key uniqueness | Efficient access | Typical use | | ---------------- | ------------------------------------------ | ---------------------- | ----------------------------------------------------------- | ---------------------------------------------------- | | `STANDARD TABLE` | Primary index in insertion order | Non-unique or empty | Index access; sequential processing | Append-heavy lists, ordered processing, small tables | | `SORTED TABLE` | Primary index always sorted by primary key | Unique or non-unique | Left-aligned primary-key access, approximately `O(log n)` | Range reads and frequent ordered key access | | `HASHED TABLE` | Hash administration; no primary index | Must be unique | Complete primary-key equality, approximately `O(1)` average | Fast exact lookup by a unique key | ### 3.1 Standard table - Fast append and index access. - A normal key search is linear unless an appropriate secondary key or a valid binary-search pattern is used. - The primary key does not enforce uniqueness. - Prefer `WITH EMPTY KEY` when the table is intentionally only a sequence. ### 3.2 Sorted table - Lines are always maintained in ascending primary-key order. - The primary key may be unique or non-unique. - Optimized access requires the search components to form a usable left-aligned part of the sorted key. - It supports index access because it is an index table. For a key `(carrier_id, connection_id)`, searching by `carrier_id` can use the sorted prefix; searching only by `connection_id` cannot use that primary-key prefix efficiently. ### 3.3 Hashed table - The primary key must be unique. - Best for equality lookup using the complete hash key. - No primary index access such as `INDEX 1`. - Partial-key and range searches do not receive the main hash advantage. ### 3.4 Selection rule ```text Need stable index/insertion order or mostly append/loop? → STANDARD Need sorted traversal, ranges, or prefix-key lookup? → SORTED Need exact lookup by one complete unique key? → HASHED Need several access paths? → Add justified secondary keys; do not copy the table automatically ``` --- ## 4. Primary and Secondary Table Keys A table key is not merely documentation. It determines uniqueness, access optimization, ordering for sorted keys, and maintenance cost. ### 4.1 Secondary-key example ```abap TYPES ty_flights_multi TYPE STANDARD TABLE OF ty_flight WITH EMPTY KEY WITH UNIQUE HASHED KEY by_connection COMPONENTS carrier_id connection_id WITH NON-UNIQUE SORTED KEY by_route COMPONENTS city_from city_to. ``` ```abap READ TABLE flights_multi WITH TABLE KEY by_connection COMPONENTS carrier_id = 'LH' connection_id = '0400' INTO DATA(flight). LOOP AT flights_multi INTO DATA(route_flight) USING KEY by_route WHERE city_from = 'FRANKFURT'. " Uses the named sorted access path when the condition fits the key ENDLOOP. ``` ### 4.2 Secondary-key trade-off Secondary keys can make reads much faster, but they require extra memory and must be maintained when table content changes. Add one only for a demonstrated access pattern, not “for performance” in the abstract. --- ## 5. Assignment and Name-Based Mapping The original claim that normal assignment can silently “misalign” fields is too broad. ABAP checks assignment compatibility and applies the defined assignment rules. It does not simply scramble fields because their names differ. Use direct assignment when source and target types are compatible: ```abap target = source. ``` Use `CORRESPONDING` when the desired contract is name-based component mapping: ```abap DATA(target) = CORRESPONDING ty_target( source MAPPING target_id = source_id ). ``` Use the statement form when updating an existing target: ```abap MOVE-CORRESPONDING source TO target. ``` Unmatched target components keep or receive values according to the exact statement/operator variant. Check `BASE`, `MAPPING`, `EXCEPT`, and deep-mapping semantics when preservation matters. --- ## 6. Constructing and Adding Lines ### 6.1 Constructor expressions ```abap flights_seq = VALUE #( ( carrier_id = 'LH' connection_id = '0400' city_from = 'FRANKFURT' city_to = 'NEW YORK' price = '800.00' currency = 'EUR' ) ( carrier_id = 'SQ' connection_id = '0012' city_from = 'SINGAPORE' city_to = 'TOKYO' price = '650.00' currency = 'SGD' ) ). ``` ### 6.2 `APPEND` `APPEND` adds at the end of an index table. It is natural for a standard table. ```abap APPEND VALUE #( carrier_id = 'VN' connection_id = '0030' city_from = 'HO CHI MINH CITY' city_to = 'TOKYO' ) TO flights_seq. ``` Although `APPEND` is possible for sorted index tables, the new line must fit after the existing last line and obey key uniqueness. Otherwise the operation fails at runtime. Prefer semantic insertion for sorted tables. ### 6.3 `INSERT ... INTO TABLE` This key-based form works with all table categories and lets the table choose the physical position. ```abap INSERT VALUE #( carrier_id = 'LH' connection_id = '0400' ) INTO TABLE flights_sorted. IF sy-subrc = 4. " Duplicate unique key; no line inserted ENDIF. ``` For a standard table, use `INSERT ... INDEX index` only when position has business meaning. --- ## 7. Reading One Line Safely ### 7.1 `READ TABLE ... INTO`: copy the row ```abap READ TABLE flights_sorted WITH TABLE KEY primary_key COMPONENTS carrier_id = 'LH' connection_id = '0400' INTO DATA(flight). IF sy-subrc = 0. " flight is a copy ENDIF. ``` Modifying `flight` does not modify the table until it is written back. ### 7.2 `READ TABLE ... ASSIGNING`: alias the row ```abap READ TABLE flights_sorted WITH TABLE KEY primary_key COMPONENTS carrier_id = 'LH' connection_id = '0400' ASSIGNING FIELD-SYMBOL(<flight>). IF sy-subrc = 0. <flight>-price = '825.00'. " Changes the table line directly ENDIF. ``` A field symbol is an alias to an assigned data object, not a separately copied row. It must be assigned before dereferencing. ### 7.3 `REFERENCE INTO`: retain a data reference ```abap READ TABLE flights_sorted WITH TABLE KEY primary_key COMPONENTS carrier_id = 'LH' connection_id = '0400' REFERENCE INTO DATA(flight_ref). IF sy-subrc = 0. flight_ref->price = '825.00'. ENDIF. ``` ### 7.4 Table expressions ```abap TRY. DATA(lh_price) = flights_sorted[ carrier_id = 'LH' connection_id = '0400' ]-price. CATCH cx_sy_itab_line_not_found. " Handle the missing row ENDTRY. ``` A failed table expression normally raises `CX_SY_ITAB_LINE_NOT_FOUND`; it does not simply set `sy-subrc` like `READ TABLE`. For existence only: ```abap IF line_exists( flights_sorted[ carrier_id = 'LH' connection_id = '0400' ] ). " Do not perform a second lookup unless the row content is also needed ENDIF. ``` Use one `READ TABLE`, assignment, or reference when the next step needs the line; `line_exists` followed by a second read repeats the lookup. ### 7.5 System fields For common `READ TABLE` forms, `sy-subrc = 0` means a line was found and `sy-subrc = 4` commonly means no matching line was found. For index tables, `sy-tabix` can identify the affected or current primary/secondary index, but its meaning depends on the statement and key used. Hashed primary-key access has no primary table index. Table expressions do not generally set `sy-subrc` and do not generally update `sy-tabix`; use their expression/exception semantics instead. Never rely on a system field without tying it to the immediately preceding statement. --- ## 8. Iteration: Copy, Alias, or Reference | Form | Row handling | Use when | | ------------------------- | ------------------------------------------- | ------------------------------------------ | | `LOOP ... INTO` | Copies each row | Readability or independent copy is desired | | `LOOP ... ASSIGNING` | Assigns a field symbol to the current row | Direct mutation or avoiding row copies | | `LOOP ... REFERENCE INTO` | Returns a data reference to the current row | A reference must be passed or retained | ```abap LOOP AT flights_seq INTO DATA(flight_copy) WHERE city_from = 'FRANKFURT'. " Changes to flight_copy do not automatically change flights_seq ENDLOOP. LOOP AT flights_seq ASSIGNING FIELD-SYMBOL(<flight_row>) WHERE city_from = 'FRANKFURT'. <flight_row>-price += 25. " Direct table-line modification ENDLOOP. ``` `ASSIGNING` can avoid copying wide or deep rows, but do not claim it is always faster in a meaningful way. Choose it first for semantics—direct mutation—and measure performance where it matters. The primary-key components of sorted and hashed tables are protected from changes that would invalidate their administration. Delete and reinsert a line when its primary identity must change. --- ## 9. Modifying Lines ### 9.1 Modify by table key ```abap DATA changed_flight TYPE ty_flight. changed_flight-carrier_id = 'LH'. changed_flight-connection_id = '0400'. changed_flight-price = '850.00'. MODIFY TABLE flights_sorted FROM changed_flight. IF sy-subrc <> 0. " No row matched the primary key ENDIF. ``` ### 9.2 Modify selected components ```abap MODIFY flights_seq FROM VALUE #( price = '700.00' currency = 'EUR' ) TRANSPORTING price currency WHERE carrier_id = 'LH'. ``` ### 9.3 Modify by field symbol ```abap LOOP AT flights_seq ASSIGNING FIELD-SYMBOL(<flight>) WHERE carrier_id = 'LH'. <flight>-price *= '0.95'. ENDLOOP. ``` No `MODIFY` is needed in the last example because `<flight>` aliases the table line. By contrast, a changed work-area copy from `LOOP ... INTO` must be written back explicitly, normally with a clear key or index. --- ## 10. Deleting and Clearing ```abap DELETE flights_seq INDEX 1. DELETE flights_sorted USING KEY primary_key WHERE carrier_id = 'LH'. DELETE TABLE flights_hashed WITH TABLE KEY primary_key COMPONENTS carrier_id = 'LH' connection_id = '0400'. ``` ### 10.1 Remove duplicates `DELETE ADJACENT DUPLICATES` removes only neighboring duplicates according to the comparison. For a standard table, sort into the required adjacency first. ```abap SORT flights_seq BY city_from city_to. DELETE ADJACENT DUPLICATES FROM flights_seq COMPARING city_from city_to. ``` The sort fields and comparison fields must express the same intended identity. ### 10.2 `CLEAR` versus `FREE` ```abap CLEAR flights_seq. " Remove rows; retain initial allocation for reuse FREE flights_seq. " Remove rows and release the initial table allocation ``` Use `CLEAR` when the table will probably be filled again soon. Use `FREE` when releasing a large table's allocation is useful. The ABAP runtime still owns the details of dynamic memory management; do not assume an operating-system memory change at that exact statement. --- ## 11. Sorting and Binary Search ```abap SORT flights_seq BY carrier_id connection_id. READ TABLE flights_seq WITH KEY carrier_id = 'LH' connection_id = '0400' BINARY SEARCH INTO DATA(flight). ``` For `BINARY SEARCH` to be correct, the standard table must already be sorted in ascending order with a compatible leading field sequence. If later code changes the order, the search contract silently becomes fragile. Prefer a sorted table or named sorted secondary key when repeated optimized key access is part of the data model. Use one-off `SORT` plus `BINARY SEARCH` only when the local lifecycle makes the ordering invariant obvious. --- ## 12. Aggregation with `COLLECT` `COLLECT` finds a line using the internal table's **primary key**. If found, it adds the source's numeric non-key components to the existing line. If not found, it inserts the line. ```abap TYPES: BEGIN OF ty_route_total, city_from TYPE c LENGTH 40, city_to TYPE c LENGTH 40, revenue TYPE decfloat34, END OF ty_route_total. TYPES ty_route_totals TYPE HASHED TABLE OF ty_route_total WITH UNIQUE KEY primary_key COMPONENTS city_from city_to. DATA route_totals TYPE ty_route_totals. LOOP AT flights_seq INTO DATA(flight). COLLECT VALUE ty_route_total( city_from = flight-city_from city_to = flight-city_to revenue = flight-price ) INTO route_totals. ENDLOOP. ``` All components outside the primary key must be numeric for this aggregation form. An explicit sorted or hashed key makes the aggregation identity and lookup behavior clearer than relying on a standard table's implicit standard key. Do not confuse ABAP `COLLECT` with database aggregation. When a large dataset can be aggregated correctly by the database, prefer `SELECT ... GROUP BY` so fewer rows cross into application-server memory. --- ## 13. Modern Group Processing Prefer `LOOP AT ... GROUP BY` over legacy control-break processing when writing new code. Grouping is explicit and does not depend on physical component order or temporary masking of work-area fields. ```abap LOOP AT flights_seq INTO DATA(flight) GROUP BY ( carrier_id = flight-carrier_id members = GROUP SIZE ) ASSIGNING FIELD-SYMBOL(<carrier_group>). DATA(total_price) = REDUCE decfloat34( INIT total = CONV decfloat34( 0 ) FOR member IN GROUP <carrier_group> NEXT total += member-price ). " <carrier_group>-carrier_id, <carrier_group>-members, total_price ENDLOOP. ``` Grouping happens in two phases: ABAP assigns rows to group keys, then iterates over the groups. Member iteration uses `LOOP AT GROUP` or `FOR ... IN GROUP`. ### 13.1 Modern table transformations Constructor and iteration expressions can make pure transformations concise: ```abap DATA(lh_flights) = VALUE ty_flights_seq( FOR flight IN flights_seq WHERE ( carrier_id = 'LH' ) ( flight ) ). ``` Use expression syntax when it makes the transformation clearer. A conventional loop is still appropriate when error handling, tracing, or several side effects would make one expression difficult to understand. --- ## 14. Legacy Constructs You Must Recognize ### 14.1 Header lines ```abap " Obsolete — recognize it; do not introduce it DATA old_flights TYPE STANDARD TABLE OF ty_flight WITH HEADER LINE. ``` This declaration creates both: ```text old_flights implicit single-line header area old_flights[] internal table body ``` That name collision makes statements ambiguous: ```abap CLEAR old_flights. " Historically addresses the header line CLEAR old_flights[]. " Addresses the table body ``` Header-line declarations are obsolete and are not allowed in classes. Modern code uses an explicit table plus an explicit work area, inline declaration, or field symbol. ### 14.2 `AT NEW`, `AT END OF`, and `SUM` Legacy control-break events include: - `AT FIRST` - `AT NEW component` - `AT END OF component` - `AT LAST` They depend on the processing order and on the component order of the row structure. During classic control-break blocks, character-like components to the right of the break component can be represented by asterisks and other components can receive initial values temporarily. This behavior is one reason the code is difficult to maintain. When reading old code: 1. inspect the row-type component order; 2. inspect the table's actual processing order; 3. identify the exact break component; 4. check which values are valid inside the event block; 5. inspect any `SUM` behavior carefully. For new code, prefer explicit `GROUP BY` and `REDUCE`. --- ## 15. Database and RAP Boundaries ### 15.1 Avoid `SELECT` inside a loop ```abap " Avoid repeated database round trips LOOP AT requests INTO DATA(request). SELECT SINGLE ... WHERE request_uuid = @request-request_uuid ... ENDLOOP. ``` Prefer set-oriented retrieval using a join, association, subquery, range, or a carefully guarded `FOR ALL ENTRIES`, depending on the problem and release. When using `FOR ALL ENTRIES`: - guard against an initial driver table; - select only necessary columns; - understand duplicate elimination and key semantics; - measure against a join or other set-oriented alternative. ### 15.2 Internal table versus RAP transactional buffer RAP method parameters and EML results are represented using generated internal table types, but the RAP transactional buffer is a framework-managed business object state. It is not identical to one local variable such as `DATA(items)`. ```text Local internal table variable → ordinary ABAP runtime data RAP transactional buffer → framework-managed pending BO changes, addressed through EML ``` Changing a local EML result table does not change the business object. Use `MODIFY ENTITIES` when the BO state must change. --- ## 16. Performance Rules That Survive Interviews 1. **Choose the table category from access patterns.** Do not choose hashed only because the dataset is “large.” 2. **Use the key explicitly.** Optimized lookup depends on the key and search components actually used. 3. **Keep processing set-oriented.** Avoid repeated database access inside internal-table loops. 4. **Avoid unnecessary row copies.** Use `ASSIGNING` or `REFERENCE INTO` when direct access is the intended semantic, especially for wide/deep rows. 5. **Do not over-index.** Secondary keys consume memory and add mutation cost. 6. **Do not sort repeatedly.** If sorted access is a stable requirement, model it with a sorted table or secondary key. 7. **Push suitable filtering and aggregation to the database.** Internal tables are not a replacement for SQL execution on large persisted datasets. 8. **Measure material paths.** Runtime depends on row count, width, mutation frequency, selectivity, and release—not only theoretical complexity. --- ## 17. Common Failure Modes | Symptom | Likely cause | Correction | | ----------------------------------- | ----------------------------------------------------------- | ------------------------------------------------ | | Lookup is still slow | Search does not use a suitable primary/secondary key | Name the key and align the search components | | `BINARY SEARCH` misses a row | Standard table is not sorted compatibly | Sort correctly or model a sorted key | | Duplicate insert fails | Unique sorted/hashed key already exists | Handle `sy-subrc` or choose non-unique semantics | | Table expression dumps | Row is absent and exception/default was not handled | Use `TRY`, `OPTIONAL`, or `READ TABLE` | | Work-area change is lost | `LOOP ... INTO` created a copy | Write it back or use `ASSIGNING` intentionally | | Sorted/hashed key cannot be changed | Direct mutation would invalidate primary-key administration | Delete and reinsert with the new identity | | Duplicate deletion misses rows | Equal comparison values are not adjacent | Sort by the comparison identity first | | `COLLECT` groups unexpectedly | Primary table key does not match aggregation identity | Define an explicit unique key | | RAP BO did not change | Only a local result internal table was modified | Use EML `MODIFY ENTITIES` | --- ## 18. Compact Decision and Syntax Sheet ```text Declare a sequence STANDARD TABLE ... WITH EMPTY KEY Repeated ordered/range access SORTED TABLE ... WITH [NON-]UNIQUE KEY ... Exact unique lookup HASHED TABLE ... WITH UNIQUE KEY ... Read a copy READ TABLE ... INTO ... Read and mutate the row READ TABLE ... ASSIGNING ... Read with a durable reference READ TABLE ... REFERENCE INTO ... Expression lookup itab[ key = value ] Existence only line_exists( itab[ key = value ] ) Insert by table semantics INSERT line INTO TABLE itab Aggregate by explicit primary key COLLECT line INTO itab Group modern ABAP data LOOP AT itab ... GROUP BY ... ``` ### Useful whole-table operations ```abap " Value-copy one compatible table target_flights = source_flights. " Append all source lines APPEND LINES OF source_flights TO target_flights. " Current number of lines DATA(line_count) = lines( target_flights ). " Older statement form still encountered DESCRIBE TABLE target_flights LINES DATA(described_count). ``` 2c:T774,1. Mental Model: Type, Structure, Work Area, and Internal Table Do not treat these as four equivalent objects. text TYPES declaration defines a type; it does not hold runtime values │ ├── DATA structure one structured data object │ └── may serve as a work area │ └── DATA internal table zero or more lines of one line type 1.1 Structured type A structured type defines named components and their types. TYPES creates a type, not a runtime data object. abap TYPES: BEGIN OF tyflight, carrierid TYPE c LENGTH 3, connectionid TYPE n LENGTH 4, cityfrom TYPE c LENGTH 40, cityto TYPE c LENGTH 40, price TYPE p LENGTH 8 DECIMALS 2, currency TYPE c LENGTH 3, END OF tyflight. The type can be local, defined globally in a class/interface, or supplied by a released Dictionary/CDS artifact. SE11 is a classic Dictionary maintenance tool, not the definition of the ABAP concept itself. 1.2 Structure data object DATA instantiates a data object and therefore allocates runtime state. abap DATA flight TYPE tyflight. The word structure can mean either a structured type or a structured data object, depending on context. Say which one you mean in technical explanations. 1.3 Work area A work area is a role played by a single data object when a table statement copies one line into it or reads a line from it. It is not a separate ABAP type category. abap DATA flight TYPE tyflight. LOOP AT flights INTO flight. " flight is the work area for this loop ENDLOOP. 1.4 Internal table An internal table is an in-memory ABAP data object containing zero or more lines. Its type is defined by: 1. line type; 2. table category; 3. primary table key; 4. optional secondary table keys. It is not a database table and is not persisted by COMMIT WORK. Its lifetime follows the lifetime and scope of its owning ABAP data object. abap TYPES tyflights TYPE STANDARD TABLE OF tyflight WITH EMPTY KEY. DATA flights2d:T80f,## 1. Mental Model: Type, Structure, Work Area, and Internal Table Do not treat these as four equivalent objects. ```text TYPES declaration defines a type; it does not hold runtime values │ ├── DATA structure one structured data object │ └── may serve as a work area │ └── DATA internal table zero or more lines of one line type ``` ### 1.1 Structured type A structured type defines named components and their types. `TYPES` creates a type, not a runtime data object. ```abap TYPES: BEGIN OF ty_flight, carrier_id TYPE c LENGTH 3, connection_id TYPE n LENGTH 4, city_from TYPE c LENGTH 40, city_to TYPE c LENGTH 40, price TYPE p LENGTH 8 DECIMALS 2, currency TYPE c LENGTH 3, END OF ty_flight. ``` The type can be local, defined globally in a class/interface, or supplied by a released Dictionary/CDS artifact. `SE11` is a classic Dictionary maintenance tool, not the definition of the ABAP concept itself. ### 1.2 Structure data object `DATA` instantiates a data object and therefore allocates runtime state. ```abap DATA flight TYPE ty_flight. ``` The word **structure** can mean either a structured type or a structured data object, depending on context. Say which one you mean in technical explanations. ### 1.3 Work area A **work area** is a role played by a single data object when a table statement copies one line into it or reads a line from it. It is not a separate ABAP type category. ```abap DATA flight TYPE ty_flight. LOOP AT flights INTO flight. " flight is the work area for this loop ENDLOOP. ``` ### 1.4 Internal table An internal table is an in-memory ABAP data object containing zero or more lines. Its type is defined by: 1. line type; 2. table category; 3. primary table key; 4. optional secondary table keys. It is not a database table and is not persisted by `COMMIT WORK`. Its lifetime follows the lifetime and scope of its owning ABAP data object.2e:T809d, ## 1. The Four Levels of Modularization The word **module** is ambiguous. First identify what is being separated. ```text Repository / deployment organization Package and software component │ Architectural contract Class, interface, released API │ Callable processing block Method, function module, legacy FORM routine │ Source-text organization INCLUDE ``` | Level | Main question | Examples | | ---------------------- | --------------------------------------------------------------- | ------------------------------------- | | Package boundary | Which objects belong, depend on one another, and move together? | Package, software component | | Architectural boundary | What stable responsibility and contract are exposed? | Interface, global class, released API | | Procedure boundary | What inputs enter, what outputs leave, and what can fail? | Method, function module, `FORM` | | Source organization | In which source unit is this text maintained? | `INCLUDE` program | Splitting 2,000 lines into ten includes improves navigation, but does not by itself reduce shared state, coupling, side effects, or test difficulty. --- ## 2. Modern Decision Guide | Need | Preferred construct | Why | | -------------------------------------------------- | -------------------------------------------------- | ----------------------------------------------------------- | | Business/domain logic in new development | Instance method behind an interface | Encapsulation, substitution, testing, dependency injection | | Stateless utility with no substitutable dependency | Static method, used selectively | Simple call without object state | | One calculated result | Functional method with `RETURNING` | Natural expression-oriented call | | Existing classic reusable API | Existing function module | Preserve the supported contract; wrap when useful | | RFC or update-task infrastructure that requires it | Appropriately configured function module | Function modules provide these classic runtime capabilities | | Organizing a large legacy program | Include program | Source separation only | | Reading old procedural code | `FORM`/`PERFORM` | Compatibility and controlled refactoring | | New RAP business logic | Behavior implementation method plus helper classes | Framework contract plus testable domain logic | Default rule for new code: ```text Interface → class → small cohesive methods ``` Do not introduce a function module or `FORM` merely because code must be reused. --- ## 3. Methods: The Primary Modern Procedure A method belongs to a class or interface. It has a statically known signature, visibility, parameter directions, typing, and exception contract. ### 3.1 Instance method ```abap INTERFACE zif_amount_calculator PUBLIC. METHODS calculate_net_amount IMPORTING quantity TYPE decfloat34 unit_price TYPE decfloat34 RETURNING VALUE(net_amount) TYPE decfloat34. ENDINTERFACE. CLASS zcl_amount_calculator DEFINITION PUBLIC FINAL CREATE PUBLIC. PUBLIC SECTION. INTERFACES zif_amount_calculator. ENDCLASS. CLASS zcl_amount_calculator IMPLEMENTATION. METHOD zif_amount_calculator~calculate_net_amount. net_amount = quantity * unit_price. ENDMETHOD. ENDCLASS. ``` Call: ```abap DATA(calculator) = NEW zcl_amount_calculator( ). DATA(net_amount) = calculator->zif_amount_calculator~calculate_net_amount( quantity = CONV decfloat34( '3' ) unit_price = CONV decfloat34( '12.50' ) ). ``` The interface expresses the consumer contract. The class expresses one implementation. Calling through the interface makes replacement and testing possible. ### 3.2 Static method ```abap CLASS-METHODS normalize_status IMPORTING raw_status TYPE string RETURNING VALUE(status) TYPE string. ``` Call: ```abap DATA(status) = zcl_status_helper=>normalize_status( raw_status ). ``` Static methods are suitable for genuinely stateless operations. Excessive static dependencies behave like globals: they are difficult to substitute and can make isolated tests harder. ### 3.3 Visibility | Visibility | Meaning | | ------------------- | ------------------------------------------- | | `PUBLIC SECTION` | Callable by external consumers | | `PROTECTED SECTION` | Accessible to the class and subclasses | | `PRIVATE SECTION` | Internal implementation detail of the class | Expose the smallest useful public contract. Test public behavior; do not make every helper public merely to call it from a test. ### 3.4 Functional methods A functional method has exactly one `RETURNING` parameter and can appear in an expression. ```abap METHODS calculate_total IMPORTING items TYPE ztt_order_item RETURNING VALUE(total) TYPE decfloat34. DATA(total) = calculator->calculate_total( items ). ``` The return value is completely typed and passed by value. Use `EXPORTING` or `CHANGING` parameters only when the procedure naturally produces several outputs or intentionally updates caller-owned state. --- ## 4. Method Interfaces and Parameter Directions Directions are named from the **callee's** perspective. | Formal parameter in method | Callee meaning | Caller clause | | -------------------------- | -------------------------------------------------- | ------------------------------------------------ | | `IMPORTING` | Method receives input | `EXPORTING` or omitted in functional call syntax | | `EXPORTING` | Method produces output | `IMPORTING` | | `CHANGING` | Method receives and returns the same logical value | `CHANGING` | | `RETURNING` | Functional result | Operand position or `RECEIVING` | Example: ```abap METHODS determine_status IMPORTING current_quantity TYPE i EXPORTING reason TYPE string CHANGING status TYPE string. service->determine_status( EXPORTING current_quantity = quantity IMPORTING reason = DATA(reason) CHANGING status = status ). ``` The caller's keywords are not an arbitrary “inversion.” Both sides describe the same flow from their own perspective. ### 4.1 Optional and default parameters Method input and changing parameters can be optional or have defaults where the language permits. ```abap METHODS format_amount IMPORTING amount TYPE decfloat34 currency TYPE c LENGTH 3 DEFAULT 'EUR' show_currency TYPE abap_bool OPTIONAL RETURNING VALUE(text) TYPE string. ``` Inside a procedure, `IS SUPPLIED` distinguishes an omitted optional parameter from one supplied with its type-initial value. Use optional parameters carefully. Too many independent options often indicate that the method has several responsibilities or needs a parameter object. --- ## 5. Parameter Passing: Reference, Value, and Value-Result Parameter direction and parameter passing are different dimensions. ```text Direction: IMPORTING / EXPORTING / CHANGING / RETURNING Passing: by reference / by value / value-result behavior ``` ### 5.1 Pass by reference The formal parameter refers to the actual parameter. No independent parameter copy is created for the procedure contract. - Changes through an output-capable reference parameter affect the caller. - Aliasing can create side effects when the same object is reachable through several paths. - Input parameters should be treated as inputs according to their contract. ### 5.2 Pass by value `VALUE(parameter)` creates a local formal parameter. Input values are copied in; output-capable values are copied back only when procedure processing completes successfully. For large or deep data, do not assume an immediate physical copy of every byte: the ABAP runtime can optimize copying internally. Choose semantics first and measure important paths. ### 5.3 Value-result For an output-capable `VALUE(...)` parameter, the procedure works on a local value and transfers the result to the caller at successful completion. If an exception ends the procedure before successful completion, that copy-back does not occur. ### 5.4 Prefer intention-revealing interfaces ```text Input only → IMPORTING One new result → RETURNING Several new results → EXPORTING or a result structure Intentional in/out → CHANGING ``` Do not use `CHANGING` as a convenient substitute for designing a result. --- ## 6. Class-Based Exceptions Declare failures that the caller can reasonably handle. ```abap METHODS submit_request IMPORTING request_uuid TYPE sysuuid_x16 RAISING zcx_request_invalid zcx_request_unauthorized. ``` ```abap TRY. service->submit_request( request_uuid ). CATCH zcx_request_invalid INTO DATA(invalid_error). DATA(message) = invalid_error->get_text( ). CATCH zcx_request_unauthorized INTO DATA(auth_error). message = auth_error->get_text( ). ENDTRY. ``` Use class-based exceptions for exceptional failure paths. Do not return a Boolean plus an unrelated global message when the caller needs structured error information. In RAP behavior methods, follow the generated `FAILED` and `REPORTED` contract for business-operation failures instead of replacing it with an arbitrary exception design. --- ## 7. Includes: Source Organization, Not Encapsulation An include program is an ABAP repository source object that cannot be compiled independently. `INCLUDE name.` incorporates its source into the compilation unit of the including program. ```abap REPORT zorder_report. INCLUDE zorder_report_top. " declarations INCLUDE zorder_report_sel. " selection screen INCLUDE zorder_report_cls. " local classes ``` Conceptually: ```text Main source + included source units ↓ activation/compilation One compilation unit ``` ### 7.1 What an include does - Splits a large source into separately maintained source units. - Participates in the including program's compilation and syntax context. - Can organize declarations, procedural blocks, local classes, or event logic. - Cannot execute independently. ### 7.2 What an include does not do - It does not define a callable interface merely by being an include. - It does not create a runtime call or stack frame. - It does not isolate global variables from the including program. - It does not make logic reusable in the architectural sense. - It does not automatically improve unit testability. Declarations in an include have the visibility and scope produced by their position in the combined program. Source order therefore matters. ### 7.3 Parameters An include itself has no parameter interface. A method or legacy `FORM` written inside an include can have parameters because that procedure—not the include— defines the call boundary. ### 7.4 Activation An include must be syntax-checked in a compilation-unit context. When it changes, activate the include and affected owning repository objects as a consistent change set. Do not claim that an include is independently compiled or that every include change always requires a manual activation of every main program; tooling and dependency handling vary by development environment. ### 7.5 Reuse warning SAP recommends assigning an include program to one compilation unit. Reusing the same include across unrelated programs creates hidden dependencies on global declarations, program type, source order, and event context. Extract a class or interface when reuse is the real requirement. --- ## 8. Subroutines: Legacy `FORM` and `PERFORM` SAP classifies subroutines as obsolete. You must recognize and safely maintain them in classic code, but use methods for new designs. ```abap PERFORM calculate_net USING quantity unit_price CHANGING net_amount. FORM calculate_net USING quantity TYPE decfloat34 unit_price TYPE decfloat34 CHANGING net_amount TYPE decfloat34. net_amount = quantity * unit_price. ENDFORM. ``` At `PERFORM`, control enters the `FORM`, executes it, and returns after the call. ### 8.1 Scope - A subroutine is implemented outside classes. - It normally belongs to its program's procedural context. - It can directly access that program's global data, which creates hidden input and output channels. - Data declared inside the `FORM` is local to a call; `STATICS` data persists across calls in the relevant internal session. `PERFORM ... IN PROGRAM` can call a subroutine in another program, but creates a fragile cross-program dependency. Do not use it as a modern public API. ### 8.2 Subroutine parameter passing | Declaration | Passing behavior | Caller effect | | ------------------- | -------------------- | ---------------------------------------------------------------- | | `USING p` | Reference by default | A write can affect caller state, despite the input-oriented name | | `USING VALUE(p)` | Value | Local copy; caller is not changed | | `CHANGING p` | Reference by default | Writes immediately affect caller state | | `CHANGING VALUE(p)` | Value-result | Local value copied back after successful completion | `USING` and `CHANGING` communicate intent; `VALUE(...)` determines value passing. A reference-passed `USING` parameter is not protected from writes by the language in the same way a strong immutable contract would be, so treat it as read-only by convention. ### 8.3 Typing Without explicit typing, a subroutine formal parameter is generically typed as `any`. This defers useful checks and allows failures to appear at runtime. ```abap " Avoid in maintained code FORM process USING input. " Better legacy form FORM process USING input TYPE ty_request. ``` Subroutines do not support modern optional/default parameter interfaces. Static calls should pass the declared parameter sequence exactly. Dynamic subroutine calls weaken static checks further and introduce injection risk if an external value controls the procedure/program name. ### 8.4 Obsolete `TABLES` parameters ```abap " Obsolete — recognize, do not introduce FORM process TABLES rows STRUCTURE zs_row. ``` Use typed `USING` or `CHANGING` parameters while maintaining a `FORM`, and use a class method when refactoring the design. ```abap TYPES ty_requests TYPE STANDARD TABLE OF ty_request WITH EMPTY KEY. FORM process USING requests TYPE ty_requests. " Read-only by convention ENDFORM. ``` --- ## 9. Function Modules A function module is a globally named procedure implemented inside a function group. Classic maintenance uses transaction `SE37`; function groups can be inspected with `SE80` or ADT tooling, depending on the environment. ```text Function group (function pool) ├── global data shared by its function modules ├── generated and developer-managed includes ├── Function Module A └── Function Module B ``` The function module has a public interface. The function group's global data is shared state within the loaded function pool and can make behavior order- dependent if misused. ### 9.1 Call direction Consider an illustrative custom function module whose interface imports an ID and exports a result: ```abap CALL FUNCTION 'Z_READ_REQUEST_STATUS' EXPORTING request_uuid = request_uuid IMPORTING status = status EXCEPTIONS not_found = 1 OTHERS = 2. IF sy-subrc <> 0. " Handle classic exception result ENDIF. ``` | Function-module interface | Caller uses | Flow | | ------------------------- | ------------------------------ | ------------------------ | | `IMPORTING request_uuid` | `EXPORTING request_uuid = ...` | Caller → function module | | `EXPORTING status` | `IMPORTING status = ...` | Function module → caller | | `CHANGING data` | `CHANGING data = ...` | Both directions | This is the same callee/caller perspective used for method calls. ### 9.2 Interface typing and runtime checks Function module names and interfaces are resolved at runtime by `CALL FUNCTION`, even when the name is a literal. Incorrect names, missing parameters, unknown parameters, length conflicts, and type conflicts therefore lead to dynamic-call exceptions or runtime errors such as: - `CALL_FUNCTION_NOT_FOUND` - `CALL_FUNCTION_PARM_MISSING` - `CALL_FUNCTION_PARM_UNKNOWN` - `CALL_FUNCTION_CONFLICT_TYPE` - `CALL_FUNCTION_CONFLICT_LENG` The sample's generic `ILLEGAL_TYPE_PARAM` label is not the useful diagnostic name for ordinary function-module parameter mismatches. Read the actual short dump and identify the formal and actual parameter types. ### 9.3 Optional parameters Unlike `FORM` routines, function module importing and changing parameters can be optional or have default values. Exporting parameters are optional to the caller. The function module can use `parameter IS SUPPLIED` where supported to distinguish omission from an initial value. ### 9.4 Exceptions #### Classic non-class-based exception ```abap CALL FUNCTION 'Z_READ_REQUEST_STATUS' EXPORTING request_uuid = request_uuid IMPORTING status = status EXCEPTIONS not_found = 1 OTHERS = 2. CASE sy-subrc. WHEN 0. " Success WHEN 1. " NOT_FOUND WHEN OTHERS. " Another mapped exception ENDCASE. ``` The numeric values are assigned by the caller. `sy-subrc = 1` has meaning only because this particular call maps `not_found = 1`. #### Class-based exception If the function module declares class-based exceptions, handle them with `TRY ... CATCH` according to its interface. ```abap TRY. CALL FUNCTION 'Z_READ_REQUEST_STATUS_NEW' EXPORTING request_uuid = request_uuid IMPORTING status = status. CATCH zcx_request_not_found INTO DATA(error). DATA(message) = error->get_text( ). ENDTRY. ``` SAP considers non-class-based exceptions a compatibility mechanism. Do not define them for new general-purpose APIs when a class-based contract is available and supported by the invocation type. ### 9.5 Obsolete `TABLES` interface parameters The `TABLES` parameter style is legacy and reference-based. New interfaces use typed importing, exporting, changing, or returning parameters. Be especially careful with RFC restrictions: remote-enabled interfaces have serialization and type constraints beyond local calls. --- ## 10. Specialized Function-Module Runtime Modes Function modules remain important where the platform explicitly requires their runtime capabilities. ### 10.1 Remote-enabled function module (RFC) ```abap CALL FUNCTION 'Z_REMOTE_OPERATION' DESTINATION destination EXPORTING input = input IMPORTING output = output EXCEPTIONS system_failure = 1 MESSAGE system_message communication_failure = 2 MESSAGE communication_message OTHERS = 3. ``` RFC introduces a serialization and communication boundary. Never pass an untrusted external string directly as a dynamic function or destination name. Validate allowlisted values and use supported communication configuration. ### 10.2 Update function module ```abap CALL FUNCTION 'Z_WRITE_AUDIT' IN UPDATE TASK EXPORTING audit_entry = audit_entry. ``` An update function module registers work for update processing associated with the SAP LUW. It has strict interface and execution rules. Do not replace an ordinary method call with `IN UPDATE TASK` merely to make it asynchronous. ### 10.3 Background/asynchronous mechanisms Classic asynchronous RFC, background tasks, bgRFC, qRFC, application jobs, and events solve different reliability and sequencing problems. “Function module” alone does not imply remote, asynchronous, or transactional behavior; the call variant and module attributes matter. --- ## 11. Other Legacy Processing Blocks ### 11.1 Macros ```abap DEFINE set_status. &1-status = &2. END-OF-DEFINITION. ``` Macros are source-level substitution constructs with positional placeholders, not typed procedures. They can obscure control flow and tooling. Recognize them in old code; prefer methods for new logic. ### 11.2 Dialog modules ```abap MODULE validate_screen_input INPUT. " Classic dynpro PAI logic ENDMODULE. ``` `MODULE ... ENDMODULE` processing blocks are called by classic screen flow logic (`PBO`/`PAI`). They are relevant to dynpro maintenance, not a preferred general-purpose reuse mechanism. ### 11.3 Event blocks Blocks such as `START-OF-SELECTION` define framework-driven program events. They are entry points, not reusable APIs. Keep them thin and delegate coherent logic to methods. --- ## 12. Scope and State | Location | Typical lifetime/visibility | Main risk | | -------------------------- | -------------------------------- | ------------------------------------------- | | Method local `DATA` | One invocation | Low; explicit local state | | Instance attribute | Object lifetime | Hidden mutation if responsibility is broad | | Static/class attribute | Internal-session/class lifetime | Global-style coupling and test interference | | Program global data | Program/internal-session context | Hidden inputs and outputs across procedures | | Function-group global data | Loaded function-pool context | Calls depend on prior calls/state | | `STATICS` local data | Retained across procedure calls | Surprising state and test-order dependence | The phrase “local data is freed immediately on exit” is an oversimplification. Local names leave scope at procedure exit, but referenced objects, shared data, runtime optimizations, and garbage collection determine physical memory lifetime. Prefer explicit parameters and returned results over procedure access to global state. --- ## 13. Refactoring a `FORM` into a Class ### 13.1 Legacy form ```abap DATA orders TYPE ztt_order. DATA total TYPE decfloat34. FORM calculate_total. LOOP AT orders INTO DATA(order). total += order-net_amount. ENDLOOP. ENDFORM. ``` Hidden contract: ```text Input: global orders Output: global total Failure: undocumented ``` ### 13.2 First safe step: expose the contract ```abap FORM calculate_total USING orders TYPE ztt_order CHANGING total TYPE decfloat34. CLEAR total. LOOP AT orders INTO DATA(order). total += order-net_amount. ENDLOOP. ENDFORM. ``` ### 13.3 Modern result: functional method ```abap METHODS calculate_total IMPORTING orders TYPE ztt_order RETURNING VALUE(total) TYPE decfloat34. METHOD calculate_total. total = REDUCE decfloat34( INIT sum = CONV decfloat34( 0 ) FOR order IN orders NEXT sum += order-net_amount ). ENDMETHOD. ``` The improvement is not the shorter syntax. The method has an explicit input, one explicit result, no dependency on program global state, and a contract that can live behind an interface. --- ## 14. Testable Modular Design Merely extracting code into a method does not make it testable. A method that calls the database, system date, authorization, external service, and output UI directly still has many hidden dependencies. ```text Application service ├── zif_order_repository ├── zif_authorization ├── zif_clock └── pure amount/status policy ``` Inject dependencies through a constructor or factory-visible seam: ```abap METHODS constructor IMPORTING repository TYPE REF TO zif_order_repository authorization TYPE REF TO zif_order_authorization. ``` Then ABAP Unit tests can supply doubles implementing those interfaces. ### Design properties - **High cohesion:** one module owns one closely related responsibility. - **Low coupling:** consumers depend on small contracts, not implementation globals. - **Explicit dependencies:** database, time, authorization, and external calls are visible. - **Explicit effects:** mutation and persistence are not hidden in a “helper.” - **Stable abstraction:** names express business intent, not implementation steps such as `do_processing_2`. --- ## 15. Transaction Ownership A reusable procedure should not issue `COMMIT WORK` or `ROLLBACK WORK` unless its documented contract truly owns the complete SAP LUW. Otherwise it can prematurely commit changes made by its caller. ```text Caller/application boundary starts orchestration ├── validate ├── calculate ├── persist/register changes └── decide transaction completion ``` This is especially important when wrapping legacy function modules: inspect whether the called API performs commits, registers update tasks, sends messages, or mutates function-group global state. --- ## 16. Modularization in RAP ### 16.1 Framework entry points A RAP behavior pool is an ABAP class pool. The framework calls generated handler/saver method signatures based on the behavior definition. ```text Behavior definition declares operation/action/validation/determination ↓ RAP runtime invokes generated behavior-handler method ↓ Behavior method orchestrates EML and domain helpers ``` Do not rename generated method parameters or invent an unrelated callable name; the framework contract determines the signature. ### 16.2 Keep behavior methods thin enough ```abap METHOD validate_customer. " 1. Read required BO state with EML " 2. Delegate pure/customer-existence decision where useful " 3. Fill FAILED and REPORTED according to RAP contract ENDMETHOD. ``` Good extraction candidates include: - deterministic calculations; - state-transition policies; - message construction; - adapters around released external APIs; - repository/query logic with a test seam. Keep `%tky`, `%cid`, `%is_draft`, `FAILED`, `MAPPED`, and `REPORTED` handling at the RAP boundary unless a dedicated helper abstraction genuinely improves it. ### 16.3 Transaction rule Do not execute `COMMIT WORK` inside RAP behavior implementation. RAP owns the save sequence and transaction boundary. A legacy function module that commits internally is therefore dangerous to call from a RAP interaction/save flow. ### 16.4 Local mode is not modularization `IN LOCAL MODE` changes EML authorization/feature-control handling inside the current BO implementation context. It does not make the called logic a separate module and does not bypass validations or the transactional buffer. --- ## 17. ABAP Cloud and Clean-Core Boundary ABAP Cloud uses a restricted language version and released APIs to provide lifecycle-stable development. For new cloud-ready code: - use classes, interfaces, and methods; - use ADT as the development environment; - depend only on objects released for the required contract; - check API State, not merely whether an object exists; - avoid obsolete syntax such as `FORM`/`PERFORM`; - do not call an unreleased classic function module directly from clean-core code; - wrap permitted classic dependencies only within an intentional migration tier in applicable private/on-premise scenarios. A function module is not automatically forbidden because it is old, and a class is not automatically clean-core because it is object-oriented. The decisive questions are release state, allowed language version, and stability contract. --- ## 18. Naming Guidance Prefixes such as `iv_`, `ev_`, `cv_`, `lt_`, and `gt_` are team conventions, not ABAP language requirements. Use names that expose intent: ```abap METHODS calculate_total IMPORTING items TYPE ztt_order_item RETURNING VALUE(total) TYPE decfloat34. ``` This is usually clearer than encoding every implementation detail: ```abap METHODS calc IMPORTING it_data TYPE ztt_order_item RETURNING VALUE(rv_val) TYPE decfloat34. ``` Follow the project's agreed style consistently, but do not mistake prefixes for encapsulation or type safety. --- ## 19. Common Failure Modes | Symptom | Likely cause | Diagnostic direction | | ----------------------------------------- | ------------------------------------------------------------------- | -------------------------------------------------------------- | | Changing an include breaks several places | Shared source depends on different globals/contexts | Use where-used list; establish each compilation-unit contract | | `PERFORM` call dumps or behaves strangely | Parameter sequence/type mismatch or hidden globals | Compare caller/callee order and explicit types | | Function module call dumps | Missing, unknown, length-conflicting, or type-conflicting parameter | Read ST22 dump and compare SE37 interface with actual values | | `sy-subrc` handling is wrong | Caller mapped classic exceptions differently or checked too late | Read the exact `EXCEPTIONS` mapping immediately after the call | | Unit test depends on execution order | Static, global, `STATICS`, or function-group state | Reset/extract state; inject dependency | | Helper unexpectedly commits data | Procedure owns hidden transaction control | Inspect `COMMIT WORK`, update-task, RFC, and called APIs | | RAP transaction becomes inconsistent | Legacy call commits or bypasses BO contract | Keep transaction under RAP and use released/compatible APIs | | “Reusable” method cannot be reused | It reads globals, UI state, or database implicitly | Make inputs, outputs, effects, and dependencies explicit | | Static utility is impossible to fake | Consumer depends directly on static implementation | Introduce a small interface and instance collaborator | --- ## 20. Technical Review Workflow When reviewing a modularization problem: 1. **Identify the construct:** include, method, function module, `FORM`, macro, screen module, or event block. 2. **Identify the owner:** program, class, interface, function group, package, or framework. 3. **Write the real contract:** inputs, outputs, exceptions/messages, database effects, global state, commits, and external calls. 4. **Check call resolution:** static method, dynamic method, local/external `PERFORM`, local FM, RFC, update task, or framework callback. 5. **Check typing and parameter passing:** direction, reference/value, optional parameters, table types, and aliasing. 6. **Check lifecycle:** local invocation, object state, class/global state, function-group state, or internal session. 7. **Check test seam:** can dependencies be substituted without a real database, clock, authorization, or remote system? 8. **Check transaction ownership:** who is allowed to save, commit, or roll back? 9. **Check release contract:** is the dependency permitted in the target ABAP language version and API contract? 10. **Refactor by risk:** first expose hidden parameters and effects, then move behavior behind a method/interface. --- ## 21. Compact Syntax Sheet ```text Instance method object->method( ... ) Static method class=>method( ... ) Functional result DATA(result) = object->method( input ) Class-based failure TRY ... CATCH cx_... ENDTRY Include source INCLUDE source_name. Legacy subroutine PERFORM routine USING ... CHANGING ... FORM routine USING ... CHANGING ... ENDFORM. Function module CALL FUNCTION 'NAME' EXPORTING ... IMPORTING ... CHANGING ... EXCEPTIONS ... Remote function call CALL FUNCTION 'NAME' DESTINATION destination ... Update registration CALL FUNCTION 'NAME' IN UPDATE TASK ... ``` 2f:T93e,1. The Four Levels of Modularization The word module is ambiguous. First identify what is being separated. text Repository / deployment organization Package and software component │ Architectural contract Class, interface, released API │ Callable processing block Method, function module, legacy FORM routine │ Source-text organization INCLUDE | Level | Main question | Examples | | ---------------------- | --------------------------------------------------------------- | ------------------------------------- | | Package boundary | Which objects belong, depend on one another, and move together? | Package, software component | | Architectural boundary | What stable responsibility and contract are exposed? | Interface, global class, released API | | Procedure boundary | What inputs enter, what outputs leave, and what can fail? | Method, function module, FORM | | Source organization | In which source unit is this text maintained? | INCLUDE program | Splitting 2,000 lines into ten includes improves navigation, but does not by itself reduce shared state, coupling, side effects, or test difficulty. --- 2. Modern Decision Guide | Need | Preferred construct | Why | | -------------------------------------------------- | -------------------------------------------------- | ----------------------------------------------------------- | | Business/domain logic in new development | Instance method behind an interface | Encapsulation, substitution, testing, dependency injection | | Stateless utility with no substitutable dependency | Static method, used selectively | Simple call without object state | | One calculated result | Functional method with RETURNING | Natural expression-oriented call | | Existing classic reusable API | Existing function module | Preserve the supported contract; wrap when useful | | RFC or update-task infrastructure that requires it | Appropriately configured function module | Function modules provide these classic runtime capabilities | | Organizing a large legacy program | Include program | Source separation only | | Reading old procedural code | FORM/PERFORM | Compatibility and controlled refactoring | | New RAP business logic | Behavior implementation method plus helper classes | Framework contract plus testable domain logic | Default rule for new code: text Interface → class → small cohesive methods Do30:Tc2b,## 1. The Four Levels of Modularization The word **module** is ambiguous. First identify what is being separated. ```text Repository / deployment organization Package and software component │ Architectural contract Class, interface, released API │ Callable processing block Method, function module, legacy FORM routine │ Source-text organization INCLUDE ``` | Level | Main question | Examples | | ---------------------- | --------------------------------------------------------------- | ------------------------------------- | | Package boundary | Which objects belong, depend on one another, and move together? | Package, software component | | Architectural boundary | What stable responsibility and contract are exposed? | Interface, global class, released API | | Procedure boundary | What inputs enter, what outputs leave, and what can fail? | Method, function module, `FORM` | | Source organization | In which source unit is this text maintained? | `INCLUDE` program | Splitting 2,000 lines into ten includes improves navigation, but does not by itself reduce shared state, coupling, side effects, or test difficulty. --- ## 2. Modern Decision Guide | Need | Preferred construct | Why | | -------------------------------------------------- | -------------------------------------------------- | ----------------------------------------------------------- | | Business/domain logic in new development | Instance method behind an interface | Encapsulation, substitution, testing, dependency injection | | Stateless utility with no substitutable dependency | Static method, used selectively | Simple call without object state | | One calculated result | Functional method with `RETURNING` | Natural expression-oriented call | | Existing classic reusable API | Existing function module | Preserve the supported contract; wrap when useful | | RFC or update-task infrastructure that requires it | Appropriately configured function module | Function modules provide these classic runtime capabilities | | Organizing a large legacy program | Include program | Source separation only | | Reading old procedural code | `FORM`/`PERFORM` | Compatibility and controlled refactoring | | New RAP business logic | Behavior implementation method plus helper classes | Framework contract plus testable domain logic | Default rule for new code:31:T7fb5, ## 1. The Correct Overall Mental Model A classic executable report is **event-driven**. Source-code position does not mean that ABAP simply executes every line from top to bottom. The ABAP runtime framework raises events and calls the matching event blocks. The selection screen also creates a loop: ```text Program requested │ ▼ Program loaded into internal session, if not already loaded │ ├─ global/static initialization performed by runtime └─ LOAD-OF-PROGRAM event block, if defined │ ▼ INITIALIZATION │ ▼ AT SELECTION-SCREEN OUTPUT selection-screen PBO │ ▼ Selection screen displayed │ ▼ User action │ ├─ F4 help ───────────────► ON VALUE-REQUEST FOR field │ │ │ └─ redisplay loop │ ├─ F1 help ───────────────► ON HELP-REQUEST FOR field │ │ │ └─ redisplay loop │ ├─ Enter / pushbutton / │ radio USER-COMMAND ────► selection-screen PAI events │ │ │ └─ AT SELECTION-SCREEN OUTPUT │ → redisplay │ └─ Execute F8 ─────────────► selection-screen PAI validation │ ├─ validation error │ └─ OUTPUT → redisplay │ └─ validation succeeds └─ START-OF-SELECTION │ ├─ report application logic ├─ END-OF-SELECTION, if defined └─ output/list processing ``` The straight-line version from the initial draft omitted the redisplay cycle. `AT SELECTION-SCREEN OUTPUT` can run many times; `INITIALIZATION` normally runs once for that report execution before the standard selection screen first appears. --- ## 2. Report Source Layout Versus Runtime Order A maintainable report can be arranged like this: ```abap REPORT zsales_order_report. " Global declarations and selection-screen definition TABLES sscrfields. PARAMETERS: p_open RADIOBUTTON GROUP mode DEFAULT 'X' USER-COMMAND mode, p_all RADIOBUTTON GROUP mode. SELECT-OPTIONS s_order FOR vbak-vbeln. CLASS lcl_application DEFINITION FINAL. PUBLIC SECTION. CLASS-METHODS run. ENDCLASS. CLASS lcl_application IMPLEMENTATION. METHOD run. " Application orchestration ENDMETHOD. ENDCLASS. INITIALIZATION. " One-time selection defaults AT SELECTION-SCREEN OUTPUT. " Dynamic screen attributes before each display AT SELECTION-SCREEN. " Cross-field/action validation START-OF-SELECTION. lcl_application=>run( ). ``` The physical order improves readability, but runtime execution is determined by events. Each event block begins with an event keyword and ends at the next processing block or the end of the program; there is no `END-...` statement. Keep event blocks thin and delegate application logic to methods. This prevents the report framework, selection-screen state, database logic, and output logic from becoming one inseparable procedure. ### 2.1 Declaration-scope trap Most event blocks are not ordinary procedures. Declarations written inside them belong to the compilation unit's global declarations and remain visible in subsequent processing blocks. Selection-screen and logical-database event blocks are special runtime implementations that can allow local declarations, but a consistent design should still put working data inside called methods. ```abap START-OF-SELECTION. DATA result TYPE string. " Do not assume method-local lifecycle semantics lcl_application=>run( ). ``` The safe architectural rule is not “declare globals inside an event.” It is “use the event as a thin framework adapter and work locally inside methods.” --- ## 3. Phase 1 — Program Load ### 3.1 What “load” means When the executable program is first needed in an internal session, its load is made available and its global data context is initialized. Programs already loaded in the same internal session need not be loaded again simply because a procedure is called again. Do not confuse: ```text Repository activation/generation creates or updates executable program load Runtime loading brings the program into an internal session for execution ``` ### 3.2 `LOAD-OF-PROGRAM` Contrary to the draft statement, this is a definable event block: ```abap LOAD-OF-PROGRAM. " Rarely needed in an ordinary report ``` It is the program constructor event and occurs when the program is loaded into an internal session. It is not the normal place for user defaults or report business processing. Typical guidance: - Use declaration-time initialization for simple constants/default state. - Use `INITIALIZATION` for initial selection-screen values. - Use constructors for object initialization. - Avoid database updates, user interaction, commits, or large queries in `LOAD-OF-PROGRAM`. ### 3.3 Why it may run less often than expected `LOAD-OF-PROGRAM` is associated with loading the program, not every selection-screen redisplay. If the program remains loaded in the internal session, repeated calls or interactions do not imply repeated program-load events. --- ## 4. Phase 2 — `INITIALIZATION` `INITIALIZATION` occurs before the standard selection screen is first processed for the report execution. ```abap PARAMETERS p_date TYPE sy-datum. INITIALIZATION. p_date = sy-datum. ``` Good uses: - calculate initial date ranges; - choose a sensible initial radio button; - initialize selection-screen texts or pushbutton labels; - supply lightweight defaults that should occur once. Avoid: - repeatedly controlling whether a field is visible or editable; - expensive report data selection; - changing database state; - authorization enforcement that must also protect background execution or non-screen entry points. ### 4.1 `DEFAULT` versus `INITIALIZATION` ```abap PARAMETERS p_status TYPE c LENGTH 1 DEFAULT 'O'. ``` Use declaration `DEFAULT` for a static initial value. Use `INITIALIZATION` when the starting value requires runtime calculation. ### 4.2 Why not put dynamic screen logic here? `INITIALIZATION` does not run on every redisplay. If screen input readiness depends on the currently selected radio button, use `AT SELECTION-SCREEN OUTPUT`. Also distinguish an initial proposal from the effective runtime selection. Selection variants, SPA/GPA memory values, `SUBMIT` parameters, or previous user input can influence values later in the screen lifecycle. When debugging, inspect the value at `AT SELECTION-SCREEN OUTPUT` and again in PAI instead of assuming the value assigned during `INITIALIZATION` is still effective. --- ## 5. Phase 3 — Selection-Screen PBO `AT SELECTION-SCREEN OUTPUT` is the Process Before Output event of the selection screen. It runs directly before the screen is displayed and can run repeatedly. ```abap PARAMETERS: p_file RADIOBUTTON GROUP mode DEFAULT 'X' USER-COMMAND mode, p_order RADIOBUTTON GROUP mode, p_path TYPE string LOWER CASE MODIF ID fil, p_vbeln TYPE vbak-vbeln MODIF ID ord. AT SELECTION-SCREEN OUTPUT. LOOP AT SCREEN. CASE screen-group1. WHEN 'FIL'. screen-active = xsdbool( p_file = abap_true ). WHEN 'ORD'. screen-active = xsdbool( p_order = abap_true ). ENDCASE. MODIFY SCREEN. ENDLOOP. ``` `MODIF ID fil` is represented in `SCREEN-GROUP1` as uppercase `FIL`. ### 5.1 Common `SCREEN` fields | Field | Purpose | | --------------------------------------- | ----------------------------------------- | | `SCREEN-GROUP1` | Modification group from `MODIF ID` | | `SCREEN-ACTIVE` | Combined active/inactive control | | `SCREEN-INPUT` | Input enabled/disabled | | `SCREEN-INVISIBLE` | Visible/hidden behavior | | `SCREEN-REQUIRED` | Visual/required-state control | | `SCREEN-DISPLAY_3D` or other attributes | Release/UI-specific presentation controls | Always execute `MODIFY SCREEN` for a changed row of the special `SCREEN` table. ### 5.2 Idempotence rule Implement output logic so the correct screen state is recalculated from the current selection values on every PBO. Do not rely on the event running only once or on the previous display state. --- ## 6. Phase 4 — Screen Display and User Action After PBO, the selection screen is sent to the presentation layer. The user can enter values, request help, choose a command, press Enter, or execute. The action determines the next event path. “User does something” is therefore not one event. | User action | Important event path | | ------------------------------------------ | ------------------------------------------------------------- | | Press F4 on a field | `ON VALUE-REQUEST FOR field` | | Press F1 on a field | `ON HELP-REQUEST FOR field` | | Change radio/checkbox with `USER-COMMAND` | Selection-screen PAI; then redisplay | | Press a custom selection-screen pushbutton | Selection-screen PAI; then usually redisplay | | Press Enter | Selection-screen PAI; then redisplay | | Press Execute F8 | Selection-screen PAI; if valid, leave screen and start report | | Press Back/Exit/Cancel | Exit-command handling and screen termination path | --- ## 7. F4 Value Help: `ON VALUE-REQUEST` Use a custom value-request event only when Dictionary/search-help behavior does not already provide the correct F4 help. ```abap AT SELECTION-SCREEN ON VALUE-REQUEST FOR p_path. p_path = lcl_file_dialog=>choose_file( ). ``` Flow: ```text User presses F4 on p_path → AT SELECTION-SCREEN ON VALUE-REQUEST FOR p_path → custom logic proposes/sets a value → selection screen is displayed again ``` This is not the report's business validation event and does not proceed to `START-OF-SELECTION`. ### 7.1 Prefer metadata-driven value help If the parameter refers to a DDIC field with a search help, check table, or fixed domain values, the runtime can often supply value help automatically. Do not replace correct metadata with unnecessary custom F4 code. ### 7.2 Security rule Value help narrows or proposes input; it is not authorization enforcement and does not guarantee that submitted input is valid. Validate the final value and perform authorization checks at the execution boundary. --- ## 8. F1 Help: `ON HELP-REQUEST` ```abap AT SELECTION-SCREEN ON HELP-REQUEST FOR p_path. lcl_help=>show_path_explanation( ). ``` Use this only when standard field/documentation help is insufficient. Like F4, it is a help request, not successful report execution. --- ## 9. Radio Buttons and `USER-COMMAND` Changing a radio button does **not** necessarily cause an immediate server round trip. Associate a function code when the selection should trigger dynamic screen modification: ```abap PARAMETERS: p_file RADIOBUTTON GROUP mode DEFAULT 'X' USER-COMMAND mode, p_order RADIOBUTTON GROUP mode. ``` The command is assigned to the group through the first declared radio button. On selection: ```text Radio selection changes → function code MODE is sent → selection-screen PAI events run → AT SELECTION-SCREEN OUTPUT recalculates field state → screen is redisplayed ``` Access the function code through `SSCRFIELDS-UCOMM` in classic code: ```abap TABLES sscrfields. AT SELECTION-SCREEN. CASE sscrfields-ucomm. WHEN 'MODE'. " Usually no business execution here; allow redisplay ENDCASE. ``` Radio-button user commands are well suited to screen adaptation, not to running the main report. F8 remains the normal transition to report execution. --- ## 10. Phase 5 — Selection-Screen PAI and Validation PAI transfers input from the screen and raises the relevant `AT SELECTION-SCREEN` events. Think of validation as layers from narrow to broad. ```text Field or selection-criterion checks → end-of-multiple-selection checks → radio-button-group checks → block checks → generic AT SELECTION-SCREEN command/cross-field check ``` The exact triggered subset depends on the screen fields and user action. ### 10.1 Validate one parameter ```abap AT SELECTION-SCREEN ON p_vbeln. IF p_order = abap_true AND p_vbeln IS INITIAL. MESSAGE e001(zreport) WITH 'Enter a sales order'. ENDIF. ``` Use for a rule local to that field. A radio-button field is validated with the group event rather than an individual field event. ### 10.2 Validate a radio-button group ```abap AT SELECTION-SCREEN ON RADIOBUTTON GROUP mode. IF p_file = abap_false AND p_order = abap_false. MESSAGE e002(zreport) WITH 'Choose a mode'. ENDIF. ``` ### 10.3 Validate a block ```abap SELECTION-SCREEN BEGIN OF BLOCK criteria WITH FRAME TITLE text-t01. PARAMETERS p_vbeln TYPE vbak-vbeln. SELECT-OPTIONS s_date FOR sy-datum. SELECTION-SCREEN END OF BLOCK criteria. AT SELECTION-SCREEN ON BLOCK criteria. IF p_vbeln IS INITIAL AND s_date[] IS INITIAL. MESSAGE e003(zreport) WITH 'Enter an order or date range'. ENDIF. ``` ### 10.4 Validate a complete `SELECT-OPTIONS` criterion ```abap AT SELECTION-SCREEN ON END OF s_date. LOOP AT s_date ASSIGNING FIELD-SYMBOL(<date_range>). IF <date_range>-option = 'BT' AND <date_range>-low > <date_range>-high. MESSAGE e004(zreport) WITH 'Invalid date interval'. ENDIF. ENDLOOP. ``` The selection criterion is a range-like table containing `SIGN`, `OPTION`, `LOW`, and `HIGH`. Validate the whole selection table when intervals or multiple rows interact. ### 10.5 Generic `AT SELECTION-SCREEN` ```abap AT SELECTION-SCREEN. CASE sscrfields-ucomm. WHEN 'ONLI'. " Common Execute function code; verify in target context lcl_selection_validator=>validate( file_mode = p_file path = p_path order = p_vbeln ). WHEN 'MODE'. " Dynamic mode switch; return to screen ENDCASE. ``` Use the generic event for cross-field validation and command handling. Do not hard-code a function code without confirming the actual selection-screen context. --- ## 11. Validation Failure and Redisplay An error message during selection-screen validation prevents the transition to `START-OF-SELECTION` and returns control to the selection screen. ```text Execute F8 → PAI validation → MESSAGE E → validation stops → AT SELECTION-SCREEN OUTPUT → corrected screen displayed ``` This is why `AT SELECTION-SCREEN OUTPUT` must tolerate repeated execution. `OBLIGATORY` provides basic required-input checking, but it does not replace cross-field business validation, existence checks, or authorization checks. ### 11.1 Message types are context-sensitive `MESSAGE E`, `W`, `I`, `S`, `A`, and `X` do not have one universal control-flow meaning independent of their processing context. In selection-screen PAI, error messages can return the user to input. In other report phases, the same message type can have a different runtime consequence. Diagnose the event and dialog context, not only the letter. --- ## 12. Exit Commands Back, Exit, and Cancel are exit-type commands. Use the specialized event only when cleanup or confirmation is genuinely necessary: ```abap AT SELECTION-SCREEN ON EXIT-COMMAND. " Avoid validation that traps the user on a screen they are leaving ``` This event is designed to handle exit commands before ordinary selection-screen validation prevents leaving because of invalid field content. Do not perform report business processing here. --- ## 13. Phase 6 — `START-OF-SELECTION` After the user chooses Execute and selection-screen processing succeeds, the runtime raises `START-OF-SELECTION`. ```abap START-OF-SELECTION. lcl_application=>run( ). ``` This is the report's standard processing block and should usually be its thin application entry point. Typical application flow: ```text START-OF-SELECTION → create application/service objects → enforce execution authorization → convert selection-screen globals into an input structure → read data set-wise → apply business rules → prepare result model → render output ``` ### 13.1 Implicit `START-OF-SELECTION` Executable statements written before the first explicit processing block are assigned to an implicit `START-OF-SELECTION` block. If no explicit event blocks exist, all functional statements form the implicit standard event. Avoid this confusing layout: ```abap REPORT zbad_layout. DATA value TYPE i. value = 10. " Implicit START-OF-SELECTION START-OF-SELECTION. value += 1. " A separate explicit event block ``` Prefer an explicit event keyword and a thin method call so runtime placement is obvious. --- ## 14. `END-OF-SELECTION` Historically, `END-OF-SELECTION` marks processing after a logical database has finished supplying rows through `GET` events. ```abap END-OF-SELECTION. " Final processing after logical-database selection ``` Without a logical database, it follows standard selection processing but often adds no useful architectural boundary. Do not use it simply because its name sounds like the required end of every report. A modern report can orchestrate its complete flow from a method called at `START-OF-SELECTION`. --- ## 15. Logical-Database Events Older reports can be linked to a logical database and receive node data through events such as: ```abap GET node. " Process one logical-database node instance GET node LATE. " Process after subordinate nodes ``` Conceptual runtime: ```text START-OF-SELECTION → logical database reads nodes → GET parent → GET child → GET parent LATE → END-OF-SELECTION ``` Recognize this in legacy reports. For new data access, prefer explicit Open SQL, CDS entities, and released APIs according to the target development model. --- ## 16. Output and List Events ### 16.1 Simple/classic list `WRITE` produces classic list output. Page/list processing can raise events such as: - `TOP-OF-PAGE` - `END-OF-PAGE` - `AT LINE-SELECTION` - `AT USER-COMMAND` Interactive list events happen after initial report processing, in response to the user acting on the displayed list. They are not part of the selection- screen validation sequence. ### 16.2 ALV/SALV For tabular results, ALV/SALV typically provides sorting, filtering, totals, layout variants, and event callbacks. Keep retrieval and business logic independent from the chosen renderer so they can be tested without a GUI. ```text Selection model → application service → result table → ALV adapter ``` --- ## 17. Complete Worked Flow ```abap REPORT zorder_extract. TABLES sscrfields. PARAMETERS: p_order RADIOBUTTON GROUP mode DEFAULT 'X' USER-COMMAND mode, p_file RADIOBUTTON GROUP mode, p_vbeln TYPE vbak-vbeln MODIF ID ord, p_path TYPE string LOWER CASE MODIF ID fil. INITIALIZATION. p_order = abap_true. AT SELECTION-SCREEN OUTPUT. LOOP AT SCREEN. CASE screen-group1. WHEN 'ORD'. screen-active = xsdbool( p_order = abap_true ). WHEN 'FIL'. screen-active = xsdbool( p_file = abap_true ). ENDCASE. MODIFY SCREEN. ENDLOOP. AT SELECTION-SCREEN ON VALUE-REQUEST FOR p_path. p_path = lcl_file_dialog=>choose_file( ). AT SELECTION-SCREEN. IF sscrfields-ucomm = 'ONLI'. IF p_order = abap_true AND p_vbeln IS INITIAL. MESSAGE e001(zreport) WITH 'Enter a sales order'. ENDIF. IF p_file = abap_true AND p_path IS INITIAL. MESSAGE e002(zreport) WITH 'Choose a file'. ENDIF. ENDIF. START-OF-SELECTION. lcl_application=>run( order_mode = p_order order = p_vbeln file_mode = p_file path = p_path ). ``` ### 17.1 Initial display ```text Program begins → INITIALIZATION selects order mode → OUTPUT activates p_vbeln and deactivates p_path → screen displayed ``` ### 17.2 User selects file mode ```text USER-COMMAND MODE → AT SELECTION-SCREEN handles round trip → OUTPUT deactivates p_vbeln and activates p_path → screen displayed again ``` ### 17.3 User presses F4 on path ```text F4 → ON VALUE-REQUEST FOR p_path → dialog result assigned → screen displayed again ``` ### 17.4 User presses Execute without a path ```text F8 / ONLI → AT SELECTION-SCREEN → MESSAGE E → START-OF-SELECTION does not run → OUTPUT → screen displayed for correction ``` ### 17.5 User presses Execute with valid input ```text F8 / ONLI → AT SELECTION-SCREEN validation succeeds → START-OF-SELECTION → lcl_application=>run( ) → result output ``` --- ## 18. Dialog, Background, and `SUBMIT` Are Different Entry Modes The main diagram describes an interactive SAP GUI execution. Reports can also run through a background job or `SUBMIT`. ### 18.1 Background job A job normally receives saved selection values through a variant and has no interactive user available for F4 help, popups, or correction dialogs. ```abap IF sy-batch = abap_true. " Use background-safe logging/output; never require a frontend file dialog ENDIF. ``` Selection-screen UI convenience is therefore not a reliable business-security boundary. Validate the effective execution input and authorization in a background-safe application layer. ### 18.2 `SUBMIT` ```abap SUBMIT ztarget_report WITH p_vbeln = order AND RETURN. ``` `SUBMIT` starts an executable program and supplies selection values. Additions such as `VIA SELECTION-SCREEN`, `USING SELECTION-SET`, background-job options, and list export change the invocation behavior. Dynamic report names are a security risk when they originate externally. Use an allowlist and proper authorization checks. ### 18.3 Design consequence Do not place core business rules only in F4 handlers, screen PBO, or GUI-only validation. Extract an application service that can receive the same input from dialog, job, test, or another allowed entry point. --- ## 19. Selection Screen Versus Application Validation | Concern | Selection-screen layer | Application/domain layer | | --------------------------- | -------------------------- | ---------------------------------------- | | Enable/disable a field | Yes | No | | Show F4 help | Yes | No | | Basic cross-field usability | Yes | Often repeated as invariant if important | | Authorization to read order | May provide early feedback | Must enforce before protected access | | Business invariant | Helpful early feedback | Must be authoritative | | Database consistency | No | Persistence/transaction boundary | | Background-safe execution | Not guaranteed | Required | This parallels RAP: UI metadata and value help improve interaction, while the backend business object must still enforce invariants and authorization. --- ## 20. Program Structure Recommendation ```text Executable report ├── selection-screen declarations ├── INITIALIZATION initial UI defaults ├── AT SELECTION-SCREEN OUTPUT dynamic UI state ├── AT SELECTION-SCREEN ... early input feedback └── START-OF-SELECTION thin application entry │ ▼ Application class ├── authorization ├── input validation ├── query/repository ├── domain transformation └── output adapter ``` Use includes only for source organization when necessary. They do not replace the method/class boundaries described in the [ABAP Modularization reference](./abap-modularization-technical-reference.md). Use explicit internal-table types and access patterns from the [ABAP Internal Tables reference](./abap-internal-tables-technical-reference.md). --- ## 21. Transaction and Side-Effect Rules - Do not update persistent business data during `INITIALIZATION` or screen PBO. - F4/F1 handlers should provide help, not perform commits. - Separate report/query output from update transactions where possible. - If the report performs updates, document authorization, locking, validation, update API, commit ownership, restart behavior, and audit logging. - Do not call `COMMIT WORK` inside a reusable helper that does not own the whole SAP LUW. - A report that calls a BAPI/function module must inspect whether that API performs commits or expects the caller to commit. - For RAP business objects, use EML and allow RAP to own its transaction model; do not reproduce RAP save behavior in a classic report. --- ## 22. Debugging and Operations Map | Need | Classic tool/transaction | Evidence | | --------------------------- | ------------------------------------------------------- | ------------------------------------------- | | Execute/test report | `SE38` or `SA38` | Selection values, event behavior, output | | Repository navigation | `SE80` or ADT | Program, includes, classes, where-used | | Debug event sequence | ADT/SAP GUI debugger | Breakpoints in each event block; call stack | | Analyze short dump | `ST22` | Runtime error, source position, call stack | | Runtime performance | `SAT` | Call hierarchy and ABAP runtime cost | | SQL trace | `ST05` | SQL statements, executions, rows, duration | | System-wide SQL aggregation | `SQLM` where available | Repeated SQL workload evidence | | Background execution | `SM37` | Job step, variant, spool, status, job log | | Authorization failure | `SU53` immediately after failure; trace when authorized | Failed authorization objects/fields | | Application log | `SLG1` when the report writes application logs | Durable business/technical messages | ### 22.1 Event-flow debugging sequence 1. Set breakpoints in `LOAD-OF-PROGRAM`, `INITIALIZATION`, `AT SELECTION-SCREEN OUTPUT`, the relevant field/value-help event, generic `AT SELECTION-SCREEN`, and `START-OF-SELECTION`. 2. Start a new execution context and record which breakpoints occur. 3. Trigger a radio-button user command and observe the PAI → PBO redisplay loop. 4. Trigger F4 and distinguish its request path. 5. Execute once with invalid input and prove that `START-OF-SELECTION` is not reached. 6. Execute with valid input and inspect the transition to the application method. 7. Repeat in background only after removing GUI-dependent assumptions. --- ## 23. Common Misinterpretations | Misinterpretation | Correction | | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | “ABAP executes a report top to bottom.” | The runtime invokes event blocks according to the report and screen lifecycle. | | “`LOAD-OF-PROGRAM` is implicit and cannot be defined.” | It is a definable program-constructor event, though rarely needed in an ordinary report. | | “`INITIALIZATION` runs before every display.” | It initializes before the first standard-screen processing; PBO can repeat. | | “Changing any radio button immediately triggers an event.” | Immediate round trip requires an associated `USER-COMMAND` or another screen command. | | “F4 executes `AT SELECTION-SCREEN` like F8.” | Custom F4 uses `ON VALUE-REQUEST`; it does not start report execution. | | “`OUTPUT` means report result output.” | `AT SELECTION-SCREEN OUTPUT` is selection-screen PBO before display. | | “Every `AT SELECTION-SCREEN` event always runs.” | The triggered variants depend on fields and the user's action. | | “F8 directly calls `START-OF-SELECTION`.” | Selection-screen PAI and validation must succeed first. | | “`END-OF-SELECTION` is mandatory.” | It is especially meaningful with logical databases and is not required for every report. | | “A required screen field enforces the business rule everywhere.” | Screen checks do not replace application authorization and invariants. | | “Report event blocks are local procedures.” | Most event blocks work with compilation-unit global data; keep them thin. | | “The same interactive flow occurs in background.” | Background processing has no user-driven F4 or correction loop. | --- ## 24. Compact Event Reference | Event | Frequency/trigger | Main responsibility | | -------------------------------- | ------------------------------------------------- | -------------------------------------- | | `LOAD-OF-PROGRAM` | When program is loaded into internal session | Rare program-constructor logic | | `INITIALIZATION` | Before first standard selection-screen processing | Initial selection defaults | | `AT SELECTION-SCREEN OUTPUT` | Before every relevant display | Dynamic screen attributes | | `... ON VALUE-REQUEST FOR field` | User presses F4 | Custom value help | | `... ON HELP-REQUEST FOR field` | User presses F1 | Custom field help | | `... ON field` | Selection-screen PAI for field | Field validation | | `... ON END OF selcrit` | Whole selection criterion available | Multiple/range validation | | `... ON RADIOBUTTON GROUP group` | Radio group processed in PAI | Group validation | | `... ON BLOCK block` | Block processed in PAI | Related-field validation | | `AT SELECTION-SCREEN` | General PAI event | Command and cross-field validation | | `... ON EXIT-COMMAND` | Exit-type command | Safe leave/cleanup behavior | | `START-OF-SELECTION` | Selection processing succeeded | Main application entry | | `GET node` | Logical database provides node | Legacy logical-database row processing | | `END-OF-SELECTION` | Selection/logical DB processing completes | Legacy/final report processing | | List events | User/page activity on classic list | Classic output interaction | --- 32:T9dd,1. The Correct Overall Mental Model A classic executable report is event-driven. Source-code position does not mean that ABAP simply executes every line from top to bottom. The ABAP runtime framework raises events and calls the matching event blocks. The selection screen also creates a loop: text Program requested │ ▼ Program loaded into internal session, if not already loaded │ ├─ global/static initialization performed by runtime └─ LOAD-OF-PROGRAM event block, if defined │ ▼ INITIALIZATION │ ▼ AT SELECTION-SCREEN OUTPUT selection-screen PBO │ ▼ Selection screen displayed │ ▼ User action │ ├─ F4 help ───────────────► ON VALUE-REQUEST FOR field │ │ │ └─ redisplay loop │ ├─ F1 help ───────────────► ON HELP-REQUEST FOR field │ │ │ └─ redisplay loop │ ├─ Enter / pushbutton / │ radio USER-COMMAND ────► selection-screen PAI events │ │ │ └─ AT SELECTION-SCREEN OUTPUT │ → redisplay │ └─ Execute F8 ─────────────► selection-screen PAI validation │ ├─ validation error │ └─ OUTPUT → redisplay │ └─ validation succeeds └─ START-OF-SELECTION │ ├─ report application logic ├─ END-OF-SELECTION, if defined └─ output/list processing The straight-line version from the initial draft omitted the redisplay cycle. AT SELECTION-SCREEN OUTPUT can run many times; INITIALIZATION normally runs once for that report execution before the standard selection screen first appears. --- 2. Report Source Layout Versus Runtime Order A maintainable report can be arranged like this: abap REPORT zsalesorderreport. " Global declarations and selection-screen definition TABLES sscrfields. PARAMETERS: popen RADIOBUTTON GROUP mode DEFAULT 'X' USER-COMMAND mode, pall RADIOBUTTON GROUP mode. SELECT-OPTIONS sorder FOR vbak-vbeln. CLASS lclapplication DEFINITION FINAL. PUBLIC SECTION. CLASS-METHODS run. ENDCLASS. CLASS lclapplication IMPLEMENTATION. METHOD run. " Application orchestration ENDMETHOD. ENDCLASS. INITIALIZATION. " One-time selection defaults AT SELECTION-SCREEN OUTPUT. " Dynamic screen attributes before each display AT SELECTION-SCREEN. " Cross-field/action validation START-OF-SELECTION. lclapplication=run( ). The physical order improves readability, but runtime execution is determined by events. Each event block begins with an event keyword and ends at the next processing block or the end of33:Tc52,## 1. The Correct Overall Mental Model A classic executable report is **event-driven**. Source-code position does not mean that ABAP simply executes every line from top to bottom. The ABAP runtime framework raises events and calls the matching event blocks. The selection screen also creates a loop: ```text Program requested │ ▼ Program loaded into internal session, if not already loaded │ ├─ global/static initialization performed by runtime └─ LOAD-OF-PROGRAM event block, if defined │ ▼ INITIALIZATION │ ▼ AT SELECTION-SCREEN OUTPUT selection-screen PBO │ ▼ Selection screen displayed │ ▼ User action │ ├─ F4 help ───────────────► ON VALUE-REQUEST FOR field │ │ │ └─ redisplay loop │ ├─ F1 help ───────────────► ON HELP-REQUEST FOR field │ │ │ └─ redisplay loop │ ├─ Enter / pushbutton / │ radio USER-COMMAND ────► selection-screen PAI events │ │ │ └─ AT SELECTION-SCREEN OUTPUT │ → redisplay │ └─ Execute F8 ─────────────► selection-screen PAI validation │ ├─ validation error │ └─ OUTPUT → redisplay │ └─ validation succeeds └─ START-OF-SELECTION │ ├─ report application logic ├─ END-OF-SELECTION, if defined └─ output/list processing ``` The straight-line version from the initial draft omitted the redisplay cycle. `AT SELECTION-SCREEN OUTPUT` can run many times; `INITIALIZATION` normally runs once for that report execution before the standard selection screen first appears. --- ## 2. Report Source Layout Versus Runtime Order A maintainable report can be arranged like this: ```abap REPORT zsales_order_report. " Global declarations and selection-screen definition TABLES sscrfields. PARAMETERS: p_open RADIOBUTTON GROUP mode DEFAULT 'X' USER-COMMAND mode, p_all RADIOBUTTON GROUP mode. SELECT-OPTIONS s_order FOR vbak-vbeln. CLASS lcl_application DEFINITION FINAL. PUBLIC SECTION. CLASS-METHODS run. ENDCLASS. CLASS lcl_application IMPLEMENTATION. METHOD run. " Application orchestration ENDMETHOD. ENDCLASS. INITIALIZATION. " One-time selection defaults AT SELECTION-SCREEN OUTPUT. " Dynamic screen attributes before each display AT SELECTION-SCREEN. " Cross-field/action validation START-OF-SELECTION. lcl_application=>run( ). ```34:T7d7b, ## 1. What ALV Is — and Is Not ALV, the SAP List Viewer, is a presentation framework for structured datasets. It can supply standard user functions such as sorting, filtering, totals, subtotals, layouts, printing, and export. ```text Database / CDS / released API │ ▼ Application reads, authorizes, and derives data │ ▼ Internal table = report output model │ ▼ ALV renders List, Grid, or Tree │ ▼ User sorts, filters, selects, navigates, or edits ``` ALV does **not** by itself: - read the correct business data; - authorize a user to see or change that data; - enforce business invariants; - persist edited cells; - fix duplicate rows caused by an incorrect SQL join; - turn a classic report into a Fiori or RAP application. Think of ALV as the report's **view and interaction adapter**. The internal table is its input model; application methods own the business behavior. --- ## 2. End-to-End Runtime Flow For a read-only executable report using SALV: ```text Program/report starts │ ▼ Selection-screen lifecycle │ defaults → dynamic PBO → user input → validation ▼ START-OF-SELECTION │ ├─ authorize requested scope ├─ read through an appropriate CDS view/API/Open SQL ├─ calculate and map the output model └─ return an internal table │ ▼ CL_SALV_TABLE=>FACTORY │ ├─ configure functions, columns, sorts, layout, events └─ DISPLAY │ ▼ User sorts/filters/totals/exports or triggers navigation ``` For an editable GUI grid, the display is only half the workflow: ```text Application internal table │ ▼ CL_GUI_ALV_GRID display │ ▼ User edits a frontend cell │ ├─ REGISTER_EDIT_EVENT / DATA_CHANGED └─ CHECK_CHANGED_DATA transfers/checks pending frontend changes │ ▼ Application validates values and authorization │ ├─ invalid → protocol/message; do not save └─ valid → released update API / BAPI / application service / EML │ ▼ transaction owner commits │ ▼ refresh application data and ALV ``` The decisive point is: **an editable cell is not a database update**. `CHECK_CHANGED_DATA` is part of synchronizing/validating the grid state; it is not persistence. --- ## 3. The Three Presentation Shapes People often say “ALV list, grid, and tree.” These are presentation shapes, not three levels of the same report. | Shape | Data relationship | Best fit | Typical technology | | -------- | ------------------------------------------------ | ---------------------------------------- | -------------------------------------------------------------------------- | | **List** | Flat rows or classic two-level sequential output | Printing, spool, legacy reports | Classic ALV list; `CL_SALV_HIERSEQ_TABLE` for two-level header/item output | | **Grid** | Flat two-dimensional table | Interactive analysis; optionally editing | `CL_SALV_TABLE` or `CL_GUI_ALV_GRID` | | **Tree** | Nodes with explicit parent/child relationships | Hierarchy navigation | `CL_SALV_TREE` or `CL_GUI_ALV_TREE` | SAP's ALV object model names the core structural forms more precisely: - `CL_SALV_TABLE`: simple, two-dimensional table; - `CL_SALV_HIERSEQ_TABLE`: hierarchical-sequential header/item list; - `CL_SALV_TREE`: arbitrary tree structure. Therefore, “list versus grid” can also describe the **rendering technology** of a simple table, while table versus hierarchy describes the **data shape**. Ask which meaning a colleague intends before choosing a class. ### 3.1 List view A list-oriented result is appropriate when printable sequential output matters more than rich cell interaction. It is also the conceptually safer direction for a background job that must create spool output. For the SALV simple-table model, the factory's `LIST_DISPLAY` choice selects a classic list-style rendering instead of the normal fullscreen grid rendering: ```abap cl_salv_table=>factory( EXPORTING list_display = abap_true IMPORTING r_salv_table = DATA(alv) CHANGING t_table = output ). alv->display( ). ``` This is an important distinction: `CL_SALV_TABLE` identifies the simple two-dimensional **data model**; `LIST_DISPLAY` influences its **display mode**. Always test printing and background behavior on the target release rather than inferring it only from the class name. Classic APIs such as `REUSE_ALV_LIST_DISPLAY` and `REUSE_ALV_GRID_DISPLAY_LVC` still appear in existing systems. Their `SLIS_*` and `LVC_*` metadata must be understood for maintenance, but new OO-oriented code should normally consider the ALV object model first when its capabilities fit. ### 3.2 Grid view A grid displays a flat table with columns and rows. Choose: - `CL_SALV_TABLE` for concise, mostly read-only reporting; - `CL_GUI_ALV_GRID` when you need editable cells, detailed grid events, a custom toolbar, or precise embedding in a screen/container. ### 3.3 Tree view A tree represents real hierarchy. Each node has identity and a relationship to a parent node. Sorting a flat table and indenting text does not create a sound tree model. Examples: ```text Sales Order 50000123 ├─ Item 10 │ ├─ Schedule line 1 │ └─ Schedule line 2 └─ Item 20 └─ Schedule line 1 ``` Use `CL_SALV_TREE` for a high-level tree display and `CL_GUI_ALV_TREE` when the application needs lower-level control. Use `CL_SALV_HIERSEQ_TABLE` when the model is exactly two sequential levels, such as header and items, rather than an arbitrary-depth tree. --- ## 4. Selection Guide | Requirement | Recommended starting point | Reason | | --------------------------------------- | -------------------------------------------- | ---------------------------------------- | | Quick read-only flat report | `CL_SALV_TABLE` | Minimal setup and standard ALV functions | | Editable cells | `CL_GUI_ALV_GRID` | Supported grid edit/event lifecycle | | Custom toolbar and fine-grained events | `CL_GUI_ALV_GRID` | Direct Control Framework integration | | Arbitrary parent/child hierarchy | `CL_SALV_TREE` | Node-oriented hierarchy model | | Highly customized hierarchy control | `CL_GUI_ALV_TREE` | Lower-level tree behavior | | Exactly header + item sequential levels | `CL_SALV_HIERSEQ_TABLE` | Matches the two-level data shape | | Background/spool-oriented output | List/spool-safe design | GUI controls require a frontend | | Very large HANA-backed result | Consider ALV with IDA, if available/released | Pushes paging/filtering toward HANA | Do not choose `CL_GUI_ALV_GRID` merely because it is more powerful. Its screen, container, frontend-state, event, and lifetime responsibilities are real complexity. --- ## 5. The Output Internal Table Is a View Model Do not send a persistence table to ALV merely because it already has fields. Define the output grain and only expose columns that serve the report. ```abap TYPES: BEGIN OF ty_order_output, sales_order TYPE vbak-vbeln, sold_to_party TYPE vbak-kunnr, overall_status TYPE c LENGTH 1, net_amount TYPE p LENGTH 15 DECIMALS 2, currency TYPE waers, END OF ty_order_output, ty_order_output_tab TYPE STANDARD TABLE OF ty_order_output WITH EMPTY KEY. ``` The model should contain: - the business key needed for navigation or update; - display values at one explicitly chosen grain; - currency/unit reference fields for amounts and quantities; - optional technical style/color fields required by an editable grid; - no sensitive fields merely “hidden” from the initial layout. Hiding a field with `NO_OUT` or a saved layout is presentation, not security. Protect the read before building the output table, and assume export/layout features can reveal any field supplied to the frontend. ### 5.1 Preserve the grain If one order header is joined to ten items and the header amount repeats ten times, ALV totals will correctly total the rows it received—and produce the wrong business answer. Fix the query/output grain rather than blaming ALV. --- ## 6. `CL_SALV_TABLE`: Read-Only Table with Minimal Ceremony `CL_SALV_TABLE` is the normal first choice for a flat display-only report. The factory receives the output internal table, creates the ALV model, and returns the main SALV object. ```abap CLASS lcl_output DEFINITION FINAL. PUBLIC SECTION. CLASS-METHODS display CHANGING orders TYPE ty_order_output_tab. ENDCLASS. CLASS lcl_output IMPLEMENTATION. METHOD display. TRY. cl_salv_table=>factory( IMPORTING r_salv_table = DATA(alv) CHANGING t_table = orders ). alv->get_functions( )->set_all( abap_true ). alv->get_columns( )->set_optimize( abap_true ). alv->get_display_settings( )->set_striped_pattern( abap_true ). alv->display( ). CATCH cx_salv_msg INTO DATA(error). MESSAGE error->get_text( ) TYPE 'E'. ENDTRY. ENDMETHOD. ENDCLASS. ``` Typical caller: ```abap START-OF-SELECTION. DATA(orders) = lcl_order_query=>execute( sales_orders = s_vbeln[] ). lcl_output=>display( CHANGING orders = orders ). ``` ### 6.1 What SALV owns SALV offers subobjects for configuration: ```text CL_SALV_TABLE ├─ GET_FUNCTIONS( ) standard toolbar functions ├─ GET_COLUMNS( ) column collection ├─ GET_SORTS( ) initial sorting ├─ GET_AGGREGATIONS( ) totals/aggregations ├─ GET_SELECTIONS( ) selection behavior/state ├─ GET_DISPLAY_SETTINGS( ) general appearance ├─ GET_LAYOUT( ) layout variants └─ GET_EVENT( ) SALV events ``` ### 6.2 Configure one column ```abap TRY. DATA(columns) = alv->get_columns( ). DATA(column) = columns->get_column( 'NET_AMOUNT' ). column->set_short_text( 'Net' ). column->set_medium_text( 'Net Amount' ). column->set_long_text( 'Sales Order Net Amount' ). CATCH cx_salv_not_found. " Programming/configuration mismatch: field is not in the output model ENDTRY. ``` Names passed to SALV refer to the ABAP component names in the output line type, usually interpreted in uppercase. A DDIC-backed component lets ALV reuse field labels, conversion exits, value help, and type semantics more reliably than an unrelated primitive type. ### 6.3 SALV editing boundary The supported `CL_SALV_TABLE` public model is display-oriented. Do not rely on release-dependent or unsupported tricks that extract an underlying GUI grid to make SALV editable. If editing is a real requirement, choose `CL_GUI_ALV_GRID` and implement the complete edit, validation, authorization, and persistence lifecycle explicitly. --- ## 7. SALV Events: Navigation, Not Business Trust A SALV double-click can navigate to an order detail, but the row number is only presentation state. After users sort and filter, row position is not a stable business identity. Conceptual event-handler shape: ```abap CLASS lcl_salv_handler DEFINITION FINAL. PUBLIC SECTION. METHODS on_double_click FOR EVENT double_click OF cl_salv_events_table IMPORTING row column. ENDCLASS. ``` Registration: ```abap DATA(events) = alv->get_event( ). DATA(handler) = NEW lcl_salv_handler( ). SET HANDLER handler->on_double_click FOR events. ``` Keep the handler object alive for as long as the ALV can raise events. In the handler: 1. resolve the selected row against the current output model; 2. extract its business key; 3. recheck authorization and current state; 4. call an application navigation/action method. Never treat “the user could see or select row 5” as authorization to update the business object represented by row 5. --- ## 8. `CL_GUI_ALV_GRID`: Control-Based Grid Architecture `CL_GUI_ALV_GRID` is a SAP GUI Control Framework control. It requires a parent container and therefore participates in a dynpro's PBO/PAI lifecycle. ```text Executable report │ └─ CALL SCREEN 0100 │ ├─ PBO: create custom container once │ create grid once │ register handlers once │ first display once │ ├─ SAP GUI: user interacts with grid │ └─ PAI: synchronize changes and process command then return to PBO for refresh ``` Screen 0100 normally contains a Custom Control element named, for example, `ALV_CONTAINER`. ### 8.1 Persistent controller attributes The grid, container, event handler, and output table must outlive a single PBO method call. Keep them as suitable program-global references or, preferably, attributes of a screen-controller object. ```abap DATA: container TYPE REF TO cl_gui_custom_container, grid TYPE REF TO cl_gui_alv_grid, output TYPE ty_order_output_tab, field_catalog TYPE lvc_t_fcat, layout TYPE lvc_s_layo. ``` ### 8.2 PBO: create once, refresh later ```abap MODULE status_0100 OUTPUT. SET PF-STATUS 'MAIN'. IF grid IS INITIAL. container = NEW cl_gui_custom_container( container_name = 'ALV_CONTAINER' ). grid = NEW cl_gui_alv_grid( i_parent = container ). " Register event handlers here, before user interaction grid->set_table_for_first_display( EXPORTING is_layout = layout CHANGING it_outtab = output it_fieldcatalog = field_catalog ). ELSE. grid->refresh_table_display( is_stable = VALUE lvc_s_stbl( row = abap_true col = abap_true ) ). ENDIF. ENDMODULE. ``` SAP documents `SET_TABLE_FOR_FIRST_DISPLAY` as the initial binding operation. Call `REFRESH_TABLE_DISPLAY` when only the data changes. Repeat the initial call only when the output structure changes. ### 8.3 PAI: process commands ```abap MODULE user_command_0100 INPUT. CASE sy-ucomm. WHEN 'SAVE'. lcl_screen_controller=>save( ). WHEN 'BACK' OR 'EXIT' OR 'CANC'. LEAVE TO SCREEN 0. ENDCASE. ENDMODULE. ``` The GUI status decides which function codes exist. The ALV grid can also raise toolbar and `USER_COMMAND` events for grid-specific functions. --- ## 9. Field Catalog: Structural and UI Metadata `CL_GUI_ALV_GRID` commonly uses `LVC_T_FCAT`, whose line type is `LVC_S_FCAT`. Important fields include: | Field | Meaning | | -------------------------- | ------------------------------------------------ | | `FIELDNAME` | Component in the output line type | | `COLTEXT`, `SCRTEXT_S/M/L` | Column labels | | `KEY` | Visually identifies a key column | | `NO_OUT` | Initially hides a column; not a security control | | `EDIT` | Makes a cell/column input-enabled in the grid | | `HOTSPOT` | Enables hotspot interaction | | `CHECKBOX` | Displays a checkbox-compatible field | | `DO_SUM` | Requests totals where supported | | `REF_TABLE`, `REF_FIELD` | Reuses DDIC metadata | | `CFIELDNAME` | Currency-reference component for an amount | | `QFIELDNAME` | Unit-reference component for a quantity | You can let the grid derive metadata from a single DDIC structure by passing `I_STRUCTURE_NAME`, or pass an explicit field catalog for a local/mixed output type and custom UI behavior. Example helper: ```abap APPEND VALUE lvc_s_fcat( fieldname = 'NET_AMOUNT' coltext = 'Net Amount' cfieldname = 'CURRENCY' do_sum = abap_true ) TO field_catalog. ``` Metadata names must match the actual output structure. A field catalog does not map database fields into differently named ABAP components; build that mapping when selecting or transforming the output model. --- ## 10. Editable Grid Lifecycle Setting `EDIT = abap_true` only changes the frontend interaction. A complete edit flow has five separate responsibilities. ### 10.1 Enable and register ```abap grid->register_edit_event( i_event_id = cl_gui_alv_grid=>mc_evt_modified ). SET HANDLER handler->on_data_changed FOR grid. ``` Common grid events include `DATA_CHANGED`, `DATA_CHANGED_FINISHED`, `DOUBLE_CLICK`, `HOTSPOT_CLICK`, `TOOLBAR`, and `USER_COMMAND`. ### 10.2 Validate pending changes Before a Save command uses the output table, synchronize pending frontend edits: ```abap DATA valid TYPE abap_bool. grid->check_changed_data( IMPORTING e_valid = valid ). CHECK valid = abap_true. ``` This is especially important when a user types into a cell and immediately presses Save without first leaving the cell or pressing Enter. ### 10.3 Separate UI checks from business checks The `DATA_CHANGED` handler can give immediate feedback about syntax, domains, or cross-cell relationships. The application service must still enforce: - current authorization; - optimistic-lock/version rules; - business invariants; - current database state; - transactional consistency. Client-side or ALV-event validation is not a security boundary. ### 10.4 Persist explicitly Use the system's supported change contract: for example a released API, BAPI, application service, or EML for a RAP BO. Do not perform an arbitrary direct table update simply because the grid output resembles the table. The transaction owner decides the commit/rollback boundary. Reusable methods should not casually issue `COMMIT WORK` when their caller owns the larger unit of work. ### 10.5 Re-read and refresh After successful persistence, re-read authoritative state when calculations, status changes, locks, or other users may have changed the record. Then refresh the grid while preserving row/column stability where appropriate. --- ## 11. Row Index Versus Business Identity ALV selection APIs frequently return display row indexes. Sorting and filtering can change what an index refers to. ```text Unsafe assumption: selected index 3 = database record originally loaded at index 3 Safe flow: current selected index → current output row → immutable business key → fresh authorization/state check → business operation ``` For SD-style data, carry `VBELN`, `POSNR`, and `ETENR` at the appropriate grain even if some technical key columns are not initially prominent. For a RAP BO, carry its actual entity key; an ALV row number is not `%tky`. --- ## 12. List and Background Processing `CL_GUI_ALV_GRID` needs the SAP GUI Control Framework and a frontend container. It is not a background-processing output mechanism. For a report that also runs as a job, design output behind an interface: ```text Application produces typed result table │ ├─ dialog renderer → SALV/grid ├─ job renderer → spool/list or file └─ test renderer → assertions on result table ``` In background: - there is no user-driven grid interaction; - frontend-dependent controls are unavailable; - selection variants supply input; - operational evidence belongs in job log, spool, application log, or a deliberately produced file. Do not assume that a SALV call automatically provides the exact background spool behavior the business needs. Test the chosen display mode in the target release and execution environment. --- ## 13. Tree Data Modeling A tree has two distinct concerns: ```text Hierarchy model Display data ------------------------------ -------------------------- node key node text parent/related node key amount/status/attributes relationship type icons and column values ``` With `CL_SALV_TREE`, the application creates nodes individually, relates each node to a parent or sibling, and assigns the node's data row. Node keys are ALV technical identities; keep business keys separately for navigation. Choose a tree only when users need to reason about containment or dependency. If they mainly compare amounts across many orders, a flat grid grouped and sorted by order is usually easier to scan. ### Tree risks - one cyclic or missing parent breaks hierarchy construction; - eager expansion of a huge tree overwhelms users and memory; - totals across levels can double count parent and child values; - a selected node key is still not authorization; - loading every deep child before it is expanded can be unnecessarily costly. --- ## 14. Currency, Quantity, Totals, and Semantics An amount without its currency and a quantity without its unit are incomplete business values. For a grid field catalog, connect amount/quantity components to the output components holding currency/unit via `CFIELDNAME` and `QFIELDNAME`. Prefer DDIC reference fields where available. Do not total values across different currencies merely because ALV permits a numeric total. Either: - group/subtotal by currency; - convert using an explicit business rule and date/rate type; - suppress a meaningless grand total. The same principle applies to incompatible quantity units. --- ## 15. Layout Variants ALV layouts can store presentation preferences such as column order, width, visibility, sorting, filtering, and totals. Variant identity is commonly described using `DISVARIANT` values such as report and handle, with save scope controlled by the ALV API. Keep three ideas separate: ```text Selection variant → input parameters and select-options ALV layout variant → result presentation Business variant → domain-specific configuration, if any ``` An ALV layout filter does not reduce the database query or replace read authorization. The data may already have reached the frontend before the user hides it. When changing an output structure, test existing saved layouts. Renamed or removed columns can make old variants behave unexpectedly. --- ## 16. Performance Model ALV can sort and filter its supplied dataset, but it cannot undo an over-fetching query. ```text Best order of responsibility: 1. database/API restricts rows and columns 2. application derives the exact report grain 3. ALV provides interactive presentation operations ``` For performance diagnosis: 1. measure the data-access phase separately from rendering; 2. inspect SQL with SQL Monitor/ST05 when appropriate; 3. check row count and output width; 4. look for joins that multiply rows; 5. avoid expensive per-row database queries; 6. consider HANA-oriented ALV with IDA for supported large-data scenarios; 7. test frontend rendering and export separately. `CL_SALV_GUI_TABLE_IDA` can support database-oriented paging/filtering on HANA in systems where the class and data source are suitable. It is not a drop-in reason to ignore data authorization, released-object rules, or the target system's API state. --- ## 17. Authorization and Data Protection Apply authorization before sensitive data enters the ALV output model. ```text Wrong boundary: SELECT everything → send to ALV → hide unauthorized column Correct boundary: authorize scope → select allowed data/fields → build output → display ``` For an action or save, authorize again against the current record and requested operation. Read authorization does not imply update, delete, approve, or export authorization. Also consider: - spreadsheet/local-file export; - print/spool access; - saved layout variants; - personal data displayed in diagnostic columns; - transaction navigation from double-click/hotspot events. --- ## 18. Error and Message Design Handle errors at the layer that understands them: | Error | Owning layer | Example response | | ------------------------------ | ---------------------------------- | ------------------------------------------ | | Invalid selection interval | Selection-screen/application input | Field/cross-field message | | User cannot read company code | Authorization/application service | Reject before output | | SALV column not found | ALV configuration | Developer-facing handling/log | | Invalid edited amount | Grid handler + business service | Cell protocol and no save | | Record changed by another user | Persistence/business API | Conflict message and refresh | | Database/API failure | Data-access layer | Logged technical cause + safe user message | An empty result is not always an error. Distinguish “no matching authorized records” from a broken query or swallowed exception. --- ## 19. Common Failure Patterns | Symptom | Likely cause | Diagnostic move | | ----------------------------------- | -------------------------------------- | --------------------------------------------- | | Empty ALV | Query/filter/auth produced no rows | Inspect result table before display | | Wrong/missing columns | Field catalog and line type disagree | Compare `FIELDNAME` with actual components | | Amount displayed without currency | Missing DDIC/currency reference | Set reference metadata/`CFIELDNAME` | | Total is multiplied | Header repeated by item/schedule join | Reconstruct result grain before ALV | | Edit disappears on Save | Pending frontend edit not synchronized | Call `CHECK_CHANGED_DATA` and inspect handler | | Edit appears saved but DB unchanged | Only output internal table changed | Trace explicit persistence call/transaction | | Grid resets on every action | Grid recreated in every PBO | Create once; refresh subsequently | | Handler stops firing | Handler reference went out of scope | Keep handler alive with the control | | Wrong record opened after sort | Original index treated as identity | Resolve current row and use business key | | Background job fails | GUI control requires frontend | Use a background-safe renderer | | Hidden data appears in export | UI hiding treated as security | Do not send unauthorized fields | | Refresh jumps/loses context | Unstable refresh | Use stable row/column options where suitable | --- ## 20. Classic ALV APIs Versus Modern Direction | Technology | Status/use | Main concern | | ------------------------------ | ---------------------------------------------- | ------------------------------------------ | | `REUSE_ALV_LIST_DISPLAY` | Common legacy list reports | Procedural callback and `SLIS_*` patterns | | `REUSE_ALV_GRID_DISPLAY(_LVC)` | Common legacy grid reports | Function-module callbacks and global state | | `CL_SALV_TABLE` | Preferred concise OO display where it fits | Read-only/public display model | | `CL_GUI_ALV_GRID` | Appropriate for rich classic GUI control needs | More lifecycle and event responsibility | | RAP + Fiori elements | Service/UI architecture, not ALV | CDS/behavior/OData/UI annotation lifecycle | When maintaining a legacy report, improve boundaries without rewriting solely for fashion. Extract authorization, query, transformation, and update logic from callbacks first. Then the renderer can be replaced independently if the business case justifies it. --- ## 21. SD Technical-Consultant Example Suppose a report shows sales-order schedule fulfillment. ### Output grain One row per sales order item schedule line: ```text VBELN + POSNR + ETENR ``` ### Flow ```text Selection: sales org, document/date range, status │ ├─ authorize organizational scope ├─ read released CDS/API or appropriate classic source ├─ construct one row per schedule line ├─ preserve order/item/schedule keys ├─ derive open quantity without mixing units └─ render read-only with CL_SALV_TABLE ``` A double-click can navigate to display the business document after a fresh authorization check. If the requirement becomes “mass-change requested dates,” that is not just `EDIT = X`: choose `CL_GUI_ALV_GRID`, capture changes, validate SD rules, call a supported sales-order change contract, handle conflicts and messages, and refresh authoritative results. In clean-core design, prefer released CDS views/APIs and verify API State in the target release. Directly updating `VBAK`, `VBAP`, or `VBEP` is not a valid business update mechanism. --- ## 22. Tools and Debugging Landmarks | Tool/object | Use | | ------------------------------ | --------------------------------------------------- | | `SE38` / `SA38` | Execute or inspect classic reports, where available | | ADT debugger | Break before display, handlers, and save service | | `SE24` | Inspect class interfaces in classic systems | | `DWDM`, `SE83`, `BCALV*` demos | Explore installed Control Framework examples | | `ST22` | Analyze runtime dumps | | `SAT` | Separate query/transformation/rendering time | | `ST05`, SQL Monitor | Diagnose data access, not ALV formatting | | `SU53` / authorization trace | Diagnose authorization failure appropriately | | `SM37` and `SP01` | Background job and spool evidence | Availability and recommended tools vary by edition and authorization. A demo program illustrates an API; it is not automatically a production architecture. --- ## 23. Implementation Checklist ### Before coding - What is one output row? - Is the result flat, exactly two-level, or an arbitrary hierarchy? - Is it read-only or genuinely transactional? - Must it run in background? - Which fields and rows may the user read/export? - What is the supported data/change API in this system edition? ### For `CL_SALV_TABLE` - Build a typed, authorized result table. - Call `FACTORY`, configure subobjects, then `DISPLAY`. - Keep event handlers alive. - Resolve navigation through business keys, not row indexes. - Do not use unsupported SALV-edit hacks. ### For `CL_GUI_ALV_GRID` - Create a custom screen and parent container. - Keep container, grid, handler, and output alive. - Call `SET_TABLE_FOR_FIRST_DISPLAY` once. - Register required events. - Synchronize pending edits before Save. - Validate and authorize in the business layer. - Persist through the supported contract. - Re-read and call `REFRESH_TABLE_DISPLAY`. - Provide a separate output path for background processing. --- 35:T850,1. What ALV Is — and Is Not ALV, the SAP List Viewer, is a presentation framework for structured datasets. It can supply standard user functions such as sorting, filtering, totals, subtotals, layouts, printing, and export. text Database / CDS / released API │ ▼ Application reads, authorizes, and derives data │ ▼ Internal table = report output model │ ▼ ALV renders List, Grid, or Tree │ ▼ User sorts, filters, selects, navigates, or edits ALV does not by itself: - read the correct business data; - authorize a user to see or change that data; - enforce business invariants; - persist edited cells; - fix duplicate rows caused by an incorrect SQL join; - turn a classic report into a Fiori or RAP application. Think of ALV as the report's view and interaction adapter. The internal table is its input model; application methods own the business behavior. --- 2. End-to-End Runtime Flow For a read-only executable report using SALV: text Program/report starts │ ▼ Selection-screen lifecycle │ defaults → dynamic PBO → user input → validation ▼ START-OF-SELECTION │ ├─ authorize requested scope ├─ read through an appropriate CDS view/API/Open SQL ├─ calculate and map the output model └─ return an internal table │ ▼ CLSALVTABLE=FACTORY │ ├─ configure functions, columns, sorts, layout, events └─ DISPLAY │ ▼ User sorts/filters/totals/exports or triggers navigation For an editable GUI grid, the display is only half the workflow: text Application internal table │ ▼ CLGUIALVGRID display │ ▼ User edits a frontend cell │ ├─ REGISTEREDITEVENT / DATACHANGED └─ CHECKCHANGEDDATA transfers/checks pending frontend changes │ ▼ Application validates values and authorization │ ├─ invalid → protocol/message; do not save └─ valid → released update API / BAPI / application service / EML │ ▼ transaction owner commits │ ▼ refresh application data and ALV The decisive point is: an editable cell is not a database update. CHECKCHANGEDDATA is part of synchronizing/validating the grid state; it is not persistence. --- 3. The36:T92f,## 1. What ALV Is — and Is Not ALV, the SAP List Viewer, is a presentation framework for structured datasets. It can supply standard user functions such as sorting, filtering, totals, subtotals, layouts, printing, and export. ```text Database / CDS / released API │ ▼ Application reads, authorizes, and derives data │ ▼ Internal table = report output model │ ▼ ALV renders List, Grid, or Tree │ ▼ User sorts, filters, selects, navigates, or edits ``` ALV does **not** by itself: - read the correct business data; - authorize a user to see or change that data; - enforce business invariants; - persist edited cells; - fix duplicate rows caused by an incorrect SQL join; - turn a classic report into a Fiori or RAP application. Think of ALV as the report's **view and interaction adapter**. The internal table is its input model; application methods own the business behavior. --- ## 2. End-to-End Runtime Flow For a read-only executable report using SALV: ```text Program/report starts │ ▼ Selection-screen lifecycle │ defaults → dynamic PBO → user input → validation ▼ START-OF-SELECTION │ ├─ authorize requested scope ├─ read through an appropriate CDS view/API/Open SQL ├─ calculate and map the output model └─ return an internal table │ ▼ CL_SALV_TABLE=>FACTORY │ ├─ configure functions, columns, sorts, layout, events └─ DISPLAY │ ▼ User sorts/filters/totals/exports or triggers navigation ``` For an editable GUI grid, the display is only half the workflow: ```text Application internal table │ ▼ CL_GUI_ALV_GRID display │ ▼ User edits a frontend cell │ ├─ REGISTER_EDIT_EVENT / DATA_CHANGED └─ CHECK_CHANGED_DATA transfers/checks pending frontend changes │ ▼ Application validates values and authorization │ ├─ invalid → protocol/message; do not save └─ valid → released update API / BAPI / application service / EML │ ▼ transaction owner commits │ ▼ refresh application data and ALV ```37:Tc28b, # SAP SD Order-to-Cash — Technical Architecture This document describes the technical structure and runtime boundaries of the SAP Sales and Distribution Order-to-Cash process. Its purpose is to connect the business-document chain to document grain, persistence landmarks, posting effects, document flow, diagnostic evidence, and clean-core integration contracts. The central architectural principle is: > Order-to-Cash is a graph of independently meaningful business documents and > postings. It is not one large database record, one status field, or one > transactional aggregate. This reference distinguishes three contexts: - **Classic SAP ERP and SAP S/4HANA on-premise/private edition**, where SAP GUI transactions and direct table inspection may be available for authorized diagnosis. - **SAP S/4HANA Cloud Public Edition**, where Fiori applications, configuration activities, and released APIs are the normal operational contracts. - **Clean-core extension development**, where released CDS entities, business objects, events, and APIs should be preferred over dependencies on internal persistence. Primary SAP sources: - [SAP Help — Sales Documents](https://help.sap.com/docs/SAP_S4HANA_CLOUD/a376cd9ea00d476b96f18dea1247e6a5/aa64b65334e6b54ce10000000a174cb4.html) - [SAP Learning — Navigating the Order-to-Cash Process Steps](https://learning.sap.com/courses/discovering-the-basics-of-sap-s-4hana-sales/executing-sales-order-management_cad9dfbe-bafc-4ed9-ac2e-6fd8422430e4) - [SAP Help — Sales Order Item Schedule Line](https://help.sap.com/docs/SAP_S4HANA_CLOUD/03c04db2a7434731b7fe21dca77440da/37df44581efca007e10000000a441470.html) - [SAP Help — Goods Issue](https://help.sap.com/docs/SAP_S4HANA_CLOUD/aff0b3f5f46c42a2b2c0fabfc233bab2/64f81a71edf5490ab522a829be075827.html?locale=en-US&version=LATEST) - [SAP Help — Billing Data Flow](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/ed84b70c199d4470ae2e5ccb93b2e45b/e26fb6535fe6b74ce10000000a174cb4.html) - [SAP Help — Displaying Goods Issue Documents](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/c7894a248ca14f74aca67f97528e5ad7/f91bbf53d25ab64ce10000000a174cb4.html) - [SAP Help — Delivery Document CDS View](https://help.sap.com/docs/SAP_S4HANA_CLOUD/c0c54048d35849128be8e872df5bea6d/e2966bcba73a455299b4937151dfd0a3.html) --- ## 1. Scope and System Boundaries ### 1.1 Core process The common sell-from-stock flow can be represented as: ```text Optional presales Core execution Inquiry → Quotation → Sales Order → Outbound Delivery → PGI → Billing → Payment ``` The technical meaning is clearer when the process is expressed as state transitions: ```text Customer interest ↓ Commercial offer ↓ Accepted demand and fulfillment intent ↓ Warehouse execution document ↓ Inventory and value posting ↓ Customer invoice and receivable ↓ Cash receipt and clearing ``` Inquiry and quotation are optional presales documents. Returns, credit memos, third-party sales, intercompany sales, milestone billing, consignment, and make-to-order processes follow different branches. The architecture in this document is therefore a baseline, not a claim that every SD transaction follows one identical path. SAP describes sales, delivery, and billing documents as individual documents that participate in a larger process flow and can be created with reference to predecessors. That reference copies relevant information and records process lineage; it does not merge all documents into one object. See [SAP Help — Sales Documents](https://help.sap.com/docs/SAP_S4HANA_CLOUD/a376cd9ea00d476b96f18dea1247e6a5/aa64b65334e6b54ce10000000a174cb4.html). ### 1.2 Responsibility boundaries | Boundary | Primary responsibility | New fact established | | ----------------- | ------------------------------------------------------ | -------------------------------------------------------- | | Presales | Sales | Interest or an offer is recorded | | Sales Order | Sales/order management | Accepted demand and commercial context are recorded | | Outbound Delivery | Shipping/warehouse execution | Deliverable quantities are organized for execution | | Post Goods Issue | Shipping, Inventory Management, accounting integration | Goods have left; stock and value effects are posted | | Billing | Billing and accounting integration | Customer invoice and accounting consequences are created | | Incoming payment | Financial Accounting | Cash is posted and an open receivable can be cleared | These are separate boundaries because they have different owners, validations, posting effects, reversal procedures, authorizations, and audit histories. ### 1.3 Architectural layers ```text User interaction SAP GUI transaction / Fiori app / external consumer │ ▼ Business operation create order / create delivery / post GI / create billing / post payment │ ▼ Application logic determination / copy control / validation / status / authorization │ ▼ Persistence and postings SD documents / material document / journal entry / clearing information │ ▼ Integration and analytics released API / CDS / event / IDoc / process flow / reporting ``` The persistence tables are implementation landmarks. The business operation is the contract. Creating a row that resembles an order or delivery is not equivalent to executing the corresponding SAP business operation. --- ## 2. End-to-End Document Lifecycle ### 2.1 Lifecycle matrix | Stage | Technical object | What becomes true | What remains unproven | | ----------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------- | | Inquiry | Sales document | Customer interest or request for information is recorded | No formal offer or accepted order | | Quotation | Sales document | A commercial offer with validity and terms exists | Customer acceptance is not guaranteed | | Sales Order | Sales document | Product, quantity, partner, price, date, and fulfillment intent are recorded | Delivery, PGI, invoice, and payment | | Outbound Delivery | Delivery document | Shipping execution has a document for quantities, dates, picking, packing, and goods movement | Goods issue may not be posted | | PGI | Material and accounting posting connected to delivery | Goods departure, stock reduction, and relevant value effects are recorded | Customer billing and cash receipt | | Billing | Billing document plus accounting integration | Invoice values are recorded and normally transferred to accounting | Incoming cash | | Incoming Payment | FI journal entry and clearing process | Cash receipt is recorded and can clear the open customer item | Completion of every other branch or open item | ### 2.2 Inquiry and quotation Inquiry and quotation normally use the sales-document architecture. They may contain header and item data and can participate in reference chains. They do not represent inventory movement or customer receivable postings. The quotation is best understood as a versioned commercial offer. Its validity, prices, quantities, and conditions can be copied into a subsequent order under configured rules. The subsequent Sales Order is still its own business document, with its own current values and lifecycle. ### 2.3 Sales Order A Sales Order is a transactional snapshot assembled from user input, partner and material master data, reference documents, pricing condition data, Customizing, and runtime determinations. Its main technical responsibilities include: - establish the commercial parties and Sales Area; - identify products or services and total demand; - determine item and schedule-line processing behavior; - determine price and commercial terms; - schedule and confirm quantities and dates; - provide a source for delivery- or order-related subsequent processing; - maintain processing status and document flow. Saving the Sales Order does not post physical goods movement. It records demand and instructions that subsequent processes can consume. ### 2.4 Outbound Delivery The Outbound Delivery is an execution document, not merely a visual plan. It organizes delivery-relevant quantities for shipping and supports processes such as picking, packing, batch/serial handling, route or shipping data, and PGI. Delivery creation can copy data from one or more due predecessor items under copy-control, combination, and split rules. The resulting delivery has its own header/item identity and status. Changing the order afterward does not imply that every copied delivery value dynamically changes. ### 2.5 Post Goods Issue PGI is the decisive physical posting boundary for the ordinary outbound sell-from-stock flow. SAP states that goods issue confirms that the goods have left the company and reduces warehouse stock. If posted data must be corrected, the normal flow is to reverse the goods issue, change the delivery, and post again. See [SAP Help — Goods Issue](https://help.sap.com/docs/SAP_S4HANA_CLOUD/aff0b3f5f46c42a2b2c0fabfc233bab2/64f81a71edf5490ab522a829be075827.html?locale=en-US&version=LATEST). PGI can create or update evidence across component boundaries: ```text Outbound Delivery │ ├─ goods-movement status and actual GI information ├─ material document / inventory quantity effect ├─ value and accounting consequences, when applicable └─ document-flow relationship ``` The goods issue document is not merely another Sales Order child. SAP identifies it as belonging to Materials Management and Financial Accounting while still being navigable from the delivery flow. See [Displaying Goods Issue Documents](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/c7894a248ca14f74aca67f97528e5ad7/f91bbf53d25ab64ce10000000a174cb4.html). ### 2.6 Billing A Billing Document is created from a billable predecessor such as a delivery or Sales Order, depending on item billing relevance and process design. Data is copied under billing copy-control rules. For delivery-related billing, SAP gives the representative behavior that quantities can be copied from the delivery while prices can be copied from the Sales Order. Pricing may also be redetermined according to the configured pricing type. See [SAP Help — Billing Data Flow](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/ed84b70c199d4470ae2e5ccb93b2e45b/e26fb6535fe6b74ce10000000a174cb4.html). The Billing Document is a distinct SD business document. Its accounting transfer normally creates the financial evidence for receivable, revenue, tax, and related postings according to configuration. ### 2.7 Incoming payment Incoming payment belongs primarily to Financial Accounting. It records the cash receipt and applies clearing logic to one or more open customer items. ```text Billing document ↓ Customer receivable/open item ↓ Incoming payment posting ↓ Full, partial, residual, or other configured clearing result ``` Payment must not be modeled as “a field sent back to the Sales Order.” It is a financial posting with its own document identity, posting date, currency, accounts, clearing state, and possible exceptions. One payment can relate to multiple invoices, and one invoice can be settled through several payments or adjustments. --- ## 3. Business Events Versus Document Creation ### 3.1 A document records intent or execution at a specific boundary The existence of a document proves only the fact owned by that document. ```text Sales Order exists proves: demand and commercial/fulfillment intent were recorded does not prove: stock moved Outbound Delivery exists proves: shipping execution document was created does not prove: PGI was posted Billing Document exists proves: billing document was created does not prove: customer paid Payment document exists proves: payment posting exists does not automatically prove: every invoice/order branch is complete ``` This prevents a common diagnostic error: interpreting a planning or execution document as proof that a later posting occurred. ### 3.2 Posting boundaries Posting establishes a committed accounting or inventory fact. It typically has stronger reversal and audit requirements than changing an unposted operational document. | Operation | Nature | Typical correction model | | ---------------------------------- | ------------------------------ | -------------------------------------------------- | | Change open Sales Order | Transaction-document change | Edit through supported Sales Order operation | | Change unposted delivery | Execution-document change | Edit through delivery operation, subject to status | | Reverse PGI | Reversal posting | Create reversal effect, correct delivery, repost | | Cancel billing | Cancellation/reversal document | Preserve traceable reversal relationship | | Reset clearing/reverse FI document | Financial correction | Execute authorized FI reversal/reset process | Direct deletion or overwriting of posted persistence would destroy lineage and violate component-level invariants. ### 3.3 Save is not universal business completion Every document has a local save boundary, but Order-to-Cash completion is a cross-document interpretation. ```text Sales Order saved ≠ delivery complete Delivery saved ≠ goods issued PGI posted ≠ billed Billing posted ≠ paid Payment received ≠ every order item complete ``` A process can contain partial deliveries, partial billing, rejected items, returns, credit/debit documents, disputes, and residual open items. Completion must therefore be evaluated at the correct document/item/quantity grain. --- ## 4. Sales Document Header, Item, and Schedule-Line Grain ### 4.1 Structural hierarchy ```text Sales Document Header one commercial document ├── Item 0010 one product/service line │ ├── Schedule Line 0001 one dated quantity requirement/result │ └── Schedule Line 0002 another dated quantity requirement/result └── Item 0020 └── Schedule Line 0001 ``` The placement rule is: > Store or expose a value at the broadest grain where it remains true without > changing its business meaning. ### 4.2 Level responsibilities | Level | Technical grain | Responsibility | Representative values | | ------------- | ----------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | Header | One sales document | Shared commercial context | Document type, Sales Area, Sold-to Party, order date, document currency, overall state | | Item | One line inside the document | Product/service demand and line processing | Material, total ordered quantity, sales unit, Plant, item category, price/net value, rejection reason | | Schedule line | One dated quantity segment inside an item | Requirement, confirmation, and logistics participation by date | Requested date/quantity, confirmed date/quantity, schedule-line category, delivery relevance, movement instructions | SAP defines a Sales Order schedule line as the subdivision of an item according to date and quantity. Multiple partial deliveries can therefore be represented by multiple schedule lines. See [SAP Help — Item Schedule Line](https://help.sap.com/docs/SAP_S4HANA_CLOUD/03c04db2a7434731b7fe21dca77440da/37df44581efca007e10000000a441470.html). ### 4.3 Classic key structure Ignoring the client column for readability: ```text VBAK key: VBELN VBAP key: VBELN + POSNR VBEP key: VBELN + POSNR + ETENR ``` The keys are nested identities: - `VBELN` identifies the sales document. - `POSNR` identifies an item within that document. - `ETENR` identifies a schedule-line record within that item. `ETENR` is not a quantity or date. It identifies the row that contains dated quantity information. ### 4.4 Correct join path ```text VBAK-VBELN = VBAP-VBELN VBAP-VBELN + VBAP-POSNR = VBEP-VBELN + VBEP-POSNR ``` Joining `VBEP` using only `VBELN` mixes schedule lines from every item in the document. A syntactically valid SQL join can therefore be semantically wrong. ### 4.5 Header-to-item propagation Selected header values can be proposed or copied into item fields. This is not object-oriented inheritance and is not necessarily a live reference. ```text Header payment terms: 30 days ↓ copied/proposed Item 0010: 30 days Item 0020: 45 days explicit permitted exception ``` If the header later changes, the behavior is field- and process-specific. An item exception may remain unchanged. Diagnose the stored item value and the relevant copy/redetermination behavior rather than assuming that the UI displays one shared header variable. ### 4.6 Child-to-parent aggregation Information also moves upward: ```text Schedule-line results → item processing summary Item values → header totals Item statuses → overall document status ``` An overall status is compressed information. It is useful for selection and navigation but does not explain which child caused a partial state. Diagnosis must move from header summary to item and schedule-line evidence. --- ## 5. Quantity and Status Propagation ### 5.1 Quantity vocabulary | Quantity | Meaning | Grain warning | | ------------------ | ----------------------------------------------------------------------------- | --------------------------------------- | | Ordered quantity | Total customer demand for one Sales Order item | Item total | | Requested quantity | Demand requested for a particular date | Commonly schedule-line/date context | | Confirmed quantity | Quantity SAP currently commits for a date after scheduling/availability logic | Promise, not execution | | Delivery quantity | Quantity included in a delivery item | Delivery-document grain | | Picked quantity | Quantity physically staged/picked according to warehouse process | Does not alone prove PGI | | GI quantity | Quantity posted as goods issue | Material-document/posting evidence | | Billed quantity | Quantity represented in billing according to billing basis | Billing-item grain | | Open quantity | Remaining quantity eligible for a defined next step | Must name which “open” measure is meant | “Open quantity” is not one universal stored fact. It can mean, for example, open order demand, open confirmed quantity for delivery, unpicked delivery quantity, or unbilled quantity. Every technical report must define the formula, source grain, status exclusions, unit, and process boundary. ### 5.2 Partial-flow example Customer demand: ```text Sales Order 50000123 / Item 0010 Ordered quantity: 10 EA Schedule Line 0001 Confirmed: 6 EA on 10 Sep Schedule Line 0002 Confirmed: 4 EA on 17 Sep ``` After the first branch is delivered, PGI-posted, and billed: ```text Ordered: 10 EA Confirmed: 10 EA across two dates Delivered: 6 EA PGI-posted: 6 EA Billed: 6 EA Open for later: 4 EA, assuming no rejection or cancellation ``` The exact number of schedule lines and status representation depends on runtime results and configuration. The invariant is the separation of demand, commitment, execution, posting, and billing. ### 5.3 Status is evidence, but not always sufficient proof Examples of useful delivery status families include: | Status family | Header landmark | Item landmark | Meaning | | -------------- | --------------- | ------------- | ---------------------------------- | | Picking | `LIKP-KOSTK` | `LIPS-KOSTA` | Progress of required picking | | Goods movement | `LIKP-WBSTK` | `LIPS-WBSTA` | Progress of goods-movement posting | Status fields support diagnosis, but decisive posting evidence is stronger: ```text PGI proof hierarchy 1. Material/goods-issue document and delivery relationship 2. Actual GI date and completed goods-movement state 3. Inventory/value/accounting effects where applicable 4. User message or visible delivery existence alone — insufficient ``` SAP S/4HANA simplified SD status persistence by moving status fields from the separate `VBUK` and `VBUP` tables into corresponding document header/item tables. Compatibility behavior and older-system documentation can still expose legacy names, so code must be checked against the exact target release. The safe extension contract is a released CDS/API rather than assumptions about a legacy status table. See SAP's [S/4HANA Simplification List](https://help.sap.com/doc/pdfa4322f56824ae221e10000000a4450e5/1511%20001/en-US/SIMPL_OP1511_FPS01.pdf). ### 5.4 Status aggregation is not arithmetic only An overall state such as “partially processed” is not necessarily calculated by simply summing quantities. Rejections, relevance indicators, blocks, document categories, and completion rules influence whether a child participates in the summary. For diagnostics: ```text Overall header status ↓ Relevant item statuses ↓ Schedule-line/delivery/billing quantities and states ↓ Document-flow and posting evidence ``` --- ## 6. SD Document Flow and Predecessor–Successor Relationships ### 6.1 Document flow is a graph The simple diagram appears linear: ```text Order → Delivery → Billing ``` The real process is a graph: ```text Quotation ↓ Sales Order Item 0010 ├─ Delivery A Item 0010 → PGI A → Invoice A └─ Delivery B Item 0010 → PGI B → Invoice B Sales Order Item 0020 └─ rejected; no delivery ``` Several orders can also be combined into a delivery when combination criteria permit it, while a single order can split into multiple deliveries or invoices. The correct cardinality is therefore frequently one-to-many or many-to-many across stages. ### 6.2 `VBFA` as a classic lineage landmark `VBFA` represents SD predecessor/successor document relationships. Important classic fields include: | Field | Meaning | | ---------------------------------------------- | ------------------------------- | | `VBELV` | Preceding SD document | | `POSNV` | Preceding SD document item | | `VBTYP_V` or release-equivalent category field | Preceding document category | | `VBELN` | Subsequent SD document | | `POSNN` | Subsequent SD document item | | `VBTYP_N` or release-equivalent category field | Subsequent document category | | `STUFE` | Document-flow level information | SAP S/4HANA simplified `VBFA` and extended the SD document-category model. Avoid encoding old one-character category assumptions into new integrations. ### 6.3 Reference field versus document-flow graph A delivery item can contain direct predecessor references such as `LIPS-VGBEL/VGPOS`. These tell how that item was created. `VBFA`, by contrast, represents broader predecessor/successor lineage across document categories. ```text Direct source reference useful for: immediate originating document/item Document-flow relationship useful for: traversing the wider process graph ``` Neither should be treated as a reason to update the predecessor or successor table directly. ### 6.4 Process flow versus full document flow Modern Fiori process-flow visualizations can deliberately show the documents most relevant to a particular business role. The full document flow can contain additional related documents. SAP notes that a process flow viewed from a Sales Order can differ from one viewed from a Billing Document even though both refer to the same broader process. See [SAP Help — Manage Billing Documents Process Flow](https://help.sap.com/docs/SAP_S4HANA_CLOUD/a376cd9ea00d476b96f18dea1247e6a5/e097b4d95c9946d49f48bba5ddfd61b3.html). Therefore: ```text UI process flow = role-oriented visualization Document flow = business-document lineage VBFA = classic persistence landmark for SD relationships ``` ### 6.5 Document flow is not RAP composition RAP composition expresses lifecycle ownership inside one business-object aggregate: ```text SalesOrderRequest └── Items └── Schedules ``` SD document flow links separate aggregates and postings: ```text Sales Order ──reference/flow──> Delivery ──flow──> Billing ``` A Billing Document should not be modeled as a composition child deleted with a Sales Order. It has independent identity, authorization, accounting effects, status, reversal behavior, and retention requirements. --- ## 7. Core Persistence Landmarks ### 7.1 Persistence map The following tables are classic technical landmarks for authorized diagnosis. They are not stable public update interfaces. | Process object | Header landmark | Item/detail landmark | Representative grain | | ---------------------------- | --------------- | -------------------------------------------- | ------------------------------------------------------------ | | Sales document | `VBAK` | `VBAP` | `VBELN`; `VBELN + POSNR` | | Sales schedule line | — | `VBEP` | `VBELN + POSNR + ETENR` | | Delivery | `LIKP` | `LIPS` | `VBELN`; `VBELN + POSNR` | | Billing document | `VBRK` | `VBRP` | `VBELN`; `VBELN + POSNR` | | SD document flow | — | `VBFA` | Predecessor/successor document-item relationship | | Material document in S/4HANA | — | `MATDOC` | Material-document item context | | Accounting document | `BKPF` | `BSEG`; universal-journal detail in `ACDOCA` | Company code, fiscal year, accounting document, line context | The repeated field name `VBELN` does not mean all tables contain the same business object. Its meaning is scoped by the table/document category. ### 7.2 Sales Order persistence ```text VBAK: one sales-document header ├─ document type and category ├─ Sales Area ├─ Sold-to/commercial context ├─ document currency/dates └─ header-level state VBAP: one sales-document item ├─ material/product ├─ item category ├─ ordered quantity and unit ├─ Plant/shipping data └─ item-level value and state VBEP: one schedule line ├─ schedule-line number/category ├─ requested/confirmed date and quantity context └─ fulfillment-control data ``` Additional partner, business-data, text, pricing, and status information can reside in other structures. The three-table model is the structural spine, not the complete Sales Order data model. ### 7.3 Delivery persistence ```text LIKP: delivery header ├─ delivery type ├─ shipping point ├─ dates ├─ partners └─ overall execution/status information LIPS: delivery item ├─ material and delivery quantity ├─ Plant/storage location/batch context ├─ predecessor reference ├─ picking and goods-movement information └─ movement-type and status context ``` A delivery row proves that delivery creation occurred. To prove PGI, correlate delivery status and actual GI information with the material/goods-issue document and relevant posting effects. ### 7.4 Billing persistence ```text VBRK: billing header ├─ billing type/category ├─ payer and dates ├─ currency/accounting references └─ header status VBRP: billing item ├─ billed product/quantity ├─ reference document/item ├─ item values └─ billing relevance/result context ``` Pricing-result details in SAP S/4HANA are associated with `PRCD_ELEMENTS`; older code commonly references `KONV`. Pricing persistence is covered in the separate Sales Document Control and Pricing reference. ### 7.5 Material and accounting evidence In SAP S/4HANA, `MATDOC` is the central material-document line-item persistence landmark. Financial postings use the accounting-document model, with `ACDOCA` as the Universal Journal line-item store and classic document header/context such as `BKPF` still relevant. Do not join these areas only by visually similar identifiers. Use documented reference keys, document flow, released CDS associations, or application APIs. ### 7.6 S/4HANA data-model changes Relevant simplifications include: - status fields moved from separate `VBUK`/`VBUP` persistence into relevant SD document header/item tables; - `VBFA` document-flow simplification; - extended SD document-category semantics; - material-document consolidation centered on `MATDOC`; - financial line-item consolidation in the Universal Journal. Legacy names can still surface through compatibility views, extractors, or old documentation. A technical design must declare its system release and avoid treating compatibility behavior as a future-stable integration contract. --- ## 8. Grain-Safe Query and Reporting Design ### 8.1 The parent-measure multiplication trap Suppose one Sales Order header stores a total of `1,000`, with two items and two schedule lines per item: ```text 1 VBAK row → 2 VBAP rows → 4 VBEP rows ``` After a flat join, the header value appears four times: | Order | Item | Schedule line | Repeated header total | | ------ | ---- | ------------- | --------------------: | | 500001 | 0010 | 0001 | 1,000 | | 500001 | 0010 | 0002 | 1,000 | | 500001 | 0020 | 0001 | 1,000 | | 500001 | 0020 | 0002 | 1,000 | `SUM(HeaderTotal)` returns `4,000`, although the database join itself is technically valid. The governing rule is: > Aggregate a measure at the grain where the measure is defined. ### 8.2 Safe strategies - Read one header measure per `VBELN`. - Aggregate schedule-line quantities to item grain before joining them to item measures. - Aggregate item values to header grain before combining them with header measures. - Include currency and unit semantics in grouping/conversion logic. - Define whether rejected, cancelled, blocked, reversed, or statistically irrelevant rows participate. - Use released analytical CDS content when it already defines the required semantics. `SUM(DISTINCT HeaderTotal)` is not a general correction. Two different orders can legitimately have the same total, causing valid values to be removed. ### 8.3 Choose one explicit report grain Examples: ```text One row per Sales Order key: Sales Order One row per Sales Order Item key: Sales Order + Item One row per Schedule Line key: Sales Order + Item + Schedule Line One row per Order-to-Cash relationship key: predecessor + predecessor item + successor + successor item + category ``` A report that mixes these grains without an explicit bridge/aggregation design will eventually produce duplicate counts, misleading totals, or ambiguous statuses. ### 8.4 Currency and unit correctness An amount without its currency and a quantity without its unit is incomplete. Do not add `10 EA` to `10 KG`, or total document values across currencies without a documented conversion date, exchange-rate type, and target currency. ```text Measure + unit/currency + grain + relevance rule + time semantics = interpretable result ``` --- ## 9. Classic Transaction Map These transactions are on-premise/private-edition landmarks and depend on role, release, and system configuration. Public Cloud uses available Fiori apps and configuration activities instead of assuming these SAP GUI entry points. | Purpose | Classic transaction | Technical boundary | | --------------------------------------- | ------------------------------------------------ | --------------------------------------------- | | Create/change/display Sales Order | `VA01` / `VA02` / `VA03` | Sales document | | List Sales Orders | `VA05` | Sales-document selection/reporting | | Create/change/display Outbound Delivery | `VL01N` / `VL02N` / `VL03N` | Delivery execution | | Delivery monitor/due processing | `VL06O` and related delivery due-list processing | Delivery eligibility and collective execution | | Reverse goods movement for delivery | `VL09` | PGI reversal boundary | | Create/change/display Billing Document | `VF01` / `VF02` / `VF03` | Billing | | Display accounting document | `FB03` | FI document evidence | | Display customer line items | `FBL5N` | Receivable/open and cleared item analysis | | Post incoming payment | `F-28` | Classic FI incoming-payment processing | Transaction availability does not define the API contract. A custom application should not simulate `VA01` by updating `VBAK`, or simulate `VL02N` PGI by updating delivery status. ### 9.1 Diagnostic navigation pattern ```text Sales Order display ↓ document flow Delivery display ↓ document flow / goods-issue evidence Material and accounting documents ↓ Billing document and accounting document ↓ Customer open/cleared item evidence ``` The UI is the starting point for business context. Persistence inspection then confirms grain and state. Posting documents provide the strongest evidence. --- ## 10. Released CDS and API Boundaries ### 10.1 Contract hierarchy ```text Best extension/integration boundary released business object / API / event ↓ released CDS entity for supported read scenario ↓ internal table inspection for authorized diagnosis ↓ Worst write boundary direct update of SAP application tables ``` “Released” is system- and release-specific. Verify API State in the target system and the current SAP Business Accelerator Hub/API documentation before choosing an object. ### 10.2 Sales Order API hierarchy The Sales Order A2X OData V2 family commonly exposes a hierarchy such as: ```text A_SalesOrder └── A_SalesOrderItem └── A_SalesOrderScheduleLine ``` SAP documents `A_SalesOrderScheduleLine` as the item schedule-line entity and supports navigation from an order item to its schedule lines in the applicable API. The `A_` prefix is a delivered entity naming convention, not an ABAP language requirement. Service versions can use different names; always inspect the service metadata. ### 10.3 Delivery read model SAP documents `I_DeliveryDocument` as a released basic interface CDS view for delivery objects, including attributes such as delivery number, shipping point, dates, partners, and overall statuses. Authorization remains part of the consumption context. See [SAP Help — Delivery Document CDS View](https://help.sap.com/docs/SAP_S4HANA_CLOUD/c0c54048d35849128be8e872df5bea6d/e2966bcba73a455299b4937151dfd0a3.html). A released read view does not automatically authorize a write. Delivery creation, picking confirmation, PGI, reversal, and other operations need the specific supported business API for that operation and release. ### 10.4 BAPI, IDoc, OData, and event boundaries | Contract | Interaction style | Typical fit | Architectural caution | | -------------- | ---------------------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------- | | BAPI | Usually synchronous business operation | Classic/on-premise integration and application calls | Check release status, return messages, transaction ownership, and modern alternatives | | IDoc | Asynchronous persisted message | Decoupled reliable business-message exchange | Monitor status, retries, duplicates, partner profile, and business idempotency | | OData/API | Synchronous service contract | Cloud-ready business access and Fiori/API consumers | Respect version, ETags, business errors, scope, and API limits | | Business event | Asynchronous notification | Inform consumers that a business fact occurred | Event is not necessarily a full state-transfer payload | | CDS entity | Read/analytical semantic model, depending on release | Queries, analytics, and supported read scenarios | Released read access is not write authorization | For example, a Sales Order BAPI asks SAP application logic to create/change a business object. An order IDoc represents a persisted integration message that is processed asynchronously. Neither should be confused with directly inserting rows into Sales Order tables. ### 10.5 Direct table updates are invalid business operations Do not directly update: ```text VBAK / VBAP / VBEP LIKP / LIPS VBRK / VBRP VBFA MATDOC ACDOCA ``` These tables participate in application invariants, status propagation, document flow, pricing, inventory valuation, accounting, change tracking, authorization, output, and integration. Updating one table cannot reproduce the complete operation and can corrupt cross-component consistency. --- ## 11. Technical Diagnostic Flow ### 11.1 Universal sequence ```text Business symptom ↓ Identify exact document and item grain ↓ Capture actual stored/runtime result ↓ Traverse predecessor and successor documents ↓ Verify decisive posting evidence ↓ Reconstruct master data and configuration inputs ↓ Inspect logs/messages/authorizations/integration ↓ Investigate enhancements or custom code last ``` This sequence prevents configuration or code changes from being used to explain a symptom that actually came from transaction input, data grain, missing master data, an unexecuted posting, or a different document branch. ### 11.2 Missing or unexpected downstream document When a delivery or billing document is missing: 1. Capture the exact predecessor `VBELN + POSNR` and expected quantity. 2. Inspect rejection, completion, block, and relevance state. 3. Inspect every schedule line, including confirmed quantity/date and delivery relevance. 4. Check whether the item is due in the selected horizon and organizational scope. 5. Check document flow for an already-created or differently split successor. 6. Verify copy-control requirements and successor type. 7. Inspect application logs and authorization failures. 8. Only then inspect exits, BAdIs, custom logic, or inbound payloads. ### 11.3 “Delivery exists, but stock did not change” ```text Delivery identity ↓ Goods-movement status and actual GI date ↓ Material/goods-issue document in document flow ↓ MATDOC/released material-document view ↓ Stock quantity/value and accounting evidence ``` If the material document does not exist, delivery creation alone is not proof of PGI. If it exists, check reversal documents and posting dates before concluding that current stock should still show the original effect. ### 11.4 “Billing exists, but payment is still open” ```text Billing document ↓ Accounting transfer/reference ↓ Customer receivable/open item ↓ Incoming payment document ↓ Clearing document/date or residual/partial state ``` The defect may be no payment, unmatched payment, partial payment, residual item, currency/difference handling, clearing reset, or a different payer/account—not a missing Sales Order update. ### 11.5 Technical evidence record A strong technical incident note records: ```text System/release and client Business process variant Document + item + schedule-line keys Expected versus actual state Predecessor/successor identities Relevant quantities with units Amounts with currencies Status evidence Posting document evidence Configuration/master-data inputs Application log/message identifiers Enhancement/custom-code evidence, if reached ``` --- ## 12. RAP Architecture Transfer ### 12.1 Honest aggregate boundary A portfolio Sales Order Request can use composition for lifecycle-dependent children: ```text SalesOrderRequest aggregate root ├── composition [0..*] → Items product/service demand │ ├── composition [0..*] → Schedules simplified dated promises │ ├── association → Product │ └── association → Plant ├── composition [0..*] → OrderPartners order-specific role assignments ├── association → BusinessPartner └── association → SalesArea ``` Product, Plant, Business Partner, and Sales Area exist independently and are therefore associations rather than lifecycle-owned children. ### 12.2 Do not model the entire O2C chain as one RAP aggregate ```text Incorrect ownership idea SalesOrderRequest └── Delivery └── Billing └── Payment Better boundary SalesOrderRequest BO ──handoff/reference/event──> Fulfillment capability ──reference/status snapshot─> External successor documents ``` Delivery, material movement, billing, and payment have independent transactional and reversal lifecycles. If a portfolio cannot connect to a real S/4HANA Sales or Delivery API, represent the boundary honestly as a simulated handoff or integration adapter rather than claiming to perform standard SD PGI. ### 12.3 CDS and persistence Custom RAP CDS entities can expose the same database persistence used by ABAP, but a CDS model is not a separate database. During a RAP transaction, EML can also observe unsaved transactional-buffer state that an ordinary database `SELECT` does not automatically represent. The analogy to SD is useful: ```text RAP transactional buffer ≠ committed database state Confirmed schedule line ≠ executed PGI state Editable UI value ≠ persisted business operation ``` Every layer represents a different degree of commitment. --- ## 13. Technical Insights and Common Misinterpretations ### 13.1 The process is a graph, not a pipeline row The happy path is drawn as a line for teaching, but partial fulfillment, combination, splitting, returns, cancellations, and financial clearing create a graph. Data models and reports must support branching rather than assume one order equals one delivery equals one invoice. ### 13.2 Document existence and posting evidence are different An Outbound Delivery is strong evidence of shipping execution preparation but not of goods issue. A Billing Document is strong evidence of invoicing but not of cash receipt. Diagnose the business event through its posting document and status evidence. ### 13.3 Confirmation is commitment, not physical movement Confirmed quantity answers what SAP currently commits for a date. Delivery and PGI answer what was operationally processed and physically posted. Combining these as one “fulfilled quantity” hides important failure states. ### 13.4 Copying is not a live foreign-key projection Successor documents copy and redetermine data under business rules. The copied value can intentionally differ from the current predecessor or master data. Always inspect the value stored in the affected document and its copy-control context. ### 13.5 Status is a summary, not the cause An overall status compresses child results. It helps locate a problem but does not replace inspection of the item, schedule line, delivery, billing, posting, or clearing record that produced it. ### 13.6 Database correctness includes grain SQL can be syntactically and relationally valid while producing a wrong business total. Every quantity and amount must be interpreted with its document level, unit/currency, relevance rules, and time semantics. ### 13.7 Persistence knowledge is not write authorization Knowing that Sales Order headers are represented in `VBAK` does not authorize a program to update `VBAK`. Table knowledge supports diagnosis; released business operations preserve application invariants. ### 13.8 Component boundaries explain reversal flows PGI belongs to an inventory/accounting posting boundary even though Shipping initiates it from the delivery. Billing creates a separate billing/accounting boundary. Payment is a financial clearing boundary. Separate reversal operations exist because later documents cannot safely be erased by editing an earlier Sales Order. ### 13.9 Clean core is a contract decision Clean core does not mean a consultant must forget classic tables. It means the extension or integration contract should use released, lifecycle-stable interfaces. Classic tables and transactions remain valuable evidence in authorized on-premise/private-edition diagnosis. ### 13.10 A portfolio must label simulation honestly A custom RAP action named `SubmitForFulfillment` can demonstrate aggregate validation, authorization, messaging, events, and integration architecture. It does not become standard SD delivery or PGI unless it calls an appropriate released S/4HANA contract and the real downstream posting succeeds. --- ## 14. Compact Technical Map ```text SALES DOCUMENT VBAK (VBELN) └── VBAP (VBELN, POSNR) └── VBEP (VBELN, POSNR, ETENR) │ │ delivery relevance, due processing, copy control ▼ DELIVERY LIKP (VBELN) └── LIPS (VBELN, POSNR) │ │ picking / packing / PGI ▼ MATERIAL & VALUE POSTING MATDOC + accounting evidence │ ▼ BILLING VBRK (VBELN) └── VBRP (VBELN, POSNR) │ ▼ FINANCIAL ACCOUNTING BKPF / BSEG / ACDOCA customer open item → payment → clearing CROSS-DOCUMENT LINEAGE VBFA: predecessor document/item → successor document/item SUPPORTED EXTENSION BOUNDARY Released CDS / business object / OData API / BAPI / IDoc / event INVALID WRITE BOUNDARY Direct updates to SAP application persistence ``` The compact map is intentionally layered. The header/item/schedule hierarchy describes ownership inside a Sales document. `VBFA` describes lineage between documents. `MATDOC` and accounting persistence prove postings in other components. Released interfaces provide the supported integration boundary. 38:T905,SAP SD Order-to-Cash — Technical Architecture This document describes the technical structure and runtime boundaries of the SAP Sales and Distribution Order-to-Cash process. Its purpose is to connect the business-document chain to document grain, persistence landmarks, posting effects, document flow, diagnostic evidence, and clean-core integration contracts. The central architectural principle is: Order-to-Cash is a graph of independently meaningful business documents and postings. It is not one large database record, one status field, or one transactional aggregate. This reference distinguishes three contexts: - Classic SAP ERP and SAP S/4HANA on-premise/private edition, where SAP GUI transactions and direct table inspection may be available for authorized diagnosis. - SAP S/4HANA Cloud Public Edition, where Fiori applications, configuration activities, and released APIs are the normal operational contracts. - Clean-core extension development, where released CDS entities, business objects, events, and APIs should be preferred over dependencies on internal persistence. Primary SAP sources: - SAP Help — Sales Documents - SAP Learning — Navigating the Order-to-Cash Process Steps - SAP Help — Sales Order Item Schedule Line - SAP Help — Goods Issue - SAP Help — Billing Data Flow - SAP Help — Displaying Goods Issue Documents - SAP Help — Delivery Document CDS View --- 1. Scope and System Boundaries 1.1 Core process The common sell-from-stock flow can be represented as: text Optional presales Core execution Inquiry → Quotation → Sales Order → Outbound Delivery → PGI → Billing → Payment The technical meaning is clearer when the process is expressed as state transitions: text Customer interest ↓ Commercial offer ↓ Accepted demand and fulfillment intent ↓ Warehouse execution document ↓ Inventory and value posting ↓ Customer invoice and receivable ↓ Cash receipt and clearing Inquiry and quotation are optional presales documents. Returns, credit memos, third-party sales, intercompany sales, milestone billing, consignment, and make-to-order processes follow different branches. The architecture in this document is therefore a baseline, not a claim that every SD transaction follows one identical path. SAP describes sales, delivery, and billing39:Tb7d,# SAP SD Order-to-Cash — Technical Architecture This document describes the technical structure and runtime boundaries of the SAP Sales and Distribution Order-to-Cash process. Its purpose is to connect the business-document chain to document grain, persistence landmarks, posting effects, document flow, diagnostic evidence, and clean-core integration contracts. The central architectural principle is: > Order-to-Cash is a graph of independently meaningful business documents and > postings. It is not one large database record, one status field, or one > transactional aggregate. This reference distinguishes three contexts: - **Classic SAP ERP and SAP S/4HANA on-premise/private edition**, where SAP GUI transactions and direct table inspection may be available for authorized diagnosis. - **SAP S/4HANA Cloud Public Edition**, where Fiori applications, configuration activities, and released APIs are the normal operational contracts. - **Clean-core extension development**, where released CDS entities, business objects, events, and APIs should be preferred over dependencies on internal persistence. Primary SAP sources: - [SAP Help — Sales Documents](https://help.sap.com/docs/SAP_S4HANA_CLOUD/a376cd9ea00d476b96f18dea1247e6a5/aa64b65334e6b54ce10000000a174cb4.html) - [SAP Learning — Navigating the Order-to-Cash Process Steps](https://learning.sap.com/courses/discovering-the-basics-of-sap-s-4hana-sales/executing-sales-order-management_cad9dfbe-bafc-4ed9-ac2e-6fd8422430e4) - [SAP Help — Sales Order Item Schedule Line](https://help.sap.com/docs/SAP_S4HANA_CLOUD/03c04db2a7434731b7fe21dca77440da/37df44581efca007e10000000a441470.html) - [SAP Help — Goods Issue](https://help.sap.com/docs/SAP_S4HANA_CLOUD/aff0b3f5f46c42a2b2c0fabfc233bab2/64f81a71edf5490ab522a829be075827.html?locale=en-US&version=LATEST) - [SAP Help — Billing Data Flow](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/ed84b70c199d4470ae2e5ccb93b2e45b/e26fb6535fe6b74ce10000000a174cb4.html) - [SAP Help — Displaying Goods Issue Documents](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/c7894a248ca14f74aca67f97528e5ad7/f91bbf53d25ab64ce10000000a174cb4.html) - [SAP Help — Delivery Document CDS View](https://help.sap.com/docs/SAP_S4HANA_CLOUD/c0c54048d35849128be8e872df5bea6d/e2966bcba73a455299b4937151dfd0a3.html) --- ## 1. Scope and System Boundaries ### 1.1 Core process The common sell-from-stock flow can be represented as: ```text Optional presales Core execution Inquiry → Quotation → Sales Order → Outbound Delivery → PGI → Billing → Payment ``` The technical meaning is clearer when the process is expressed as state transitions: ```text Customer interest ↓ Commercial offer ↓ Accepted demand and fulfillment intent ↓ Warehouse execution document ↓ Inventory and value posting ↓ Customer invoice and receivable ↓ Cash receipt and clearing ```3a:T9e4e, # SAP SD Organizational Structure and Master Data — Technical Reference This document explains how SAP Sales and Distribution combines organizational configuration and reusable master data to establish a valid processing context for a sales transaction. It connects business meaning to classic persistence landmarks, maintenance transactions, runtime determination, diagnostic technique, RAP modeling, and clean-core boundaries. The central technical principle is: > Organizational structure defines where a transaction is permitted to run; > master data supplies reusable facts for that context; the Sales Order stores > the resulting transactional values. This reference distinguishes three environments: - **SAP S/4HANA on-premise or private edition**, where SAP GUI transactions, IMG activities, and authorized table inspection are common diagnostic tools. - **SAP S/4HANA Cloud Public Edition**, where Fiori applications and configuration activities replace many classic transaction-code paths. - **Clean-core extension development**, where released CDS entities, business objects, events, and APIs are contracts; internal tables are not. Primary SAP sources: - [SAP Learning — Identifying Organizational Units in SAP S/4HANA Sales](https://learning.sap.com/courses/exploring-sap-s-4hana-sales-essentials/identifying-organizational-units-in-sap-s-4hana-sales_ddb48d1e-1f57-46bd-8d13-d8e4ef6d0560) - [SAP Learning — Maintaining Organizational Units for Delivery Processing](https://learning.sap.com/courses/configuring-delivery-processing-in-sap-s-4hana-sales/maintaining-the-organizational-units-for-delivery-processing) - [SAP Learning — Managing Business Partners](https://learning.sap.com/courses/customizing-core-settings-in-financial-accounting-in-sap-s4hana/managing-business-partners) - [SAP Learning — Identifying the Source of Data in a Sales Document](https://learning.sap.com/courses/fundamental-customizing-in-sap-s-4hana-sales/identifying-the-source-of-data-in-a-sales-document) - [SAP Learning — Applying the Partner Function Concept](https://learning.sap.com/courses/fundamental-customizing-in-sap-s-4hana-sales/applying-the-partner-function-concept) - [SAP Help — Creating Customer-Material Information Records](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/7b24a64d9d0941bda1afa753263d9e39/3f8bc95360267214e10000000a174cb4.html) - [SAP Help — Business Partner Address](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/74b0b157c81944ffaac6ebc07245b9dc/e84813a97a3645b38b41d374a17ae713.html) --- ## 1. The Runtime Model ### 1.1 Three kinds of data participate in one order ```text Organizational configuration Which legal and commercial units may work together? │ ▼ Master data Who is the customer? What is sold? Which context-specific defaults apply? │ ▼ Sales Order transaction Which values were proposed, derived, copied, overridden, and accepted now? ``` These layers are related but not interchangeable: | Layer | Examples | Lifecycle | Technical role | | ---------------------------- | ------------------------------------------------------------------------------------- | ------------------------------ | -------------------------------------------------- | | Organizational configuration | Company Code, Sales Organization, Sales Area, Plant assignment | Relatively stable Customizing | Defines permitted processing contexts | | Master data | Business Partner, customer segments, product/material, customer-material relationship | Reusable across transactions | Supplies identities, classifications, and defaults | | Transaction data | Sales Order header, items, partners, schedule lines | Created for one business event | Records the actual agreement and processing state | A Sales Order does not continuously calculate every displayed field by joining the latest master data. During creation or redetermination, the application obtains values from several sources and places the accepted result in the document. This is essential for traceability: a later master-data change must not silently rewrite the commercial meaning of every historical order. ### 1.2 Configuration graph, not a flat list SAP does not merely check whether each code exists. It checks whether the required assignments and combinations exist. ```text Company Code └── Sales Organization ├── Distribution Channel │ └── forms Distribution Chain └── Division └── completes Sales Area Distribution Chain ── permits ── Plant Plant + Shipping Condition + Loading Group ── determines ── Shipping Point ``` For example, a Sales Organization, Distribution Channel, and Division may each be valid individually while their exact Sales Area combination is invalid. This is why technical diagnosis must reconstruct the full runtime key rather than validate codes one at a time. --- ## 2. Company Code and Sales Organization ### 2.1 Company Code The Company Code is an independent accounting unit for which a complete set of financial statements can be produced. In an SD process it establishes the legal and Financial Accounting context behind the selling organization. Typical responsibilities include: - accounting currency and fiscal-year context; - customer receivables and reconciliation-account processing; - tax and legal reporting context; - accounting documents generated through SD integration. The Company Code is not “the highest level of the whole SAP system.” SAP has other enterprise structures and higher grouping concepts. Its precise meaning is the smallest organizational unit for complete external accounting. ### 2.2 Sales Organization The Sales Organization is the central commercial unit in Sales and Distribution. It is responsible for selling and distributing products or services and is commonly used to control commercial reporting, master-data segments, and sales-document processing. Standard assignment rule: ```text One Company Code ──< many Sales Organizations One Sales Organization ──> exactly one Company Code ``` This relationship makes the commercial operation accountable to one legal accounting unit. It does not imply that every sales document in a Company Code shares the same route to market, product division, pricing, or fulfillment location. --- ## 3. Sales Area and Distribution Chain ### 3.1 Sales Area The Sales Area is the exact commercial context in which a sales transaction is processed: ```text Sales Organization + Distribution Channel + Division = Sales Area ``` Each component answers a different question: | Component | Meaning | Example | | -------------------- | -------------------------------- | --------------------------- | | Sales Organization | Which commercial unit sells? | Domestic Sales | | Distribution Channel | Through which route to market? | Wholesale, retail, online | | Division | Which product or service family? | Finished goods, spare parts | Two recurring misinterpretations should be avoided: - A Distribution Channel is a commercial route to market, not a truck route or shipping method. - A Division classifies a product/service range; it is not the individual material being ordered. The Sales Area scopes important customer sales data, partner determination, sales-document processing, and reporting. A valid combination must be configured explicitly. ### 3.2 Distribution Chain The Distribution Chain is the smaller combination: ```text Sales Organization + Distribution Channel = Distribution Chain ``` It omits Division. This distinction matters because some assignments and master-data views—such as material sales data and the assignment of a Plant for sales processing—are organized by Sales Organization and Distribution Channel rather than by the full Sales Area. ### 3.3 Example ```text Sales Organization: 1000 Domestic Sales Distribution Channel: 10 Direct Sales Division: 00 Cross-division products Distribution Chain: 1000 / 10 Sales Area: 1000 / 10 / 00 ``` The combination `1000 / 10 / 00` can be valid while `1000 / 20 / 00` is not, even if channel `20` exists elsewhere. The assignment is part of the business rule. --- ## 4. Plant and Shipping Point ### 4.1 Plant A Plant represents an operational location used by logistics. Depending on the business it can represent manufacturing, distribution, inventory, service, or another operational site. The Plant is deliberately not part of the Sales Area formula: - Sales Area defines the commercial selling context. - Plant defines an operational sourcing or fulfillment context. - One commercial route may use different Plants according to material, customer, stock, geography, or business rules. A Plant is assigned to a Company Code for valuation and accounting purposes. For Sales processing, a Plant must also be permitted for the relevant Distribution Chain. That assignment makes the Plant available as a possible delivering location; it does not prove that a specific order can be delivered. ### 4.2 Shipping Point A Shipping Point is the organizational unit responsible for shipping execution. It can represent a loading ramp, mail depot, express station, or other dispatch unit. SAP permits many-to-many assignment between Plants and Shipping Points, but an individual outbound delivery is processed by one Shipping Point. Therefore a different determined Shipping Point can be a delivery-split cause. The standard determination inputs are: ```text Delivering Plant + Shipping Condition + Loading Group = Shipping Point ``` Representative sources are: - delivering Plant: determined from customer/material/document context; - shipping condition: customer sales data or a document-type override; - loading group: material/product sales-general Plant data. The determination is performed for the Sales Order item because different items may use different Plants or loading requirements. ### 4.3 Permission is not determination These checks answer different questions: | Check | Meaning | | ------------------------------------- | ----------------------------------------------------- | | Distribution Chain ↔ Plant assignment | May this sales route use this Plant? | | Plant ↔ Shipping Point assignment | May this Shipping Point serve this Plant? | | Shipping-point determination | Which Shipping Point results for these exact inputs? | | ATP and scheduling | Can quantity be confirmed, and for what date? | | Delivery due processing | Is the item currently eligible for delivery creation? | Passing an organizational assignment does not guarantee ATP confirmation, delivery creation, picking, or PGI. --- ## 5. Sales Office and Sales Group A Sales Office represents a geographical or organizational sales location. A Sales Group represents a responsible team or group of employees within the sales organization, often within a Sales Office. They support responsibility assignment, reporting, and operational ownership, but they are not components of the Sales Area key. This separation lets one commercial model scale across multiple offices and teams without creating a different Sales Area for every reporting unit. ```text Sales Area Responsibility dimensions SO + Channel + Division Sales Office → Sales Group → Sales Employee ``` Do not infer from this that Sales Office and Sales Group are unimportant. Depending on configuration and reporting requirements, they can influence defaulting, authorizations, workflow, output, or analytics. They simply do not define the Sales Area itself. --- ## 6. Business Partner and Customer Data ### 6.1 Business Partner as the leading object In SAP S/4HANA, Business Partner is the leading master-data object for parties that can act as customers, suppliers, persons, or organizations. Customer and supplier integration synchronizes the relevant application-specific views. Three concepts must remain separate: | Concept | Purpose | Examples | | ---------------- | ------------------------------------------ | -------------------------------- | | BP Category | Fundamental nature of the party | Person, Organization, Group | | BP Role | Application-specific view and fields | FI Customer, Customer | | Partner Function | Responsibility in one business transaction | Sold-to, Ship-to, Bill-to, Payer | A BP Category is not a transaction role. A BP Role does not say which party receives one particular shipment. Partner Function supplies that transactional meaning. ### 6.2 Customer data segments Customer information is separated according to organizational validity: | Segment | Scope | Representative content | Classic landmark | | ------------ | ----------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------- | | General | Client-wide identity | Name, address, communication, search data | `KNA1`; BP identity also uses BP persistence such as `BUT000` | | Company Code | One customer in one accounting unit | Reconciliation account, payment methods, dunning, correspondence | `KNB1` | | Sales Area | One customer in SO/channel/division | Sales, shipping, billing, partner, pricing-related defaults | `KNVV` | The same customer can therefore be valid for one Company Code or Sales Area and missing or blocked in another. “The customer exists” is not enough evidence that the customer is usable in a given order. Typical S/4HANA customer roles include: - `FLCU00` — FI Customer, supplying Company Code/accounting context; - `FLCU01` — Customer, supplying Sales Area/sales context. Exact required roles, fields, and synchronization behavior depend on the solution scope and release. ### 6.3 Address identity and time dependency A Business Partner can have multiple addresses, address usages, and validity periods. A delivery address and billing address need not be identical. Modern multiple-address handling can determine address-dependent Sales Area data and propagate it into a newly created or changed sales document. This introduces two separate identities: ```text Business Partner identity ≠ Business Partner address identity ``` Released APIs can require a Business Partner address UUID when a specific address must be selected. Technical designs should not assume that a BP number always implies exactly one timeless address. The document behavior also depends on the operation. Changing the selected address in an existing document can redetermine address-dependent fields. A later master-data change does not mean that all old transactions become live views of the new address. The target release and address-handling configuration must be checked before making historical-data assumptions. --- ## 7. Partner Functions and Partner Determination ### 7.1 Four core customer partner functions | Partner function | Business responsibility | | ---------------- | ----------------------------------- | | Sold-to Party | Places or owns the commercial order | | Ship-to Party | Receives the goods or service | | Bill-to Party | Receives the invoice | | Payer | Pays the receivable | One Business Partner may perform all four functions. Alternatively, several partners can divide them—for example, headquarters places the order, a branch receives the goods, a shared-services entity receives invoices, and a treasury entity pays. In classic persistence and configuration, internal keys are often language- independent values inherited from German terminology, for example `AG`, `WE`, `RE`, and `RG`. APIs may expose semantic values such as sold-to or ship-to, or other codes depending on the contract. Integration logic must use the values defined by the released interface, not assume that a UI label is the stored key. ### 7.2 Partner determination Partner determination controls which partner functions are: - proposed from customer/BP relationships; - required or optional; - allowed at header or item level; - unique or repeatable; - changeable during document processing. The result is transaction data. Sales-document partner assignments are stored separately from the reusable Business Partner master because the same party can have different responsibilities in different orders. ```text BP/customer relationships + partner procedure + document context │ ▼ Sales-document partner rows ``` `VBPA` is a classic persistence landmark for sales-document partners. It is useful when diagnosing what was stored, but partner determination should be changed through supported configuration rather than direct table updates. --- ## 8. Product and Material Master Organizational Views ### 8.1 One material, several scopes The product/material master is not one flat record. Its views are organized by the business scope in which attributes are valid. | Scope | Representative content | Classic landmark | | -------------------- | ------------------------------------------------------------------------- | ---------------- | | Client/general | Material type, base unit, cross-application identity | `MARA` | | Description/language | Material descriptions | `MAKT` | | Distribution Chain | Sales unit, item-category group, sales status, delivering-plant proposals | `MVKE` | | Plant | MRP, procurement, availability, loading, planning | `MARC` | | Storage Location | Storage-location stock and operational data | `MARD` | | Units of measure | Alternative units and conversions | `MARM` | | Valuation | Valuation and price-control data | `MBEW` | The appropriate record grain matters. Reading `MARA` proves that the material exists globally; it does not prove that Sales data exists for the order's Distribution Chain or that Plant data exists for the delivering Plant. ### 8.2 Fields reused by later determinations Important examples include: - `MVKE-MTPOS`: item-category group used in item-category determination; - `MARC-DISMM`: MRP type used in schedule-line-category determination; - `MARC-LADGR`: loading group used in Shipping Point determination. These are inputs, not final decisions. The application combines them with document context and Customizing to select the result. ```text Material master classification + document context + configuration assignment = runtime document value ``` --- ## 9. Customer-Material Information Record A customer-material information record describes a relationship between one customer and one internal material in a particular commercial context. It is more specific than either master alone. Representative key context: ```text Customer + Sales Organization + Distribution Channel + Internal Material = Customer-material relationship ``` Typical content includes: - the customer's own material number and description; - customer-specific delivery agreements or tolerances; - customer-material text; - other customer/material-specific shipping information. The classic table landmark is `KNMT`; common classic transactions are `VD51` for creation, `VD52` for change, and `VD53` for display. Current S/4HANA releases can also provide Fiori maintenance applications. This record does not replace the product/material master. It maps customer- specific commercial language and agreements to an internal material that must already exist. --- ## 10. Sales Order Data-Provenance Pipeline ### 10.1 Sources A Sales Order can receive values from several independent sources: ```text Reference document ─────┐ Customer/BP master ─────┤ Material master ────────┤ Customer-material data ─┤ Condition records ──────┤──> determination and validation ──> order fields Customizing ────────────┤ Existing document data ─┤ User or interface input ┘ ``` No universal precedence rule covers every field. Each field has its own proposal, copy, override, redetermination, and validation behavior. Examples: - Sales Area may come from the entry context or reference document. - partner functions may be proposed from BP/customer relationships. - Plant may be proposed from customer-material, customer, or material context and may then be changed if permitted. - item category is determined from document type, material item-category group, item usage, and higher-level item category. - pricing is executed using pricing-procedure and condition-technique inputs. - schedule-line category uses item category and MRP type. ### 10.2 A practical provenance record When diagnosing a wrong field, capture this chain: | Evidence | Meaning | | ------------------------------ | ---------------------------------------------------- | | Actual stored value | What the transaction finally contains | | Source candidates | Master, reference document, Customizing, input, code | | Exact organizational key | Scope under which each source was read | | Determination sequence | Which source or rule had priority for this field | | Override/redetermination event | Why the original proposal may have changed | | Enhancement point or extension | Whether custom logic altered standard output | This is stronger than asking only, “Which table contains the field?” The same field name can exist at several grains and represent a source, copied snapshot, or calculated result. --- ## 11. Copy Semantics and Transactional Snapshots ### 11.1 Proposal is not live inheritance When master data proposes a value into a Sales Order, the order normally stores its own transactional value. The conceptual relationship is: ```text Master value at determination time │ copy / derive / validate ▼ Sales Order value │ └── remains part of this transaction unless explicitly changed ``` Changing master data later normally affects newly created or explicitly redetermined transactions. It does not retroactively rewrite all existing orders. This rule protects: - commercial traceability; - auditability; - stable downstream processing; - explanation of what the customer and seller agreed at that time. ### 11.2 Exceptions require field-specific analysis Some values can be redetermined when a relevant document field changes. Address-dependent Sales data is one example: selecting a different BP address can cause the application to propose different Incoterms or a different Plant. Pricing, texts, dates, partners, and output can have their own copy and redetermination controls. Therefore, “master data never changes an existing order” is too broad. The precise statement is: > Existing orders are transactional records, not live master-data projections; > however, supported change operations may deliberately redetermine selected > fields according to their configuration and application logic. --- ## 12. Classic Persistence Landmarks The following objects are useful for authorized diagnosis in classic or on-premise/private-edition environments. They are not clean-core integration contracts. ### 12.1 Organizational Customizing | Object | Typical meaning | | ------- | ----------------------------------------------------------- | | `T001` | Company Code definition | | `TVKO` | Sales Organization definition and related settings | | `TVTW` | Distribution Channel definition | | `TSPA` | Division definition | | `TVTA` | Valid Sales Area combinations | | `T001W` | Plant definition | | `TVKWZ` | Plant assignment to Sales Organization/Distribution Channel | | `TVST` | Shipping Point definition | | `TVSWZ` | Shipping Point assignment to Plant | | `TVSTZ` | Shipping Point determination combinations | | `TVBUR` | Sales Office definition | | `TVKGR` | Sales Group definition | Some relationships are technically represented through additional tables or valuation-area logic rather than one intuitive foreign-key field. The IMG and data dictionary should be used to confirm the exact implementation in the target release. ### 12.2 Business Partner and customer | Object | Typical meaning | | -------- | ---------------------------------------------------------- | | `BUT000` | General Business Partner identity | | `BUT020` | BP address assignment | | `ADRC` | Address details referenced by address number | | `KNA1` | General customer data | | `KNB1` | Customer Company Code data | | `KNVV` | Customer Sales Area data | | `KNVP` | Customer master partner functions by Sales Area | | `VBPA` | Partner assignments copied/determined for a sales document | BP/customer synchronization is handled by Customer/Vendor Integration in S/4HANA. Directly changing these tables can break consistency between the leading BP object and customer application data. ### 12.3 Product/material and relationship records | Object | Grain | | ------ | ------------------------------------------------- | | `MARA` | Material/client | | `MAKT` | Material/language | | `MVKE` | Material/Sales Organization/Distribution Channel | | `MARC` | Material/Plant | | `MARD` | Material/Plant/Storage Location | | `MARM` | Material/alternative unit | | `MBEW` | Material/valuation area/valuation type context | | `KNMT` | Customer/material/commercial relationship context | The correct join keys follow the grain. Joining only on material number can multiply or mix Sales Organization, Plant, language, unit, or valuation rows. --- ## 13. Classic Maintenance and Diagnostic Transactions These are common SAP GUI landmarks for classic/on-premise environments. Exact availability and navigation vary by release, installed scope, and authorization. For configuration work, prefer the IMG path in the target system over memorizing a transaction code without its business activity. | Area | Common landmark | Purpose | | ---------------------------- | ---------------------- | --------------------------------------------- | | Company Code | `OX02` | Define or inspect Company Codes | | Sales Organization | `OVX5` | Define Sales Organizations | | Distribution Channel | `OVXB` | Define Distribution Channels | | Division | `OVXA` | Define Divisions | | Sales Area | `OVXG` | Set up valid Sales Areas | | Sales Org → Company Code | `OVX3` | Maintain assignment | | Plant → Distribution Chain | `OVXK` | Assign Plant to Sales Org/Channel | | Shipping Point → Plant | `OVXC` | Maintain permitted assignments | | Shipping Point determination | `OVL2` | Maintain Plant/condition/loading-group result | | Business Partner | `BP` | Maintain BP roles and customer data | | Product/material | `MM01`, `MM02`, `MM03` | Create, change, display material | | Customer-material info | `VD51`, `VD52`, `VD53` | Create, change, display relationship | | Partner determination | `VOPA` | Configure partner procedures and assignments | | Sales Order | `VA01`, `VA02`, `VA03` | Create, change, display transaction result | SAP S/4HANA Cloud Public Edition uses configuration activities and Fiori apps; the same business concept may not expose a classic transaction. --- ## 14. Organizational-Key Diagnosis ### 14.1 Diagnostic sequence For an error such as “customer/material not maintained,” “Plant not allowed,” or “Shipping Point not determined,” follow the runtime dependency from broad context to exact input: ```text 1. Capture the failing document and item ↓ 2. Record the exact Sales Area and document type ↓ 3. Verify customer/BP role and organizational segments ↓ 4. Verify material Distribution Chain and Plant views ↓ 5. Verify organizational assignments ↓ 6. Reconstruct determination inputs and result ↓ 7. Check blocks, validity, status, authorization, and enhancements ``` ### 14.2 Evidence checklist | Area | Evidence to capture | | ----------------- | ------------------------------------------------------------- | | Sales context | Sales Org, Distribution Channel, Division, order type | | Partner | BP/customer number, function, selected address, required role | | Product | material number, Sales Org/Channel view, Plant view, units | | Plant | proposed/stored Plant and Distribution Chain assignment | | Shipping Point | Plant, shipping condition, loading group, determined result | | Relationship data | customer-material record and organizational key | | Runtime result | actual header/item/partner/schedule-line values | | Extensions | user exits, BAdIs, custom determination, interface mapping | ### 14.3 Diagnose the actual grain Suppose material `M-100` works in Sales Area `1000/10/00` but fails in `1000/20/00`. The global material record is not the first suspect because the same material already works elsewhere. The diagnostic focus should move to: - `MVKE` data for the failing Distribution Chain; - customer `KNVV` data for the failing Sales Area; - Plant assignment to that Distribution Chain; - condition and determination records scoped by the failing key; - blocks or validity specific to that context. This is the reusable troubleshooting pattern: > When behavior differs by organization, compare organizationally scoped data > before investigating global identity data or custom code. --- ## 15. RAP Modeling Translation ### 15.1 Ownership versus reference An SD-style RAP model should distinguish lifecycle ownership from reusable references: ```text SalesOrderRequest aggregate ownership ├── composition [0..*] Items │ └── composition [0..*] Schedules └── composition [0..*] OrderPartners Item ───────── association ─────────> Product OrderPartner ─ association ─────────> BusinessPartner Request ───── association ──────────> SalesArea / Plant reference ``` The reasoning is: - Item, Schedule, and OrderPartner rows describe this one request and normally lose their lifecycle meaning when the request is deleted. - Product, Business Partner, Plant, and organizational reference entities exist independently and are therefore associations, not compositions. `OrderPartner` can still be a composition even though it points to a Business Partner. It owns the transaction-specific fact “this BP performs this function in this request,” not the Business Partner master itself. ### 15.2 Snapshot versus live display A custom RAP application must decide deliberately which data is stored and which is dereferenced live: | Design | Benefit | Risk | | ------------------------------------------------------------- | ------------------------------------------- | ------------------------------------------------- | | Store only BP/Product key and display live association fields | Simple and always shows current master data | Historical display can drift after master changes | | Copy selected descriptive/commercial fields into transaction | Preserves what was accepted at the time | Requires clear redetermination/change rules | | Store key plus explicit snapshot fields | Separates identity from historical evidence | More fields and lifecycle logic | An association such as `_Customer.Name` is not automatically a historical snapshot. If auditability matters, the design needs explicit snapshot fields or a released standard document API that already owns those semantics. ### 15.3 Validation and determination responsibilities Representative RAP responsibilities are: - determination proposes a Plant or copies transaction currency; - validation rejects an invalid Business Partner, product, Sales Area, or organizational combination; - feature control restricts changes based on state; - authorization checks whether the user may perform the operation; - value help assists selection but does not replace backend validation. These rules belong in the business object, not only in Fiori annotations, because EML, APIs, tests, and alternate projections must receive the same protection. --- ## 16. Clean-Core and Integration Boundaries ### 16.1 Tables are landmarks, not APIs Classic tables help an authorized consultant inspect persistence. They are not stable contracts for extension or integration. Avoid designs that: - update `KNA1`, `KNVV`, `MARA`, `MVKE`, or Customizing tables directly; - expose broad table joins as public APIs without business semantics; - assume an internal table layout will remain stable across releases; - bypass BP/CVI consistency or application validations. Prefer: - released Business Partner and Product APIs; - released CDS views with the required supported capability; - released transactional business objects and EML in ABAP Cloud; - documented events or integration services; - application configuration through supported activities. Availability and release status must be checked in the target system. A CDS entity that exists is not necessarily released for every use case. ### 16.2 Read model versus write contract ```text Read/analytics released CDS view or analytical query Transactional write released API / RAP BO / documented business operation Internal diagnosis authorized app, transaction, trace, or table inspection ``` A released read model does not automatically authorize updates. Conversely, an API can execute business logic that cannot be reproduced safely by inserting database rows. ### 16.3 Extension ownership Before copying standard SD concepts into a custom RAP application, define the boundary: - If SAP S/4HANA owns the real Sales Order, extend or consume the released standard contract when possible. - If the RAP object is a request or pre-order, keep its lifecycle separate and hand off to S/4HANA through an explicit integration boundary. - Do not label a simplified custom amount derivation as complete SD pricing or a request aggregate as a standard SAP Sales Order. --- ## 17. Technical Insights and Common Misinterpretations ### 17.1 Existence is weaker than usability ```text BP exists ≠ customer role exists ≠ Company Code segment exists ≠ Sales Area segment exists ≠ partner function is valid in this document Material exists ≠ Distribution Chain sales view exists ≠ Plant view exists ≠ Plant is permitted for the Distribution Chain ≠ quantity can be confirmed ``` ### 17.2 Assignment is weaker than successful execution Organizational assignment establishes permission and reachability. Execution still depends on master data, determination, status, blocks, availability, authorization, and transaction-specific rules. ### 17.3 Master data supplies facts; the document owns the transaction The Business Partner owns reusable party identity. The Product owns reusable product identity. The Sales Order owns the fact that a particular partner, address, material, quantity, price, and date were accepted in this transaction. ### 17.4 Organizational keys explain many “same data, different result” cases If the same customer and material behave differently across orders, compare the full Sales Area, Distribution Chain, Plant, address, and document-type context. The changed behavior is often correct because a more specific master-data or configuration record applies. ### 17.5 The most specific record is not universally the winner Customer-material data is more relationship-specific than customer-only or material-only data, but field precedence is application-specific. The correct technical explanation names the field, its source sequence, and the event that triggered determination or redetermination. --- ## 18. Compact Technical Map ```text LEGAL CONTEXT Company Code │ 1:n ▼ COMMERCIAL CONTEXT Sales Organization + Distribution Channel + Division = Sales Area Sales Organization + Distribution Channel = Distribution Chain │ ├── scopes customer and material sales data └── permits Plant assignment │ ▼ FULFILLMENT CONTEXT Plant + Shipping Condition + Loading Group = Shipping Point REUSABLE MASTER DATA Business Partner ├── general identity/address ├── FI Customer / Company Code data └── Customer / Sales Area data Product/Material ├── general identity ├── Distribution Chain sales data └── Plant planning/loading data Customer-Material └── customer-specific material identity and agreements TRANSACTIONAL RESULT Sales Order ├── header: Sales Area and commercial context ├── partners: sold-to / ship-to / bill-to / payer ├── items: material, Plant, quantity, price, behavior └── schedule lines: confirmed quantity and date ``` The map should be read from top to bottom: configuration permits the context, master data supplies scoped inputs, application logic determines values, and the Sales Order records the resulting transaction. 3b:T9d0,SAP SD Organizational Structure and Master Data — Technical Reference This document explains how SAP Sales and Distribution combines organizational configuration and reusable master data to establish a valid processing context for a sales transaction. It connects business meaning to classic persistence landmarks, maintenance transactions, runtime determination, diagnostic technique, RAP modeling, and clean-core boundaries. The central technical principle is: Organizational structure defines where a transaction is permitted to run; master data supplies reusable facts for that context; the Sales Order stores the resulting transactional values. This reference distinguishes three environments: - SAP S/4HANA on-premise or private edition, where SAP GUI transactions, IMG activities, and authorized table inspection are common diagnostic tools. - SAP S/4HANA Cloud Public Edition, where Fiori applications and configuration activities replace many classic transaction-code paths. - Clean-core extension development, where released CDS entities, business objects, events, and APIs are contracts; internal tables are not. Primary SAP sources: - SAP Learning — Identifying Organizational Units in SAP S/4HANA Sales - SAP Learning — Maintaining Organizational Units for Delivery Processing - SAP Learning — Managing Business Partners - SAP Learning — Identifying the Source of Data in a Sales Document - SAP Learning — Applying the Partner Function Concept - SAP Help — Creating Customer-Material Information Records - SAP Help — Business Partner Address --- 1. The Runtime Model 1.1 Three kinds of data participate in one order text Organizational configuration Which legal and commercial units may work together? │ ▼ Master data Who is the customer? What is sold? Which context-specific defaults apply? │ ▼ Sales Order transaction Which values were proposed, derived, copied, overridden, and accepted now? These layers are related but not interchangeable: | Layer | Examples | Lifecycle | Technical role | | ---------------------------- | ------------------------------------------------------------------------------------- | ------------------------------ | -------------------------------------------------- | | Organizational configuration | Company Code, Sales Organization, Sales Area, Plant assignment | Relatively stable Customizing | Defines permitted processing contexts | | Master data | Business Partner, customer segments, product/material, customer-material relationship |3c:Tbf1,# SAP SD Organizational Structure and Master Data — Technical Reference This document explains how SAP Sales and Distribution combines organizational configuration and reusable master data to establish a valid processing context for a sales transaction. It connects business meaning to classic persistence landmarks, maintenance transactions, runtime determination, diagnostic technique, RAP modeling, and clean-core boundaries. The central technical principle is: > Organizational structure defines where a transaction is permitted to run; > master data supplies reusable facts for that context; the Sales Order stores > the resulting transactional values. This reference distinguishes three environments: - **SAP S/4HANA on-premise or private edition**, where SAP GUI transactions, IMG activities, and authorized table inspection are common diagnostic tools. - **SAP S/4HANA Cloud Public Edition**, where Fiori applications and configuration activities replace many classic transaction-code paths. - **Clean-core extension development**, where released CDS entities, business objects, events, and APIs are contracts; internal tables are not. Primary SAP sources: - [SAP Learning — Identifying Organizational Units in SAP S/4HANA Sales](https://learning.sap.com/courses/exploring-sap-s-4hana-sales-essentials/identifying-organizational-units-in-sap-s-4hana-sales_ddb48d1e-1f57-46bd-8d13-d8e4ef6d0560) - [SAP Learning — Maintaining Organizational Units for Delivery Processing](https://learning.sap.com/courses/configuring-delivery-processing-in-sap-s-4hana-sales/maintaining-the-organizational-units-for-delivery-processing) - [SAP Learning — Managing Business Partners](https://learning.sap.com/courses/customizing-core-settings-in-financial-accounting-in-sap-s4hana/managing-business-partners) - [SAP Learning — Identifying the Source of Data in a Sales Document](https://learning.sap.com/courses/fundamental-customizing-in-sap-s-4hana-sales/identifying-the-source-of-data-in-a-sales-document) - [SAP Learning — Applying the Partner Function Concept](https://learning.sap.com/courses/fundamental-customizing-in-sap-s-4hana-sales/applying-the-partner-function-concept) - [SAP Help — Creating Customer-Material Information Records](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/7b24a64d9d0941bda1afa753263d9e39/3f8bc95360267214e10000000a174cb4.html) - [SAP Help — Business Partner Address](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/74b0b157c81944ffaac6ebc07245b9dc/e84813a97a3645b38b41d374a17ae713.html) --- ## 1. The Runtime Model ### 1.1 Three kinds of data participate in one order ```text Organizational configuration Which legal and commercial units may work together? │ ▼ Master data Who is the customer? What is sold? Which context-specific defaults apply? │ ▼ Sales Order transaction Which values were proposed, derived, copied, overridden, and accepted now? ``` These layers are related but not interchangeable:3d:Tae7a, # SAP SD Sales Document Control and Pricing — Technical Reference This document explains how SAP Sales and Distribution controls a Sales Order at header, item, and schedule-line level and how the condition technique builds the document-specific pricing result. It connects business grain to determination inputs, Customizing, runtime persistence, diagnostic evidence, RAP concepts, and clean-core boundaries. The central technical principle is: > First identify the grain and the selected control object. Then distinguish > how that object was determined from what its definition makes it do. This reference distinguishes three environments: - **SAP S/4HANA on-premise or private edition**, where SAP GUI transactions, IMG activities, Pricing Analysis, and authorized table inspection are common diagnostic tools. - **SAP S/4HANA Cloud Public Edition**, where Fiori applications and configuration activities provide the supported paths and may add features such as flexible item-category determination. - **Clean-core extension development**, where released CDS entities, business objects, and APIs are contracts; classic tables and Customizing views are diagnostic landmarks rather than integration interfaces. Primary SAP sources: - [SAP Help — How Sales Documents Are Controlled](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/7b24a64d9d0941bda1afa753263d9e39/c264b65334e6b54ce10000000a174cb4.html) - [SAP Learning — Configuring a Sales Document Type](https://learning.sap.com/courses/fundamental-customizing-in-sap-s-4hana-sales/configuring-a-sales-document-type) - [SAP Learning — Configuring an Item Category](https://learning.sap.com/courses/fundamental-customizing-in-sap-s-4hana-sales/configuring-an-item-category-1) - [SAP Help — Determining Sales Document Item Categories](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/7b24a64d9d0941bda1afa753263d9e39/dc89c95360267214e10000000a174cb4.html) - [SAP Learning — Assigning Schedule Line Categories](https://learning.sap.com/courses/fundamental-customizing-in-sap-s-4hana-sales/assigning-schedule-line-categories) - [SAP Learning — Introducing the Condition Technique](https://learning.sap.com/courses/configuring-pricing-in-sap-s-4hana-sales/introducing-the-condition-technique_dce0f313-dee6-470e-8851-3f1773cb5d45) - [SAP Help — Pricing Information and Analysis](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/4dd8cb7b1c484b4b93af84d00f60fdb8/918dc95360267214e10000000a174cb4.html) - [SAP Help — Sales Order Item Pricing Element](https://help.sap.com/docs/SAP_S4HANA_CLOUD/03c04db2a7434731b7fe21dca77440da/abf59161a5734e0393d30c5fa2f41053.html) --- ## 1. Sales Document Runtime Architecture ### 1.1 The control chain ```text Header Sales document type │ supplies whole-transaction context ▼ Item Item category │ supplies product/service-line behavior ▼ Schedule line Schedule-line category │ supplies dated-quantity fulfillment behavior ▼ Subsequent processing delivery, requirements, procurement, goods movement, billing ``` The three controls cooperate, but they answer different questions: | Level | Business scope | Main control object | Stored result | | ------------- | ----------------------------- | ---------------------- | ------------- | | Header | One commercial transaction | Sales document type | `VBAK-AUART` | | Item | One product/service line | Item category | `VBAP-PSTYV` | | Schedule line | One quantity/date subdivision | Schedule-line category | `VBEP-ETTYP` | In common business speech, “line” often means Sales Order item or line item. Technically, always clarify the grain because a Sales Order item can itself contain several schedule lines and pricing-element rows. ### 1.2 Definition, assignment, and transaction result These are three different objects: ```text Category definition Describes what a category does Determination assignment Maps runtime inputs to a proposed category Selected transaction result Stores the category actually used in this document ``` Example: ```text VOV7 / TVAP → defines item category TAN VOV4 / T184 → proposes TAN for OR + NORM + blank + blank VBAP-PSTYV → stores the item category selected for Item 10 ``` A maintenance transaction changes reusable configuration. A selected transaction result records which value one business document contains. They must not be described as the same thing. ### 1.3 The primary diagnostic split ```text Unexpected category in the document → reconstruct the determination input and assignment Expected category, unexpected processing behavior → inspect the selected category's definition and dependent configuration ``` This split prevents unnecessary custom-code investigation. Standard determination must first be explained with runtime evidence. --- ## 2. Header, Item, and Schedule-Line Grain ### 2.1 Placement rule Place a value at the broadest level where it remains true without losing business meaning: ```text Entire commercial transaction → Header One product or service → Item One quantity on one date → Schedule line ``` | Level | Representative fields | | ------------- | ----------------------------------------------------------------------------------------------------- | | Header | document type, Sales Area, sold-to party, customer reference, document currency, overall value/status | | Item | material, ordered quantity, sales unit, Plant, item category, rejection reason, net value | | Schedule line | requested date/quantity, confirmed date/quantity, schedule category, delivery block | Screen position does not prove technical grain. A field shown in a page header can be an aggregate, and a visually repeated value can be stored separately at item level. ### 2.2 Classic persistence and keys | Level | Table landmark | Key excluding client | One row represents | | ------------- | -------------- | ----------------------- | ---------------------------------- | | Header | `VBAK` | `VBELN` | One sales-document header | | Item | `VBAP` | `VBELN + POSNR` | One item in the document | | Schedule line | `VBEP` | `VBELN + POSNR + ETENR` | One dated-quantity row in the item | ```text VBAK-VBELN = VBAP-VBELN VBAP-VBELN + VBAP-POSNR = VBEP-VBELN + VBEP-POSNR ``` `ETENR` identifies the schedule line. It is not the requested date or quantity. ### 2.3 Downward propagation and upward aggregation Selected header values can be copied or propagated into item fields, and an item may hold a permitted exception. This is not dynamic inheritance. ```text Header default ──copy/propagate──> aligned item value │ └── item-specific override, if allowed ``` Results also roll upward: ```text Schedule confirmations → item fulfillment state Item values → header total Item statuses → overall document status ``` Overall status is a summary, not proof that every child is in the same state. ### 2.4 Wrong-grain joins If one item has two schedule lines, joining `VBAP` to `VBEP` produces two rows for that item. Its item net value is repeated. ```text Item 10 net value: 1,000 Schedule 0001 → joined item value 1,000 Schedule 0002 → joined item value 1,000 Naive SUM → 2,000 incorrect ``` Aggregate a measure at its native grain before joining it to a lower grain. The same rule applies when joining pricing-element rows to items. --- ## 3. Sales Document Type ### 3.1 Responsibility The Sales Document Type describes the overall commercial transaction, such as an inquiry, quotation, standard order, return, or credit memo request. It can control or propose: - the broad sales-document category; - number-range and general document behavior; - delivery and billing blocks; - requested-delivery-date and other defaults; - messages or checks for reference and master data; - proposed follow-on delivery or billing document types; - the document pricing procedure used later in pricing-procedure determination. It does not fully determine the behavior of every item. The item category and schedule-line category provide lower-grain controls. ### 3.2 Technical map ```text Maintenance: VOV8 Configuration table: TVAK Transaction result: VBAK-AUART ``` `AUART` identifies the Sales Document Type. Standard code `OR` commonly means a standard Sales Order. The code is configuration, not an ABAP keyword, and a customer can copy a standard type into a `Z...` type with different behavior. SAP recommends creating a custom document type by copying a similar tested type because many dependent assignments reference it. A copied code must still be reviewed; copying does not prove that every inherited setting fits the new business process. --- ## 4. Item Category ### 4.1 Responsibility An Item Category controls how one product or service line participates in the sales process. It can influence: - whether pricing is relevant; - whether and how the item is billed; - whether business data may differ from the header; - whether the line represents a material, service, value, or text item; - the incompletion procedure; - whether schedule lines are allowed; - behavior of main items and subitems; - delivery relevance for items without schedule lines. The determination inputs select an Item Category. The Item Category definition then controls the line. Selection and behavior are distinct stages. ### 4.2 Standard determination formula ```text Sales document type + material item-category group + item usage + higher-level item category = proposed item category ``` | Input | Meaning | Common technical clue | | ---------------------------- | ------------------------------------------------------- | ---------------------------------------------------------- | | Sales document type | Whole-document transaction context | `VBAK-AUART` | | Material item-category group | General sales-processing classification of the material | `MVKE-MTPOS`, scoped by Sales Org/Channel | | Item usage | Special purpose in the current document | Often blank for an ordinary stock item | | Higher-level item category | Processing context from a parent item | Relevant to free goods, BOM components, and other subitems | ### 4.3 `OR + NORM + blank + blank → TAN` The common standard illustration means: | Code | Meaning in the example | | --------------------------- | -------------------------------------------------------- | | `OR` | Standard Sales Order document type | | `NORM` | Normal-item item-category group from material sales data | | blank usage | No specialized item usage applies | | blank higher-level category | Standalone item, not a subitem | | `TAN` | Standard order item category proposed by the assignment | ```text OR supplies order context NORM supplies material processing classification blank says no special usage blank says no parent-item context TAN is the configured default result ``` This is an example, not a universal invariant. The assignment can differ by system configuration. In supported Public Cloud scenarios, flexible item- category determination can additionally use configured business rules when the feature and prerequisites apply. ### 4.4 Main item and subitem example ```text Item 10 Material M1 100 EA normal priced item Item 20 Material M1 10 EA free-of-charge subitem Higher-level item = 10 ``` The higher-level Item Category lets the determination distinguish a subitem from an unrelated standalone item even when both use the same material. ### 4.5 Technical map ```text Determine/assign: VOV4 Assignment table: T184 Define behavior: VOV7 Definition table: TVAP Selected result: VBAP-PSTYV Master-data input: MVKE-MTPOS ``` The customer number is not one of the four standard item-category determination keys. Customer context can influence other data and newer flexible rule scenarios, but it should not be inserted into the classic formula. --- ## 5. Schedule-Line Category ### 5.1 Responsibility A Schedule-Line Category controls how one dated quantity participates in fulfillment. It can influence: - delivery relevance; - transfer of requirements; - availability checking; - the movement type used by a later goods movement; - automatic procurement or purchase-requisition behavior; - schedule-line delivery blocks. The Item Category must permit schedule lines before schedule-line control can participate. ### 5.2 Two-step determination ```text Attempt 1: Item category + MRP type Attempt 2: Item category + blank MRP type fallback ──────────────────────────────────────────────────── Result: proposed schedule-line category ``` The MRP type is Plant-specific material data, commonly `MARC-DISMM`. Therefore, the runtime Plant from the affected item is part of the diagnostic context even though Plant is not displayed as a direct key in `VOV5`. ### 5.3 Technical map ```text Determine/assign: VOV5 Assignment table: TVEPZ Define behavior: VOV6 Definition table: TVEP Selected result: VBEP-ETTYP Master-data input: MARC-DISMM ``` The assignment can also specify alternative Schedule-Line Categories that the user is allowed to select instead of the proposal. ### 5.4 Delivery relevance nuance For an ordinary item with schedule lines, schedule-line configuration is central to delivery relevance of the dated quantity. The Item Category's delivery-relevance indicator is particularly used for delivery-relevant items without schedule lines, such as certain text items. Therefore neither of these absolute claims is safe: ```text “Only the item category controls delivery relevance.” “Only the schedule-line category controls delivery relevance.” ``` The correct answer begins with whether the item has schedule lines and then identifies the relevant control. ### 5.5 Movement type is a future posting rule ```text Schedule category contains movement-type control ≠ Inventory has already changed ``` Saving the Sales Order records demand and processing instructions. Inventory changes only when the logistics process executes an applicable goods movement, normally at Post Goods Issue for an outbound sell-from-stock scenario. --- ## 6. Complete Sales-Document Control Map | Purpose | Maintenance | Configuration landmark | Runtime result | | -------------------------------- | ----------- | ---------------------- | ------------------------ | | Define Sales Document Type | `VOV8` | `TVAK` | `VBAK-AUART` | | Determine Item Category | `VOV4` | `T184` | proposes `VBAP-PSTYV` | | Define Item Category | `VOV7` | `TVAP` | behavior of `VBAP-PSTYV` | | Determine Schedule-Line Category | `VOV5` | `TVEPZ` | proposes `VBEP-ETTYP` | | Define Schedule-Line Category | `VOV6` | `TVEP` | behavior of `VBEP-ETTYP` | Compact memory map: ```text VOV8 defines the header transaction VOV4 finds the Item Category VOV7 defines the Item Category VOV5 finds the Schedule-Line Category VOV6 defines the Schedule-Line Category ``` All `VOV...` transactions are related to SD configuration, but they do not all configure the same object. The prefix alone is not a diagnostic explanation. Always name the IMG activity and the affected runtime result. --- ## 7. Pricing Architecture ### 7.1 Why pricing is not one material price The transaction price can depend on: - customer or customer group; - product or product hierarchy; - Sales Area; - ordered quantity and scale; - pricing date and validity interval; - currency and unit of measure; - negotiated discounts; - freight, surcharge, promotion, and tax; - exclusion, requirement, formula, or manual entry; - document and billing repricing rules. SAP therefore uses the condition technique: reusable configuration and condition master data produce document-specific pricing-element rows. ### 7.2 Two separate pricing pipelines ```text PIPELINE A — SELECT THE PRICING PROCEDURE Sales Organization + Distribution Channel + Division + Document Pricing Procedure + Customer Pricing Procedure = Pricing Procedure PIPELINE B — EXECUTE THE PRICING PROCEDURE Pricing Procedure → Step / counter → Condition Type → Access Sequence → Condition Table key → Valid Condition Record → Rate / base / unit / scale / formula → Document Pricing Element ``` Pipeline A answers **which calculation framework applies**. Pipeline B answers **how that framework calculated the item**. --- ## 8. Pricing-Procedure Determination ### 8.1 Inputs ```text Sales Area = Sales Organization + Distribution Channel + Division Document Pricing Procedure ← Sales Document Type ← classic clue TVAK-KALVG Customer Pricing Procedure ← sold-to party Sales Area data ← classic clue KNVV-KALKS Selected Pricing Procedure ← determination configured in OVKK ← common document clue VBAK-KALSM ``` The input is not simply “customer plus material.” Customer/material keys are commonly used later by a condition-table access; they do not replace pricing- procedure determination. ### 8.2 Technical map | Object | Landmark | Purpose | | ------------------------- | ------------------------------------- | ------------------------------------------------------------------ | | Procedure determination | `OVKK` / `T683V` | Map Sales Area and two procedure indicators to a pricing procedure | | Document procedure source | `VOV8` / `TVAK-KALVG` | Supply indicator from Sales Document Type | | Customer procedure source | BP/customer sales data / `KNVV-KALKS` | Supply indicator for sold-to in the Sales Area | | Selected result | `VBAK-KALSM` | Record the procedure used by the document | If the wrong pricing procedure was selected, tracing its condition records is premature. First reconstruct all five inputs and prove the `OVKK` result. --- ## 9. Condition-Technique Components ### 9.1 Responsibility map | Component | Responsibility | Not the same as | | ----------------- | ---------------------------------------------------------------------------- | ------------------------------------ | | Pricing Procedure | Orders condition types and step-level calculation controls | A customer's maintained price | | Condition Type | Represents one concept such as price, discount, freight, surcharge, or tax | The actual rate | | Access Sequence | Searches condition tables in priority order for one automatic Condition Type | The procedure's condition-type order | | Condition Table | Defines the fields forming one search key | A record containing a rate | | Condition Record | Stores rate, validity, currency/unit, and scales for one key value | The calculated document result | | Pricing Element | Stores how the condition participated in one document | Reusable master data | The most important distinction is: ```text Pricing Procedure sequence = calculation order across Condition Types Access Sequence = record-search order inside one Condition Type ``` ### 9.2 Specific-to-general access ```text Access 10 Sales Org + Customer + Material ↓ no applicable record Access 20 Customer Price Group + Material ↓ no applicable record Access 30 Sales Org + Material ↓ record found Result use the applicable general material record ``` The order preserves commercial priority. A negotiated customer/material record normally deserves priority over a general material fallback. An unsuccessful specific access can be expected behavior rather than an error. ### 9.3 Condition table versus condition record ```text Condition table definition Key fields: Sales Org + Customer + Material Condition record instance 1000 + C100 + M200 90 EUR per 1 EA Valid 01 Jan–31 Dec ``` Generated `Axxx` tables commonly index condition records using the configured key and point to condition-record identity such as `KNUMH`. The number and key layout are configuration-dependent. A record can exist but not apply because: - the access was never executed; - runtime key values differ; - the pricing date is outside validity; - an earlier access already satisfied the search; - the condition was excluded or made inactive; - unit, currency, scale, or other control does not match the expectation. --- ## 10. Pricing-Procedure Row Controls ### 10.1 Step and counter The step controls sequence. The counter distinguishes multiple entries at the same step. ```text Step 10 / Counter 0 → base price Step 20 / Counter 0 → discount Step 30 / Counter 0 → subtotal Step 40 / Counter 0 → freight Step 50 / Counter 0 → tax ``` The actual procedure can contain more complex bases, subtotals, statistical rows, exclusions, and formulas. ### 10.2 Important controls | Control | Technical meaning | | ------------------------------- | ------------------------------------------------------------------------------------------------- | | Requirement | Routine decides whether the row is processed in the current context | | Manual | Condition is intended for manual input rather than ordinary automatic access | | Mandatory | The condition is expected; absence can affect completeness or messages according to configuration | | Statistical | Condition is calculated and retained without normal contribution to net value | | From/To | References earlier steps as a calculation or subtotal range | | Subtotal | Stores an intermediate result for subsequent use | | Alternative base formula | Replaces the ordinary condition base | | Alternative calculation formula | Replaces ordinary condition-value calculation | Statistical does not mean useless. A statistical condition can support cost, credit, analytics, or another downstream purpose. ### 10.3 Inactive is not draft An inactive pricing condition is a result row that does not currently contribute to the effective calculation. It can have been found and then deactivated through exclusion or competing-condition logic. ```text Material discount: 5% found, inactive Customer discount: 10% found, active Rule: retain only the better discount ``` This is unrelated to a RAP draft, which is a persisted editing state for a business-object instance. --- ## 11. Rate, Base, Unit, Scale, and Value ### 11.1 Core arithmetic concepts ```text Condition rate = maintained amount or percentage Condition base = amount or quantity affected by the rate Condition value = calculated contribution in this document ``` Percentage example: ```text Rate: 10% Base: 1,000 EUR Value: -100 EUR ``` Pricing-unit example: ```text Rate: 100 EUR Pricing unit: 10 Condition unit: EA Meaning: 100 EUR per 10 EA 20 EA → 200 EUR ``` The numerical rate is incomplete without its currency, unit, pricing unit, and scale context. ### 11.2 Pricing-result fields | Field | Meaning | Diagnostic use | | ------- | ------------------------------------------- | ----------------------------------------- | | `KSCHL` | Condition Type | Identify the pricing concept | | `KBETR` | Condition rate | Compare with the master record/scale | | `KAWRT` | Condition base value | Verify quantity, amount, or base formula | | `KWERT` | Condition value | Verify calculated document contribution | | `KPEIN` | Pricing unit | Interpret rate per 1, 10, 100, and so on | | `KMEIN` | Condition unit | Interpret unit to which the rate applies | | `KNUMH` | Condition-record reference where applicable | Trace selected master record | | `KSTAT` | Statistical indicator | Explain net-value participation | | `KINAK` | Inactive context | Explain why a found row is ineffective | | `KHERK` | Condition origin | Help identify how the row entered pricing | Diagnostic split: ```text Wrong KBETR → record, scale, conversion, or manual rate Wrong KAWRT → quantity, amount, or alternative-base logic Wrong KPEIN/KMEIN → pricing-unit or UoM interpretation Inputs correct but KWERT wrong → formula, sign, conversion, or rounding ``` --- ## 12. Pricing Configuration and Master-Data Landmarks ### 12.1 Classic maintenance transactions | Transaction | Responsibility | | ---------------------- | ---------------------------------------------------------------------------------------- | | `OVKK` | Determine the Sales pricing procedure | | `V/08` | Define procedure steps, counters, Condition Types, requirements, subtotals, and formulas | | `V/06` | Define Condition Type behavior and assign its Access Sequence | | `V/07` | Define ordered accesses and Condition Tables in an Access Sequence | | `V/03`, `V/04`, `V/05` | Create, change, and display classic Condition Table definitions | | `VK11`, `VK12`, `VK13` | Create, change, and display condition records | `VK13` displays condition master data. It is not the Sales Order Pricing Analysis technical view. ```text Pricing Analysis technical view → what fields and values the runtime searched VK13 → what condition record was maintained ``` Diagnosis compares them. ### 12.2 Configuration tables | Object | Classic landmark | Meaning | | ------------------------------- | ----------------- | ---------------------------------------- | | Pricing-procedure determination | `T683V` | Input combination selects procedure | | Pricing-procedure steps | `T683S` | Step/counter and row controls | | Condition Type | `T685` | Condition-Type definition | | Access Sequence | `T682I` / `T682Z` | Accesses and access fields | | Condition Table | generated `Axxx` | Business-key index for condition records | ```text T683V selects procedure T683S orders and controls calculation steps T685 defines the Condition Type T682I/Z defines the record-search strategy Axxx indexes condition records by configured business key ``` These objects must not be updated directly. Use authorized Customizing or master-data applications and transport configuration through the landscape. --- ## 13. Document Pricing-Result Persistence ### 13.1 S/4HANA result model ```text VBAK-KNUMV = PRCD_ELEMENTS-KNUMV ``` One document pricing result contains items, procedure steps, and potentially several entries at one step. A useful classic technical grain is: ```text KNUMV + KPOSN + STUNR + ZAEHK ``` | Field | Identifies | | ------- | ---------------------------------------------------------------------------- | | `KNUMV` | Pricing result for a business document | | `KPOSN` | Item within that pricing result; header context can use a header-level value | | `STUNR` | Procedure step | | `ZAEHK` | Entry/counter within the step | `PRCD_ELEMENTS` stores the document result, not the reusable condition master record. Joining it to `VBAP` creates multiple rows per Sales Order item. ### 13.2 `KONV` versus `PRCD_ELEMENTS` ```text SAP ERP KONV → traditional persisted document pricing result SAP S/4HANA PRCD_ELEMENTS → persisted pricing result KONV → compatibility/application structure role, not old persistence ``` It is inaccurate to say that `KONV` can never appear in S/4HANA code. The precise statement is that `PRCD_ELEMENTS` replaced it in the database persistence role. Neither object should become a new clean-core integration contract. ### 13.3 Result-grain aggregation risk ```text Sales Order Item 10: net value 1,000 Pricing row PR00: 1,200 Pricing row K004: -100 Pricing row K007: -100 Join result repeats Item.NetValue three times. SUM(Item.NetValue) = 3,000 incorrect ``` Use pricing-element values for pricing analysis and item values for item-level reporting. Aggregate each measure at its own grain before combining them. --- ## 14. Pricing Analysis Failure Classes Pricing Analysis should classify the failure before the consultant searches tables or enhancements. | Runtime state | Meaning | Primary investigation | | ----------------------------------- | --------------------------------------------- | ------------------------------------------------------------ | | Condition Type skipped | Procedure control prevented processing | Requirement, manual-only setting, context, procedure row | | Access executed, no record found | No applicable record matched | Runtime key, pricing date, validity, condition master | | Record found but condition inactive | Condition was considered but made ineffective | Exclusion, competition, manual replacement, limits | | Active condition, wrong value | Selection succeeded but calculation differs | Rate, base, scale, unit, formula, sign, conversion, rounding | ```text Skipped → procedure control Not found → access key and record Inactive → exclusion or competition Wrong value → calculation inputs ``` “The record exists in `VK13`” does not prove that it applied. Pricing Analysis must show that the expected Condition Type and access were executed with the expected runtime key and date. --- ## 15. End-to-End Pricing Diagnostic Algorithm ### 15.1 Capture the exact grain In `VA03` or the corresponding Fiori application, capture: - Sales Order `VBELN` and item `POSNR`; - expected and actual net value; - expected and actual Condition Type/rate; - Sales Area, sold-to party, material, quantity, unit, currency, and pricing date. Do not begin from a screenshot containing only the final total. ### 15.2 Confirm item eligibility Inspect: - selected Item Category `VBAP-PSTYV`; - whether the Item Category is pricing relevant; - rejection, incompletion, status, or special item behavior; - manual changes or reference-document copying. ### 15.3 Prove pricing-procedure selection ```text Sales Area + TVAK-KALVG + KNVV-KALKS → OVKK / T683V → expected Pricing Procedure → compare with VBAK-KALSM ``` If the procedure is wrong, stop and diagnose its inputs or determination. ### 15.4 Verify procedure and Condition Type In `V/08`, prove that the expected Condition Type exists at the expected step/counter and inspect requirement, manual, mandatory, statistical, subtotal, and formula controls. In `V/06`, prove its assigned Access Sequence and Condition-Type behavior. ### 15.5 Trace the Access Sequence Use Pricing Analysis to inspect each access in order: ```text Condition Type processing status ├── no → procedure/requirement/manual control └── yes ↓ Expected-access execution status ├── no → access requirement or earlier exclusive success └── yes ↓ Condition-record search result ├── no → compare runtime key/date with condition record └── yes ↓ Condition activity status ├── no → exclusion/competition/inactive reason └── yes → validate calculation ``` ### 15.6 Compare runtime key with condition master From Pricing Analysis technical data, record the actual search values. Compare them with `VK13` or the supported condition-record application: - Condition Type; - full Condition Table key; - valid-from and valid-to dates; - rate and currency; - pricing unit and Condition Unit; - quantity/value scale and selected tier. ### 15.7 Validate the calculation Inspect `KBETR`, `KAWRT`, `KWERT`, `KPEIN`, `KMEIN`, formulas, sign, conversion, and rounding. A correct record selection does not prove correct arithmetic. ### 15.8 Widen only after standard logic is explained Then investigate: - manual conditions; - condition exclusion; - reference-document copy and repricing type; - user exits, BAdIs, formulas, or custom routines; - external pricing integration; - API payload behavior; - release-specific features. The evidence chain should explain exactly where observed behavior diverges: ```text grain → eligibility → procedure → step → access → record → calculation → result ``` --- ## 16. Item- and Schedule-Category Diagnostic Algorithms ### 16.1 Wrong Item Category ```text 1. Capture VBAK-AUART and VBAP-PSTYV 2. Read MVKE-MTPOS for the exact Sales Org/Channel 3. Capture item usage 4. Capture higher-level Item Category when it is a subitem 5. Reconstruct the exact VOV4 / T184 combination 6. Compare proposed, allowed alternatives, and actual result 7. If result is expected, inspect behavior in VOV7 / TVAP 8. Only then inspect enhancements or flexible determination ``` ### 16.2 Correct schedule category but no requirements transfer ```text 1. Identify VBELN + POSNR + ETENR 2. Capture VBAP-PSTYV and VBEP-ETTYP 3. Read MARC-DISMM for the exact Material and Plant 4. Verify exact Item Category/MRP Type assignment in VOV5 5. Verify blank-MRP fallback if exact assignment is absent 6. Inspect selected category in VOV6 7. Check requirements-transfer and availability controls 8. Check status, blocks, dates, and dependent configuration 9. Widen to custom code only after standard evidence is complete ``` ### 16.3 Configuration result versus execution evidence | Configuration says | It proves | It does not prove | | ------------------------------------ | ----------------------------------------------- | ------------------------------------- | | Item is pricing relevant | Pricing may run for the item | Correct Condition Record was selected | | Schedule line transfers requirements | Demand transfer is configured | ATP confirmed the requested quantity | | Movement type is assigned | Later goods movement has a posting rule | PGI occurred | | Item is billing relevant | Subsequent billing is permitted by that control | Billing document exists | --- ## 17. Sales Order Pricing Versus Billing Pricing A Billing Document can copy or redetermine pricing according to copy-control pricing type and process design. Potential differences include: - different pricing date; - updated Condition Records or validity; - actual billed quantity and scale; - exchange-rate or currency handling; - tax redetermination; - copied or redetermined manual conditions; - selected pricing type in copy control. ```text Sales Order pricing result ≠ guaranteed identity Billing Document pricing result ``` Before classifying a difference as a defect, capture the document flow, reference relationship, pricing dates, source/target pricing elements, billed quantity, and copy-control pricing type. --- ## 18. RAP Translation and Portfolio Boundary ### 18.1 SD determination versus RAP determination | Concept | Purpose | Mechanism | | ------------------------- | ------------------------------------------------------ | ---------------------------------------------------- | | SD category determination | Select configured category from business inputs | Customizing assignment such as `VOV4` or `VOV5` | | SD pricing determination | Select and execute pricing configuration and records | Condition technique | | RAP determination | Automatically derive BO fields after declared triggers | Behavior definition and behavior-pool implementation | | RAP validation | Reject inconsistent BO state | Behavior definition and behavior pool | ```text SD: OR + NORM + blank + blank → TAN RAP: RequestedQuantity changes → recalculate NetAmount ``` The shared word “determination” does not make these mechanisms equivalent. ### 18.2 `deriveAmounts` is not the SD condition technique A simple RAP portfolio calculation can be: ```text RequestedQuantity × UnitPrice → Item.NetAmount Σ Item.NetAmount → Request.TotalAmount ``` Standard SD pricing is: ```text Procedure determination → Condition Types → Access Sequences → Condition Records → rates, bases, units, scales, formulas → discounts, freight, tax, exclusion → document pricing result ``` The RAP calculation is credible for an SD-inspired order request, but it must not be presented as a reimplementation of standard SAP Sales pricing. ### 18.3 Safe portfolio evolution The custom BO can expose an explicit pricing status: ```text Estimated → custom request-level calculation Priced by S/4HANA → result returned by a released Sales Order/pricing contract ``` Keep the integration behind an adapter so the custom domain model does not depend directly on `PRCD_ELEMENTS`, `KONV`, or generated `Axxx` tables. --- ## 19. Clean-Core Access and Extension Rules ### 19.1 Persistence is not a write interface Never repair a pricing or category symptom by directly updating: - `VBAK`, `VBAP`, or `VBEP`; - `PRCD_ELEMENTS` or condition master tables; - `TVAK`, `TVAP`, `TVEP`, `T184`, or other Customizing tables. Such writes bypass business logic, dependent updates, authorization, consistency, transport governance, and compatibility contracts. ### 19.2 Preferred contracts Use, as available and released in the target system: - Sales Order business objects and APIs for transactional operations; - released CDS views for supported read and analytical use cases; - Sales Order item-pricing-element API nodes for pricing-result consumption; - supported pricing configuration and condition-record applications; - released enhancement points for additional fields or rules. Release status and supported capability must be checked in the target system. An entity can exist without being released for Cloud development or without supporting transactional writes. ### 19.3 Cloud configuration distinction Public Cloud commonly exposes configuration activities through SAP Central Business Configuration or the supported configuration environment rather than classic transactions. Flexible Item Category Determination can supplement standard assignment in supported scenarios by evaluating configured business rules. This does not invalidate the classic four-input model. It means the diagnostic record must include edition, release, activated feature, and business-rule result before concluding that `T184` alone explains the selected category. --- ## 20. Technical Insights and Common Misinterpretations ### 20.1 Category code does not explain behavior by itself `TAN` is a selected classification. Its effective behavior comes from the definition and dependent settings in the target system. Never diagnose only from the label “standard item.” ### 20.2 Material classification does not fully determine the item `NORM` supplies one input. Document type, usage, and higher-level category allow the same material to participate differently across commercial contexts. ### 20.3 A valid Condition Record is not necessarily applicable Applicability requires that the correct procedure and Condition Type execute the expected access with matching runtime keys and pricing date, and that the result remains active. ### 20.4 A selected price is not a material-master property Pricing elements belong to the document result. They can depend on customer, date, quantity, currency, commercial agreements, and calculation controls that do not belong to the material alone. ### 20.5 Selection, calculation, and posting are separate boundaries ```text Category selected → classification result Price calculated → document commercial result Delivery created → execution document exists PGI posted → inventory movement occurred Billing posted → invoice/accounting boundary occurred ``` Evidence from one boundary must not be used to claim that a later boundary has completed. ### 20.6 Configuration before customization The strongest diagnostic order is: ```text Capture actual grain → prove stored result → reconstruct inputs → prove assignment → inspect definition → inspect dependent master/configuration → investigate custom code ``` This is not an assumption that custom code is harmless. It is an evidence strategy that first explains standard runtime behavior and gives custom-code analysis precise input/output expectations. --- ## 21. Compact Technical Map ```text SALES DOCUMENT CONTROL Header VOV8 / TVAK → Sales Document Type → VBAK-AUART │ ▼ Item Category determination VBAK-AUART + MVKE-MTPOS + item usage + higher-level Item Category → VOV4 / T184 → VBAP-PSTYV → behavior in VOV7 / TVAP │ ▼ Schedule-Line Category determination VBAP-PSTYV + MARC-DISMM for Material/Plant → VOV5 / TVEPZ, then blank-MRP fallback → VBEP-ETTYP → behavior in VOV6 / TVEP PRICING CONTROL Sales Area + TVAK-KALVG + KNVV-KALKS → OVKK / T683V → VBAK-KALSM Pricing Procedure │ ▼ V/08 / T683S procedure step → V/06 / T685 Condition Type → V/07 / T682I/Z Access Sequence → generated Axxx Condition Table key → matching valid Condition Record → rate + base + unit + scale + formula → PRCD_ELEMENTS document result ``` Read both maps in the same order: capture the stored result, reconstruct the inputs that selected it, inspect the reusable definition that controls its behavior, and only then widen the investigation. 3e:T927,SAP SD Sales Document Control and Pricing — Technical Reference This document explains how SAP Sales and Distribution controls a Sales Order at header, item, and schedule-line level and how the condition technique builds the document-specific pricing result. It connects business grain to determination inputs, Customizing, runtime persistence, diagnostic evidence, RAP concepts, and clean-core boundaries. The central technical principle is: First identify the grain and the selected control object. Then distinguish how that object was determined from what its definition makes it do. This reference distinguishes three environments: - SAP S/4HANA on-premise or private edition, where SAP GUI transactions, IMG activities, Pricing Analysis, and authorized table inspection are common diagnostic tools. - SAP S/4HANA Cloud Public Edition, where Fiori applications and configuration activities provide the supported paths and may add features such as flexible item-category determination. - Clean-core extension development, where released CDS entities, business objects, and APIs are contracts; classic tables and Customizing views are diagnostic landmarks rather than integration interfaces. Primary SAP sources: - SAP Help — How Sales Documents Are Controlled - SAP Learning — Configuring a Sales Document Type - SAP Learning — Configuring an Item Category - SAP Help — Determining Sales Document Item Categories - SAP Learning — Assigning Schedule Line Categories - SAP Learning — Introducing the Condition Technique - SAP Help — Pricing Information and Analysis - SAP Help — Sales Order Item Pricing Element --- 1. Sales Document Runtime Architecture 1.1 The control chain text Header Sales document type │ supplies whole-transaction context ▼ Item Item category │ supplies product/service-line behavior ▼ Schedule line Schedule-line category │ supplies dated-quantity fulfillment behavior ▼ Subsequent processing delivery, requirements, procurement, goods movement, billing The three controls cooperate, but they answer different questions: | Level | Business scope | Main control object | Stored result | | ------------- | ----------------------------- | ---------------------- | ------------- | | Header | One commercial transaction | Sales document type | VBAK-AUART | | Item | One product/service line |3f:Tc56,# SAP SD Sales Document Control and Pricing — Technical Reference This document explains how SAP Sales and Distribution controls a Sales Order at header, item, and schedule-line level and how the condition technique builds the document-specific pricing result. It connects business grain to determination inputs, Customizing, runtime persistence, diagnostic evidence, RAP concepts, and clean-core boundaries. The central technical principle is: > First identify the grain and the selected control object. Then distinguish > how that object was determined from what its definition makes it do. This reference distinguishes three environments: - **SAP S/4HANA on-premise or private edition**, where SAP GUI transactions, IMG activities, Pricing Analysis, and authorized table inspection are common diagnostic tools. - **SAP S/4HANA Cloud Public Edition**, where Fiori applications and configuration activities provide the supported paths and may add features such as flexible item-category determination. - **Clean-core extension development**, where released CDS entities, business objects, and APIs are contracts; classic tables and Customizing views are diagnostic landmarks rather than integration interfaces. Primary SAP sources: - [SAP Help — How Sales Documents Are Controlled](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/7b24a64d9d0941bda1afa753263d9e39/c264b65334e6b54ce10000000a174cb4.html) - [SAP Learning — Configuring a Sales Document Type](https://learning.sap.com/courses/fundamental-customizing-in-sap-s-4hana-sales/configuring-a-sales-document-type) - [SAP Learning — Configuring an Item Category](https://learning.sap.com/courses/fundamental-customizing-in-sap-s-4hana-sales/configuring-an-item-category-1) - [SAP Help — Determining Sales Document Item Categories](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/7b24a64d9d0941bda1afa753263d9e39/dc89c95360267214e10000000a174cb4.html) - [SAP Learning — Assigning Schedule Line Categories](https://learning.sap.com/courses/fundamental-customizing-in-sap-s-4hana-sales/assigning-schedule-line-categories) - [SAP Learning — Introducing the Condition Technique](https://learning.sap.com/courses/configuring-pricing-in-sap-s-4hana-sales/introducing-the-condition-technique_dce0f313-dee6-470e-8851-3f1773cb5d45) - [SAP Help — Pricing Information and Analysis](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/4dd8cb7b1c484b4b93af84d00f60fdb8/918dc95360267214e10000000a174cb4.html) - [SAP Help — Sales Order Item Pricing Element](https://help.sap.com/docs/SAP_S4HANA_CLOUD/03c04db2a7434731b7fe21dca77440da/abf59161a5734e0393d30c5fa2f41053.html) --- ## 1. Sales Document Runtime Architecture ### 1.1 The control chain ```text Header Sales document type │ supplies whole-transaction context ▼ Item Item category │ supplies product/service-line behavior ▼ Schedule line Schedule-line category │ supplies dated-quantity fulfillment behavior ▼ Subsequent processing delivery, requirements, procurement, goods movement, billing ``` The three controls cooperate, but they answer different questions:40:Te148, # SAP SD Fulfillment, Posting, and Integration — Technical Reference This document explains the technical execution path from a delivery-relevant Sales Order through Outbound Delivery, picking, packing, Post Goods Issue (PGI), billing, accounting, payment clearing, and external integration. It connects business-document boundaries to configuration, persistence, application logs, interfaces, reversals, diagnostic evidence, and clean-core extension design. The central technical principle is: > A planned or created document proves intent at its own boundary. Only the > corresponding posting document and consistent process state prove that a > physical or financial event occurred. This reference distinguishes three environments: - **SAP S/4HANA on-premise or private edition**, where SAP GUI transactions, IMG activities, and authorized persistence inspection are common diagnostic tools. - **SAP S/4HANA Cloud Public Edition**, where Fiori applications, configuration activities, released APIs, and communication arrangements are the normal operational contracts. - **Clean-core extension development**, where internal SD, MM, and FI tables are diagnostic landmarks—not write interfaces or lifecycle-stable APIs. Primary SAP sources: - [SAP Learning — Processing Outbound Deliveries](https://learning.sap.com/courses/configuring-delivery-processing-in-sap-s-4hana-sales/processing-outbound-deliveries) - [SAP Learning — Posting a Goods Issue](https://learning.sap.com/courses/configuring-delivery-processing-in-sap-s-4hana-sales/posting-a-goods-issue) - [SAP Help — Shipping Points](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/c7894a248ca14f74aca67f97528e5ad7/5d1bbf53d25ab64ce10000000a174cb4.html) - [SAP Help — Goods Issue](https://help.sap.com/docs/SAP_S4HANA_CLOUD/aff0b3f5f46c42a2b2c0fabfc233bab2/64f81a71edf5490ab522a829be075827.html) - [SAP Help — Outbound Delivery API Operations](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/2f36056ae9a044bba55bcbad204b7bc5/a4c5d84ecef2494985883829a24e393c.html) - [SAP Learning — Billing and Integration to SAP S/4HANA Finance](https://learning.sap.com/courses/exploring-sap-s-4hana-sales-essentials/executing-the-billing-process-and-the-integration-to-sap-s-4hana-finance_e2dd5db3-73c3-4cda-8ad5-1e7f39f04fba) - [SAP Help — Canceling Billing Documents](https://help.sap.com/docs/SAP_S4HANA_CLOUD/a376cd9ea00d476b96f18dea1247e6a5/2a70b6535fe6b74ce10000000a174cb4.html) - [SAP Help — IDoc Inbound Processing](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/7b24a64d9d0941bda1afa753263d9e39/4b4c8e091c300a93e10000000a421937.html) --- ## 1. Execution Boundaries ### 1.1 Baseline sell-from-stock flow ```text Sales Order accepted demand and commercial intent │ ▼ Outbound Delivery shipping execution object │ ├── picking ├── packing └── warehouse execution │ ▼ Post Goods Issue inventory and relevant value posting │ ▼ Billing Document customer invoice and FI transfer │ ▼ Incoming Payment and Clearing cash receipt and receivable settlement ``` This is a baseline, not a universal sequence. Third-party sales, services, intercompany processing, consignment, returns, pro forma billing, EWM-managed warehouses, and other scenarios use different branches. ### 1.2 Each boundary proves one fact | Evidence | Fact established | Fact not established | | ---------------------------- | ------------------------------------------ | ---------------------------------------- | | Sales Order exists | Demand and processing intent were recorded | Goods were shipped | | Outbound Delivery exists | Shipping execution document was created | Picking or PGI completed | | Picking complete | Required warehouse staging was recorded | Inventory was posted out | | PGI material document exists | Goods issue posting occurred | Customer was billed or paid | | Billing Document exists | Billing transaction was created | FI transfer and payment always succeeded | | FI customer open item exists | Receivable was posted | Incoming cash was matched and cleared | | Payment document exists | Cash-related posting occurred | The intended invoice was fully cleared | The technical investigation must move to the evidence owned by the failing boundary rather than infer later events from an earlier document. ### 1.3 State transition versus data creation ```text Create Delivery → new delivery aggregate Pick → update warehouse/delivery execution state Pack → create or update handling-unit assignment Post GI → create posting documents and update delivery state Create Billing → new billing aggregate and possible FI posting Receive Payment → new FI posting and clearing relationship ``` These operations require business logic. Directly inserting or updating a row cannot reproduce their cross-component effects. --- ## 2. From Sales Order to Delivery Due Processing ### 2.1 Delivery eligibility A Sales Order item becomes relevant to delivery processing only when its transactional and configured conditions permit it. Typical evidence includes: - item and schedule-line delivery relevance; - confirmed quantity remaining for delivery; - material and Plant data; - Shipping Point and route/shipping context; - relevant delivery date within the due-list horizon; - no blocking or rejection state preventing delivery; - sufficient completion of required document data; - no successor delivery already consuming the due quantity. ```text Configured relevance + confirmed open quantity + due date in selection horizon + valid organizational/shipping data + no effective block or completion = candidate for delivery due processing ``` The due list is a selection and work-processing mechanism. Absence from it does not by itself prove a program defect. ### 2.2 Quantity separation | Measure | Grain | Meaning | | ------------------ | ---------------------------- | ------------------------------------------- | | Ordered quantity | Sales Order item | Total customer demand | | Confirmed quantity | Schedule line/date | Quantity currently committed | | Delivery quantity | Delivery item | Quantity placed into one execution document | | Picked quantity | Delivery/warehouse execution | Quantity staged for dispatch | | GI quantity | Material-document item | Quantity physically posted out | | Billed quantity | Billing item | Quantity used by billing basis | “Open quantity” must be qualified: ```text Open order quantity Open confirmed quantity for delivery Unpicked delivery quantity Unposted GI quantity Unbilled quantity ``` Each measure has a different source, relevance rule, and unit context. ### 2.3 Classic navigation | Operation | Common classic landmark | | ------------------------------------- | ----------------------- | | Create delivery with order reference | `VL01N` | | Process delivery due list | `VL10*` family | | Outbound Delivery Monitor | `VL06O` | | Display Sales Order and document flow | `VA03` | Public Cloud uses role-specific Fiori apps and background processing rather than assuming the same transaction set. --- ## 3. Delivery Creation, Combination, and Split ### 3.1 Delivery creation Delivery creation copies and determines data into a new business document. It does not turn a Sales Order item into a delivery row. ```text Due predecessor item/schedule quantity + copy-control requirements + delivery type and item behavior + combination/split criteria + runtime determinations = Outbound Delivery header and items ``` The new delivery has its own identity, ownership, authorization, status, change restrictions, and reversal path. ### 3.2 Many predecessors can combine Compatible Sales Order items can be grouped into one delivery when all combination-relevant values permit it. ```text Order A / Item 10 ─┐ ├──> Delivery 800001 Order B / Item 20 ─┘ ``` Typical commonality requirements include the same Shipping Point and Ship-to Party, plus compatible route, delivery timing, and other delivery-header data. The exact split-relevant set depends on process and release. ### 3.3 One predecessor can split ```text Sales Order Item 10 ├── Delivery 800001 for 6 EA └── Delivery 800025 for 4 EA ``` Split causes can include: - different Shipping Points; - different Ship-to Parties or addresses; - incompatible routes or delivery dates; - different delivery types or header-relevant data; - capacity, warehouse, or business-process decisions; - custom split logic or enhancements. The correct diagnostic action is to compare the actual split-relevant values and application split analysis—not guess from document count. ### 3.4 Copy control Copy control governs whether and how predecessor data is transferred to a successor. It can include: - permitted source/target document combinations; - header- and item-level copy requirements; - data-transfer routines; - quantity and completion behavior; - document-flow updates. Common classic landmarks include: | Flow | Classic transaction | | ------------------------------- | ------------------- | | Sales document → Sales document | `VTAA` | | Sales document → Delivery | `VTLA` | | Sales document → Billing | `VTFA` | | Delivery → Billing | `VTFL` | | Billing → Billing | `VTFF` | Copy control is not a database-copy command. It is application configuration executed during successor creation. --- ## 4. Outbound Delivery Data Model ### 4.1 Header and item grain ```text LIKP — Outbound Delivery header key: VBELN │ └── LIPS — Outbound Delivery item key: VBELN + POSNR ``` Representative fields include: | Meaning | Classic clue | Grain | | ---------------------- | ---------------------------------- | --------------------------------------------------- | | Delivery type | `LIKP-LFART` | Header | | Shipping Point | `LIKP-VSTEL` | Header result; derived from compatible item context | | Planned GI date | `LIKP-WADAT` | Header expectation | | Actual GI date | `LIKP-WADAT_IST` | Header posting result clue | | Delivery item category | `LIPS-PSTYV` | Item | | Delivery quantity | `LIPS-LFIMG` with unit | Item | | Picked quantity | `LIPS-PIKMG` with its unit context | Item | | Movement type proposal | `LIPS-BWART` | Item posting instruction | | Immediate predecessor | `LIPS-VGBEL + LIPS-VGPOS` | Item source reference | `LF` is a common standard delivery type and `601` a common sell-from-stock goods issue movement type. Both are configurable examples, not universal constants. ### 4.2 Direct predecessor versus document flow ```text LIPS-VGBEL / VGPOS → immediate source document/item copied into this delivery item VBFA → broader predecessor/successor graph across SD document categories ``` The direct reference and document-flow graph have related but different purposes. A robust trace can use both. ### 4.3 Delivery control configuration Common classic landmarks include: | Purpose | Transaction | Configuration clue | | ----------------------------------- | ----------- | ------------------------------------------ | | Define delivery type | `OVLK` | delivery-header behavior | | Define delivery item category | `OVLP` | delivery-item behavior | | Shipping Point determination | `OVL2` | Plant + shipping condition + loading group | | Sales order → delivery copy control | `VTLA` | source/target copying behavior | The selected delivery type and item category are transaction data. The maintenance transactions define reusable behavior. --- ## 5. Picking, Packing, and Warehouse Execution ### 5.1 Different execution facts | Activity | Business meaning | Technical result | | ---------------- | --------------------------------------------------------- | ---------------------------------------------------------------------- | | Picking | Remove and stage required stock from a warehouse location | Picking quantity/status or warehouse-task confirmation | | Packing | Assign products to physical shipping units | Handling Units and packaging relationships | | Loading/shipping | Prepare transport departure | Delivery/shipment execution state according to process | | PGI | Record goods departure in Inventory Management | Material document, status, date, and accounting effects where relevant | Packing is not required in every process. Picking can be controlled in the delivery directly, through Lean Warehouse Management, classic Warehouse Management, Stock Room Management, or Extended Warehouse Management. ### 5.2 Warehouse architecture changes the route ```text Simple delivery execution Delivery → record picking → PGI EWM-managed execution LE delivery → EWM delivery objects → warehouse tasks → pick/pack/stage → EWM goods issue → confirmation to LE delivery and ERP postings ``` The exact document chain differs, but the boundary remains the same: warehouse task completion and picking status are not themselves Inventory Management goods-issue posting. ### 5.3 Handling Units A Handling Unit combines packaging material with packed goods. Classic persistence landmarks include `VEKP` for HU header and `VEPO` for HU items, but their use depends on scenario and architecture. ```text Delivery item quantity └── packed into Handling Unit ├── packaging material ├── contained product quantity └── identification/status ``` Use supported HU and warehouse APIs for integration. Direct table updates cannot safely maintain nested packing, status, serial/batch, and warehouse relationships. ### 5.4 Picking status versus goods-movement status | Status family | Header clue | Item clue | Meaning | | -------------- | ------------ | ------------ | ----------------------- | | Picking | `LIKP-KOSTK` | `LIPS-KOSTA` | Picking progress | | Goods movement | `LIKP-WBSTK` | `LIPS-WBSTA` | Goods-movement progress | ```text Picking complete + goods movement not started ``` is a valid intermediate state. It proves warehouse staging but not stock posting. --- ## 6. Post Goods Issue ### 6.1 PGI as the decisive posting boundary For a common delivery-related sell-from-stock process, PGI records that the goods left the company and produces the Inventory Management posting. ```text Before PGI Delivery exists Quantity can be picked and packed Movement type is only an instruction After successful PGI Material document exists Delivery goods-movement state is updated Actual GI date is recorded Inventory quantity is reduced Relevant inventory-value/accounting effects exist Delivery-related billing can normally continue ``` PGI must be executed through the application operation. Writing the actual GI date or goods-movement status would not create the material and accounting documents. ### 6.2 Typical accounting effect For a valuated stock sale, a simplified posting is: ```text Debit Cost of Goods Sold Credit Inventory ``` Actual accounts and controlling/profitability effects depend on valuation, movement type, account determination, account assignment, ledger design, and process variant. The example is conceptual, not a universal journal template. PGI accounting and billing accounting are separate: ```text PGI posting inventory and cost-side effect Billing posting customer receivable, revenue, and tax-side effect ``` ### 6.3 Proof hierarchy | Observation | Evidential strength | | ------------------------------------------------- | ------------------------------------------------ | | Delivery exists | proves delivery creation only | | Picked quantity complete | proves picking state only | | Movement type `601` present | proves proposed/configured posting behavior only | | Actual GI date and completed goods-movement state | strong delivery-side evidence | | Related material document and line item | decisive posting evidence | | Consistent inventory and accounting effects | corroborating cross-component evidence | A successful UI message or HTTP status should be correlated with the resulting business-document identity and state before downstream work is triggered. ### 6.4 Material-document persistence in S/4HANA ```text SAP ERP model MKPF material-document header MSEG material-document item SAP S/4HANA persistence MATDOC central material-document line-item persistence compatibility views preserve selected legacy read semantics ``` A common material-document identity uses document number, year, and item context. Use released material-document CDS views or APIs for clean-core access rather than binding new code to `MATDOC` layout. ### 6.5 PGI API operation In supported releases, `API_OUTBOUND_DELIVERY_SRV` exposes a `PostGoodsIssue` operation. SAP documents that the Delivery Document is mandatory and the current ETag is required. ```text GET delivery/current ETag → validate local intent → POST PostGoodsIssue with If-Match → inspect HTTP/business result → reread delivery and posting evidence ``` The ETag prevents a caller from posting against a stale delivery version. It does not replace business validation, authorization, idempotency, or posting evidence. --- ## 7. Reversing Goods Issue ### 7.1 Reversal preserves history If PGI data is wrong, the normal correction is: ```text Reverse PGI → create reversing material/accounting effects → restore delivery to an editable process state as permitted → correct delivery data → post PGI again ``` The classic landmark is `VL09`. Reversal does not delete the original posting or rewrite history. It creates compensating evidence and updates process state. ### 7.2 Reversal dependency checks Later documents can restrict reversal. Before reversing PGI, inspect: - subsequent Billing Documents; - warehouse/EWM state; - period and posting-date controls; - batch, serial number, and stock availability implications; - authorization and business-process restrictions. If billing already exists, the required sequence commonly starts by canceling the downstream billing result before reversing PGI. The precise sequence is process- and configuration-dependent. ### 7.3 Reversal is not negative direct SQL ```text Original posting + reversal posting = auditable correction chain Direct overwrite/delete = lost lineage and inconsistency ``` This pattern repeats in billing and FI clearing. --- ## 8. Billing Eligibility and Creation ### 8.1 Order-related and delivery-related billing ```text Order-related billing Sales Order item → Billing Document Delivery-related billing Outbound Delivery item → Billing Document ``` The Item Category, billing relevance, copy control, process status, quantity, and billing block determine how an item participates. Physical products are commonly delivery-related; services and other processes can be order-related. ### 8.2 Billing due processing Typical eligibility evidence includes: - billing relevance of the source item; - billable quantity or value; - required predecessor processing state; - billing date in the selection horizon; - no effective billing block; - complete required billing data; - no existing successor already consuming the billable basis. Classic landmarks: | Operation | Transaction | | --------------------------------- | ----------- | | Create Billing Document | `VF01` | | Process billing due list | `VF04` | | Background billing | `VF06` | | Display Billing Document | `VF03` | | Display blocked billing documents | `VFX3` | ### 8.3 Billing combination and split Compatible source items can combine into one Billing Document. Differences in billing-header criteria can cause a split, for example payer, billing date, payment terms, destination country, Incoterms, or other configured data. ```text Several deliveries ──compatible billing data──> one invoice One delivery ──incompatible billing data──────> several invoices ``` Use Billing Split Analysis and compare actual header-relevant values. Do not assume one delivery must always create one invoice. ### 8.4 Billing copy control and pricing `VTFL` commonly maintains Delivery-to-Billing copy control, while `VTFA` maintains Sales-Document-to-Billing copy control. Copy control can govern: - source and target document combinations; - copying requirements and data-transfer routines; - quantity/value basis; - pricing type and repricing behavior; - update of document flow. A Billing Document may copy or redetermine pricing according to the pricing type. Its result therefore need not be numerically identical to the Sales Order pricing result. --- ## 9. Billing Data Model and Cancellation ### 9.1 Persistence grain ```text VBRK — Billing Document header key: VBELN │ └── VBRP — Billing Document item key: VBELN + POSNR ``` Related landmarks include: | Object | Purpose | | ----------------- | ----------------------------------------------------- | | `VBPA` | Billing-document partner rows among other SD partners | | `VBFA` | Predecessor/successor document flow | | `PRCD_ELEMENTS` | S/4HANA document pricing-result rows | | `BKPF` / `ACDOCA` | Accounting header/context and Universal Journal lines | The repeated field `VBELN` is scoped by table and document category. A Sales Order number, delivery number, and billing number are different identities even where field names are shared. ### 9.2 Billing type and account determination Common classic configuration landmarks include: | Purpose | Transaction | | ------------------------------------- | ----------- | | Define Billing Types | `VOFA` | | Delivery → Billing copy control | `VTFL` | | Sales document → Billing copy control | `VTFA` | | Revenue account determination | `VKOA` | Revenue account determination commonly combines organizational and account- assignment context such as: ```text Chart of accounts + Sales Organization + customer account-assignment group + material account-assignment group + account key from pricing procedure = G/L account ``` The actual access combination and result are configuration-dependent. Typical master-data clues include `KNVV-KTGRD` for customer account-assignment group and `MVKE-KTGRM` for material account-assignment group. ### 9.3 Typical billing accounting effect For a normal customer invoice, a simplified view is: ```text Debit Customer receivable Credit Revenue Credit Output tax, where applicable ``` Saving a standard billing document commonly transfers data to Financial Accounting automatically. Exceptions include pro forma documents, posting blocks, account-determination failures, closed periods, and other process controls. Billing-document existence alone therefore does not prove successful FI transfer. ### 9.4 Billing cancellation The classic transaction is `VF11`. Cancellation creates a cancellation Billing Document; it does not delete the original invoice. ```text Original Billing Document → Cancellation Billing Document → offsetting FI entry when accounting transfer applies → predecessor can become open for correct rebilling ``` SAP's Billing Document API also exposes a cancellation action in supported releases and requires ETag handling. A cancellation response must be correlated with the cancellation document and accounting status. --- ## 10. Financial Accounting and Incoming Payment ### 10.1 Billing creates a receivable, not payment ```text Billing posting → customer open item / receivable Incoming payment → cash or bank-clearing posting → matching and clearing against open item ``` The Sales Order does not become “paid” by receiving a field update from FI. Payment and clearing are Financial Accounting transactions with their own document identities and states. ### 10.2 Common payment outcomes | Outcome | Meaning | | -------------------- | ------------------------------------------------------------------------------ | | Full clearing | Payment settles the selected receivable completely | | Partial payment | Payment is posted while the original invoice remains open according to process | | Residual item | Original item is cleared and a new residual open item is created | | On-account payment | Payment is posted without immediate invoice matching | | Difference/write-off | Configured tolerance or reason handling resolves a difference | One payment can clear multiple invoices, and one invoice can be settled by multiple payment-related postings. The relationship is not inherently one-to- one. ### 10.3 Classic navigation | Purpose | Common classic landmark | | ------------------------------------ | ------------------------------------------------------ | | Display accounting document | `FB03` | | Display customer line items | `FBL5N` | | Post incoming payment manually | `F-28` | | Electronic bank statement processing | release/process-specific applications and transactions | ### 10.4 Clearing evidence ```text Billing Document → accounting document reference → customer receivable line → clearing document/date or remaining open state → payment/bank posting ``` Payment status in an SD-oriented report should be derived from an authorized, documented FI source or released API/CDS model. A custom Boolean copied into an order can become stale and cannot represent partial or residual settlement. --- ## 11. Document Flow and Status Architecture ### 11.1 The process is a graph ```text Sales Order Item 10 ├── Delivery A → Material Document A → Invoice A └── Delivery B → Material Document B → Invoice B Invoice A ├── Payment 1 └── Cancellation or credit branch, when applicable ``` Several Sales Orders can also combine into one delivery or invoice. Order-to- Cash cannot be represented reliably as one foreign-key chain with one status. ### 11.2 `VBFA` as the SD relationship landmark Representative fields include: | Field | Meaning | | ------------------------ | ---------------------------------------- | | `VBELV` | Preceding SD document | | `POSNV` | Preceding item | | `VBELN` | Subsequent SD document | | `POSNN` | Subsequent item | | document-category fields | Classify predecessor and successor types | | `STUFE` | Document-flow level context | S/4HANA extended document-category semantics and simplified `VBFA`. New code should not hard-code old one-character assumptions without checking the target release. ### 11.3 Status is compressed evidence Overall statuses answer whether processing is open, partial, complete, or not relevant according to application rules. They do not explain the cause. ```text Overall status → item statuses → source and successor quantities → document-flow edges → posting documents ``` S/4HANA moved many SD status fields from separate `VBUK`/`VBUP` persistence into relevant document header/item tables. Compatibility artifacts can still surface legacy names. Released CDS/API status fields are safer extension contracts. ### 11.4 Reversed documents remain evidence Reversal and cancellation append corrective documents and status transitions. Reports must decide deliberately whether to show: - gross posted quantity/value; - reversing quantity/value; - net current effect; - original and reversal identities; - current process eligibility. Deleting reversed rows from a dataset can hide audit history; counting both as positive can overstate activity. --- ## 12. Cross-Component Persistence Map | Boundary | Header/primary landmark | Item/detail landmark | Native grain | | ---------------------------- | ----------------------- | -------------------------------------- | --------------------------------------- | | Sales Order | `VBAK` | `VBAP`, `VBEP` | order; item; schedule line | | Outbound Delivery | `LIKP` | `LIPS` | delivery; delivery item | | SD document flow | — | `VBFA` | predecessor/successor item relationship | | Handling Unit | `VEKP` | `VEPO` | HU; packed item | | Material document in S/4HANA | — | `MATDOC` | material-document line | | Billing Document | `VBRK` | `VBRP` | billing header; billing item | | Pricing result | — | `PRCD_ELEMENTS` | pricing document/item/step/counter | | Accounting | `BKPF` context | `ACDOCA`; classic views such as `BSEG` | journal-entry line | | IDoc | `EDIDC` | `EDID4`, `EDIDS` | message control; segment; status event | These tables do not form one safe flat join. Document categories, fiscal year, Company Code, item numbers, units, currencies, and one-to-many relationships must be respected. ### 12.1 Grain-safe reporting ```text Delivery item → may have several document-flow edges → may have several material-document lines → may contribute to several billing items Naive join → row multiplication → repeated quantities and values ``` Safe design: 1. Choose one output grain. 2. Aggregate each child source to that grain. 3. Preserve units, currencies, reversal signs, and relevance rules. 4. Join summarized results. 5. Reconcile against application totals. --- ## 13. Classic Transaction and Configuration Map These are on-premise/private-edition landmarks. Availability depends on release, role, activated scope, and warehouse architecture. ### 13.1 Operational transactions | Area | Common transaction | | ------------------------------ | --------------------------- | | Sales Order display | `VA03` | | Delivery create/change/display | `VL01N` / `VL02N` / `VL03N` | | Delivery due processing | `VL10*` | | Outbound Delivery Monitor | `VL06O` | | Reverse goods issue | `VL09` | | Billing create/change/display | `VF01` / `VF02` / `VF03` | | Billing due list | `VF04` | | Cancel Billing Document | `VF11` | | Display accounting document | `FB03` | | Display customer line items | `FBL5N` | | Post incoming payment | `F-28` | ### 13.2 Configuration transactions | Area | Common transaction | Responsibility | | ------------------------------- | ------------------ | ------------------------------------------------------------------ | | Shipping Point determination | `OVL2` | Plant + shipping condition + loading group result | | Delivery type | `OVLK` | Header-level delivery behavior | | Delivery item category | `OVLP` | Item-level delivery behavior | | Sales → Delivery copy control | `VTLA` | Eligibility and data transfer | | Delivery → Billing copy control | `VTFL` | Billing basis, routines, pricing type | | Sales → Billing copy control | `VTFA` | Order-related billing transfer | | Billing type | `VOFA` | Billing-header behavior and cancellation relation | | Revenue account determination | `VKOA` | Pricing/account-assignment context to G/L account | | Movement type control | `OMJJ` | Inventory movement behavior; cross-process impact requires caution | Always begin from the IMG activity and business requirement. Transaction codes are navigation shortcuts, not a substitute for configuration design and transport governance. --- ## 14. Missing Delivery Diagnostic Flow ### 14.1 Evidence sequence ```text Exact Sales Order item → item/schedule delivery relevance → confirmed quantity and requested/confirmed date → open quantity after existing successors → Plant, Shipping Point, route, and due-list selection → rejection, completion, block, and incompletion → copy-control requirement → application log and authorization → enhancements only after standard evidence ``` ### 14.2 Common cause classes | Cause class | Evidence | | -------------------------- | --------------------------------------------- | | Not due | relevant date outside selection horizon | | No open confirmed quantity | schedule-line and successor quantities | | Not delivery relevant | Item/Schedule-Line Category control | | Blocked or rejected | document/item/schedule state | | Missing shipping data | Plant, Shipping Point, route, partner/address | | Already processed | document flow and existing delivery quantity | | Copy requirement failed | copy-control routine and runtime data | | Authorization/job issue | application log, job log, authorization trace | Do not change due-list configuration merely because one item is absent. First prove the exact failing eligibility condition. --- ## 15. Unexpected Delivery Split Diagnostic Flow ```text 1. Identify all resulting delivery numbers and source items 2. Confirm quantities and source references 3. Compare Shipping Point and Ship-to Party/address 4. Compare route, delivery date, delivery type, and header-relevant values 5. Use available split analysis or application log 6. Verify copy-control and combination rules 7. Inspect warehouse/capacity process decisions 8. Investigate custom split logic only after the differing field is known ``` The strongest finding names the exact value that prevented combination: ```text Source Item A: Shipping Point 1000 Source Item B: Shipping Point 2000 Result: separate delivery headers required ``` “SAP decided to split” is not a technical root cause. --- ## 16. PGI Failure Diagnostic Flow ```text Delivery and exact item → picking/warehouse completion → delivery quantity, unit, batch, serial, stock type → Plant, storage location, movement type → posting date and open period → stock and negative-stock rules → account determination and valuation → delivery and goods-movement status → warehouse/EWM queues and application logs → authorization trace → custom code last ``` ### 16.1 Failure families | Failure family | Typical evidence | | --------------------- | -------------------------------------------------------------------- | | Warehouse incomplete | open warehouse tasks or picking status | | Quantity mismatch | delivery, picking, base-unit, or batch quantity conflict | | Master-data issue | missing valuation, serial/batch, storage, or account-assignment data | | Posting-period issue | FI/MM period or posting date message | | Stock issue | insufficient relevant stock or stock-type mismatch | | Account determination | missing G/L account or valuation combination | | Lock/concurrency | enqueue or stale ETag conflict | | Integration | queue, API, IDoc, tRFC, or middleware error | The exact message class, number, variables, application log, and document state are evidence. A paraphrase such as “PGI failed” is only the symptom. --- ## 17. Billing and Payment Diagnostic Flows ### 17.1 Source absent from billing due list ```text Source document/item → billing relevance and billing basis → required predecessor state → billable quantity/value → billing date and due-list horizon → billing block/incompletion → existing successor Billing Documents → VTFA or VTFL copy requirement → application log and authorization ``` ### 17.2 Billing Document exists but FI document is missing ```text Billing Document and posting status → pro forma versus accounting-relevant billing type → account-determination result in VKOA → customer and material account-assignment groups → posting date and FI period → tax and G/L account configuration → accounting interface/application log → correction and authorized release/reprocessing path ``` ### 17.3 Billing exists but receivable remains open ```text Billing → FI accounting document → customer line item → payment document → clearing document/date → partial/residual/on-account outcome → payer, currency, amount, reference, and tolerance ``` The open item may be correct because payment has not arrived, was posted on account, was only partial, or matched a different receivable. --- ## 18. Integration Contract Selection ### 18.1 Contract comparison | Contract | Style | Appropriate use | Main technical concerns | | -------------- | ---------------------------------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------- | | BAPI | Synchronous business operation, commonly RFC-enabled | Classic SAP-to-SAP or application call in supported systems | return messages, LUW ownership, commit, release status | | IDoc | Persisted asynchronous business message | Decoupled ALE/EDI and middleware exchange | statuses, retries, duplicates, partner profile, monitoring | | OData/REST API | Synchronous HTTP service contract | Cloud-ready transactional/read integration | authentication, CSRF, ETag, batching, version, business errors | | SOAP API | Contract-first service | Enterprise integrations where delivered | reliable messaging, faults, version, communication arrangement | | Business event | Asynchronous notification | Inform consumers that a business fact occurred | delivery guarantee, duplicate events, state retrieval, ordering | | CDS view | Semantic read model for supported capability | Read, analytics, extraction where released | authorization, extraction delta, grain, not a write API | ### 18.2 BAPI versus RFC RFC is the remote-call mechanism. A BAPI is a business-oriented method/API contract that is often implemented through an RFC-enabled function module. ```text RFC → how an ABAP callable unit can be invoked remotely BAPI → released/stable business operation in the classic Business Object model ``` A common classic Sales Order creation BAPI is `BAPI_SALESORDER_CREATEFROMDAT2`. Its availability does not automatically make it the preferred clean-core interface for every S/4HANA edition. Typical call responsibility: ```text Call BAPI → inspect every RETURN/BAPIRET2 message → treat error/abort messages as failure → call BAPI_TRANSACTION_COMMIT with WAIT on success → call BAPI_TRANSACTION_ROLLBACK on failure when appropriate → store returned business-document identity ``` Do not commit inside a reusable helper without an explicit transaction- ownership decision. The caller may need several operations in one SAP LUW. ### 18.3 API concurrency and evidence Released delivery and billing operations can require ETags. The correct flow is: ```text Read current representation and ETag → construct operation from current state → send If-Match and CSRF token as required → interpret HTTP and business error payload → persist correlation key → reread or consume event to confirm final state ``` HTTP `2xx` proves acceptance/success according to that API operation; it does not by itself replace the business evidence required by the application. Some operations return an empty body, making the correlation and reread especially important. --- ## 19. IDoc Architecture ### 19.1 Message Type, Basic Type, and extension ```text Message Type business meaning, such as order or invoice Basic Type hierarchical technical segment structure Extension customer-specific additional segments attached to a Basic Type ``` Common SD-oriented Message Type examples include: | Business exchange | Common Message Type example | | ----------------------------- | --------------------------- | | Order | `ORDERS` | | Order response | `ORDRSP` | | Advance shipping notification | `DESADV` | | Invoice | `INVOIC` | Basic Type versions such as `ORDERS05`, `DELVRY...`, or `INVOIC02` depend on the scenario, partner, release, and mapping contract. Message Type and Basic Type must not be used as synonyms. ### 19.2 Runtime records | Record | Classic table | Purpose | | -------------- | ------------- | --------------------------------------------------------------------- | | Control record | `EDIDC` | sender, receiver, Message Type, Basic Type, direction, current status | | Data records | `EDID4` | ordered segment payload instances | | Status records | `EDIDS` | append-only processing history and messages | ```text One EDIDC control record ├── many EDID4 segment records └── many EDIDS status-history records ``` An IDoc is an integration document, not the Sales Order, delivery, or invoice it may create. The application document has a separate identity. ### 19.3 Outbound flow ```text Application/output/change event → build IDoc control and data records → check WE20 outbound partner profile → resolve WE21 port/transport → dispatch through tRFC/qRFC/file/middleware path → record status history → receiver processes business message ``` ### 19.4 Inbound flow ```text Sender/middleware → IDoc received and persisted → partner/message profile recognized → inbound process code resolves processing logic → application function executes → business document created or application error recorded → IDoc status appended ``` SAP explicitly separates receipt/persistence of an inbound IDoc from later application processing. Successful technical receipt is therefore not proof that the Sales Order or other application document was posted. ### 19.5 Configuration and monitoring landmarks | Transaction | Purpose | | --------------- | --------------------------------------------------------- | | `WE20` | Partner profiles and inbound/outbound parameters | | `WE21` | Ports and technical transport destination | | `WE30` | IDoc Basic Type structure | | `WE31` | Segment type definition | | `WE42` | Inbound process code | | `WE57` | Function Module, Message Type, and Basic Type assignment | | `WE02` / `WE05` | Display and search IDocs/status history | | `BD87` | Controlled reprocessing of eligible IDocs | | `WE19` | Test tool; use only in a safe non-production test context | | `SM58` | tRFC backlog/error monitoring | | `SMQ1` / `SMQ2` | outbound/inbound qRFC queue monitoring | | `SLG1` | application-log analysis where the process writes logs | Common status examples include: | Status | Common meaning | | ------ | ------------------------------------------------ | | `03` | Outbound data passed to port | | `02` | Outbound error passing data to port | | `64` | Inbound IDoc ready for application processing | | `53` | Inbound application document posted successfully | | `51` | Inbound application posting error | Status meanings should be confirmed in the target system and scenario. Status `53` is strong IDoc-side evidence of successful application processing, but the created application-document identity should still be captured. ### 19.6 Safe reprocessing ```text Failed IDoc → inspect current and previous statuses → read exact application message → correct root cause in master data/configuration/application → assess duplicate/idempotency risk → reprocess through supported tool → confirm new status and business document ``` Never edit `EDIDC`, `EDID4`, or `EDIDS` directly to make a message appear successful. Repeated processing can create duplicate business documents unless the receiving logic and business keys are idempotent. --- ## 20. Integration Observability and Failure Isolation ### 20.1 Four failure domains ```text Caller/application request construction, mapping, credentials │ Transport/middleware HTTP, RFC, queue, routing, transformation │ SAP interface layer service activation, partner profile, deserialization, authorization │ SAP business application master data, configuration, validation, lock, posting, account determination ``` The same user symptom can originate in any domain. Record correlation IDs and business keys across all layers. ### 20.2 Minimum integration evidence ```text Source business key Interface contract and version Correlation/message/IDoc identifier Request timestamp and sender/receiver Sanitized request or mapped business fields Transport response/status SAP business messages Created or changed document identity Final application state/posting evidence Retry/reversal history ``` ### 20.3 Technical success versus business success | Observation | Interpretation | | ------------------------------------------ | ---------------------------------------------------------- | | HTTP connection succeeded | transport reached endpoint | | HTTP `2xx` returned | operation succeeded/was accepted according to API contract | | IDoc received | integration document persisted | | IDoc status `53` | inbound application processing reported success | | Business document number returned | application object identity exists | | Posting document and final state confirmed | decisive business boundary completed | An integration monitor should expose both technical status and business result. --- ## 21. RAP Portfolio and Standard SD Boundary ### 21.1 Aggregate ownership ```text Custom SalesOrderRequest BO ├── Items ├── Schedules └── OrderPartners Standard S/4HANA Sales Order ── independent aggregate Standard Outbound Delivery ── independent aggregate Material Document, Billing Document, FI documents ── separate postings/aggregates ``` Do not place Delivery, Billing, and Payment beneath the custom request as RAP composition children. They have separate identities, authorization, posting, retention, and reversal lifecycles. ### 21.2 Honest integration state model ```text Draft → Submitted → HandoffPending → HandoffSucceeded → ExternalOrderCreated → FulfillmentInProgress → Fulfilled / Failed / Reversed ``` The exact states should be based on events the custom application can prove. If the portfolio does not call a real released PGI operation, label the action as simulated fulfillment or handoff—not `PostGoodsIssue`. ### 21.3 Adapter boundary ```text RAP action SubmitToS4 → outbound port/interface → adapter maps custom request to released API contract → adapter records correlation and external identity → callback/event/polling updates integration projection ``` The domain logic should depend on a narrow port such as “submit order request” rather than on generated OData field names, BAPI structures, or IDoc segments. ### 21.4 Transaction boundary The local RAP save and remote S/4HANA transaction cannot usually be one atomic database transaction. ```text Local commit succeeds + remote call fails → recoverable integration state and retry required Remote creation succeeds + response is lost → idempotent lookup/correlation required before retry ``` Use an outbox/event or controlled orchestration approach when reliability matters. Never solve distributed failure by holding a database lock around a long remote call. --- ## 22. Clean-Core and Security Rules ### 22.1 Prohibited write shortcuts Do not directly update: ```text LIKP / LIPS VBFA MATDOC VBRK / VBRP PRCD_ELEMENTS BKPF / BSEG / ACDOCA EDIDC / EDID4 / EDIDS ``` These objects participate in application invariants, postings, status, document flow, output, change tracking, and integration. ### 22.2 Released contract selection Before selecting an API or CDS entity, verify: - API State/release status in the target system; - supported operation and business scenario; - communication scenario and authorization requirements; - edition and minimum release; - ETag, CSRF, batch/change-set, and error semantics; - update versus read-only capability; - rate, payload, and extensibility limitations. ### 22.3 Authorization layers ```text Business authorization operation allowed for user and organizational context Communication authorization technical client may call service/partner profile Data authorization caller may read the requested business data State/feature control operation permitted for current document state ``` A technically authenticated API client can still be correctly rejected by business authorization or document state. ### 22.4 Sensitive operational data Integration traces can contain customer data, addresses, prices, bank references, tokens, and internal identifiers. Store sanitized payloads where possible, restrict monitor access, and avoid copying secrets or full personal data into application logs. --- ## 23. Technical Insights and Common Misinterpretations ### 23.1 Delivery is execution, but not posting An Outbound Delivery is more than a plan because it owns warehouse/shipping execution. Its existence still does not prove PGI. ### 23.2 Picking and packing are operational states They prepare goods for dispatch. Neither reduces Inventory Management stock by itself. ### 23.3 Movement type is instruction, not evidence `LIPS-BWART = 601` can explain expected posting behavior. Only the executed material document proves the goods issue. ### 23.4 Billing and payment belong to different components Billing creates the customer invoice and normally the receivable. Incoming payment and clearing belong to FI and can have partial, residual, or on-account states. ### 23.5 Cancellation and reversal preserve audit history Corrective documents offset earlier effects. They do not erase the original transaction. ### 23.6 IDoc success is not transport success alone Inbound receipt, application posting, and resulting business-document identity are distinct checkpoints. An outbound sender status also cannot prove how the receiver completed its business process. ### 23.7 API success needs correlation Record the external document key and reread the resulting state. This protects against lost responses, duplicate retries, and false assumptions about posting. ### 23.8 Document flow is not composition Sales Order, Delivery, Material Document, Billing Document, and Payment are independent objects linked by reference and process flow. Deleting a root must not cascade across those legal and accounting records. ### 23.9 Status is navigation, posting document is proof Status accelerates selection and diagnosis. Posting documents and their reversal chain provide stronger event evidence. --- ## 24. Compact Technical Map ```text FULFILLMENT Sales Order item/schedule line delivery relevance + confirmed open quantity + due date + no block │ ▼ Delivery creation VTLA copy control + split/combination rules │ ▼ LIKP delivery header / LIPS delivery item pick → pack → warehouse execution │ ▼ PGI operation actual GI date + goods-movement status MATDOC material-document line inventory and relevant accounting effect BILLING AND FINANCE Delivery or Sales Order billable item VTFL or VTFA copy control + billing relevance + no block │ ▼ VBRK billing header / VBRP billing item PRCD_ELEMENTS pricing result │ ▼ VKOA revenue account determination FI journal entry / customer receivable │ ▼ Incoming payment full / partial / residual / on-account clearing state PROCESS LINEAGE VBFA predecessor/successor graph direct source references + statuses + reversal documents INTEGRATION BAPI synchronous classic business operation IDoc persisted asynchronous business message OData/API released HTTP operation with ETag/CSRF where required Event asynchronous notification followed by state retrieval Every path records correlation key → business document → final state → reversal/retry evidence ``` The map should be read boundary by boundary. At each transition, distinguish configuration that permits an operation, transaction state that prepares it, the application operation that executes it, and the document that proves its business effect. 41:T98d,SAP SD Fulfillment, Posting, and Integration — Technical Reference This document explains the technical execution path from a delivery-relevant Sales Order through Outbound Delivery, picking, packing, Post Goods Issue (PGI), billing, accounting, payment clearing, and external integration. It connects business-document boundaries to configuration, persistence, application logs, interfaces, reversals, diagnostic evidence, and clean-core extension design. The central technical principle is: A planned or created document proves intent at its own boundary. Only the corresponding posting document and consistent process state prove that a physical or financial event occurred. This reference distinguishes three environments: - SAP S/4HANA on-premise or private edition, where SAP GUI transactions, IMG activities, and authorized persistence inspection are common diagnostic tools. - SAP S/4HANA Cloud Public Edition, where Fiori applications, configuration activities, released APIs, and communication arrangements are the normal operational contracts. - Clean-core extension development, where internal SD, MM, and FI tables are diagnostic landmarks—not write interfaces or lifecycle-stable APIs. Primary SAP sources: - SAP Learning — Processing Outbound Deliveries - SAP Learning — Posting a Goods Issue - SAP Help — Shipping Points - SAP Help — Goods Issue - SAP Help — Outbound Delivery API Operations - SAP Learning — Billing and Integration to SAP S/4HANA Finance - SAP Help — Canceling Billing Documents - SAP Help — IDoc Inbound Processing --- 1. Execution Boundaries 1.1 Baseline sell-from-stock flow text Sales Order accepted demand and commercial intent │ ▼ Outbound Delivery shipping execution object │ ├── picking ├── packing └── warehouse execution │ ▼ Post Goods Issue inventory and relevant value posting │ ▼ Billing Document customer invoice and FI transfer │ ▼ Incoming Payment and Clearing cash receipt and receivable settlement This is a baseline, not a universal sequence. Third-party sales, services, intercompany processing, consignment, returns, pro forma billing, EWM-managed warehouses, and other scenarios use different branches. 1.2 Each boundary proves one fact | Evidence | Fact established | Fact not established | | ---------------------------- | ------------------------------------------ | ---------------------------------------- | | Sales Order exists42:Td67,# SAP SD Fulfillment, Posting, and Integration — Technical Reference This document explains the technical execution path from a delivery-relevant Sales Order through Outbound Delivery, picking, packing, Post Goods Issue (PGI), billing, accounting, payment clearing, and external integration. It connects business-document boundaries to configuration, persistence, application logs, interfaces, reversals, diagnostic evidence, and clean-core extension design. The central technical principle is: > A planned or created document proves intent at its own boundary. Only the > corresponding posting document and consistent process state prove that a > physical or financial event occurred. This reference distinguishes three environments: - **SAP S/4HANA on-premise or private edition**, where SAP GUI transactions, IMG activities, and authorized persistence inspection are common diagnostic tools. - **SAP S/4HANA Cloud Public Edition**, where Fiori applications, configuration activities, released APIs, and communication arrangements are the normal operational contracts. - **Clean-core extension development**, where internal SD, MM, and FI tables are diagnostic landmarks—not write interfaces or lifecycle-stable APIs. Primary SAP sources: - [SAP Learning — Processing Outbound Deliveries](https://learning.sap.com/courses/configuring-delivery-processing-in-sap-s-4hana-sales/processing-outbound-deliveries) - [SAP Learning — Posting a Goods Issue](https://learning.sap.com/courses/configuring-delivery-processing-in-sap-s-4hana-sales/posting-a-goods-issue) - [SAP Help — Shipping Points](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/c7894a248ca14f74aca67f97528e5ad7/5d1bbf53d25ab64ce10000000a174cb4.html) - [SAP Help — Goods Issue](https://help.sap.com/docs/SAP_S4HANA_CLOUD/aff0b3f5f46c42a2b2c0fabfc233bab2/64f81a71edf5490ab522a829be075827.html) - [SAP Help — Outbound Delivery API Operations](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/2f36056ae9a044bba55bcbad204b7bc5/a4c5d84ecef2494985883829a24e393c.html) - [SAP Learning — Billing and Integration to SAP S/4HANA Finance](https://learning.sap.com/courses/exploring-sap-s-4hana-sales-essentials/executing-the-billing-process-and-the-integration-to-sap-s-4hana-finance_e2dd5db3-73c3-4cda-8ad5-1e7f39f04fba) - [SAP Help — Canceling Billing Documents](https://help.sap.com/docs/SAP_S4HANA_CLOUD/a376cd9ea00d476b96f18dea1247e6a5/2a70b6535fe6b74ce10000000a174cb4.html) - [SAP Help — IDoc Inbound Processing](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/7b24a64d9d0941bda1afa753263d9e39/4b4c8e091c300a93e10000000a421937.html) --- ## 1. Execution Boundaries ### 1.1 Baseline sell-from-stock flow ```text Sales Order accepted demand and commercial intent │ ▼ Outbound Delivery shipping execution object │ ├── picking ├── packing └── warehouse execution │ ▼ Post Goods Issue inventory and relevant value posting │ ▼ Billing Document customer invoice and FI transfer │ ▼ Incoming Payment and Clearing cash receipt and receivable settlement ``` This is a baseline, not a universal sequence. Third-party sales, services, intercompany processing, consignment, returns, pro forma billing, EWM-managed warehouses, and other scenarios use different branches. ### 1.2 Each boundary proves one fact43:Tb453, # SAP RAP Architecture and End-to-End Runtime — Technical Reference This document explains the architecture and runtime of the ABAP RESTful Application Programming Model (RAP). It traces metadata, read, and transactional requests through CDS, behavior, service exposure, the RAP transactional buffer, the save sequence, and database persistence. The central technical principle is: > CDS defines the semantic data model, the behavior definition declares the > transactional contract, the behavior pool implements application-specific > behavior, and the service layer exposes a consumer-specific projection. The > RAP runtime coordinates these artifacts as one business-object contract. This reference focuses on architectural responsibility and runtime flow. Detailed CDS modeling, EML syntax, draft, authorization, business-rule implementation, UI annotations, and testing are developed in the remaining documents of the RAP technical-reference set. Primary SAP sources: - [SAP Help — ABAP RESTful Application Programming Model](https://help.sap.com/docs/abap-cloud/abap-rap/abap-restful-application-programming-model) - [SAP Learning — Exploring the Concept and Architecture of RAP](https://learning.sap.com/courses/building-transactional-apps-with-the-abap-restful-application-programming-model/exploring-the-concept-and-architecture-of-rap) - [SAP Help — RAP BO Runtime](https://help.sap.com/docs/abap-cloud/abap-rap/rap-bo-runtime) - [SAP Help — RAP Business Object Contract](https://help.sap.com/docs/abap-cloud/abap-rap/rap-business-object-contract) - [SAP Help — Entity Manipulation Language](https://help.sap.com/docs/abap-cloud/abap-rap/entity-manipulation-language-eml) - [SAP Help — Business Service](https://help.sap.com/docs/abap-cloud/abap-rap/business-service) - [SAP Help — Service Definition](https://help.sap.com/docs/abap-cloud/abap-rap/service-definition) - [SAP Help — OData V4 Service Binding Editor](https://help.sap.com/docs/abap-cloud/abap-development-tools-user-guide/using-service-binding-editor-for-odata-v4-service) --- ## 1. RAP in One Architectural View ### 1.1 Design-time stack ```text Consumer Fiori elements / external API client / ABAP EML consumer │ ▼ Business service exposure Service Binding + Service Definition │ ▼ Consumer projection CDS Projection + Behavior Projection + Metadata Extension │ ▼ RAP Business Object CDS root/composition model + Base Behavior Definition │ ▼ Behavior implementation Behavior Pool: handlers and saver where implementation is required │ ▼ Persistence and external capabilities Database tables / released APIs / legacy implementation ``` The stack is not a sequence of duplicate models. Each layer makes a different decision: | Layer | Primary decision | | ------------------ | ------------------------------------------------------------ | | Persistence | Where durable state is stored | | CDS data model | What the business data means and how entities relate | | Base behavior | Which operations and transactional rules the BO supports | | Behavior pool | How application-specific operations and rules execute | | Projection | Which data and behavior one consumer may use | | Service definition | Which CDS entities form one business service | | Service binding | Which protocol and service category expose that service | | Metadata extension | How a metadata-driven UI presents the service | | Consumer | Which operations are requested and how results are displayed | ### 1.2 Runtime services supplied by RAP Depending on the implementation type and declared features, RAP can coordinate: - query processing and OData query options; - typed standard and custom operations; - transactional buffering; - optimistic and pessimistic concurrency; - authorization and feature control; - draft lifecycle; - determinations, validations, actions, and prechecks; - message propagation; - save-sequence orchestration; - OData exposure and metadata generation. RAP is therefore not only an OData generator. It is a business-object runtime and programming model whose operations can also be consumed locally through EML without HTTP. ### 1.3 Provider and consumer sides ```text BO provider defines CDS + behavior + implementation guarantees the business-object contract BO consumer invokes exposed operations through OData or EML depends on the projected or released contract ``` An OData client is one possible consumer. A behavior implementation can also consume its own BO through local EML, and one ABAP component can consume a released BO interface through EML. --- ## 2. RAP Business Object ### 2.1 Aggregate structure A RAP Business Object is an entity tree with one root and optional composed children. ```text SalesOrderRequest root entity ├── Items composition child │ └── Schedules composition child └── OrderPartners composition child Item ───────────── association ─────────> Product OrderPartner ───── association ─────────> BusinessPartner ``` Composition expresses lifecycle ownership inside the aggregate. Association expresses a relationship to an independently meaningful entity or BO. The root provides the aggregate entry point and coordinates transaction-level concerns such as locking, authorization dependency, draft ownership, and total ETag behavior according to the model. ### 2.2 Data contract plus behavior contract ```text CDS entity tree fields + keys + associations + compositions + semantics Base Behavior Definition operations + field control + locks + authorization + ETags + actions + determinations + validations + draft + mapping Together RAP Business Object contract ``` A CDS entity without transactional behavior can still support a read model. A transactional RAP BO needs a behavior definition that states which changes are legal and how the runtime should coordinate them. ### 2.3 Aggregate consistency The aggregate boundary determines which state should change consistently in a single BO transaction. For an order request: - an Item normally cannot exist without its Request; - deleting the Request normally removes its lifecycle-owned Items; - Product and Customer remain independent; - root and children can participate in one transactional buffer and save sequence. The boundary should follow business ownership rather than screen layout or foreign-key existence alone. --- ## 3. Repository Artifact Responsibilities ### 3.1 Persistence table The database table stores durable state. It does not itself define: - business names and semantic associations; - transactional operations; - authorization behavior; - draft lifecycle; - OData exposure; - Fiori presentation. ```abap define table zsor_request { key client : abap.clnt not null; key request_uuid : sysuuid_x16 not null; request_number : abap.char(10); sold_to_party : abap.char(10); status : abap.char(2); total_amount : abap.curr(15,2); transaction_currency : abap.cuky; local_last_changed_at : abp_locinst_lastchange_tstmpl; } ``` The table is persistence, not the public business API. ### 3.2 Base CDS entity The base CDS entity gives persistence business meaning and defines BO topology. ```abap define root view entity ZI_SalesOrderRequest as select from zsor_request as Request composition [0..*] of ZI_SalesOrderItem as _Items association [0..1] to ZI_CustomerReference as _Customer on $projection.SoldToParty = _Customer.CustomerID { key Request.request_uuid as RequestUUID, Request.request_number as RequestNumber, Request.sold_to_party as SoldToParty, Request.status as Status, @Semantics.amount.currencyCode: 'TransactionCurrency' Request.total_amount as TotalAmount, Request.transaction_currency as TransactionCurrency, Request.local_last_changed_at as LocalLastChangedAt, _Items, _Customer } ``` `ZI_` is a customer naming convention. The prefix does not create an interface contract or behavior by itself. ### 3.3 Base Behavior Definition The base BDEF declares the reusable BO's transactional capabilities. ```abap managed implementation in class zbp_i_salesorderrequest unique; strict ( 2 ); define behavior for ZI_SalesOrderRequest alias SalesOrderRequest persistent table zsor_request lock master authorization master ( instance ) etag master LocalLastChangedAt { create; update; delete; field ( readonly ) RequestUUID, TotalAmount; field ( mandatory : create ) SoldToParty; association _Items { create; } } ``` The BDEF says what exists in the BO contract. It does not make every capability available to every service consumer. ### 3.4 Behavior pool The behavior pool is the ABAP class pool associated with a behavior definition. Its local handler classes implement application-specific interaction logic such as actions, determinations, validations, authorizations, and feature control. Saver logic participates where the implementation scenario requires it. ```text Behavior Definition declares action Submit │ ▼ Behavior Pool handler method implements Submit business logic ``` The behavior pool is not a service and does not link HTTP directly to the BDEF. The RAP runtime dispatches BO operations to it according to the behavior contract. ### 3.5 CDS projection A CDS projection defines a consumer-specific data shape over the reusable model. ```abap define root view entity ZC_SalesOrderRequest provider contract transactional_query as projection on ZI_SalesOrderRequest { key RequestUUID, RequestNumber, SoldToParty, Status, TotalAmount, TransactionCurrency, _Items : redirected to composition child ZC_SalesOrderItem, _Customer } ``` Redirection keeps navigation within the projected topology. Without proper redirection, navigation can target the underlying model rather than the corresponding consumer projection. Redirection does not “copy data” and its absence does not universally mean that fields become blank. ### 3.6 Behavior projection The behavior projection exposes selected base-BO behavior to one consumer. ```abap projection; strict ( 2 ); define behavior for ZC_SalesOrderRequest alias SalesOrderRequest { use create; use update; use delete; use association _Items { create; } use action Submit; } ``` Custom business logic is not implemented in the behavior projection. It stays in the base BO's behavior pool so every permitted consumer receives the same invariants. ### 3.7 Metadata extension A metadata extension commonly holds UI vocabulary annotations separately from the core CDS model. ```abap @Metadata.layer: #CORE annotate entity ZC_SalesOrderRequest with { @UI.lineItem: [{ position: 10 }] @UI.identification: [{ position: 10 }] RequestNumber; } ``` Metadata can control presentation, field grouping, value help, and UI actions. It must not be the only enforcement point for business invariants. ### 3.8 Service definition The service definition chooses which CDS entities form the protocol-agnostic business service. ```abap @EndUserText.label: 'Sales Order Request Service' define service ZUI_SALES_ORDER_REQUEST { expose ZC_SalesOrderRequest as SalesOrderRequests; expose ZC_SalesOrderItem as SalesOrderItems; expose ZI_CustomerReference as Customers; expose ZI_ProductReference as Products; } ``` Reference entities are exposed when the consumer needs to address or query them—for example through value help or navigation. An association in CDS does not automatically guarantee that every target is available as an entity set in the service. ### 3.9 Service binding The service binding attaches a service definition to a concrete protocol and service category, such as: - OData V4 UI; - OData V4 Web API; - another binding type supported by the target platform. One service definition can support multiple bindings or service versions. The binding owns protocol-level exposure; it does not implement domain logic. ### 3.10 Fiori elements or API client Fiori elements interprets OData metadata and annotations to generate floorplan behavior. An external API client reads the service document and metadata to construct requests. Both are consumers: ```text Consumer requests operation → RAP BO enforces business behavior → consumer renders success, state, and messages ``` The UI can improve usability but cannot replace BO validation or authorization. --- ## 4. Three Runtime Paths RAP is easier to reason about when metadata, query, and transactional paths are separated. ```text Metadata path describe entities, fields, annotations, navigation, and operations Query path retrieve data with filtering, sorting, paging, search, and authorization Transactional path execute create/update/delete/action in a RAP LUW and save accepted changes ``` A single Fiori screen can use all three paths, but they do not execute the same runtime work. --- ## 5. Metadata Request Path ### 5.1 Flow ```text Fiori elements or API client requests $metadata │ ▼ OData service binding identifies protocol/service version │ ▼ Service definition identifies exposed CDS entities │ ▼ Projection CDS and Behavior Projection define exposed shape/capabilities │ ▼ CDS annotations and metadata extensions contribute vocabulary │ ▼ OData metadata document returned to consumer ``` The metadata describes fields, types, entity sets, associations/navigation, actions, capabilities, and annotations according to the exposed contract. ### 5.2 Metadata is descriptive, not transactional execution When Fiori elements renders a column because of `@UI.lineItem`, the annotation has influenced presentation. It has not read a database row or executed an amount calculation. Likewise, a value-help annotation describes lookup behavior. Backend validation must still protect the business rule against direct OData, EML, and other consumers. ### 5.3 Metadata troubleshooting boundary ```text Annotation source → active CDS/metadata extension → service metadata → Fiori metadata cache → rendered control ``` If the expected annotation is absent from `$metadata`, debugging the browser layout first is premature. --- ## 6. Managed Query Path ### 6.1 OData read flow ```text Client GET + $select / $filter / $orderby / $top / $skip / $expand │ ▼ Service binding parses the OData request │ ▼ Service definition and projection identify entity/query contract │ ▼ RAP query runtime interprets requested fields and query options │ ▼ CDS query + access control + supported query semantics │ ▼ Optimized database query │ ▼ OData response serialized to the client ``` For a normal CDS-based managed query, the framework generates and executes the database query. The behavior pool is not automatically called merely because a client reads a list. Additional behavior-related calls can still occur for requested functions, instance features, authorizations, draft state, messages, or other declared capabilities. ### 6.2 Pushdown The query runtime can translate supported OData options into database work: ```text $filter → SQL filter $orderby → database ordering $top → result limit $skip → paging offset $select → required columns ``` This reduces data transfer and application-server processing. The exact query plan remains database- and model-dependent. ### 6.3 CDS access control CDS DCL can restrict which rows a user may read. It participates in the query path according to the access-control model. ```text Service exposure says the entity is reachable CDS access control says which rows are readable BO authorization says which operations are permitted ``` These are complementary controls. ### 6.4 Unmanaged query path When a CDS-backed SQL query is insufficient—for example when data comes from a remote service—a CDS custom entity can delegate retrieval to an ABAP class implementing the RAP query-provider interface. ```text OData query → CDS custom entity → IF_RAP_QUERY_PROVIDER implementation → remote/nonstandard data source → response object ``` In an unmanaged query, the developer must handle supported paging, sorting, filtering, total count, and authorization responsibilities correctly. It is not a shortcut around the managed query model. --- ## 7. Transactional Request Path ### 7.1 OData modification flow ```text Fiori or API request POST / PATCH / DELETE / action │ ▼ Service Binding protocol, request parsing, changeset boundary │ ▼ Service Definition + Projection exposed entity and permitted projected behavior │ ▼ Base Behavior Definition operation contract, field control, concurrency, authorization │ ▼ RAP interaction phase precheck / standard operation / handler / determination / action │ ▼ Transactional buffer current uncommitted BO state │ ▼ RAP save sequence finalization / validation / late numbering / persistence / cleanup │ ▼ Database commit or rollback │ ▼ MAPPED / FAILED / REPORTED and operation result returned to consumer ``` The exact callbacks depend on implementation type, operation, draft state, and declared behavior. The diagram is a responsibility map, not a promise that every hook runs for every request. ### 7.2 Projected operation first A base action can exist but remain unavailable through a given service if the Behavior Projection does not expose it. ```text Base BDEF declares Release + Behavior Projection uses Release + Service exposes the projected entity = OData consumer can discover/invoke Release, subject to controls ``` The projection narrows the contract; it does not duplicate the implementation. ### 7.3 Runtime entity name In EML: ```abap MODIFY ENTITIES OF ZI_SalesOrderRequest IN LOCAL MODE ENTITY SalesOrderItem UPDATE FIELDS ( NetAmount ) WITH CORRESPONDING #( items ). ``` `ZI_SalesOrderRequest` identifies the RAP BO through its root entity. `SalesOrderItem` identifies an entity or alias declared inside that BO's behavior definition. It is not a free-form operation name. ### 7.4 One root names the BO An EML statement uses `ENTITIES OF <root>` because operations are coordinated within the BO contract rooted at that entity. The selected `ENTITY` can still be a composed child. ```text BO identifier: ZI_SalesOrderRequest Selected node: SalesOrderItem Operation: UPDATE ``` This is why a child update is written as an operation “of” the root BO. --- ## 8. RAP BO Runtime Phases ### 8.1 Interaction phase SAP divides BO runtime into an interaction phase and a save sequence. During the interaction phase, consumers invoke operations and the BO maintains the current transaction state in its buffer. ```text Initial persisted state │ ▼ CREATE / UPDATE / DELETE / ACTION │ ├── field and operation control ├── authorization / feature checks ├── prechecks where declared ├── determinations and action logic └── messages and failures │ ▼ Current transactional-buffer state ``` Multiple operations can participate in one RAP Logical Unit of Work (LUW) before persistence. ### 8.2 Transactional buffer The transactional buffer represents the current BO state including accepted, unsaved changes. ```text Database state at transaction start + buffered creates + buffered updates - buffered deletes = current transactional state ``` Every transactional RAP BO requires a buffer. In managed RAP, the framework provides it. In unmanaged RAP, the provider assumes responsibility for the essential implementation, including correct buffering semantics. ### 8.3 Save sequence The save sequence turns an acceptable buffered state into durable state. Representative stages are: ```text FINALIZE last permitted final calculations/changes before save checks complete │ ▼ CHECK_BEFORE_SAVE validations and consistency checks can reject the save │ ▼ ADJUST_NUMBERS final keys assigned for late-numbered instances where applicable │ ▼ SAVE persist accepted state │ ▼ CLEANUP release/reset transaction resources ``` The actual framework callbacks vary between managed, unmanaged, and additional save scenarios. Application code must respect the phase contract; late errors after the point of no return can cause runtime failure rather than ordinary business rejection. ### 8.4 Successful save ```text Buffered state accepted → persistence operations succeed → database transaction commits → response returns keys/results/messages → buffer is cleaned up ``` ### 8.5 Rejected save ```text Validation or check-before-save failure → failed instances and messages returned → persistence does not commit for the failed transactional request → consumer retains or corrects editable state according to scenario ``` For draft-enabled BOs, the invalid draft can remain persisted and editable while activation of that draft is rejected. Draft semantics are separate from ordinary transient buffering. --- ## 9. Three States That Must Not Be Confused | State | Durable | Cross-session | Purpose | | -------------------- | ------- | ------------- | --------------------------------------- | | Transactional buffer | No | No | Hold current changes inside RAP LUW | | Draft persistence | Yes | Yes | Preserve an unfinished editable version | | Active persistence | Yes | Yes | Store committed official business state | ```text Transactional buffer temporary transaction memory Draft persistent editing state managed through RAP draft lifecycle Active database state committed business data ``` A draft still uses a transactional buffer while a request modifies it. Draft does not replace the buffer. ### 9.1 SQL versus EML visibility An ordinary ABAP SQL `SELECT` reads database state. It does not automatically represent unsaved changes in the RAP transactional buffer. ```text SELECT from persistence → committed database representation READ ENTITIES → BO operation and transactional-state semantics ``` Behavior implementations should use EML when they need the current BO state, especially when calculations depend on changes made earlier in the same RAP LUW. --- ## 10. Managed, Unmanaged, and Additional Save ### 10.1 Managed implementation Managed RAP is appropriate when framework-managed transactional processing and persistence fit the business object. RAP can provide: - standard create, update, delete, and create-by-association processing; - managed transactional buffer; - persistence mapping; - locking and ETag support as declared; - save orchestration. The developer still owns: - the CDS and behavior model; - domain actions; - determinations and validations; - authorization and feature-control implementation; - field control and business messages; - tests and operational behavior. Managed does not mean “no ABAP” or “all business logic is generated.” ### 10.2 Unmanaged implementation Unmanaged RAP is appropriate when an existing implementation, legacy business logic, remote source, or nonstandard persistence mechanism must remain authoritative. The developer implements more of the interaction and save responsibilities, including correct transactional buffering, standard operations, and persistence orchestration according to the BO contract. ```text Managed framework owns generic transactional mechanics Unmanaged application provider owns essential transactional mechanics ``` Unmanaged is not inherently more powerful or more professional. It carries more responsibility and should be selected because the integration boundary requires it. ### 10.3 Managed with additional or unmanaged save Hybrid variants let the managed interaction phase coexist with application- specific save work. They are useful when the normal managed buffer is valuable but persistence must also invoke a legacy API, write extra durable data, or perform another supported save responsibility. The selected variant must follow the platform's exact release-specific contract. It must not perform uncontrolled commits inside BO implementation. ### 10.4 Draft is an independent choice ```text Managed or unmanaged = who implements transaction mechanics Draft or non-draft = whether a persistent editing lifecycle is provided ``` These are different architectural dimensions. --- ## 11. Entity Manipulation Language ### 11.1 Purpose EML is part of the ABAP language and provides type-safe access to RAP BO operations without using HTTP. ```text OData consumer → service contract → RAP BO ABAP consumer → EML → RAP BO ``` Both paths reach the business-object contract, although service projections, authorization context, and permitted EML modes can differ. ### 11.2 Main statement families ```text READ ENTITIES read instances, associations, functions, permissions MODIFY ENTITIES create, update, delete, create by association, execute actions COMMIT ENTITIES trigger the RAP save sequence for external/non-RAP consumption ROLLBACK ENTITIES discard RAP LUW changes and reset the transactional buffer ``` ### 11.3 Consumer EML example ```abap MODIFY ENTITIES OF ZI_SalesOrderRequest ENTITY SalesOrderRequest CREATE FIELDS ( SoldToParty TransactionCurrency ) WITH VALUE #( ( %cid = 'REQ_1' SoldToParty = 'C1000' TransactionCurrency = 'EUR' ) ) MAPPED DATA(mapped) FAILED DATA(failed) REPORTED DATA(reported). IF failed IS INITIAL. COMMIT ENTITIES RESPONSE OF ZI_SalesOrderRequest FAILED DATA(commit_failed) REPORTED DATA(commit_reported). ENDIF. ``` The consumer checks interaction-phase and commit responses separately. A successful `MODIFY` only means the change entered the RAP transaction; it does not itself prove database persistence. ### 11.4 `IN LOCAL MODE` Inside its own behavior pool, a BO implementation can use EML `IN LOCAL MODE` to call its BO directly. According to the operation, local mode bypasses controls such as: - authorization checks; - feature control; - prechecks; - CDS access control for applicable reads; - readonly restrictions for internal derived-field updates. It remains within RAP transactional processing. It is not a general privilege for external callers and is not available merely because two BOs participate in the same transaction. ```text Own behavior pool + own BO → IN LOCAL MODE can be valid External/cross-BO consumer → consume the published/released contract and controls ``` Using local mode creates a responsibility: internal logic must preserve the invariants that consumer-facing controls normally protect. --- ## 12. Typed RAP Responses ### 12.1 `MAPPED` `MAPPED` returns key mapping, especially from a content identifier such as `%cid` to the assigned transactional or final key. ```text Caller temporary identity %cid → RAP-created instance identity ``` It does not map CDS field names to database-column names. Persistence mapping belongs to the behavior model. ### 12.2 `FAILED` `FAILED` identifies instances for which an operation or save could not complete. It controls transactional outcome for those instances according to the RAP contract. ```text FAILED entry = this entity instance did not pass the requested processing ``` ### 12.3 `REPORTED` `REPORTED` carries messages and related information for consumers. A reported message by itself is not universally the mechanism that rejects an operation. The failure marker and RAP contract determine failure; the message explains the outcome. ```text FAILED → affected instance failed REPORTED → explanation, severity, field highlighting, state area ``` Warning and success messages can also be reported without rejecting the operation. ### 12.4 Action result An action can return an updated entity or custom result through its declared result contract. ```abap result = VALUE #( FOR request IN requests ( %tky = request-%tky %param = request ) ). ``` `%tky` correlates the response with the precise transactional instance. It can contain more transactional identity context than the visible persistent key, including draft identity where relevant. --- ## 13. Transaction Ownership and Commit ### 13.1 Framework-managed service request When OData invokes a RAP BO, the RAP framework owns request and changeset transaction orchestration. Behavior implementation code must not issue its own `COMMIT WORK` or `COMMIT ENTITIES` inside the handler. ```text OData changeset → framework collects operations → interaction phase → save sequence → one controlled commit or rollback ``` ### 13.2 External EML consumer An ABAP report, class, or test consuming a BO through EML owns the RAP LUW boundary and normally uses `COMMIT ENTITIES` to persist successful changes. ```text MODIFY ENTITIES → inspect FAILED and REPORTED → COMMIT ENTITIES → inspect commit FAILED and REPORTED ``` ### 13.3 Behavior implementation Inside a behavior pool: - use EML to request additional BO operations when allowed; - do not independently commit; - let the framework preserve atomicity across affected BOs; - propagate failures and messages through RAP response structures. An explicit commit inside reusable business logic would split the transaction and prevent the framework from rolling the entire request back consistently. --- ## 14. Authorization, Feature, and Field-Control Boundaries These controls answer different runtime questions: | Control | Responsibility | | ------------------------ | ------------------------------------------------------------ | | CDS access control | Restrict readable data according to DCL model | | Global authorization | Decide user permission independent of one instance | | Instance authorization | Decide user permission using instance context | | Global feature control | Enable/disable capability globally at runtime | | Instance feature control | Enable/disable operation or field for current instance state | | Static field control | Declare readonly or mandatory characteristics in BDEF | | Dynamic field control | Return instance-specific field behavior where supported | | Validation | Reject inconsistent business state | ```text User may update orders → authorization Released order cannot be edited → feature/state control Requested quantity must be positive → validation ``` Disabling a button is not security. A direct OData or EML consumer must still be constrained by the BO contract. --- ## 15. Activation, Publishing, Transport, and Deployment ### 15.1 Activation Activation creates or updates the active repository version of an ABAP development object after syntax and dependency checks. RAP artifacts depend on one another, so activation is usually performed from lower-level persistence and CDS artifacts toward behavior and service exposure. ```text Table → base CDS → projection CDS → BDEF and behavior implementation → Behavior Projection → metadata extension → service definition → service binding ``` Activation is not end-user deployment and does not automatically publish every service endpoint. ### 15.2 Service publishing Publishing a service binding makes the configured service/version accessible in the current ABAP system according to its platform and authorization setup. ```text Active Service Definition + active Service Binding + publish = reachable service endpoint in that system ``` The preview is a consumer of that endpoint. “Local publish” means local to the current ABAP system/tenant, not execution on the developer's laptop. ### 15.3 Transport A transport moves repository and configuration changes through the system landscape. It does not mean that an independently built Fiori application has already been deployed to its frontend runtime or that every target-system service is configured and authorized. ### 15.4 Deployment Deployment delivers a separately packaged application to its runtime, for example a standalone Fiori application. Generated Fiori preview, service publication, ABAP transport, and frontend deployment are related but different lifecycle steps. ### 15.5 ADT and execution location RAP development can be performed in ABAP Development Tools in Eclipse. ADT is the development client; activation, OData execution, ABAP runtime, and database access occur in the connected ABAP system. ```text Developer machine Eclipse / ADT source editor and repository tools │ ▼ ABAP system active repository + RAP runtime + application server │ ▼ Configured database persistence read by ABAP SQL and CDS ``` CDS does not use a separate database from ABAP. It models data in the database connected to the ABAP system, subject to the CDS source and runtime contract. --- ## 16. End-to-End Sales Order Request Trace ### 16.1 Read a list ```text 1. Fiori elements obtains OData metadata 2. UI builds a List Report from annotations 3. UI sends GET with filter/select/order/paging options 4. Service Binding resolves the service version 5. Projection determines exposed fields and navigation 6. RAP managed query evaluates CDS, query options, and access control 7. Database returns matching rows 8. OData serializes the projected result 9. Fiori renders the list ``` ### 16.2 Create a request with items ```text 1. Consumer sends root CREATE and item create-by-association 2. Projection contract permits the exposed operations 3. Base BDEF supplies field/operation/authorization contract 4. RAP assigns early UUIDs when configured 5. Managed runtime places root and items in transactional buffer 6. Determinations initialize or derive BO-owned values 7. MAPPED correlates client identifiers with instance keys 8. Save is requested at the request/changeset boundary 9. On-save validations inspect current aggregate state 10. Accepted instances persist atomically 11. FAILED/REPORTED and created keys return to consumer ``` ### 16.3 Submit action ```text 1. UI annotation exposes an action button 2. Behavior Projection exposes Submit 3. Client invokes bound OData action for selected instance 4. RAP resolves %tky and checks authorization/feature control 5. Behavior Pool Submit method executes 6. Method reads current BO state through EML 7. Invalid transition appends FAILED and REPORTED 8. Valid transition updates Status through local EML 9. Transactional buffer holds updated state 10. Save sequence validates and persists 11. Action result and messages return to UI 12. Side-effect metadata can instruct UI to reread affected fields ``` The UI annotation causes discoverability and rendering. The action contract and behavior pool own the business transition. ### 16.4 Derived amount update ```text RequestedQuantity or UnitPrice changes → determination trigger → read current Item state from transactional buffer → calculate Item.NetAmount → update derived field through local EML → recalculate parent TotalAmount from current Items → buffer contains consistent aggregate → side effect tells UI which values to refresh → save sequence persists accepted result ``` The side effect does not calculate the amount. It describes which consumer data became stale after backend logic ran. --- ## 17. Runtime Diagnostics by Layer ### 17.1 Universal trace ```text Observed symptom → identify metadata, query, interaction, or save path → capture exact entity, operation, key/%tky, and payload → inspect projected capability → inspect base behavior contract → inspect behavior implementation when it participates → inspect FAILED, REPORTED, HTTP error, and application log → inspect transactional versus persistent state → inspect service/cache/UI only at its responsible boundary ``` ### 17.2 UI field or action missing ```text Metadata extension / CDS annotation → active projection → exposed entity in Service Definition → active/published Service Binding → $metadata contains annotation/capability → Fiori cache and floorplan interpretation ``` For an action, also verify: ```text Base BDEF declaration → Behavior Projection use action → action annotation → feature-control result → authorization result ``` ### 17.3 Read returns no rows ```text OData request and filter values → correct entity set and service version → projection filters/parameters → CDS associations and join cardinality → DCL/access control → database data and client context → unmanaged query implementation if applicable ``` An entity exposed in a service can correctly return no rows because DCL denies all data. ### 17.4 Modification rejected before handler logic Possible earlier boundaries include: - operation not exposed by Behavior Projection; - readonly or mandatory field contract; - authorization or feature control; - precheck; - stale ETag; - invalid payload/type or missing key; - draft/active instance mismatch. The absence of a breakpoint hit in an action or validation does not prove that the request reached that implementation method. ### 17.5 Modify succeeds but save fails ```text Interaction-phase MODIFY accepted → current change exists in transactional buffer → save-sequence validation/check fails → COMMIT ENTITIES or OData changeset fails → database remains unchanged ``` Inspect both interaction and commit response structures. The final business error can be returned only when save is attempted. ### 17.6 Database is unchanged ```text Verify operation response → verify save boundary occurred → verify validation/late-numbering/save messages → verify correct client and persistence table → verify draft versus active instance → verify rollback or failed changeset ``` Do not add direct SQL writes to “fix” a missing save. That bypasses the BO contract and hides the actual transaction error. --- ## 18. Performance and Correctness Boundaries ### 18.1 RAP requests are set-oriented Handler methods receive tables of keys or instances because one request can process several entities. Implementations should avoid assuming one row. ```text keys table → bulk EML read → set-based lookup/calculation → bulk EML modify → correlated FAILED/REPORTED/result rows ``` ### 18.2 Avoid database reads per entity Poor pattern: ```text LOOP over keys SELECT one row SELECT reference row MODIFY one entity ENDLOOP ``` Preferred direction: ```text READ ENTITIES for all keys → extract distinct reference keys → one set-oriented lookup → process in memory → one bulk MODIFY ENTITIES ``` ### 18.3 Read the correct state Business logic depending on current transaction changes should read via EML, not assume the database already contains earlier modifications. ### 18.4 Idempotent determinations The runtime does not guarantee a simple user-imagined order across all determinations. Derived-value logic should be safe when triggered repeatedly and should converge to the same result for the same BO state. ### 18.5 No commits in handlers Independent commits break RAP atomicity and can leave partial cross-entity or cross-BO results. The framework or external EML consumer owns the save boundary. --- ## 19. Clean-Core and Release Contracts ### 19.1 Internal existence is not release A CDS entity, class, or function can exist in the system without being released for Cloud development or stable cross-component consumption. ```text Exists in repository ≠ released API ≠ permitted in ABAP Cloud ≠ stable across upgrades ``` Check API State and supported capabilities in the target system. ### 19.2 BO interface versus ordinary service projection A formal RAP BO interface can use a projection with provider contract `transactional_interface` and a Behavior Definition Interface to provide a lifecycle-stable cross-component contract. An ordinary service projection commonly uses `transactional_query` and shapes one business service. Naming a CDS entity `ZI_...` does not automatically make it a released RAP BO interface. ```text Base BO → optional released BO interface for cross-component stability → service-specific projection for OData consumer ``` ### 19.3 Extension hierarchy Preferred extension dependencies move toward released contracts: ```text Released BO interface / API / event → custom adapter or extension → custom service projection Avoid direct dependency on SAP internal table or unreleased implementation class ``` ### 19.4 Protocol does not define the domain boundary OData V4, EML, and events are consumption mechanisms. Aggregate ownership, business rules, and transaction boundaries should be defined from the domain and provider contract first. --- ## 20. Common Architectural Misinterpretations ### 20.1 CDS is not only a database view CDS can define semantic elements, associations, compositions, annotations, authorization relevance, and BO topology in addition to database projection. ### 20.2 The behavior pool is not the service It implements BO behavior. Service Definition and Service Binding expose a projected contract through a protocol. ### 20.3 The Behavior Projection contains no domain implementation It selects capabilities for a consumer. The base behavior pool remains the implementation owner. ### 20.4 `REPORTED` does not universally reject an operation It transports messages. `FAILED`, validation outcome, and RAP transaction semantics determine rejection. ### 20.5 Managed RAP is not zero-code CRUD The framework supplies generic transaction mechanics, while the developer owns the domain model, rules, security implementation, messages, and tests. ### 20.6 Transactional buffer is not draft The buffer is temporary LUW state used by every transactional BO. Draft is a persistent editing version with its own lifecycle. ### 20.7 Service publication is not application deployment Publication exposes an endpoint in the ABAP system. Transport and frontend deployment solve different lifecycle problems. ### 20.8 OData is not required for local BO consumption EML invokes RAP BO operations directly from ABAP and preserves the declared BO contract according to the consumption mode. ### 20.9 Direct SQL does not participate in RAP state automatically Database reads do not automatically include unsaved transactional-buffer data, and direct writes bypass RAP behavior. ### 20.10 UI control is not backend protection Annotations and disabled buttons improve interaction. Authorization, validation, and feature control must protect the BO for every consumer. --- ## 21. Compact Architecture Map ```text DESIGN TIME Persistence table durable columns and technical keys │ ▼ Base CDS root + compositions + associations semantic data model and aggregate topology │ ├── Base BDEF │ transactional contract │ │ │ └── Behavior Pool │ custom interaction/save implementation │ ▼ CDS Projection + Behavior Projection consumer-specific data and capability contract │ ├── Metadata Extension │ UI vocabulary and presentation │ ▼ Service Definition exposed entity set │ ▼ Service Binding OData protocol, category, version, publication RUNTIME — METADATA Client → Binding → Service → Projection/Behavior metadata → $metadata RUNTIME — QUERY Client GET → Binding → projected query contract → RAP query runtime + DCL → CDS/SQL or unmanaged query provider → response RUNTIME — MODIFY Client or EML consumer → projected/released BO operation → Base BDEF controls → Behavior Pool/framework interaction logic → transactional buffer → save sequence → database commit or rollback → MAPPED / FAILED / REPORTED / result STATE Transactional buffer temporary LUW state Draft persistence durable editable state Active persistence durable committed business state ``` The architecture should always be read in two directions: ```text Design persistence → semantic model → behavior → projection → service Diagnosis client symptom → service metadata/request → projection → BO contract → runtime phase → buffer/save → persistence ``` That two-way trace is the foundation for implementing and debugging every other RAP feature. 44:T8e4,SAP RAP Architecture and End-to-End Runtime — Technical Reference This document explains the architecture and runtime of the ABAP RESTful Application Programming Model (RAP). It traces metadata, read, and transactional requests through CDS, behavior, service exposure, the RAP transactional buffer, the save sequence, and database persistence. The central technical principle is: CDS defines the semantic data model, the behavior definition declares the transactional contract, the behavior pool implements application-specific behavior, and the service layer exposes a consumer-specific projection. The RAP runtime coordinates these artifacts as one business-object contract. This reference focuses on architectural responsibility and runtime flow. Detailed CDS modeling, EML syntax, draft, authorization, business-rule implementation, UI annotations, and testing are developed in the remaining documents of the RAP technical-reference set. Primary SAP sources: - SAP Help — ABAP RESTful Application Programming Model - SAP Learning — Exploring the Concept and Architecture of RAP - SAP Help — RAP BO Runtime - SAP Help — RAP Business Object Contract - SAP Help — Entity Manipulation Language - SAP Help — Business Service - SAP Help — Service Definition - SAP Help — OData V4 Service Binding Editor --- 1. RAP in One Architectural View 1.1 Design-time stack text Consumer Fiori elements / external API client / ABAP EML consumer │ ▼ Business service exposure Service Binding + Service Definition │ ▼ Consumer projection CDS Projection + Behavior Projection + Metadata Extension │ ▼ RAP Business Object CDS root/composition model + Base Behavior Definition │ ▼ Behavior implementation Behavior Pool: handlers and saver where implementation is required │ ▼ Persistence and external capabilities Database tables / released APIs / legacy implementation The stack is not a sequence of duplicate models. Each layer makes a different decision: | Layer | Primary decision | | ------------------ | ------------------------------------------------------------ | | Persistence | Where durable state is stored | | CDS data model | What the business data means and how entities relate | | Base behavior | Which operations and transactional rules the45:Tbf3,# SAP RAP Architecture and End-to-End Runtime — Technical Reference This document explains the architecture and runtime of the ABAP RESTful Application Programming Model (RAP). It traces metadata, read, and transactional requests through CDS, behavior, service exposure, the RAP transactional buffer, the save sequence, and database persistence. The central technical principle is: > CDS defines the semantic data model, the behavior definition declares the > transactional contract, the behavior pool implements application-specific > behavior, and the service layer exposes a consumer-specific projection. The > RAP runtime coordinates these artifacts as one business-object contract. This reference focuses on architectural responsibility and runtime flow. Detailed CDS modeling, EML syntax, draft, authorization, business-rule implementation, UI annotations, and testing are developed in the remaining documents of the RAP technical-reference set. Primary SAP sources: - [SAP Help — ABAP RESTful Application Programming Model](https://help.sap.com/docs/abap-cloud/abap-rap/abap-restful-application-programming-model) - [SAP Learning — Exploring the Concept and Architecture of RAP](https://learning.sap.com/courses/building-transactional-apps-with-the-abap-restful-application-programming-model/exploring-the-concept-and-architecture-of-rap) - [SAP Help — RAP BO Runtime](https://help.sap.com/docs/abap-cloud/abap-rap/rap-bo-runtime) - [SAP Help — RAP Business Object Contract](https://help.sap.com/docs/abap-cloud/abap-rap/rap-business-object-contract) - [SAP Help — Entity Manipulation Language](https://help.sap.com/docs/abap-cloud/abap-rap/entity-manipulation-language-eml) - [SAP Help — Business Service](https://help.sap.com/docs/abap-cloud/abap-rap/business-service) - [SAP Help — Service Definition](https://help.sap.com/docs/abap-cloud/abap-rap/service-definition) - [SAP Help — OData V4 Service Binding Editor](https://help.sap.com/docs/abap-cloud/abap-development-tools-user-guide/using-service-binding-editor-for-odata-v4-service) --- ## 1. RAP in One Architectural View ### 1.1 Design-time stack ```text Consumer Fiori elements / external API client / ABAP EML consumer │ ▼ Business service exposure Service Binding + Service Definition │ ▼ Consumer projection CDS Projection + Behavior Projection + Metadata Extension │ ▼ RAP Business Object CDS root/composition model + Base Behavior Definition │ ▼ Behavior implementation Behavior Pool: handlers and saver where implementation is required │ ▼ Persistence and external capabilities Database tables / released APIs / legacy implementation ``` The stack is not a sequence of duplicate models. Each layer makes a different decision:46:Tab25, # SAP RAP CDS Data Modeling and Projection Design — Technical Reference This document explains how ABAP CDS defines the structural and semantic model of a RAP business object and how CDS projection views adapt that model for a specific consumer. It focuses on entity boundaries, keys, compositions, associations, cardinality, semantic annotations, projection contracts, and navigation topology. The central design principle is: > The base CDS model describes the reusable business object and its > relationships. A CDS projection selects and adapts that model for one > consumption scenario. Neither layer replaces the behavior definition, which > owns the transactional capabilities and business rules. Primary SAP sources: - [SAP Help — Defining the Data Model in CDS Views](https://help.sap.com/docs/abap-cloud/abap-rap/defining-data-model-in-cds-views) - [SAP Help — CDS View Entities](https://help.sap.com/docs/abap-cloud/abap-data-models/cds-view-entities-8b3e8e8b8797432abecd7d1fbb6d5c12) - [SAP Help — Associations](https://help.sap.com/docs/abap-cloud/abap-data-models/cds-associations) - [SAP Help — Projection Views](https://help.sap.com/docs/abap-cloud/abap-data-models/cds-projection-views) - [SAP Help — Creating CDS View Entities for RAP](https://help.sap.com/docs/abap-cloud/abap-rap/creating-cds-view-entities) - [SAP Help — CDS Annotations for RAP](https://help.sap.com/docs/abap-cloud/abap-rap/cds-annotations) --- ## 1. Position of CDS in RAP ```text Database tables or released data sources │ ▼ Base CDS view entities fields, keys, aliases, compositions, associations, semantics │ ├──────── Base Behavior Definition │ operations and transactional contract │ ▼ CDS projection views consumer-specific field and navigation shape │ ├──────── Behavior Projection │ consumer-visible operations │ ├──────── Metadata Extension │ presentation metadata │ ▼ Service Definition and Service Binding ``` CDS is responsible for the data model. It can express: - entity elements and their ABAP Dictionary types; - semantic keys exposed by the entity; - aliases that give technical columns business-oriented names; - calculations supported by the CDS language; - root, child, and reference relationships; - semantic dependencies such as amount/currency and quantity/unit; - reusable navigation paths; - annotations consumed by the ABAP runtime and other frameworks. CDS does not by itself implement: - create, update, or delete behavior; - validations, determinations, actions, or feature control; - transactional buffering and save handling; - a custom authorization decision for a modification; - an OData endpoint. Those responsibilities belong to other RAP artifacts. --- ## 2. Persistence Model Versus Semantic Model ### 2.1 Database table A database table is the durable storage contract. It normally contains: - technical keys; - foreign-key columns; - business data; - administrative fields; - ETag timestamps; - internal processing fields; - fields needed by persistence but not every consumer. Example: ```abap define table zsor_request { key client : abap.clnt not null; key request_uuid : sysuuid_x16 not null; request_number : abap.char(10); sold_to_party : abap.char(10); status : abap.char(1); total_amount : abap.curr(15,2); transaction_currency : abap.cuky; internal_processing_code: abap.char(4); created_by : abp_creation_user; created_at : abp_creation_tstmpl; last_changed_at : abp_lastchange_tstmpl; local_last_changed_at : abp_locinst_lastchange_tstmpl; } ``` The table proves how values are stored. It does not fully explain what the business object means, which rows belong to one aggregate, or which fields a consumer should see. ### 2.2 Base CDS view entity A CDS view entity creates a reusable semantic layer over the data source: ```abap define root view entity ZI_SalesOrderRequest as select from zsor_request as Request { key Request.request_uuid as RequestUUID, Request.request_number as RequestNumber, Request.sold_to_party as SoldToParty, Request.status as Status, Request.total_amount as TotalAmount, Request.transaction_currency as TransactionCurrency, Request.last_changed_at as LastChangedAt, Request.local_last_changed_at as LocalLastChangedAt } ``` The CDS entity: - exposes business-oriented names; - selects only the columns required by the model; - can attach semantics and relationships; - provides a typed source for behavior and projections; - decouples consumers from the physical table layout. The CDS view does not copy data out of the table. It is a repository definition that the runtime translates into database access when queried. ### 2.3 Why the layers must remain separate ```text Persistence concern Semantic/consumer concern ───────────────────────────────── ───────────────────────────────── How is the value stored? What does the value mean? Which technical column exists? Which business name is stable? Which administrative field exists? Does this consumer need the field? How are rows physically keyed? How are BO nodes navigated? ``` Exposing a database table directly makes its storage design part of the consumer contract. A CDS layer allows the persistence structure to evolve behind a more stable semantic interface. --- ## 3. View Entities and Their Elements ### 3.1 Basic syntax ```abap @EndUserText.label: 'Sales Order Request' @AccessControl.authorizationCheck: #CHECK define root view entity ZI_SalesOrderRequest as select from zsor_request as Request { key Request.request_uuid as RequestUUID, Request.request_number as RequestNumber, Request.status as Status } ``` Key parts: | Construct | Meaning | | -------------------- | ------------------------------------------------- | | `define view entity` | Defines a CDS view entity | | `root` | Marks the root of a RAP composition tree | | `as select from` | Defines the data source | | `key` | Declares an element as part of the CDS entity key | | `as RequestUUID` | Assigns a semantic alias | | annotations | Add technical or semantic metadata | `root` is a modeling statement. It says that this entity may anchor a RAP business-object composition tree. It does not automatically create behavior. ### 3.2 CDS keys are not a substitute for database integrity The CDS key describes how consumers and frameworks identify the result rows. It should match the actual uniqueness of the result. ```text Database primary key enforces uniqueness in persisted rows CDS entity key declares the identity of rows exposed by the CDS entity ``` Declaring a field with `key` does not repair a query that returns duplicates. If joins, path expressions, or incorrect cardinalities multiply rows, the model is still incorrect even though the select list contains a key declaration. For a UUID-based root, the technical key is commonly a `RAW(16)` UUID exposed through a data element such as `sysuuid_x16`. A separate human-readable order number can remain a business identifier rather than the technical key. ### 3.3 Aliases and persistence mapping Aliases improve meaning: ```abap Request.sold_to_party as SoldToParty ``` If the CDS element names differ from the persistence column names, a managed behavior definition can use a mapping block: ```abap mapping for zsor_request { RequestUUID = request_uuid; RequestNumber = request_number; SoldToParty = sold_to_party; TotalAmount = total_amount; TransactionCurrency = transaction_currency; } ``` This mapping belongs to the behavior definition. It is different from the RAP response parameter `MAPPED`, which reports preliminary-to-final key mappings during EML processing. --- ## 4. Designing the Business-Object Aggregate ### 4.1 Aggregate boundary A RAP business object is normally modeled as a tree: ```text SalesOrderRequest root └── SalesOrderItem composition child └── RequestedSchedule composition grandchild ``` The root is the transactional entry point and consistency boundary. It often owns: - aggregate status; - aggregate totals; - lifecycle transitions; - locking and authorization dependencies; - navigation to all owned child nodes. The decisive question for a child is existential dependency: the child has no business meaning outside its parent aggregate. ### 4.2 Composition A composition is a specialized association that defines ownership and a parent-child lifecycle dependency. ```abap define root view entity ZI_SalesOrderRequest as select from zsor_request as Request composition [0..*] of ZI_SalesOrderItem as _Items { key Request.request_uuid as RequestUUID, _Items } ``` The root exposes the composition in its element list. The cardinality `[0..*]` means that one request may relate to zero, one, or many items. The composition states structure and ownership. Transactional operations on the child are still declared in the behavior definition, for example creation by association from the parent. ### 4.3 Association to parent The child completes the composition relationship with a to-parent association: ```abap define view entity ZI_SalesOrderItem as select from zsor_item as Item association to parent ZI_SalesOrderRequest as _Request on $projection.RequestUUID = _Request.RequestUUID { key Item.item_uuid as ItemUUID, Item.request_uuid as RequestUUID, Item.product as Product, _Request } ``` Important details: - the target is the parent CDS entity; - the `ON` condition connects the child's parent key to the root key; - `$projection.RequestUUID` refers to the element name exposed by this CDS entity, not the database column name; - the association must be published in the element list for navigation; - the association alias is later used by behavior and projection artifacts. For a deeper tree, a child can also carry an explicit association to the root when root navigation is required. The direct `association to parent` still points to the immediate parent node. ### 4.4 Composition is not an ordinary foreign-key link ```text Composition SalesOrderRequest ─owns─> SalesOrderItem child lifecycle depends on parent Association SalesOrderRequest ─refers to─> Customer target has an independent lifecycle ``` An item is a composition child because an order item without its request has no meaning in this use case. Customer, Product, Plant, and Sales Area are normally associations because those targets exist independently and are reused by many transactions. Do not choose composition merely because the database contains a foreign key. Choose it because the domain says the parent owns the target's lifecycle. --- ## 5. Associations to Independent Entities ### 5.1 Definition ```abap association [0..1] to ZI_CustomerReference as _Customer on $projection.SoldToParty = _Customer.CustomerID ``` ```abap association [0..1] to ZI_ProductReference as _Product on $projection.Product = _Product.ProductID ``` An association defines a reusable relationship. It behaves like a declared join that is instantiated when a consumer follows the association or requests a target field through a path expression. ### 5.2 Publishing versus consuming an association Publishing the association: ```abap { key Request.request_uuid as RequestUUID, Request.sold_to_party as SoldToParty, _Customer } ``` Consuming a target field through a path: ```abap { key Request.request_uuid as RequestUUID, Request.sold_to_party as SoldToParty, _Customer.CustomerName as CustomerName } ``` These have different effects: | Form | Effect | | ------------------------ | -------------------------------------------------------------------- | | `_Customer` | Publishes a navigation relationship | | `_Customer.CustomerName` | Adds a target field to the current result and causes join processing | Associations can reduce unnecessary joins because navigation is instantiated on demand. They do not guarantee good performance by themselves; deep paths, incorrect cardinalities, and wide consumption can still produce expensive SQL. ### 5.3 Association naming An underscore prefix such as `_Customer` is the established ABAP CDS convention for an association alias. The underscore communicates navigation rather than scalar data. It is a convention, not the business identity of the target. ### 5.4 Referential validity An association describes how a target is found. It does not automatically reject an invalid foreign-key value during a transactional save. ```text CDS association navigation and query relationship Value help assists selection and can support consumer validation metadata RAP validation enforces the business rule and can reject the save ``` If every submitted request must refer to an existing Customer, implement that invariant in backend behavior even when the UI provides a Customer value help. --- ## 6. Cardinality ### 6.1 Meaning Cardinality documents how many target rows may match one source row. | Numeric form | Meaning from one source instance | | ------------ | -------------------------------- | | `[0..1]` | Zero or one target | | `[1..1]` | Exactly one target is expected | | `[0..*]` | Zero, one, or many targets | | `[1..*]` | One or many targets are expected | Examples: ```abap association [0..1] to ZI_CustomerReference as _Customer ... composition [0..*] of ZI_SalesOrderItem as _Items ``` ### 6.2 Cardinality is a model assertion, not general validation `[0..1]` does not mean RAP will automatically reject two matching rows. It states what the model expects and can influence syntax checks, generated SQL, and optimizer decisions. The actual data and `ON` condition must satisfy the declaration. If a declared to-one association returns multiple targets, consumers can receive unstable or unexpected results and database optimizations may be based on a false model. ### 6.3 Cardinality does not determine ownership Both of these relationships can use `[0..*]`: ```text Order ─composition→ Items Customer ─association→ Addresses ``` The number of targets does not decide whether the relationship is a composition. Ownership and lifecycle dependency decide that. ### 6.4 Optional during editing versus required business state A `[0..1]` Customer association permits the relationship to be absent from a modeling perspective. That can support incomplete creation or draft editing. It does not express a rule such as “Customer is mandatory when Status is Submitted.” That state-dependent rule belongs in behavior validation. ```text Structural possibility Customer relationship may be empty while editing Business invariant Customer must be valid before submission or activation ``` --- ## 7. Complete Base CDS Aggregate Example ### 7.1 Root entity ```abap @EndUserText.label: 'Sales Order Request' @AccessControl.authorizationCheck: #CHECK define root view entity ZI_SalesOrderRequest as select from zsor_request as Request composition [0..*] of ZI_SalesOrderItem as _Items association [0..1] to ZI_CustomerReference as _Customer on $projection.SoldToParty = _Customer.CustomerID { key Request.request_uuid as RequestUUID, Request.request_number as RequestNumber, Request.sold_to_party as SoldToParty, Request.status as Status, @Semantics.amount.currencyCode: 'TransactionCurrency' Request.total_amount as TotalAmount, Request.transaction_currency as TransactionCurrency, Request.internal_processing_code as InternalProcessingCode, @Semantics.systemDateTime.createdAt: true Request.created_at as CreatedAt, @Semantics.user.createdBy: true Request.created_by as CreatedBy, @Semantics.systemDateTime.lastChangedAt: true Request.last_changed_at as LastChangedAt, @Semantics.systemDateTime.localInstanceLastChangedAt: true Request.local_last_changed_at as LocalLastChangedAt, _Items, _Customer } ``` ### 7.2 Child entity ```abap @EndUserText.label: 'Sales Order Request Item' @AccessControl.authorizationCheck: #CHECK define view entity ZI_SalesOrderItem as select from zsor_item as Item association to parent ZI_SalesOrderRequest as _Request on $projection.RequestUUID = _Request.RequestUUID association [0..1] to ZI_ProductReference as _Product on $projection.Product = _Product.ProductID { key Item.item_uuid as ItemUUID, Item.request_uuid as RequestUUID, Item.product as Product, @Semantics.quantity.unitOfMeasure: 'QuantityUnit' Item.requested_quantity as RequestedQuantity, Item.quantity_unit as QuantityUnit, @Semantics.amount.currencyCode: 'TransactionCurrency' Item.unit_price as UnitPrice, @Semantics.amount.currencyCode: 'TransactionCurrency' Item.net_amount as NetAmount, Item.transaction_currency as TransactionCurrency, Item.local_last_changed_at as LocalLastChangedAt, _Request, _Product } ``` ### 7.3 Structural interpretation ```text ZI_SalesOrderRequest key: RequestUUID owns: _Items references: _Customer aggregate values: Status, TotalAmount concurrency value: LocalLastChangedAt ZI_SalesOrderItem key: ItemUUID belongs to: _Request references: _Product entered values: Product, RequestedQuantity derived candidates: UnitPrice, NetAmount, TransactionCurrency ``` “Entered” and “derived” in the last diagram are design classifications. CDS has no `[entered]` or `[derived]` element syntax. The behavior definition marks consumer restrictions such as `readonly`, and determinations implement the derivation. --- ## 8. Semantic Annotations ### 8.1 Amount and currency ```abap @Semantics.amount.currencyCode: 'TransactionCurrency' Item.net_amount as NetAmount, Item.transaction_currency as TransactionCurrency ``` This metadata declares that `NetAmount` must be interpreted together with `TransactionCurrency`. Consumers can use it for formatting, decimal handling, metadata generation, and display. It does not: - convert one currency to another; - retrieve a price condition; - calculate `NetAmount`; - guarantee that header and item currencies match; - validate that the currency key exists. Those require business logic, a released conversion capability, or validation as appropriate. ### 8.2 Quantity and unit ```abap @Semantics.quantity.unitOfMeasure: 'QuantityUnit' Item.requested_quantity as RequestedQuantity, Item.quantity_unit as QuantityUnit ``` The annotation makes the quantity/unit dependency explicit. It does not perform unit conversion or availability checking. ### 8.3 Administrative timestamps Typical managed RAP administrative fields include: ```abap @Semantics.systemDateTime.createdAt: true CreatedAt, @Semantics.user.createdBy: true CreatedBy, @Semantics.systemDateTime.lastChangedAt: true LastChangedAt, @Semantics.systemDateTime.localInstanceLastChangedAt: true LocalLastChangedAt ``` Their exact use depends on the behavior definition. For example, an ETag must be declared in behavior; annotating a timestamp alone does not activate ETag concurrency control. ### 8.4 Annotation responsibility Annotations are metadata interpreted by a particular framework or runtime. Their presence does not imply arbitrary application logic. ```text Semantic annotation describes meaning or framework relationship Behavior implementation computes, validates, or changes transactional state ``` --- ## 9. CDS Projection Views ### 9.1 Purpose A projection view adapts a base CDS entity for a defined scenario: ```text Reusable base model RequestUUID, RequestNumber, SoldToParty, Status, TotalAmount, InternalProcessingCode, admin fields, relationships │ ▼ Customer-facing UI projection RequestUUID, RequestNumber, SoldToParty, Status, TotalAmount, relationships needed by UI ``` The projection decides which fields and associations are visible through that projection. It does not erase excluded fields from the base entity or table. ### 9.2 Transactional query projection ```abap @EndUserText.label: 'Sales Order Request Consumption' @AccessControl.authorizationCheck: #CHECK define root view entity ZC_SalesOrderRequest provider contract transactional_query as projection on ZI_SalesOrderRequest { key RequestUUID, RequestNumber, SoldToParty, Status, TotalAmount, TransactionCurrency, LocalLastChangedAt, _Items : redirected to composition child ZC_SalesOrderItem, _Customer } ``` `transactional_query` identifies the projection as a service-consumption layer for a transactional RAP business object. Current CDS syntax expects the provider contract to be stated explicitly. ### 9.3 Child projection ```abap @EndUserText.label: 'Sales Order Request Item Consumption' @AccessControl.authorizationCheck: #CHECK define view entity ZC_SalesOrderItem provider contract transactional_query as projection on ZI_SalesOrderItem { key ItemUUID, RequestUUID, Product, RequestedQuantity, QuantityUnit, UnitPrice, NetAmount, TransactionCurrency, LocalLastChangedAt, _Request : redirected to parent ZC_SalesOrderRequest, _Product } ``` The child projection must use `as projection on` and a provider contract just like the root projection. Omitting `as projection on ZI_SalesOrderItem` does not define a projection. ### 9.4 Base versus projection responsibility | Concern | Base CDS | CDS projection | | ----------------------- | ------------------------------------------ | ------------------------------------------------- | | BO node identity | Defines reusable entity key | Projects the required key | | Aggregate topology | Defines composition and parent association | Redirects topology to projected nodes | | Independent references | Defines reusable associations | Exposes or omits them for the consumer | | Internal field | Can retain it for implementation | Can omit it from the consumer contract | | Amount/unit semantics | Usually defined close to reusable field | Inherited or adapted when supported | | Transactional operation | Not a CDS concern | Not a CDS concern; behavior projection exposes it | | UI layout | Not a base-model concern | Usually placed in metadata extension | --- ## 10. Projection Redirection ### 10.1 Why redirection exists The base root composition points to the base child: ```text ZI_SalesOrderRequest._Items ──> ZI_SalesOrderItem ``` The consumer should navigate within the projected graph: ```text ZC_SalesOrderRequest._Items ──> ZC_SalesOrderItem ZC_SalesOrderItem._Request ───> ZC_SalesOrderRequest ``` Redirection rewires the projected relationship to the corresponding projected entity. ### 10.2 Syntax Root to child: ```abap _Items : redirected to composition child ZC_SalesOrderItem ``` Child to parent: ```abap _Request : redirected to parent ZC_SalesOrderRequest ``` Ordinary association redirection, when a projected target is required, uses an appropriate redirected association form supported by the projection model. ### 10.3 What redirection does not do Redirection does not: - copy records between base and projection entities; - create child rows; - calculate target data; - map a field to a persistence column; - make a blank database relationship valid; - implement cascade deletion. The base and projection views still operate over the same underlying business data. Redirection changes the navigation contract visible from the projection. ### 10.4 Missing redirection is not universally “blank data” The actual consequence depends on the artifact and syntax. Common outcomes include activation errors, an inconsistent projected composition, navigation to an unintended base target, or missing service navigation. It is inaccurate to treat “blank data” as the universal result. Diagnose the metadata target and projected topology rather than assuming the persistence rows disappeared. --- ## 11. Projection Provider Contracts Projection views support different use cases. The provider contract makes the intended contract explicit. | Provider contract | Main purpose | | ------------------------- | ----------------------------------------------------- | | `transactional_query` | Consumer/service projection of a transactional RAP BO | | `transactional_interface` | Stable BO interface intended for reuse and release | | `analytical_query` | Analytical query projection | These contracts are not interchangeable labels. ### 11.1 Transactional query Use for a consumer-specific service projection: ```abap define root view entity ZC_SalesOrderRequest provider contract transactional_query as projection on ZI_SalesOrderRequest ``` This projection can be paired with a behavior projection and exposed through a service definition. ### 11.2 Transactional interface Use when defining a formal BO interface intended as a stable reusable contract: ```abap define root view entity ZI_SalesOrderRequestAPI provider contract transactional_interface as projection on ZI_SalesOrderRequest ``` A formal RAP BO interface also requires the corresponding behavior-interface artifacts and release decisions. Merely naming a regular base entity `ZI_...` does not make it a released BO interface. ### 11.3 Naming conventions do not establish semantics Common project naming: ```text ZI_* interface/base-style CDS entity ZC_* consumption/service projection ZR_* root or reuse-oriented entity in some projects ``` These prefixes help humans but do not control RAP. The DDL syntax, provider contract, behavior definitions, and release contract establish the technical role. --- ## 12. Field Exposure and Information Boundaries ### 12.1 Excluding internal fields The base entity may need an internal processing field: ```abap Request.internal_processing_code as InternalProcessingCode ``` The service projection can omit it: ```abap define root view entity ZC_SalesOrderRequest provider contract transactional_query as projection on ZI_SalesOrderRequest { key RequestUUID, RequestNumber, SoldToParty, Status, TotalAmount, TransactionCurrency } ``` Omission reduces the field surface of this projection. It does not by itself establish the entire security model. DCL, modification authorization, released API boundaries, and service configuration must also be designed correctly. ### 12.2 Projection as consumer contract Create separate projections when consumers require genuinely different contracts: ```text Processor UI projection editable business fields, internal workflow status, processor actions Requester UI projection requester-visible fields and requester actions Integration API projection stable machine contract, API-safe navigation, no UI-only design ``` Avoid creating projections that differ only cosmetically if one stable contract and metadata extension would be sufficient. Every public contract creates lifecycle and compatibility responsibilities. ### 12.3 Do not put business invariants in the projection A projection can omit a field or operation, but another EML consumer or projection might still reach the base BO. Therefore rules such as these belong to base behavior: - submitted request must contain at least one valid item; - item product must exist; - requested quantity must be positive; - total amount must equal the sum of item amounts; - status transition must follow the permitted state machine. Projection is exposure. Behavior is enforcement. --- ## 13. Entered, Derived, and Technical Fields Classify every element before implementing the model: | Classification | Example | Source of truth | Typical behavior | | ----------------- | -------------------- | ----------------------- | ----------------------------------- | | Entered | `SoldToParty` | Consumer input | Editable, validated | | Entered | `RequestedQuantity` | Consumer input | Mandatory on create, validated | | Derived | `UnitPrice` | Pricing/reference logic | Read-only, determined | | Derived | `NetAmount` | Quantity × price logic | Read-only, determined | | Aggregate-derived | `TotalAmount` | Sum of item amounts | Read-only, determined from children | | Lifecycle | `Status` | BO state machine | Changed by controlled action | | Technical | `RequestUUID` | Numbering/framework | Read-only, generated | | Administrative | `LocalLastChangedAt` | RAP runtime | Read-only, ETag candidate | The CDS model exposes the typed fields. The behavior definition and behavior pool turn this classification into executable controls. Incorrect pseudo-syntax: ```abap TotalAmount [derived] UnitPrice [entered] ``` RAP does not use these brackets. A real implementation combines: ```text CDS element + behavior field control + determination/validation/action + UI metadata where useful ``` --- ## 14. Access Control Boundary ### 14.1 Authorization-check annotation ```abap @AccessControl.authorizationCheck: #CHECK ``` This annotation tells CDS access control how access to the entity should be handled. A DCL role can restrict result rows when that entity is accessed as the authorization-relevant entity. It is not equivalent to RAP modification authorization. ```text CDS DCL Which rows can the user read through this CDS access? RAP authorization control May the user create, update, delete, or execute this operation? ``` ### 14.2 Access control is evaluated at the accessed entity Do not assume a lower CDS entity's DCL is automatically inherited through every higher-level CDS entity. Define and test authorization at the actual consumption entity and service boundary. ### 14.3 Association exposure and data exposure Publishing `_Customer` allows consumers to request navigation if the service exposes a reachable target. It is therefore part of the information surface. Review associations with the same care as scalar fields. --- ## 15. Query Semantics and Performance ### 15.1 Association-on-demand does not remove SQL cost ```text Association only exposed no target join required until consumer uses navigation/path Target field selected through path database join is generated ``` Evaluate the generated query when a projection contains: - multiple to-many paths; - calculated elements over joined data; - filters on associated entities; - large text/value-help targets; - nested expansions from OData; - associations whose declared cardinality does not match data. ### 15.2 To-many joins can change result grain Suppose one item has two schedule lines: ```text Item 10 NetAmount 100 Schedule 1 Schedule 2 ``` Joining item to schedule-line grain yields two rows containing the same item amount. A naïve sum returns 200 instead of 100. The problem is not fixed by declaring the item key in CDS. The query must aggregate at the correct grain or separate item and schedule-line measures. ### 15.3 Prefer explicit grain For each entity, document: ```text One row represents: one Sales Order Request item Key: ItemUUID Parent identity: RequestUUID Expected association multiplicity: one Product, many Schedules ``` Most CDS duplication defects are grain defects disguised as join defects. ### 15.4 Measure before denormalizing Do not copy Customer or Product master fields into the transactional CDS model solely to avoid associations. Copy data only when the transaction must preserve a historical snapshot or the domain explicitly owns that value. Otherwise use released associations and diagnose the actual SQL plan before denormalizing. --- ## 16. Clean-Core and Released-Source Design In ABAP Cloud, use released CDS entities, released RAP BO interfaces, and other released APIs as dependencies. A technically reachable classic table or class is not automatically an allowed clean-core dependency. ```text Custom RAP BO ├── own persistence tables ├── released Customer/Product reference CDS entities ├── released conversion or business APIs └── explicit projection and release contract ``` For an SD-inspired portfolio model, distinguish clearly between: - a custom training object that resembles a Sales Order Request; - a projection over released SAP business data; - a released transactional SAP BO interface used through EML; - direct access to classic SD persistence such as `VBAK` or `VBAP`. These are different architectures. Do not present a custom RAP aggregate as an extension of the standard SAP Sales Order unless the target system and released extension contracts actually support that design. --- ## 17. Activation and Dependency Order A practical bottom-up activation sequence is: ```text 1. Data elements/domains and database tables 2. Independent reference CDS entities 3. Child base CDS entities where dependencies allow 4. Root base CDS and completed composition topology 5. Base behavior definition and behavior pool 6. Child projection views 7. Root projection and redirections 8. Behavior projection 9. Metadata extension 10. Service definition and service binding ``` Circular root/child CDS dependencies are handled by the ADT activation process and the repository object's supported creation flow. Activate related objects together when necessary. Activation: - performs syntax and dependency checks; - creates an active repository version; - does not publish an OData endpoint; - does not transport the artifact to another system; - does not deploy a separate Fiori application. --- ## 18. Technical Diagnostics ### 18.1 Field is missing from OData metadata Trace from the service inward: ```text Service Definition Is the intended projection entity exposed? │ ▼ CDS Projection Is the field in the projection list? │ ▼ Base CDS Does the field exist and activate with the expected type? │ ▼ Service Binding Is the correct active service version published? ``` If the field exists in the base entity but not the projection, omission is working as designed. ### 18.2 Navigation target is incorrect or absent Check: 1. root composition exists and is exposed in the base entity; 2. child contains the correct `association to parent`; 3. projection root redirects to the projected composition child; 4. projection child redirects to the projected parent; 5. both projected nodes are exposed where the service requires them; 6. service metadata points to the projected entity set; 7. `ON` conditions use the correct projected keys. Do not begin by inspecting database rows if the navigation is absent from `$metadata`; that is first a modeling or exposure defect. ### 18.3 Duplicate root or item rows Check: 1. the declared row grain; 2. key uniqueness in the actual query result; 3. to-many associations consumed as path fields; 4. joins missing part of their conditions; 5. incorrect cardinality declarations; 6. language-dependent text joins without a language condition; 7. aggregation after a one-to-many expansion. ### 18.4 Association returns no target Check: ```text Source foreign-key value → target key format and conversion → complete ON condition → client/language/context fields → target data exists → DCL visibility → service target exposure ``` An empty association target is not automatically a redirection problem. ### 18.5 Amount displays incorrectly Verify: 1. amount field type and decimal definition; 2. currency element type; 3. exact annotation element name and case; 4. both fields are projected; 5. metadata contains the semantic dependency; 6. stored currency/value pair is internally consistent; 7. no missing currency conversion is being mistaken for formatting. ### 18.6 Consumer can edit a derived field The fix is not a CDS marker. Check the base behavior field control and behavior projection, then verify the service metadata. Keep the derivation in one backend behavior path so UI, API, and EML consumers observe the same result. --- ## 19. Common Modeling Errors ### 19.1 Defining the child as another root Incorrect: ```abap define root view entity ZI_SalesOrderItem ... ``` Use a non-root view entity with `association to parent` when Item is owned by the Sales Order Request aggregate. ### 19.2 Using singular composition cardinality for a collection Incorrect for a normal order: ```abap composition [0..1] of ZI_SalesOrderItem as _Items ``` Use `[0..*]` when the root may contain multiple items. ### 19.3 Exposing an association name that was never defined Incorrect: ```abap _SalesOrderRequest, _Product ``` when the definitions use `_Request` and contain no `_Product` association. Association aliases must be consistent across the definition, select list, behavior model, projection, and code. ### 19.4 Repeating scalar fields Incorrect: ```abap Request.status as Status, Status, ``` The first line already defines the projected element. A duplicate element name causes an activation problem. ### 19.5 Referencing persistence aliases inside a projection Incorrect: ```abap define root view entity ZC_SalesOrderRequest as projection on ZI_SalesOrderRequest { Request.request_uuid as RequestUUID } ``` The projection source is `ZI_SalesOrderRequest`, so project its element names: ```abap { key RequestUUID, RequestNumber } ``` ### 19.6 Treating semantic annotations as calculations `@Semantics.amount.currencyCode` does not calculate an amount. Declare a RAP determination or use another appropriate calculation source. ### 19.7 Assuming a value help enforces the invariant A consumer can bypass the UI. Preserve the value help for usability and enforce the rule through backend validation. ### 19.8 Treating projection omission as complete security Omitting a field narrows one contract. It does not replace DCL, RAP authorization, released-object governance, or secure service design. ### 19.9 Treating cardinality as observed row count Cardinality is a statement of the expected relationship, not a live counter. Test the data and `ON` condition before relying on it. ### 19.10 Treating names as framework configuration `ZI_`, `ZC_`, `_Items`, and `_Customer` communicate intent but do not activate RAP features. Keywords, provider contracts, behavior definitions, and service artifacts provide the executable contract. --- ## 20. Design Review Checklist ### Base model - Each entity has a documented row grain. - CDS keys match the actual result uniqueness. - Technical column aliases express stable business meaning. - The root represents the aggregate consistency boundary. - Owned children use composition. - Each composition child has the correct association to parent. - Independent master/reference objects use ordinary associations. - Association `ON` conditions include the complete identity. - Cardinalities describe real data expectations. - Amount/currency and quantity/unit pairs are modeled together. - Technical and administrative fields are available where behavior needs them. ### Projection model - Provider contract is explicit. - Only consumer-relevant fields and associations are exposed. - Keys required for identity remain projected. - Root/child associations are redirected to projected nodes. - Internal fields are omitted unless the consumer genuinely needs them. - The projection does not attempt to enforce base business invariants. - A separate projection exists only when it represents a real contract. ### Runtime and operations - DCL is defined and tested at the actual accessed entity. - Behavior field control protects derived and technical fields. - Backend validation protects reference integrity and state-dependent rules. - To-many navigation does not silently change the result grain. - Generated SQL and OData expansions are measured for important access paths. - Dependencies use released APIs when ABAP Cloud or clean-core rules require it. --- ## 21. Compact Model Map ```text PERSISTENCE zsor_request zsor_item request_uuid item_uuid request_number request_uuid sold_to_party product status requested_quantity total_amount unit_price currency net_amount │ │ ▼ ▼ BASE CDS BUSINESS OBJECT ZI_SalesOrderRequest ZI_SalesOrderItem root child key RequestUUID key ItemUUID composition _Items ───────────────────> association to parent _Request association _Customer association _Product TotalAmount + Currency Quantity + Unit NetAmount + Currency │ │ ▼ ▼ CONSUMER PROJECTION ZC_SalesOrderRequest ZC_SalesOrderItem transactional_query transactional_query selected fields selected fields _Items redirected ───────────────────> projected child <──────────────── _Request redirected │ ▼ BEHAVIOR PROJECTION + SERVICE EXPOSURE ``` The model should be read as three separate decisions: ```text Composition decides ownership. Association decides navigation to an independent entity. Projection decides which part of the reusable model a consumer receives. ``` 47:T8df,SAP RAP CDS Data Modeling and Projection Design — Technical Reference This document explains how ABAP CDS defines the structural and semantic model of a RAP business object and how CDS projection views adapt that model for a specific consumer. It focuses on entity boundaries, keys, compositions, associations, cardinality, semantic annotations, projection contracts, and navigation topology. The central design principle is: The base CDS model describes the reusable business object and its relationships. A CDS projection selects and adapts that model for one consumption scenario. Neither layer replaces the behavior definition, which owns the transactional capabilities and business rules. Primary SAP sources: - SAP Help — Defining the Data Model in CDS Views - SAP Help — CDS View Entities - SAP Help — Associations - SAP Help — Projection Views - SAP Help — Creating CDS View Entities for RAP - SAP Help — CDS Annotations for RAP --- 1. Position of CDS in RAP text Database tables or released data sources │ ▼ Base CDS view entities fields, keys, aliases, compositions, associations, semantics │ ├──────── Base Behavior Definition │ operations and transactional contract │ ▼ CDS projection views consumer-specific field and navigation shape │ ├──────── Behavior Projection │ consumer-visible operations │ ├──────── Metadata Extension │ presentation metadata │ ▼ Service Definition and Service Binding CDS is responsible for the data model. It can express: - entity elements and their ABAP Dictionary types; - semantic keys exposed by the entity; - aliases that give technical columns business-oriented names; - calculations supported by the CDS language; - root, child, and reference relationships; - semantic dependencies such as amount/currency and quantity/unit; - reusable navigation paths; - annotations consumed by the ABAP runtime and other frameworks. CDS does not by itself implement: - create, update, or delete behavior; - validations, determinations, actions, or feature control; - transactional buffering and save handling; - a custom authorization decision for a modification; - an OData endpoint. Those responsibilities belong to other RAP artifacts. --- 2.48:Tbd2,# SAP RAP CDS Data Modeling and Projection Design — Technical Reference This document explains how ABAP CDS defines the structural and semantic model of a RAP business object and how CDS projection views adapt that model for a specific consumer. It focuses on entity boundaries, keys, compositions, associations, cardinality, semantic annotations, projection contracts, and navigation topology. The central design principle is: > The base CDS model describes the reusable business object and its > relationships. A CDS projection selects and adapts that model for one > consumption scenario. Neither layer replaces the behavior definition, which > owns the transactional capabilities and business rules. Primary SAP sources: - [SAP Help — Defining the Data Model in CDS Views](https://help.sap.com/docs/abap-cloud/abap-rap/defining-data-model-in-cds-views) - [SAP Help — CDS View Entities](https://help.sap.com/docs/abap-cloud/abap-data-models/cds-view-entities-8b3e8e8b8797432abecd7d1fbb6d5c12) - [SAP Help — Associations](https://help.sap.com/docs/abap-cloud/abap-data-models/cds-associations) - [SAP Help — Projection Views](https://help.sap.com/docs/abap-cloud/abap-data-models/cds-projection-views) - [SAP Help — Creating CDS View Entities for RAP](https://help.sap.com/docs/abap-cloud/abap-rap/creating-cds-view-entities) - [SAP Help — CDS Annotations for RAP](https://help.sap.com/docs/abap-cloud/abap-rap/cds-annotations) --- ## 1. Position of CDS in RAP ```text Database tables or released data sources │ ▼ Base CDS view entities fields, keys, aliases, compositions, associations, semantics │ ├──────── Base Behavior Definition │ operations and transactional contract │ ▼ CDS projection views consumer-specific field and navigation shape │ ├──────── Behavior Projection │ consumer-visible operations │ ├──────── Metadata Extension │ presentation metadata │ ▼ Service Definition and Service Binding ``` CDS is responsible for the data model. It can express: - entity elements and their ABAP Dictionary types; - semantic keys exposed by the entity; - aliases that give technical columns business-oriented names; - calculations supported by the CDS language; - root, child, and reference relationships; - semantic dependencies such as amount/currency and quantity/unit; - reusable navigation paths; - annotations consumed by the ABAP runtime and other frameworks. CDS does not by itself implement: - create, update, or delete behavior; - validations, determinations, actions, or feature control; - transactional buffering and save handling; - a custom authorization decision for a modification; - an OData endpoint.49:Ta9fa, # SAP RAP Behavior Modeling and Implementation — Technical Reference This document explains how a RAP business object becomes transactional. It covers the base behavior definition, behavior projection, managed and unmanaged implementation choices, behavior pools, standard operations, field control, determinations, validations, actions, prechecks, feature control, EML, and RAP response structures. The central implementation principle is: > The behavior definition declares what the business object can do. The RAP > runtime enforces the declared contract and supplies framework behavior. The > behavior pool implements only the application-specific logic required by > that contract. The behavior projection selects which capabilities a consumer > may use. Primary SAP sources: - [SAP Help — Defining Standard Behavior](https://help.sap.com/docs/abap-cloud/abap-rap/defining-standard-behavior) - [SAP Help — Implementing Behavior](https://help.sap.com/docs/abap-cloud/abap-rap/implementing-behavior-of-business-object) - [SAP Help — Projecting Behavior](https://help.sap.com/docs/abap-cloud/abap-rap/projecting-behavior) - [SAP Help — Determinations](https://help.sap.com/docs/abap-cloud/abap-rap/determinations) - [SAP Help — Validation Implementation](https://help.sap.com/docs/abap-cloud/abap-rap/validation-implementation) - [SAP Help — Action Runtime](https://help.sap.com/docs/abap-cloud/abap-rap/action-runtime) - [SAP Help — Feature Control](https://help.sap.com/docs/abap-cloud/abap-rap/implementation-contract-feature-control) --- ## 1. Position of Behavior in RAP ```text CDS data model entities, fields, composition tree, associations │ ▼ Base Behavior Definition transactional capabilities and implementation contract │ ├──────── RAP managed runtime │ generic CRUD, buffer, mapping, │ locking and ETag support │ └──────── Behavior Pool custom rules and operations │ ▼ Behavior Projection capabilities exposed for one consumer │ ▼ OData service or EML consumer ``` The behavior definition, often abbreviated as BDEF, is attached to the CDS business-object model. It declares: - managed, unmanaged, projection, or interface behavior; - standard create, update, and delete operations; - create-by-association for child nodes; - persistence tables and field mappings; - locks and ETags; - static and dynamic field characteristics; - determinations and validations; - actions and functions; - authorization and feature-control hooks; - draft behavior where applicable. The BDEF contains declarations, not the ABAP implementation of custom business logic. --- ## 2. Base Behavior Definition Versus Behavior Projection ### 2.1 Base behavior definition The base BDEF defines the reusable transactional contract: ```abap managed implementation in class zbp_i_salesorderrequest unique; strict ( 2 ); define behavior for ZI_SalesOrderRequest alias SalesOrderRequest persistent table zsor_request lock master authorization master ( instance ) etag master LocalLastChangedAt { create; update; delete; association _Items { create; } field ( numbering : managed, readonly ) RequestUUID; field ( readonly ) RequestNumber, Status, TotalAmount, LocalLastChangedAt; field ( mandatory : create ) SoldToParty; determination DeriveAmounts on modify { create; field TransactionCurrency; } validation ValidateCustomer on save { create; field SoldToParty; } action ( features : instance ) Submit result [1] $self; mapping for zsor_request { RequestUUID = request_uuid; RequestNumber = request_number; SoldToParty = sold_to_party; Status = status; TotalAmount = total_amount; TransactionCurrency = transaction_currency; LocalLastChangedAt = local_last_changed_at; } } define behavior for ZI_SalesOrderItem alias SalesOrderItem persistent table zsor_item lock dependent by _Request authorization dependent by _Request etag master LocalLastChangedAt { update; delete; field ( numbering : managed, readonly ) ItemUUID; field ( readonly ) RequestUUID, UnitPrice, NetAmount, TransactionCurrency, LocalLastChangedAt; field ( mandatory : create ) Product, RequestedQuantity; determination DeriveItemAmount on modify { create; field RequestedQuantity, UnitPrice; } validation ValidateProduct on save { create; field Product; } validation ValidateQuantity on save { create; field RequestedQuantity; } association _Request; association _Product; mapping for zsor_item { ItemUUID = item_uuid; RequestUUID = request_uuid; Product = product; RequestedQuantity = requested_quantity; QuantityUnit = quantity_unit; UnitPrice = unit_price; NetAmount = net_amount; TransactionCurrency = transaction_currency; LocalLastChangedAt = local_last_changed_at; } } ``` ### 2.2 Behavior projection The behavior projection selects capabilities from the underlying BO for one consumption contract: ```abap projection; strict ( 2 ); define behavior for ZC_SalesOrderRequest alias SalesOrderRequest use etag { use create; use update; use delete; use action Submit; use association _Items { create; } } define behavior for ZC_SalesOrderItem alias SalesOrderItem use etag { use update; use delete; use association _Request; use association _Product; } ``` The projection does not contain the implementation of `Submit`, a validation, or a determination. It can only expose behavior supported by the underlying contract. ### 2.3 Responsibility boundary | Artifact | Technical responsibility | | ------------------- | -------------------------------------- | | Base CDS | Entity data model and relationships | | Base BDEF | Reusable transactional contract | | Behavior pool | Custom ABAP implementation | | CDS projection | Consumer-visible fields and navigation | | Behavior projection | Consumer-visible operations | | Metadata extension | UI presentation and action placement | A field being present in a CDS projection does not make it editable. Editability is governed by behavior field control and the exposed operation contract. --- ## 3. Behavior Entity Aliases ```abap define behavior for ZI_SalesOrderRequest alias SalesOrderRequest ``` `SalesOrderRequest` is the BDEF entity alias. EML uses it to identify a node inside the business object: ```abap READ ENTITIES OF ZI_SalesOrderRequest IN LOCAL MODE ENTITY SalesOrderRequest ... ``` The alias is not random at the call site. `ENTITY UpdateRequest` is valid only if `UpdateRequest` is the declared alias of a BO entity in that behavior contract. One CDS entity belongs to one base behavior contract. Defining the same CDS entity twice with aliases such as `Travel` and `UpdateTravel` does not create two independent behavior modes. Different business operations are declared as operations or actions on the one entity behavior: ```abap define behavior for ZI_Travel alias Travel { update; action AcceptTravel result [1] $self; action RejectTravel result [1] $self; } ``` --- ## 4. Managed and Unmanaged Implementation ### 4.1 Managed behavior Managed RAP supplies generic transactional processing for standard operations. Depending on the model and declarations, the framework handles: - standard create, update, and delete; - create-by-association; - transactional buffering; - persistence mapping; - managed UUID numbering; - lock handling; - ETag handling; - orchestration of determinations, validations, and save processing. The developer still owns: - the CDS and behavior model; - field control; - validations and determinations; - actions and functions; - authorization and feature control; - business messages; - integration with other BOs or released APIs; - tests and operational diagnostics. Managed does not mean “no ABAP.” It means the framework owns generic CRUD and transaction mechanics while application code owns business-specific behavior. ### 4.2 Unmanaged behavior Unmanaged RAP is appropriate when the application must control the operational implementation, commonly because it: - reuses an existing transactional API or legacy business object; - has persistence that does not fit managed table handling; - requires custom buffering or locking; - maps operations to BAPIs, function modules, or other released capabilities; - has an established save protocol that RAP must wrap. The developer implements operation handlers such as create, update, delete, read-by-association, create-by-association, and locking as required by the contract. Unmanaged does not mean direct SQL is automatically appropriate. The wrapped application contract, released APIs, LUW rules, and clean-core restrictions still apply. ### 4.3 Additional save Managed with additional save keeps managed interaction and persistence while allowing controlled save-phase additions such as writing an audit record or outbox entry. It is not a reason to duplicate ordinary managed table updates. Detailed save-sequence and additional-save design belongs to the transaction and draft reference. ### 4.4 Selection guide ```text New custom persistence with standard CRUD → managed Existing released transactional API owns the real operation → unmanaged wrapper or façade Managed persistence plus controlled post-save integration record → managed with additional save, where supported and appropriate ``` Choose by ownership of transaction mechanics, not by which syntax appears shorter. --- ## 5. Strict Mode ```abap strict ( 2 ); ``` Strict mode applies the current RAP contract rules and syntax restrictions to the behavior definition and its implementation. It improves consistency and helps prevent reliance on obsolete or ambiguous behavior patterns. Strict mode does not provide: - CRUD; - validation; - determination; - authorization; - locking; - persistence; - business correctness. Those features still require the corresponding implementation type and declarations. Use the strongest strict mode supported by the target ABAP release and keep the behavior artifacts internally consistent. --- ## 6. Standard Operations and Child Creation ### 6.1 Root operations ```abap create; update; delete; ``` These lines add standard operations to the BO contract. In a managed BO, the framework can implement their generic persistence behavior. ### 6.2 Create-by-association A composition child is created through its parent relationship: ```abap define behavior for ZI_SalesOrderRequest alias SalesOrderRequest { association _Items { create; } } ``` The child behavior normally does not declare standalone `create`: ```abap define behavior for ZI_SalesOrderItem alias SalesOrderItem { update; delete; association _Request; } ``` This preserves aggregate ownership: ```text Create Request root create Create Item for Request create by association through SalesOrderRequest._Items Create Item with no Request not part of the BO contract ``` ### 6.3 Operation declaration is not consumer exposure An operation must pass through both layers: ```text Base BDEF declares update │ ▼ Behavior Projection uses update │ ▼ Consumer sees update capability ``` If the base BDEF supports `delete` but the behavior projection omits `use delete`, that service consumer cannot request delete through that projection. --- ## 7. Persistence and Mapping ### 7.1 Persistent table ```abap define behavior for ZI_SalesOrderItem alias SalesOrderItem persistent table zsor_item ``` The persistent-table declaration connects a managed entity to durable storage. It does not mean every CDS element is automatically writable. Field control, mapping, and framework-managed fields still apply. ### 7.2 Mapping block ```abap mapping for zsor_item { ItemUUID = item_uuid; RequestUUID = request_uuid; Product = product; RequestedQuantity = requested_quantity; QuantityUnit = quantity_unit; UnitPrice = unit_price; NetAmount = net_amount; TransactionCurrency = transaction_currency; } ``` The left side is the CDS element. The right side is the persistence field. This mapping is unrelated to EML `MAPPED` output: ```text BDEF mapping for table CDS field name ↔ persistence column name EML MAPPED response client correlation ID ↔ generated/final entity key ``` ### 7.3 Read-only and generated fields Technical UUID: ```abap field ( numbering : managed, readonly ) ItemUUID; ``` Managed early numbering assigns the key during the create interaction so the new instance can be addressed immediately. A `RAW(16)` UUID is a common key type for this pattern. Read-only means the external consumer cannot change the field. The framework or behavior implementation may still set it through its defined internal mechanism. --- ## 8. Field Characteristics ### 8.1 Read-only ```abap field ( readonly ) RequestNumber, TotalAmount, LocalLastChangedAt; ``` Use read-only for fields whose source of truth is the framework or backend logic. Examples include technical keys, administrative timestamps, calculated amounts, and controlled status fields. ### 8.2 Mandatory on create ```abap field ( mandatory : create ) SoldToParty, TransactionCurrency; ``` This describes a structural create requirement to RAP consumers. It is not a substitute for semantic validation. ```text mandatory : create field must be supplied as part of creation contract validation supplied value must satisfy a business invariant ``` For example, `SoldToParty` can be supplied but reference a nonexistent or blocked Customer. Backend validation must still reject that state. ### 8.3 Dynamic field control Field mutability can depend on instance state: ```abap field ( features : instance ) SoldToParty, TransactionCurrency; ``` The behavior pool returns permission markers from an instance-feature method. A submitted request can make commercial fields read-only while a draft request keeps them editable. Dynamic field control represents availability, not authorization. If the rule depends on user identity or permission, implement authorization control. --- ## 9. Behavior Pool Architecture ### 9.1 Global container and local classes A behavior pool is a special global ABAP class declared for the behavior of a root CDS entity. Its relevant implementation normally resides in local classes: ```abap CLASS lhc_SalesOrderRequest DEFINITION INHERITING FROM cl_abap_behavior_handler. PRIVATE SECTION. METHODS DeriveAmounts FOR DETERMINE ON MODIFY IMPORTING keys FOR SalesOrderRequest~DeriveAmounts. METHODS ValidateCustomer FOR VALIDATE ON SAVE IMPORTING keys FOR SalesOrderRequest~ValidateCustomer. METHODS Submit FOR MODIFY IMPORTING keys FOR ACTION SalesOrderRequest~Submit RESULT result. METHODS GetInstanceFeatures FOR INSTANCE FEATURES IMPORTING keys REQUEST requested_features FOR SalesOrderRequest RESULT result. ENDCLASS. ``` Handler classes inherit from `CL_ABAP_BEHAVIOR_HANDLER`. Saver classes inherit from the appropriate RAP saver base class when the implementation type requires save callbacks. ### 9.2 Framework invocation The application does not instantiate `lhc_SalesOrderRequest` directly. RAP generates and invokes the handler signatures from BDEF declarations. ```text BDEF action Submit │ ▼ generates contract METHODS Submit FOR MODIFY ... │ ▼ runtime dispatch RAP calls handler when consumer invokes action ``` ### 9.3 Do not keep transaction state in handler instance attributes Handler and saver instances can be reinstantiated during nested calls. Do not assume an instance attribute written by one method will remain available to a later method. Use: - RAP transactional state; - EML reads and modifications; - method-local data; - defined saver mechanisms; - dedicated stable helper abstractions where appropriate. Do not use behavior-handler instance memory as an undocumented transaction buffer. ### 9.4 Keep orchestration separate from domain calculation A strong behavior method has two layers: ```text RAP adapter layer read keys and BO state call domain calculation write changes through EML map failures and messages Domain helper calculate amount evaluate status transition validate date interval ``` Pure calculations are easier to unit-test when separated from EML orchestration. --- ## 10. Determinations ### 10.1 Purpose A determination automatically modifies BO state when declared trigger conditions occur. ```abap determination DeriveItemAmount on modify { create; field RequestedQuantity, UnitPrice; } ``` Typical uses: - calculate `NetAmount` after quantity or price changes; - copy root currency to a newly created child; - derive a default status; - update a root aggregate from child data. A determination is not a guard. It changes or derives state. ### 10.2 Runtime requirements Determinations must be designed for RAP runtime semantics: - execution order between separate determinations is not fixed; - each determination must work independently; - repeated execution under the same state must give the same result; - trigger fields must include every input that can change the calculation; - logic must work for active and draft keys when the BO supports both; - a determination does not have a `FAILED` response like a validation. Avoid two determinations that silently depend on one another: ```text Determination A calculates Item.NetAmount Determination B assumes A already ran and calculates Request.TotalAmount ``` Because ordering is not guaranteed, either make B read a state that is always valid or centralize the dependent derivation in one orchestrated calculation. ### 10.3 Business flow for item amount derivation ```text 1. Consumer changes quantity or unit price. 2. RAP places the change in the transactional buffer. 3. Trigger condition invokes DeriveItemAmount. 4. Handler reads current item state from the buffer. 5. Domain logic calculates quantity × price. 6. Handler updates NetAmount in local mode. 7. Consumer receives or rereads the derived value. 8. Save validation later decides whether the complete BO is valid. ``` ### 10.4 Representative implementation ```abap METHOD DeriveItemAmount. READ ENTITIES OF ZI_SalesOrderRequest IN LOCAL MODE ENTITY SalesOrderItem FIELDS ( RequestedQuantity UnitPrice ) WITH CORRESPONDING #( keys ) RESULT DATA(items). MODIFY ENTITIES OF ZI_SalesOrderRequest IN LOCAL MODE ENTITY SalesOrderItem UPDATE FIELDS ( NetAmount ) WITH VALUE #( FOR item IN items ( %tky = item-%tky NetAmount = item-RequestedQuantity * item-UnitPrice ) ) REPORTED DATA(update_reported). reported = CORRESPONDING #( DEEP update_reported ). ENDMETHOD. ``` Code-to-business mapping: | Code | Business meaning | | ---------------------------------- | ------------------------------------------------------------------ | | `READ ENTITIES ... IN LOCAL MODE` | Read the current item values within this BO transaction | | `FIELDS (...)` | Fetch only calculation inputs | | `WITH CORRESPONDING #( keys )` | Convert the trigger-key table into the typed EML request shape | | `RESULT DATA(items)` | Hold current buffered item state | | `UPDATE FIELDS ( NetAmount )` | Restrict the internal modification to the derived field | | `VALUE #( FOR item IN items ... )` | Construct one update row per item explicitly | | `%tky = item-%tky` | Preserve the exact transactional identity, including draft context | | `REPORTED` | Preserve messages returned by nested EML processing | `WITH VALUE #( ... )` is used because the update payload must be constructed: it contains transactional identity plus a newly calculated value. ### 10.5 Why `ENTITIES OF` names the root ```abap MODIFY ENTITIES OF ZI_SalesOrderRequest ENTITY SalesOrderItem ``` `ZI_SalesOrderRequest` identifies the business-object behavior contract. `SalesOrderItem` identifies one entity alias inside that BO. This is correct even though the operation changes an item rather than the root. --- ## 11. Validations ### 11.1 Purpose A validation checks the BO state and rejects invalid instances during save processing. ```abap validation ValidateCustomer on save { create; field SoldToParty; } ``` Typical invariants: - Customer or Product reference must exist; - quantity must be positive; - requested date must be permitted; - submitted request must contain at least one valid item; - status transition must not violate the lifecycle; - item and root currencies must be consistent. ### 11.2 Determination versus validation ```text Determination derives or changes BO state result: modified buffer and optional messages Validation evaluates whether BO state is acceptable result: pass, or FAILED plus REPORTED messages ``` Do not use a determination merely to reject an invalid value. Do not use a validation to calculate a field that must remain derived throughout editing. ### 11.3 Validation business flow ```text 1. Consumer requests save. 2. RAP invokes validations whose triggers apply. 3. Handler reads current BO state through local EML. 4. Handler obtains trusted reference data if required. 5. Each invalid instance is appended to FAILED. 6. A consumer-facing message is appended to REPORTED. 7. RAP rejects the affected save and retains or rolls back state according to the transaction/draft lifecycle. ``` ### 11.4 Simplified Customer validation ```abap METHOD ValidateCustomer. READ ENTITIES OF ZI_SalesOrderRequest IN LOCAL MODE ENTITY SalesOrderRequest FIELDS ( SoldToParty ) WITH CORRESPONDING #( keys ) RESULT DATA(requests). LOOP AT requests INTO DATA(request). APPEND VALUE #( %tky = request-%tky %state_area = 'VALIDATE_CUSTOMER' ) TO reported-SalesOrderRequest. SELECT SINGLE FROM ZI_CustomerReference FIELDS CustomerID WHERE CustomerID = @request-SoldToParty INTO @DATA(customer_id). IF request-SoldToParty IS INITIAL OR customer_id IS INITIAL. APPEND VALUE #( %tky = request-%tky ) TO failed-SalesOrderRequest. APPEND VALUE #( %tky = request-%tky %state_area = 'VALIDATE_CUSTOMER' %msg = NEW zcm_salesorderrequest( severity = if_abap_behv_message=>severity-error textid = zcm_salesorderrequest=>customer_unknown customerid = request-SoldToParty ) %element-SoldToParty = if_abap_behv=>mk-on ) TO reported-SalesOrderRequest. ENDIF. ENDLOOP. ENDMETHOD. ``` For many instances, collect distinct non-initial Customer IDs and issue one set-oriented read instead of `SELECT SINGLE` inside the loop. The simplified version exposes the control flow; the production version should avoid N+1 database access. ### 11.5 Meaning of response components ```text failed-SalesOrderRequest marks the exact instances whose operation must fail reported-SalesOrderRequest carries state messages and field markers for the consumer ``` Appending only a message to `REPORTED` does not necessarily reject an operation. `FAILED` is the validation failure signal. For authorization methods, returned authorization values decide whether the operation is allowed. --- ## 12. RAP Messages ### 12.1 Message class role A behavior message class commonly: - inherits from `CX_STATIC_CHECK`; - implements `IF_ABAP_BEHV_MESSAGE`; - implements T100 message interfaces; - defines text IDs and placeholder attributes; - receives severity and business values in its constructor. Example construction: ```abap %msg = NEW zcm_salesorderrequest( severity = if_abap_behv_message=>severity-error textid = zcm_salesorderrequest=>customer_unknown customerid = request-SoldToParty ) ``` The message object converts a technical failure into a stable, localizable business message. ### 12.2 `%tky` `%tky` is the transactional key generated by the RAP type system. It identifies the exact entity instance in the current transactional context. In a draft-enabled BO, it also carries draft identity information such as `%is_draft`. Prefer `%tky` in behavior logic when matching and returning instances. A plain business key may not distinguish active from draft state. ### 12.3 `%state_area` `%state_area` groups a state message by validation or business concern: ```abap %state_area = 'VALIDATE_CUSTOMER' ``` A message row with the same `%tky` and `%state_area` but no `%msg` clears older state messages for that area before the current validation result is reported. This prevents an old “Customer unknown” error from remaining after the user corrects the Customer. ### 12.4 `%element` ```abap %element-SoldToParty = if_abap_behv=>mk-on ``` The field marker connects the message to a specific element. Metadata-driven consumers can highlight the field rather than displaying only a document-level error. ### 12.5 `%msg` `%msg` carries the RAP message object. It can be used for error, warning, information, or success messages where the contract permits. It is not limited to failed cases. --- ## 13. Actions ### 13.1 Purpose An action is a named, non-standard modifying operation that expresses business intent: ```abap action ( features : instance ) Submit result [1] $self; action ( features : instance ) Cancel result [1] $self; ``` Actions are preferable to exposing arbitrary status editing: ```text Direct Status update consumer chooses any raw value Submit action backend evaluates transition, changes status, derives dependent state, returns messages, and exposes a stable business command ``` ### 13.2 Submit workflow ```text 1. Consumer invokes Submit for selected request keys. 2. RAP dispatches to the Submit handler. 3. Handler reads current buffered request and item state. 4. Handler checks action-specific preconditions. 5. Invalid instances are returned in FAILED with REPORTED messages. 6. Valid instances are updated through EML in local mode. 7. Handler rereads the changed instances. 8. Handler builds `result` using `%tky` and `%param`. 9. RAP later runs save validations and the save sequence. ``` ### 13.3 Representative action implementation ```abap METHOD Submit. MODIFY ENTITIES OF ZI_SalesOrderRequest IN LOCAL MODE ENTITY SalesOrderRequest UPDATE FIELDS ( Status ) WITH VALUE #( FOR key IN keys ( %tky = key-%tky Status = zif_sor_status=>submitted ) ) FAILED failed REPORTED reported. READ ENTITIES OF ZI_SalesOrderRequest IN LOCAL MODE ENTITY SalesOrderRequest ALL FIELDS WITH CORRESPONDING #( keys ) RESULT DATA(requests). result = VALUE #( FOR request IN requests ( %tky = request-%tky %param = request ) ). ENDMETHOD. ``` The first EML request changes buffered state. The read retrieves the resulting representation. `%param` carries the action result declared as `$self`. ### 13.4 Why update uses `VALUE` and read uses `CORRESPONDING` ```abap WITH VALUE #( FOR key IN keys ( %tky = key-%tky Status = ... ) ) ``` The update payload contains a new value that does not already exist in `keys`, so the method constructs rows explicitly. ```abap WITH CORRESPONDING #( keys ) ``` The read request only needs matching key components already present in `keys`, so a name-based type conversion is sufficient. The choice follows the required payload, not a special update-versus-read syntax rule. --- ## 14. Prechecks and Save Validations ### 14.1 Precheck A precheck evaluates a modify request before the requested change is accepted into transactional state. It is useful when the incoming delta itself must be rejected early. Examples: - prevent an update to an immutable external reference; - reject a requested operation based on the before-image and incoming values; - avoid accepting a change that must never enter the buffer. ### 14.2 Validation on save An on-save validation evaluates the coherent BO state before persistence. It is appropriate for invariants that depend on multiple fields or child instances. Examples: - submitted request must contain at least one valid item; - begin date must not be after end date; - aggregate total must match item state; - Customer/Product references must be valid at save time. ### 14.3 Boundary ```text Precheck incoming request + relevant current state rejects before accepting the modification Validation on save resulting transactional BO state rejects before persistence ``` A precheck does not “pass data to a validation.” They are separate runtime contracts. Use each at the phase where its evidence is available. --- ## 15. Feature Control ### 15.1 Purpose Feature control determines whether fields, standard operations, associations, actions, or functions are available. It can be global or instance-specific. ```abap action ( features : instance ) Submit result [1] $self; ``` Representative implementation: ```abap METHOD GetInstanceFeatures. READ ENTITIES OF ZI_SalesOrderRequest IN LOCAL MODE ENTITY SalesOrderRequest FIELDS ( Status ) WITH CORRESPONDING #( keys ) RESULT DATA(requests). result = VALUE #( FOR request IN requests ( %tky = request-%tky %action-Submit = COND #( WHEN request-Status = zif_sor_status=>draft THEN if_abap_behv=>fc-o-enabled ELSE if_abap_behv=>fc-o-disabled ) ) ). ENDMETHOD. ``` The consumer can disable or hide Submit for an already submitted request, and the RAP runtime receives the operation permission state. ### 15.2 Feature control versus validation Feature control improves affordance and prevents unavailable operations from being offered. Validation remains necessary for save-time invariants and race-resistant backend enforcement. ### 15.3 Feature control versus authorization ```text Feature control Is Submit meaningful for this object state? Authorization Is this user permitted to Submit? ``` An action can be enabled by status and still unauthorized for the current user. Both conditions must pass. --- ## 16. EML Inside Behavior Implementations ### 16.1 Why EML is used Behavior logic should work with the current BO transaction, including unsaved changes. EML provides typed access to that state: ```abap READ ENTITIES OF ZI_SalesOrderRequest IN LOCAL MODE ... MODIFY ENTITIES OF ZI_SalesOrderRequest IN LOCAL MODE ... ``` Ordinary SQL primarily sees database persistence. It does not automatically represent the latest RAP transactional buffer state. ### 16.2 `IN LOCAL MODE` Inside the implementation of the same BO, `IN LOCAL MODE` enables internal BO orchestration and bypasses selected external controls such as authorization, feature control, and prechecks according to the EML contract. It does not mean: - a draft is created; - changes are already committed; - validations never run; - the database is updated immediately; - arbitrary data corruption is acceptable. The implementation becomes responsible for preserving the invariant while using this privileged internal path. ### 16.3 Do not issue commit in a behavior handler Behavior code participates in the RAP transaction controlled by the consumer and framework. Do not execute `COMMIT WORK` or `COMMIT ENTITIES` inside the behavior pool to finalize only part of the operation. An external EML consumer owns its transaction boundary: ```abap MODIFY ENTITIES OF ZI_SalesOrderRequest ... FAILED DATA(failed) REPORTED DATA(reported). IF failed IS INITIAL. COMMIT ENTITIES RESPONSE OF ZI_SalesOrderRequest FAILED DATA(commit_failed) REPORTED DATA(commit_reported). ENDIF. ``` --- ## 17. Typed RAP Responses ### 17.1 `MAPPED` `MAPPED` associates preliminary identities or client correlation IDs with keys assigned during create processing. Typical use: ```text Consumer sends %cid = 'REQ_1' Managed early numbering assigns RequestUUID MAPPED returns %cid ↔ RequestUUID ``` It is not a persistence field-name mapping. ### 17.2 `FAILED` `FAILED` identifies entity instances for which an operation could not be completed. Its cause may be validation, authorization, missing data, conflict, or an implementation-specific failure. ### 17.3 `REPORTED` `REPORTED` communicates messages associated with instances, state areas, or elements. A reported row can explain a failure, clear a prior state message, or provide non-error feedback. ### 17.4 Action `result` An action result is separate from the generic response structures: ```abap result = VALUE #( ( %tky = request-%tky %param = request ) ). ``` `%param` contains the result type declared by the action. With `result [1] $self`, it contains the returned entity representation. ### 17.5 Response interpretation ```text MAPPED Which generated key belongs to which create request? FAILED Which instance did not complete the operation? REPORTED What should the consumer be told about an instance or field? result What business result did the action/function return? ``` --- ## 18. Aggregate Business Logic ### 18.1 Sales Order Request invariants A coherent custom request aggregate can use these rules: ```text Request Customer must be valid before submission. Submitted request must contain at least one valid Item. TotalAmount equals the sum of Item.NetAmount. Item Product must exist. RequestedQuantity must be positive. TransactionCurrency follows the Request currency. NetAmount is derived, not entered. ``` ### 18.2 Single derivation path Keep one authoritative path for each calculated value: ```text RequestedQuantity or UnitPrice changes │ ▼ derive Item.NetAmount │ ▼ aggregate Request.TotalAmount ``` If UI code, action code, and determination code each calculate the amount, their formulas will eventually diverge. The UI should display and refresh the backend-derived result rather than become another source of truth. ### 18.3 Child deletion Deletion requires special care because fields needed for aggregation may no longer be readable after the child has been removed from the buffer. Design the trigger and key flow so the parent identity is available before or as part of the delete processing, then recompute the parent from the surviving buffered children. Avoid subtracting an assumed old amount without reliable before-image data. Re-aggregation from current authoritative state is usually safer when the aggregate size permits it. ### 18.4 UI refresh A determination updates backend transactional state. A Fiori client does not continuously reread every dependent field. Declare appropriate side effects or return/reread affected data so `NetAmount` and `TotalAmount` refresh after their inputs change. Side effects control refresh behavior; they do not perform the calculation. --- ## 19. Runtime Flow by Operation ### 19.1 Managed create ```text Consumer CREATE → projection allows create → RAP checks external contract → managed numbering assigns UUID → instance enters transactional buffer → on-modify determinations run → consumer receives interaction response and key mapping → save requested → on-save validations run → framework persists mapped fields → commit succeeds or save is rejected ``` ### 19.2 Managed update ```text Consumer UPDATE → entity and ETag identify current instance → authorization/feature/field controls apply → update enters buffer → determinations react to changed fields → save validations inspect final BO state → framework writes changed persistence state ``` ### 19.3 Action ```text Consumer invokes Submit → behavior projection exposes action → RAP checks action authorization and feature state → handler runs → handler reads/modifies through local EML → handler returns FAILED/REPORTED/result → save sequence validates and persists valid state ``` ### 19.4 Validation failure ```text Save requested → ValidateCustomer reads SoldToParty → target not found → %tky appended to FAILED → error object appended to REPORTED → field marker identifies SoldToParty → save of affected instance is rejected → consumer receives actionable business message ``` --- ## 20. Technical Diagnostics ### 20.1 Create or Edit button is missing Check in this order: ```text Base BDEF operation declaration → Behavior Projection `use` declaration → CDS projection/service exposure → active OData metadata → authorization and feature-control result → UI metadata and client cache ``` Do not add another action before proving which contract layer omitted the standard operation. ### 20.2 Determination does not run Verify: 1. determination is declared on the correct entity; 2. operation or field trigger includes the actual changed input; 3. handler signature matches the generated contract; 4. behavior pool is assigned and active; 5. modification reaches this BO rather than a different projection/interface; 6. handler reads current state with the correct `%tky`; 7. nested EML does not produce ignored `REPORTED` messages; 8. consumer refresh behavior is not hiding a successful calculation. ### 20.3 Validation does not block save Verify: 1. validation is `on save` with the correct triggers; 2. invalid entity `%tky` is appended to the correct `FAILED-<entity>` table; 3. validation reads buffered state rather than stale persistence; 4. reference query is not accidentally empty because of type conversion or access control; 5. the consumer actually requests save/activation; 6. only writing `REPORTED` was not mistaken for marking a failure. ### 20.4 Action changes status but returns old data Check that the action: 1. updates through EML; 2. preserves failures from the update; 3. rereads after the modification; 4. fills `result-%tky` and `result-%param` from the reread state; 5. does not read the database before the buffer is saved. ### 20.5 Child creation fails Check: ```text Root composition exists → Base BDEF association permits create → Behavior projection uses association create → request uses create-by-association payload → parent transactional key is valid → child mapping and numbering are correct ``` Do not add standalone child `create` to bypass aggregate ownership. ### 20.6 Derived fields are editable Check base BDEF `field ( readonly )`, dynamic field control if used, behavior projection, active metadata, and client cache. A semantic CDS annotation does not make a field read-only. ### 20.7 Duplicate or recursive determination execution Inspect trigger fields and nested local EML. A determination that updates one of its own trigger fields can retrigger itself. Make the operation idempotent, update only when the derived value actually differs, and avoid hidden ordering dependencies. --- ## 21. Implementation Review Checklist ### Behavior contract - Implementation type matches ownership of CRUD and save mechanics. - `strict ( 2 )` is used where supported. - Each CDS node has one clear BDEF alias. - Root owns create and child creation occurs by association. - Persistent tables and mappings are complete and correctly oriented. - Framework-generated and derived fields are read-only to consumers. - Structural mandatory fields are declared without replacing semantic validation. - Locks, ETags, and authorization dependencies follow aggregate ownership. ### Business logic - Determinations derive state and are idempotent. - Determination triggers cover every calculation input. - Separate determinations do not depend on execution order. - Validations append invalid instances to `FAILED`. - `REPORTED` messages identify state area and field where useful. - Actions express business intent rather than raw status editing. - Feature control depends on object state; authorization depends on user permission. - All invariants are enforced at the reusable BO layer. ### ABAP implementation - Behavior methods use EML for current transactional BO state. - Internal EML uses `IN LOCAL MODE` intentionally. - `%tky` is preserved across reads, writes, results, and messages. - Set-oriented reference reads replace database access inside large loops. - Nested EML failures and messages are propagated. - Handler attributes are not used as a persistent transaction buffer. - No commit is issued inside the behavior pool. - Pure domain calculations are separated from RAP orchestration where useful. ### Consumer contract - Behavior projection exposes only intended operations. - CDS field exposure and behavior editability are consistent. - Side effects refresh fields affected by backend derivation. - OData metadata is verified after activation and publication. - API consumers receive stable action results and actionable messages. --- ## 22. Compact Behavior Map ```text BASE BDEF SalesOrderRequest create / update / delete association _Items { create } readonly RequestUUID, TotalAmount, timestamps mandatory:create SoldToParty determination DeriveAmounts validation ValidateCustomer action Submit feature + authorization hooks │ ▼ BEHAVIOR POOL Handler methods DeriveAmounts read buffer → calculate → local EML update ValidateCustomer read buffer → check reference → FAILED/REPORTED Submit change status → reread → action result GetFeatures inspect status → enabled/disabled │ ▼ RAP TRANSACTION interaction buffer → determinations → action/standard-operation responses → on-save validations → managed/unmanaged save processing │ ▼ BEHAVIOR PROJECTION use create / update / delete use action Submit use association _Items { create } │ ▼ CONSUMER ``` The behavior layer should always be read as four separate decisions: ```text BDEF declares capability. Runtime supplies framework mechanics. Behavior pool implements business-specific logic. Behavior projection exposes selected capability. ``` 4a:T975,SAP RAP Behavior Modeling and Implementation — Technical Reference This document explains how a RAP business object becomes transactional. It covers the base behavior definition, behavior projection, managed and unmanaged implementation choices, behavior pools, standard operations, field control, determinations, validations, actions, prechecks, feature control, EML, and RAP response structures. The central implementation principle is: The behavior definition declares what the business object can do. The RAP runtime enforces the declared contract and supplies framework behavior. The behavior pool implements only the application-specific logic required by that contract. The behavior projection selects which capabilities a consumer may use. Primary SAP sources: - SAP Help — Defining Standard Behavior - SAP Help — Implementing Behavior - SAP Help — Projecting Behavior - SAP Help — Determinations - SAP Help — Validation Implementation - SAP Help — Action Runtime - SAP Help — Feature Control --- 1. Position of Behavior in RAP text CDS data model entities, fields, composition tree, associations │ ▼ Base Behavior Definition transactional capabilities and implementation contract │ ├──────── RAP managed runtime │ generic CRUD, buffer, mapping, │ locking and ETag support │ └──────── Behavior Pool custom rules and operations │ ▼ Behavior Projection capabilities exposed for one consumer │ ▼ OData service or EML consumer The behavior definition, often abbreviated as BDEF, is attached to the CDS business-object model. It declares: - managed, unmanaged, projection, or interface behavior; - standard create, update, and delete operations; - create-by-association for child nodes; - persistence tables and field mappings; - locks and ETags; - static and dynamic field characteristics; - determinations and validations; - actions and functions; - authorization and feature-control hooks; - draft behavior where applicable. The BDEF contains declarations, not the ABAP implementation of custom business logic. --- 2. Base Behavior Definition Versus Behavior Projection 2.1 Base behavior definition The base BDEF defines the reusable transactional contract: abap managed implementation in class zbpisalesorderrequest unique; strict ( 2 ); define behavior for ZISalesOrderRequest alias SalesOrderRequest persistent table zsorrequest lock master4b:Tcb5,# SAP RAP Behavior Modeling and Implementation — Technical Reference This document explains how a RAP business object becomes transactional. It covers the base behavior definition, behavior projection, managed and unmanaged implementation choices, behavior pools, standard operations, field control, determinations, validations, actions, prechecks, feature control, EML, and RAP response structures. The central implementation principle is: > The behavior definition declares what the business object can do. The RAP > runtime enforces the declared contract and supplies framework behavior. The > behavior pool implements only the application-specific logic required by > that contract. The behavior projection selects which capabilities a consumer > may use. Primary SAP sources: - [SAP Help — Defining Standard Behavior](https://help.sap.com/docs/abap-cloud/abap-rap/defining-standard-behavior) - [SAP Help — Implementing Behavior](https://help.sap.com/docs/abap-cloud/abap-rap/implementing-behavior-of-business-object) - [SAP Help — Projecting Behavior](https://help.sap.com/docs/abap-cloud/abap-rap/projecting-behavior) - [SAP Help — Determinations](https://help.sap.com/docs/abap-cloud/abap-rap/determinations) - [SAP Help — Validation Implementation](https://help.sap.com/docs/abap-cloud/abap-rap/validation-implementation) - [SAP Help — Action Runtime](https://help.sap.com/docs/abap-cloud/abap-rap/action-runtime) - [SAP Help — Feature Control](https://help.sap.com/docs/abap-cloud/abap-rap/implementation-contract-feature-control) --- ## 1. Position of Behavior in RAP ```text CDS data model entities, fields, composition tree, associations │ ▼ Base Behavior Definition transactional capabilities and implementation contract │ ├──────── RAP managed runtime │ generic CRUD, buffer, mapping, │ locking and ETag support │ └──────── Behavior Pool custom rules and operations │ ▼ Behavior Projection capabilities exposed for one consumer │ ▼ OData service or EML consumer ``` The behavior definition, often abbreviated as BDEF, is attached to the CDS business-object model. It declares: - managed, unmanaged, projection, or interface behavior; - standard create, update, and delete operations; - create-by-association for child nodes; - persistence tables and field mappings; - locks and ETags; - static and dynamic field characteristics; - determinations and validations; - actions and functions; - authorization and feature-control hooks; - draft behavior where applicable. The BDEF contains declarations, not the ABAP implementation of custom business logic. --- ## 2. Base Behavior Definition Versus Behavior Projection ### 2.1 Base behavior definition The base BDEF defines the reusable transactional contract: ```abap managed implementation in class zbp_i_salesorderrequest unique; strict ( 2 );4c:T9e36, # SAP RAP Transactions, Draft, and Concurrency — Technical Reference This document explains how RAP manages state from the first modification until database commit. It covers the interaction phase, transactional buffer, save sequence, draft persistence, draft actions, pessimistic locks, entity ETags, total ETags, early and late numbering, and transaction ownership. The central runtime principle is: > Every RAP modification first participates in a framework-controlled > transaction. The transactional buffer holds the current logical BO state; > the save sequence validates and persists that state. Draft adds a durable > editing version, but it does not replace the transactional buffer or the save > sequence used by each request. Primary SAP sources: - [SAP Help — RAP BO Runtime](https://help.sap.com/docs/abap-cloud/abap-rap/rap-bo-runtime) - [SAP Help — Save Sequence Runtime](https://help.sap.com/docs/abap-cloud/abap-rap/save-sequence-runtime) - [SAP Help — Draft Runtime](https://help.sap.com/docs/abap-cloud/abap-rap/draft-runtime) - [SAP Help — Pessimistic Concurrency Control](https://help.sap.com/docs/abap-cloud/abap-rap/pessimistic-concurrency-control-locking) - [SAP Help — Optimistic Concurrency Control](https://help.sap.com/docs/abap-cloud/abap-rap/optimistic-concurrency-control) - [SAP Help — Total ETag](https://help.sap.com/docs/ABAP_PLATFORM_NEW/fc4c71aa50014fd1b43721701471913d/f5e8548c241b43ab82bceec030b5dc9a.html) - [SAP Help — Numbering](https://help.sap.com/docs/abap-cloud/abap-rap/numbering) --- ## 1. RAP Transaction Model ### 1.1 Two runtime phases ```text INTERACTION PHASE Consumer request → authorization / feature / precheck controls → create, update, delete, or action → transactional buffer changes → on-modify determinations → interaction response save requested │ ▼ SAVE SEQUENCE FINALIZE → CHECK_BEFORE_SAVE → point of no return → ADJUST_NUMBERS when late numbering is used → SAVE / managed persistence → database commit → CLEANUP ``` The interaction phase can contain multiple operations. Those operations build one coherent logical transaction before persistence. The save sequence begins only when the consumer or service runtime closes the transaction with a save request. ### 1.2 RAP logical unit of work A RAP LUW is the framework-controlled unit in which one or more business objects participate in a transaction. Its boundary is not owned by an individual behavior method. ```text External EML consumer MODIFY ENTITIES ... MODIFY ENTITIES ... COMMIT ENTITIES OData consumer sends transactional request/batch RAP service runtime owns save and commit orchestration Behavior implementation participates in the current RAP LUW must not commit independently ``` This enables RAP to validate all participating BOs and either persist the coherent result or reject the transaction. --- ## 2. Transactional Buffer ### 2.1 Purpose The transactional buffer contains the current BO state during interaction. It includes requested changes that have not yet reached active database persistence. ```text Database before request Status = Open TotalAmount = 100 Transactional buffer after local changes Status = Submitted TotalAmount = 130 Database until successful save Status = Open TotalAmount = 100 ``` The buffer allows determinations, validations, actions, and several EML operations to work on one coherent in-progress state. ### 2.2 Buffer is not a draft ```text Transactional buffer temporary state inside the current RAP transaction required for draft and non-draft modifications discarded when its LUW ends or rolls back Draft persistence durable editable state stored in draft tables survives stateless requests and interrupted UI sessions has a managed active/draft lifecycle Active persistence committed business state stored in active tables ``` A draft request still has an interaction buffer. At the end of that request, the save sequence persists the current editable state to the draft table. Later activation uses another RAP transaction to transfer validated draft state into active persistence. ### 2.3 Read the current state with EML Behavior code normally uses local EML: ```abap READ ENTITIES OF ZI_SalesOrderRequest IN LOCAL MODE ENTITY SalesOrderRequest ALL FIELDS WITH CORRESPONDING #( keys ) RESULT DATA(requests). ``` This reads the BO state known to RAP, including unsaved modifications in the current transaction. Ordinary SQL reads database persistence. It does not automatically merge the RAP transactional buffer into the result. ### 2.4 Local mode is not a persistence mode `IN LOCAL MODE` means the BO implementation accesses its own transactional contract internally while bypassing selected external checks. It does not mean “write locally to the database,” “create a draft,” or “commit immediately.” --- ## 3. Interaction Phase ### 3.1 Managed update flow ```text 1. Consumer sends entity key, changed fields, and ETag where required. 2. RAP resolves the projection operation to the base BO. 3. Authorization, feature control, field control, and prechecks apply. 4. RAP locks the relevant lock-master instance. 5. Requested values enter the transactional buffer. 6. Triggered determinations update derived buffered values. 7. FAILED and REPORTED responses are returned for interaction failures. 8. No active database commit has occurred yet. ``` ### 3.2 Multiple modifications see one logical state ```abap MODIFY ENTITIES OF ZI_SalesOrderRequest ENTITY SalesOrderRequest UPDATE FIELDS ( TransactionCurrency ) WITH VALUE #( ( %tky = request_key TransactionCurrency = 'USD' ) ) ENTITY SalesOrderItem UPDATE FIELDS ( RequestedQuantity ) WITH VALUE #( ( %tky = item_key RequestedQuantity = 5 ) ) FAILED DATA(failed) REPORTED DATA(reported). ``` Determinations and later validations should evaluate the resulting BO state, not independently reread stale active values. ### 3.3 Interaction failure versus save failure ```text Interaction failure operation cannot enter or complete in the buffer examples: authorization denied, invalid key, failed precheck Save failure buffered state cannot be persisted coherently examples: on-save validation failed, ETag conflict, persistence error ``` Both can return typed RAP responses, but they occur at different points and have different diagnostic evidence. --- ## 4. Save Sequence ### 4.1 Overall order ```text Successful interaction modifications │ ▼ FINALIZE last permitted buffered modifications │ ▼ CHECK_BEFORE_SAVE consistency checks and managed validations │ failure ─┴─ success │ │ ▼ ▼ cleanup/failure POINT OF NO RETURN response │ ▼ ADJUST_NUMBERS if required │ ▼ SAVE / SAVE_MODIFIED │ ▼ database commit │ ▼ CLEANUP ``` The exact framework callbacks depend on managed, unmanaged, draft, additional save, and release-specific features. The conceptual boundaries remain stable. ### 4.2 `FINALIZE` `FINALIZE` is the first save-sequence step and the last point where BO data can be modified in the transactional buffer. Managed BOs perform final derivation through applicable determinations. An unmanaged saver can implement a `FINALIZE` callback. After `FINALIZE`, modifying EML is not permitted in later saver methods. Appropriate use: - final calculations requiring all transactionally involved BO state; - resolving values that can only be finalized when save begins; - cross-BO finalization designed within RAP save rules. Do not defer ordinary interactive derivations to `FINALIZE` if the consumer needs to see them while editing. ### 4.3 `CHECK_BEFORE_SAVE` This step establishes whether the complete transaction can be saved. In managed BOs, on-save validations provide the consistency checks. In unmanaged scenarios, the saver implementation supplies the corresponding check. ```text Check succeeds for every involved BO → point of no return Any involved BO returns failed instances → save sequence is rejected before persistence ``` No recoverable business validation should be postponed beyond this boundary. ### 4.4 Point of no return After all pre-save checks succeed, RAP reaches the point of no return. From this boundary onward, providers must guarantee successful completion of the save sequence. Do not place predictable business rejection logic after this point. Failures there represent technical or contract defects rather than normal user correction flow. ### 4.5 `ADJUST_NUMBERS` This phase assigns final keys when late numbering is used and maps preliminary identities to final keys. It occurs after the point of no return so gap-sensitive numbers are consumed only for a transaction already accepted for saving. ### 4.6 `SAVE` and managed persistence The save step persists buffered BO state: - managed RAP writes mapped entity state to persistent tables; - unmanaged RAP invokes provider save implementation; - managed additional save invokes the relevant additional-save contract; - multiple involved BOs must obey RAP save-order and consistency rules. The provider must not execute an independent database commit inside the saver. The RAP transaction manager owns the commit. ### 4.7 `CLEANUP` Cleanup removes provider-specific transactional buffer state and releases resources after save completion or rollback processing as defined by the implementation contract. `CLEANUP_FINALIZE` is available for cleanup when `FINALIZE` or `CHECK_BEFORE_SAVE` fails, particularly where cross-BO finalization created provider-side state that must be revoked. --- ## 5. Transaction Ownership and Commit ### 5.1 External EML consumer ```abap MODIFY ENTITIES OF ZI_SalesOrderRequest ENTITY SalesOrderRequest CREATE FIELDS ( SoldToParty TransactionCurrency ) WITH VALUE #( ( %cid = 'REQUEST_1' SoldToParty = '100000' TransactionCurrency = 'USD' ) ) MAPPED DATA(mapped) FAILED DATA(failed) REPORTED DATA(reported). IF failed IS INITIAL. COMMIT ENTITIES RESPONSE OF ZI_SalesOrderRequest FAILED DATA(commit_failed) REPORTED DATA(commit_reported). ELSE. ROLLBACK ENTITIES. ENDIF. ``` `MODIFY ENTITIES` changes RAP transactional state. `COMMIT ENTITIES` requests the save sequence and transaction completion. ### 5.2 Behavior implementation Inside a behavior handler: ```abap MODIFY ENTITIES OF ZI_SalesOrderRequest IN LOCAL MODE ... ``` The handler participates in the current consumer-owned transaction. It must not call: ```abap COMMIT WORK. COMMIT ENTITIES. ROLLBACK WORK. ``` Independent commit would split the atomic business transaction and can leave one part durable when another part fails. ### 5.3 OData service consumer The service runtime maps OData modification requests and change sets to RAP interaction and save handling. The Fiori application does not directly commit database tables. ```text Fiori Save / OData change set → RAP interaction → RAP save sequence → ABAP database transaction commit → OData response ``` --- ## 6. Draft Architecture ### 6.1 Why draft exists REST communication is stateless across requests. A user can edit an object over many interactions, navigate away, lose a frontend session, or resume from another device. A purely in-memory transaction cannot safely span that period. Draft provides a durable editing version: ```text Active tables official committed business state Draft tables persisted unfinished editing state plus draft administration RAP draft runtime controls transitions, identity, ownership, locks, ETags, and activation ``` ### 6.2 Draft table per BO entity Each draft-enabled entity in the composition tree normally has corresponding draft persistence because each node can contain editable state. ```text zsor_request ↔ zsor_request_d zsor_item ↔ zsor_item_d ``` Draft tables contain business fields, entity keys, and RAP draft administration fields, commonly through the standard draft administration include. Representative structure: ```abap define table zsor_request_d { key client : abap.clnt not null; key request_uuid : sysuuid_x16 not null; request_number : abap.char(10); sold_to_party : abap.char(10); status : abap.char(1); total_amount : abap.curr(15,2); transaction_currency : abap.cuky; local_last_changed_at: abp_locinst_lastchange_tstmpl; "%admin" : include sych_bdl_draft_admin_inc; } ``` Use the ADT quick fix/generator for a draft table instead of hand-maintaining a structure that can drift from the active entity. ### 6.3 Do not access draft tables directly Application code should not use direct SQL as the business interface to draft tables. Direct access bypasses: - active/draft identity; - draft ownership and administration; - lock and total-ETag checks; - draft action lifecycle; - behavior validations and determinations; - composition consistency; - framework evolution of draft persistence. Use EML or OData against the draft-enabled BO contract. --- ## 7. Draft-Enabled Behavior Definition ### 7.1 Base BDEF ```abap managed implementation in class zbp_i_salesorderrequest unique; strict ( 2 ); with draft; define behavior for ZI_SalesOrderRequest alias SalesOrderRequest persistent table zsor_request draft table zsor_request_d lock master total etag LastChangedAt authorization master ( instance ) etag master LocalLastChangedAt { create; update; delete; association _Items { create; with draft; } draft action Resume; draft action Edit; draft action Activate optimized; draft action Discard; draft determine action Prepare { validation ValidateCustomer; validation ValidateSubmittedRequest; validation SalesOrderItem~ValidateProduct; validation SalesOrderItem~ValidateQuantity; } field ( numbering : managed, readonly ) RequestUUID; field ( readonly ) LastChangedAt, LocalLastChangedAt; } define behavior for ZI_SalesOrderItem alias SalesOrderItem persistent table zsor_item draft table zsor_item_d lock dependent by _Request authorization dependent by _Request etag master LocalLastChangedAt { update; delete; association _Request { with draft; } association _Product; field ( numbering : managed, readonly ) ItemUUID; field ( readonly ) RequestUUID, LocalLastChangedAt; } ``` Important distinctions: - `with draft` enables draft behavior for the BO; - `draft table` declares node-specific draft persistence; - `total etag` belongs to the lock-master/root entity; - each composition path is explicitly marked `with draft` under strict mode; - `Prepare` lists checks to execute for draft preparation/activation; - ordinary reference associations such as `_Product` do not become owned draft nodes. ### 7.2 Behavior projection ```abap projection; strict ( 2 ); define behavior for ZC_SalesOrderRequest alias SalesOrderRequest use etag { use create; use update; use delete; use association _Items { create; with draft; } use action Resume; use action Edit; use action Activate; use action Discard; use action Prepare; } define behavior for ZC_SalesOrderItem alias SalesOrderItem use etag { use update; use delete; use association _Request { with draft; } use association _Product; } ``` The consumer receives draft capabilities only when the base BO and projection contracts expose them correctly. --- ## 8. Active, New-Draft, and Edit-Draft State ### 8.1 Active instance ```text Active table row exists Draft table row may or may not exist Represents current official business state ``` ### 8.2 New draft ```text Draft table row exists No corresponding active row exists Represents a new object not yet activated ``` If the new draft is discarded, no active instance remains because one never existed. ### 8.3 Edit draft ```text Active row exists Draft row exists in parallel Draft began as a copy of active state Further edits affect draft state Active remains unchanged until activation ``` The active and edit-draft instances share business identity but differ by the draft indicator and lifecycle metadata. ### 8.4 `%is_draft` RAP typed keys include draft identity: ```abap %tky business/entity key components %is_draft ``` In OData, the corresponding technical distinction is represented through `IsActiveEntity`. Preserving `%tky` in EML reads, updates, messages, and results prevents behavior logic from accidentally reading the active version while processing a draft. --- ## 9. Draft Actions ### 9.1 `Edit` Purpose: ```text Active instance → lock active aggregate → copy active aggregate state to draft persistence → return editable draft identity ``` The active instance remains. Edits are applied to the draft version. `Edit` is not a generic field update and does not activate code in the ABAP repository. ### 9.2 `Prepare` Purpose: ```text Current draft state → run listed determinations and validations → return state messages and failures → keep result as draft ``` `Prepare` checks readiness for activation. It does not by itself transfer the draft to active persistence. The `draft determine action Prepare` explicitly lists the determinations and validations that should be executed. Activation can execute Prepare processing as part of its lifecycle. ### 9.3 `Activate` Purpose: ```text Draft state → prepare/check as required → verify concurrency against active state → run active save sequence → create or update active persistence → delete draft state after success ``` For a new draft, activation creates the first active instance. For an edit draft, activation updates the corresponding active instance. If activation fails validation, the draft remains available for correction; invalid data does not become active. ### 9.4 `Discard` Purpose: ```text Edit draft delete draft version keep existing active version unchanged New draft delete draft version no active version exists ``` Discard is destructive for the unfinished draft state. It does not create a recoverable “discarded version” that `Resume` can restore. ### 9.5 `Resume` Purpose: ```text Existing draft survives after exclusive lock expires → reacquire lock on corresponding active aggregate → compare remembered total ETag with current active total ETag → continue editing if active state is still compatible ``` Resume continues an existing draft. It does not restore a discarded or deleted draft. --- ## 10. Draft Composition Consistency ### 10.1 `with draft` ```abap association _Items { create; with draft; } association _Request { with draft; } ``` Draft-enabled BO-internal navigation keeps all nodes in the same active/draft context: ```text Navigate from active Request → active Items Navigate from draft Request → draft Items Create Item through draft Request → draft Item ``` Without consistent draft navigation, a user could edit a draft root while accidentally reading or creating active children, breaking aggregate consistency. ### 10.2 Independent reference associations Customer and Product reference entities usually remain active reference data: ```text Draft Request ─association→ active Customer reference Draft Item ─association→ active Product reference ``` They are not draft-owned merely because the draft transaction refers to them. --- ## 11. Pessimistic Concurrency: Locks ### 11.1 Purpose Pessimistic concurrency prevents simultaneous modification by acquiring an exclusive enqueue lock before modifying an existing instance. ```text User A requests modification → lock acquired User B requests conflicting modification → lock collision → request rejected while A owns lock ``` Locks prevent concurrent editing. They do not prove that a client is modifying the exact version it previously read; that is the ETag responsibility. ### 11.2 Lock master and dependent ```abap define behavior for ZI_SalesOrderRequest lock master define behavior for ZI_SalesOrderItem lock dependent by _Request ``` The root is the aggregate lock master. Modifying an Item resolves its parent Request and locks the relevant aggregate, so related root and child changes are protected together. ```text Request A + its Items → one lock-master scope Request B + its Items → separate lock-master scope ``` ### 11.3 Managed and unmanaged lock handling Managed RAP can implement standard lock behavior from the BDEF declaration. Unmanaged RAP requires provider implementation, normally using the SAP enqueue lock concept and returning lock failures through RAP responses. ### 11.4 Lock limitations A lock: - does not validate a business rule; - does not replace a database uniqueness constraint; - does not automatically prevent two creates with the same externally supplied key before an existing instance is available to lock; - does not replace an ETag check; - does not make a long-running database transaction acceptable. --- ## 12. Optimistic Concurrency: Entity ETags ### 12.1 Purpose An entity ETag represents a version of entity state known to the OData consumer. ```text Client reads entity with ETag V1 │ Other client changes entity → current ETag V2 │ First client sends update with V1 │ RAP compares V1 with V2 → mismatch → reject ``` This prevents lost updates based on stale client state. ### 12.2 BDEF declaration ```abap etag master LocalLastChangedAt ``` or, for a dependent entity: ```abap etag dependent by _Request ``` An ETag master owns its ETag field. An ETag-dependent entity uses the ETag of a reachable master according to the declared association. ### 12.3 Reliable ETag update The field must change reliably whenever the protected entity state changes. Managed RAP can maintain correctly annotated administrative timestamps. Unmanaged providers must implement reliable updates themselves. ```abap @Semantics.systemDateTime.localInstanceLastChangedAt: true Request.local_last_changed_at as LocalLastChangedAt ``` Declaring `etag master` without reliably changing the value creates false concurrency safety. ### 12.4 Lock versus ETag ```text Lock prevents a conflicting writer during the current lock lifetime ETag rejects a write based on a stale previously read version ``` RAP transactional services use both forms because they address different race conditions. --- ## 13. Total ETag ### 13.1 Purpose The total ETag is a root-level version of the complete active business object used by draft concurrency transitions. ```abap lock master total etag LastChangedAt ``` It protects an edit draft from silently overwriting active changes made after the draft's exclusive lock expired. ### 13.2 Aggregate scope ```text Request root changes → total ETag changes Relevant Item child changes → total ETag changes Resume/Activate edit draft → remembered total ETag compared with current active total ETag ``` The total ETag is not a receipt proving that “the previous change applied successfully.” It is active aggregate version evidence used for optimistic concurrency. ### 13.3 Entity ETag versus total ETag | Control | Scope | Main use | | ----------- | -------------------------------------- | -------------------------------------------------------- | | Entity ETag | One entity or declared ETag dependency | Protect an OData modification against stale entity state | | Total ETag | Complete active draft-enabled BO | Protect active/draft transitions after lock expiry | Draft table administration also maintains draft-specific last-change evidence to prevent stale edits of the same draft from different clients. ### 13.4 Root field annotation A managed total-ETag timestamp is commonly annotated: ```abap @Semantics.systemDateTime.lastChangedAt: true Request.last_changed_at as LastChangedAt ``` It must also be present in persistence mapping when CDS and table field names differ. The total ETag can remain an internal field and does not always need to be exposed in the service projection. --- ## 14. Draft Lock Lifecycle ### 14.1 Exclusive phase When an edit draft is created, RAP locks the corresponding active aggregate. For the exclusive lock period, another user cannot modify that active instance. ```text Edit action → create draft → exclusive lock on active aggregate → draft owner edits ``` ### 14.2 Optimistic phase The exclusive lock cannot remain forever across stateless interaction. After its configured lifetime expires, the draft can still persist while the active instance becomes available under optimistic control. ```text Draft still exists Exclusive lock expired Total ETag remembers active version at draft boundary ``` ### 14.3 Resume conflict ```text Draft remembered total ETag = V1 Current active total ETag = V2 Resume attempts lock + comparison V1 ≠ V2 → conflict → stale draft cannot continue as if active were unchanged ``` The application should return a clear concurrency message and guide the user toward reviewing current active data rather than hiding the conflict. --- ## 15. Numbering ### 15.1 Identity timing ```text Early numbering key assigned during create interaction new instance is addressable before save Late numbering final key assigned after point of no return useful when final business number should be consumed only for accepted save ``` Key timing is independent from whether a field is called an “order number.” A BO can use a technical UUID early and assign a human-readable business number late. ### 15.2 Managed internal early numbering ```abap field ( numbering : managed, readonly ) RequestUUID; ``` Managed early numbering: - is available for managed BO UUID keys with ABAP type `RAW(16)`; - assigns the UUID during `CREATE`; - lets the draft and child instances reference the root immediately; - returns generated identity through RAP key mapping; - requires no custom numbering handler. Draft does not universally require every key to use this exact strategy, but a stable early technical key is especially practical for draft composition navigation. ### 15.3 Unmanaged early numbering ```abap define behavior for ZI_SalesOrderRequest early numbering ``` The behavior pool implements a `FOR NUMBERING` method invoked during create or create-by-association. The provider must guarantee uniqueness under concurrent requests and return assigned keys in `MAPPED`. For sequential business numbers, use a proper number-range or equivalent released concurrency-safe mechanism. “Read MAX and add one” is not safe under parallel creation without additional synchronization. ### 15.4 Late numbering Late numbering assigns final key values in `ADJUST_NUMBERS` after the point of no return. Appropriate uses can include legally or operationally controlled document numbers where gaps must be minimized according to the actual requirement. Trade-offs: - earlier interaction must use preliminary identity; - parent/child key relationships must be remapped correctly; - `MAPPED` results become central; - provider must guarantee save success after consuming final numbers; - error handling becomes more constrained after the point of no return. ### 15.5 Technical UUID plus business number ```text RequestUUID technical immutable key managed early numbering used for composition and transactional identity RequestNumber human-facing business identifier can be assigned by controlled application logic at the required phase ``` Separating the two reduces the pressure to use a mutable or late-assigned business identifier as the relational key of the entire aggregate. --- ## 16. `MAPPED`, `%cid`, and Transactional Identity ### 16.1 Create correlation ```abap WITH VALUE #( ( %cid = 'REQUEST_1' SoldToParty = '100000' TransactionCurrency = 'USD' ) ) MAPPED DATA(mapped) ``` The consumer supplies `%cid` as a request-local correlation identifier. RAP returns the assigned key in `mapped-SalesOrderRequest`. ### 16.2 Child correlation Deep or create-by-association requests use correlation IDs to connect newly created instances before final keys are known. Preserve the exact generated types rather than manually constructing partial key structures. ### 16.3 `%tky` `%tky` identifies an existing or newly addressed entity in its current transactional context. In a draft BO it includes the draft indicator. ```text Business key alone RequestUUID Transactional identity RequestUUID + draft/active context + framework key components ``` Use `%tky` across local reads, modifications, validation failures, messages, and action results. --- ## 17. Managed, Unmanaged, and Additional Save ### 17.1 Managed save The framework owns ordinary persistence based on: - persistent and draft tables; - CDS fields and BDEF mappings; - managed administrative fields; - validations and determinations; - lock, ETag, and numbering declarations. Application code should not duplicate standard table inserts or updates. ### 17.2 Unmanaged saver An unmanaged provider implements save-sequence methods appropriate to its contract, commonly including: ```abap CLASS lsc_SalesOrderRequest DEFINITION INHERITING FROM cl_abap_behavior_saver. PROTECTED SECTION. METHODS finalize REDEFINITION. METHODS check_before_save REDEFINITION. METHODS adjust_numbers REDEFINITION. METHODS save REDEFINITION. METHODS cleanup REDEFINITION. METHODS cleanup_finalize REDEFINITION. ENDCLASS. ``` Implement only callbacks required by the design. Later saver phases cannot use modifying EML to reopen interaction processing. ### 17.3 Additional save Additional save supplements managed persistence with an allowed secondary save effect. Suitable designs are durable and idempotent, such as an audit record or transactional outbox entry tied to the same commit. Unsafe design: ```text SAVE calls remote HTTP service remote system commits local database later fails systems disagree ``` Prefer a durable local outbox/event record in the RAP transaction, followed by asynchronous delivery with retry and idempotency. ### 17.4 Point-of-no-return discipline After the point of no return: - no normal user-correctable validation should fail; - final numbering must be concurrency-safe; - persistence must be guaranteed by the provider contract; - external side effects must not create an uncoordinated partial commit; - cleanup must release provider resources reliably. --- ## 18. Failure and Recovery Flows ### 18.1 Validation failure during activation ```text Draft contains invalid Product → user invokes Prepare or Activate → ValidateProduct appends Item %tky to FAILED → REPORTED carries field message → activation rejected → active data remains unchanged → draft remains available for correction ``` ### 18.2 Entity ETag conflict ```text Client sends stale ETag → RAP compares current entity version → mismatch → modification rejected before overwriting newer state → client must reread and reconcile ``` ### 18.3 Total ETag conflict on resume ```text Draft lock expired Active aggregate changed elsewhere → Resume reacquires lock → total ETag mismatch → stale draft cannot resume normally → user reviews current active version ``` ### 18.4 Technical failure after point of no return This indicates that the provider could not honor the save guarantee. Diagnose: - unmanaged save implementation; - key collision or unsafe numbering; - direct database constraint violation; - forbidden remote side effect; - incorrect persistence mapping; - save-order dependency between BOs; - uncaught exception or runtime error. Do not convert such defects into a generic validation message without fixing the violated save contract. ### 18.5 Discard flow ```text User discards edit draft → draft rows and administration removed → active row remains unchanged → draft editing state cannot be resumed ``` --- ## 19. End-to-End Sales Order Request Traces ### 19.1 Create a new draft request ```text 1. UI sends CREATE for draft root. 2. Managed early numbering assigns RequestUUID. 3. Initial values enter transactional buffer. 4. Determinations set defaults. 5. Save sequence persists state to zsor_request_d. 6. Active zsor_request has no corresponding row yet. 7. UI can return later using draft identity. ``` ### 19.2 Add a draft item ```text 1. UI creates by association through draft Request._Items. 2. ItemUUID is assigned early. 3. Parent RequestUUID and draft context are preserved. 4. Product/quantity enter buffer. 5. Determinations derive currency, price, and NetAmount. 6. Root TotalAmount is recomputed. 7. Save sequence persists Item and Request draft state. 8. No active Item is created yet. ``` ### 19.3 Activate the new request ```text 1. UI invokes Prepare/Activate. 2. Listed validations inspect complete draft aggregate. 3. Customer and Products are valid; quantity is positive. 4. Final determinations produce coherent totals. 5. Concurrency and save checks succeed. 6. Managed save creates active Request and Items. 7. Draft rows are removed. 8. Active aggregate becomes the official state. ``` ### 19.4 Edit an active request ```text 1. UI reads active Request and its ETag. 2. Edit verifies version and creates edit draft. 3. Active aggregate is exclusively locked. 4. Active Request and owned Items are represented in draft context. 5. User changes quantity; derivations update draft totals. 6. Active values remain unchanged during editing. 7. Activate validates and replaces active state atomically. 8. Draft is deleted after success. ``` --- ## 20. Technical Diagnostics ### 20.1 Draft button or edit flow is absent Check: ```text Base BDEF `with draft` → draft tables for every owned entity → total ETag on root → draft actions declared → BO-internal associations `with draft` → behavior projection uses draft actions → service binding and current metadata → Fiori draft support ``` ### 20.2 Draft changes appear in active data too early Check whether: - application code writes active tables directly; - an unmanaged save maps draft requests to the wrong persistence; - `%is_draft` was lost when reconstructing keys; - a helper uses SQL rather than current BO context; - navigation reaches active rather than draft child instances; - a custom action intentionally modifies active data. ### 20.3 Draft navigation returns no Items Check: 1. root composition and child parent association; 2. `with draft` on BO-internal relationships; 3. CDS projection redirection; 4. child draft table and key mapping; 5. `%is_draft` in EML keys; 6. service metadata and expansion path. ### 20.4 Activation fails with no useful message Check: - validations append exact `%tky` to `FAILED`; - `REPORTED` contains a message object and field marker; - validation is listed in `Prepare` when early feedback is expected; - nested EML `REPORTED` data is propagated; - late save failure is not being mislabeled as validation; - service/client logs contain the full RAP response. ### 20.5 Lock conflict Capture: - root business key and child key if applicable; - user/session owning the lock; - lock-master resolution path; - draft owner and draft age; - enqueue table evidence; - exact requested operation; - whether the lock is exclusive or the draft is in optimistic phase. Do not disable locking to make the symptom disappear. ### 20.6 ETag conflict Capture: ```text ETag read by client ETag sent in modification current ETag in active/draft entity operation timestamp and competing change entity ETag declaration and update annotation ``` An ETag conflict is normally evidence that concurrency protection worked. The consumer should reread and reconcile rather than retry the stale update blindly. ### 20.7 Total ETag does not change after child update Check: - root total-ETag field annotation; - persistence mapping; - managed administrative update behavior; - child is inside the same composition tree; - unmanaged provider updates aggregate version correctly; - update actually passed through RAP rather than direct SQL; - the field read is active total ETag rather than local entity timestamp. ### 20.8 Number collision Check: - early versus late numbering declaration; - managed UUID field type is `RAW(16)`; - custom `FOR NUMBERING` returns every required key in `MAPPED`; - number-range locking/concurrency; - preliminary-to-final parent/child remapping; - database uniqueness evidence; - unsafe `MAX + 1` logic. --- ## 21. Transaction and Draft Review Checklist ### Transaction model - Behavior code reads current state through EML where buffered data matters. - Interaction and save failures are diagnosed separately. - No handler or saver commits independently. - Predictable validation completes before the point of no return. - `FINALIZE` is the last phase that modifies buffered BO state. - Save implementation can guarantee success after pre-save checks. - Cross-BO save order and atomicity are explicit. ### Draft model - Draft is required by the user workflow, not enabled automatically everywhere. - Every draft-owned entity has correct generated draft persistence. - Application logic never treats draft tables as public SQL interfaces. - Active/draft identity is preserved through `%tky` and `%is_draft`. - Composition navigation stays within active or draft context. - `Prepare` lists the checks needed before activation. - `Discard` and `Resume` semantics are correctly represented to users. ### Concurrency - Root and dependent locks match aggregate ownership. - Entity ETags change reliably for every protected modification. - Draft root has a total ETag covering the aggregate. - Lock conflicts and ETag conflicts produce distinct diagnostics. - Consumers reread on stale-version conflicts rather than force overwrite. ### Numbering - Technical identity and business document number are separated where useful. - Managed UUID numbering uses the required type and read-only contract. - Custom numbering is concurrency-safe. - Late numbering occurs only after all normal rejection checks. - `MAPPED` preserves correlation and parent/child identity. --- ## 22. Compact Runtime Map ```text NON-DRAFT MODIFY Client reads V1 → sends modification + ETag V1 → RAP lock + ETag check → interaction buffer → determinations → save request → FINALIZE → CHECK_BEFORE_SAVE → point of no return → numbering/save → active database V2 → cleanup DRAFT EDIT Active V1 → Edit → active lock + draft copy → repeated draft modifications → each request saves durable draft state → Prepare validates draft → Activate compares concurrency state → active save sequence → Active V2 → draft removed CONCURRENCY Lock prevents simultaneous modification during lock lifetime Entity ETag rejects a write based on stale entity state Total ETag rejects stale active/draft transition for the aggregate STATE Transactional buffer temporary current RAP LUW state Draft persistence durable unfinished editing state Active persistence durable official business state ``` The transaction layer should always be understood through four boundaries: ```text Buffer is not persistence. Draft is not the transactional buffer. Prepare is not activation. Reported information is not automatically a rejected operation. ``` 4d:T8a8,SAP RAP Transactions, Draft, and Concurrency — Technical Reference This document explains how RAP manages state from the first modification until database commit. It covers the interaction phase, transactional buffer, save sequence, draft persistence, draft actions, pessimistic locks, entity ETags, total ETags, early and late numbering, and transaction ownership. The central runtime principle is: Every RAP modification first participates in a framework-controlled transaction. The transactional buffer holds the current logical BO state; the save sequence validates and persists that state. Draft adds a durable editing version, but it does not replace the transactional buffer or the save sequence used by each request. Primary SAP sources: - SAP Help — RAP BO Runtime - SAP Help — Save Sequence Runtime - SAP Help — Draft Runtime - SAP Help — Pessimistic Concurrency Control - SAP Help — Optimistic Concurrency Control - SAP Help — Total ETag - SAP Help — Numbering --- 1. RAP Transaction Model 1.1 Two runtime phases text INTERACTION PHASE Consumer request → authorization / feature / precheck controls → create, update, delete, or action → transactional buffer changes → on-modify determinations → interaction response save requested │ ▼ SAVE SEQUENCE FINALIZE → CHECKBEFORESAVE → point of no return → ADJUSTNUMBERS when late numbering is used → SAVE / managed persistence → database commit → CLEANUP The interaction phase can contain multiple operations. Those operations build one coherent logical transaction before persistence. The save sequence begins only when the consumer or service runtime closes the transaction with a save request. 1.2 RAP logical unit of work A RAP LUW is the framework-controlled unit in which one or more business objects participate in a transaction. Its boundary is not owned by an individual behavior method. text External EML consumer MODIFY ENTITIES ... MODIFY ENTITIES ... COMMIT ENTITIES OData consumer sends transactional request/batch RAP service runtime owns save and commit orchestration Behavior implementation participates in the current RAP LUW must not commit independently This enables RAP to validate all participating4e:Taed,# SAP RAP Transactions, Draft, and Concurrency — Technical Reference This document explains how RAP manages state from the first modification until database commit. It covers the interaction phase, transactional buffer, save sequence, draft persistence, draft actions, pessimistic locks, entity ETags, total ETags, early and late numbering, and transaction ownership. The central runtime principle is: > Every RAP modification first participates in a framework-controlled > transaction. The transactional buffer holds the current logical BO state; > the save sequence validates and persists that state. Draft adds a durable > editing version, but it does not replace the transactional buffer or the save > sequence used by each request. Primary SAP sources: - [SAP Help — RAP BO Runtime](https://help.sap.com/docs/abap-cloud/abap-rap/rap-bo-runtime) - [SAP Help — Save Sequence Runtime](https://help.sap.com/docs/abap-cloud/abap-rap/save-sequence-runtime) - [SAP Help — Draft Runtime](https://help.sap.com/docs/abap-cloud/abap-rap/draft-runtime) - [SAP Help — Pessimistic Concurrency Control](https://help.sap.com/docs/abap-cloud/abap-rap/pessimistic-concurrency-control-locking) - [SAP Help — Optimistic Concurrency Control](https://help.sap.com/docs/abap-cloud/abap-rap/optimistic-concurrency-control) - [SAP Help — Total ETag](https://help.sap.com/docs/ABAP_PLATFORM_NEW/fc4c71aa50014fd1b43721701471913d/f5e8548c241b43ab82bceec030b5dc9a.html) - [SAP Help — Numbering](https://help.sap.com/docs/abap-cloud/abap-rap/numbering) --- ## 1. RAP Transaction Model ### 1.1 Two runtime phases ```text INTERACTION PHASE Consumer request → authorization / feature / precheck controls → create, update, delete, or action → transactional buffer changes → on-modify determinations → interaction response save requested │ ▼ SAVE SEQUENCE FINALIZE → CHECK_BEFORE_SAVE → point of no return → ADJUST_NUMBERS when late numbering is used → SAVE / managed persistence → database commit → CLEANUP ``` The interaction phase can contain multiple operations. Those operations build one coherent logical transaction before persistence. The save sequence begins only when the consumer or service runtime closes the transaction with a save request. ### 1.2 RAP logical unit of work A RAP LUW is the framework-controlled unit in which one or more business objects participate in a transaction. Its boundary is not owned by an individual behavior method. ```text External EML consumer MODIFY ENTITIES ... MODIFY ENTITIES ... COMMIT ENTITIES OData consumer sends transactional request/batch RAP service runtime owns save and commit orchestration4f:T95c8, # SAP RAP Service Exposure and Fiori Elements — Technical Reference This document explains how a reusable RAP business object becomes a consumer-facing OData service and a metadata-driven SAP Fiori elements application. It covers service projections, behavior projections, metadata extensions, value helps, side effects, service definitions, service bindings, OData V4 UI and Web API contracts, publication, and runtime diagnosis. The central exposure principle is: > A service projection defines the data and behavior contract for one > consumption scenario. A service definition groups the entities exposed by > that contract. A service binding chooses the protocol and service category. > UI annotations describe presentation; they do not implement or secure the > underlying business rules. Primary SAP sources: - [SAP Help — Business Object Projection](https://help.sap.com/docs/abap-cloud/abap-rap/business-object-projection-6e7a10d30b74412a9482a80b0b88e005-194) - [SAP Help — Metadata-Driven UI Annotations](https://help.sap.com/docs/abap-cloud/abap-rap/defining-cds-annotations-for-metadata-driven-uis) - [SAP Help — Providing Value Help](https://help.sap.com/docs/abap-cloud/abap-rap/providing-value-help-for-selection-fields) - [SAP Help — Side Effects](https://help.sap.com/docs/abap-cloud/abap-rap/side-effects) - [SAP Help — Service Definition](https://help.sap.com/docs/abap-cloud/abap-rap/service-definition) - [SAP Help — Business Service](https://help.sap.com/docs/abap-cloud/abap-rap/business-service) - [SAP Help — OData V4 Service Binding Editor](https://help.sap.com/docs/abap-cloud/abap-development-tools-user-guide/using-service-binding-editor-for-odata-v4-service) --- ## 1. Consumer-Facing RAP Stack ```text Reusable RAP BO Base CDS + Base BDEF + Behavior Pool │ ▼ Service Projection CDS Projection + Behavior Projection │ ├──────── Metadata Extension │ UI semantics │ ▼ Service Definition entity exposure and service aliases │ ▼ Service Binding OData V4 UI / OData V4 Web API / other supported type │ ▼ Published endpoint and metadata │ ┌─────────┴─────────┐ ▼ ▼ Fiori elements UI External API consumer ``` Each artifact makes a different decision: | Artifact | Decision | | ------------------- | ----------------------------------------------------------- | | CDS projection | Which fields and relationships this consumer sees | | Behavior projection | Which BO capabilities this consumer may call | | Metadata extension | How a metadata-driven UI presents the model | | Service definition | Which CDS entities belong to the service | | Service binding | Which protocol and service category expose it | | Fiori application | How users navigate and interact with the published contract | The service layer does not replace the BO. It exposes a selected view of it. --- ## 2. Business Object Projection ### 2.1 Purpose A BO projection adapts a reusable business object for one service use case. ```text Base SalesOrderRequest BO create, update, delete, Submit, Cancel, Approve, internal fields │ ┌──────────────┼────────────────┐ ▼ ▼ ▼ Requester UI Processor UI Integration API Create Approve stable machine fields Edit draft Reject Submit Submit internal status no UI-only annotations ``` The base BO remains the invariant and transaction boundary. Each projection can narrow fields, navigation, and operations. ### 2.2 CDS projection ```abap @EndUserText.label: 'Sales Order Request UI' @AccessControl.authorizationCheck: #CHECK @Metadata.allowExtensions: true define root view entity ZC_SalesOrderRequest provider contract transactional_query as projection on ZI_SalesOrderRequest { key RequestUUID, RequestNumber, SoldToParty, Status, TotalAmount, TransactionCurrency, LocalLastChangedAt, _Items : redirected to composition child ZC_SalesOrderItem, _Customer } ``` The projection: - exposes consumer-relevant fields; - redirects the composition to projected child nodes; - can add consumer-specific aliases and annotations where supported; - omits implementation-only fields; - forms the data side of the service contract. `transactional_query` means this projection is intended as a transactional service-consumption layer. It does not mean the entity is read-only. ### 2.3 Behavior projection ```abap projection; strict ( 2 ); define behavior for ZC_SalesOrderRequest alias SalesOrderRequest use etag { use create; use update; use delete; use action Submit; use association _Items { create; with draft; } use action Resume; use action Edit; use action Activate; use action Discard; use action Prepare; } define behavior for ZC_SalesOrderItem alias SalesOrderItem use etag { use update; use delete; use association _Request { with draft; } use association _Product; } ``` The behavior projection exposes capabilities already supported by the underlying BO. Omitting `use action Submit` prevents this projection's OData consumer from calling the base action. ### 2.4 Projection is not business-rule enforcement Omitting `TotalAmount` or `Cancel` can narrow one service. Another projection or EML consumer may still reach the base BO. Therefore these rules remain in base behavior: - Customer must be valid; - quantity must be positive; - calculated amount must be consistent; - only permitted status transitions may be saved; - user must be authorized for the operation. Projection decides exposure. Base behavior guarantees correctness. --- ## 3. Metadata Extensions ### 3.1 Purpose A metadata extension, or MDE, stores annotations separately from the CDS data definition: ```abap @Metadata.layer: #CORE @UI.headerInfo: { typeName: 'Sales Order Request', typeNamePlural: 'Sales Order Requests', title: { type: #STANDARD, value: 'RequestNumber' }, description: { value: 'SoldToParty' } } annotate entity ZC_SalesOrderRequest with { ... } ``` This separation keeps the reusable semantic/query model readable while allowing the UI contract to evolve in its own repository object. ### 3.2 Enabling extensions The annotated CDS entity normally allows metadata extensions: ```abap @Metadata.allowExtensions: true define root view entity ZC_SalesOrderRequest ... ``` The effective annotation set can include: - annotations declared directly on source entities; - propagated annotations; - annotations declared on the projection; - annotations from metadata extensions at defined layers. Use ADT's Active Annotations view when the runtime result differs from the source file being inspected. ### 3.3 Metadata layers `@Metadata.layer` participates in annotation layering and precedence. Select the layer that matches ownership of the artifact rather than using one value for every extension without understanding its purpose. In a custom application, `#CORE` commonly represents the application owner's base UI semantics. Partner and customer adaptation layers have different ownership expectations where supported. ### 3.4 Metadata extension does not execute ABAP An MDE can: - place fields in a list report or object page; - define labels, importance, facets, and action placement; - describe text and value-help behavior; - hide a field from a generated UI; - instruct a client about refresh dependencies. It cannot: - calculate `NetAmount`; - reject an invalid Customer as a universal BO invariant; - authorize a user; - commit a transaction; - update a database table; - create a service endpoint. --- ## 4. Core Fiori Elements Annotations ### 4.1 `@UI.lineItem` Controls columns or actions in a list/table presentation: ```abap @UI.lineItem: [ { position: 10, importance: #HIGH } ] RequestNumber; ``` Typical use: ```text List report table RequestNumber | Customer | Status | TotalAmount ``` `position` establishes relative order. `importance` helps responsive clients decide what to retain when screen space becomes constrained. ### 4.2 `@UI.identification` Defines fields or actions associated with the object identity/detail area: ```abap @UI.identification: [ { position: 10 } ] RequestNumber; ``` It is commonly rendered on an object page, but exact rendering remains a consumer responsibility. ### 4.3 `@UI.selectionField` Defines fields proposed for the filter bar: ```abap @UI.selectionField: [ { position: 10 } ] Status; ``` This makes the field available prominently for selection. It does not add a backend authorization restriction. ### 4.4 `@UI.facet` Defines object-page sections and navigation structure: ```abap @UI.facet: [ { id: 'General', purpose: #STANDARD, type: #IDENTIFICATION_REFERENCE, label: 'General Information', position: 10 }, { id: 'Items', purpose: #STANDARD, type: #LINEITEM_REFERENCE, label: 'Items', position: 20, targetElement: '_Items' } ] RequestUUID; ``` The Item facet requires a valid projected composition and service navigation. An annotation cannot compensate for a broken `_Items` relationship. ### 4.5 `@UI.fieldGroup` Groups related fields into a reusable UI collection: ```abap @UI.fieldGroup: [ { qualifier: 'Commercial', position: 10 } ] SoldToParty; ``` A facet can reference the qualified group to form an object-page section. ### 4.6 `@UI.hidden` ```abap @UI.hidden: true LocalLastChangedAt; ``` This removes the field from ordinary generated presentation. The field can still remain in OData metadata and be used technically, for example as an ETag. UI hiding is not a security control. --- ## 5. Complete Root Metadata Example ```abap @Metadata.layer: #CORE @UI.headerInfo: { typeName: 'Sales Order Request', typeNamePlural: 'Sales Order Requests', title: { type: #STANDARD, value: 'RequestNumber' }, description: { value: 'Status' } } annotate entity ZC_SalesOrderRequest with { @UI.facet: [ { id: 'General', purpose: #STANDARD, type: #IDENTIFICATION_REFERENCE, label: 'General Information', position: 10 }, { id: 'Items', purpose: #STANDARD, type: #LINEITEM_REFERENCE, label: 'Items', position: 20, targetElement: '_Items' } ] RequestUUID; @UI: { lineItem: [ { position: 10, importance: #HIGH } ], identification: [ { position: 10 } ] } @EndUserText.label: 'Request' RequestNumber; @UI: { lineItem: [ { position: 20, importance: #HIGH } ], identification: [ { position: 20 } ], selectionField: [ { position: 10 } ] } @EndUserText.label: 'Sold-to Party' SoldToParty; @UI: { lineItem: [ { position: 30, importance: #HIGH } ], identification: [ { position: 30 } ], selectionField: [ { position: 20 } ] } Status; @UI: { lineItem: [ { position: 40, importance: #HIGH } ], identification: [ { position: 40 } ] } TotalAmount; @UI.hidden: true RequestUUID; @UI.hidden: true LocalLastChangedAt; } ``` The amount/currency relationship should already exist in the CDS semantic model. The UI annotation places `TotalAmount`; it does not need to recreate the calculation. --- ## 6. Child Metadata and Composition Rendering ```abap @Metadata.layer: #CORE annotate entity ZC_SalesOrderItem with { @UI.lineItem: [ { position: 10, importance: #HIGH } ] Product; @UI.lineItem: [ { position: 20, importance: #HIGH } ] RequestedQuantity; @UI.lineItem: [ { position: 30, importance: #MEDIUM } ] UnitPrice; @UI.lineItem: [ { position: 40, importance: #HIGH } ] NetAmount; @UI.hidden: true ItemUUID; @UI.hidden: true RequestUUID; @UI.hidden: true LocalLastChangedAt; } ``` For the object page to render editable Items correctly, all of these layers must align: ```text Base CDS composition → base BDEF create-by-association → projected CDS redirection → projected BDEF association create → service entity exposure/navigation → root facet targets `_Items` → child has `@UI.lineItem` ``` A problem at any layer can appear as a missing table, missing Create button, empty navigation, or read-only child section. --- ## 7. UI Actions ### 7.1 Action placement The action must exist in base behavior and be used in the behavior projection. Metadata can then place it: ```abap @UI.lineItem: [ { type: #FOR_ACTION, dataAction: 'Submit', label: 'Submit', position: 50 } ] RequestNumber; ``` Action naming in metadata must match the service-visible action name, including any projection aliasing or external naming. ### 7.2 End-to-end action visibility ```text Base BDEF action Submit │ ▼ Behavior Projection use action Submit │ ▼ OData metadata action import/bound action contract │ ▼ UI annotation #FOR_ACTION + dataAction │ ▼ Fiori button ``` ### 7.3 Feature control Instance feature control can disable Submit when Status is already Submitted. The UI consumes the result and adjusts affordance. Backend behavior remains the source of truth; do not implement the state rule only as frontend visibility. --- ## 8. Texts and Text Arrangement ### 8.1 Code and description Business fields often contain a compact key and a human-readable text: ```text Product = HT-1000 ProductName = Notebook Basic 15 ``` CDS associations and text annotations allow consumers to present both without copying the text into transactional persistence. ### 8.2 Text arrangement ```abap @UI.textArrangement: #TEXT_LAST Product; ``` Possible arrangements depend on supported metadata and can favor: - key only; - text only; - text followed by key; - key followed by text. The annotation controls presentation. It does not change the stored Product ID. ### 8.3 Historical snapshot boundary Use a live association when the UI should show the current master-data text. Persist a copied description only when the transaction has a genuine historical snapshot requirement. Those are different domain semantics. --- ## 9. Value Help ### 9.1 Purpose A value help connects an input field to a lookup provider: ```abap @Consumption.valueHelpDefinition: [ { entity: { name: 'ZI_CustomerValueHelp', element: 'CustomerID' } } ] SoldToParty; ``` The consumer can query the provider, display key/text/filter columns, and copy the selected key into `SoldToParty`. ### 9.2 Provider model ```abap @EndUserText.label: 'Customer Value Help' @ObjectModel.resultSet.sizeCategory: #XS define view entity ZI_CustomerValueHelp as select from ZI_CustomerReference { key CustomerID, CustomerName, CountryCode } ``` A good value-help provider has: - stable key element; - useful descriptive text; - fields required for search/filter/display; - correct authorization behavior; - an appropriate result-set shape and size strategy; - no accidental exposure of sensitive master data. ### 9.3 Service exposure The value-help provider must be reachable through the service contract when the consumer needs to query it. In many RAP OData services, that means exposing the provider entity in the service definition: ```abap expose ZI_CustomerValueHelp as CustomerValueHelp; ``` Defining the annotation alone does not publish an entity set. ### 9.4 `useForValidation: true` ```abap @Consumption.valueHelpDefinition: [ { entity: { name: 'ZI_CustomerValueHelp', element: 'CustomerID' }, useForValidation: true } ] SoldToParty; ``` This marks the value-help definition for validation of user input. Supported consumer/framework processing can check entered values against the provider's allowed result set. It does not replace a RAP behavior validation when: - validity depends on Status, date, Sales Area, role, or other BO state; - the rule must protect direct EML and every service projection; - the provider list is a convenience subset rather than the domain truth; - the rule requires a precise backend error message; - security or transactional consistency is involved; - the referenced object can change between input and save. Use value-help validation for the lookup constraint and backend validation for the durable business invariant. ### 9.5 Additional binding A value help can pass context fields into or out of the provider, for example filtering Product by Sales Organization or returning a related Unit. Model those bindings explicitly and ensure their fields are exposed in the service metadata. Do not hide a missing business determination inside a value-help side effect. Returned values should have a clearly owned source of truth. --- ## 10. Why a Service Definition May Expose Reference Entities Representative Travel service: ```abap define service ZUI_TRAVEL { expose ZC_Travel as Travel; expose ZC_Booking as Booking; expose ZI_AgencyVH as Agency; expose ZI_CustomerVH as Customer; expose ZI_FlightVH as Flight; expose I_Currency as Currency; expose I_Country as Country; } ``` Reference entities can be exposed because the consumer needs them for: - value-help queries; - text retrieval; - direct navigation targets; - filtering or autocomplete; - dependent lookup fields; - service metadata relationships; - an API operation that legitimately reads the reference collection. Do not expose every CDS association automatically. Expose an entity when the service contract requires it and when its authorization/data surface is safe. The correct rule is broader than “expose it only when it appears as a scalar field in the projection.” A provider may need exposure even when used through value help or navigation rather than displayed as a root field. --- ## 11. Service Definition ### 11.1 Responsibility A service definition is a protocol-independent repository object that groups the CDS entities exposed by one business service. ```abap @EndUserText.label: 'Sales Order Request UI Service' @ObjectModel.leadingEntity.name: 'ZC_SalesOrderRequest' define service ZUI_SALESORDERREQUEST { expose ZC_SalesOrderRequest as SalesOrderRequests; expose ZC_SalesOrderItem as SalesOrderItems; expose ZI_CustomerValueHelp as Customers; expose ZI_ProductValueHelp as Products; expose I_Currency as Currencies; } ``` The service definition decides: - which entity models belong to this service; - their service-visible aliases; - the primary/leading entity where declared; - which navigation and lookup targets can become reachable. It does not decide: - whether the service uses OData V2 or V4; - whether it is a UI service or Web API; - the HTTP endpoint URL; - how CRUD is implemented; - whether the current user is authorized; - whether the service is published. ### 11.2 Service aliases ```abap expose ZC_SalesOrderRequest as SalesOrderRequests; ``` The alias decouples the external entity-set name from the CDS technical object name. Choose a stable consumer-oriented name and treat changes as API contract changes. ### 11.3 Complete service graph For a composition-based UI, expose all nodes needed by the business service. The root alone is not always sufficient when child entity sets, navigation, metadata, or value helps must be reachable. At the same time, exposure should be minimal. Every extra entity adds: - metadata and compatibility surface; - possible direct query access; - authorization and performance responsibility; - maintenance and release obligations. --- ## 12. Service Binding ### 12.1 Responsibility A service binding assigns the service definition to a supported protocol and service category. ```text Service Definition protocol-independent model │ ├── OData V4 UI binding ├── OData V4 Web API binding └── another supported binding type ``` One service definition can be used by multiple bindings when the same service contract is appropriate. If UI and integration consumers require materially different fields, operations, versioning, or lifecycle promises, use separate projections and often separate service definitions rather than forcing one oversized contract. ### 12.2 OData V4 UI Designed for metadata-driven user interfaces such as Fiori elements. It consumes UI annotations, draft metadata, actions, value helps, side effects, messages, field control, and navigation. ### 12.3 OData V4 Web API Designed for machine-to-machine consumption. Its contract should emphasize: - stable external names; - explicit operation semantics; - controlled versioning; - predictable messages and HTTP outcomes; - API authorization; - idempotency and concurrency behavior; - minimal UI-specific metadata. A UI projection is not automatically a good public API merely because both use OData V4. ### 12.4 OData V2 and `@OData.publish: true` Older examples often use OData V2 or `@OData.publish: true`. Current RAP design normally favors explicit service definitions and bindings because they provide a clearer service contract, category, protocol choice, versioning, and publication lifecycle. Do not copy an older workshop's V2 binding solely because the sample predates OData V4 support. Confirm the target ABAP release and consumer requirement. --- ## 13. Metadata Request Runtime ```text Fiori client requests $metadata │ ▼ Published Service Binding │ ▼ Service Definition exposed entity aliases and relationships │ ▼ CDS Projection + Behavior Projection fields, navigation, actions, field/ETag/draft contract │ ▼ Metadata Extension + annotations line items, facets, labels, value help, side effects │ ▼ OData metadata document │ ▼ Fiori elements generates list/object-page behavior ``` No behavior-pool method is normally called merely to compile static metadata. Dynamic feature or authorization requests occur when the client asks for the corresponding runtime permissions or data. ### 13.1 Metadata caching After changing CDS, behavior projection, or annotations: - activate all dependent artifacts; - verify the intended service version is published; - inspect live `$metadata` rather than only source code; - refresh or clear relevant client metadata caches; - confirm the browser is calling the expected endpoint. Many apparent annotation defects are stale-metadata defects. --- ## 14. Query and Navigation Runtime ### 14.1 List report read ```text Fiori GET SalesOrderRequests → OData V4 binding → service entity alias → CDS transactional query projection → CDS access control and query runtime → database query → OData response → lineItem rendering ``` The normal CDS-backed query path does not require a behavior-pool read method for a managed query. ### 14.2 Object-page navigation ```text Select one Request → GET by key → object-page identification/facets rendered → expand or navigate `_Items` → projected composition target → child query → child line items rendered ``` ### 14.3 Value-help request ```text User opens SoldToParty value help → metadata identifies provider entity/element → client queries Customers entity set → DCL and service authorization apply → search/filter/order/page options processed → key and text returned → selected CustomerID copied to SoldToParty ``` The provider may return no values because of authorization or filters even when the underlying table contains records. --- ## 15. Side Effects ### 15.1 Purpose Side effects describe which fields, entities, permissions, or messages should be refreshed after a source value or action changes. ```text RequestedQuantity changes → determination recalculates NetAmount → root aggregation recalculates TotalAmount → side-effect metadata tells UI what to reread ``` The determination performs the calculation. The side effect synchronizes the consumer presentation with backend state. ### 15.2 Representative declaration Exact supported syntax depends on the BDEF and target release, but the model is: ```abap side effects { field RequestedQuantity affects field NetAmount; field UnitPrice affects field NetAmount; action Submit affects field Status, permissions ( action Submit ); } ``` Cross-entity dependencies can require association or entity targets supported by the release and service protocol. ### 15.3 Side effects are not determinations ```text Determination changes backend BO state Side effect declares consumer refresh dependency ``` If a side effect exists but no backend logic updates `NetAmount`, the reread returns the same value. If determination exists but side effects are missing, the backend state can be correct while the UI continues showing an old value. --- ## 16. Security Boundaries ### 16.1 UI hiding `@UI.hidden: true` controls presentation. A malicious or custom client can still inspect or request an OData property if the service exposes it and the protocol permits access. ### 16.2 Projection omission Omitting `InternalProcessingCode` from the CDS projection removes it from that service contract. This is stronger than UI hiding but still does not replace authorization for remaining fields and operations. ### 16.3 CDS DCL DCL restricts readable rows for the CDS entity where it is applied. Test the actual consumption entity; do not assume access controls automatically propagate through every view stack. ### 16.4 RAP authorization RAP authorization controls create, update, delete, associations, actions, and other modifying capabilities based on the current user and context. ### 16.5 Value-help security A value-help entity is a query surface. Apply appropriate authorization and expose only the columns needed for selection. Do not treat lookup data as automatically harmless. ```text UI annotation presentation Projection contract surface DCL read-row restriction RAP authorization modify-operation permission Backend validation business invariant ``` All five can be required in one service. --- ## 17. Activate, Publish, Transport, and Deploy ### 17.1 Activate Creates the active repository version after syntax and dependency checks. ```text CDS/MDE/BDEF/service source → Activate in ADT → active ABAP repository object ``` Activation does not make an OData endpoint externally available by itself. ### 17.2 Publish Publishing a service binding enables/registers the service endpoint in the connected ABAP system according to that environment's lifecycle. ```text Active service definition + binding → Publish → callable local system endpoint/version ``` ### 17.3 Transport Transport moves repository and configuration artifacts through the system landscape, for example development to quality to production. Local publication status and environment-specific service setup can still require lifecycle handling in each target system. ### 17.4 Deploy Deployment often refers to delivering a separate frontend application to its runtime or making a complete solution available. It is not a synonym for ABAP artifact activation. ```text Activate repository code becomes active in one ABAP system Publish service endpoint becomes available in that system Transport artifacts move between ABAP systems Deploy separate application/content reaches its target runtime ``` --- ## 18. Fiori Elements Preview The service-binding editor can launch a Fiori elements preview for suitable UI services. Preview is valuable for validating: - entity-set availability; - list report columns; - object-page facets; - composition navigation; - value helps; - draft actions; - action placement; - field control and messages; - side-effect refresh. Preview is not a substitute for a production Fiori application. It does not prove: - launchpad role/catalog configuration; - semantic-object and target-mapping correctness; - production authorization roles; - frontend deployment and routing; - accessibility and UX review; - API compatibility; - performance under real volume. --- ## 19. End-to-End Sales Order Request UI Flow ### 19.1 Open list report ```text 1. Browser loads Fiori elements application. 2. Client requests OData `$metadata`. 3. Service binding resolves ZUI_SALESORDERREQUEST. 4. Metadata describes SalesOrderRequests, Items, actions, value helps, and UI. 5. Client requests SalesOrderRequests with query options. 6. RAP query runtime reads ZC_SalesOrderRequest under DCL. 7. `@UI.lineItem` fields form the table. ``` ### 19.2 Create request draft ```text 1. Create visibility comes from projected behavior. 2. Client creates a draft root. 3. Managed RAP assigns RequestUUID and persists draft state. 4. Object page uses headerInfo and identification annotations. 5. SoldToParty value help queries the exposed Customers provider. 6. Item facet navigates through projected `_Items` composition. ``` ### 19.3 Change quantity ```text 1. UI PATCH changes RequestedQuantity on draft Item. 2. Behavior determination recalculates NetAmount and TotalAmount. 3. Side-effect metadata tells UI to reread affected fields. 4. Refreshed values are formatted with unit/currency semantics. 5. No active business data changes until activation. ``` ### 19.4 Submit ```text 1. Action exists in base BDEF and behavior pool. 2. Behavior projection exposes Submit. 3. UI annotation renders the action button. 4. Instance feature control enables it for eligible Status. 5. RAP authorization checks the user's permission. 6. Handler changes buffered state and returns action result/messages. 7. Draft Prepare/Activate validations protect final persistence. 8. UI refreshes Status and action permissions. ``` --- ## 20. Technical Diagnostics ### 20.1 Entity is absent from the service Check: ```text CDS projection active → service definition `expose` → correct service alias → service binding references intended definition/version → binding published → live `$metadata` → client endpoint and cache ``` ### 20.2 Field is absent Check: 1. base CDS element; 2. CDS projection list; 3. active metadata annotations; 4. service metadata property; 5. UI annotation placement; 6. client personalization and cache. If the property is absent from `$metadata`, the defect is before UI rendering. ### 20.3 Create/Edit/Delete button is missing Check: 1. base BDEF operation; 2. behavior projection `use` declaration; 3. draft actions if draft is enabled; 4. dynamic feature result; 5. RAP authorization result; 6. current service metadata; 7. Fiori page mode and client cache. ### 20.4 Action button is missing Trace: ```text Base action declaration → behavior-pool method → behavior projection `use action` → service-visible action name → `@UI.lineItem` or `@UI.identification` action annotation → feature control → live metadata ``` ### 20.5 Item facet is empty Check: - root facet `targetElement` spelling; - projected composition redirection; - child projection and service exposure; - active/draft navigation context; - parent/child keys and `ON` condition; - DCL on child query; - whether Items exist in the relevant active/draft state. ### 20.6 Value-help icon or values are missing Check: 1. active `@Consumption.valueHelpDefinition`; 2. exact provider entity and element names; 3. provider exposed/reachable in the service; 4. provider appears in `$metadata`; 5. DCL/authorization permits provider rows; 6. additional-binding fields exist and contain values; 7. search/filter metadata and data types are compatible; 8. browser calls the expected endpoint. ### 20.7 Value accepted by UI but save fails This can be correct when value help and business validation enforce different rules. Capture: - selected provider row; - `useForValidation` setting; - current BO Status, Sales Area, date, and other context; - backend validation message; - whether the reference changed between selection and save. The business validation remains authoritative. ### 20.8 Derived value changes in backend but not UI Check: ```text Determination actually updates buffer → nested EML messages/failures → side-effect source field/action → affected target field/entity → target property exposed → UI reread network request → response value and metadata cache ``` ### 20.9 Works in preview but not launchpad Inspect the application-level delivery chain: - deployed frontend application/component; - destination and service URL; - OData service activation/publication in the target system; - launchpad catalog and role; - semantic object and action; - target mapping; - user frontend/backend authorizations; - cache and gateway error logs; - transport completeness. Preview proves the local service/UI metadata path, not the full launchpad setup. --- ## 21. UI and API Contract Design ### 21.1 Separate contracts when promises differ ```text UI service draft editing UI annotations role-specific actions user-facing state messages Web API versioned stable schema machine-oriented operation names explicit concurrency requirements integration authorization minimal navigation and lookup surface ``` Reusing one service definition can be appropriate for closely aligned consumers. Separate projections are appropriate when the contract lifecycle and exposed capabilities differ materially. ### 21.2 Avoid exposing implementation details Do not expose: - internal processing codes without a consumer contract; - raw administrative fields that consumers do not need; - direct write access to derived fields; - unrestricted master-data lookup collections; - legacy persistence names as public API names; - actions whose semantics are not stable. ### 21.3 Versioning Treat service aliases, field types, nullability, actions, navigation paths, and message behavior as compatibility surface. A published Web API requires a stronger compatibility policy than a private preview service. --- ## 22. Exposure Review Checklist ### Projection - CDS projection contains only consumer-relevant fields and navigation. - `transactional_query` provider contract is explicit. - Compositions and parents redirect to projected nodes. - Behavior projection exposes only required operations and actions. - Derived/internal fields have consistent behavior and visibility. - UI and API consumers use separate contracts when their promises differ. ### Metadata - UI annotations are stored in metadata extensions where practical. - Header, line item, identification, filters, and facets reflect the entity grain. - Item facet targets a valid projected composition. - Technical fields are hidden for presentation but retained when runtime needs them. - Action metadata matches the service-visible action name. - Text associations and arrangements do not change stored identity. ### Value help and side effects - Lookup provider exposes only needed, authorized fields. - Provider and key element are reachable in the service. - `useForValidation` is used intentionally and not confused with BO validation. - Additional bindings pass complete context. - Determinations calculate; side effects trigger consumer refresh. - Cross-entity refresh is verified through actual network responses. ### Service - Service definition exposes the complete required graph and no accidental entities. - External aliases are stable and consumer-oriented. - Binding type matches UI or API use. - Intended service version is active and published. - Live `$metadata` is reviewed after changes. - Transport and frontend deployment requirements are documented separately. ### Security - UI hiding is never treated as access control. - Projection omission, DCL, RAP authorization, and validation are all applied at their proper boundaries. - Value-help endpoints are treated as data APIs. - Preview and launchpad authorization are tested independently. --- ## 23. Compact Exposure Map ```text BASE RAP BO ZI_SalesOrderRequest + Base BDEF + Behavior Pool reusable data, operations, invariants, transaction handling │ ▼ SERVICE PROJECTION ZC_SalesOrderRequest CDS fields/navigation Projection BDEF use CRUD/actions/draft Metadata Extension lineItem/facet/value help/action/side effect │ ▼ SERVICE DEFINITION SalesOrderRequests SalesOrderItems Customers value help Products value help Currencies │ ▼ SERVICE BINDING OData V4 UI Fiori elements metadata-driven application OData V4 Web API machine-oriented integration contract │ ▼ RUNTIME $metadata contract and annotations GET CDS query + DCL PATCH/POST/action RAP behavior + authorization + transaction value-help GET lookup provider query side-effect reread synchronize UI with backend derivation ``` The consumer layer should always be read through five separate concerns: ```text Projection narrows the reusable BO. Metadata describes presentation. Service definition selects entity exposure. Service binding selects protocol and service category. Backend behavior and authorization protect correctness. ``` 50:T89e,SAP RAP Service Exposure and Fiori Elements — Technical Reference This document explains how a reusable RAP business object becomes a consumer-facing OData service and a metadata-driven SAP Fiori elements application. It covers service projections, behavior projections, metadata extensions, value helps, side effects, service definitions, service bindings, OData V4 UI and Web API contracts, publication, and runtime diagnosis. The central exposure principle is: A service projection defines the data and behavior contract for one consumption scenario. A service definition groups the entities exposed by that contract. A service binding chooses the protocol and service category. UI annotations describe presentation; they do not implement or secure the underlying business rules. Primary SAP sources: - SAP Help — Business Object Projection - SAP Help — Metadata-Driven UI Annotations - SAP Help — Providing Value Help - SAP Help — Side Effects - SAP Help — Service Definition - SAP Help — Business Service - SAP Help — OData V4 Service Binding Editor --- 1. Consumer-Facing RAP Stack text Reusable RAP BO Base CDS + Base BDEF + Behavior Pool │ ▼ Service Projection CDS Projection + Behavior Projection │ ├──────── Metadata Extension │ UI semantics │ ▼ Service Definition entity exposure and service aliases │ ▼ Service Binding OData V4 UI / OData V4 Web API / other supported type │ ▼ Published endpoint and metadata │ ┌─────────┴─────────┐ ▼ ▼ Fiori elements UI External API consumer Each artifact makes a different decision: | Artifact | Decision | | ------------------- | ----------------------------------------------------------- | | CDS projection | Which fields and relationships this consumer sees | | Behavior projection | Which BO capabilities this consumer may call | | Metadata extension | How a metadata-driven UI presents the model | | Service definition | Which CDS entities belong to the service | | Service binding | Which protocol and service category expose it | | Fiori application | How users navigate and interact with the published contract | The service layer does not replace51:Ta1a,# SAP RAP Service Exposure and Fiori Elements — Technical Reference This document explains how a reusable RAP business object becomes a consumer-facing OData service and a metadata-driven SAP Fiori elements application. It covers service projections, behavior projections, metadata extensions, value helps, side effects, service definitions, service bindings, OData V4 UI and Web API contracts, publication, and runtime diagnosis. The central exposure principle is: > A service projection defines the data and behavior contract for one > consumption scenario. A service definition groups the entities exposed by > that contract. A service binding chooses the protocol and service category. > UI annotations describe presentation; they do not implement or secure the > underlying business rules. Primary SAP sources: - [SAP Help — Business Object Projection](https://help.sap.com/docs/abap-cloud/abap-rap/business-object-projection-6e7a10d30b74412a9482a80b0b88e005-194) - [SAP Help — Metadata-Driven UI Annotations](https://help.sap.com/docs/abap-cloud/abap-rap/defining-cds-annotations-for-metadata-driven-uis) - [SAP Help — Providing Value Help](https://help.sap.com/docs/abap-cloud/abap-rap/providing-value-help-for-selection-fields) - [SAP Help — Side Effects](https://help.sap.com/docs/abap-cloud/abap-rap/side-effects) - [SAP Help — Service Definition](https://help.sap.com/docs/abap-cloud/abap-rap/service-definition) - [SAP Help — Business Service](https://help.sap.com/docs/abap-cloud/abap-rap/business-service) - [SAP Help — OData V4 Service Binding Editor](https://help.sap.com/docs/abap-cloud/abap-development-tools-user-guide/using-service-binding-editor-for-odata-v4-service) --- ## 1. Consumer-Facing RAP Stack ```text Reusable RAP BO Base CDS + Base BDEF + Behavior Pool │ ▼ Service Projection CDS Projection + Behavior Projection │ ├──────── Metadata Extension │ UI semantics │ ▼ Service Definition entity exposure and service aliases │ ▼ Service Binding OData V4 UI / OData V4 Web API / other supported type │ ▼ Published endpoint and metadata │ ┌─────────┴─────────┐ ▼ ▼ Fiori elements UI External API consumer ``` Each artifact makes a different decision:52:T95c8, # SAP RAP Service Exposure and Fiori Elements — Technical Reference This document explains how a reusable RAP business object becomes a consumer-facing OData service and a metadata-driven SAP Fiori elements application. It covers service projections, behavior projections, metadata extensions, value helps, side effects, service definitions, service bindings, OData V4 UI and Web API contracts, publication, and runtime diagnosis. The central exposure principle is: > A service projection defines the data and behavior contract for one > consumption scenario. A service definition groups the entities exposed by > that contract. A service binding chooses the protocol and service category. > UI annotations describe presentation; they do not implement or secure the > underlying business rules. Primary SAP sources: - [SAP Help — Business Object Projection](https://help.sap.com/docs/abap-cloud/abap-rap/business-object-projection-6e7a10d30b74412a9482a80b0b88e005-194) - [SAP Help — Metadata-Driven UI Annotations](https://help.sap.com/docs/abap-cloud/abap-rap/defining-cds-annotations-for-metadata-driven-uis) - [SAP Help — Providing Value Help](https://help.sap.com/docs/abap-cloud/abap-rap/providing-value-help-for-selection-fields) - [SAP Help — Side Effects](https://help.sap.com/docs/abap-cloud/abap-rap/side-effects) - [SAP Help — Service Definition](https://help.sap.com/docs/abap-cloud/abap-rap/service-definition) - [SAP Help — Business Service](https://help.sap.com/docs/abap-cloud/abap-rap/business-service) - [SAP Help — OData V4 Service Binding Editor](https://help.sap.com/docs/abap-cloud/abap-development-tools-user-guide/using-service-binding-editor-for-odata-v4-service) --- ## 1. Consumer-Facing RAP Stack ```text Reusable RAP BO Base CDS + Base BDEF + Behavior Pool │ ▼ Service Projection CDS Projection + Behavior Projection │ ├──────── Metadata Extension │ UI semantics │ ▼ Service Definition entity exposure and service aliases │ ▼ Service Binding OData V4 UI / OData V4 Web API / other supported type │ ▼ Published endpoint and metadata │ ┌─────────┴─────────┐ ▼ ▼ Fiori elements UI External API consumer ``` Each artifact makes a different decision: | Artifact | Decision | | ------------------- | ----------------------------------------------------------- | | CDS projection | Which fields and relationships this consumer sees | | Behavior projection | Which BO capabilities this consumer may call | | Metadata extension | How a metadata-driven UI presents the model | | Service definition | Which CDS entities belong to the service | | Service binding | Which protocol and service category expose it | | Fiori application | How users navigate and interact with the published contract | The service layer does not replace the BO. It exposes a selected view of it. --- ## 2. Business Object Projection ### 2.1 Purpose A BO projection adapts a reusable business object for one service use case. ```text Base SalesOrderRequest BO create, update, delete, Submit, Cancel, Approve, internal fields │ ┌──────────────┼────────────────┐ ▼ ▼ ▼ Requester UI Processor UI Integration API Create Approve stable machine fields Edit draft Reject Submit Submit internal status no UI-only annotations ``` The base BO remains the invariant and transaction boundary. Each projection can narrow fields, navigation, and operations. ### 2.2 CDS projection ```abap @EndUserText.label: 'Sales Order Request UI' @AccessControl.authorizationCheck: #CHECK @Metadata.allowExtensions: true define root view entity ZC_SalesOrderRequest provider contract transactional_query as projection on ZI_SalesOrderRequest { key RequestUUID, RequestNumber, SoldToParty, Status, TotalAmount, TransactionCurrency, LocalLastChangedAt, _Items : redirected to composition child ZC_SalesOrderItem, _Customer } ``` The projection: - exposes consumer-relevant fields; - redirects the composition to projected child nodes; - can add consumer-specific aliases and annotations where supported; - omits implementation-only fields; - forms the data side of the service contract. `transactional_query` means this projection is intended as a transactional service-consumption layer. It does not mean the entity is read-only. ### 2.3 Behavior projection ```abap projection; strict ( 2 ); define behavior for ZC_SalesOrderRequest alias SalesOrderRequest use etag { use create; use update; use delete; use action Submit; use association _Items { create; with draft; } use action Resume; use action Edit; use action Activate; use action Discard; use action Prepare; } define behavior for ZC_SalesOrderItem alias SalesOrderItem use etag { use update; use delete; use association _Request { with draft; } use association _Product; } ``` The behavior projection exposes capabilities already supported by the underlying BO. Omitting `use action Submit` prevents this projection's OData consumer from calling the base action. ### 2.4 Projection is not business-rule enforcement Omitting `TotalAmount` or `Cancel` can narrow one service. Another projection or EML consumer may still reach the base BO. Therefore these rules remain in base behavior: - Customer must be valid; - quantity must be positive; - calculated amount must be consistent; - only permitted status transitions may be saved; - user must be authorized for the operation. Projection decides exposure. Base behavior guarantees correctness. --- ## 3. Metadata Extensions ### 3.1 Purpose A metadata extension, or MDE, stores annotations separately from the CDS data definition: ```abap @Metadata.layer: #CORE @UI.headerInfo: { typeName: 'Sales Order Request', typeNamePlural: 'Sales Order Requests', title: { type: #STANDARD, value: 'RequestNumber' }, description: { value: 'SoldToParty' } } annotate entity ZC_SalesOrderRequest with { ... } ``` This separation keeps the reusable semantic/query model readable while allowing the UI contract to evolve in its own repository object. ### 3.2 Enabling extensions The annotated CDS entity normally allows metadata extensions: ```abap @Metadata.allowExtensions: true define root view entity ZC_SalesOrderRequest ... ``` The effective annotation set can include: - annotations declared directly on source entities; - propagated annotations; - annotations declared on the projection; - annotations from metadata extensions at defined layers. Use ADT's Active Annotations view when the runtime result differs from the source file being inspected. ### 3.3 Metadata layers `@Metadata.layer` participates in annotation layering and precedence. Select the layer that matches ownership of the artifact rather than using one value for every extension without understanding its purpose. In a custom application, `#CORE` commonly represents the application owner's base UI semantics. Partner and customer adaptation layers have different ownership expectations where supported. ### 3.4 Metadata extension does not execute ABAP An MDE can: - place fields in a list report or object page; - define labels, importance, facets, and action placement; - describe text and value-help behavior; - hide a field from a generated UI; - instruct a client about refresh dependencies. It cannot: - calculate `NetAmount`; - reject an invalid Customer as a universal BO invariant; - authorize a user; - commit a transaction; - update a database table; - create a service endpoint. --- ## 4. Core Fiori Elements Annotations ### 4.1 `@UI.lineItem` Controls columns or actions in a list/table presentation: ```abap @UI.lineItem: [ { position: 10, importance: #HIGH } ] RequestNumber; ``` Typical use: ```text List report table RequestNumber | Customer | Status | TotalAmount ``` `position` establishes relative order. `importance` helps responsive clients decide what to retain when screen space becomes constrained. ### 4.2 `@UI.identification` Defines fields or actions associated with the object identity/detail area: ```abap @UI.identification: [ { position: 10 } ] RequestNumber; ``` It is commonly rendered on an object page, but exact rendering remains a consumer responsibility. ### 4.3 `@UI.selectionField` Defines fields proposed for the filter bar: ```abap @UI.selectionField: [ { position: 10 } ] Status; ``` This makes the field available prominently for selection. It does not add a backend authorization restriction. ### 4.4 `@UI.facet` Defines object-page sections and navigation structure: ```abap @UI.facet: [ { id: 'General', purpose: #STANDARD, type: #IDENTIFICATION_REFERENCE, label: 'General Information', position: 10 }, { id: 'Items', purpose: #STANDARD, type: #LINEITEM_REFERENCE, label: 'Items', position: 20, targetElement: '_Items' } ] RequestUUID; ``` The Item facet requires a valid projected composition and service navigation. An annotation cannot compensate for a broken `_Items` relationship. ### 4.5 `@UI.fieldGroup` Groups related fields into a reusable UI collection: ```abap @UI.fieldGroup: [ { qualifier: 'Commercial', position: 10 } ] SoldToParty; ``` A facet can reference the qualified group to form an object-page section. ### 4.6 `@UI.hidden` ```abap @UI.hidden: true LocalLastChangedAt; ``` This removes the field from ordinary generated presentation. The field can still remain in OData metadata and be used technically, for example as an ETag. UI hiding is not a security control. --- ## 5. Complete Root Metadata Example ```abap @Metadata.layer: #CORE @UI.headerInfo: { typeName: 'Sales Order Request', typeNamePlural: 'Sales Order Requests', title: { type: #STANDARD, value: 'RequestNumber' }, description: { value: 'Status' } } annotate entity ZC_SalesOrderRequest with { @UI.facet: [ { id: 'General', purpose: #STANDARD, type: #IDENTIFICATION_REFERENCE, label: 'General Information', position: 10 }, { id: 'Items', purpose: #STANDARD, type: #LINEITEM_REFERENCE, label: 'Items', position: 20, targetElement: '_Items' } ] RequestUUID; @UI: { lineItem: [ { position: 10, importance: #HIGH } ], identification: [ { position: 10 } ] } @EndUserText.label: 'Request' RequestNumber; @UI: { lineItem: [ { position: 20, importance: #HIGH } ], identification: [ { position: 20 } ], selectionField: [ { position: 10 } ] } @EndUserText.label: 'Sold-to Party' SoldToParty; @UI: { lineItem: [ { position: 30, importance: #HIGH } ], identification: [ { position: 30 } ], selectionField: [ { position: 20 } ] } Status; @UI: { lineItem: [ { position: 40, importance: #HIGH } ], identification: [ { position: 40 } ] } TotalAmount; @UI.hidden: true RequestUUID; @UI.hidden: true LocalLastChangedAt; } ``` The amount/currency relationship should already exist in the CDS semantic model. The UI annotation places `TotalAmount`; it does not need to recreate the calculation. --- ## 6. Child Metadata and Composition Rendering ```abap @Metadata.layer: #CORE annotate entity ZC_SalesOrderItem with { @UI.lineItem: [ { position: 10, importance: #HIGH } ] Product; @UI.lineItem: [ { position: 20, importance: #HIGH } ] RequestedQuantity; @UI.lineItem: [ { position: 30, importance: #MEDIUM } ] UnitPrice; @UI.lineItem: [ { position: 40, importance: #HIGH } ] NetAmount; @UI.hidden: true ItemUUID; @UI.hidden: true RequestUUID; @UI.hidden: true LocalLastChangedAt; } ``` For the object page to render editable Items correctly, all of these layers must align: ```text Base CDS composition → base BDEF create-by-association → projected CDS redirection → projected BDEF association create → service entity exposure/navigation → root facet targets `_Items` → child has `@UI.lineItem` ``` A problem at any layer can appear as a missing table, missing Create button, empty navigation, or read-only child section. --- ## 7. UI Actions ### 7.1 Action placement The action must exist in base behavior and be used in the behavior projection. Metadata can then place it: ```abap @UI.lineItem: [ { type: #FOR_ACTION, dataAction: 'Submit', label: 'Submit', position: 50 } ] RequestNumber; ``` Action naming in metadata must match the service-visible action name, including any projection aliasing or external naming. ### 7.2 End-to-end action visibility ```text Base BDEF action Submit │ ▼ Behavior Projection use action Submit │ ▼ OData metadata action import/bound action contract │ ▼ UI annotation #FOR_ACTION + dataAction │ ▼ Fiori button ``` ### 7.3 Feature control Instance feature control can disable Submit when Status is already Submitted. The UI consumes the result and adjusts affordance. Backend behavior remains the source of truth; do not implement the state rule only as frontend visibility. --- ## 8. Texts and Text Arrangement ### 8.1 Code and description Business fields often contain a compact key and a human-readable text: ```text Product = HT-1000 ProductName = Notebook Basic 15 ``` CDS associations and text annotations allow consumers to present both without copying the text into transactional persistence. ### 8.2 Text arrangement ```abap @UI.textArrangement: #TEXT_LAST Product; ``` Possible arrangements depend on supported metadata and can favor: - key only; - text only; - text followed by key; - key followed by text. The annotation controls presentation. It does not change the stored Product ID. ### 8.3 Historical snapshot boundary Use a live association when the UI should show the current master-data text. Persist a copied description only when the transaction has a genuine historical snapshot requirement. Those are different domain semantics. --- ## 9. Value Help ### 9.1 Purpose A value help connects an input field to a lookup provider: ```abap @Consumption.valueHelpDefinition: [ { entity: { name: 'ZI_CustomerValueHelp', element: 'CustomerID' } } ] SoldToParty; ``` The consumer can query the provider, display key/text/filter columns, and copy the selected key into `SoldToParty`. ### 9.2 Provider model ```abap @EndUserText.label: 'Customer Value Help' @ObjectModel.resultSet.sizeCategory: #XS define view entity ZI_CustomerValueHelp as select from ZI_CustomerReference { key CustomerID, CustomerName, CountryCode } ``` A good value-help provider has: - stable key element; - useful descriptive text; - fields required for search/filter/display; - correct authorization behavior; - an appropriate result-set shape and size strategy; - no accidental exposure of sensitive master data. ### 9.3 Service exposure The value-help provider must be reachable through the service contract when the consumer needs to query it. In many RAP OData services, that means exposing the provider entity in the service definition: ```abap expose ZI_CustomerValueHelp as CustomerValueHelp; ``` Defining the annotation alone does not publish an entity set. ### 9.4 `useForValidation: true` ```abap @Consumption.valueHelpDefinition: [ { entity: { name: 'ZI_CustomerValueHelp', element: 'CustomerID' }, useForValidation: true } ] SoldToParty; ``` This marks the value-help definition for validation of user input. Supported consumer/framework processing can check entered values against the provider's allowed result set. It does not replace a RAP behavior validation when: - validity depends on Status, date, Sales Area, role, or other BO state; - the rule must protect direct EML and every service projection; - the provider list is a convenience subset rather than the domain truth; - the rule requires a precise backend error message; - security or transactional consistency is involved; - the referenced object can change between input and save. Use value-help validation for the lookup constraint and backend validation for the durable business invariant. ### 9.5 Additional binding A value help can pass context fields into or out of the provider, for example filtering Product by Sales Organization or returning a related Unit. Model those bindings explicitly and ensure their fields are exposed in the service metadata. Do not hide a missing business determination inside a value-help side effect. Returned values should have a clearly owned source of truth. --- ## 10. Why a Service Definition May Expose Reference Entities Representative Travel service: ```abap define service ZUI_TRAVEL { expose ZC_Travel as Travel; expose ZC_Booking as Booking; expose ZI_AgencyVH as Agency; expose ZI_CustomerVH as Customer; expose ZI_FlightVH as Flight; expose I_Currency as Currency; expose I_Country as Country; } ``` Reference entities can be exposed because the consumer needs them for: - value-help queries; - text retrieval; - direct navigation targets; - filtering or autocomplete; - dependent lookup fields; - service metadata relationships; - an API operation that legitimately reads the reference collection. Do not expose every CDS association automatically. Expose an entity when the service contract requires it and when its authorization/data surface is safe. The correct rule is broader than “expose it only when it appears as a scalar field in the projection.” A provider may need exposure even when used through value help or navigation rather than displayed as a root field. --- ## 11. Service Definition ### 11.1 Responsibility A service definition is a protocol-independent repository object that groups the CDS entities exposed by one business service. ```abap @EndUserText.label: 'Sales Order Request UI Service' @ObjectModel.leadingEntity.name: 'ZC_SalesOrderRequest' define service ZUI_SALESORDERREQUEST { expose ZC_SalesOrderRequest as SalesOrderRequests; expose ZC_SalesOrderItem as SalesOrderItems; expose ZI_CustomerValueHelp as Customers; expose ZI_ProductValueHelp as Products; expose I_Currency as Currencies; } ``` The service definition decides: - which entity models belong to this service; - their service-visible aliases; - the primary/leading entity where declared; - which navigation and lookup targets can become reachable. It does not decide: - whether the service uses OData V2 or V4; - whether it is a UI service or Web API; - the HTTP endpoint URL; - how CRUD is implemented; - whether the current user is authorized; - whether the service is published. ### 11.2 Service aliases ```abap expose ZC_SalesOrderRequest as SalesOrderRequests; ``` The alias decouples the external entity-set name from the CDS technical object name. Choose a stable consumer-oriented name and treat changes as API contract changes. ### 11.3 Complete service graph For a composition-based UI, expose all nodes needed by the business service. The root alone is not always sufficient when child entity sets, navigation, metadata, or value helps must be reachable. At the same time, exposure should be minimal. Every extra entity adds: - metadata and compatibility surface; - possible direct query access; - authorization and performance responsibility; - maintenance and release obligations. --- ## 12. Service Binding ### 12.1 Responsibility A service binding assigns the service definition to a supported protocol and service category. ```text Service Definition protocol-independent model │ ├── OData V4 UI binding ├── OData V4 Web API binding └── another supported binding type ``` One service definition can be used by multiple bindings when the same service contract is appropriate. If UI and integration consumers require materially different fields, operations, versioning, or lifecycle promises, use separate projections and often separate service definitions rather than forcing one oversized contract. ### 12.2 OData V4 UI Designed for metadata-driven user interfaces such as Fiori elements. It consumes UI annotations, draft metadata, actions, value helps, side effects, messages, field control, and navigation. ### 12.3 OData V4 Web API Designed for machine-to-machine consumption. Its contract should emphasize: - stable external names; - explicit operation semantics; - controlled versioning; - predictable messages and HTTP outcomes; - API authorization; - idempotency and concurrency behavior; - minimal UI-specific metadata. A UI projection is not automatically a good public API merely because both use OData V4. ### 12.4 OData V2 and `@OData.publish: true` Older examples often use OData V2 or `@OData.publish: true`. Current RAP design normally favors explicit service definitions and bindings because they provide a clearer service contract, category, protocol choice, versioning, and publication lifecycle. Do not copy an older workshop's V2 binding solely because the sample predates OData V4 support. Confirm the target ABAP release and consumer requirement. --- ## 13. Metadata Request Runtime ```text Fiori client requests $metadata │ ▼ Published Service Binding │ ▼ Service Definition exposed entity aliases and relationships │ ▼ CDS Projection + Behavior Projection fields, navigation, actions, field/ETag/draft contract │ ▼ Metadata Extension + annotations line items, facets, labels, value help, side effects │ ▼ OData metadata document │ ▼ Fiori elements generates list/object-page behavior ``` No behavior-pool method is normally called merely to compile static metadata. Dynamic feature or authorization requests occur when the client asks for the corresponding runtime permissions or data. ### 13.1 Metadata caching After changing CDS, behavior projection, or annotations: - activate all dependent artifacts; - verify the intended service version is published; - inspect live `$metadata` rather than only source code; - refresh or clear relevant client metadata caches; - confirm the browser is calling the expected endpoint. Many apparent annotation defects are stale-metadata defects. --- ## 14. Query and Navigation Runtime ### 14.1 List report read ```text Fiori GET SalesOrderRequests → OData V4 binding → service entity alias → CDS transactional query projection → CDS access control and query runtime → database query → OData response → lineItem rendering ``` The normal CDS-backed query path does not require a behavior-pool read method for a managed query. ### 14.2 Object-page navigation ```text Select one Request → GET by key → object-page identification/facets rendered → expand or navigate `_Items` → projected composition target → child query → child line items rendered ``` ### 14.3 Value-help request ```text User opens SoldToParty value help → metadata identifies provider entity/element → client queries Customers entity set → DCL and service authorization apply → search/filter/order/page options processed → key and text returned → selected CustomerID copied to SoldToParty ``` The provider may return no values because of authorization or filters even when the underlying table contains records. --- ## 15. Side Effects ### 15.1 Purpose Side effects describe which fields, entities, permissions, or messages should be refreshed after a source value or action changes. ```text RequestedQuantity changes → determination recalculates NetAmount → root aggregation recalculates TotalAmount → side-effect metadata tells UI what to reread ``` The determination performs the calculation. The side effect synchronizes the consumer presentation with backend state. ### 15.2 Representative declaration Exact supported syntax depends on the BDEF and target release, but the model is: ```abap side effects { field RequestedQuantity affects field NetAmount; field UnitPrice affects field NetAmount; action Submit affects field Status, permissions ( action Submit ); } ``` Cross-entity dependencies can require association or entity targets supported by the release and service protocol. ### 15.3 Side effects are not determinations ```text Determination changes backend BO state Side effect declares consumer refresh dependency ``` If a side effect exists but no backend logic updates `NetAmount`, the reread returns the same value. If determination exists but side effects are missing, the backend state can be correct while the UI continues showing an old value. --- ## 16. Security Boundaries ### 16.1 UI hiding `@UI.hidden: true` controls presentation. A malicious or custom client can still inspect or request an OData property if the service exposes it and the protocol permits access. ### 16.2 Projection omission Omitting `InternalProcessingCode` from the CDS projection removes it from that service contract. This is stronger than UI hiding but still does not replace authorization for remaining fields and operations. ### 16.3 CDS DCL DCL restricts readable rows for the CDS entity where it is applied. Test the actual consumption entity; do not assume access controls automatically propagate through every view stack. ### 16.4 RAP authorization RAP authorization controls create, update, delete, associations, actions, and other modifying capabilities based on the current user and context. ### 16.5 Value-help security A value-help entity is a query surface. Apply appropriate authorization and expose only the columns needed for selection. Do not treat lookup data as automatically harmless. ```text UI annotation presentation Projection contract surface DCL read-row restriction RAP authorization modify-operation permission Backend validation business invariant ``` All five can be required in one service. --- ## 17. Activate, Publish, Transport, and Deploy ### 17.1 Activate Creates the active repository version after syntax and dependency checks. ```text CDS/MDE/BDEF/service source → Activate in ADT → active ABAP repository object ``` Activation does not make an OData endpoint externally available by itself. ### 17.2 Publish Publishing a service binding enables/registers the service endpoint in the connected ABAP system according to that environment's lifecycle. ```text Active service definition + binding → Publish → callable local system endpoint/version ``` ### 17.3 Transport Transport moves repository and configuration artifacts through the system landscape, for example development to quality to production. Local publication status and environment-specific service setup can still require lifecycle handling in each target system. ### 17.4 Deploy Deployment often refers to delivering a separate frontend application to its runtime or making a complete solution available. It is not a synonym for ABAP artifact activation. ```text Activate repository code becomes active in one ABAP system Publish service endpoint becomes available in that system Transport artifacts move between ABAP systems Deploy separate application/content reaches its target runtime ``` --- ## 18. Fiori Elements Preview The service-binding editor can launch a Fiori elements preview for suitable UI services. Preview is valuable for validating: - entity-set availability; - list report columns; - object-page facets; - composition navigation; - value helps; - draft actions; - action placement; - field control and messages; - side-effect refresh. Preview is not a substitute for a production Fiori application. It does not prove: - launchpad role/catalog configuration; - semantic-object and target-mapping correctness; - production authorization roles; - frontend deployment and routing; - accessibility and UX review; - API compatibility; - performance under real volume. --- ## 19. End-to-End Sales Order Request UI Flow ### 19.1 Open list report ```text 1. Browser loads Fiori elements application. 2. Client requests OData `$metadata`. 3. Service binding resolves ZUI_SALESORDERREQUEST. 4. Metadata describes SalesOrderRequests, Items, actions, value helps, and UI. 5. Client requests SalesOrderRequests with query options. 6. RAP query runtime reads ZC_SalesOrderRequest under DCL. 7. `@UI.lineItem` fields form the table. ``` ### 19.2 Create request draft ```text 1. Create visibility comes from projected behavior. 2. Client creates a draft root. 3. Managed RAP assigns RequestUUID and persists draft state. 4. Object page uses headerInfo and identification annotations. 5. SoldToParty value help queries the exposed Customers provider. 6. Item facet navigates through projected `_Items` composition. ``` ### 19.3 Change quantity ```text 1. UI PATCH changes RequestedQuantity on draft Item. 2. Behavior determination recalculates NetAmount and TotalAmount. 3. Side-effect metadata tells UI to reread affected fields. 4. Refreshed values are formatted with unit/currency semantics. 5. No active business data changes until activation. ``` ### 19.4 Submit ```text 1. Action exists in base BDEF and behavior pool. 2. Behavior projection exposes Submit. 3. UI annotation renders the action button. 4. Instance feature control enables it for eligible Status. 5. RAP authorization checks the user's permission. 6. Handler changes buffered state and returns action result/messages. 7. Draft Prepare/Activate validations protect final persistence. 8. UI refreshes Status and action permissions. ``` --- ## 20. Technical Diagnostics ### 20.1 Entity is absent from the service Check: ```text CDS projection active → service definition `expose` → correct service alias → service binding references intended definition/version → binding published → live `$metadata` → client endpoint and cache ``` ### 20.2 Field is absent Check: 1. base CDS element; 2. CDS projection list; 3. active metadata annotations; 4. service metadata property; 5. UI annotation placement; 6. client personalization and cache. If the property is absent from `$metadata`, the defect is before UI rendering. ### 20.3 Create/Edit/Delete button is missing Check: 1. base BDEF operation; 2. behavior projection `use` declaration; 3. draft actions if draft is enabled; 4. dynamic feature result; 5. RAP authorization result; 6. current service metadata; 7. Fiori page mode and client cache. ### 20.4 Action button is missing Trace: ```text Base action declaration → behavior-pool method → behavior projection `use action` → service-visible action name → `@UI.lineItem` or `@UI.identification` action annotation → feature control → live metadata ``` ### 20.5 Item facet is empty Check: - root facet `targetElement` spelling; - projected composition redirection; - child projection and service exposure; - active/draft navigation context; - parent/child keys and `ON` condition; - DCL on child query; - whether Items exist in the relevant active/draft state. ### 20.6 Value-help icon or values are missing Check: 1. active `@Consumption.valueHelpDefinition`; 2. exact provider entity and element names; 3. provider exposed/reachable in the service; 4. provider appears in `$metadata`; 5. DCL/authorization permits provider rows; 6. additional-binding fields exist and contain values; 7. search/filter metadata and data types are compatible; 8. browser calls the expected endpoint. ### 20.7 Value accepted by UI but save fails This can be correct when value help and business validation enforce different rules. Capture: - selected provider row; - `useForValidation` setting; - current BO Status, Sales Area, date, and other context; - backend validation message; - whether the reference changed between selection and save. The business validation remains authoritative. ### 20.8 Derived value changes in backend but not UI Check: ```text Determination actually updates buffer → nested EML messages/failures → side-effect source field/action → affected target field/entity → target property exposed → UI reread network request → response value and metadata cache ``` ### 20.9 Works in preview but not launchpad Inspect the application-level delivery chain: - deployed frontend application/component; - destination and service URL; - OData service activation/publication in the target system; - launchpad catalog and role; - semantic object and action; - target mapping; - user frontend/backend authorizations; - cache and gateway error logs; - transport completeness. Preview proves the local service/UI metadata path, not the full launchpad setup. --- ## 21. UI and API Contract Design ### 21.1 Separate contracts when promises differ ```text UI service draft editing UI annotations role-specific actions user-facing state messages Web API versioned stable schema machine-oriented operation names explicit concurrency requirements integration authorization minimal navigation and lookup surface ``` Reusing one service definition can be appropriate for closely aligned consumers. Separate projections are appropriate when the contract lifecycle and exposed capabilities differ materially. ### 21.2 Avoid exposing implementation details Do not expose: - internal processing codes without a consumer contract; - raw administrative fields that consumers do not need; - direct write access to derived fields; - unrestricted master-data lookup collections; - legacy persistence names as public API names; - actions whose semantics are not stable. ### 21.3 Versioning Treat service aliases, field types, nullability, actions, navigation paths, and message behavior as compatibility surface. A published Web API requires a stronger compatibility policy than a private preview service. --- ## 22. Exposure Review Checklist ### Projection - CDS projection contains only consumer-relevant fields and navigation. - `transactional_query` provider contract is explicit. - Compositions and parents redirect to projected nodes. - Behavior projection exposes only required operations and actions. - Derived/internal fields have consistent behavior and visibility. - UI and API consumers use separate contracts when their promises differ. ### Metadata - UI annotations are stored in metadata extensions where practical. - Header, line item, identification, filters, and facets reflect the entity grain. - Item facet targets a valid projected composition. - Technical fields are hidden for presentation but retained when runtime needs them. - Action metadata matches the service-visible action name. - Text associations and arrangements do not change stored identity. ### Value help and side effects - Lookup provider exposes only needed, authorized fields. - Provider and key element are reachable in the service. - `useForValidation` is used intentionally and not confused with BO validation. - Additional bindings pass complete context. - Determinations calculate; side effects trigger consumer refresh. - Cross-entity refresh is verified through actual network responses. ### Service - Service definition exposes the complete required graph and no accidental entities. - External aliases are stable and consumer-oriented. - Binding type matches UI or API use. - Intended service version is active and published. - Live `$metadata` is reviewed after changes. - Transport and frontend deployment requirements are documented separately. ### Security - UI hiding is never treated as access control. - Projection omission, DCL, RAP authorization, and validation are all applied at their proper boundaries. - Value-help endpoints are treated as data APIs. - Preview and launchpad authorization are tested independently. --- ## 23. Compact Exposure Map ```text BASE RAP BO ZI_SalesOrderRequest + Base BDEF + Behavior Pool reusable data, operations, invariants, transaction handling │ ▼ SERVICE PROJECTION ZC_SalesOrderRequest CDS fields/navigation Projection BDEF use CRUD/actions/draft Metadata Extension lineItem/facet/value help/action/side effect │ ▼ SERVICE DEFINITION SalesOrderRequests SalesOrderItems Customers value help Products value help Currencies │ ▼ SERVICE BINDING OData V4 UI Fiori elements metadata-driven application OData V4 Web API machine-oriented integration contract │ ▼ RUNTIME $metadata contract and annotations GET CDS query + DCL PATCH/POST/action RAP behavior + authorization + transaction value-help GET lookup provider query side-effect reread synchronize UI with backend derivation ``` The consumer layer should always be read through five separate concerns: ```text Projection narrows the reusable BO. Metadata describes presentation. Service definition selects entity exposure. Service binding selects protocol and service category. Backend behavior and authorization protect correctness. ``` 53:T89e,SAP RAP Service Exposure and Fiori Elements — Technical Reference This document explains how a reusable RAP business object becomes a consumer-facing OData service and a metadata-driven SAP Fiori elements application. It covers service projections, behavior projections, metadata extensions, value helps, side effects, service definitions, service bindings, OData V4 UI and Web API contracts, publication, and runtime diagnosis. The central exposure principle is: A service projection defines the data and behavior contract for one consumption scenario. A service definition groups the entities exposed by that contract. A service binding chooses the protocol and service category. UI annotations describe presentation; they do not implement or secure the underlying business rules. Primary SAP sources: - SAP Help — Business Object Projection - SAP Help — Metadata-Driven UI Annotations - SAP Help — Providing Value Help - SAP Help — Side Effects - SAP Help — Service Definition - SAP Help — Business Service - SAP Help — OData V4 Service Binding Editor --- 1. Consumer-Facing RAP Stack text Reusable RAP BO Base CDS + Base BDEF + Behavior Pool │ ▼ Service Projection CDS Projection + Behavior Projection │ ├──────── Metadata Extension │ UI semantics │ ▼ Service Definition entity exposure and service aliases │ ▼ Service Binding OData V4 UI / OData V4 Web API / other supported type │ ▼ Published endpoint and metadata │ ┌─────────┴─────────┐ ▼ ▼ Fiori elements UI External API consumer Each artifact makes a different decision: | Artifact | Decision | | ------------------- | ----------------------------------------------------------- | | CDS projection | Which fields and relationships this consumer sees | | Behavior projection | Which BO capabilities this consumer may call | | Metadata extension | How a metadata-driven UI presents the model | | Service definition | Which CDS entities belong to the service | | Service binding | Which protocol and service category expose it | | Fiori application | How users navigate and interact with the published contract | The service layer does not replace54:Ta1a,# SAP RAP Service Exposure and Fiori Elements — Technical Reference This document explains how a reusable RAP business object becomes a consumer-facing OData service and a metadata-driven SAP Fiori elements application. It covers service projections, behavior projections, metadata extensions, value helps, side effects, service definitions, service bindings, OData V4 UI and Web API contracts, publication, and runtime diagnosis. The central exposure principle is: > A service projection defines the data and behavior contract for one > consumption scenario. A service definition groups the entities exposed by > that contract. A service binding chooses the protocol and service category. > UI annotations describe presentation; they do not implement or secure the > underlying business rules. Primary SAP sources: - [SAP Help — Business Object Projection](https://help.sap.com/docs/abap-cloud/abap-rap/business-object-projection-6e7a10d30b74412a9482a80b0b88e005-194) - [SAP Help — Metadata-Driven UI Annotations](https://help.sap.com/docs/abap-cloud/abap-rap/defining-cds-annotations-for-metadata-driven-uis) - [SAP Help — Providing Value Help](https://help.sap.com/docs/abap-cloud/abap-rap/providing-value-help-for-selection-fields) - [SAP Help — Side Effects](https://help.sap.com/docs/abap-cloud/abap-rap/side-effects) - [SAP Help — Service Definition](https://help.sap.com/docs/abap-cloud/abap-rap/service-definition) - [SAP Help — Business Service](https://help.sap.com/docs/abap-cloud/abap-rap/business-service) - [SAP Help — OData V4 Service Binding Editor](https://help.sap.com/docs/abap-cloud/abap-development-tools-user-guide/using-service-binding-editor-for-odata-v4-service) --- ## 1. Consumer-Facing RAP Stack ```text Reusable RAP BO Base CDS + Base BDEF + Behavior Pool │ ▼ Service Projection CDS Projection + Behavior Projection │ ├──────── Metadata Extension │ UI semantics │ ▼ Service Definition entity exposure and service aliases │ ▼ Service Binding OData V4 UI / OData V4 Web API / other supported type │ ▼ Published endpoint and metadata │ ┌─────────┴─────────┐ ▼ ▼ Fiori elements UI External API consumer ``` Each artifact makes a different decision:55:T5d84, ### Càng cố gắng, tôi thấy mình càng đứng yên Bản thân tôi không phải người dễ bỏ cuộc, tuy nhiên lần này tôi cảm nhận rõ bản thân đang quá tải. Có lẽ cảm giác burnout không đến từ một khoảnh khắc, mà nó được tích tụ sau một thời gian dài mọi thứ liên tục diễn ra không như mong đợi. Tôi có vài trải nghiệm không được tốt lắm ở công ty gần nhất tôi làm việc, tôi vẫn nhớ như in cái cảm giác vào ngày cuối cùng làm việc ở đó, thay vì lo sợ hành trình sắp tới sẽ ra sao, tôi lại thấy bình yên đến lạ, như trút được gánh nặng vậy. Tôi cũng không vội đi tìm việc mới, thử nghiệm làm vài mô hình “startup 1 người” mà mình đã nghĩ đến trước đó. Tôi cũng nhận triển khai các mô hình AI Automation, n8n trên thị trường freelance và học một ngách mới - SAP. Tôi sẽ kể chi tiết hơn trong một bài viết khác. Nghề nghiệp của tôi thay đổi quá nhanh, tôi cũng cố gắng chạy theo, học liên tục để không bị outdate, nhưng tôi phải thừa nhận, mình không đuổi kịp với tốc độ phát triển của các công cụ AI. Nhu cầu khách hàng cũng giảm mạnh vì giờ đây AI đã đủ thông minh để triển khai được thứ họ muốn chỉ với vài prompt, không cần một người đứng trung gian như mình. Dù đã dành rất nhiều thời gian và công sức, kết quả vẫn không đạt được như kỳ vọng. Dần dần, tôi bắt đầu tự hỏi những gì mình đang làm có thật sự mang lại ý nghĩa gì không. Sau những cú trượt dài của mình, tôi gom phần năng lượng còn lại để lên chiến lược cho các buổi phỏng vấn, quay về môi trường công sở trước đó; khi thị trường có cung lớn hơn cầu thì kế hoạch của tôi là làm sao để mình nổi bật nhất trong đống hồ sơ ứng viên. Thay vì chỉ gửi một chiếc CV nhàm chán thì tôi gửi hẳn một cái web kèm với video giới thiệu trên đó. Và nó thật sự hiệu quả, nó đã giúp tôi bước chân vào được 3 buổi phỏng vấn trong thị trường đang bão hoà này. Tôi nhận được offer. Có lẽ đây là điều duy nhất diễn ra đúng với kỳ vọng của tôi trong khoảng thời gian gần đây. Tôi vui và nhẹ nhõm, nhưng niềm vui ấy không đủ để lập tức lấp đầy sự mệt mỏi đã tích tụ từ trước. Cảm giác mệt mỏi không bùng lên dữ dội mà âm thầm rút cạn năng lượng của tôi. Thêm nữa là thời gian khó khăn này, tôi không cảm nhận được ai xung quanh đồng cảm với tôi cả. Tôi không còn muốn bắt đầu một dự án mới, không muốn tiếp tục cố gắng, thậm chí chẳng còn hứng thú với những điều mình từng rất thích. Tôi vẫn có thể làm việc, vẫn có thể tiếp tục chạy, nhưng bên trong chỉ còn lại sự chán chường và trống rỗng. Có lẽ đó là lúc tôi nhận ra: mình cần dừng lại một chút. ### Không kế hoạch, không kỳ vọng, cứ thế mà đi Tôi bắt đầu nghĩ đến chuyện rời khỏi Sài Gòn một vài ngày. Không phải để tìm kiếm cảm hứng, chữa lành hay trở về với một phiên bản tốt hơn của chính mình. Tôi chỉ muốn đi đâu đó đủ xa khỏi những con đường quen thuộc, tạm rời màn hình, công việc và những suy nghĩ cứ lặp đi lặp lại trong đầu. Nói vui một chút, tôi muốn đi “chạm cỏ”, nhưng lần này phải là cỏ ở một thành phố khác. Trước đây, mỗi khi đi đâu, làm gì, tôi thường lên kế hoạch rất kỹ: sẽ xuất phát lúc nào, ở đâu, ăn gì, ghé những địa điểm nào và phải làm được bao nhiêu thứ trong một ngày. Nhưng phần lớn các chuyến đi lại không diễn ra đúng như những gì tôi hình dung. Lần này tôi quyết định không chuẩn bị một lịch trình cụ thể. Không có danh sách những nơi nhất định phải đến, cũng không suy nghĩ mục tiêu gì nhiều. Tôi chỉ mang theo những thứ cần thiết, chọn một điểm đến rồi lên đường. Mệt thì dừng, thích nơi nào thì ở lại lâu hơn, thấy một con đường thú vị thì rẽ vào. Thậm chí tôi còn không biết trưa hôm đó ăn gì hay tối ngủ ở đâu nữa. Tôi vốn là một người không giỏi ứng biến, có lẽ vì thế trước đây tôi luôn muốn lên kế hoạch để cố gắng kiểm soát mọi thứ. Nhưng tôi nhận ra một điều, càng lên kế hoạch kỹ thì mình sẽ mang một sự kỳ vọng rất lớn. Chính vì lẽ đó, tôi thường cảm thấy hụt hẫng, thất vọng khá nhiều khi mọi thứ bị chệch khỏi đường ray. Và lần này, khi để mọi thứ tự nhiên xảy ra, tôi lại có ấn tượng tốt hơn về những nơi mà tôi không kỳ vọng nhiều ban đầu. Tuy nhiên, tôi cũng đặt ra vài luật cho mình: không được ngủ thiếu giấc vì đi dài ngày, không chạy khuya, mệt thì nghỉ, không ráng, tuân thủ tốc độ trong mức kiểm soát, thậm chí nơi nào đẹp thì dừng lại ngắm cảnh một tí, đến nơi trễ một tí cũng được, chả ảnh hưởng đến ai. Và đây cũng là lý do tôi thích đi một mình. ### Rời thành phố, bắt đầu hành trình Tôi bắt đầu hành trình từ Sài Gòn và lựa chọn sẽ đi theo cung đường biển. Dù sao đây cũng là một chuyến đi để giải toả, chạy mãi trên quốc lộ cùng với xe tải và lượng lớn xe khác, có lẽ chỉ khiến tôi mệt thêm. Tôi muốn nhìn thấy biển, muốn cảm nhận không khí trong lành thêm một tí gió trên đường; không biết sao nhưng mỗi lần đứng trước sự to lớn của thiên nhiên, tôi đều cảm thấy mình nhỏ bé và mọi lo âu của mình cũng được thu hẹp lại. Điểm đến đầu tiên tôi chọn là Bàu Trắng. Đây không phải lần đầu tôi đến nơi này. Trong chuyến đi trước, tôi đã bị hút hồn bởi khung cảnh nơi đây, lúc mà bãi biển đột nhiên xuất hiện trước mắt, cảnh vật như thay đổi ngay tức khắc, tiếp đến là con đường thẳng tắp với một bên là đồi cát trải dài và một bên là biển xanh, cảnh tượng nếu tôi ngồi trên xe khách, chắc khó mà cảm nhận được. ![[../images/healing-bau-trang.jpeg]] Tôi nghỉ chân một lát, ăn quán ăn địa phương, ghé vào ngẫu nhiên, chọn một món ăn đơn giản, nhưng bất ngờ là rất hợp khẩu vị. Nghỉ chân xong, tôi tiếp tục tiến thẳng. Rời Bàu Trắng, tôi tiếp tục hướng về Ninh Thuận. Dù đây là một chuyến đi không được lên kế hoạch, nhưng tôi cũng có một danh sách các nơi mà mình đã muốn đến từ lâu. Qua những hình ảnh trên mạng, con đường hiện ra một vùng biển xanh, tiếp đến là dãy núi khô cằn, sỏi đá, mang một vẻ đẹp hoang sơ rất riêng. Tôi đã biết đến cung đường này từ khá lâu nhưng chưa từng có dịp tự mình chạy qua. Vì thế, Ninh Thuận trở thành điểm tiếp theo của hành trình. ### 13 km dài nhất trong chuyến đi Nhưng chuyến đi không kế hoạch cũng đồng nghĩa với việc tôi phải sẵn sàng cho những chuyện ngoài dự tính. Trên đường đi, chiếc xe bắt đầu gặp vấn đề: hụp ga, máy yếu và cứ chạy được một lúc lại tắt. Cảm giác lúc ấy giống như xe sắp hết xăng, dù trong bình vẫn còn. Ban đầu, tôi nghĩ có thể do chạy đường dài khiến máy quá nóng nên tìm một tiệm sửa xe gần đó để kiểm tra và thay nhớt. Đây là lần đầu tôi gặp sự cố lớn vậy, khá bế tắc cho một chuyến solo trip. Nhưng thay nhớt xong, tình hình vẫn không khá hơn. Chiếc xe tiếp tục hụp ga, còn tiệm sửa cũng không có đủ dụng cụ để kiểm tra kỹ. Tôi nghĩ mình xong rồi. Tôi định tìm một nhà nghỉ gần đó và ở lại qua đêm. Nhưng rồi lại nghĩ, nếu ở đây thì sáng hôm sau tôi vẫn không biết phải xử lý chiếc xe thế nào. Anh chủ tiệm khuyên tôi nên cố chạy thêm khoảng 12 km vào trung tâm Phan Rí để nghỉ ngơi và cũng dễ sửa loại xe của tôi hơn. Tôi cố đèo người bạn đồng hành của mình đi tiếp, tốc độ có lúc lên được 40km/h xong hụp xuống 10 km/h, cảm giác như xe không có xăng vậy, có thể tắt máy bất cứ lúc nào. Tôi cố được 3km thì bỏ cuộc và quyết định nhờ sự trợ giúp. May mắn là tôi đã gặp anh Thiện. Anh dùng chiếc Wave của mình đẩy chiếc xe của tôi suốt gần 10 km còn lại vào trung tâm Phan Rí. Khung cảnh một chiếc Wave nhỏ đẩy một chiếc xe to hơn chạy dọc đường chắc nhìn từ bên ngoài cũng khá vui. Chiếc xe đầu tiên của tôi cũng là Wave, nó gợi nhớ cho tôi phết. Tôi ngủ lại ở một nhà nghỉ ngẫu nhiên tại Phan Rí, và vì tôi cũng không áp lực thời gian trong chuyến đi nên sự cố này cũng không quá làm ảnh hưởng tinh thần của mình, chỉ là không biết xe mình đang bị gì thôi. Sáng hôm sau tôi mang xe mình đến HEAD Hưng Thịnh, tôi là khách hàng đầu tiên, vừa mở cửa là tôi đã đẩy xe vào rồi. | | | | ------------------------------------ | ------------------------------------ | | ![[../images/healing-sua-xe-1.jpeg]] | ![[../images/healing-sua-xe-2.jpeg]] | Tôi miêu tả vấn đề, các anh kỹ thuật bắt đầu khám. Mở tung bugi đến bơm xăng rồi hỏi tôi có bơm xăng đểu không nữa (từ lúc có xăng e10 thì vấn đề này tôi không chắc), rút xăng ra, đổ xăng mới vào, và tình trạng vẫn thế. Không lẽ phải kết thúc hành trình và đưa xe về Sài Gòn sao ta. Sau khoảng 1h30p khám thì các anh mở kim phun xăng ra và phát hiện nó đã bị cháy. Cuối cùng đã tìm ra vấn đề. Nhưng vấn đề mới là tại HEAD không có linh kiện để thay, tôi lại tiếp tục ngồi chờ linh kiện được mang đến. Tôi mất tổng cộng 3h30p để ra khỏi tiệm sửa xe, các anh bảo đây là cái kim phun cuối cùng trong các chi nhánh ở đây. May mắn là xe tôi đã tiếp tục chạy được rồi. Tiếp tục hành trình thôi. Trên đường đi thì tôi suy nghĩ khá nhiều, là việc mình gặp sự cố ở đây cũng không hẳn là xui xẻo, vì nó chưa dẫn đến một hậu quả gì quá nghiêm trọng cả, tưởng tượng nếu xe tôi gặp sự cố trên Đèo Bảo Lộc thì…. đó thật sự là thảm hoạ. Đây cũng là bài học kinh nghiệm cho tôi trong những lần đi sau. ### Phía cuối đường mòn là biển Tôi tiếp tục lên đường khám phá Ninh Thuận. Ban đầu là dọc con đường biển, tiến thẳng đến Vĩnh Hy, nhưng đột nhiên tôi nhớ đến Công viên đá, vẫn còn sớm nên tôi đổi lịch trình khám phá nơi này. Đường vào không hề dễ đi, phần lớn là đường mòn với nhiều đất và sỏi đá, tôi phải chạy thật chậm và tập trung quan sát, xung quanh cũng không có người, nói thật là tôi cũng hơi sợ, nhất là lại vừa gặp sự cố với xe. Nhưng khi đến nơi, tôi biết quãng đường khó khăn ấy hoàn toàn xứng đáng. Trước mắt tôi là một không gian rộng lớn và gần như nguyên sơ: những khối đá với đủ hình dáng nằm rải rác bên bờ biển, phía trước là mặt nước kéo dài đến tận chân trời. Không hàng quán, không những công trình đông đúc, chỉ có đá, biển, gió và âm thanh của sóng. Đứng trên những vách đá nhìn ra biển, một lần nữa tôi cảm thấy mình thật nhỏ bé trước thiên nhiên. Nhưng sự nhỏ bé ấy không khiến tôi thấy lạc lõng. Ngược lại, nó làm những suy nghĩ vốn rất nặng nề trong đầu bỗng trở nên nhẹ hơn. Khá bất ngờ vì rất ít người ở đó, có lẽ là đi trong tuần, tôi thoải mái quay video rồi, làm đủ trò ở đấy. ![[../images/healing-cong-vien-da.jpg]] Sau khoảng 2 tiếng ở đây thì tôi chạy đến làng chài Vĩnh Hy, với mong muốn được thả lỏng nhìn cuộc sống thường ngày của một làng chài và dự định tối sẽ tá túc ở đây. Vịnh Vĩnh Hy trong suy nghĩ của tôi là một nơi cực kỳ thanh bình, là nơi mưu sinh của các cô chú làng chài, là hình ảnh mà tôi thường thấy trong những quyển sách giáo khoa. Khi đến nơi, tôi có hơi hụt hẫng, làng chài không to như tôi nghĩ, chỉ nằm gọn trên một con đường, khung cảnh nhìn ra thì rất thơ mộng, tôi bị hút hồn bởi những hình ảnh này trên truyền thông. Tuy nhiên, để bảo là khám phá thì, không có gì mấy. Cảm giác hụt hẫng có lẽ đến từ việc tôi đã kỳ vọng nhiều quá. Hoặc tôi đã tiếp cận Vĩnh Hy sai cách, hẹn Vĩnh Hy lần sau, chắc có lẽ ra khơi cùng dân địa phương sẽ mang lại trải nghiệm tốt hơn. ![[../images/healing-vinh-hy.jpg]] Tôi thay đổi ý định, đi tiếp, tôi tìm ngẫu nhiên trên Map và thấy Bãi Thùng cách tôi 20p đi xe, không suy nghĩ nhiều, tôi lên đường. Lại lần nữa, tôi lại rẽ vào một con đường gồ gề sỏi đá, cấp độ còn khó hơn trước. Độ dốc cao hơn, dễ ngã hơn, tôi cũng không biết phía trước là gì, thôi kệ đi tiếp. Băng qua chông gai ấy thì tôi đang đứng sát vách của biển. À ra đây là bãi tắm, biển trong vắt, tôi đi 1 mình nên không dám xuống tắm, xung quanh tôi cũng có 2-3 gia đình đi nghỉ mát ở đây. Tôi ngồi ở đó, không làm gì, chỉ hít thở, mặc kệ xung quanh luôn. Lúc đó đã khoảng gần 5 giờ chiều rồi, ngồi một lúc thì phải đứng dậy đi tiếp để tìm chỗ ngủ tối nay. Đi ra con đường sỏi đá lúc nãy, bây giờ là game khó hơn, chạy lên dốc nhưng đường là sỏi, không có độ bám. Sợ té nên tôi đi từ từ, nhưng xui sao chệch bánh phát, tôi xoè ngay đó. Hahah, biết ngay mà, xe tôi bị gãy gác chân trước và may mắn là tôi không sao, tinh thần cũng còn vững lắm, vẫn muốn đi tiếp. Tôi vẫn chưa quyết được là nên ở đâu tối nay. Quay lại Vịnh Vĩnh Hy thì cũng được nhưng tôi không có ấn tượng tốt. Tôi search map và thấy mình cách Nha Trang 2 tiếng chạy xe nữa. Đi luôn, tôi quyết định sẽ ngủ lại tại thành phố biển Nha Trang. ### Hóa ra đi du lịch không phức tạp đến thế Điểm dừng chân tiếp theo của tôi là thành phố Nha Trang. Trước chuyến đi này, tôi chỉ biết về nơi đây qua báo đài và lời kể của những người xung quanh. Vì là một thành phố du lịch nổi tiếng, tôi luôn mặc định rằng chi phí ăn ở tại Nha Trang chắc hẳn sẽ khá đắt đỏ. Nhưng khi thực sự đến đây, mọi thứ lại trái ngược với những gì tôi từng nghĩ. Ngay trong đêm, tôi mở Agoda và tìm một chỗ nghỉ gần biển. Không mất quá nhiều thời gian, tôi đặt được một căn phòng ngay trên đường Trần Phú, chỉ cách biển vài trăm mét đi bộ, với mức giá chưa đến 300.000 đồng. Phòng ốc cực kỳ sạch sẽ và không thiếu bất kỳ một tiện nghi nào, đầy đủ máy lạnh, máy sấy tóc, TV. Khoảnh khắc ấy khiến tôi nhận ra đôi khi chính những suy nghĩ và giả định của mình đã khiến việc đi du lịch trở nên khó khăn hơn thực tế. Tôi từng nghĩ một chuyến đi cần được chuẩn bị thật kỹ, phải đặt phòng từ sớm và dự trù rất nhiều chi phí. Nhưng lần này, ngay cả khi quyết định mọi thứ vào phút cuối, tôi vẫn tìm được một nơi ở sạch sẽ, gần biển và có mức giá hợp lý. Có lẽ sau chuyến đi này, tôi sẽ cho phép mình đi nhiều hơn. Không nhất thiết phải đợi đến khi có một kế hoạch hoàn hảo, một lịch trình chi tiết hay một khoản ngân sách thật lớn. Đôi khi, chỉ cần lên đường trước, những điều còn lại có thể đơn giản hơn mình tưởng rất nhiều. Nhận phòng xong, cả đêm tôi đi bộ quanh khu vực bãi biển Trần Phú. Nơi đây hiện đại hơn tôi nghĩ, có một nét đẹp rất có gu, cả con đường thẳng tấp mọc lên rất nhiều khách sạn, toà nhà trọc trời với nhiều màu sắc, cũng là trung tâm thành phố nhưng có lẽ tôi thích không khí ở đây hơn quận 1, Sài Gòn. Một điều bị sốc văn hoá ở Nha Trang là khắp nơi đều là chữ Nga và người Nga ở khắp nơi, tôi cứ tưởng người Trung Quốc nhiều hơn. Một tí hơi sốc cũng như hơi buồn, là người Việt mình cạnh tranh không bằng người nước ngoài ngay chính mảnh đất của mình. Có một thứ tôi rất thích ở người nước ngoài ở các địa điểm du lịch, là trông họ rất tận hưởng hành trình, chứ không phải chạy KPI check in nơi này nơi kia, nhìn thấy các anh chơi bóng chuyền ở bãi biển, thật sự mang lại một cảm giác rất tận hưởng. Sáng hôm sau, ngủ dậy, người tôi ê ẩm, tính sẽ xách xe chạy thêm nơi này nơi kia, nhưng không hiểu sao bị lười ghê luôn. Tôi đi bộ quanh khu vực tôi tá túc, đi tìm một quán ăn địa phương, một dĩa bánh căn đầy với giá 25k. Trời ơi, ở SG là dĩa này có giá 40k rồi, có ai đi du lịch mà tốn ít tiền hơn bình thường như tôi không. Tôi nhìn thấy một quán cà phê trông rất chill, tôi bước vào và gọi một ly cà phê đen, ngồi nhâm nhi như một người trưởng thành, hahah… Và tôi nghĩ cũng đã đến lúc đi tiếp rồi. Tạm biệt Nha Trang. ### Từ biển xanh đến thành phố trên cao Sau nhiều ngày men theo những cung đường biển, tôi bắt đầu muốn tìm đến một khung cảnh khác. Từ Nha Trang, tôi rời biển và bắt đầu đi về phía núi. Cảnh vật dọc đường cũng từ từ thay đổi. Những đoạn đường bằng phẳng nhường chỗ cho các con dốc và khúc cua nối tiếp nhau. Không khí dần mát hơn, cây cối xanh hơn, còn biển thì lùi lại phía sau. Càng lên cao, tôi càng cảm nhận rõ mình đang bước vào một chặng hoàn toàn khác của chuyến đi và Đà Lạt là điểm đến tiếp theo, cũng là điểm kết thúc hành trình trước khi về lại Sài Gòn. Nếu những ngày ở biển mang lại cảm giác tự do và rộng mở, Đà Lạt lại khiến mọi thứ chậm xuống. Đây không phải lần đầu tôi đến thành phố này, nhưng trong một hành trình không kế hoạch, Đà Lạt dường như mang một ý nghĩa khác. Tôi không còn muốn chạy đi thật nhiều nơi hay cố gắng hoàn thành một danh sách các điểm phải đến. Tôi chỉ muốn đi chậm giữa những con dốc, cảm nhận không khí se lạnh và nhịp sống thong thả nơi đây. Tôi chạy đến Thung Lũng Vàng, nơi có nhiều cây thông mang nét đẹp đậm chất Đà Lạt, cũng chụp được nhiều ảnh ở đây và quay được những đoạn rất cinematic. Xong, tôi đặt phòng cho nghỉ ngơi buổi chiều và sáng hôm sau. Tôi tiếp tục chọn phòng trên Agoda, và bất ngờ 1 lần nữa, phòng cách Hồ Xuân Hương 3p đi xe nhưng chỉ có giá 250k, tôi không mong đợi gì nhiều, nghĩ chắc phòng cũng bình thường, nhưng phòng rất xinh xắn, đáp ứng đầy đủ nhu cầu cơ bản của tôi. Tôi cho phép mình nghỉ ngơi cả buổi chiều không làm gì cả, ngủ 1 giấc trưa thật ngon rồi tính tiếp. Tôi cũng có vài địa điểm muốn đến nhưng chiều hôm đó tôi chỉ muốn đi dạo thôi, thế là tôi loanh quanh Hồ Xuân Hương và cũng quay được vài video deep deep ở đó. Buổi tối tôi có ghé Quảng trường Lâm Viên, ngồi uống 1 ly đậu nành nóng nghe saxophone, cũng sanh chảnh phết, haha. Tôi cũng hoà mình vào đám đông tại chợ để cảm nhận lại không khí của đám đông, tôi cô lập bản thân mình quá lâu rồi. Trút hết ưu phiền rồi quay lại homestay thôi. Tối đó tôi lên kế hoạch 4h30 sáng hôm sau đi săn mây, mà nửa muốn đi nửa không, vì trời vừa mưa, tôi không chắc đường lên có an toàn không nữa. Ngủ đến sáng, 4h tôi bật dậy, không hiểu sao lúc này tôi lười biếng ghê luôn, chả muốn đi đâu nữa, với lâu rồi tôi mới có cảm giác ngủ ngon như vậy, cuối cùng, tôi không nghĩ gì đến chuyện săn mây nữa, ngủ tiếp, giờ không ai cản được tôi đâu. Haha. Tầm 7h thì tôi dậy, lúc này là gần như tôi đã rất hài lòng về chuyến đi của mình rồi, tôi đi tìm đến một quán ăn bán bánh ướt lòng gà đặc trưng của Đà Lạt, xong mua 1 ly cà phê đen ra Hồ Xuân Hương ngồi nhâm nhi một lát rồi chào tạm biệt nơi này. ### Có những chuyến đi chỉ để được nghỉ Những tâm lý bất ổn của tôi, phần lớn đến từ việc nó không đạt được như kỳ vọng, hoặc là do sự thay đổi quá nhanh của thị trường làm tôi không thích ứng kịp, bị chơ vơ. Và tôi cũng nhận ra, khi đặt kỳ vọng quá nhiều thì tỷ lệ tôi bị hụt hẫng cũng nhiều hơn. Tôi học được cách chỉ nên kiểm soát những thứ mình có thể kiểm soát, chuyện gì tới nó sẽ tới, không cần nghiêm trọng hoá vấn đề. Chuyến đi này có những trục trặc ngoài ý muốn, may là vẫn chưa xảy ra vấn đề gì quá nghiêm trọng. Tuy nhiên, chính những điều đó làm chuyến đi này đáng nhớ hơn nhiều. Tôi liên tưởng chuyến đi này đến những việc xảy ra gần đây trong cuộc đời mình, rõ ràng phải có những chông gai, khó khăn thì mới tạo nên sự cứng rắn hiện tại. Một chuyến đi đáng nhớ. 56:T7c3,Càng cố gắng, tôi thấy mình càng đứng yên Bản thân tôi không phải người dễ bỏ cuộc, tuy nhiên lần này tôi cảm nhận rõ bản thân đang quá tải. Có lẽ cảm giác burnout không đến từ một khoảnh khắc, mà nó được tích tụ sau một thời gian dài mọi thứ liên tục diễn ra không như mong đợi. Tôi có vài trải nghiệm không được tốt lắm ở công ty gần nhất tôi làm việc, tôi vẫn nhớ như in cái cảm giác vào ngày cuối cùng làm việc ở đó, thay vì lo sợ hành trình sắp tới sẽ ra sao, tôi lại thấy bình yên đến lạ, như trút được gánh nặng vậy. Tôi cũng không vội đi tìm việc mới, thử nghiệm làm vài mô hình “startup 1 người” mà mình đã nghĩ đến trước đó. Tôi cũng nhận triển khai các mô hình AI Automation, n8n trên thị trường freelance và học một ngách mới - SAP. Tôi sẽ kể chi tiết hơn trong một bài viết khác. Nghề nghiệp của tôi thay đổi quá nhanh, tôi cũng cố gắng chạy theo, học liên tục để không bị outdate, nhưng tôi phải thừa nhận, mình không đuổi kịp với tốc độ phát triển của các công cụ AI. Nhu cầu khách hàng cũng giảm mạnh vì giờ đây AI đã đủ thông minh để triển khai được thứ họ muốn chỉ với vài prompt, không cần một người đứng trung gian như mình. Dù đã dành rất nhiều thời gian và công sức, kết quả vẫn không đạt được như kỳ vọng. Dần dần, tôi bắt đầu tự hỏi những gì mình đang làm có thật sự mang lại ý nghĩa gì không. Sau những cú trượt dài của mình, tôi gom phần năng lượng còn lại để lên chiến lược cho các buổi phỏng vấn, quay về môi trường công sở trước đó; khi thị trường có cung lớn hơn cầu57:T6d8,### Càng cố gắng, tôi thấy mình càng đứng yên Bản thân tôi không phải người dễ bỏ cuộc, tuy nhiên lần này tôi cảm nhận rõ bản thân đang quá tải. Có lẽ cảm giác burnout không đến từ một khoảnh khắc, mà nó được tích tụ sau một thời gian dài mọi thứ liên tục diễn ra không như mong đợi. Tôi có vài trải nghiệm không được tốt lắm ở công ty gần nhất tôi làm việc, tôi vẫn nhớ như in cái cảm giác vào ngày cuối cùng làm việc ở đó, thay vì lo sợ hành trình sắp tới sẽ ra sao, tôi lại thấy bình yên đến lạ, như trút được gánh nặng vậy. Tôi cũng không vội đi tìm việc mới, thử nghiệm làm vài mô hình “startup 1 người” mà mình đã nghĩ đến trước đó. Tôi cũng nhận triển khai các mô hình AI Automation, n8n trên thị trường freelance và học một ngách mới - SAP. Tôi sẽ kể chi tiết hơn trong một bài viết khác. Nghề nghiệp của tôi thay đổi quá nhanh, tôi cũng cố gắng chạy theo, học liên tục để không bị outdate, nhưng tôi phải thừa nhận, mình không đuổi kịp với tốc độ phát triển của các công cụ AI. Nhu cầu khách hàng cũng giảm mạnh vì giờ đây AI đã đủ thông minh để triển khai được thứ họ muốn chỉ với vài prompt, không cần một người đứng trung gian như mình. Dù đã dành rất nhiều thời gian và công sức, kết quả vẫn không đạt được như kỳ vọng. Dần dần, tôi bắt đầu tự hỏi những gì mình đang làm có thật sự mang lại ý nghĩa gì không.5:["$","main",null,{"className":"blog-module__JsT-Oq__blogRoot","children":[["$","$Lf",null,{}],["$","$L10",null,{"documents":[{"slug":"hello-world","language":"vi","title":"Chương 1. Hello World! Tôi đang học cách cảm nhận lại thế giới","part":"Part 1. Hello World","summary":"Tôi đã mất cả tỷ lần trì hoãn chỉ để đắn đo về việc xây dựng một khoảng lặng cho riêng mình. Thì bây giờ đây, chính là nó, JusteeSpace - một không gian, nơi tôi thoải mái ghi lại những câu chuyện, những trải nghiệm sống, là nơi lưu trữ, vừa mang tính cá nhân, vừa mang tính hệ thống. Một quyển nhật ký dành cho tôi ở phiên bản tương lai có thể xem lại những suy nghĩ, bài học mà tôi học được ở hiện tại.","category":"Personal","tags":["introduction"],"publishedAt":"2026-05-09","updatedAt":"$undefined","draft":false,"content":"$11","excerpt":"$12","previewContent":"## Điều gì đã thôi thúc tôi bắt đầu viết blog này?\n\nTôi vốn là một người không giỏi trong việc thể hiện cảm xúc, không giỏi trong việc diễn đạt và trình bày ý tưởng. Và nhìn lại quá khứ, điều đó đã cản trở tôi có thể dấn thân vào làm một việc gì đó hết mình. Những ngày tháng ngồi ở giảng đường Đại học, nếu như Giảng viên không trực tiếp gọi tôi thì có lẽ tôi cũng chả bao giờ phát biểu ý kiến, có lẽ là do sợ sai hay bị chê cười… haha… đúng là đần, mình là người trả tiền sử dụng dịch vụ mà, sợ cái đ’ gì chứ.\n\nCuộc sống của tôi cứ trôi qua êm đềm như vậy. Đến ngày tốt nghiệp, rồi cũng đi thực tập và may mắn có được công việc mà ở đó đã xây dựng lên nền tảng khá vững cho tôi. Bạn đã nghĩ cuộc sống của tôi như vậy là ổn, không có gì để chê đúng không, tốt nghiệp trường top (Bách Khoa), lại công việc ổn định. Cứ thế mà an nhàn đi, suy nghĩ làm gì.","connections":["who-am-i"],"readingMinutes":7,"languages":["vi"],"backlinks":[],"unresolvedReferences":[]},{"slug":"who-am-i","language":"vi","title":"Chương 2. Tôi là ai giữa thế giới này","part":"Part 1. Hello World","summary":"Tôi không định nghĩa bản thân bằng chức danh công việc, bằng những công nghệ mình thành thạo, hay bằng những con số vô hình trên màn hình máy tính. Bản thể của tôi là con người đã được hình thành dựa trên trải nghiệm sống, cách tôi phản ứng với những rào cản, hoài nghi của chính mình.","category":"Personal","tags":["introduction"],"publishedAt":"2026-05-12","updatedAt":"$undefined","draft":false,"content":"$13","excerpt":"$14","previewContent":"## Những thứ định nghĩa sự tồn tại của tôi\n\nMọi người thường nghĩ Dev bọn tôi chỉ biết có màn hình đen và những dòng code khô khan đúng không. Nhưng sau giờ làm, tôi lại ôm đàn, cầm máy ảnh đi lang thang, hoặc ngồi dựng một thước phim ngắn. Tôi còn chả biết có ai giống mình như vậy không. Blog này sinh ra vì tôi không muốn những mảnh ghép đó bị tách rời.\n\nTôi là một cựu sinh viên Bách Khoa K18, chuyên ngành Khoa học máy tính. Vâng, sau 5 năm trầy trật trên giảng đường, cuối cùng tôi cũng có thể tự tin giới thiệu mình là một Kỹ sư máy tính. Nhưng quay ngược thời gian vào thời điểm chọn ngành, bản thân tôi còn chả định nghĩa được 'kỹ sư' là gì. Tôi chỉ biết là xung quanh mọi người ca ngợi nó lắm, nào là ra trường lương nghìn đô, nào là tạo ra nhiều đột phá công nghệ. Năm đó, tôi cũng là một trong số ít học sinh của trường đỗ vào Bách Khoa, cảm giác bước đi mặt vênh lên trời, 'oách xà lách' vô cùng, và cái niềm tự hào âm ỉ ấy tôi vẫn giữ mãi cho đến tận bây giờ.","connections":["nothing-change-if-nothing-change"],"readingMinutes":6,"languages":["vi"],"backlinks":["hello-world"],"unresolvedReferences":[]},{"slug":"nothing-change-if-nothing-change","language":"vi","title":"Chương 3. Không có gì thay đổi nếu không có gì thay đổi","part":"Part 1. Hello World","summary":"Ai trong chúng ta cũng mong muốn trở thành phiên bản tốt hơn của chính mình, nhưng ít ai sẵn sàng thay đổi","category":"Personal","tags":["motivation"],"publishedAt":"2026-05-15","updatedAt":"$undefined","draft":false,"content":"$15","excerpt":"$16","previewContent":"## Chúng ta đang quá tham lam\n\nMạng xã hội ngày nay dựng lên những khung cảnh quá hoàn hảo: một đứa trẻ phát âm tiếng Anh chuẩn bản xứ, những người trẻ chưa đầy ba mươi đã sở hữu nhà riêng, xe sang hay tự do tài chính. Chúng ta lướt qua những lát cắt ấy mỗi ngày và vô tình rơi vào một cái bẫy tâm lý nguy hiểm: nhìn vào kết quả của người khác và gán nó làm tiêu chuẩn cho bản thân.\n\nNhưng sự thật là, những gì bạn thấy chưa chắc đã là 100% sự thật, có những bí mật đằng sau mà bạn chưa nhìn rõ, mọi trạng thái ở hiện tại đều có nguyên do của nó.\nĐằng sau một đứa trẻ nói tiếng Anh lưu khoát có thể là một gia đình có điều kiện, được đầu tư học trường quốc tế và tiếp xúc với ngoại ngữ từ lúc còn chưa sõi tiếng mẹ đẻ. Đằng sau một sự thành công sớm là những nguồn lực ngầm về tài chính, mối quan hệ hoặc xuất phát điểm vượt trội. Tất nhiên vẫn sẽ tồn tại vài trường hợp xuất chúng, nhưng tỷ lệ là dưới 1%.","connections":[],"readingMinutes":6,"languages":["vi"],"backlinks":["who-am-i"],"unresolvedReferences":[]},{"slug":"sap-switching","language":"vi","title":"Chương 1. Từ Kỹ Sư Phần Mềm Đến Hành Trình Mới Với SAP","part":"Part 2. Cú chuyển mình trong sự nghiệp","summary":"Từ 1 software engineer với kỹ năng Database Optimizing và Blockchain, vì sao tôi lại muốn bắt đầu hành trình mới với SAP","category":"Personal","tags":["sap"],"publishedAt":"2026-05-20","updatedAt":"$undefined","draft":false,"content":"$17","excerpt":"$18","previewContent":"## Bước đi chập chững từ các công ty khởi nghiệp\n\nTôi có nhiều năm làm việc với các công ty start up và may mắn được cọ xát với nhiều công nghệ mới, được nhúng tay khá sâu vào các dự án, như là trực tiếp sửa đổi / thiết kế lại hệ thống database của một ứng dụng đang chạy production và kết quả được cải thiện tương đối chỉ với vài kỹ năng cơ bản về Index và partitioning.","connections":["sap-foundation"],"readingMinutes":5,"languages":["vi"],"backlinks":[],"unresolvedReferences":[]},{"slug":"sap-foundation","language":"vi","title":"Chương 2. Đặt nền móng","part":"Part 2. Cú chuyển mình trong sự nghiệp","summary":"Định nghĩa tư duy, lên kế hoạch học tập để xây dựng nền móng vững chắc","category":"Personal","tags":["sap","foundation"],"publishedAt":"2026-05-27","updatedAt":"$undefined","draft":false,"content":"$19","excerpt":"$1a","previewContent":"$1b","connections":["sap-concepts"],"readingMinutes":7,"languages":["vi"],"backlinks":["sap-switching"],"unresolvedReferences":[]},{"slug":"sap-concepts","language":"vi","title":"Chương 3. Hiểu rõ hơn về các khái niệm trong SAP","part":"Part 2. Cú chuyển mình trong sự nghiệp","summary":"Cái nhìn toàn diện về hệ sinh thái SAP, từ tính năng cốt lõi, ngôn ngữ lập trình, hệ thống phân hệ đến cơ chế vận hành chi tiết của kiến trúc 3 lớp R/3 và Application Server.","category":"Personal","tags":["sap","foundation"],"publishedAt":"2026-06-01","updatedAt":"$undefined","draft":false,"content":"$1c","excerpt":"$1d","previewContent":"$1e","connections":["sap-abap"],"readingMinutes":3,"languages":["vi"],"backlinks":["sap-foundation"],"unresolvedReferences":[]},{"slug":"sap-abap","language":"vi","title":"Chương 4. ABAP Fundamentals: Bước Chân Vào Tầng Xử Lý Logic","part":"Part 2. Cú chuyển mình trong sự nghiệp","summary":"Những bài học đầu tiên về Technical trong SAP","category":"Personal","tags":["sap","foundation","abap"],"publishedAt":"2026-06-07","updatedAt":"$undefined","draft":false,"content":"$1f","excerpt":"$20","previewContent":"$21","connections":["sap-abap-1","sap-abap-2","sap-abap-3","sap-abap-4","sap-abap-5","sap-abap-6","sap-abap-7","sap-sd"],"readingMinutes":2,"languages":["vi"],"backlinks":["sap-concepts"],"unresolvedReferences":[]},{"slug":"sap-abap-1","language":"en","title":"ABAP BASIC Statements","part":"ABAP","summary":"ABAP Basic Statements","category":"Technical","tags":["sap","abap"],"publishedAt":"2026-06-10","updatedAt":"$undefined","draft":false,"content":"$22","excerpt":"$23","previewContent":"$24","connections":[],"readingMinutes":5,"languages":["en"],"backlinks":["sap-abap"],"unresolvedReferences":[]},{"slug":"sap-abap-2","language":"en","title":"ABAP Data Dictionary","part":"ABAP","summary":"ABAP Data Dictionary","category":"Technical","tags":["sap","abap"],"publishedAt":"2026-06-17","updatedAt":"$undefined","draft":false,"content":"$25","excerpt":"$26","previewContent":"$27","connections":[],"readingMinutes":5,"languages":["en"],"backlinks":["sap-abap"],"unresolvedReferences":[]},{"slug":"sap-abap-3","language":"en","title":"ABAP Open SQL","part":"ABAP","summary":"ABAP Open SQL","category":"Technical","tags":["sap","abap"],"publishedAt":"2026-06-24","updatedAt":"$undefined","draft":false,"content":"$28","excerpt":"$29","previewContent":"$2a","connections":[],"readingMinutes":5,"languages":["en"],"backlinks":["sap-abap"],"unresolvedReferences":[]},{"slug":"sap-abap-4","language":"en","title":"ABAP Internal Table","part":"ABAP","summary":"ABAP Internal Table","category":"Technical","tags":["sap","abap"],"publishedAt":"2026-06-28","updatedAt":"$undefined","draft":false,"content":"$2b","excerpt":"$2c","previewContent":"$2d","connections":[],"readingMinutes":16,"languages":["en"],"backlinks":["sap-abap"],"unresolvedReferences":[]},{"slug":"sap-abap-5","language":"en","title":"SAP ABAP Modularization","part":"ABAP","summary":"SAP ABAP Modularization","category":"Technical","tags":["sap","abap"],"publishedAt":"2026-07-06","updatedAt":"$undefined","draft":false,"content":"$2e","excerpt":"$2f","previewContent":"$30","connections":[],"readingMinutes":19,"languages":["en"],"backlinks":["sap-abap"],"unresolvedReferences":[]},{"slug":"sap-abap-6","language":"en","title":"SAP ABAP Classical Report","part":"ABAP","summary":"SAP ABAP Classical Report","category":"Technical","tags":["sap","abap"],"publishedAt":"2026-07-13","updatedAt":"$undefined","draft":false,"content":"$31","excerpt":"$32","previewContent":"$33","connections":[],"readingMinutes":18,"languages":["en"],"backlinks":["sap-abap"],"unresolvedReferences":[]},{"slug":"sap-abap-7","language":"en","title":"SAP ABAP ALV Report","part":"ABAP","summary":"SAP ABAP ALV Report","category":"Technical","tags":["sap","abap"],"publishedAt":"2026-07-21","updatedAt":"$undefined","draft":false,"content":"$34","excerpt":"$35","previewContent":"$36","connections":[],"readingMinutes":19,"languages":["en"],"backlinks":["sap-abap"],"unresolvedReferences":[]},{"slug":"sap-sd","language":"vi","title":"Chương 5. Bài toàn vận hành doanh nghiệp về luồng bán hàng và phân phối","part":"Part 2. Cú chuyển mình trong sự nghiệp","summary":"Hiểu được cú pháp ABAP, nắm vững cấu trúc tầng Application hay kiến trúc Data Dictionary mới chỉ là bước đầu. Kiến thức kỹ thuật của tôi sẽ trở nên vô dụng nếu như không được sử dụng để giải quyết một vấn đề cụ thể. Thay vì bắt tay vào code ngay một ứng dụng SAP, tôi chọn cách hiểu bức tranh nghiệp vụ toàn cảnh. Khi đã có cái nhìn rõ ràng hơn về nghiệp vụ các module, tôi sẽ hiểu rõ những gì mình đang làm hơn. Hơn nữa vào thời điểm hiện tại, AI có thể hỗ trợ rất nhiều trong kỹ thuật, hiểu rõ nghiệp vụ sẽ tăng tốc quá trình làm việc đáng kể. Bước đầu về nghiệp vụ, tôi chọn bắt đầu với module SD (Sales & Distribution) — trái tim vận hành doanh thu của mọi tổ chức.","category":"Personal","tags":["sap","sd"],"publishedAt":"2026-07-28","updatedAt":"$undefined","draft":false,"content":"\nSD (Sales & Distribution) giải quyết đúng một bài toán cốt lõi của doanh nghiệp: Làm sao để bán được hàng, giao được hàng và thu được tiền về tài khoản mà không bị thất thoát hay nghẽn quy trình.\nNghiệp vụ SD xoay quanh chuỗi quy trình kinh điển gọi là Order-to-Cash (O2C) bắt đầu từ bước khách hàng có sự quan tâm về sản phẩm, hỏi giá, thông tin đến ghi nhận đơn hàng đến bước thanh toán, kết thúc vòng đời đơn hàng.\n\n### Order To Cash Architecture\n\n[Đọc tiếp: Order To Cash Architecture →](/blog/sap-sd-1-o2c)\n\n### Organization and Master Data\n\n[Đọc tiếp: Organization and Master Data →](/blog/sap-sd-2-organization)\n\n### Sale Document Control and Pricing\n\n[Đọc tiếp: Document Control and Pricing →](/blog/sap-sd-3-sale-document)\n\n### Fulfillment, Posting, and Integration\n\n[Đọc tiếp: Fulfillment, Posting, and Integration →](/blog/sap-sd-4-fulfilment-posting-integration)\n\n### SAP RAP\n\n[Đọc tiếp: SAP RAP →](/blog/sap-rap)\n","excerpt":"SD (Sales & Distribution) giải quyết đúng một bài toán cốt lõi của doanh nghiệp: Làm sao để bán được hàng, giao được hàng và thu được tiền về tài khoản mà không bị thất thoát hay nghẽn quy trình. Nghiệp vụ SD xoay quanh chuỗi quy trình kinh điển gọi là Order-to-Cash (O2C) bắt đầu từ bước khách hàng có sự quan tâm về sản phẩm, hỏi giá, thông tin đến ghi nhận đơn hàng đến bước thanh toán, kết thúc vòng đời đơn hàng. Order To Cash Architecture Đọc tiếp: Order To Cash Architecture → Organization and Master Data Đọc tiếp: Organization and Master Data → Sale Document Control and Pricing Đọc tiếp: Document Control and Pricing → Fulfillment, Posting, and Integration Đọc tiếp: Fulfillment, Posting, and Integration → SAP RAP Đọc tiếp: SAP RAP →","previewContent":"SD (Sales & Distribution) giải quyết đúng một bài toán cốt lõi của doanh nghiệp: Làm sao để bán được hàng, giao được hàng và thu được tiền về tài khoản mà không bị thất thoát hay nghẽn quy trình.\nNghiệp vụ SD xoay quanh chuỗi quy trình kinh điển gọi là Order-to-Cash (O2C) bắt đầu từ bước khách hàng có sự quan tâm về sản phẩm, hỏi giá, thông tin đến ghi nhận đơn hàng đến bước thanh toán, kết thúc vòng đời đơn hàng.\n\n### Order To Cash Architecture\n\n[Đọc tiếp: Order To Cash Architecture →](/blog/sap-sd-1-o2c)\n\n### Organization and Master Data\n\n[Đọc tiếp: Organization and Master Data →](/blog/sap-sd-2-organization)\n\n### Sale Document Control and Pricing\n\n[Đọc tiếp: Document Control and Pricing →](/blog/sap-sd-3-sale-document)\n\n### Fulfillment, Posting, and Integration\n\n[Đọc tiếp: Fulfillment, Posting, and Integration →](/blog/sap-sd-4-fulfilment-posting-integration)\n\n### SAP RAP\n\n[Đọc tiếp: SAP RAP →](/blog/sap-rap)","connections":["sap-sd-1-o2c","sap-sd-2-organization","sap-sd-3-sale-document","sap-sd-4-fulfilment-posting-integration","sap-rap"],"readingMinutes":1,"languages":["vi"],"backlinks":["sap-abap"],"unresolvedReferences":[]},{"slug":"sap-sd-1-o2c","language":"en","title":"SAP SD Order To Cash Overview","part":"ABAP","summary":"This document describes the technical structure and runtime boundaries of the SAP Sales and Distribution Order-to-Cash process. Its purpose is to connect the business-document chain to document grain, persistence landmarks, posting effects, document flow, diagnostic evidence, and clean-core integration contracts.","category":"Technical","tags":["sap","sd"],"publishedAt":"2026-07-30","updatedAt":"$undefined","draft":false,"content":"$37","excerpt":"$38","previewContent":"$39","connections":[],"readingMinutes":28,"languages":["en"],"backlinks":["sap-sd"],"unresolvedReferences":[]},{"slug":"sap-sd-2-organization","language":"en","title":"SAP SD Organizational and Master Data","part":"ABAP","summary":"This document explains how SAP Sales and Distribution combines organizational configuration and reusable master data to establish a valid processing context for a sales transaction. It connects business meaning to classic persistence landmarks, maintenance transactions, runtime determination, diagnostic technique, RAP modeling, and clean-core boundaries.","category":"Technical","tags":["sap","sd"],"publishedAt":"2026-08-06","updatedAt":"$undefined","draft":false,"content":"$3a","excerpt":"$3b","previewContent":"$3c","connections":[],"readingMinutes":23,"languages":["en"],"backlinks":["sap-sd"],"unresolvedReferences":[]},{"slug":"sap-sd-3-sale-document","language":"en","title":"SAP SD Document Control and Pricing","part":"ABAP","summary":"This document explains how SAP Sales and Distribution controls a Sales Order at header, item, and schedule-line level and how the condition technique builds the document-specific pricing result. It connects business grain to determination inputs, Customizing, runtime persistence, diagnostic evidence, RAP concepts, and clean-core boundaries.","category":"Technical","tags":["sap","sd"],"publishedAt":"2026-08-15","updatedAt":"$undefined","draft":false,"content":"$3d","excerpt":"$3e","previewContent":"$3f","connections":[],"readingMinutes":26,"languages":["en"],"backlinks":["sap-sd"],"unresolvedReferences":[]},{"slug":"sap-sd-4-fulfilment-posting-integration","language":"en","title":"SAP SD Fulfillment, Posting, and Integration","part":"ABAP","summary":"This document explains the technical execution path from a delivery-relevant Sales Order through Outbound Delivery, picking, packing, Post Goods Issue (PGI), billing, accounting, payment clearing, and external integration. It connects business-document boundaries to configuration, persistence, application logs, interfaces, reversals, diagnostic evidence, and clean-core extension design.","category":"Technical","tags":["sap","sd"],"publishedAt":"2026-08-22","updatedAt":"$undefined","draft":false,"content":"$40","excerpt":"$41","previewContent":"$42","connections":[],"readingMinutes":32,"languages":["en"],"backlinks":["sap-sd"],"unresolvedReferences":[]},{"slug":"sap-rap","language":"vi","title":"Chương 6. Triển khai nghiệp vụ với kiến trúc hệ thống chuẩn Clean Core - RAP","part":"Part 2. Cú chuyển mình trong sự nghiệp","summary":"Sau khi hiểu được một phần nghiệp vụ. Tôi chọn cách triển khai bài toán trên một giải pháp Backend hiện đại, không chỉ đơn thuần là một ALV report. Từ viết code thủ công đến kiến trúc xử lý hướng đối tượng, phân tầng rõ ràng và bám sát triết lý Clean Core","category":"Personal","tags":["sap","rap"],"publishedAt":"2026-08-25","updatedAt":"$undefined","draft":false,"content":"\n### SAP RAP Architecture and End-to-End Runtime\n\n[Đọc tiếp: SAP RAP Architecture and End-to-End Runtime→](/blog/sap-rap-1-architecture-to-e2e-runtime)\n\n### SAP RAP CDS Data Modeling and Projection Design\n\n[Đọc tiếp: SAP RAP CDS Data Modeling and Projection Design →](/blog/sap-rap-2-cds-data)\n\n### SAP RAP Behavior Modeling and Implementation\n\n[Đọc tiếp: SAP RAP Behavior Modeling and Implementation →](/blog/sap-rap-3-behavior-modeling)\n\n### SAP RAP Behavior Modeling and Implementation\n\n[Đọc tiếp: SAP Transactions, Draft, and Concurrency →](/blog/sap-rap-4-transaction-draft-concurrency)\n\n### SAP RAP Service Exposure and Fiori Elements\n\n[Đọc tiếp: SAP RAP Service Exposure and Fiori Elements →](/blog/sap-rap-5-service-exposure)\n\n### SAP RAP Security, Testing, and Production Readiness\n\n[Đọc tiếp: SAP RAP Security, Testing, and Production Readiness →](/blog/sap-rap-6-security-testing)\n","excerpt":"SAP RAP Architecture and End-to-End Runtime Đọc tiếp: SAP RAP Architecture and End-to-End Runtime→ SAP RAP CDS Data Modeling and Projection Design Đọc tiếp: SAP RAP CDS Data Modeling and Projection Design → SAP RAP Behavior Modeling and Implementation Đọc tiếp: SAP RAP Behavior Modeling and Implementation → SAP RAP Behavior Modeling and Implementation Đọc tiếp: SAP Transactions, Draft, and Concurrency → SAP RAP Service Exposure and Fiori Elements Đọc tiếp: SAP RAP Service Exposure and Fiori Elements → SAP RAP Security, Testing, and Production Readiness Đọc tiếp: SAP RAP Security, Testing, and Production Readiness →","previewContent":"### SAP RAP Architecture and End-to-End Runtime\n\n[Đọc tiếp: SAP RAP Architecture and End-to-End Runtime→](/blog/sap-rap-1-architecture-to-e2e-runtime)\n\n### SAP RAP CDS Data Modeling and Projection Design\n\n[Đọc tiếp: SAP RAP CDS Data Modeling and Projection Design →](/blog/sap-rap-2-cds-data)\n\n### SAP RAP Behavior Modeling and Implementation\n\n[Đọc tiếp: SAP RAP Behavior Modeling and Implementation →](/blog/sap-rap-3-behavior-modeling)\n\n### SAP RAP Behavior Modeling and Implementation\n\n[Đọc tiếp: SAP Transactions, Draft, and Concurrency →](/blog/sap-rap-4-transaction-draft-concurrency)\n\n### SAP RAP Service Exposure and Fiori Elements\n\n[Đọc tiếp: SAP RAP Service Exposure and Fiori Elements →](/blog/sap-rap-5-service-exposure)\n\n### SAP RAP Security, Testing, and Production Readiness\n\n[Đọc tiếp: SAP RAP Security, Testing, and Production Readiness →](/blog/sap-rap-6-security-testing)","connections":["sap-rap-1-architecture-to-e2e-runtime","sap-rap-2-cds-data","sap-rap-3-behavior-modeling","sap-rap-4-transaction-draft-concurrency","sap-rap-5-service-exposure","sap-rap-6-security-testing"],"readingMinutes":1,"languages":["vi"],"backlinks":["sap-sd"],"unresolvedReferences":[]},{"slug":"sap-rap-1-architecture-to-e2e-runtime","language":"en","title":"SAP RAP Architecture and End-to-End Runtime","part":"ABAP","summary":"This document explains the architecture and runtime of the ABAP RESTful Application Programming Model (RAP). It traces metadata, read, and transactional requests through CDS, behavior, service exposure, the RAP transactional buffer, the save sequence, and database persistence.","category":"Technical","tags":["sap","rap"],"publishedAt":"2026-08-30","updatedAt":"$undefined","draft":false,"content":"$43","excerpt":"$44","previewContent":"$45","connections":[],"readingMinutes":28,"languages":["en"],"backlinks":["sap-rap"],"unresolvedReferences":[]},{"slug":"sap-rap-2-cds-data","language":"en","title":"SAP RAP CDS Data Modeling and Projection Design","part":"RAP","summary":"This document explains how ABAP CDS defines the structural and semantic model of a RAP business object and how CDS projection views adapt that model for a specific consumer. It focuses on entity boundaries, keys, compositions, associations, cardinality, semantic annotations, projection contracts, and navigation topology.","category":"Technical","tags":["sap","rap"],"publishedAt":"2026-09-02","updatedAt":"$undefined","draft":false,"content":"$46","excerpt":"$47","previewContent":"$48","connections":[],"readingMinutes":24,"languages":["en"],"backlinks":["sap-rap"],"unresolvedReferences":[]},{"slug":"sap-rap-3-behavior-modeling","language":"en","title":"SAP RAP Behavior Modeling and Implementation","part":"RAP","summary":"This document explains how a RAP business object becomes transactional. It covers the base behavior definition, behavior projection, managed and unmanaged implementation choices, behavior pools, standard operations, field control, determinations, validations, actions, prechecks, feature control, EML, and RAP response structures.","category":"Technical","tags":["sap","rap"],"publishedAt":"2026-09-07","updatedAt":"$undefined","draft":false,"content":"$49","excerpt":"$4a","previewContent":"$4b","connections":[],"readingMinutes":26,"languages":["en"],"backlinks":["sap-rap"],"unresolvedReferences":[]},{"slug":"sap-rap-4-transaction-draft-concurrency","language":"en","title":"SAP RAP Transactions, Draft, and Concurrency","part":"RAP","summary":"This document explains how RAP manages state from the first modification until database commit. It covers the interaction phase, transactional buffer, save sequence, draft persistence, draft actions, pessimistic locks, entity ETags, total ETags, early and late numbering, and transaction ownership.","category":"Technical","tags":["sap","rap"],"publishedAt":"2026-09-10","updatedAt":"$undefined","draft":false,"content":"$4c","excerpt":"$4d","previewContent":"$4e","connections":[],"readingMinutes":25,"languages":["en"],"backlinks":["sap-rap"],"unresolvedReferences":[]},{"slug":"sap-rap-5-service-exposure","language":"en","title":"SAP RAP Service Exposure and Fiori Elements","part":"RAP","summary":"This document explains how a reusable RAP business object becomes a consumer-facing OData service and a metadata-driven SAP Fiori elements application. It covers service projections, behavior projections, metadata extensions, value helps, side effects, service definitions, service bindings, OData V4 UI and Web API contracts, publication, and runtime diagnosis.","category":"Technical","tags":["sap","rap"],"publishedAt":"2026-09-12","updatedAt":"$undefined","draft":false,"content":"$4f","excerpt":"$50","previewContent":"$51","connections":[],"readingMinutes":23,"languages":["en"],"backlinks":["sap-rap"],"unresolvedReferences":[]},{"slug":"sap-rap-6-security-testing","language":"en","title":"SAP RAP Service Exposure and Fiori Elements","part":"RAP","summary":"This document explains how a reusable RAP business object becomes a consumer-facing OData service and a metadata-driven SAP Fiori elements application. It covers service projections, behavior projections, metadata extensions, value helps, side effects, service definitions, service bindings, OData V4 UI and Web API contracts, publication, and runtime diagnosis.","category":"Technical","tags":["sap","rap"],"publishedAt":"2026-09-12","updatedAt":"$undefined","draft":false,"content":"$52","excerpt":"$53","previewContent":"$54","connections":[],"readingMinutes":23,"languages":["en"],"backlinks":["sap-rap"],"unresolvedReferences":[]},{"slug":"toi-di-tim-mot-khoang-dung","language":"vi","title":"Tôi đi tìm cho mình một khoảng dừng","part":"Part 3. Cuộn phim","summary":"Sau một thời gian dài chạy theo công việc, tính từ lúc tôi còn chưa tốt nghiệp Đại học đến bây giờ, tôi chưa có một kỳ nghỉ nào thật sự trọn vẹn cho riêng mình cả. Thời gian gần đây tôi cảm nhận rõ sự ‘burnout’ trong mình, tôi mất cảm xúc hay không còn hứng thú với những điều mình từng rất yêu thích. Thế là tôi quyết định xách con xe của mình, rời Sài Gòn, đi “chạm cỏ” ở một thành phố khác với không lịch trình và không có một sự kỳ vọng nào.","category":"Personal","tags":["introduction","journal","psychology"],"publishedAt":"2026-10-24","updatedAt":"$undefined","draft":false,"content":"$55","excerpt":"$56","previewContent":"$57","connections":[],"readingMinutes":19,"languages":["vi"],"backlinks":[],"unresolvedReferences":[]}],"initialDocument":"$undefined","language":"vi"}]]}] b:[["$","meta","0",{"charSet":"utf-8"}],["$","meta","1",{"name":"viewport","content":"width=device-width, initial-scale=1"}]] 58:I[27201,["/_next/static/immutable/chunks/33v8uwkv4wy50.js"],"IconMark"] 8:null d:[["$","title","0",{"children":"Graph | Thanh's Blog"}],["$","meta","1",{"name":"description","content":"Explore connections between technical and personal documents."}],["$","link","2",{"rel":"shortcut icon","href":"/images/favicon.webp"}],["$","link","3",{"rel":"icon","href":"/images/favicon.webp"}],["$","link","4",{"rel":"apple-touch-icon","href":"/images/favicon.webp"}],["$","$L58","5",{}]] </article></body></html>