Search

Fiori Drafts

This section describes which events occur in combination with SAP Fiori Drafts.

Content

Overview

See Advanced > Draft-based Editing for an overview on SAP Fiori Draft support in CAP.

Editing Drafts

When users edit a draft-enabled entity in the frontend, the following requests are sent to the CAP Java backend. As an effect, draft-specific events are triggered, as described in the following table. The draft-specific events are defined by the DraftService interface.

Note

Draft-enabled entities have an extra key IsActiveEntity by which you can access either the active entity or the draft (inactive entity).

Request sent by Fiori frontend Event name Default implementation
POST DraftService.EVENT_DRAFT_NEW Creates a new empty draft
PATCH with key IsActiveEntity=false DraftService.EVENT_DRAFT_PATCH Updates an existing draft
DELETE with key IsActiveEntity=false DraftService.EVENT_DRAFT_CANCEL Deletes an existing draft
DELETE with key IsActiveEntity=true CdsService.EVENT_DELETE Deletes an active entity and the corresponding draft
POST with action draftPrepare DraftService.EVENT_DRAFT_PREPARE Empty implementation
POST with action draftEdit DraftService.EVENT_DRAFT_EDIT Creates a new draft from an active entity
POST with action draftActivate DraftService.EVENT_DRAFT_SAVE Activates a draft and updates the active entity. Triggers an EVENT_CREATE or EVENT_UPDATE event on the affected entity.

You can use these events to add custom logic to the SAP Fiori draft flow, for example to interact with drafts or to validate user data.

The following example registers a @Before handler to fill in default-values into a draft before the user starts editing:

@Before(event = DraftService.EVENT_DRAFT_NEW)
public void prefillOrderItems(DraftNewEventContext context, OrderItems orderItem) {
    // Pre-fill fields with default values
}

For more examples, see the Bookshop sample application.

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.

The following example shows how to validate user input right before an active entity gets created:

@Before(event = CdsService.EVENT_CREATE)
public void validateOrderItem(CdsCreateEventContext context, OrderItems orderItem) {
    // Add validation logic
}

After a draft is activated, it’s deleted from the database.

Working with Draft-Enabled Entities

When deleting active entities that have a draft, the draft is deleted as well. In this case, a DELETE and DRAFT_CANCEL event are triggered.

To read an active entity, send a GET request with key IsActiveEntity=true, for example:

GET /v4/myservice/myentity(IsActiveEntity=true,ID=<key>);

Likewise, to read the corresponding draft, call:

GET /v4/myservice/myentity(IsActiveEntity=false,ID=<key>);

To get all active entities, you could use a filter as illustrated by the following example:

GET /v4/myservice/myentity?$filter=IsActiveEntity eq true

Bypassing the SAP Fiori Draft Flow

It’s possible to create and update data directly without creating intermediate drafts. For example, this is useful when prefilling draft-enabled entities with data or in general, when technical components deal with the API exposed by draft-enabled entities. To achieve this, use the following requests. You can register event handlers for the corresponding events to validate incoming data:

HTTP / OData request Event name Default implementation
PUT with key IsActiveEntity=true CdsService.EVENT_CREATE
CdsService.EVENT_UPDATE
Creates or updates the active entity (full update)
PATCH with key IsActiveEntity=true CdsService.EVENT_UPDATE
CdsService.EVENT_UPDATE
Creates or updates the active entity (sparse update)

These events have the same semantics as described in section Event Flow.

Garbage Collecting Drafts

Inactive drafts are automatically deleted after a timeout (30 days default). You can configure the timeout with the following application configuration property:

cds.drafts.deletionTimeout: 8w

In this example, the draft timeout is set to 8 weeks.

This feature can be also turned off completely by setting the application configuration:

cds.drafts.gc.enabled: false

To get notified when a particular draft-enabled entity is garbage collected, you can register an event handler on the DraftService.EVENT_DRAFT_CANCEL event.

Overriding SAP Fiori’s Draft Creation Behaviour

By default SAP Fiori triggers a POST request with an empty body to the entity collection to create a new draft. This behavior can be overridden by implementing a custom action, which SAP Fiori will trigger instead.

  1. Define an action, which is bound to the draft-enabled entity, and annotate it with @cds.odata.bindingparameter.collection.

    The action, that is used to create a new draft needs to be bound to the collection of the draft-enabled entity.

  2. Annotate the draft-enabled entity with @Common.DraftRoot.NewAction: '<action name>'.

    This indicates to SAP Fiori that this action should be used when creating a new draft.

  3. Implement the action in Java.

    The implementation of the action must trigger the newDraft(CqnInsert) method of the DraftService interface to create the draft. In addition, it must return the created draft entity.

The following code summarizes all of these steps in an example:

service AdminService {
  @odata.draft.enabled
  @Common.DraftRoot.NewAction: 'AdminService.createDraft'
  entity Orders as projection on my.Orders actions {
    @cds.odata.bindingparameter.collection
    action createDraft(orderNo: String) returns Orders;
  };
}
@On(entity = Orders_.CDS_NAME)
public void createDraft(CreateDraftContext context) {
    Orders order = Orders.create();
    order.setOrderNo(context.getOrderNo());
    context.setResult(adminService.newDraft(Insert.into(Orders_.class).entry(order)).single(Orders.class));
}