saphanaacademy/generator-saphanaacademy-cap

Yeoman Generator to jump-start SAP Cloud Business Applications

generator-saphanaacademy-cap

Yeoman Generator to jump-start BTP Full-Stack Cloud Applications

Installation

This generator creates projects using SAP Cloud Application Programming Model (CAP)

First, install Yeoman and generator-saphanaacademy-cap using npm

npm install -g yo
npm install -g generator-saphanaacademy-cap

SAP BTP, Cloud Foundry runtime

We assume you have pre-installed node.js and the Cloud Foundry CLI with the multiapps plugin.

In order to build the project ensure @sap/cds-dk and Cloud MTA Build Tool (MBT) are installed.

This is already the case for SAP Business Application Studio.

If using SAP HANA Cloud ensure you have created an instance and have configured a database mapping to the SAP BTP, Cloud Foundry runtime org and space that you will be deploying to.

If using the HTML5 Application Repository ensure you have subscribed to the SAP Launchpad service in the subaccount where you'll be deploying the app.

If enabling Continuous Integration and Delivery (CI/CD) ensure you have subscribed to the Continuous Integration & Delivery service and optionally the Transport Management service in the subaccount where you'll be deploying the app.

Also ensure that you are logged in to the SAP BTP, Cloud Foundry runtime CLI and are targeting the org and space into which you want to deploy the app.

To generate your new project:

yo saphanaacademy-cap

NB: If you prefer a rich user experience when generating your projects consider the Application Wizard.

To refresh project files for an existing SAP HANA Cloud schema:

cd <projectName>
yo saphanaacademy-cap:schema

To refresh project files for an existing SAP HANA Cloud HDI Container:

cd <projectName>
yo saphanaacademy-cap:hdi

To refresh project files for SAP Graph:

cd <projectName>
yo saphanaacademy-cap:graph

SAP BTP, Kyma runtime

We assume you have pre-installed node.js, have a Docker Hub ID and the ability to build and push containers either via Docker Desktop or an alternative such as Paketo Builder with the pack CLI, Rancher Desktop or podman or a CI/CD pipeline with kaniko.

The Kubernetes command-line tool kubectl is required with the kubelogin extension.

In order to build or deploy the project via the Makefile ensure that GNU Make is installed.

In order to deploy the project ensure that Helm is installed or use a CI/CD pipeline.

If using SAP HANA Cloud ensure you have created an instance and have configured a database mapping to the SAP BTP, Kyma runtime namespace that you will be deploying to.

If using the HTML5 Application Repository ensure you have subscribed to the SAP Launchpad service in the subaccount where you'll be deploying the app.

If enabling Continuous Integration and Delivery (CI/CD) ensure you have subscribed to the Continuous Integration & Delivery service and optionally the Transport Management service in the subaccount where you'll be deploying the app.

Ensure that you have set the KUBECONFIG environment variable, have optionally created a namespace into which you would like to deploy the project and are logged in to Docker Hub. For example:

Mac/Linux:

chmod go-r {KUBECONFIG_FILE_PATH}
export KUBECONFIG={KUBECONFIG_FILE_PATH}
kubectl create ns dev
docker login

Windows:

$ENV:KUBECONFIG="{KUBECONFIG_FILE_PATH}"
kubectl create ns dev
docker login

You can also specify the path to your Kubeconfig file in the generator.

To generate your new project:

yo saphanaacademy-cap

NB: If you prefer a rich user experience when generating your projects consider the Application Wizard.

To refresh project files for an existing SAP HANA Cloud schema:

cd <projectName>
yo saphanaacademy-cap:schema

To refresh project files for an existing SAP HANA Cloud HDI Container:

cd <projectName>
yo saphanaacademy-cap:hdi

To refresh project files for SAP Graph:

cd <projectName>
yo saphanaacademy-cap:graph

To build and push your project containers to Docker Hub:

cd <projectName>
make docker-push

If you prefer, you can issue the build & push commands manually (see the generated /Makefile) or use a CI/CD pipeline.

To deploy your new project to SAP BTP, Kyma runtime:

cd <projectName>
make helm-deploy

If you prefer, you can issue the helm commands manually (see the generated /Makefile) or use a CI/CD pipeline.

To undeploy your new project from SAP BTP, Kyma runtime:

cd <projectName>
make helm-undeploy

Important

Please pay special attention to messages produced by the generator!

Video Tutorials

For hands-on video tutorials click here.

Getting To Know Yeoman

• Yeoman has a heart of gold.
• Yeoman is a person with feelings and opinions, but is very easy to work with.
• Yeoman can be too opinionated at times but is easily convinced not to be.
• Feel free to learn more about Yeoman.

License

Copyright (c) 2022 SAP SE or an SAP affiliate company. All rights reserved. This project is licensed under the Apache Software License, Version 2.0 except as noted otherwise in the LICENSE file.

generator-saphanaacademy-cap's Issues

Unable to use with existing HDI Containers

While attempting to use this generator for an existing HDI Container, once I enter a hdi service name, I'm no longer presented with options to add the schema, url etc..

I've tried this via command line and with UI in SAP Business Application Studio.

Can't use the Show Page Map from BAS.

HI experts.

Do you think it is possible to add to the generator the parameters so the Fiori Elements plugins recognize the Fiori app as a Fiori application?

Doing some research I found the missing configuration is to add at the bottom of the package JSON:
"sapux" : [
"app/fiori",
]

But this doesn't seem to be not enough, because now it knows that there is a Fiori app but it opens a blank page:

One thing that I found is if you add another Fiori project in the MTA and add again the Fiori app at the bottom of the package.json it will start to work.

Thanks and best regards,
Edu

How to run app locally with HANA Cloud?

Hi. Firstly thanks for this wonderful generator - excellent!

I'm wondering how to run the app locally. Obviously I can just do cds watch and I can run the app on localhost using an SQLite in-memory db.

But CAP has the ability to do this with the real HANA DB, yet still run the service locally. According to the CAP docs here: https://cap.cloud.sap/docs/guides/databases. you can execute:

cds deploy --to hana
cds watch --production

But then I hit errors as it cannot find the xsuaa service. This is where I am stuck. I've tried using the CF DefaultEnv plugin and it does get around the authentication issue however I can no longer run the embedded html applications as they just give error like this:

Cannot GET /resources/html5/catalog/userInfo()

For some reason /resources gets added to the paths and that seems to be stuffing it up.

So I'm wondering if you know the "best" way to continue to develop an app from this generator - locally?

Unable to install this generator in BAS

It says installing forever in generator templates.
and "npm install -g generator-saphanaacademy-cap" throws the error in the screenshot.
2023-01-12T04_07_02_750Z-debug-0.log

Issue with creating an application if using an existing hdi container

When creating a BTP App using an existing hdi container, the creation stops and says schemaName is not defined in the mta yaml template.

I ran:
yarn run yo saphanaacademy-cap
used the default settings and entered an existing hdi container (question 6: Will you be using an existing SAP HANA Cloud HDI Container? If so please enter the HDI Container service instance name here or leave blank for none. )

? What project name would you like? app
? Would you like to create a new directory for this project? Yes
? What is the display name of your app? App
? What is the description of your app? Business Application
? Which runtime will you be deploying the project to? SAP BTP, Cloud Foundry runtime
? Will you be using an existing SAP HANA Cloud HDI Container? If so please enter the HDI Container service instance name here or leave blank for none.
? Would you like to create an entity with SAP HANA Cloud persistence? Yes
? Would you like to use native SAP HANA Cloud artifacts? Yes
? Would you like to enable external access to the HDI Container? Yes
? Would you like to use an external API? No
? Would you like authentication? No
? Would you like to enable OData v2 support? No
? Would you like a UI? No
? Will you be using a wildcard custom domain (eg: apps.domain.com)? If so please enter the custom domain name here. Leave blank to use the platform default.
? Would you like to include an additional backend service using SAP Cloud Application Programming Model? No
? Would you like to include an additional backend service using regular Node.js? No
? Would you like to enable messaging with SAP Event Mesh? No
? Would you like to enable Continuous Integration and Delivery (CI/CD)? No
? Would you like to enable Application Logging? No
? Would you like to enable GraphQL? No
? Would you like to enable a Swagger UI? No
? Would you like to build and deploy the project immediately? No
Accessing existing SAP HANA Cloud HDI Container: Start
Checking whether the service instance exists...
Creating service key...
Reading service key...
Accessing existing SAP HANA Cloud HDI Container: End
✖ An error occured while running saphanaacademy-cap:app#writing
Error saphanaacademy-cap
*/node_modules/generator-saphanaacademy-cap/generators/app/templates/mta.yaml:47
45| <% } -%>
46| - name: <%= projectName %>-db
>> 47| <% if(schemaName !== "" && hanaTargetHDI === ""){ -%>
48| - name: <%= projectName %>-db-<%= schemaName %>
49| <% } -%>
50| <% if(hanaTargetHDI !== ""){ -%>
schemaName is not defined
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

This lead to the issue of the first line.

I tracked down the issue to generators/app/hanaUtils.js. Here in the processSchema-Function it seems the JSON parsing is going wrong, leaving us with a hdiBinding still containing the credentials property. Therefore in the following lines, the properties schema, host, port, user and password are undefined.

OData v2 support not working. "kind" is set to "odata" instead of "odata-v2"

Hi team,

When using SFSF as external source and setting OData v2 support to true in the wizard, the kind attribute is set to odata:

"RCMCandidate": {
        "kind": "odata",
        "model": "srv/external/RCMCandidate",
        "credentials": {
          "[production]": {
            "destination": "sfsfcapapp-sf-api",
            "path": "odata/v2"
          },
          "[development]": {
            "url": "https://sandbox.api.sap.com/successfactors/odata/v2"
          }
        }
      }

This will break a Fiori Elements app, see:
https://answers.sap.com/questions/13530425/fiori-elements-list-not-showing-data-batch-request.html

When I set OData v2 support to true, I'm expecting the kind to be set to odata-v2, as stated in CAP docs:

You can consume OData V2 services with Node.js, by setting kind to odata-v2.

https://cap.cloud.sap/docs/releases/oct21#consuming-odata-v2-services-in-nodejs

Thanks,
Pedro