Consuming SAP with SAP Build Apps - adding application logic with CAP while keeping the core clean

[LudoNoens]

This blog post is the seventh in a series of posts that cover the connectivity options available for SAP Build Apps to interface with SAP systems. The series will cover connecting SAP Build Apps with the following:

1. CAP-based services
2. S/4HANA systems
3. ABAP systems

The format of this post is similar to a tutorial. However, I'll provide more comprehensive details, tips and the opportunity for you to provide feedback. Based on the feedback we will be able to adjust and enhance this post and future parts of the series, and might even be able to improve the products involved as well. 

Introduction 

Before we get into the details of setting up connections between SAP Build Apps and SAP Systems, I intend to introduce a couple of SAP technology components in each post that are relevant for the use cases covered in the series.

Custom business logic

Custom logic in CAP allows you to extend and customise the default behaviours of the framework a fully tailored and functional application. This custom code allows you to implement data validation, enrichment, calculations, integration with external systems, or any other custom processing that your application requires.

In the above figure, the Service API for custom logic, you see four types of APIs. More details can be found in the Learning Journey "Building side-by-side extensions on SAP BTP". In this blog post, we will focus on the custom event handlers.

Use case G : Adding application logic to the CAP service

For this use case, we'll use SAP Build Code to enhance the CAP service exposing the data source from an S/4 HANA Cloud system and use it in the application previously created in SAP Build Apps. We will also use the Joule assistant to create some code for us. There will surely be CODING involved here, but it will be minimal. This is a typical scenario for so called side-by-side extensions on SAP Business Technology Platform.

Solution diagram

We will start with a quick look into what needs to change in our solution overview. For this use case, the change is relatively small. I've added some app logic that handles the data coming from the S/4HANA Cloud sandbox system. We have already rerouted the data flow in the previous blog post. By routing the data source through our CAP service we can add application logic without changing anything on the S/4HANA system.

The application logic editor

We will now go ahead and add logic to the data service for the entity MySupplier. This service entity exposes a limited set of data entities coming from the S/4HANA Cloud sandbox system. Select MySupplier on the Storyboard and select Add Logic.

The Application Logic Editor opens and a dialog is shown to add a logic module. The logic will be invoked by an event handler. The code for the event handler itself will be generated for you; so you just need to focus on the logic itself.

We'll use the defaults here and select Add.

You will now see the editor, with your new logic module selected. 

Configuring the application logic

There are a few things you can configure. One category is the phase in which the code is triggered during request processing. The other is which standard event it is associated with. For more details, please refer to the CAP documentation.

Phase

Here you can select the phase in which the event handler triggers your code:

Before
As the name suggests, in this case the code will be activated before the service executes it's task. A common use case is the validation of user input. 

On
This is the phase where the event handler actually fulfills a request, such as reading or writing data to or from a database. An example use case here is the creation of mashups or returning mockup data.

After
This code is activated after the service executed it's task and results have been retrieved. A typical use case here is to enrich outbound data.

Standard Event

Your logic can be associated with one or more events related to Create, Read, Update and Delete.

Adding the code

For our example use case, we are adding logic to handle the requests for retrieving data from the S/4HANA Cloud sandbox system. As mentioned before, this data source is read-only. Therefore, our example here will be limited to the READ requests and handle the data after receiving it.

Select Open Code Editor and pick Application Logic.

This opens the code editor, and along side it, for those using SAP Build Code, the SAP Joule AI assistant will be ready for your prompt. In this example I will use Joule. Those using SAP Business Application Studio can just copy-paste the code into the code editor for the same result. 

As you might have noticed while browsing through the data retrieved from the S/4HANA Cloud sandbox system, this contains quite some test data, including plenty of suppliers with the name "Supplier". For the sake of this blog post, we will change the response data before it is sent to the SAP Build Apps client application. This is just simple example of what is possible, without making things too complicated.

I will Accept the code proposed by Joule, which will be copied into my application logic module.

As you might have noticed, Joule will now also offer a button to Open Debug Console. This can help you in debugging your (or Joule's) code. I'll come back to the topic of debugging later. Please be aware that code generated with Generative AI is not always perfect. As mentioned, Joule is an assistant and you as developer must check what your assistant is doing.

While we are at it, let me add another piece of code (manually). In case the SupplierName contains the word "test", we add a fake VAT registration number for that specific record. The end-result is this piece of logic:

/**
 * Example of service logic to alter query results.
 * Where the SupplierName contains "Supplier", we change it to "Acme Corporation" (Meep Meep...) and add a VAT registration number.
 * Where the SupplierName contains "test", we add a VAT registration number.
 * @After(event = { "READ" }, entity = "blogproductssvc.MySupplier")
 *  {(Object|Object[])} results - For the After phase only: the results of the event processing
 *  {Object} request - User information, tenant-specific CDS model, headers and query parameters
 */
module.exports = async function(results, request) {
    // Check if results is an array, if not make it an array for uniform processing
    const suppliers = Array.isArray(results) ? results : [results];

    // Iterate over each supplier and modify the SupplierName and VATRegistration if condition is met
    suppliers.forEach(supplier => {
        if (supplier.SupplierName && supplier.SupplierName.includes("Supplier")) {
            supplier.SupplierName = "Acme Corporation";
            supplier.VATRegistration = "US12345678";
        }

		if (supplier.SupplierName && supplier.SupplierName.includes("test")) {
            supplier.VATRegistration = "2001234";
        }
    });
}

So, where does this code end up in your project? The above code is stored in srv/code, as you can find in the Explorer.

There is also code generated for you (the other highlight files). The srv/service.js handles the initialisation and registers your code with the handler(s). There is also an xml file (using extension .code) that is used by the Application Logic Editor.

Preview the results

Let us see whether this works by starting a Preview. Open the Run Configuration tab and hit Run for the Business Partner (A2X) entry.

The project preview will open. We can now select the 'View as code' button for MySupplier.

In the output, you will find the changed data.

Alternatively, you can run the preview app.

Debugging your code

What if you've created a bug in the logic code? Well, you can easily debug this in the SAP Build Code environment.

In the code editor, you can set a breakpoint in front of the line where you want break execution and inspect what is going on in your JavaScript function.

When you now run your project and trigger your code (by requesting data) the execution will stop in SAP Build Code. In the screenshot below, you can see the breakpoint that was hit. In the debug console you can see the connection details. In the Run and Debug panel you can see local variables, items I've put on the Watch list and also the call stack.

Debugging your code in this SAP Build Code (or SAP Business Application Studio) environment is a lot easier than debugging your service once it is deployed to BTP. So I highly recommend debugging your service's application logic here, using the Preview function.

Deploy to BTP and run the SAP Build Apps preview app

Now that we are done coding, let's deploy it to BTP and go back to SAP Build Apps to see how our data is received in our UI application.

Summary – use case G

In this use case we have added custom application logic code to our data service handling data coming from an S/4HANA Cloud 'sandbox' ERP system. As the sandbox system's data services are read-only, we have implemented a simple piece code that changes records after the READ operation is done. 

We have used Joule as our code assistant to generate some of this logic.

It was also demonstrated how easy it is to debug your custom application logic within SAP Build Code, without even deploying your application to BTP. 

What's next

In the next blog post, we will continue on the connectivity topic and change the UI application into a CRUD application.