- SAP Managed Tags:
Following the 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, here I would like to show you how you can create RAP Business Events in an OP system.
With the release 2022, SAP supports the native exposure and consumption of business events for on-premise systems as well. 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 ready-to-use event consumption models using the event consumer wizard embedded in ABAP Development Tools for Eclipse. This is explained in another post later.
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. For those who read the corresponding blog post for creating RAP events in the Cloud, you can skip from this part until the connection to the SAP Event Mesh which is the main difference between the two.
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.
From release 2022 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, SAP BTP ABAP Environment and SAP S/4HANA Cloud (Embedded Steampunk).
A RAP event has the following characteristics at design time:
At runtime
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 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.
First, we must 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 SAP Event Mesh system. We also implement a method where we raise the event.
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.
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. Basically, 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 behaviour 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’.
We activate this BO and with this, we model a new event called ‘BookingCancelled’.
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:
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 required is a minimal RAP implementation that provides a method that raises the event that can be called from existing non-RAP .
After an event is raised, it must be delivered to the SAP Event Mesh to be consumed later. The connection between the system and the SAP Event Mesh is achieved through a so-called channel. In the Cloud, we need to create a communication arrangement to provide the channel. However, in on premise you can directly create the channel in the system.
A channel represents a single connection to a service instance of the SAP Event Mesh. As a prerequisite, you need to prepare an SAP Event Mesh instance in your SAP business technology platform system and download the service key of this instance.
In your system, run the transaction /IWXBE/CONFIG and press the ‘📄via Service Key’ button to create a new channel.
Paste the service key of your SAP Event Mesh instance into the corresponding field. Destination name and OAuth Configuration name are optional fields. These are filled with random names if left empty.
The daemon user denotes the user under which the daemon session is running. The daemon sessions are background processes that are responsible for keeping the connection open and process the events. There is a corresponding role for the customer to use SAP_IWXBE_RT_XBE_DAEMON, which has all the required authorizations.
Once you filled out all necessary fields hit save. Your newly created channel will now show up in the channel list. Activate the channel by pressing the ‘Activate’ button. If the channel is active, it should appear with a green box under active channels.
In case the green status isn’t shown, you might need to refresh because the background session needs time to start.
After creating a channel, you can decide which events should be listed on this channel. This explicit step of maintaining an outbound binding is necessary to publish events by an SAP S/4HANA system.
To send the created event to the SAP Event Mesh, you need to configure the outbound bindings for this channel. In the channel config UI, you can simply click on ‘Outbound Bindings’ to start configuring the event topics to be sent to SAP Event Mesh. Alternatively, you can run /IWXBE/OUTBOUND_CFG.
Select your channel, click on creates new topic binding and choose the topic which is generated during the event binding creation.
You can also monitor the generated event with /IWXBE/EVENT_MONITOR in your SAP S/4HANA system:
A RAP event is modelled 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 SAP Event Mesh service. You also need to create and configure your channel in your SAP S/4HANA system. More you can find 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.
With the release 2022, SAP supports the native exposure and consumption of business events for on-premise systems as well. 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 ready-to-use event consumption models using the event consumer wizard embedded in ABAP Development Tools for Eclipse. This is explained in another post later.
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. For those who read the corresponding blog post for creating RAP events in the Cloud, you can skip from this part until the connection to the SAP Event Mesh which is the main difference between the two.
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.
From release 2022 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, SAP BTP ABAP Environment 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 SAP 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 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 must 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 SAP 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. Basically, 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 behaviour 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 SAP 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 in OP' ) ) ).
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 required is a minimal RAP implementation that provides a method that raises the event that can be called from existing non-RAP .
Send the Event to SAP Event Mesh
After an event is raised, it must be delivered to the SAP Event Mesh to be consumed later. The connection between the system and the SAP Event Mesh is achieved through a so-called channel. In the Cloud, we need to create a communication arrangement to provide the channel. However, in on premise you can directly create the channel in the system.
Creating a channel using a service key
A channel represents a single connection to a service instance of the SAP Event Mesh. As a prerequisite, you need to prepare an SAP Event Mesh instance in your SAP business technology platform system and download the service key of this instance.
In your system, run the transaction /IWXBE/CONFIG and press the ‘📄via Service Key’ button to create a new channel.
Paste the service key of your SAP Event Mesh instance into the corresponding field. Destination name and OAuth Configuration name are optional fields. These are filled with random names if left empty.
The daemon user denotes the user under which the daemon session is running. The daemon sessions are background processes that are responsible for keeping the connection open and process the events. There is a corresponding role for the customer to use SAP_IWXBE_RT_XBE_DAEMON, which has all the required authorizations.
Once you filled out all necessary fields hit save. Your newly created channel will now show up in the channel list. Activate the channel by pressing the ‘Activate’ button. If the channel is active, it should appear with a green box under active channels.
In case the green status isn’t shown, you might need to refresh because the background session needs time to start.
After creating a channel, you can decide which events should be listed on this channel. This explicit step of maintaining an outbound binding is necessary to publish events by an SAP S/4HANA system.
Configure outbound bindings
To send the created event to the SAP Event Mesh, you need to configure the outbound bindings for this channel. In the channel config UI, you can simply click on ‘Outbound Bindings’ to start configuring the event topics to be sent to SAP Event Mesh. Alternatively, you can run /IWXBE/OUTBOUND_CFG.
Select your channel, click on creates new topic binding and choose 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. For more information on how to create a queue, check this blog post.
Run the booking application, select the entry with the chosen ID and delete it. An event will be raised then.
Now we check the SAP 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.
You can also monitor the generated event with /IWXBE/EVENT_MONITOR in your SAP S/4HANA system:
Summary
A RAP event is modelled 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 SAP Event Mesh service. You also need to create and configure your channel in your SAP S/4HANA system. More you can find 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.
14 Comments
