How to send SAP Application Interface Framework alerts to SAP Alert Notification Service
In this blog, I would like to show you how to integrate SAP Application Interface Framework (AIF) with SAP Alert Notification service in order to notify you about message processing errors within SAP S/4 HANA.
SAP Alert Notification service is a service of the SAP Business Technology Platform (SAP BTP) that allows you to expose real-time information in the channel of your choice. Here, different channel types are natively supported such as email, Microsoft Teams, Slack, ServiceNow, SAP Workflow, etc. For more details, check out the standard documentation of SAP Alert Notification.
I have setup an AIF interface of an IDoc message in an SAP S/4HANA 2020 system. Note, that SAP Application Interface Framework is an integral part of SAP S/4HANA for interface implementation as well as monitoring and error handling. In our case, whenever an error happens during message processing of this particular interface, we would like to trigger an alert and post the same to a Microsoft Teams channel.
Here, the approach is actually that all AIF alerts should be posted to SAP Alert Notification service, so you do not filter out in AIF but rather in SAP Alert Notification service by defining condition rules and actions to determine which alert is sent to which channel.
For more use cases where SAP Alert Notification service interacts with different services of SAP BTP and other applications such as SAP Integration Suite, SAP Solution Manager, SAP Focused Run or hyperscalers such as AWS, GCP, etc., see this blog series. There, you also find an example where Microsoft Teams is used as channel.
The SAP Alert Notification service integration with SAP Application Interface Framework is actually supported for both SAP S/4HANA and SAP S/4HANA Cloud. The configuration steps for both options are described here. They differ only in the setup within the S/4 systems. As said, I have setup the overall scenario in an on-prem system, hence in a nutshell the following configuration steps need to be carried out:
- Initial setup of the SAP Alert Notification service in the BTP cockpit
- Configure entitlements & service plan
- Create service instance and service key
- Setup connection between SAP S/4HANA and SAP Alert Notification
- Create an SM59 destination
- Create an OAuth configuration
- Setup AIF
- Maintain table /AIF/ANS_DEST
- Enable AIF interface for monitoring the alerting itself
- Setup Webhook in Microsoft Teams
- Setup action, conditions, and subscription in SAP Alert Notification service
So, let’s get started.
Initial setup of the SAP Alert Notification service in the BTP cockpit
I assume that the initial setup of the SAP Alert Notification service has been already done such as configuring entitlements, adding a service plan, creating spaces and service instances, etc. Administration and operations in the Cloud Foundry environment is described here. An overview of the initial setup of SAP Alert Notification is described here.
Once a service instance has been created, we need to create a service key in the BTP cockpit in order to consume the SAP Alert Notification service. URL, OAuth URL, client id and client secret are actually needed below.
Setup connection between SAP S/4HANA and SAP Alert Notification
We logon to the SAP S/4HANA system, and run transaction SM59 to create a destination of connection type G.
On the Technical Settings tab, as host we enter the url value from the service key. As path prefix we enter /cf/producer/v1/resource-events, see API description in the SAP API Business Hub.
On tab Logon & Security, we do not enter any user and activate SSL.
Furthermore, on tab Special Options, we select the HTTP version 1.1, set the Compression Status to Inactive, and the Type of Cookies Acceptance to Yes.
Next, we need to create an OAuth configuration. We run transaction code OA2C_CONFIG and create a new profile /AIF/CP_ANS_OAUTH_PROFILE with configuration name /AIF/CP_ANS_OAUTH_PROFILE_CONFIG.
As OAuth 2.0 Client ID and Client Secret we enter the client_id and client_secret from the service key above.
We enter the oauth_url from the service key into the Token Endpoint.
We do the same with the Authorization Endpoint parameter except that we replace the url path after oauth/ with the term authorize.
Below Access Settings, we select Basic client authentication, Header field as resource access authentication, and Client Credentials as selected grant type.
We run transaction code SE16, and maintain table /AIF/ANS_DEST. We add a new entry into the table with the field DEST the name of our SM59 destination and the field OAUTH_CONFIG the name of the OAuth configuration created before.
In order to be able to monitor the alerts sent to the SAP Alert Notification service, we need to extract the corresponding AIF interface shipped by SAP. We run transaction code /AIF/CONTENT_EXTRACT, and execute the program for the deployment scenario SAP_COM_0578.
To be able to get the interface displayed in the message monitor, we assign the recipient RECIPIENT_ALERTING_ANS of namespace /AIFAL to our user. You can do this either in transaction code /AIF/RECIPIENTS or /AIF/MYRECIPIENTS.
As you can see in the interface monitoring below (transaction /AIF/IFMON), the Interface monitoring for Alert Notification Service is added to the list of interfaces.
Setup MS Teams
We open our MS Teams, select our channel, and add a new connector of type Incoming Webhook to be able to send data from the SAP Alert Notification service to the Office 365 group in real time. We enter a name and click Create, this will automatically generate a WebHook URL. We copy the provided WebHook URL into our clipboard. This is needed below when creating an action.
Setup actions, conditions, and subscriptions in SAP Alert Notification Service
With the settings so far configured, an alert is created for each error that happens during message processing. In SAP Alert Notification service we now have to define conditions to filter out the alerts. Furthermore, in an action we define to which channel the alerts are sent. Finally, a subscription combines both conditions and actions.
Let’s start with creating the action. As mentioned above, we like to post the event to a Microsoft Teams channel. So, we navigate to the Actions entry in the navigation pane of the SAP BTP Cockpit, and create a new action of type Microsoft Teams.
On the next screen, we enter the URL address of the Webhook created beforehand.
Next, we define the conditions. The conditions can be based on the event properties. Each event has a set of common properties such as eventType, severity, category, etc. Besides this, application specific properties are defined as tags. For AIF, those are for instance ifname, ifversion, ns, etc. For a complete list of event properties, see SAP Alert Notification Service Events. In the example of an AIF event below, you can see further AIF specific properties and their values to be able to define your own conditions.
We switch to the Conditions area within the SAP BTP Cockpit, and create a new condition. As you can see, we have defined a condition to filter on a particular interface with name IDOC_02. This is actually the AIF interface name that we have customized in AIF. So the condition is defined as follows: tags.ifname is Equal to IDOC_02.
Furthermore, we define another condition that qualifies an AIF alert using its event type as follows: eventType is Equal to MessageMonitoringAlertingEvent. So, we end up with two conditions.
Finally, in a subscription we define which conditions and actions are used. So, we switch to the Subscriptions area within the SAP BTP Cockpit, and create a new subscription.
As you can see, we have chosen both conditions and the action created beforehand.
Run and monitor the message exchange
Once we have done all required settings, let’s test the interface. I have posted an IDoc message to the S/4HANA system enforcing an error. In the Message Monitoring Overview in the Fiori launchpad, we can see the number of messages and status for each interface that we are assigned to. Optionally, we can also use the interface monitor via the SAP GUI. Let’s click on the Create flight customer tile. This is actually the description of our AIF interface with technical name IDOC_02.
In the Message Monitor on the next screen, you can see a failed message due to a wrong customer type.
Switching back to the Message Monitoring Overview, you also find a tile for the monitoring of the alerting itself. We click on the same.
In the Message Monitor, we can see that an alert has been created and sent to the SAP Alert Notification service.
If I open my Microsoft Teams channel, I can see an event of event type MessageMonitoringAlertingEvent.
Finally, here’s an example of an AIF event so that you can see all event properties in order to be able to define a proper condition:
[ERROR] [ALERT] Alert occurred within Message Monitoring in system host_S4H_00 client 100 Landscape Details region cf-eu10 region type sap-cp Resource Details global account CAXXXXXXXXXXXXXXXXXXXX subaccount xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx resource group xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx resource type ABAP resource name host_S4H_00 resource instance host Resource Tags client 100 resourceLandscape cf-eu10 Event Details event type MessageMonitoringAlertingEvent event subject Alert occurred within Message Monitoring in system host_S4H_00 client 100 event timestamp 1632492657 [ 2021-09-24T14:10:57Z ] category ALERT severity ERROR priority 200 Event Tags ans:correlationId 0E8C1ED33D451EDC87A8277E3427BEA9 ans:recommendedActionLink https://host.dummy.nodomain:44301/sap/bc/ui2/flp?sap-client=100&sap-language=EN#AIFMessage-manage?ns=DEMO&ifname=IDOC_02&ifvers=1&action=search_message&status=E ans:status CREATE_OR_UPDATE ifDisplayName Create flight customer ifname IDOC_02 ifversion 1 message type E msgGuid 00000000000440070000000000000000 ns DEMO recipients [ALL][DEMO_ALL] Event Body [No instance of object type FlightCustomer has been created. External reference: Janet TaylorMainz][Customer type can be only B or P][Errors occurred during processing in AIF; see transaction /AIF/ERR][No instance of object type FlightCustomer has been created. External reference: Janet TaylorMainz][Customer type can be only B or P]
Hope, this blog helps you to setup your own monitoring scenario with AIF and the alerting capabilities of the SAP Alert Notification service.
Also check out this blog to learn about another interoperability topic between AIF and SAP BTP, actually about how to forward notifications from SAP Cloud Integration to AIF.
Thanks for such a detailed and informative blog.
Can we use this service to alert in case when certain services are down on BTP or even the BTP cockpit is facing a downtime(planned or unplanned)?
I don't know for sure, actually I'm not an Alert Notification expert, my background is rather AIF, I would say that the Alert Notification service is quite open, you find a link to a blog series with more use cases in my blog above.
Anyway, I would propose that you post your question in the OpsDev community at DevOps | SAP Community
Very informative post.
But I do have a challenge finding a guide for the service key creation. (Think I end on a "blind" road when coming to https://help.sap.com/viewer/09cc82baadc542a688176dce601398de/Cloud/en-US/6fcac08409db4b0f9ad55a6acd4d31c5.html )
you do not need to specify any parameters, just choose a name for the service key, that's it
My problem was another. I was not Space admin, thus the creation wizard did not work;-)
But after I got the role it went smoothly.
BTW - is it intended that the "Go to application" functionality is not active from the instance?
Or am I missing more roles?;-)
For the Alert Notification, there is no Go to Application button, you actually need to select the Manage Instance button
Nice blog..Thanks for sharing
Could you please explain the same but for S/4 HANA Cloud?
configuration for S/4HANA Cloud is described here, it requires even less steps: https://help.sap.com/docs/help/08396ebe30e245e69ea8b1f00be0f9d0/f23b89a2839740d0a994e4b0ea0d6ac9.html
Configuration on the Alert Notification Service is the same like described in the blog
Thanks for the response.
I followed that guide, but I'm still unable to set up a proper integration. Do we need to add any special URL in the Comm System? do we need to set up any specific port in the comm arrangement?
Thanks in advance,
Thanks for post Alexander. Is there a way we can filter these notifications by recipients defined in AIF ?
yes, you need to create a condition for tags.recipients
see all the possible tags in the sample alert that I have provided in the blog
Thank you Alex.