feat: persisted fiori draft messages

advanced/fiori.md

@@ -466,12 +466,38 @@ POST /odata/v4/AdminService/Books(ID=a11fb6f1-36ab-46ec-b00c-d379031e817a,IsActi
 Content-Type: application/json
 
 {}
-
+```
 
 For more details, see the [official UI5 documentation](https://ui5.sap.com/#/topic/ed9aa41c563a44b18701529c8327db4d).
 
 ### Validating Drafts
 
+With Fiori draft state messages, you benefit from the following improvements without any change in your application code:
+- The UI displays error messages for annotation-based validations (such as `@mandatory` or `@assert...`) while editing drafts.
+- You can register [custom validations](#custom-validations) to the `PATCH` event and write (error) messages. The draft choreography ensures the invalid value still persists.
+- Messages remain visible in the UI, even after editing other fields.
+- The UI automatically loads messages when reopening a previously edited draft.
+CAP generates side-effect annotations in the EDMX to instruct UI5 to fetch state messages after every `PATCH` request. To control side-effect annotations more precisely, override or disable them per entity:
+
+  ```cds
+  // Setting `null` disables the side-effect annotation for always fetching messages.
+  annotate MyService.MyEntity with @Common.SideEffects #alwaysFetchMessages: null;
+  ```
+
+For this feature to work correctly, CAP adds additional elements to your draft-enabled entities and [`DraftAdministrativeData`](/guides/security/data-protection-privacy#dpp-cap) to store and serve the state messages. CAP runtimes persist (error) messages for draft-enabled entities.
+
+::: warning Requires Schema Update
+This feature initiates a database schema update, as it adds an additional element to `DraftAdministrativeData`.
+:::
+
+::: warning Requires OData V4 and UI5 version >=1.135.0
+State messages require UI5 to use _document URLs_. CAP sets the `@Common.AddressViaNavigationPath` annotation to enable this. You need OData V4 and UI5 version >= 1.135.0. OData V2 does not support this annotation.
+:::
+To disable this feature, set <Config>cds.fiori.draft_messages:false</Config>.
+
+
+#### Custom Validations
+
 You can add [custom handlers](../guides/providing-services#custom-logic) to add specific validations, as usual. In addition, for a draft, you can register handlers to the respective `UPDATE` events to validate input per field, during the edit session, as follows.
 
 

java/fiori-drafts.md

@@ -94,46 +94,6 @@ The `DRAFT_CREATE` is an internal event that is not triggered by OData requests
 
 For more examples, see the [Bookshop sample application](https://github.com/SAP-samples/cloud-cap-samples-java/tree/master/srv/src/main/java/my/bookshop/handlers/AdminServiceHandler.java).
 
-## Validating Drafts <Beta />
-
-CAP Java can provide _state messages_ to the UI5 OData V4 model. This enables validations of drafts and giving feedback about errors to users faster in the UI.
-
-To enable this feature, set the following properties in your `.cdsrc.json`:
-
-::: code-group
-```json [.cdsrc.json]
-{
-  "cdsc": {
-    "draftMessages": true
-  }
-}
-```
-:::
-
-::: warning Uses _document URLs_ and requires UI5 version >=1.135.0
-The _state messages_ feature relies on UI5 to use _document URLs_. That's because, with this feature enabled, CAP sets the annotation `@Common.AddressViaNavigationPath` to instruct UI5 to use _document URLs_. In turn, this requires UI5 version >= 1.135.0.
-:::
-
-Setting the `draftMessages` property adds additional elements to your draft-enabled entities and [`DraftAdministrativeData`](/guides/security/data-protection-privacy#dpp-cap), which are required to store and serve state messages. For this to work, CAP Java supports persisting (error) messages for draft-enabled entities.
-
-If you activate this feature, you can observe the following improvements, without any changes to the application code:
-
-- Error messages for annotation-based validations (for example, `@mandatory` or `@assert...`) already appear while editing the draft.
-- Custom validations can now be registered to the `DRAFT_PATCH` event and can write (error) messages. It's ensured that the invalid value is still persisted, as expected by the draft choreography.
-- Messages no longer unexpectedly vanish from the UI after editing another field.
-- Messages are automatically loaded when reopening a previously edited draft.
-
-By default, when activating this state messages, side-effect annotations are generated in the EDMX that instruct UI5 to fetch state messages after every `PATCH` request. If you require more precise control over side-effect annotations, you can disable the side-effect annotation per entity:
-
-```cds
-// Setting `null` disables the side-effect annotation for always fetching messages.
-annotate MyService.MyEntity with @Common.SideEffects #alwaysFetchMessages: null;
-```
-
-::: warning Requires Schema Update
-Enabling draft messages requires a database schema update, as it adds an additional element to `DraftAdministrativeData`.
-:::
-
 ## Activating Drafts
 
 When you finish editing drafts by pressing the *Save* button, a draft gets activated. That means, either a single `CREATE` or `UPDATE` event is triggered to create or update the active entity with all of its compositions through a deeply structured document. You can register to these events to validate the activated data.