Chapter 1: Introduction to SAP Messaging Mechanisms

This article shares insights from my experience within the SAP Labs China Development Team, focusing on the design and technical aspects of message display across various SAP products.

The motivation for this write-up stems from a customization inquiry regarding the SAP Commerce Cloud Spartacus UI presented in the StackOverflow community by a partner. The context revolves around enabling customers to leave feedback on product detail pages within the SAP Commerce Cloud and receive a notification upon submission via a "Submit" button. The current system prompts users with a message reading, "Thank you for your review." However, the client seeks to modify this default behavior to execute alternative actions, such as sending notifications via SMS or email, instead of displaying the standard message.

Before delving deeper, it's essential to briefly assess the UI message display mechanism utilized in other SAP products. Messages serve as a vital communication channel for user feedback during application usage, typically initiated by user actions and showcased on the product interface. Background jobs within the application can also trigger message displays based on specific conditions at different stages. Clear, concise messages are critical in assisting users in understanding the application's current status and guiding their next steps.

Messages presented in SAP product UIs are meticulously reviewed and published by a dedicated Knowledge Management (KM) team. For developers, the context surrounding these messages is paramount; upon encountering a message in the UI, they aim to quickly pinpoint the exact code responsible for generating it.

For instance, in the classic SAPGUI SE38 ABAP program editor, if a user inputs a nonexistent report name, the system will display the message: "Program XX does not exist," where "XX" is a placeholder for the actual report name inputted by the user.

All SAP products that utilize ABAP, including SAP CRM, SAP SRM, SAP S/4HANA, and SAP Cloud for Customer, have corresponding backend message records for each UI message, which can be maintained using transaction code SE91. For the aforementioned message, its code is DS017, with "DS" representing the message class and "017" being the unique message number that identifies the record.

In the SAP CRM WebClient UI, every message presented in the browser, such as "Data Contains errors and cannot be saved," corresponds to a backend message record identified as CRM_BUPA_BOL/036, maintained by the Business Partner application.

In SAP Cloud for Customer, while partners do not have direct access to the ABAP backend, they can still ascertain the message class and number corresponding to UI messages via Chrome Developer Tools. Additionally, partners can create new UI messages through the Cloud Application Studio. In the ABSL code, messages are displayed on the UI using the raise statement:

raise delivery_message.Create("S", this.OutboundDeliveryID);

At runtime, the placeholder &1 in the message text defined by delivery_message will be substituted with the value from the this.outboundDeliveryID field.

In SAP S/4HANA, all Fiori apps built on Fiori Elements utilize a common set of view templates and controller implementations, leading to most messages being maintained by the framework rather than defined within individual applications. For example, the message "Product Type 03 is not valid" is maintained within the message class /BOFU/CODE_LISTS, associated with the Business Suite Foundation Reusable Components development package.

Let's now revisit the customization request concerning the message display in SAP Commerce Cloud introduced earlier in this article. The identifier for the "Thank you for your review" message is productReview.thankYouForReview, which is displayed via the MessageService after the ProductReviewEffects receives the POST_PRODUCT_REVIEW_SUCCESS action.

A conventional method for secondary development would involve inheriting the standard ProductReviewEffects class of SAP Commerce Cloud UI and overriding the implementation logic following POST_PRODUCT_REVIEW_SUCCESS to eliminate the MessageService call responsible for displaying the thank-you message. However, since all Effects implementation classes released by SAP Commerce Cloud UI are non-extendable, this approach is not feasible.

Next, let's take a look at the communication framework between Spartacus and the Commerce backend, illustrated in the following figure. The interaction is performed through HTTP calls to the OCC API. The Connector initiates these HTTP requests while maintaining static configuration details, specifically the API endpoint.

For instance, when retrieving product master data from the Commerce system, the field list to be read is specified as URL parameters within the API endpoint. These parameters can be configured within the Connector's static configuration.

The Connector does not communicate directly with Commerce but instead forwards requests to the Adapter, which manages the specific communication tasks. By default, the Adapter provided by Spartacus utilizes the OCC Module, which corresponds to Commerce's standard OCC RESTful API. However, clients are also able to create their own Adapter to connect to backend systems other than Commerce.

The data retrieved by the Adapter is relayed to the NgRx Store for unified management, with its complexity abstracted by the Facade layer. Consequently, Spartacus UI components only interact with the Facade layer for data binding and page display, adhering to the principle of separation of concerns.

To implement the customization request previously mentioned, we must examine the details concerning the interaction between the NgRx Store and the SAP Spartacus Connector, which is highlighted in the following figure.

NgRx serves as a reactive state management library for Angular, based on RxJs, and comprises several core concepts, which I will elucidate with practical use cases of NgRx within the SAP Commerce Cloud UI.

• Action: Essentially serves as an event alias within the programming domain. The UI components of SAP Commerce Cloud can respond to user operations and dispatch corresponding Actions via the component's Service instance. The sender and receiver of the Action remain decoupled and unaware of each other's existence.

The subsequent figure illustrates the Service class's code that dispatches the PostProductReview Action once the Submit button is clicked in the review section of the SAP Commerce Cloud product detail page. ProductActions.PostProductReview is a subclass of NgRx Action, with the type field designated as POST_PRODUCT_REVIEW. The payload parameter within the constructor defines the data structure required to persist user reviews via the Commerce OCC API call.

• Effects: These serve as receivers of Actions within SAP Commerce Cloud UI. The following Effects code receives Actions of type POST_PRODUCT_REVIEW (line 46), calls the Connector to initiate OCC API calls to the Commerce backend (line 49), and based on the API results, dispatches either the review save success or failure Action:
  • PostProductReviewSuccess (line 53)
  • PostProductReviewFail (line 56)
• Store: This is a memory-maintained structure within Angular applications containing runtime data for all SAP Commerce Cloud UI components. When Effects retrieve new data from the Commerce OCC API, they invoke a Reducer to integrate the incremental data into the Store.
• Reducer: This acts as a finite state machine that, upon receiving an Action indicating data changes from the Commerce backend, drives the appropriate Reducer to adjust the data in the Store based on the payload from the new Action.

For example, when the product detail page is initially rendered, Effects must fetch all review data from the Commerce backend. Upon successful retrieval, a LOAD_PRODUCT_REVIEWS_SUCCESS Action is dispatched. The ProductReviewsReducer, upon receiving this Action, extracts the actual review data from its payload and returns it, which is then incorporated into the Store by the NgRx framework.

• Selector: These are pure functions that act as the interface for the application to access the latest data from the NgRx Store.

A thorough understanding of state management utilizing NgRx in the SAP Commerce Cloud UI is crucial for realizing the client-specific requirements presented at the beginning of this article.

Given that the standard Effects depicted in the SAP Commerce Cloud UI cannot be extended, we observe that the Service layer of UI components marks the starting point for all event flows. Therefore, we can create a new Service to replace the standard Service within the SAP Commerce Cloud UI, and on the basis of this customized Service, we can develop corresponding Effects and Actions.

As a result, the standard logic flow linked to user reviews, as illustrated in figures 1–2–3, will no longer be executed. Instead, our customized execution flow, represented in figures A-B-C, with blue annotations indicating the custom code to be developed by partners, will take precedence.

A brief overview of this solution includes:

1. Creating new Actions: CustPostProductReview, CustPostProductReviewSuccess, and CustPostProductReviewFail, which involves prefixing the standard implementation classes with "Cust."
2. Developing a new CustProductReviewService that inherits from the standard ProductReviewService. Its add method will be overridden to dispatch the new CustPostProductReview Action.
3. Establishing CustProductReviewsEffects that receive the new Action CUST_POST_PRODUCT_REVIEW (line 25), still invoking the Connector to save user reviews to the Commerce backend (line 28), and then dispatching the new CustPostProductReviewSuccess Action.

Upon receiving the new Action CUST_POST_PRODUCT_REVIEW_SUCCESS, the custom Effect can proceed with executing customized logic.

4. Finally, implement the custom Effect and Service, integrating them into the corresponding Module using the Angular dependency injection framework.

This article provides an in-depth exploration of the design and technical implementation details of messaging mechanisms I have been involved in across various product development projects at SAP. I hope this information serves as inspiration for fellow SAP practitioners. Thank you for reading.

An overview of how SAP systems display system messages to users, emphasizing the importance of effective communication.

Demonstration of the Call Step Atom and its integration framework for SAP Business One, showcasing practical applications of messaging solutions.