Skip to content

Review on Java - Validating Drafts #1917

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Review on Java - Validating Drafts #1917

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 8 additions & 9 deletions java/fiori-drafts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,8 +96,7 @@ For more examples, see the [Bookshop sample application](https://github.com/SAP-

## Validating Drafts <Beta />

CAP Java supports persisting (error) messages for draft-enabled entities and providing _state messages_ to the UI5 OData V4 model.
This enables validations of drafts and giving feedback about errors to users faster in the UI.
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`:

Expand All @@ -113,23 +112,23 @@ To enable this feature, set the following properties in your `.cdsrc.json`:
```
:::

::: warning Document-based URLs
The state messages feature relies on UI5 to use _document URLs_. CAP sets the annotation `@Common.AddressViaNavigationPath` to instruct UI5 to use _document URLs_. This requires UI5 version >= 1.135.0.
::: warning Uses _document URLs_ and requires UI5 version >=1.135.0
The _state messages_ feature relies on UI5 to use _document URLs_. CAP sets the annotation `@Common.AddressViaNavigationPath` to instruct UI5 to use _document URLs_. This requires UI5 version >= 1.135.0.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The _state messages_ feature relies on UI5 to use _document URLs_. CAP sets the annotation `@Common.AddressViaNavigationPath` to instruct UI5 to use _document URLs_. This 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.
Suggested change
The _state messages_ feature relies on UI5 to use _document URLs_. CAP sets the annotation `@Common.AddressViaNavigationPath` to instruct UI5 to use _document URLs_. This requires UI5 version >= 1.135.0.
The _state messages_ feature relies on UI5 to use _document URLs_. CAP sets the annotation `@Common.AddressViaNavigationPath` to instruct UI5 to use _document URLs_. This requires UI5 version >= 1.135.0.

:::

Setting this property adds additional elements to your draft-enabled entities and `DraftAdministrativeData`, which are required to store and serve state messages.
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 this feature is activated, you can observe the following improvements, without any changes to the application code:
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 bound 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.
- 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, side-effect annotations are generated in the EDMX that instruct UI5 to fetch state messages after every `PATCH` request.
In case more precise side-effect annotations are required you can disable the default side-effect annotation per entity:
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;
```

Expand Down