How to set up enhanced SAP Events for Advanced Event Mesh with Application Interface Framework

[AlexPfeil]

Introduction

After the announcement of Karsten here and Christians Blog here I would like to offer a simple and detailed HowTo Guide to activate and enhance Event Integration via Application Interface Framework to Advanced Event Mesh.

SAP Note for Release Strategy: https://me.sap.com/notes/3480454

SAP Note for AIFAEM Metering: https://me.sap.com/notes/3474406

SAP Application Interface Framework does not only make it easy and brings a lot of Flexibility to enhance Events, but also included in the AEM Licence.

Some parts of the process are always the same, some are dependent on the scenario. In this blog I will show you the process on the Example Business Partner. We will enhance the Business Partner Event with Name and Address Data. Let´s dive in. 

Important Note: The Function Modules ZAIF_EVENT_INTEGRATION & ZAIF_ACTION_CALL_AEM (Code of them is documented in Christian´s Blog if you want to create those as Z-Function Modules) are provided in the AIFAEM AddOn in the /AIF/-Namespace. I am not aware of the exact name of them in the /AIF/-Namespace, but will update you here as soon as I know.

1) Event Linkage in SWE2

In Transaction SWE2 we can add Linkages for SAP Standard Object Events. On New Entries we just have to add an entry with Function Module "ZAIF_EVENT_INTEGRATION". The Event Types consist of technical Business Object Keys. In order to find the right Key Value, click on the F4 Help and use the Information System to Search for your Object

In our Case I will choose BUS1006 Business Partner

The Checkbox "Linkage Activated" should be not active yet, because Event would go into error in the Function Module, since we haven´t set up the AIF Interface yet.

2) AIF Target Structure Design

Before we get to define the Interface, we need to design the expected Output of our Event. Here you need to know, that AIF requires DDIC Types as Structures. The AIF AEM Addon requires a Structure with "CONTROLLER" and "DATA". 

@EndUserText.label : 'Event Message'
@AbapCatalog.enhancement.category : #NOT_EXTENSIBLE
define structure zaif_aem_bupa_event_message {

  controller : zaif_aem_controller;
  data       : zaif_aem_bupa;

}

2.1) Controller

The "Controller"-Structure requires these Fields, so the AIF Action later has all the information needed to call the AEM and pass the event to the right topic

@EndUserText.label : 'ZAIF_AEM_CONTROLLER'
@AbapCatalog.enhancement.category : #NOT_EXTENSIBLE
define structure zaif_aem_controller {

  rfc_dest        : rfcdest;
  topic           : char255;
  uri             : char255;
  name_mapping_id : zaif_aem_name_mapping_id;
}

Definition zaif_aem_name_mapping_id: Domain CHAR10

The RFC_DEST is the Destination maintained in SM59. With AIF we always use the REST Endpoint to the AEM. The assumption here is that the SM59 connection to AEM is already established. This might be done with Basic Auth or Client Certificate. One way is described here 

The Name Mapping ID refers to the Database Table zaif_aem_name_ma, which you have to create exactly with the same name, since it is hard-coded in the AddOn´s Action.

@EndUserText.label : 'Name Mapping'
@AbapCatalog.enhancement.category : #NOT_EXTENSIBLE
@AbapCatalog.tableCategory : #TRANSPARENT
@AbapCatalog.deliveryClass : #A
@AbapCatalog.dataMaintenance : #ALLOWED
define table zaif_aem_name_ma {

  key client          : mandt not null;
  key name_mapping_id : zaif_aem_name_mapping_id not null;
  key abap            : char30 not null;
  json                : badi_char255;

}

Here you can define for which Mapping ID which ABAP name get´s mapped to a json Tag Name. For example:

2.2) Data

This Element in the Target Structure basically is what the AIF Action will convert into a json and send as Payload to the AEM. You can use the Event Header like Christian did in his Blog (referenced at the beginning) or simply the Payload itself, like me with zaif_aem_bupa (This works because we specify the Topic to AEM in the Controller-Structure, which will be added to the URL in the Action Function Module):

@EndUserText.label : 'BusinessPartner'
@AbapCatalog.enhancement.category : #NOT_EXTENSIBLE
define structure zaif_aem_bupa {

  businesspartner : abusinesspartner;
  bpaddress       : zaif_aem_abpaddress_tt;

}

Every Customer is free to design whatever fits to their needs here. To reduce effort to design structures and make Move-Corresponding work after Data Selection, I decided to orientate on the CDS Views, where I get the Data from in my Structure Mapping Function Module (which you will see in the section after this). Generally in S/4HANA CDS views are part of the Virtual Data Model, which forms the basis for data access. For more information feel free to read the SAP Help here.

I chose to call the CDS View behind this API: https://api.sap.com/api/OP_API_BUSINESS_PARTNER_SRV/resource/Business_Partner

For every Entity here there is a CDS View in the System you can check in ABAP Developer Studio.

Many CDS Views are documented in the SAP Accelerator Hub. They can be used as well. Example: I_BusinessPartner: https://api.sap.com/cdsviews/PCE_I_BUSINESSPARTNER

Since CDS Views cannot be used in AIF, I use the DDIC Views generated by the CDS Views. For General Data i chose the CDS View A_BusinessPartner, which generates DDIC View ABUSINESSPARTNER

For the Address the Address below A_BusinessPartner --> ABUPARTADDRESS.

Since there could be multiple addresses, we need a Table Type here. So I created one for ABUPARTADDRESS in SE11:

Now that the Target Structure is designed, we can move on to create the AIF Interface

3) AIF Interface Design

The RAW (Source) Structure is always the same

@EndUserText.label : 'ZAIF_EVENT_RAW'
@AbapCatalog.enhancement.category : #NOT_EXTENSIBLE
define structure zaif_event_raw {

  objtype : swo_objtyp;
  objkey  : swo_typeid;
  event   : swo_event;
  rectype : swe_rectyp;

}

In /N/AIF/CUST -> Define Namespaces we defined our Namespace "AEM" and in /N/AIF/CUST -> Define Interface our Interface:

In /N/AIF/CUST -> Additional Interface Properties -> Specify Interface Engines we also need to change the Application and Persistence Engine to XML

Also we need to specify on what condition the AIF needs to call this interface (because the Source Structure is always the same for all Events). Therefore we need to open /N/AIF/CUST -> System Configuration -> Interface Determination -> Interface Determination For XML.

We could define Rules here on multiple Fields. For example a different Interface for different Events (Create, Change,..). But here we only do this based on the Object Type.

 

4) AIF Structure Mapping

In /N/AIF/CUST -> Define Structure Mapping we can define what and how exactly needs to be mapped to our Target Structure. We only have one Source Structure: ZAIF_EVENT_RAW. The Target Structure is the Root Structure of our Target Message.

4.1) Controller

Here we defined some fix values. This is always the same for all Business Partners

The Topic could contain more detailed information and organizational dimensions, which might be specific for the object (for instance sap.com/businesspartner/change/v1/Organization/<BusinessPartnerNumber>). Instead of a Fix Value you might want to use the AIF Field Mapping or ABAP Coding (for instance in the Structure Mapping Function Module in chapter 4.2) to dynamically set the Topic. For Topic Nomenclature Best Practices check out this Page: https://help.pubsub.em.services.cloud.sap/Messaging/Topic-Architecture-Best-Practices.htm 

In my example I don´t send the Event Header in the DATA-Segment (compared to Christian´s Blog referenced at the beginning). That is why I have to provide the Topic Name in the URL as /Topic/<Topic Name>.  

4.2) DATA

In AIF there are many ways to check & Map Data. We have Value Mappings, Conditions and the freedom to add ABAP Coding in many places. Christian showed us in his blog how to do it in Customizing, which would be the cleanest way. But if there are multiple Fields to be fetched from the same Database-Table (or CDS View), it is not the most performant way to do it. That is why I chose to implement the selection of the data in one Structure Mapping Function Module. 

With the F1-Help we always get a Template from AIF which we can copy and use in that specific Step

After copying the Template /AIF/FILE_TEMPL_MAP I changed the OUT_STRUC Data Type to our Target Data Type

In the Function Module I select the Data and move it to the Target Structure afterwards:

FUNCTION zaif_aem_bupa_get_data .
*"----------------------------------------------------------------------
*"*"Local Interface:
*"  IMPORTING
*"     REFERENCE(RAW_STRUCT) TYPE  ZAIF_EVENT_RAW
*"     REFERENCE(RAW_LINE)
*"     REFERENCE(SMAP) TYPE  /AIF/T_SMAP
*"     REFERENCE(INTREC) TYPE  /AIF/T_INTREC
*"     REFERENCE(SENDING_SYSTEM) TYPE  /AIF/AIF_BUSINESS_SYSTEM_KEY
*"       OPTIONAL
*"  TABLES
*"      RETURN_TAB STRUCTURE  BAPIRET2 OPTIONAL
*"  CHANGING
*"     REFERENCE(OUT_STRUCT) TYPE  ZAIF_AEM_BUPA_EVENT_MESSAGE
*"     REFERENCE(DEST_LINE)
*"     REFERENCE(DEST_TABLE)
*"     REFERENCE(APPEND_FLAG) TYPE  C
*"----------------------------------------------------------------------

  SELECT
    FROM A_BusinessPartner
    FIELDS
      BusinessPartner,
      FirstName,
      lastName,
      businesspartnercategory,
      \_BusinessPartnerAddress-addressid,
      \_BusinessPartnerAddress-ValidityStartDate,
      \_BusinessPartnerAddress-validityenddate,
      \_BusinessPartnerAddress-streetname,
      \_BusinessPartnerAddress-cityname,
      \_BusinessPartnerAddress-housenumber,
      \_BusinessPartnerAddress-postalcode,
      \_BusinessPartnerAddress-country
   WHERE BusinessPartner = @RAW_struct-objkey
    INTO TABLE @DATA(lt_result).

  IF lt_result IS NOT INITIAL.
    READ TABLE lt_result ASSIGNING FIELD-SYMBOL(<ls_result>) INDEX 1. "General Data is the same in every Row
    IF <ls_result> IS ASSIGNED.
      MOVE-CORRESPONDING <ls_result> TO out_struct-data-businesspartner.
    ENDIF.
    MOVE-CORRESPONDING lt_result TO out_struct-data-bpaddress.
  ELSE.
    CALL FUNCTION '/AIF/UTIL_ADD_MSG'
      EXPORTING
        msgty      = 'E'
        msgid      = '/AIF/MES'
        msgno      = '000'
        msgv1      = 'No Business partner found'
      TABLES
        return_tab = return_tab.

  ENDIF.

ENDFUNCTION.

5) AIF Action Creation & Assignment

The Action, which is calling the AEM, has to be created and configured.

/N/AIF/CUST -> Interface Development -> Define Action

The Function Module "ZAIF_ACTION_CALL_AEM" is provided by the AIFAEM AddOn and can be used for all Event Interfaces.

After saving, the Action can be assigned to the Interface in /N/AIF/CUST -> Interface Development -> Define Structure Mapping -> Assign Action

6) Testing & Monitoring

As mentioned in Step 1, the Event Linkage in SWE2 needs to be activated. After that we can trigger the Event. In this case we just change a Business Partner in Transaction BP:

--> AIF Monitoring /N/AIF/ERR

to see the mapped result, we can use the Technical Mode and transform

Now we can see the data:

Message on Advanced Event Mesh:

Now if I add an Entry in my Name Mapping Table, I can change the Field Names in the Json:

Summary

This Blog shows how to easily set up an Application Interface Framework (AIF) Interface for any SAP Standard Event on the example Business Partner. Additionally the AIF offers a lot of other features which can be used, for instance to do Checks, Value Mappings or enhance the Monitoring to Select Events based on any Information the Target Data contains. This should enable many Customers to easily publish and enhance Events to Advanced Event Mesh.