tonybaloney/app-service-javascript-sap-cloud-sdk-quickstart

Sample project showcasing SAP Cloud SDK for OData consumption from SAP S4 with Azure App Service

page_type	languages	products	urlFragment	name	description
sample	azdeveloper typescript bicep hcl powershell	azure azure-monitor azure-key-vault azure-app-service azure-api-management	app-service-javascript-sap-cloud-sdk-quickstart	SAP Cloud SDK on Azure App Service Quickstart (TypeScript)	Quick-start project showcasing SAP Cloud SDK for JavaScript for SAP OData running on Azure App Services.

SAP Cloud SDK on Azure App Service Quickstart 🚀

This repos serves as quick-start project showcasing SAP Cloud SDK for JavaScript OData consumption running on Azure App Services. Its 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 for 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.

Looking for Azure Functions instead? Here you go.

Warning

Verify latest SAP's open-source license for the Cloud SDK for your reference.

Tip

• Looking for SAP Cloud Application Programming model instead of plain SAP Cloud SDK? See this sister project.
• In case you need to translate between OData versions and metadata specification use our converter here.
• In case you prefer an implementation without 3rd party library dependencies, have a look at this sister project deploying to Azure Functions.
• Looking for SAP Cloud SDK for Java? See this SAP repos.

Features ⚙️

Implementations using the approach described by this repos expand the feature scope of SAP's Cloud SDK for JavaScript 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.

• 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

Example uses pug engine for rendering the UI. Learn more about template engines here.

Getting Started 🛫

Prerequisites & Installation

Follow the SAP Cloud SDK documentation for JavaScript 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 Cloud SDK for JavaScript developer tutorial

Deploy time

0. Run azd auth login.

Important

Add az login if using the Entra ID option to authenticate with Azure and Azure Developer CLI (AZD). Azure CLI login is only required for the Entra ID deployment and configuration. See here for reference.

1. Run the following command to initialize the project.

   azd init --template app-service-javascript-sap-cloud-sdk-quickstart

   This command will clone the code to your current folder and prompt you for Environment Name. This will be used as a prefix for the resource group that will be created to hold all Azure resources. This name should be unique within your Azure subscription.

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

3. Select suitable VS Code workspace. We suggest bicep as it is the default for Azure Developer CLI.
4. cd app-service-javascript-sap-cloud-sdk-quickstart/src/api
5. cp ../../templates/.env ./.env and maintain your OData url including credentials
6. npm install
7. npm run start:dev
8. browse to http://localhost:8080 for your "hello world"
9. maintain your SAP OData url with credentials in .env file (put in project root app-service-javascript-sap-cloud-sdk-quickstart/src/api) and restart the app if necessary
10. browse to http://localhost:8080/business-partner for your first OData call and pick one of the business partners (examples below use ids from SAP mock server)

Important

SAP's examples for the business partner API for SAP S/4HANA Cloud mentioned in the tutorial differ to the SAP S/4HANA on-premises flavor. Add AddressUsage, otherwise you will see "Internal error when calling operation module BUA_CHECK_ADDRESS_VALIDITY_ALL; a check table is missing". Check SAP KBA's for more details.

10. get that business partner by id: http://localhost:8080/business-partner/1003764

11. update the address with a house number: http://localhost:8080/business-partner/1003764/address/28238.

Note

For your convenience we provide a collection of REST calls in the repos. Execute them with the VS Code REST client.

12. delete the address: http://localhost:8080/business-partner/1003764/address/28238

13. add an address to your chosen business partner: http://localhost:8080/business-partner/1003764/address

Congratulations 🥳, you have successfully consumed SAP OData with the SAP Cloud SDK for JavaScript running on Azure App Service!

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.

Important

If you choose to deploy to Azure via azd we provide two options to define the Infrastructure as Code, namely Bicep and Terraform. To make your life easier we provide two distinct workspaces for that to show you the relevant files and folders. If you want to go for Bicep you can open the workspace workspaces/azd-bicep.code-workspace, for Terraform go for the workspace workspaces/azd-terraform.code-workspace.

Deploy to SAP BTP 🪂

We provide the necessary configurations for the deployment to SAP BTP leveraging 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 find more information here.

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 Cloud SDK Troubleshooting guide

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.