feat: direct CRUD in both stacks

guides/uis/fiori.md

@@ -448,6 +448,73 @@ Content-Type: application/json
 
 For more details, see the [official UI5 documentation](https://ui5.sap.com/#/topic/ed9aa41c563a44b18701529c8327db4d).
 
+
+### Direct CRUD
+
+By default, all modifications to draft-enabled entities go through the [draft choreography](#draft-choreography-how-draft-editing-works), which is optimized for human users working with SAP Fiori UIs.
+However, technical consumers — such as remote services or AI agents — typically need to create and update data directly, without the overhead of draft management.
+Activating Direct CRUD with <Config>cds.fiori.direct_crud:true</Config> enables the best of both worlds: standard CRUD operations on active entities are restored, while the full draft feature set stays intact for SAP Fiori UIs.
+
+To achieve this, SAP Fiori Elements' default draft-creation behavior is redirected to a collection-bound action via the `@Common.DraftRoot.NewAction` annotation.
+This frees up `POST` requests to create active instances directly — the same behavior as without draft enablement.
+
+#### Creating Active Instances Directly
+
+```http
+POST /odata/v4/CatalogService/Books
+Content-Type: application/json
+
+{
+  "ID": 123,
+  "title": "How to be more active"
+}
+```
+
+In such direct requests, the additional key `IsActiveEntity` defaults to `true` in the body, which means you can omit it during a `CREATE`.
+
+#### Creating Draft Instances via Action
+
+```http
+POST /odata/v4/CatalogService/Books/CatalogService.draftNew
+Content-Type: application/json
+
+{}
+```
+
+#### Updating Active Instances Directly
+
+```http
+PUT /odata/v4/CatalogService/Books(ID=123)
+Content-Type: application/json
+
+{
+  "title": "Updated title"
+}
+```
+
+In CAP Node.js, the defaulting of `IsActiveEntity` described above extends to the URL as well.
+That is, you can omit the key predicate `IsActiveEntity=true` from it.
+In CAP Java, however, the additional key predicate `IsActiveEntity=true` must still be provided.
+That is, in the example above, the `PUT` request would need to target `/odata/v4/CatalogService/Books(ID=123,IsActiveEntity=true)`.
+
+:::tip Draft locks still apply
+Directly updating an active entity does **not** bypass draft locks.
+If an existing draft locks the entity, direct updates are blocked to prevent losing draft changes upon activation.
+See draft lock configuration for [Node.js](../../node.js/fiori#draft-locks) or [Java](../../java/fiori-drafts#draft-lock).
+:::
+
+In CAP Node.js, Direct CRUD is a prerequisite for [SAP Fiori Elements Mass Edit](https://sapui5.hana.ondemand.com/sdk/#/topic/965ef5b2895641bc9b6cd44f1bd0eb4d.html), which allows users to change multiple objects with the same editable properties in one step — without creating individual drafts per row. All unlocked rows are updated even if some rows are locked and therefore fail.
+
+:::warning Additional entry points
+Both Direct CRUD and Mass Edit create additional entry points to your application.
+Custom handlers are triggered with delta payloads rather than the complete business object.
+:::
+
+[Learn more about Direct CRUD events in **Java**.](../../java/fiori-drafts#bypassing-draft-flow){.learn-more}
+
+[Learn more about draft-specific events in **Node.js**.](../../node.js/fiori#draft-specific-events){.learn-more}
+
+
 ### Validating Drafts
 
 With Fiori draft state messages, you benefit from the following improvements without any change in your application code:
@@ -491,6 +558,7 @@ You can add your validation logic before the operation handler for either CRUD o
 
 <div id="query-data-draft-enabled" />
 
+
 ### Query Drafts Programmatically
 
 To access drafts in code, you can use the [`.drafts` reflection](../../node.js/cds-reflect#drafts).
@@ -500,6 +568,7 @@ SELECT.from(Books.drafts) //returns all drafts of the Books entity
 
 [Learn how to query drafts in Java.](../../java/fiori-drafts#draftservices){.learn-more}
 
+
 ## Use Roles to Toggle Visibility of UI elements
 
 In addition to adding [restrictions on services, entities, and actions/functions](../security/authorization#restrictions), there are use cases where you only want to hide certain parts of the UI for specific users. This is possible by using the respective UI annotations like `@UI.Hidden` or `@UI.CreateHidden` in conjunction with `$edmJson` pointing to a singleton.

java/fiori-drafts.md

@@ -146,12 +146,13 @@ It's possible to create and update data directly without creating intermediate d
 
 These events have the same semantics as described in section [Handling CRUD events](./cqn-services/application-services#crudevents).
 
-::: tip
-With the 4.8.0 release, CAP Java introduced a mode where POST without `IsActiveEnitity=true` results in the `CqnService.EVENT_CREATE` (creation of an active entity) for the given entity. This mode is only active when the CDS property `cds.draft.post-active` is set to `true` and the entity is annotated with `@Common.DraftRoot.NewAction`. The annotation value needs to be the name of an unbound action in the same service of the entity. If the entity has a key with the type `UUID`, the action needs no further parameter. Otherwise, the action needs the key values of the entity as parameters.
+
+::: tip POST Behavior with Direct CRUD
+With the 4.8.0 release, CAP Java introduced a mode where `POST` without `IsActiveEntity=true` results in the `CqnService.EVENT_CREATE` (creation of an active entity) for the given entity. This mode is only active when the CDS property `cds.draft.post-active` is set to `true` and the entity is annotated with `@Common.DraftRoot.NewAction`. The annotation value needs to be the name of an unbound action in the same service of the entity. If the entity has a key with the type `UUID`, the action needs no further parameter. Otherwise, the action needs the key values of the entity as parameters.
 :::
 
-::: warning
-Directly updating the active entity does **not** bypass the [Draft Lock](#draft-lock). If an existing draft locks the active entity, the system blocks any attempt to update it. This ensures that the system does not lose changes to the active entity when you subsequently activate a draft.
+::: warning Draft locks still apply
+Directly updating the active entity does **not** bypass the [Draft Lock](#draft-lock). If an existing draft locks the active entity, the system blocks any attempt to update it directly. This ensures that the system does not lose changes to the active entity when you subsequently activate a draft.
 :::
 
 ## Draft Lock { #draft-lock }

node.js/fiori.md

@@ -191,48 +191,12 @@ It can occur that inactive drafts are still in the database after the configured
 
 ## Bypassing Drafts {.deprecated}
 
-Use [Direct CRUD](#direct-crud) instead.
+Use [Direct CRUD](../guides/uis/fiori#direct-crud) instead.
 
 Until the next major release (`cds10`), you can still activate the draft bypass without also allowing direct CRUD via <Config>cds.fiori.bypass_draft:true</Config>.
 
 
 
-## Direct CRUD <Beta />
-
-With <Config>cds.fiori.direct_crud:true</Config>, creating or modifying active instances directly is possible without creating drafts.
-This comes in handy when technical services without a UI interact with each other.
-
-That is, you can then create and modify active instances directly:
-
-```http
-POST /Books
-
-{
-  "ID": 123
-}
-```
-
-```http
-PUT /Books(ID=123)
-
-{
-  "title": "How to be more active"
-}
-```
-
-For this, the default draft creation behavior by SAP Fiori Elements is redirected to a collection-bound action via annotation `@Common.DraftRoot.NewAction`.
-The thereby freed `POST` request to draft roots without specifying `IsActiveEntity` leads to the creation of an active instance (as it would without draft enablement).
-
-The feature is required to enable [SAP Fiori Elements Mass Edit](https://sapui5.hana.ondemand.com/sdk/#/topic/965ef5b2895641bc9b6cd44f1bd0eb4d.html), allowing users to change multiple objects with the
-same editable properties without creating drafts for each row.
-
-:::warning Additional entry point
-Note that this feature creates additional entry points to your application. Custom handlers are triggered with delta
-payloads rather than the complete business object.
-:::
-
-
-
 ## Programmatic APIs <Beta />
 
 You can programmatically invoke draft actions with the following APIs: