Skip to Content
Technical Articles
Author's profile photo Paolo Sfilio

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:

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

 

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.

Assigned Tags

      20 Comments
      You must be Logged on to comment or reply to a post.
      Author's profile photo Ravi Joseph
      Ravi Joseph

      Hi Paolo,

       

      we are working on the similar scenario to test the event enablement features, however we are struggling in sending the event notification out of S/4 HANA. From the monitor web socket area we can see the event notification triggered, however the EM Queue is not receiving the message. Could you please advise any pointers. In addition, we are unable to do a test connection for the RFC, the RFC requires an user name and password, we tried with sever options, using s-user/pwd, secret, however none of them work. Would you please advise if you are able to successfully test the RFC as well?

      Thanks in advance

      Jo.

      Author's profile photo Paolo Sfilio
      Paolo Sfilio
      Blog Post Author

      Hi Ravi,

      Not sure if you can test the websocket URL via sm59. I am getting a HTTP code 401 when I test my RFC connection. That at least means that I can reach the endpoint but authentication does not work in sm59. I guess this is because I need to request an access token first. With the OAuth Client setup requesting an access token and combining both in an channel works perfectly well.

      Did you have imported the certificates for your Enterprise Messaging Gateway in STRUST and did an ICM restart afterwards? You can get the certificates via putting the URL (which you can get from the service key) into a webrowser and exporting them. Are proxy settings required in your network? What HTTP Code are you getting when testing the RFC connection? Can you at least reach the end point?

      Best

      Paolo

      Author's profile photo Vijay Sharma
      Vijay Sharma

      Thanks Paolo Sfilio for sharing it. Very nice blog!!

      I have a question, as per the details, we need to download the certificates from the tokenendpoint url that we will get from the service key.

      So i got the URL as mentioned below. When i try to open this URL in the browser, it asks for credentials. I tried by entering the SCP user id and password and also with the email (used for messaging service logon) and password, but it is not taking the credentials.

      Can you help me to verify if i am doing anything wrong?

      I am able to open the Enterprise messaging dashboard though.

      tokenendpoint URL:  https://p376567trial.authentication.eu10.hana.ondemand.com/oauth/token

       

      Regards

      Vijay

      Author's profile photo Paolo Sfilio
      Paolo Sfilio
      Blog Post Author

      Hi Vijay,

      In order to download the certificate you do not need to enter any credentials. Just click on "cancel" and then you should see the green key button left to the url. Click on it, go to certificate details and click on export.

      That's it for the step 🙂

      Best

      Paolo

       

      Author's profile photo Vijay Sharma
      Vijay Sharma

      Thanks Paolo for your response. I will try this out.

      Regards

      Vijay

      Author's profile photo Vijay Sharma
      Vijay Sharma

      Hi Paolo,

      I am facing some issues while trying this . I have posted the same as new query here

      https://answers.sap.com/questions/12928694/issue-while-setting-up-enteerprise-messaging-with.html

      Can you please help me with this?

      Thanks

      Vijay

      Author's profile photo Paolo Sfilio
      Paolo Sfilio
      Blog Post Author

      Thanks Tobias for providing more details on how to export the certificates:

      https://answers.sap.com/questions/12928694/issue-while-setting-up-enteerprise-messaging-with.html

      Author's profile photo Udita Saklani
      Udita Saklani

      Hello Paulo,

      I have performed exact steps as mentioned in the blog. I have bound  Business partner topic to the Channel. The channel connection check is also successful. However when I perform the business event change in my on-prem box, then the count in the queue of the enterprise service instance does not get increased.

      My on-prem is on 1809.

      Is there anything I am missing here?

      Author's profile photo Binson Varikkasseril Abraham
      Binson Varikkasseril Abraham

      Hi Udita,

       

      Please check whether any logs are available in the system using SPRO=> SAP Customizing Implementation Guide -> SAP NetWeaver -> Enterprise Event Enablement -> Administration -> Troubleshooting.

       

      After updating the business partner, also check whether web sockets are created to SCP using SPRO=> SAP Customizing Implementation Guide -> SAP NetWeaver -> Enterprise Event Enablement -> Monitoring -> Monitor Web Socket

       

      For more details, please check: https://help.sap.com/viewer/810dfd34f2cc4f39aa8d946b5204fd9c/1809.000/en-US/9c1b889fc3c640328962f560ec9b8ea0.html

      Author's profile photo Gregor Wolf
      Gregor Wolf

      Hi Paolo, Hi Binson Varikkasseril Abraham,

      I'm facing the same issue as Udita Saklani. I've posted how far I've got at Enterprise Event Enablement: is there a monitor for events? before I've discovered this great blog.

      Best regards
      Gregor

      Author's profile photo Udita Saklani
      Udita Saklani

      Hi Binson/Paulo,

      As suggested, I have checked the logs and the web socket.

      In the WebSocket, one entry is created for the same. However when I perform changes in the business partner, then what is the expected behavior in the Websocket? should the send/receive time be updated?

      In my case, the time is not getting updated if that is the expected behavior of the web socket afetr Business partner change.

       

      Regards,

      Udita

      Author's profile photo Satnam Singh
      Satnam Singh

      Hi Paolo,

       

      Very nicely documented..!!

      Question : Can we add more fields into the event message? Currently, we can see that only "Key" information is passed whenever business partner is changed..

       

      Regards,

      Satnam Singh

      Author's profile photo Paolo Erhardt Sfilio
      Paolo Erhardt Sfilio

      Hi Satnam,

      As a best practice you only put the ID of the object which had changed. As a publisher you usually don’t know every client which e.g. has subscribed to a queue/topic and therefore you don’t know if the receiver is allowed to read the actual data. That’s why you only send the ID ore more precisely inform the client about only which object(s) has changed (but not what). It’s then up to the client to request the actual data via an authenticated request so that authorization checks etc. can happen. There might be scenarios where the above is not true and under different circumstances it might make sense to put the actual data into the event notification itself, e.g. when no authorization checks have to happen, etc. But sending only the ID and letting the client request the actual data (in order to perform authorization checks) is definitely one common way of working with events in business processes.

      I might be possible to extend the event message. Unfortunately I do not work with EM that much anymore so in case this is possible I don’t know how. In case you found sth. out please feel free to post it here.

      Best

      Paolo

      Author's profile photo Huiying Luo
      Huiying Luo

      hi Paolo

       

      very good document to helping me setup this, but i find a isue when i active the channel .

      and when i debug it shows , can not direct connect with the site.

       

      Author's profile photo Alexander Sahler
      Alexander Sahler

      I had the same issue.

      According to https://launchpad.support.sap.com/#/notes/3039709 it is due to a missing global proxy setting. After implementing the Note it worked for me.

      Hope this helps,

      Alexander

      Author's profile photo Sampath Ramanujam
      Sampath Ramanujam

      Thanks it is a nice blog.

      I am connecting the S/4Hana onpremise (2020) with SAP Cloud Platform Enterprise message serivce instance, after i configure the RFC, OAuth then created channel in S4, tested with "Check Connection" throwing me following error

      HTTP failure, processing failed, invalid state, invalid timeout or others

      Message no. BL001

      I have verfiied the import certs, cleared cache (Exitsoft -> local) , i am now clue less what else we can check, to move forward ?

      Thanks

      Sampath Ramanujam

      Author's profile photo Brendon Bouwer
      Brendon Bouwer

      Good day,

      I am also getting "HTTP failure, processing failed, invalid state, invalid timeout or others Message no. BL001" when trying to activate the channel.

      Please can you let me know if you have a solution for this issue?

      Thank you

      Author's profile photo Alexander Sahler
      Alexander Sahler

      Hello Paolo.

      Thank you for the very good link compilation and comments! I followed it by the word.

      After getting it working I wondered if it is possible, to connect to a private MQTT Server not hosted in the cloud/ BTP. Unfortunately the channel registration forces me to use a OAuth profile. Is it somehow possible to get around this and use native MQTT protocol for a connection?

      Best regards, Alexander

      Author's profile photo Jordi Vila
      Jordi Vila

      Hello,

      Did you find how to connect it to a private MQTT?

      Thank you

      Author's profile photo Frank Li
      Frank Li

      Great blog!