RAP Business Events with Advanced Event Mesh [2]: Creating custom business events

This series of blogs intends to show in a step-by-step way the different possibilities to use RAP Business Events with Advanced Event Mesh.

 

Overview

In this second blog, we’re going to look at creating custom business events from scratch and publishing them to the Advanced Event Mesh. To be precise we’ll be creating a “Business Partner Address Changed” event that can be used to indicate that the address of a business partner has been changed. For that we’ll be creating a minimal RAP business object to contain the event, create a payload structure to be used by the event and finally create an event binding to publish the event.

 

Create a minimal RAP business object

To create a minimal RAP object, start of by creating a package to contain all repository artefacts. As we are able to use the “ABAP for Cloud Development” language version for that part, choose software component “ZLOCAL” when creating the package. To create the custom business object right click the created package and select “New” > “Other ABAP Repository Object”.

In the search field enter “Data Definition”, select the entry and hit “Next”.

Next enter the name and the description of the data definition and complete the creation of the data definition.

As the “Address Changed” event should be referencing the business partner adjust the data definition to be a selection on “I_BusinessPartner” and reference all keys of this object. The result should look something like this:

 

@AbapCatalog.viewEnhancementCategory: [#NONE]
@AccessControl.authorizationCheck: #NOT_REQUIRED
@EndUserText.label: ‘Business Partner View’
@Metadata.ignorePropagatedAnnotations: true
@ObjectModel.usageType:{
serviceQuality: #X,
sizeCategory: #S,
dataClass: #MIXED
}

define root view entity Z_ADDR_CHANGED as select from I_BusinessPartner
{
key BusinessPartner
}

 

Activate the data definition.

The just created data definition represents the root view of the new RAP business object. In the next step let’s create the associated behavior definition. 

For that right click the newly created data definition and select “New Behavior Definition”.

Fill out the creation wizard and finally hit “Finish”.

Adjust the behavior definition according to the following template:

 

managed with unmanaged save implementation in class zbp_addr_changed unique;
strict;

define behavior for Z_ADDR_CHANGED
lock master
authorization master ( instance )
{

}

 

Activate the behavior definition.

Define a new notification event

A new event can simply be defined in a behavior definition using the keyword “event” followed by the events name. To add the address changed event simply add “event AddressChanged” to the behavior definition.

 

managed with unmanaged save implementation in class zbp_addr_changed unique;
strict;

define behavior for Z_ADDR_CHANGED
lock master
authorization master ( instance )
{
event AddressChanged;
}

 

This event can then directly be raised through ABAP EML. Note that despite it not being a data event there still must be some data passed to the event. Specifically, the key of the business object where the event is defined at. This is required to associate the event with one specific object. In the case of the “AddressChanged” event the “BusinessPartner” has to be given.

 

DATA it_address_changed TYPE TABLE FOR EVENT Z_ADDR_CHANGED~AddressChanged.
it_address_changed = VALUE #( ( BusinessPartner = ‘0001’ ) ).
RAISE ENTITY EVENT Z_ADDR_CHANGED~AddressChanged FROM it_address_changed.

 

 

Define a new data event

To change a notification event within RAP to a data event, only an additional abstract entity is required to define the payload structure. For that right click your package and select “New” > “Other ABAP Repository Object” and again search for “Data Definition”. As we are creating an abstract entity you can either already choose the abstract entity template from the creation wizard or alternatively adjust the object afterwards. Within the entity, list all fields and their datatypes which should be included in the event payload. The resulting abstract entity should look as follows:

 

@EndUserText.label: ‘Address’
define abstract entity Z_ADDR_CHANGED_PAYLOAD
{
AddressNumber : abap.char(4);
FullAddress : abap.char(100);
}

 

Activate the entity.

This entity can then be passed to the event definition. For that simply add the key word “parameter” followed by the name of the abstract entity to the already defined notification event “AddressChanged” within the behavior definition.

 

managed with unmanaged save implementation in class zbp_addr_changed unique;
strict;

define behavior for Z_ADDR_CHANGED
lock master
authorization master ( instance )
{
event AddressChanged parameter Z_ADDR_CHANGED_PAYLOAD;
}

 

Activate the behavior definition.

Trigger an event

RAP events can be triggered using ABAP EML with the “RAISE ENTITY EVENT” statement. In addition, data can be passed to the event by adding the keyword “FROM”.

 

RAISE ENTITY EVENT Z_ADDR_CHANGED~AddressChanged FROM it_events.

 

However, since this statement can only be executed within the context of the RAP business object, it is recommended to use a wrapper method which in turn can be called from any environment.

Start by creating the implementation class of the previously created behavior definition. Simply place your cursor on the class reference and press “Ctrl + 1”. Finally select “Create behavior implementation class <class-name>”

Click through the wizard and finish the creation process.

In the global class add a new class method which can be called to trigger the address changed event. This requires firstly to create a table type of the “AddressChanged” event to use as an importing parameter to the method definition and secondly the class method itself which imports a table of the defined type.

 

CLASS zbp_addr_changed DEFINITION PUBLIC ABSTRACT FINAL FOR BEHAVIOR OF z_addr_changed.

TYPES tt_events TYPE TABLE FOR EVENT Z_ADDR_CHANGED~AddressChanged.

PUBLIC SECTION.
CLASS-METHODS raise_address_changed
IMPORTING it_events TYPE tt_events.

ENDCLASS.

 

Finally implement the method by calling a yet to be implemented local method “on_Address_Changed” and pass the imported table along.

 

CLASS zbp_addr_changed IMPLEMENTATION.

METHOD raise_address_changed.
lcl_event_handler=>on_Address_Changed( it_events ).
ENDMETHOD.

ENDCLASS.

 

The complete global class should look as follows:

 

CLASS zbp_addr_changed DEFINITION PUBLIC ABSTRACT FINAL FOR BEHAVIOR OF z_addr_changed.

TYPES tt_events TYPE TABLE FOR EVENT Z_ADDR_CHANGED~AddressChanged.

PUBLIC SECTION.
CLASS-METHODS raise_address_changed
IMPORTING it_events TYPE tt_events.

ENDCLASS.

CLASS zbp_addr_changed IMPLEMENTATION.

METHOD raise_address_changed.
lcl_event_handler=>on_Address_Changed( it_events ).
ENDMETHOD.

ENDCLASS.

 

After implementing the global class lets define the local class.

Add the local class “lcl_event_handler” with the previously referenced public class method “on_Address_Changed”. The implementation of that method should raise the event and look as follows:

 

CLASS lcl_event_handler DEFINITION FRIENDS zbp_addr_changed.
PUBLIC SECTION.
CLASS-METHODS on_Address_Changed IMPORTING it_events TYPE zbp_addr_changed=>tt_events.
ENDCLASS.

CLASS lcl_event_handler IMPLEMENTATION.
METHOD on_Address_Changed.

RAISE ENTITY EVENT Z_ADDR_CHANGED~AddressChanged FROM it_events.

ENDMETHOD.
ENDCLASS.

 

The complete local class should look something like this:

 

CLASS lhc_Z_ADDR_CHANGED DEFINITION INHERITING FROM cl_abap_behavior_handler.
PRIVATE SECTION.

METHODS get_instance_authorizations FOR INSTANCE AUTHORIZATION
IMPORTING keys REQUEST requested_authorizations FOR z_addr_changed RESULT result.

ENDCLASS.

CLASS lhc_Z_ADDR_CHANGED IMPLEMENTATION.

METHOD get_instance_authorizations.
ENDMETHOD.

ENDCLASS.

CLASS lsc_Z_ADDR_CHANGED DEFINITION INHERITING FROM cl_abap_behavior_saver.
PROTECTED SECTION.

METHODS save_modified REDEFINITION.

METHODS cleanup_finalize REDEFINITION.

ENDCLASS.

CLASS lsc_Z_ADDR_CHANGED IMPLEMENTATION.

METHOD save_modified.
ENDMETHOD.

METHOD cleanup_finalize.
ENDMETHOD.

ENDCLASS.

CLASS lcl_event_handler DEFINITION FRIENDS zbp_addr_changed.
PUBLIC SECTION.
CLASS-METHODS on_Address_Changed IMPORTING it_events TYPE zbp_addr_changed=>tt_events.
ENDCLASS.

CLASS lcl_event_handler IMPLEMENTATION.
METHOD on_Address_Changed.

RAISE ENTITY EVENT Z_ADDR_CHANGED~AddressChanged FROM it_events.

ENDMETHOD.
ENDCLASS.

 

Save and activate the class.

This “on_Address_Changed” method can now be called every time the “AddressChanged” event should be raised. This can for example be done from the local event handler defined in the previous blog.

 

Create an event binding

To publish the event to different channels like advanced event mesh an event binding is required. It references a namespace, SAP object type and operation which together build the event bindings type. The namespace, SAP object type and operation also build the event topic which is used for the outbound binding.

To create the event binding right click on your package, select “New” > “Other ABAP Repository Object” and search for “Event Binding”. After creating the event binding enter the following data:

Type Namespace: zevent

SAP Object Type: ZBusinessPartner

Operation: Changed

While namespace, SAP object type and operation can be chosen freely, it is recommended to setup and follow a clear policy and naming convention.

Next add the “AddressChanged” event to the event binding. Press the add button and enter the name of the RAP business object where the event is defined as entity name. Enter “AddressChanged” as entity event name. Depending on your requirements you can also define a specific version. Save the event by pressing “Add”.

The complete event binding should look as follows:

Activate the event binding. This should automatically fill the type of the event binding.

 

Send events to the AEM

In order to send events from the S/4HANA system to the AEM an outbound channel is required. The setup of this channel is described in the first blog of this series.

To publish the “AddressChanged” event to the advanced event mesh a topic binding on the outbound channel is required identical to the topic binding of a standard business event. To create this, go to transaction “/IWXBE/OUTBOUND_CFG” and select the channel to your AEM.

Next select “Create new topic binding” and enter the topic of the event. The topic consists of the namespace, object type and operation of the event binding divided by a slash. Use a wildcard for the version.

The resulting topic should look as follows:

As a result every “AddressChanged” event is send to the advanced event mesh. There a new subscription to a topic can be created in a queue to access the events. The setup is identical for custom events as it is for standard events and is already described in this blog.

 

​ This series of blogs intends to show in a step-by-step way the different possibilities to use RAP Business Events with Advanced Event Mesh. OverviewIn this second blog, we’re going to look at creating custom business events from scratch and publishing them to the Advanced Event Mesh. To be precise we’ll be creating a “Business Partner Address Changed” event that can be used to indicate that the address of a business partner has been changed. For that we’ll be creating a minimal RAP business object to contain the event, create a payload structure to be used by the event and finally create an event binding to publish the event. Create a minimal RAP business objectTo create a minimal RAP object, start of by creating a package to contain all repository artefacts. As we are able to use the “ABAP for Cloud Development” language version for that part, choose software component “ZLOCAL” when creating the package. To create the custom business object right click the created package and select “New” > “Other ABAP Repository Object”.In the search field enter “Data Definition”, select the entry and hit “Next”.Next enter the name and the description of the data definition and complete the creation of the data definition.As the “Address Changed” event should be referencing the business partner adjust the data definition to be a selection on “I_BusinessPartner” and reference all keys of this object. The result should look something like this: @AbapCatalog.viewEnhancementCategory: [#NONE]
@AccessControl.authorizationCheck: #NOT_REQUIRED
@EndUserText.label: ‘Business Partner View’
@Metadata.ignorePropagatedAnnotations: true
@ObjectModel.usageType:{
serviceQuality: #X,
sizeCategory: #S,
dataClass: #MIXED
}

define root view entity Z_ADDR_CHANGED as select from I_BusinessPartner
{
key BusinessPartner
} Activate the data definition.The just created data definition represents the root view of the new RAP business object. In the next step let’s create the associated behavior definition. For that right click the newly created data definition and select “New Behavior Definition”.Fill out the creation wizard and finally hit “Finish”.Adjust the behavior definition according to the following template: managed with unmanaged save implementation in class zbp_addr_changed unique;
strict;

define behavior for Z_ADDR_CHANGED
lock master
authorization master ( instance )
{

} Activate the behavior definition.Define a new notification eventA new event can simply be defined in a behavior definition using the keyword “event” followed by the events name. To add the address changed event simply add “event AddressChanged” to the behavior definition. managed with unmanaged save implementation in class zbp_addr_changed unique;
strict;

define behavior for Z_ADDR_CHANGED
lock master
authorization master ( instance )
{
event AddressChanged;
} This event can then directly be raised through ABAP EML. Note that despite it not being a data event there still must be some data passed to the event. Specifically, the key of the business object where the event is defined at. This is required to associate the event with one specific object. In the case of the “AddressChanged” event the “BusinessPartner” has to be given. DATA it_address_changed TYPE TABLE FOR EVENT Z_ADDR_CHANGED~AddressChanged.
it_address_changed = VALUE #( ( BusinessPartner = ‘0001’ ) ).
RAISE ENTITY EVENT Z_ADDR_CHANGED~AddressChanged FROM it_address_changed.  Define a new data eventTo change a notification event within RAP to a data event, only an additional abstract entity is required to define the payload structure. For that right click your package and select “New” > “Other ABAP Repository Object” and again search for “Data Definition”. As we are creating an abstract entity you can either already choose the abstract entity template from the creation wizard or alternatively adjust the object afterwards. Within the entity, list all fields and their datatypes which should be included in the event payload. The resulting abstract entity should look as follows: @EndUserText.label: ‘Address’
define abstract entity Z_ADDR_CHANGED_PAYLOAD
{
AddressNumber : abap.char(4);
FullAddress : abap.char(100);
} Activate the entity.This entity can then be passed to the event definition. For that simply add the key word “parameter” followed by the name of the abstract entity to the already defined notification event “AddressChanged” within the behavior definition. managed with unmanaged save implementation in class zbp_addr_changed unique;
strict;

define behavior for Z_ADDR_CHANGED
lock master
authorization master ( instance )
{
event AddressChanged parameter Z_ADDR_CHANGED_PAYLOAD;
} Activate the behavior definition.Trigger an eventRAP events can be triggered using ABAP EML with the “RAISE ENTITY EVENT” statement. In addition, data can be passed to the event by adding the keyword “FROM”. RAISE ENTITY EVENT Z_ADDR_CHANGED~AddressChanged FROM it_events. However, since this statement can only be executed within the context of the RAP business object, it is recommended to use a wrapper method which in turn can be called from any environment.Start by creating the implementation class of the previously created behavior definition. Simply place your cursor on the class reference and press “Ctrl + 1”. Finally select “Create behavior implementation class <class-name>”Click through the wizard and finish the creation process.In the global class add a new class method which can be called to trigger the address changed event. This requires firstly to create a table type of the “AddressChanged” event to use as an importing parameter to the method definition and secondly the class method itself which imports a table of the defined type. CLASS zbp_addr_changed DEFINITION PUBLIC ABSTRACT FINAL FOR BEHAVIOR OF z_addr_changed.

TYPES tt_events TYPE TABLE FOR EVENT Z_ADDR_CHANGED~AddressChanged.

PUBLIC SECTION.
CLASS-METHODS raise_address_changed
IMPORTING it_events TYPE tt_events.

ENDCLASS. Finally implement the method by calling a yet to be implemented local method “on_Address_Changed” and pass the imported table along. CLASS zbp_addr_changed IMPLEMENTATION.

METHOD raise_address_changed.
lcl_event_handler=>on_Address_Changed( it_events ).
ENDMETHOD.

ENDCLASS. The complete global class should look as follows: CLASS zbp_addr_changed DEFINITION PUBLIC ABSTRACT FINAL FOR BEHAVIOR OF z_addr_changed.

TYPES tt_events TYPE TABLE FOR EVENT Z_ADDR_CHANGED~AddressChanged.

PUBLIC SECTION.
CLASS-METHODS raise_address_changed
IMPORTING it_events TYPE tt_events.

ENDCLASS.

CLASS zbp_addr_changed IMPLEMENTATION.

METHOD raise_address_changed.
lcl_event_handler=>on_Address_Changed( it_events ).
ENDMETHOD.

ENDCLASS. After implementing the global class lets define the local class.Add the local class “lcl_event_handler” with the previously referenced public class method “on_Address_Changed”. The implementation of that method should raise the event and look as follows: CLASS lcl_event_handler DEFINITION FRIENDS zbp_addr_changed.
PUBLIC SECTION.
CLASS-METHODS on_Address_Changed IMPORTING it_events TYPE zbp_addr_changed=>tt_events.
ENDCLASS.

CLASS lcl_event_handler IMPLEMENTATION.
METHOD on_Address_Changed.

RAISE ENTITY EVENT Z_ADDR_CHANGED~AddressChanged FROM it_events.

ENDMETHOD.
ENDCLASS. The complete local class should look something like this: CLASS lhc_Z_ADDR_CHANGED DEFINITION INHERITING FROM cl_abap_behavior_handler.
PRIVATE SECTION.

METHODS get_instance_authorizations FOR INSTANCE AUTHORIZATION
IMPORTING keys REQUEST requested_authorizations FOR z_addr_changed RESULT result.

ENDCLASS.

CLASS lhc_Z_ADDR_CHANGED IMPLEMENTATION.

METHOD get_instance_authorizations.
ENDMETHOD.

ENDCLASS.

CLASS lsc_Z_ADDR_CHANGED DEFINITION INHERITING FROM cl_abap_behavior_saver.
PROTECTED SECTION.

METHODS save_modified REDEFINITION.

METHODS cleanup_finalize REDEFINITION.

ENDCLASS.

CLASS lsc_Z_ADDR_CHANGED IMPLEMENTATION.

METHOD save_modified.
ENDMETHOD.

METHOD cleanup_finalize.
ENDMETHOD.

ENDCLASS.

CLASS lcl_event_handler DEFINITION FRIENDS zbp_addr_changed.
PUBLIC SECTION.
CLASS-METHODS on_Address_Changed IMPORTING it_events TYPE zbp_addr_changed=>tt_events.
ENDCLASS.

CLASS lcl_event_handler IMPLEMENTATION.
METHOD on_Address_Changed.

RAISE ENTITY EVENT Z_ADDR_CHANGED~AddressChanged FROM it_events.

ENDMETHOD.
ENDCLASS. Save and activate the class.This “on_Address_Changed” method can now be called every time the “AddressChanged” event should be raised. This can for example be done from the local event handler defined in the previous blog. Create an event bindingTo publish the event to different channels like advanced event mesh an event binding is required. It references a namespace, SAP object type and operation which together build the event bindings type. The namespace, SAP object type and operation also build the event topic which is used for the outbound binding.To create the event binding right click on your package, select “New” > “Other ABAP Repository Object” and search for “Event Binding”. After creating the event binding enter the following data:Type Namespace: zeventSAP Object Type: ZBusinessPartnerOperation: ChangedWhile namespace, SAP object type and operation can be chosen freely, it is recommended to setup and follow a clear policy and naming convention.Next add the “AddressChanged” event to the event binding. Press the add button and enter the name of the RAP business object where the event is defined as entity name. Enter “AddressChanged” as entity event name. Depending on your requirements you can also define a specific version. Save the event by pressing “Add”.The complete event binding should look as follows:Activate the event binding. This should automatically fill the type of the event binding. Send events to the AEMIn order to send events from the S/4HANA system to the AEM an outbound channel is required. The setup of this channel is described in the first blog of this series.To publish the “AddressChanged” event to the advanced event mesh a topic binding on the outbound channel is required identical to the topic binding of a standard business event. To create this, go to transaction “/IWXBE/OUTBOUND_CFG” and select the channel to your AEM.Next select “Create new topic binding” and enter the topic of the event. The topic consists of the namespace, object type and operation of the event binding divided by a slash. Use a wildcard for the version.The resulting topic should look as follows:As a result every “AddressChanged” event is send to the advanced event mesh. There a new subscription to a topic can be created in a queue to access the events. The setup is identical for custom events as it is for standard events and is already described in this blog.   Read More Technology Blogs by SAP articles 

#SAP

#SAPTechnologyblog