Skip to content

Latest commit

 

History

History

btp-cap-monorepo

README.md

Project Template for SAP BTP & Fiori Application

angular-logo sap-cap-logo

This project is a development template for building mobile and desktop sap btp & Fiori applications
using Angular and Ant Design.

www.mtda.cloud

English | 中文

🌟 What is this?

This is a template for building SAP BTP and Fiori apps with Angular framework and Ant Design. It is based on Nx and UI5 Tooling.

  • Node.js 18
  • Angular 17
  • Tailwindcss 3
  • Storybook 7.5
  • ui5-tooling 1
  • CAP SDK 7

⚡ Quick Start

🛫 Start the Project

Before you start, install npm packages by running npm install or yarn install.

Before other packages that this project is depend on upgrade to Angular 17 version, please use npm install --legacy-peer-deps to install dependent packages.

Start BTP App

Run docker-compose up -d to start the docker container of the pg database service.

If you first run this BTP project, run yarn deploy:btp:local to deploy db models to local database.

To start the development server run yarn start or run nx serve launchpad and yarn --cwd caps/app-store w-sandbox separately. Open your browser and navigate to http://localhost:4200/. Happy coding!

Start s4h App

Run yarn start:s4h:live or yarn start:s4h:mock to start the application for s4h system.

Environments

The application has two environments, development and production. The default environment for build is production, and default environment for serve is development. You can change the environment by setting the --configuration option when running the build or serve command.

The features in environment are:

  • production - enable production mode, disable debug log, and others.
  • platform - S4H | BTP | LOCAL
  • enableFiori - enable load all Fiori apps in SAP system as menus in this application.
  • enableNotification - enable notification service in S4HANA system.
  • enableWaterMark - enable water mark on page of the application.
  • mockData - is mock data in local.
  • embeddedAnalytics - Enable embedded analytics in S4HANA system.
  • enableDemo - Enable demo pages, you can view demo features.

✨ How we generate the code?

We use the Nx CLI to generate code npx create-nx-workspace <workspace-name>.

Add tailwind css use command npx nx g @nx/angular:setup-tailwind launchpad.

Add UI library Ant Design of Angular ng-zorro-antd use command npx nx g @nx/angular:ng-add ng-zorro-antd --style=less.

Add storybook use command npx nx g @nx/angular:storybook-configuration launchpad.

🖥 Previewing Application

You can execute the following npm scripts to preview the application:

  • start - starts the application (btp).
  • start:btp - starts the application for btp.
  • start:s4h:live - starts the application for s4h system with live service.
  • start:s4h:mock - starts the application for s4h system with mock data.

📡 Use Live Data

When running npm run start the local development application and calling the live OData service, you need to configure the proxy to forward the request to the ABAP server.

Here is the configuration file apps/launchpad/proxy.conf.json, all the requests starting with /sap/ are forwarded to the server target, and the authorization account information auth is configured.

{
  ...,
  "/sap/": {
    "target": "<your sap abap server url>",
    "secure": false,
    "changeOrigin": true,
    "auth": "<SAP Username>:<SAP Password>"
  }
}

📋 Use Mock Data

When using npm run start-mock to start the application and a mock server to reflect the OData endpoint, you can use the application without having to connect to a live OData service and generate mock data on the fly.

Add New OData Mock Data

If you want to add new OData mock data, you need to create a folder in the src/mock/odata/odata service name directory with the name corresponding to the OData service you want to simulate. Inside this folder, you should add a metadata.xml file, which should contain the metadata for the respective OData service. You can also create a data subfolder to store mock data files.

You also need to add a service configuration (for example: EPM_REF_APPS_PO_APV_SRV) in the ui5-mock.yaml configuration file, as follows:

...
server:
  customMiddleware:
    - name: sap-fe-mockserver
      configuration:
        mountPath: /
        services:
          ...
          - urlPath: /sap/opu/odata/sap/EPM_REF_APPS_PO_APV_SRV
            metadataPath: ./src/mock/odata/EPM_REF_APPS_PO_APV_SRV/metadata.xml
            mockdataPath: ./src/mock/odata/EPM_REF_APPS_PO_APV_SRV/data
            generateMockData: false
            debug: true
            watch: true

Please refer to @sap-ux/ui5-middleware-fe-mockserver for more detailed usage instructions.

Troubleshooting Tips

toString error in mockserver

In dealing with mock data containing navigation, the mock server might throw an error related to a toString() call. Please check the following code in the getV2KeyString function within the @sap-ux/fe-mockserver-core/dist/data/dataAccess.js file:

default: {
  // keyStr = encodeURIComponent(`'${currentKeys[Object.keys(currentKeys)[0]].toString()}'`);
  // Change to
  keyStr = encodeURIComponent(`'${currentKeys[Object.keys(currentKeys)[0]]?.toString()}'`);
  break;
}

🚀 Ready to deploy?

Ready to deploy, you can ref to How to deploy?.

Deploy to BTP

For BTP platform, you can disable

  • yarn b:btp Build for BTP platform.
  • yarn d:btp Deploy to BTP platform, you might be login using cf cli firstly.

Deploy to S4HANA

  • Base url

The deployed application needs to be opened in a non-root path, so you need to configure the base url when building the app. Replace your_project_name with the name of the BSP application in command yarn b:s4h:app.

{
  "b:s4h:app": "nx build launchpad -- --base-href /sap/bc/ui5_ui5/sap/your_project_name/",
}
  • Deploy

Run yarn d:s4h to build and deploy to s4h system, other details ref to Deploying to ABAP.