Skip to Content
Technical Articles

SAP Cloud Application Programming Model and Enterprise Messaging [1] : Intro

With other words:

How to use
SAP Cloud Application Programming Model (CAP)
to send and receive messages/events via
SAP Cloud Platform Enterprise Messaging
(Part 1: Intro)

Quicklinks:
Intro
Prepare Enterprise Messaging
Entitlements
Create instance
Open Dashboard
Trial
Series of Blogs

Introduction

Typically, SAP Cloud Application Programming Model (CAP) is used for exposing OData services
Everybody knows that
However, the design is such that it suits perfectly the paradigm of eventing / messaging

What is messaging?

Apologies, but we have to keep this section very short
Let’s just compare

When calling a REST service, e.g. a CAP based OData service, then:
You call the service
You get a response with payload (data)
-> That’s synchronous

When using Enterprise Messaging:
You send a message to a broker
After sending the message, you can safely rely on the broker to deliver the message (fire-and-forget)
-> That’s asynchronous, one benefit of messaging

A broker is a server which manages messages, queues, subscriptions
Applications which are interested in receiving the message, can connect to the broker whenever they want and the messages will be delivered

Messages usually have very small payload

There are several patterns, about how a broker deals with messages:
For example, keep them in a queue
Interested consumers can subscribe to such queues.
Like that, one published message can be consumed by multiple consumers (publish-subscribe pattern, or pub-sub)

To separate different concerns, the broker can allow to define so-called topics
Like that, the event-producer can send events to different topics and the consumer can subscribe to a  topic to get notified

Furthermore, events have names, such that a subscriber can specify that he wants to be receive only specific events
Otherwise, he might be flooded by myriads of messages

How does SAP support Messaging?

One very interesting aspect in the world of heterogenous systems:
One system, for example S/4 HANA, can send messages (events) whenever changes occur to specific data
A common example: a new Customer is entered in the system
In that case, the system sends an event, e.g.  CUSTOMER_CREATED
That event is sent to SAP Cloud Platform Enterprise Messaging (which has been previously configured)
The underlying broker receives the message and spreads it to all subscribed consumers
Consumers can be applications deployed in the cloud
Such an application receives the event and can react upon it, e.g. show popup, update data, etc

Like that, data can be kept in sync, which is very important.
No need to regularly poll for changes
No need to configure recurring jobs/schedules (e.g. with JobScheduler)
Much better: connect the application to Enterprise Messaging and receive messages whenever data changes.

Such a consumer application can be a CAP application

Yes.
Because CAP offers support for eventing and has built-in support for Enterprise Messaging.
Without eventing, the CAP application would need to manually call the S/4 system periodically to check for changes.
But readers of my blogs will be able to build CAP applications which can react upon events.
Note: The messaging-integration in CAP is currently in BETA-mode

CAP apps can be connected to multiple systems via Enterprise Messaging.
We can call that “event-driven architecture”

What are the advantages?

Decoupling of systems
No dependencies between systems
Decoupled systems can be updated more easily
Asynchronous communication, no need to wait for a response
Messages don’t get lost (broker guarantees the delivery)
Quality of service

Note:
Again, let me point out that I’m not writing an introduction to messaging, rather, I’m arbitrarily mentioning  a few of the important topics

How does that technically work?

In SAP Cloud Platform, we can create an instance of the Enterprise Messaging service
We can open the Messaging Dashboard
There, we can create queues and we can create subscriptions
When using CAP, such queues and subscriptions are generated by CAP

Note:
You might be interested in going through this tutorial

Prepare Enterprise Messaging

This little series of tutorials will be based on a productive account of SAP Cloud Platform.
Enterprise Messaging instance in Trial account is a bit simpler to configure, but also less powerful

Create Service instance

In your subaccount, go to your space and open the Service Marketplace
There you should see the Enterprise Messaging Tile

If you don’t see, it isn’t a bug nor a matter of your eyes. It’s just that you need to assign Entitlements to your subaccount. See Appendix

Create instance

To create a service instance, in Marketplace, click on the “Messaging” – tile

Click on “Documentation” and read it all….
(Sorry,  forgot to mention: this step is optional…)

Then press “instances” in the left pane
Next, press the button “New Instance”
In the wizard, choose service plan “default”
In the next page, enter the following json into the text box:

{
    "options": {
        "management": true,
        "messagingrest": true,
        "messaging": true
    },
    "rules": {
        "topicRules": {
            "publishFilter": [
                "${namespace}/*"
            ],
            "subscribeFilter": [
                "${namespace}/*"
            ]
        },
        "queueRules": {
            "publishFilter": [
                "${namespace}/*"
            ],
            "subscribeFilter": [
                "${namespace}/*"
            ]
        }
    },
    "version": "1.1.0",
    "emname": "cap_msg_client_custcare",
    "namespace": "company/customer/care"
}

Explanation

emname
The name of the messaging client.
You will see the client name afterwards, when we open the messaging dashboard
Don’t confuse it with the instance name of messaging service

namespace
This is very important setting, because it can cause severe trouble when creating CAP application
When creating a queue, the queue name has to match the namespace
When subscribing to a topic, the topic name has to match the namespace
Since CAP handles that automatically, you have to take care to follow the rules

topicRules
The parameters used above follow a “normal” recommended approach:
The rules allow to create topics only if they start with the namespace that is specified in the
“namespace” property.
That’s what I’ve written above.

In our example, we can only create a topic subscription like this:
company/customer/care/topicname
Or similar
company/customer/care/my/desired/topicname

If it is necessary to handle “foreign” topics, e.g. for events that are sent from S/4HANA, then we need to “open” the rules here

The settings are so fine-grained that it is possible to distinguish between topics of messages that are sent (publish) and messages that are received (subscribe)

Filter means that the messaging client refuses to handle messages that are sent to this broker, but don’t match the filter settings

queueRules
It is possible to define filter for queues as well,  but this is not so relevant for us
So we follow the “normal” approach of allowing only queue names that start with our namespace, that will do the job.

 

To continue with instance creation, press Next
Here we don’t have an application to choose, so press next once more
In this last page, we have to enter a name for the new instance.
Enter a name of your choice, e.g. msgcustcare

Note that this name has to be given later in the manifest of CAP application

As a result, we can see the new messaging instance in the list

What can we do with it now?

Human users can open the Messaging Dashboard

In productive landscape (trial users see below), the dashboard is accessed via subscription.
To access it, you have to create a subscription first:

Go to your subaccount, the click “Subscriptions” on the left menu pane
Search for the tile “Enterprise Messaging” and click on it
In the Details screen, you can press the “subscribe” button
Afterwards, press on “Go to Application”

If you’re not able to log in, you need to assign the required roles to your user.
See appendix

If you were able to log in, you should see a screen like this

And what can we do with it now?

To see what you can do, you can click on the client with the name that we specified in the JSON parameters above

Tab “Service Descriptor”
You can click here to view and remember the settings specified while instance creation

Tab “Rules”
You can click here to view and remember the rule settings specified while instance creation

Tab “Queues”
You can click here to create a queue, e.g. testqueue
And afterwards, you can create a subscription in this queue
Press the little icon on the right side:

Read the hint on the dialog.
You can only enter names that match the rules which we specified while instance creation
As such, the topic name which we specify has to start with our namespace
You can now create a subscription like e.g.
company/customer/care/testtopic

Some business use cases could be to specify the events sent by some backend or application
e.g.
company/customer/care/demo/customer/created
company/customer/care/demo/customer/changed
company/customer/care/demo/customer/deleted

To make life easier, in such cases you can use placeholder
e.g.
company/customer/care/demo/customer/*

Once you subscribe to a topic, you can receive messages which are sent to that topic.
If you don’t know what to enter here: a topic can be specific e.g. to S4HANA, so you would need to obtain the information from an Admin of S4HANA who defined it there

Now we can send messages to this queue

How to send messages?

It is possible to send messages with a REST client, because the Enterprise Messaging service offers a REST API
See docu: Use REST APIs to send and receive messages
Note that the APIs requires OAuth2 …. And complicated URLs and payload….
Brrr that’s tedious

Alternatively, there’s the “Test”-tab
Ouw, that’s boring

You know what?
What?
Let’s write a CAP application to send messages
Yeah!!! THAT sounds interesting!
But be warned, writing CAP app is tedious, requires configuration, lot of complicated coding, etc..
Oh – come on, I don’t believe that…. I know that CAP makes life easy…
You’re right, I was just kidding…

Continue with next blog to create CAP application

Summary

In this blog, we’ve talked about basic messaging concepts
And we’ve gone through the required steps to create instance of Enterprise Messaging service
The description was related to the messaging in productive account (service plan “default”)

SAP Help Portal: Enterprise Messaging
SAP Help Portal: Use REST APIs to send and receive messages

Tutorials:
Enterprise Messaging
Holger Bruchelt’s great Blog about Azure

Series:
Next Blog: create CAP application to send messages to Enterprise Messaging
And: create CAP application to receive messages
Extra: local development with Enterprise Messaging
CAP managed messaging using keyword event in CDS model

 

Appendix 1: Entitlements

In case you need to configure Entitlements for Enterprise Messaging, proceed as follows.

Go to your Global Account
On the left menu pane, click Entitlements, then “Subaccount Assignments”
Choose subaccounts, then press Go
Then click “Configure Entitlements” button
You might need to remove entitlement from one account before adding it to a different account

To configure entitlements, click “Add Service Plans” to open the selection dialog
Here you can enter “messaging” in the filter field,
Then select the “Enterprise Messaging” service in the list
Then choose a service plan (In Trial account, only “dev” can be chosen, in productive account, only “default” can be chosen)
Finally press the Add button at the bottom of the dialog

Back in the “Entitlements” screen, don’t forget to press “Save” on the top right corner

Now you can go to your Space and you’ll find the tile “Enterprise Messaging” in your “Service Marketplace”

 

Appendix 2: Role Assignment

To prevent innocent users from causing damage to the setup of Enterprise Messaging and connected systems, the Enterprise Messaging enforces users to have certain roles

In your subaccount, go to Security > Role Collections
Create new Role Collection and add these roles to it:

ReadRole
ManageRole
TestRole

Info?

Afterwards, click on “Trust Configuration” in the left menu of subaccount
Click on your identity provider (e.g. SAP ID Service)
Enter your mail address, then click on “Show Assignments”
Here you can assign the newly created role collection to your user

Note that you can as well use the default role collections instead of creating an own one

Appendix 3: Test tab

Only in productive account with messaging instance with service plan “default”, the dashboard supports sending and receiving test messages

The test tool is quite self-explaining:

Choose “Publish” to send a message
Select the queue created in previous step
Enter a message, e.g. “hello”
Press “Publish”
As a result, you can see the counter of messages increases by one
If you go to the “Queues” tab, you can see the counter increased as well

Means that a message has been sent to the queue and there it is waiting to be delivered.

Next test is to go back to the “Test” tab, choose “Consume” and select the same queue
Press “Consume”
As a result, the payload of the message (“hello”) is displayed and the counter is decreased

Appendix 4: Trial account

See here for differences in the Trial account

Create Instance

Choose service plan “dev”
Use these JSON parameters:

{
    "emname": "yourmessagingclient",
    "options": {
        "management": true,
        "messagingrest": true,
        "messaging": true
    }
}

As you can see, it is not possible to protect the interaction with rule.
On the other side, it makes life easier, for poc creation in Trial landscape

Open Dashboard

To access the Messaging Dashboard, go to the service instance and click the little icon on the right side

The Enterprise Messaging Administration Dashboard opens in a new browser tab

First, create a queue using the “Queue” menu entry in the left menu bar
Afterwards proceed to the “Queue Subscriptions” menu entry to create a subscription for that queue
Then go back to the “Queues” screen to view the number of messages

Note:
Command-line-lovers can find the dashboard URL in the services details:

Appendix 5: Enable BETA mode

If CAP complains that you need to run your project in beta mode in order to use beta features:

Create a file with name .cdsrc.json in the root of your project (next to package.json)

Copy the following content into it:

{
  "cdsc": {
    "betaMode": true
  }
}
5 Comments
You must be Logged on to comment or reply to a post.