SAP Enterprise Messaging for S/4HANA On-premises

In this tutorial you will learn how you establish a communication between SAP Enterprise Messaging and SAP S/4HANA On-premises. With this you can consume the SAP S/4HANA On-premises business events in Enterprise Messaging, to trigger follow up activities via e.g. custom applications, SAP CPI, etc. Please note that a SAP S/4HANA System >= v.1809 is needed.

In order to set up Enterprise Messaging with SAP S/4HANA Cloud or SAP Marketing Cloud, please refer to the following blog posts:

• SAP S/4HANA Cloud
• SAP Marketing Cloud

To gain a fundamental understanding of SAP Enterprise Messaging Service on Cloud Foundry, please refer to the following blog posts:

• https://blogs.sap.com/2019/09/16/basics-about-sap-enterprise-messaging/
• https://blogs.sap.com/2018/10/07/getting-started-with-sap-enterprise-messaging/

Prerequisite

To go through the steps in this tutorial you need a:

• SAP Cloud Platform Cloud Foundry account (trial is sufficient)
• S/4HANA On-premises system

Architecture

After completing this tutorial, you should end up with the architecture below. Each step is described in detail. Please also refer to the official documentation: https://help.sap.com/viewer/810dfd34f2cc4f39aa8d946b5204fd9c/1809.000/en-US/c200f98fadb64ff1828ed5696c86fca2.html

All the configuration steps are available in transaction SPRO, under SAP Reference IMG  -> SAP Customizing Implementation Guide  -> SAP NetWeaver  -> Enterprise Event Enablement.

Step 1 – PFCG (User Roles and Authorizations)

In order to perform the configuration steps your user needs to have the corresponding authorization. In general, there are three role templates available. By going to transaction PFCG (Role Maintenance) you can use the role template to create roles, which you can then assign to your user(s). The process of creating roles is well known to SAP Admins. For creating roles to setup Enterprise Event Enablement you can refer to the official guide: https://help.sap.com/viewer/810dfd34f2cc4f39aa8d946b5204fd9c/1809.000/en-US/cd8a2607096c4c8ab2aa154abe05fd98.html

The three role templates are:

• /IWXBE/RT_XBE_ADM: Template needed for main admin tasks (step 2-4), e.g. creating a RFC destination, channel and OAuth setup.
• /IWXBE/RT_XBE_BUSI: Template needed for maintaining event topics (step 5). Users with this role are called Enterprise Event Enablement business administrators and decide for which business events of the S/4HANA system, event notifications are sent to the Enterprise Messaging instance.
• /IWXBE/RT_XBE_MDT: Template needed to execute OData service BROWSER_SRV (step 6), which is needed to display “activated” Events in the Event Hub UI.

Note: The Event Hub UI can be used to check which Events can be consumed from the event source system. This is needed as SAP Cloud Platform users might not have access to the S/4HANA On-premises system.

Step 2 – RFC (Creating RFC Destination)

A destination pointing to the Enterprise Messaging (EM) Service instance is needed (see picture of architecture above), so that the S/4HANA On-premises system can send event notifications to it.

Note: To be precise, the S/4HANA On-premises system does not send an event to the EM Service instance. From a formal perspective, the event is the state change of the business object in the SAP system. The system (event source) then sends a message (called event notification) to inform the EM Service instance that an event happened (usually including metadata as the business object ID).

Prerequisite:

• Enterprise Event Enablement administrator role
• Subaccount in SAP Cloud Platform Cloud Foundry

Creating Enterprise Messaging Service instance
First you need to create an instance of the Enterprise Messaging Service. You can discover services via the Service Marketplace in Cloud Foundry. In case you cannot find the Enterprise Messaging Service, please make sure to assign the corresponding quota to your subaccount:

After corresponding quota is assigned, the service should show up in the marketplace (navigate to your space inside your subaccount):

Now go through the process of creating a service instance of Enterprise Messaging (official guide). For all services visible in the marketplace a wizard opens with the following steps:

• • Choose Service Plan
    A Service Plan in SAP Cloud Platform Cloud Foundry defines the capabilities of a service and usage costs. In case trial version is used, we only have ‘dev’ as a plan to choose from, which is for non-productive usage. With a productive account you can also choose ‘Default’ as Service Plan which drastically simplifies the configuration steps via the Extension Factory and provides an advanced UI. You can read more here: https://blogs.sap.com/2019/07/30/new-service-plan-and-ui-for-sap-cloud-platform-enterprise-messaging/
  • Specify Parameters (Optional)
    This one is not optional. Parameters are typically defined as a JSON object and allow you to configure your service instance. Values to be passed depend on the service and can be checked for each service in the official documentations published in the SAP Help Portal. For the Enterprise Message Service, you need to define the mandatory ‘emname’ property to uniquely identify the instance. Enterprise Messaging comes with an optional REST API which allows you to manage (e.g. create/read/etc. queues and topics) and send messages – all via HTTP. More information can be found here: https://help.sap.com/viewer/bf82e6b26456494cbdd197057c09979f/Cloud/en-US/d0483a9e38434f23a4579d6fcc72654b.html. A configuration object can look like the following:

    {"emname": "em-ps","options": {"management": true,"messagingrest": true}}

     

  • Assign Application (Optional)
    According to The Twelve-Factor App methodology, Enterprise Messaging is a so-called Backing Service. When you develop an application on Cloud Foundry which uses the Enterprise Messaging instance, your app treats the instance as an attached resource. Backing Services are loosely coupled to applications, which allows to e.g. replace it without any code change. This is due to the fact, that with Cloud Foundry you don’t need to hard-code credentials of backing services. Rather, and this is what this step is all about, you bind the instance to your application. By doing so, credentials (as well as further metadata) of the Enterprise Messaging instance, get represented by environment variables, which are accessible by your application. So again, instead of using hard-coded credentials, you use environment variables, which don’t change in case the attached resource is replaced. You can read more about Backing Services here: https://12factor.net/backing-services. We are not going to develop an application in this tutorial, so choose ‘(None)’.
  • Confirm
    Choose an instance name and click ‘Finish’. You should now have successfully created the instance:

Creating a Service Key of your Enterprise Messaging Service instance

We now know that in case we want to use the instance within an application, we need to define a binding (step ‘Assign Application (Optional)’ from above). As for the S/4HANA On-premises system we cannot define a service binding in that way. Instead we need to create a service key for our instance. A service key can typically be created for services under the Service Marketplace in case we want to consume them outside of SAP Cloud Platform Cloud Foundry.

In our case we need the service key for two things:

• Get the MQTT URL of your Enterprise Messaging Gateway (needed in this step for the destination)
• Setup an OAuth 2.0 Client in your S/4HANA system to store credentials for authenticating against the Enterprise Messaging instance (needed in step 3)

The RFC destination and the OAuth 2.0 Client setup are then combined in step 4 via a Channel.

By default, you cannot access URLs (resources outside the SAP system) from your S/4HANA system. Making the token MQTT and token endpoint URL accessible from the S/4HANA system requires you to configure trust by importing the corresponding certificates of the MQTT URL.

Creating a Service Key is described here: https://help.sap.com/viewer/601525c6e5604e4192451d5e7328fa3c/Cloud/en-US/7502e1780e5b46f7982f8cc2a37a0080.html

Configuring trust and creating the RFC destination are described in the official guide: https://help.sap.com/viewer/810dfd34f2cc4f39aa8d946b5204fd9c/1809.000/en-US/12559a8c26f34e0bbe8c6d82b7501424.html

Hint 1: In order to export the certificates of the token endpoint URL you can click the key symbol in Firefox (left from the URL input field).

Hint 2: Hostname in destinations need to be entered without ‘wss://’, like:

Step 3 – OAuth 2.0 Account setup (Manage OAuth 2.0 Account Client Setup)

The Enterprise Messaging Service instance is secured via OAuth 2.0. The credentials (client ID and secret) are stored in the Service Key created previously. In order for the S/4HANA system to call the instance, you need to setup a client who requests the access token.

The necessary steps are described in the official documentation: https://help.sap.com/viewer/810dfd34f2cc4f39aa8d946b5204fd9c/1809.000/en-US/9d4a3428c80c45b38c5ca47969ae47fb.html

After going through the steps, you should see a success message like:

Step 4 – Channel (Manage Channel and Parameters)

A channel represents a single connection to a service instance of SAP Enterprise Messaging in SAP Cloud Platform.

For the connection you need the destination created in a previous step which points to the Enterprise Messaging Gateway (protocol MQTT) and the OAuth Client setup to be able to authenticate against the gateway. The channel combines both.

The necessary steps are described in the official documentation: https://help.sap.com/viewer/810dfd34f2cc4f39aa8d946b5204fd9c/1809.000/en-US/dbaac652c4c941eea383a2e7f954443d.html

Hint: The Topic Space is the identifier for the events that originate from the same source. As a best practice you enter the name of the S/4HANA system (S4D below). Via that in your application development you can e.g. decide to consume only event notifications from a certain system, etc.

Step 5 – Event Topics (Maintain Event Topics)

So far, no events are pushed to the SAP Enterprise Messaging. You explicitly must define for which events, notification messages are sent by the S/4HANA system.

The necessary steps are described in the official documentation: https://help.sap.com/viewer/810dfd34f2cc4f39aa8d946b5204fd9c/1809.000/en-US/c35bda94bb1f4364b38ebb5050c65a4c.html

Hint 1: Make sure to have the entry below in the list displayed via transaction: /IWXBE/SERVICE. Here you define the service which listens to business object changes.

Hint 2: Under Maintain Event Topics (SPRO) you define the filter which regulates which events are passed to the Enterprise Messaging instance.

Hint 3: The official documentation states ‘Each event is assigned to one topic. Topics form a logical tree to organize messages, like a folder hierarchy in a file system. As consequence, topics appear technically as strings, consisting of multiple segments, separated by one defined delimiter, like file paths.’. This can be represented graphically e.g. like:

Step 6 – BROWSER_SRV (Activate Event Discovery Service)

As already mentioned, a SAP Cloud Platform developer might not have access to the S/4HANA On-premises system. The developer still needs to know which events are consumable (defined in the previous step). Therefore, you can activate the OData Service Browser_SRV, which can be consumed buy the SAP Cloud Platform developers via the Event Hub UI.

The necessary steps to activate the OData Service are described in the official documentation: https://help.sap.com/viewer/810dfd34f2cc4f39aa8d946b5204fd9c/1809.000/en-US/01e0abdc7eea4127928710059c107f6a.html

As a last step you need to configure a destination on SAP Cloud Platform Cloud Foundry for the Event Hub to consume the Discovery OData Service. As we are on an On-premises scenario, Cloud Connector is needed as well. Once again details can be found in the official documentation: https://help.sap.com/viewer/810dfd34f2cc4f39aa8d946b5204fd9c/1809.000/en-US/bb74452b4d114377ac3a3bf480f2bd70.html

Note: This step is not needed for application development. It’s indeed only for discovering what was entered in step 5 from the SAP Cloud Platform Cockpit.

Testing the configuration

Now it’s time to test if everything was setup successfully. In SAP Cloud Platform Cloud Foundry, navigate to your Enterprise Messaging instance and open the Dashboard:

Event notifications from an S/4HANA System can only be sent to a topic. We could now start developing an application an consume the events from our On-premises system. However, as we just want to test if our setup was correct, we will use the dashboard. Basically, we will forward all messages from relevant topics to a queue. Messages in a queue are buffered until consumed by an application. As we are not going to consume the messages in this tutorial, we will see in the dashboard the content of our queue.

1. Create a queue
   Go to Queues -> Create and enter any queue name.
2. Create a queue subscription
   We have now created a queue. Again, we could start developing an application to send messages to the queue programmatically or use the REST API (if enabled) to send messages over HTTP. However, we are going to create a Queue Subscription to forward all event notifications from our S/4HANA On-premises system to our newly created queue:Note: As a value for ‘Topic Name or Pattern’ we use our Topic Space defined in step 4 to forward all event coming from our S/4HANA On-premises system to our queue.

You can now go to your S/4HANA On-premises system and trigger a state change of a corresponding business object. With help of the dashboard you should see a message appearing in your queue:

Congratulations you have now successfully completed the configuration steps to send event notifications from a S/4HANA On-premises system to an SAP Cloud Platform Enterprise Messaging instance.

As next steps you could now e.g. use SAP CPI or develop an application to trigger follow up activities whenever an event notification is sent from your S/4HANA On-premises system.