How to Create RAP Business Events in SAP BTP ABAP Environment

This blog is the second post from a blog series of enterprise event enablement and the possible ways to produce and consume an event in SAP BTP ABAP Environment and SAP S/4 HANA Cloud. In the first post, I gave you a rough introduction on the basics of event-based communication. Here, you will see how you can implement a RAP event.

With the release 2208, SAP supports the native exposure and consumption of business events. To consume an event, you can generate ready-to-use event consumption models using the event consumer wizard embedded in ABAP Development Tools for Eclipse. This is explained in the third post of this blog series, consuming an event using the event consumer wizard ,embedded in ABAP Development Tools for Eclipse (ADT).

For exposure, an event can be defined and raised in the behaviour definition of a RAP business object and then published via a corresponding Event Binding. Let us explore this in detail here.

Introduction

Event-driven architecture enables asynchronous communication between an event provider and an event consumer in use cases where no direct response from the event consumer is required. Previously, events could only be defined in SAP S/4HANA with the help of Business Event Enablement (releases 2008 to 2205). However, this solution is not integrated into RAP. Therefore, from release 2208 we offer a RAP integrated solution supporting all RAP qualities like extensibility, documentability, supportability and testability. The solution is offered for customers and partners in on-premise, Steampunk and SAP S/4HANA Cloud (Embedded Steampunk).

A RAP event has the following characteristics at design time:

• An event is directly defined via RAP behaviour definition (BDEF)
• Events can be added via extensions (BDEF additional behaviour)
• The event exposure is represented by a corresponding RAP Event Binding that supports an event specific life cycle incl. API state. Events are part of the BO and have the same life cycle.

At runtime

• A RAP BO implementation can register an event, which will be raised later shortly before a commit is triggered
• Dedicated API in ABAP supports event registration
• The events are forwarded to the central event infrastructure and later propagated asynchronously to the BTP Event Mesh.

Usually, an event with the respective message is raised after a change of the business object has been completed. For example, if a BO entity like a travel or a booking has been created, updated, or deleted. When the changed business object is saved to the database, the event is raised during the SAVE sequence after the point of no return has passed.

How to Create Business Events with RAP

First, we have to define a business event in our behaviour definition, then we will see how to map this implementation detail to the outer business event world using a channel to the Event Mesh system. We also implement a method where we raise the event.

 Prerequisite: Create a Custom RAP Business Object

As prerequisite, you need to define your BO. You can follow exercise1 of  RAP 100 to build the booking application. If you already have a BO, you can extend your own BO with the appropriate logic.

Create an Event in Behaviour Definition

An event can be defined in the behaviour definition of a RAP business object with the key word event *EventName* with or without parameters. There might be various ways to raise an entity event in your RAP business object implementation. Basicly, you can raise an event either inside your BO implementation, i.e. in  “save modified” method or outside the BO implementation by creating e.g. a static method in the global class pool of the behavior implementation class. However, it is recommended to raise events during (additional) save.

Let’s create an event which is raised when a booking flight is cancelled. For this, go to the behaviour definition and add a new event to the business object. The event name is ‘BookingCancelled’

This is the code snippet you need to add to the behaviour definition:

event BookingCancelled parameter ZD_CancelingReason;

In addition, we want to provide a cancellation reason and description. So, we define an additional parameter as an abstract entity, where we put those definitions.

@EndUserText.label: 'booking cancelation reason'
  define abstract entity ZD_CancelingReason 
{
  ReasonCode : abap.char(2);  
  Description : abap.char(64);
}

We activate this BO and with this, we model a new event called ‘BookingCancelled’.

Creation of an Event Binding for Our New Business Event

Now we create the event binding for our newly created business event. This event binding is needed to map the RAP business event to the external event infrastructure. Additionally, the event binding ensures that this event is linked to SAP Event Mesh.

To create a new event binding in your package, right click on Business Service > New > Event Binding. Provide a Namespace, the business object name, and the business event topic (business object operation). You can freely choose these names to specify your event.

Next step is to map this event binding to your RAP business event. Click on ‘Add’. Under event items select the version (in future we might have several versions) and pick the business object name and the event name defined in your behaviour definition as it is shown in this following screenshot:

Click Add so the event will be created. Now activate the Event Binding. As you can see in the screenshot, the type (aka topic) is a concatenation of the three attributes (name space, business object, business object operation) followed by the version of the event. So, the wildcard * points to the corresponding event version. This is relevant for addressing the events to the Event Mesh.

Raise an Event

As said, an event is triggered in a save sequence. So, to raise an event, we implement the logic in ‘save modified’ method of the implementation class:

CLASS lcl_event_handler DEFINITION INHERITING FROM cl_abap_behavior_saver.

  PROTECTED SECTION.
    METHODS save_modified REDEFINITION.

ENDCLASS.

CLASS lcl_event_handler IMPLEMENTATION.

  METHOD save_modified.
    IF delete-booking IS NOT INITIAL.
      RAISE ENTITY EVENT zr_bookingdata~BookingCancelled
    FROM VALUE #( FOR <s_travel> IN delete-booking  ( TravelID = <s_travel>-TravelID  %param = VALUE #( reasoncode ='02'  description = 'cancelled by customer' ) ) ).

The event payload data will include both the key fields of the entity and the fields of the parameter (abstract entity). In case no parameter is specified, the payload only consists of the entity key fields. Here, an event with key field travel ID and given parameter values will be raised as we delete an entry. 

It is also possible to raise the RAP-based event from existing code outside a RAP implementation. So, It is not required to have a managed RAP entity. All that is requiered is a minimal RAP implementation that provides a method that raises the event that can be called from existing non-RAP code.

Send the Event to SAP Event Mesh

After an event is raised, it is delivered to the Event Mesh to be consumed later. The connection between the system and the SAP Event Mesh is achieved through a so-called channel. To this aim, we need to create a communication arrangement in our SAP BTP ABAP environment system using the event mesh instance’s service key and the sap_com_0092 scenario which is built for an event enablement.

Add the Event to an Outbound Channel

By creating a communication arrangement, a channel will be stablished between the BTP system and the event mesh system. Now we need to add the event to the outbound channel. This is done by the outbound configuration. After selecting your channel in ‘Enterprise Event Enablement’ application, click on ‘create’ and find the topic which is generated during the event binding creation.

In the SAP Event Mesh system, create a queue for the selected instance and subscribe it to your topic. You can find the topic by opening the Event Metadata and copy the channel from there.

Run the booking application, select the entry with the chosen ID and delete it. An event will be raised then.

Now we check the Event Mesh service to see if this event has arrived. The event payload data will include both the key fields of the entity and the fields of the parameter. You see the type which has been defined in the event binding. The field ‘data’ of the event payload contains the key of the business object and the event parameter structure.

Summary

A RAP event is modeled as a part of the behaviour definition (BDEF) and linked to the payload. The key information is derived from the RAP object. Additionally, a RAP binding is mapping the implementation in RAP to the SAP Object Type (SOT), event operation and version information that is used to create the topic which can be consumed in Event Mesh service. You can also follow this tutorial to try it yourself.

From release 2022, RAP BO can also be created in S/4HANA On Premise as it is explained in here. Besides, an event which is implemented in RAP can be called from everywhere, also from legacy coding. For more information please refer to this post.

To consume an event, you can generate the event consumption model from the event meta data using an event consumer wizard embedded in ADT. If you just hang tight, I’ll explain this in the next post!