UI5 freestyle app in CAP

Hi,

I’ve been playing around with CAP for NodeJS, developing business applications for customers as well as some fun projects. In those apps I had to add a UI5 app to interact with the service layer of the CAP framework.Some of these UI5 apps were not fiori elements but  freestyle UI5 apps. The documentation of CAP is more focussing more on Fiori elements instead of real freestyle apps: https://cap.cloud.sap/docs/guides/fiori/

Even in the OpenSAP course they used Fiori Elements: https://open.sap.com/courses/cp7/overview

Adding a freestyle UI5 app is probably very similar to Fiori elements. Still I think it’s worth to mention something about it. 

In the SAP Web IDE and SAP Business Application Studio you can use the wizards that will generate your UI into the CAP project. In VS code, you use the Yeoman generator of Marius Obert: https://blogs.sap.com/2019/02/05/introducing-the-easy-ui5-generator/

Nevertheless, it is always good to know how to do it yourself, to know your options, to know what’s being generated. That’s what I did and what I’m going to share in the next steps:

1. 1. Start your project
   2. Add a UI5 Freestyle app
   3. Run the app
      1. Run with UI5Tooling
      2. Run using the approuter
      3. Run with Mock authentication
   4. Use UI5Tooling in MTA Build processes
   5. Conclustion

Let’s start 🙂

Start your project

Started project by following these steps:

https://cap.cloud.sap/docs/get-started/in-a-nutshell

• Add schema cds for the database layer
• Add cat-service cds for the service layer
• Add csv files for generating mock data
• Add sqlite and run the deploy command

Just for now, remove the authentication:

Before we can add a UI5 app, we need to implement the OData v2 proxy adapter: https://blogs.sap.com/2020/06/30/how-to-add-odata-v2-adapter-proxy-to-your-cap-project/

The proxy is needed because most of the UI5 templates are designed to work with OData v2. UI5 apps can work with OData v4 but you still might run into problems.

Add a UI5 freestyle app

Go into the app folder and let’s generate the UI5 app based on a template. Here you have a list of all possible templates to kick start your UI5 project:  https://ui5.sap.com/#/topic/a460a7348a6c431a8bd967ab9fb8d918

For generating the UI5 project, I used the official yeoman generator to create a project, more info:

https://blogs.sap.com/2020/04/07/ui5-tooling-a-modern-development-experience-for-ui5/

Start by installing yeoman for rui5 with the following command: 

npm install -g yo @sapui5/generator-sapui5-templates

Go to the app folder: cd app (it is important to stick with the folder “app” as this is being used by the “cds” commands to search for the UI layer)

Use Yeoman to create the UI5 project with one of the templates: 

yo @sapui5/sapui5-templates

Fill in all the fields of the yeomand wizard:

As soon as the yeoman wizard is finished, you will see the following files in the app folder:

Run the UI5 app with the UI5 Tooling

After the template is generated, you can run npm install and start to test the app using the UI5 Tooling:

1. First install all depdenncies by running “npm install”
2. And then start the app with “npm start”

This will only run the UI5 app but not the CAP service. Therefore, you need to open a second terminal and also run your cap project. 

When opening the browser on localhost port 8080, you will be able to test the app with data from the CAP project:

Unfortunately the UI5 serve command will not work on Cloud Foundry:

On top of that, it is not able to work with authentication, for example when we make the service only available for authenticated users:

It can, however, handle the mocked authentication: https://cap.cloud.sap/docs/node.js/authentication#mocked 

It could be used for testing purpose but not productive when working with authentication to your SAP IAS or the SAP default IDP, it will not be enough…

Run using the Approuter

We need to implement the approuter to be able to authenticate to an SAP IAS or the SAP default IDP. This is required to run in productive mode and can be used to test locally although you can run without it locally.

Adding the approuter: https://cap.cloud.sap/docs/node.js/authentication

Install the following NPM packages:

npm install passport

npm install @sap/xssec@^2 @sap/xsenv

Change the package.json in the app folder as followed to use it when running in SCP CF:

I changed the name of the original start script to “serve” so this can still be used and I added a new “start” script to run the approuter. Next to that, I added the approuter as a dependency.

Link to package.json of the UI5 app: https://github.com/lemaiwo/CAP-UI5-APP/blob/master/app/package.json

The approuter requires an additional files “xs-app.json” to be able to work. All the routes to the UI5 app and the service can be configured including the authentication. If “authenticationMethod” is “none”, the approuter will run without authentication. If it has the value “route”, like in my example, it will run with authentication:

Full code of the xs-app.json: https://github.com/lemaiwo/CAP-UI5-APP/blob/master/app/xs-app.json

In this file, you notice that I add a route to the dist folder and one to the webapp folder. The dist folder is for productive usage and the webapp is for debugging. I know that you can turn on debuggin in UI5 but it gives me another option to access the debug files. 

When using the approuter, we also need to change the path to the OData service in the manifest.json. Add a “/” in front of the uri:

Almost ready to test the approuter but first we have to add configuration for the approuter to know the xsuaa service in SCP and a destination to the OData service for testing locally.

Add another file “default-env.json” in the “app” folder:

Add a section for the destination like this. The approuter needs this to find the CAP service that’s running locally. On SCP CF this will be resolved by the MTA config:

And add VCAP_SERVICES with the details of the xsuaa service that you use in your SCP account:

Full code: https://github.com/lemaiwo/CAP-UI5-APP/blob/master/app/default-env.json

The same file needs to be added to the root project with only xsuaa part: https://github.com/lemaiwo/CAP-UI5-APP/blob/master/default-env.json

Now we are ready to start the approuter.

Go to the app folder:

• cd app

Install the approuter by running the command npm install. I already added the dependency earlier to the package.json:

• npm install

We need to build the app to have a dist folder. This is needed because I have defined a route to the dist folder in the xs-app.json file earlier. If a path in one of the routes is not available, the approuter will fail to start:

• npm run build => to generate the dist folder

Start the approuter:

• npm start (you can still use the ui5 tools with npm serve)

We also need to start the OData service in the CAP project. Before we can run this, we need to change the authentication mechanism to JWT so it can handle the requests from the approuter. Add the following to the package.json file of the root folder:

    "auth": {
      "passport": {
        "strategy": "JWT"
      }
    }

Open a second terminal and run the command: “cds run”

We can now test the app via approuter on localhost:5000

⇒ The approuter will detect that authentication is required and forward you to the right Identity provider, by default it will be the SAP IAS

After authentication you will have access to your app and the service. But this still requires to run two terminals just for testing the app. Of course, this could be simplified by creating a custom npm script in the package.json.

Nevertheless, there is still an easier way to do the same which I will explain in the next section.

Run using CAP Mock authentication

Instead of running two terminals, remove the authentication config in package.json and simply use “cds run”

You will get a basic auth popup, you can fill in whatever you like or just nothing and hit enter to authenticate:

Just like in the two previous case, you will have access to the app and the service behind it. With only one simple command 🙂

If you want, you can configure mock users for the basic authentication dialog. You can find more details about that in the official SAP documentation here: https://cap.cloud.sap/docs/node.js/authentication#mocked

Use UI5Tooling in MTA Build process

For deploying to SCP CF you can follow the steps here: 

https://cap.cloud.sap/docs/advanced/deploy-to-cloud

Switching to hana is not needed anymore, like explained here:

https://cap.cloud.sap/docs/guides/databases

You will still need to add some config for using the UI5Tooling when building the MTAR. Therefore, I will still add the following steps here:

First, run cds build which will generate a gen folder with all modules:

Generate an mta.yaml file to start with by using the following command:

cds mta add

We will still need to add the “ui” module to the mta.yaml configuration file. Here we define a custom builder to use the UI5Tooling in the MTA build process ui module.

 - name: ui
   type: html5
   path: gen/app
   build-parameters:
     builder: custom
     commands:
       - npm install
       - npm run build
   requires:
     - name: srv-binding
       group: destinations
       properties:
         forwardAuthToken: true
         name: srv_api
         url: '~{srv-url}'

Full mta.yaml config: https://github.com/lemaiwo/CAP-UI5-APP/blob/master/mta.yaml

I had some help for this configuration from SAP:

https://github.com/SAP/cloud-mta-build-tool/issues/722#event-3201612082

   build-parameters:
     builder: custom
     commands:
       - npm install
       - npm run build

Now we are ready to build the MTA and deploy to SCP CF with MTA Build Tool as described in the documentation:

https://sap.github.io/cloud-mta-build-tool/

Conclusion

You can add a UI5 freestyle app like you would do otherwise, you just need to make sure it’s being added into the “app” folder. For running the UI5 app in the CAP project with the service there are several options possible:

1. Approuter: is needed anyway for running the app on SCP CF with authentication. Nevertheless, you do not need to use the approuter for local testing. A few things you need to be aware of in case you want to use it for local testing:
   1. does require separate server
   2. add config for xsuaa service ⇒ default-env.json
   3. requires connection to SCP CF
   4. gives you the possibility to run like it would run on SCP CF
2. UI5 tooling can be used instead of the approuter but will only allow you to run with mock authentication. 
   1. also requires a separate server
   2. only works with mock authentication
   3. gives you the power of the UI5 Tooling and community extensions like livereload, livetranspile and more here: https://petermuessig.github.io/ui5-ecosystem-showcase/
3. use cds run
   1. single server for service and UI5 app
   2. mock auth
   3. the cds tools comes with a “watch” command but no possibilites for live transpiler or other UI5Tooling extensions

My suggestion, add the UI5 project, configure the approuter and run the app (UI and service layer) using the UI5 tooling or with cds run/watch.

The choice between UI5Tooling and the CDS tooling all depends on your needs for developing UI5 apps.

As mentioned earlier, for setting everything up you can use the Yeoman generator of Marius Obert: https://blogs.sap.com/2019/02/05/introducing-the-easy-ui5-generator/

But it’s always good to know how it works 🙂

The full project is available on GitHub: https://github.com/lemaiwo/CAP-UI5-APP