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.
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.
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.
Setup AIF
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.
As mentioned above, we do define the conditions and actions in SAP Alert Notification service, so we need to ensure that mass alerts are not suppressed. So, in the interface monitor, we change the Mail settings of our interfaces to Mail for Every Single Error.
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]
