Skip to content

Commit b2d09b6

Browse files
oblomov-devoblomov-dev
committed
docs: rewrite Draft Handling page to match doc style
1 parent 0f0de0d commit b2d09b6

1 file changed

Lines changed: 41 additions & 298 deletions

File tree

‎docs/development/specific/draft.md‎

Lines changed: 41 additions & 298 deletions
Original file line numberDiff line numberDiff line change
@@ -3,313 +3,56 @@ outline: [2, 4]
33
---
44
# Draft Handling
55

6-
Draft handling lets users save unfinished work — for example, a half-filled form — without committing it to the active database state. With abap2UI5 you can drive RAP draft-enabled business objects directly through EML.
6+
Draft handling lets users save unfinished work — for example a half-filled form — without writing through to the active database state. In abap2UI5 apps you drive RAP draft-enabled business objects directly through EML, just like any other entity (see also [CDS, EML](./cds.md)).
77

8-
### Modify a Draft
9-
Use `MODIFY ENTITIES` with the `IN LOCAL MODE` and the draft addition to create or update draft instances:
8+
#### Create a Draft
9+
Use `MODIFY ENTITIES` with `%is_draft = if_abap_behv=>mk-on` to create a new draft instance:
1010
```abap
11-
MODIFY ENTITIES OF i_salesordertp
12-
ENTITY salesorder
13-
CREATE
14-
FIELDS ( salesordertype salesorganization )
15-
WITH VALUE #( ( %cid = `0001`
16-
%is_draft = if_abap_behv=>mk-on
17-
%data = VALUE #(
18-
SalesOrderType = `TA`
19-
SalesOrganization = `1010` ) ) )
20-
MAPPED DATA(ls_mapped)
21-
FAILED DATA(ls_failed)
22-
REPORTED DATA(ls_reported).
11+
METHOD z2ui5_if_app~main.
12+
13+
MODIFY ENTITIES OF i_salesordertp
14+
ENTITY salesorder
15+
CREATE
16+
FIELDS ( salesordertype salesorganization )
17+
WITH VALUE #( ( %cid = `0001`
18+
%is_draft = if_abap_behv=>mk-on
19+
%data = VALUE #(
20+
SalesOrderType = `TA`
21+
SalesOrganization = `1010` ) ) )
22+
MAPPED DATA(ls_mapped)
23+
FAILED DATA(ls_failed)
24+
REPORTED DATA(ls_reported).
25+
26+
COMMIT ENTITIES.
27+
28+
ENDMETHOD.
29+
```
30+
31+
#### Read a Draft
32+
Set `%key-IsActiveEntity = abap_false` to read the draft instead of the active record:
33+
```abap
34+
READ ENTITIES OF i_salesordertp
35+
ENTITY SalesOrder
36+
FIELDS ( SalesOrderType )
37+
WITH VALUE #( ( %key-SalesOrder = `0000004711`
38+
%key-IsActiveEntity = abap_false ) )
39+
RESULT DATA(lt_drafts).
2340
```
2441

25-
### Activate a Draft
26-
Promote the draft to the active state with the `Activate` action and commit:
42+
#### Activate or Discard
43+
Promote the draft to the active state with the `Activate` action, or throw it away with `Discard`:
2744
```abap
2845
MODIFY ENTITIES OF i_salesordertp
29-
ENTITY salesorder
46+
ENTITY SalesOrder
3047
EXECUTE Activate
31-
FROM VALUE #( ( %key = ls_key
32-
%is_draft = if_abap_behv=>mk-on ) )
33-
MAPPED DATA(ls_mapped_act)
34-
FAILED DATA(ls_failed_act)
35-
REPORTED DATA(ls_reported_act).
48+
FROM VALUE #( ( %key-SalesOrder = `0000004711`
49+
%key-IsActiveEntity = abap_false ) )
50+
FAILED DATA(ls_failed)
51+
REPORTED DATA(ls_reported).
3652
37-
COMMIT ENTITIES BEGIN
38-
RESPONSE OF i_salesordertp
39-
FAILED DATA(ls_save_failed)
40-
REPORTED DATA(ls_save_reported).
41-
COMMIT ENTITIES END.
53+
COMMIT ENTITIES.
4254
```
4355

44-
For more on EML in abap2UI5 apps, see [CDS, EML](./cds.md).
45-
4656
::: tip
47-
Draft tables hold exclusive locks for the draft owner. Combine draft handling with [Locks](./locks.md) only when you also need backend lock objects outside of RAP.
57+
A draft-enabled BO holds an exclusive lock for its owner as long as the draft exists, so the app can stay stateless and the user can resume work later. If you need additional locks for non-draft objects, see [Locks](./locks.md).
4858
:::
49-
50-
## 8. Scenario 7 — Standard SAP BO draft via EML
51-
52-
**Source:** [`scenarios/z2ui5_test_lock_07.clas.abap`](scenarios/z2ui5_test_lock_07.clas.abap)
53-
54-
If you are on **S/4HANA** or **BTP ABAP Environment (Steampunk)** and the business object you want to edit is already shipped by SAP as a draft-enabled BO (e.g. `I_SalesOrderTP`), you do not build your own BO and you do not create a draft table. SAP ships both. Your abap2UI5 app simply calls the standard BO via EML.
55-
56-
This sidesteps the whole lock-during-think-time problem.
57-
58-
The flow the user sees in the demo class:
59-
60-
```
61-
on_init -> Edit (create or resume the draft)
62-
"Save Draft" pressed -> UPDATE (writes the draft only, VBAK stays as-is)
63-
"Save Draft" again -> UPDATE (still draft)
64-
...
65-
"Activate" pressed -> Activate (now VBAK is written through)
66-
"Discard" pressed -> Discard (drops the draft, releases lock)
67-
```
68-
69-
**When to use this:**
70-
- The business object you need is already a released, draft-enabled SAP BO
71-
- You want classic Fiori-style "edit a draft, activate later" UX in an abap2UI5 app
72-
73-
**Key idea:** the session can stay **stateless**. The draft survives between roundtrips in SAP's own draft-shadow table. The lock is held by the BO framework as long as the draft exists — closing the browser without activating or discarding leaves the draft so the same user can resume it on the next visit. No `set_session_stateful( )`, no `ENQUEUE_*`, no custom Z table — SAP does all of that.
74-
75-
**Caveat:** field names (`SalesOrder`, `SalesOrderType`) match the released `I_SalesOrderTP` on current S/4HANA. On older releases the BO name or fields may differ — check the released-objects list in your system.
76-
77-
**If no standard BO exists** for your object — for instance because you are editing a custom Z business object — you would have to define your own draft-enabled RAP BO (with its own `draft table z…_d`, `lock master`, etc.) and consume that via EML in the same way. That is a separate topic; see the official [SAP RAP draft documentation](https://help.sap.com/docs/abap-cloud/abap-rap/draft).
78-
79-
---
80-
81-
### example
82-
83-
```abap
84-
* Scenario 7 — Consume a standard SAP draft-enabled BO via EML
85-
*
86-
* You are on S/4HANA or BTP ABAP Environment. The sales order is
87-
* already exposed by SAP as a draft-enabled BO (I_SalesOrderTP). You
88-
* do NOT build your own BO and you do NOT create a draft table — SAP
89-
* ships both.
90-
*
91-
* The flow the user sees:
92-
* on_init -> Edit (create or resume the draft)
93-
* "Save Draft" pressed -> UPDATE (writes the draft only)
94-
* "Save Draft" again -> UPDATE (still draft, VBAK untouched)
95-
* ...
96-
* "Activate" pressed -> Activate (now VBAK is written)
97-
* "Discard" pressed -> Discard (drops the draft, releases lock)
98-
*
99-
* The session stays stateless. The draft survives in SAP's own
100-
* draft-shadow table between roundtrips. The lock is held by the BO
101-
* framework as long as the draft exists; closing the browser without
102-
* discarding leaves the draft so the same user can resume it later.
103-
*
104-
* Field names below (SalesOrder, SalesOrderType) match the released
105-
* CDS view I_SalesOrderTP on current S/4HANA. On older releases the
106-
* BO name or fields may differ — check the released-objects list in
107-
* your system.
108-
109-
CLASS z2ui5_test_lock_07 DEFINITION PUBLIC.
110-
111-
PUBLIC SECTION.
112-
INTERFACES z2ui5_if_app.
113-
114-
DATA sales_order TYPE c LENGTH 10 VALUE `0000004711`.
115-
DATA sales_order_type TYPE c LENGTH 4.
116-
DATA draft_open TYPE abap_bool.
117-
DATA status_text TYPE string.
118-
119-
PROTECTED SECTION.
120-
DATA client TYPE REF TO z2ui5_if_client.
121-
122-
METHODS on_init.
123-
METHODS on_event_save_draft.
124-
METHODS on_event_activate.
125-
METHODS on_event_discard.
126-
METHODS draft_acquire.
127-
METHODS draft_read.
128-
METHODS view_display.
129-
130-
PRIVATE SECTION.
131-
ENDCLASS.
132-
133-
134-
CLASS z2ui5_test_lock_07 IMPLEMENTATION.
135-
136-
METHOD z2ui5_if_app~main.
137-
138-
me->client = client.
139-
140-
IF client->check_on_init( ).
141-
on_init( ).
142-
ELSEIF client->check_on_event( `SAVE_DRAFT` ).
143-
on_event_save_draft( ).
144-
ELSEIF client->check_on_event( `ACTIVATE` ).
145-
on_event_activate( ).
146-
ELSEIF client->check_on_event( `DISCARD` ).
147-
on_event_discard( ).
148-
ENDIF.
149-
150-
ENDMETHOD.
151-
152-
153-
METHOD on_init.
154-
155-
draft_acquire( ).
156-
draft_read( ).
157-
view_display( ).
158-
159-
ENDMETHOD.
160-
161-
162-
METHOD draft_acquire.
163-
164-
" Edit is idempotent: if the user already has a draft for this
165-
" sales order, SAP returns it instead of failing.
166-
167-
MODIFY ENTITIES OF i_salesordertp
168-
ENTITY SalesOrder
169-
EXECUTE Edit
170-
FROM VALUE #( ( %key-SalesOrder = sales_order
171-
%param-PreserveChanges = abap_true ) )
172-
FAILED DATA(failed)
173-
REPORTED DATA(reported).
174-
175-
IF failed IS NOT INITIAL.
176-
draft_open = abap_false.
177-
status_text = `Could not open draft — locked by another user, or no authorization.`.
178-
RETURN.
179-
ENDIF.
180-
181-
COMMIT ENTITIES.
182-
183-
draft_open = abap_true.
184-
status_text = `Draft open — changes are saved as a draft until you press Activate.`.
185-
186-
ENDMETHOD.
187-
188-
189-
METHOD draft_read.
190-
191-
IF draft_open = abap_false.
192-
RETURN.
193-
ENDIF.
194-
195-
READ ENTITIES OF i_salesordertp
196-
ENTITY SalesOrder
197-
FIELDS ( SalesOrderType )
198-
WITH VALUE #( ( %key-SalesOrder = sales_order
199-
%key-IsActiveEntity = abap_false ) )
200-
RESULT DATA(drafts).
201-
202-
IF drafts IS NOT INITIAL.
203-
sales_order_type = drafts[ 1 ]-SalesOrderType.
204-
ENDIF.
205-
206-
ENDMETHOD.
207-
208-
209-
METHOD on_event_save_draft.
210-
211-
" Persists progress to the draft only. VBAK is NOT touched.
212-
" The user can press Save Draft many times across many roundtrips.
213-
214-
MODIFY ENTITIES OF i_salesordertp
215-
ENTITY SalesOrder
216-
UPDATE FIELDS ( SalesOrderType )
217-
WITH VALUE #( ( %tky-SalesOrder = sales_order
218-
%tky-IsActiveEntity = abap_false
219-
SalesOrderType = sales_order_type
220-
%control-SalesOrderType = if_abap_behv=>mk-on ) )
221-
FAILED DATA(failed)
222-
REPORTED DATA(reported).
223-
224-
IF failed IS NOT INITIAL.
225-
client->message_box_display( `Draft update failed.` ).
226-
RETURN.
227-
ENDIF.
228-
229-
COMMIT ENTITIES.
230-
client->message_toast_display( `Draft saved.` ).
231-
232-
ENDMETHOD.
233-
234-
235-
METHOD on_event_activate.
236-
237-
" Writes the draft through to the active sales order (VBAK) and
238-
" deletes the draft. Lock is released by the framework.
239-
240-
MODIFY ENTITIES OF i_salesordertp
241-
ENTITY SalesOrder
242-
EXECUTE Activate
243-
FROM VALUE #( ( %key-SalesOrder = sales_order
244-
%key-IsActiveEntity = abap_false ) )
245-
FAILED DATA(failed)
246-
REPORTED DATA(reported).
247-
248-
IF failed IS NOT INITIAL.
249-
client->message_box_display( `Activation failed — see application log.` ).
250-
RETURN.
251-
ENDIF.
252-
253-
COMMIT ENTITIES.
254-
client->message_toast_display( `Sales order activated.` ).
255-
client->nav_app_leave( ).
256-
257-
ENDMETHOD.
258-
259-
260-
METHOD on_event_discard.
261-
262-
MODIFY ENTITIES OF i_salesordertp
263-
ENTITY SalesOrder
264-
EXECUTE Discard
265-
FROM VALUE #( ( %key-SalesOrder = sales_order
266-
%key-IsActiveEntity = abap_false ) )
267-
FAILED DATA(failed)
268-
REPORTED DATA(reported).
269-
270-
COMMIT ENTITIES.
271-
client->nav_app_leave( ).
272-
273-
ENDMETHOD.
274-
275-
276-
METHOD view_display.
277-
278-
DATA(view) = z2ui5_cl_xml_view=>factory( ).
279-
view->shell(
280-
)->page(
281-
title = `Edit Sales Order — Standard BO Draft via EML`
282-
shownavbutton = client->check_app_prev_stack( )
283-
navbuttonpress = client->_event( `DISCARD` )
284-
)->simple_form(
285-
title = `Header (draft)`
286-
editable = draft_open
287-
)->content( `form`
288-
)->label( `Sales Order`
289-
)->input(
290-
value = sales_order
291-
enabled = abap_false
292-
)->label( `Type`
293-
)->input( client->_bind_edit( sales_order_type )
294-
)->label( `Status`
295-
)->input(
296-
value = status_text
297-
enabled = abap_false
298-
)->button(
299-
text = `Save Draft`
300-
press = client->_event( `SAVE_DRAFT` )
301-
enabled = draft_open
302-
)->button(
303-
text = `Activate`
304-
type = `Emphasized`
305-
press = client->_event( `ACTIVATE` )
306-
enabled = draft_open
307-
)->button(
308-
text = `Discard`
309-
press = client->_event( `DISCARD` ) ).
310-
client->view_display( view->stringify( ) ).
311-
312-
ENDMETHOD.
313-
314-
ENDCLASS.
315-
```abap

0 commit comments

Comments
 (0)