page_type	languages	products	urlFragment	name	description
sample	azdeveloper javascript bicep hcl powershell	azure azure-monitor azure-key-vault azure-app-service azure-api-management azure-cosmos-db azure-database-postgresql	app-service-javascript-sap-cap-quickstart	SAP CAP on Azure App Service Quickstart	Quick-start project using SAP CAP model with consuming SAP OData running on Azure App Services backed by Azure Cosmos DB for PostgreSQL.

SAP CAP on Azure App Service Quickstart 🚀

This repos serves as quick-start project showcasing SAP Cloud Application Programming Model (CAP) for Node.js OData consumption from SAP S/4HANA running on Azure App Services backed with Azure Cosmos DB for PostgreSQL. SAP offers a native module cds-dbs for PostgreSQL integration.

Understand the difference between Azure Database for PostreSQL and Cosmos DB for PostgreSQL from this post.

The project's primary purpose is to set you up for success for your SAP extension project on Azure and reduce the lead time to your first successful deployment as much as possible with developer friendly commands.

It uses the Business Partner OData v2 API from SAP S/4HANA as an example.

The project is setup as per the best practices advocated by the Azure Developer CLI and referenced as official awesome azd template.

Warning

Verify the latest SAP's open-source license for SAP CAP for your reference. Please be aware if your SAP libraries are still using the SAP Developer License. Components are being added to open-source by SAP on an ongoing basis according to their road map published here. When in doubt, consider the SAP Cloud SDK on Azure instead.

Tip

• In case you need to translate between OData versions and metadata specification use our converter here.
• Looking for SAP CAP for Java? See the SAP docs here.
• Looking for the less opinionated SAP Cloud SDK with pug template engine for UI generation? See the dedicated repos here.

Features ⚙️

Implementations using the approach described by this repo expand the feature scope of SAP CAP for Node.js to Azure PaaS apps.

Important

When deployed on Azure App Services instead of SAP Business Technology Platform, Cloud Foundry specific features like the destination service or XSUAA are not available. Instead you will likely be using Microsoft Entra ID and the App Service and Azure API Management to govern your APIs.

• One code base to run on both Azure App Service and SAP Business Technology Platform
• Built in resiliency and caching patterns
• Native Azure authentication and token handling with Entra ID without any coding effort. Simply switch on the Microsoft Entra ID for your App Service on the AZD config here using variable useEntraIDAuthentication.
• Configurable Azure API Management integration for SAP APIs including policy enforcement for use cases like request throttling, SAP token caching, etc.
• Native Azure virtual network integration next to the SAP workload
• Enabled for SAP Private Link and Azure Private Link / Private Endpoint (depending on wether you use the SAP Business Technology Platform or Azure only)
• OData v2 and v4 + entity and client generator managed by SAP
• OpenAPI + client generator managed by SAP
• Seamless integration with Azure native databases Azure Cosmos DB, purpose built for cloud native apps
• Frictionless integration of Azure App Service app roles with SAP CAP authorization model using cds-entra-id
• Out-of-the-box support for remote debugging your CAP application hosted on Azure App Service as described here.

This example uses a UI5-based app for rendering the UI. Learn more about other template engines here.

Getting Started 🛫

Prerequisites & Installation

Follow the SAP CAP documentation for Node.js for your project setup.

Use the devcontainer (with GitHub Codespaces for instance) or install the Azure Developer CLI in your environment.

Use any OData enabled SAP system:

• SAP's mock server (used in screenshots below),
• SAP API Business Hub S/4HANA Cloud sandbox with APIKey (⚠️read-only)
• SAP's public demo system ES5 (⚠️Business Partner API not activated!),
• S/4HANA Fully-Activated Appliance from SAP Cloud Appliance Library or
• your own available in-house SAP system.

Important

Be aware that SAP's mock server is anticipating the S4 Cloud version of the Business Partner API. So, you might need to adapt the mock server to your needs. During our testing at the time of release there were no discrepancies discovered. You may expose the mock server running locally for testing with the cloud services to the internet using ngrok or similar tools.

to hit the ground running with our tailored image and avoid installing anything on your local machine and continue with step 6.

Quickstart 🚀

Familiarize yourself with the SAP CAP for Node.js jumpstart guide and optionally browse SAP Developer tutorials like this beginner guide and this end-to-end focused one.

Deploy time

0. Run azd auth login and az login to authenticate with Azure and Azure Developer CLI (AZD). Azure CLI is required for the runtime update of CosmosDB credentials on the Azure App Service during post-provision. See here for reference.

1. Switch the current working directory to azd-sub, containing the azure.yaml defining all resources and deployment procedure to bring your application up in Azure.

   cd azd-sub

2. Run the following command to package a deployable copy of your application, provision the template's infrastructure to Azure and also deploy the application code to those newly provisioned resources.

   azd up

This command will prompt you for the following information:

• Azure Location: The Azure location where your resources will be deployed.
• Azure Subscription: The Azure Subscription where your resources will be deployed.

Note

This may take a while to complete as it executes three commands: azd package (packages a deployable copy of your application), azd provision (provisions Azure resources), and azd deploy (deploys application code). You will see a progress indicator as it packages, provisions and deploys your application.

Dev time

1. cd src/
2. npm install
3. cp ../templates/.env ./.env and maintain your OData url including credentials
4. Start Docker engine locally (or use pre-provided devcontainer - Docker outside of Docker feature)
5. docker-compose -f pg.yml up -d
6. cds watch
7. browse to http://localhost:4004 for your "hello world"
8. browse to http://localhost:8080 to use postgres web interface adminer

Note

Use the hybrid profile cds watch --profile hybrid to query the Azure PostgreSQL DB instead of the local dockerized PostgreSQL instance. Note that this requires to have additional credentials set in /.env. See here for more details.

Deploy to Azure 🪂

There are multiple ways to deploy this project to Azure. We provide two options in this repository:

1. via template deployment and VS Code extension. This approach allows an quick deployment to Azure but does not necessarily reflect the best practices. You find more information on this option here.
2. via Azure Developer CLI using azd up. This approach enables a quick and easy deployment and already contains best practices. It serves as a perfect starting point for a production grade setup. You find more information on this option here.

Deploy to SAP BTP 🪂

Code-based deployment could be done using the recently added SAP BTP terraform provider or the open-source project BTP setup automator. The configuration comprises the infrastructure as well as the mta build and the deployment to Cloud Foundry. You can find more information on the setup using the BTP automator here and for terraform here.

Cost estimates

Solution componenents like the Azure App Service offer free plans. The burstable plans of Azure Cosmos DB for PostreSQL is the primary consumption driver. Consult the Azure Pricing Calculator for a detailed view.

What's next?

You can do a lot more once the app is deployed. Curious? We got you covered with some more information on out-of-the-box Entra ID (formerly Azure AD) authentication here, insights into networking, OpenUI5 for frontend design and DevOps here.

Troubleshooting 🩺

Sometimes things do not work as expected. Here are some resources that support you in finding and fixing the issue:

• Access SAP Gateway logs in /IWFND/ERROR_LOG
• Azure App Service diagnostics
• Use Kudu SSH console from VNet integrated App Service to check connectivity to SAP Gateway with curl https://<your domain>:<your https port>/sap/opu/odata/sap/API_BUSINESS_PARTNER -u "<user>:<password>"
• Azure API Management Request tracing
• Azure API Management Gateway logs
• SAP CAP Troubleshooting guide
• Remote Debug your application using remote debugging with the Azure App Service extension for VS Code.

Additional resources

We collected additional resources and related efforts and projects here.

Contributing 👩🏼‍🤝‍👨🏽

This project welcomes contributions and suggestions. Please use GitHub Issues to report errors or request new features. For conceptual conversations, please use GitHub Discussions

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

Trademarks™

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.