This blog is the third and the last 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 S/4 HANA Cloud. In the first post, I gave you a rough introduction on the basics of event-based communication. In the second one, I explain how you can Create RAP Business Events in SAP BTP ABAP Environment. Here, I will explain the consumption of an existing event using the event consumption wizard embedded in ABAP Development Tools for Eclipse (ADT).
Introduction
An “Event” is a data record expressing an occurrence and its context. Usually, a change of a business objects can be indicated by raising a business event. Nowadays, business applications expose lots of events. For example, when sales order gets created in SAP S/4HANA system or a new employee gets hired in SAP SuccessFactors. An interested party having subscribed to this event can consume and process it.
In an event-driven integration scenario, you have two main parts which are the event providers and the event consumer system. Both are connected via a message broker in our case, SAP Event Mesh. Event Mesh is a fully managed cloud service which help us to distribute events in an efficient fast & simple consumable way without disturbing any other consumers.
Event provider could be for example SAP S/4HANA On-premise, SAP S/4HANA cloud or other SAP cloud applications like Ariba or success factor and so on, or you could have 3rd party applications which produce an event. From release 2208, customers can also produce an event within SAP BTP ABAP Environment using a natively integrated RAP solution. This means, customer can build event providers and consumers in any ABAP Platform based SAP product.
On the event consumer side and from release 2208, you can now generate an event consumption model from AsyncAPI using an event consumer wizard embedded in ADT. Let’s explore this wizard together.
Event Enablement and Consumption process in a Nutshell
Here you see the configuration of event enablement and consumption in SAP BTP ABAP environment in a nutshell. As said, in an event-driven integration scenario at runtime, we have two main parts which are event providers and event consumers connected via SAP Event Mesh.
In our use case we can choose the SAP S/4 HANA Cloud system as an event provider. Within the S/4HANA Cloud system we can use the standard application ‘Maintain Business Partner’ to demonstrate how a business event is triggered. There should be an active connection to the SAP Event Mesh from the S/4HANA Cloud system. This connection can be configured by creating a communication arrangement based on the scenario SAP_COM_0092. Once the communication arrangement has become active, the connection is established in the background.
After building the communication arrangement in the event producer system, we must allowlist the event types for this connection. So, we maintain the event channel binding by adding the outbound topic we are interested in, into our connection. Here, we bind the event type reflecting the creation of the business partner to our connection. Later on, all events of this type which are triggered in the event provider system will be transported via the AMQP protocol to the SAP Event Mesh. These two steps are required at the event provider side.
Before starting with the configuration of the event consumer part on the right-hand side, we need to generate an Event Consumption Model and create a communication scenario in ADT wizard.
Then we need a communication arrangement of type SAP_COM_0092 to build the connection to an Event Mesh instance to receive the event in the consumer side.
Then we should build a communication arrangement and system of type of the implemented custom scenario and connect it to the communication arrangement of type SAP_COM_0092 to bound our event consumption model to the eventing connection. With all this, the configuration of event consumption model is done successfully.
Now the business user should create a new business partner in the ‘Maintain Business Partner’ application. Then, the event will be sent to Event Mesh, and we are able to consume it in a way defined in the custom code implemented in the event handler method of our new Event Consumption Model. In the following, I’ll explain this all in more details.
Generate an Event Consumption Model from AsyncAPI
An Event Consumption Model is a set of ABAP artifacts which allows you to receive events from external applications and to consume them within your business application.
As said, we can have a wide range of event producers. So, we need to know how the emitted event exactly looks like. To this aim, we need a file which contains the metadata of this event like how the payload looks like, what kind of types are there and so on. This is all specified in the event specification file, in our case, AsyncAPI specification, which is supported by SAP and can be either downloaded from SAP API Business Hub or directly generated during the creation of the outbound binding in the event producer system.
Asynchronous APIs are application programming interfaces aimed at improving the state of Event-Driven Architecture. These APIs provide a call back to the requester when the requested resource is ready and then return data later in JSON format.
Our aim is to create an event in an event production system, for example a new business partner is created, and consume it in a BTP consumer application by implementing the custom logic in the event handler class generated by the Event Consumption Model.
Prerequisites
Before we start with generation of the Event Consumption Model, we need to do some configurations at the producer side like building a successful connection to the Event Mesh system through a communication arrangement with the proper scenario (SAP_COM_0092) and generating the event Metadata for the selected event topic.
One requirement is that we have an existing SAP Event Mesh service instance of the default plan. You can create an instance of SAP Event Mesh provided that you already subscribe to the event mesh service. An Event Mesh service instance provides a service key which contains the endpoints and the credentials required to authenticate this service instance.
A communication arrangement defines which system (communication system) and which user can call which APIs (communication scenarios). For more information about communication arrangements, see the “Communication Arrangements Quick Guide” in the documentation of the SAP cloud solution.
Events must be allowlisted to be exchanged through a connection between SAP S/4HANA Cloud (or other application) and the SAP Event Mesh. To allowlist certain event types for a specific connection we can use the ‘Enterprise Event Enablement – Configure Event Bindings’ Fiori App of the SAP S/4 HANA Cloud tenant. In this app we can select from the list of available event types and bind the required event types to our connection. Afterwards, the proper event metadata will be generated automatically. Save this as a JSON file for further usage.
As said, here we bind the event type reflecting the creation of the business partner (..BusinessPartner.Created.v1) to our connection established via a SAP_COM_0092 communication arrangement. Afterwards all events of this type triggered in the event provider system will be transported via the AMQP protocol to the SAP Event Mesh. The details of this process is nicely explained in the second & third steps of the tutorial .
You can also use the generated metadata of the event you raised through the creation of a RAP business event as I already explained in the second post of this blog series. Simply download the ‘Event Metadata’ after you add the event to the outbound channel.
In case of a third-party event provider, one needs to get the AsyncAPI file from the event provider.
How to generate an Event Consumption Model in SAP BTP ABAP environment system
In ADT and as a first step, you upload the event specification file into our event consumption wizard of the SAP BTP ABAP Environment. This will then automatically generate all the information you need in this Event Consumption Model, like the event handler class, authorization defaults values and inbound service.
In your ABAP project, open the context menu and choose New > Other ABAP Repository Object > Business Services > Event Consumption Model to launch the creation wizard.
Fill the fields and upload the .json file you saved before. Go to the next page, select all the Event Types that you would like to consume in your business application after the creation of the Event Consumption Model. Then Define Consumer Artifacts and in the next step, copy the Inbound Service name from the provided list for further usage. In the created event consumption model, you can see the selected Event Types that you are assigned to.
Implementation of Consumer Extension Class
The developer can then implement the event handler class which contains custom business logic like how the system should respond to this incoming event. In the generated class, you can find a respective handler event method for the selected event types of the Event Consumption Model. In each method, the corresponding event type and the typed business data for this event can be found. The latter is commented out so that you can implement your own logic. The authorisation default values are maintained in the authorization default proposal for the Event Consumption Model. In the BTP ABAP Environment, If you perform authorization checks in the event handling method, you have to add the authorization objects manually to the Authorization Default Values.
Creation of the Communication Scenario for Event Consumption Model in ADT
As a next step, one should define the communication scenario for the generated Event Consumption Model in which the inbound service will be created with the event consumption model is assigned to.
In a communication scenario, you can generally define a set of inbound and outbound services for a business process. Inbound services are Web services that you have created based on an SAP or custom business object, or Web services provided by SAP. Outbound services are external Web services that you have integrated into your solution. Based on a communication scenario, a customer can create a communication arrangement in SAP’s cloud solution to exchange business documents electronically and provide an inbound communication to the SAP S/4HANA tenant.
Right-click on your package and choose New > Other ABAP Repository Object > Cloud Communication Management > Communication Scenario, then go to the next step and fill the fields.
The creation steps are shown in the tutorial. Click on the Inbound tab of the Communication Scenario and add the generated inbound service of the Event Consumption Model which you copied before under Inbound Service ID and click on Finish. To test the created communication scenario with the generated Event Consumption Model, you need to publish it.
To consume the event, you need to configure this event consumption model in the productive system. For this, you create a communication arrangement. To create this communication arrangements, you need the service key of an Event Mesh instance.
Then you need to configure a communication arrangement based on your consumer specific communication scenario. In the next step you assign this communication arrangement to the communication arrangement of type SAP_COM_0092 to allowlist your new consumer to receive events. The connection is available as soon as the SAP_COM_0092 Communication arrangement has been activated.
With this, we have a connection from the consumer system to the Event Mesh. Then the configuration of this event consumption model is all set up and done.
Summary
From release 2208, you can generate the event consumption model from AsyncAPI using an event consumer wizard embedded in ADT. Then you need to implement your specific event handler methods inside the generated consumer class to consume this event, based on your custom logic. You must also create a consumption communication scenario for this consumption model. At the end, you need to transport the generated Event Consumption Model and the communication scenario to your productive tenant. Later, this communication scenario is used to create a communication arrangement with the generated event consumer.
If you are familiar with event consumption via webhooks or REST APIs offered by the Event Mesh, you will see how this wizard simplifies consuming an event for you. Try it for yourself and follow the steps in Event Consumption Model within a Business Application tutorial.
