@linkup-ai/abap-ai 2.0.0

package/dist/knowledge/abap/rap-eml.md

@@ -0,0 +1,453 @@
+# RAP & EML — behavior definition, CRUD, actions, draft
+
+## Behavior Definition (BDEF)
+
+```cds
+managed implementation in class zbp_z_order unique;
+strict ( 2 );
+
+define behavior for ZI_Order alias Order
+persistent table ztab_order
+lock master
+authorization master ( instance )
+etag master changed_at
+{
+  create;
+  update;
+  delete;
+
+  field ( readonly ) order_id;
+  field ( readonly : update ) order_id;
+  field ( mandatory ) customer, amount;
+
+  association _Item { create; }
+
+  action confirm result [1] $self;
+  static action recalculate_all;
+  internal action set_defaults;
+  factory action copy [1];
+
+  determination set_number on save { create; }
+  determination calc_total on modify { field quantity, price; }
+
+  validation check_customer on save { create; update; field customer; }
+  validation check_amount on save { create; field amount; }
+
+  mapping for ztab_order corresponding;
+}
+
+define behavior for ZI_OrderItem alias Item
+persistent table ztab_order_item
+lock dependent by _Order
+authorization dependent by _Order
+{
+  update;
+  delete;
+
+  field ( readonly ) order_id, item_id;
+
+  association _Order;
+
+  mapping for ztab_order_item corresponding;
+}
+```
+
+## BDEF Specifications
+
+```cds
+" Standard operations
+create;
+update;
+delete( precheck );
+
+" Associations
+association _Child { create; }
+
+" Actions and functions
+action act1 result [1] $self;
+static action act2;
+internal action act3;
+factory action act4 [1];
+function get_items result [0..*] ZI_OrderItem;
+
+" Field characteristics
+field ( readonly ) field1;
+field ( readonly : update ) key_field;
+field ( mandatory ) field2, field3;
+field ( features : instance ) field4;
+
+" Determinations
+determination det1 on save { create; }
+determination det2 on modify { field field1, field2; }
+
+" Validations
+validation val1 on save { create; update; field field1; }
+
+" Lock and authorization
+lock master
+lock dependent by _Parent
+authorization master ( instance )
+authorization dependent by _Parent
+```
+
+## ABAP Behavior Pool — Global Class
+
+```abap
+CLASS zbp_z_order DEFINITION PUBLIC ABSTRACT FINAL
+  FOR BEHAVIOR OF zi_order.
+ENDCLASS.
+
+CLASS zbp_z_order IMPLEMENTATION.
+ENDCLASS.
+```
+
+## Handler Class (Local)
+
+```abap
+CLASS lhc_order DEFINITION INHERITING FROM cl_abap_behavior_handler.
+  PRIVATE SECTION.
+    METHODS get_instance_authorizations FOR INSTANCE AUTHORIZATION
+      IMPORTING keys REQUEST requested_authorizations
+      FOR Order RESULT result.
+
+    METHODS create FOR MODIFY
+      IMPORTING entities FOR CREATE Order.
+
+    METHODS update FOR MODIFY
+      IMPORTING entities FOR UPDATE Order.
+
+    METHODS delete FOR MODIFY
+      IMPORTING keys FOR DELETE Order.
+
+    METHODS read FOR READ
+      IMPORTING keys FOR READ Order RESULT result.
+
+    METHODS confirm FOR MODIFY
+      IMPORTING keys FOR ACTION Order~confirm RESULT result.
+
+    METHODS set_number FOR DETERMINE ON SAVE
+      IMPORTING keys FOR Order~set_number.
+
+    METHODS check_customer FOR VALIDATE ON SAVE
+      IMPORTING keys FOR Order~check_customer.
+ENDCLASS.
+```
+
+## Saver Class (Unmanaged/Additional Save)
+
+```abap
+CLASS lsc_order 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.
+
+CLASS lsc_order IMPLEMENTATION.
+  METHOD save.
+    " Persist transactional buffer to database
+  ENDMETHOD.
+  METHOD cleanup.
+    " Clear transactional buffer
+  ENDMETHOD.
+ENDCLASS.
+```
+
+## BDEF Derived Types
+
+```abap
+" Table types
+DATA zt_create TYPE TABLE FOR CREATE zi_order.
+DATA zt_update TYPE TABLE FOR UPDATE zi_order.
+DATA zt_delete TYPE TABLE FOR DELETE zi_order.
+DATA zt_read   TYPE TABLE FOR READ IMPORT zi_order.
+DATA zt_result TYPE TABLE FOR READ RESULT zi_order.
+DATA zt_action TYPE TABLE FOR ACTION IMPORT zi_order~confirm.
+
+" Response types
+DATA zs_mapped   TYPE RESPONSE FOR MAPPED   zi_order.
+DATA zs_failed   TYPE RESPONSE FOR FAILED   zi_order.
+DATA zs_reported TYPE RESPONSE FOR REPORTED zi_order.
+```
+
+## Special Components (% Prefixed)
+
+```abap
+" %cid — content ID for new instances (before key assignment)
+zt_create = VALUE #( (
+  %cid = 'new_order_1'
+  customer = 'CUST100'
+  amount = 500 ) ).
+
+" %cid_ref — reference %cid of parent in deep create
+" %key — primary key fields only
+" %tky — primary key + draft indicator (preferred)
+zt_delete = VALUE #( ( %tky = VALUE #( order_id = '1000' ) ) ).
+
+" %control — flags which fields are provided
+zt_update = VALUE #( (
+  order_id = '1000'
+  status = 'C'
+  %control = VALUE #(
+    order_id = if_abap_behv=>mk-off
+    status   = if_abap_behv=>mk-on ) ) ).
+
+" %data — all key + data fields
+zt_create = VALUE #( (
+  %cid = 'cid1'
+  %data = VALUE #( customer = 'CUST100' amount = 500 ) ) ).
+```
+
+## EML CREATE
+
+```abap
+" Short form — FIELDS list
+MODIFY ENTITY zi_order
+  CREATE FIELDS ( customer amount )
+  WITH VALUE #(
+    ( %cid = 'cid1' customer = 'CUST100' amount = 500 )
+    ( %cid = 'cid2' customer = 'CUST200' amount = 300 ) )
+  MAPPED DATA(mapped)
+  FAILED DATA(failed)
+  REPORTED DATA(reported).
+
+" Long form — %control
+MODIFY ENTITIES OF zi_order
+  ENTITY Order
+  CREATE FROM VALUE #( (
+    %cid = 'cid1'
+    customer = 'CUST100'
+    amount = 500
+    %control = VALUE #(
+      customer = if_abap_behv=>mk-on
+      amount   = if_abap_behv=>mk-on ) ) )
+  MAPPED DATA(m) FAILED DATA(f) REPORTED DATA(r).
+
+" AUTO FILL CID
+MODIFY ENTITIES OF zi_order
+  ENTITY Order
+  CREATE AUTO FILL CID
+  WITH VALUE #( ( customer = 'CUST100' amount = 500
+    %control = VALUE #(
+      customer = if_abap_behv=>mk-on
+      amount   = if_abap_behv=>mk-on ) ) )
+  MAPPED DATA(m2) FAILED DATA(f2) REPORTED DATA(r2).
+```
+
+## EML UPDATE
+
+```abap
+" Short form
+MODIFY ENTITY zi_order
+  UPDATE FIELDS ( status )
+  WITH VALUE #( ( order_id = '1000' status = 'C' ) )
+  FAILED DATA(f) REPORTED DATA(r).
+
+" Long form
+MODIFY ENTITIES OF zi_order
+  ENTITY Order
+  UPDATE FROM VALUE #( (
+    order_id = '1000'
+    status = 'C'
+    %control = VALUE #(
+      status = if_abap_behv=>mk-on ) ) )
+  FAILED DATA(f2) REPORTED DATA(r2).
+```
+
+## EML DELETE
+
+```abap
+MODIFY ENTITY zi_order
+  DELETE FROM VALUE #(
+    ( order_id = '1000' )
+    ( order_id = '2000' ) )
+  FAILED DATA(f) REPORTED DATA(r).
+```
+
+## EML READ
+
+```abap
+" Specific fields
+READ ENTITY zi_order
+  FIELDS ( customer amount status )
+  WITH VALUE #( ( order_id = '1000' ) )
+  RESULT DATA(zt_result)
+  FAILED DATA(f) REPORTED DATA(r).
+
+" All fields
+READ ENTITY zi_order
+  ALL FIELDS
+  WITH VALUE #( ( order_id = '1000' ) )
+  RESULT DATA(zt_all).
+
+" Read by association
+READ ENTITIES OF zi_order
+  ENTITY Order
+  BY \_Item
+  FIELDS ( item_id description quantity )
+  WITH VALUE #( ( order_id = '1000' ) )
+  RESULT DATA(zt_items)
+  FAILED DATA(f2) REPORTED DATA(r2).
+```
+
+## Deep Create (Parent + Children)
+
+```abap
+MODIFY ENTITIES OF zi_order
+  ENTITY Order
+  CREATE FIELDS ( customer amount )
+  WITH VALUE #( (
+    %cid = 'cid_order'
+    customer = 'CUST100'
+    amount = 800 ) )
+
+  CREATE BY \_Item
+  FIELDS ( item_id description quantity )
+  WITH VALUE #( (
+    %cid_ref = 'cid_order'
+    %target = VALUE #(
+      ( %cid = 'cid_item1' item_id = 10 description = `Widget` quantity = 5 )
+      ( %cid = 'cid_item2' item_id = 20 description = `Gadget` quantity = 3 ) ) ) )
+
+  MAPPED DATA(mapped) FAILED DATA(failed) REPORTED DATA(reported).
+```
+
+## Action Execution
+
+```abap
+MODIFY ENTITY zi_order
+  EXECUTE confirm
+  FROM VALUE #( ( order_id = '1000' ) )
+  RESULT DATA(zt_action_result)
+  FAILED DATA(f) REPORTED DATA(r).
+```
+
+## COMMIT and ROLLBACK
+
+```abap
+" Persist all changes
+COMMIT ENTITIES
+  RESPONSE OF zi_order
+  MAPPED DATA(mapped)
+  FAILED DATA(failed)
+  REPORTED DATA(reported).
+
+" Check for errors
+IF failed IS NOT INITIAL.
+  " Handle failures
+ENDIF.
+
+" Discard all changes
+ROLLBACK ENTITIES.
+```
+
+## IN LOCAL MODE
+
+```abap
+" Bypass authorization and feature control within ABP
+MODIFY ENTITY zi_order IN LOCAL MODE
+  CREATE FIELDS ( customer amount )
+  WITH VALUE #( ( %cid = 'cid1' customer = 'SYS' amount = 0 ) )
+  MAPPED DATA(m) FAILED DATA(f) REPORTED DATA(r).
+
+READ ENTITY zi_order IN LOCAL MODE
+  ALL FIELDS WITH VALUE #( ( order_id = '1000' ) )
+  RESULT DATA(zt_data).
+```
+
+## Validation Implementation
+
+```abap
+METHOD check_customer.
+  READ ENTITIES OF zi_order IN LOCAL MODE
+    ENTITY Order
+    FIELDS ( customer )
+    WITH CORRESPONDING #( keys )
+    RESULT DATA(zt_orders).
+
+  LOOP AT zt_orders INTO DATA(zs_order).
+    IF zs_order-customer IS INITIAL.
+      APPEND VALUE #(
+        %tky = zs_order-%tky
+        %msg = new_message_with_text(
+          severity = if_abap_behv_message=>severity-error
+          text = 'Customer is required' ) )
+        TO reported-order.
+      APPEND VALUE #( %tky = zs_order-%tky ) TO failed-order.
+    ENDIF.
+  ENDLOOP.
+ENDMETHOD.
+```
+
+## Determination Implementation
+
+```abap
+METHOD set_number.
+  READ ENTITIES OF zi_order IN LOCAL MODE
+    ENTITY Order
+    FIELDS ( order_id )
+    WITH CORRESPONDING #( keys )
+    RESULT DATA(zt_orders).
+
+  MODIFY ENTITIES OF zi_order IN LOCAL MODE
+    ENTITY Order
+    UPDATE FIELDS ( order_id )
+    WITH VALUE #( FOR zs_order IN zt_orders
+      ( %tky = zs_order-%tky
+        order_id = cl_uuid_factory=>create_system_uuid(
+          )->create_uuid_x16( ) ) )
+    REPORTED DATA(reported).
+ENDMETHOD.
+```
+
+## Response Handling
+
+```abap
+" MAPPED — key mapping for created instances
+mapped-order = VALUE #( ( %cid = 'cid1' order_id = '1000' ) ).
+
+" FAILED — failed instances with cause
+failed-order = VALUE #( (
+  %cid = 'cid1'
+  %fail-cause = if_abap_behv=>cause-unspecific ) ).
+
+" REPORTED — messages
+reported-order = VALUE #( (
+  %tky = VALUE #( order_id = '1000' )
+  %msg = new_message_with_text(
+    severity = if_abap_behv_message=>severity-error
+    text = 'Validation failed' ) ) ).
+```
+
+---
+
+## Rules
+
+- Always use %tky over %key — includes draft indicator
+- Use %cid for new instances, %cid_ref for parent references in deep create
+- Use IN LOCAL MODE inside ABP to bypass auth/feature control
+- Use COMMIT ENTITIES to persist, always check failed response
+- Use CORRESPONDING with MAPPING FROM/TO ENTITY for BDEF-DB mapping
+- Short form (FIELDS list) is cleaner; long form (%control) for dynamic scenarios
+- Validations report errors via reported + failed, never raise exceptions
+- Determinations run IN LOCAL MODE by default
+- One handler class per entity, one saver class per BO root
+- Use `new_message_with_text( )` or message class for reported-%msg
+
+## Anti-Patterns
+
+| Anti-Pattern | Correct Approach |
+|---|---|
+| Direct DB access in managed BO | Use EML (MODIFY/READ ENTITIES) |
+| RAISE EXCEPTION in validation | Append to `reported` and `failed` |
+| Using %key instead of %tky | Always use %tky (draft-safe) |
+| Forgetting COMMIT ENTITIES after MODIFY | Always COMMIT or use auto-commit in OData |
+| Hardcoded strings in %msg | Use message class via `new_message( )` |
+| READ ENTITIES without IN LOCAL MODE inside ABP | Use IN LOCAL MODE to avoid auth loops |
+| Missing `IS NOT INITIAL` check on failed after COMMIT | Always check failed response |
+| Creating handler for child entity in root class | Separate handler class per entity |
+| Using MODIFY ENTITY (short) mixing multiple entities | Use MODIFY ENTITIES OF (long) for multi-entity |
+| Skipping %control in dynamic updates | Always set %control flags for partial updates |