Important Notice

This public repository is read-only and no longer maintained.

Enterprise Sales Procurement Model (ESPM) Application

The ESPM (Enterprise Sales & Procurement Model) application is a reference application which demonstrates how to build applications on SAP Business Technology Platform (BTP) with the Java runtime. The application also consumes and showcases services like the Persistence Service, Document Service, SAP Jam Collaboration, and API Management which are offered by the platform. The application User Interface (UI) is built with the SAPUI5 framework after the SAP Fiori design principles.

Demo URL of the application https://espmrefapps.hana.ondemand.com/espm-cloud-web/webshop/

Business Scenario

The business scenario is that of an eCommerce site that sells electronic products.

The Customers can order products and provide reviews on the products.
The Retailer can then accept the sales orders created against orders created by customers. The Retailer can also update the product stock information.

Get the Source Code

Clone the Git repository or download the latest release.

1. Quick start guide

Setting up the developer environment

Install Oracle Java SE Development Kit (JDK) 8 and set up the JAVA_HOME and PATH environment variables on your local machine.
Install Eclipse. Please install Eclipse Oxygen.
(Optional: Only if you use SAP JVM) Set up SAP JVM in Eclipse.
Install SAP Development Tools for Eclipse. Please use the link for Eclipse Oxygen.
Install SAP Business Technology Platform SDK. Please install Java Web Tomcat 8.
Register for a free developer account on SAP Business Technology Platform, follow the tutorial.

Build the application and deploy

Below are the steps to build and run the ESPM application:

1.Git configuration in Eclipse
2.Maven configuration
3.Clone Git repository and import Maven project
4.Update dependencies and build Maven project
5.Deploy the application on local Cloud Runtime
6.Deploy the application on SAP BTP via the cockpit
7.Bind the database to espm application and start espm application

1.Git configuration in Eclipse

From the Eclipse IDE main menu, choose Window > Preferences
Enter git in the filter field in the top-left corner
Navigate to Team > Git > Configuration and select the Configuration node and add the following configuration

Note! For most people the proxy value doesn’t need to be set but if you are working behind a proxy, then it should be set as per you environment.

2.Maven configuration

From the Eclipse IDE main menu, choose Window > Preferences
Enter maven in the filter field in the top-left corner
Navigate to Maven > User Settings and select the User Settings node
If you have already installed Maven before you can click the open file link. If you are using Maven for the first time you need to create a settings.xml file at the location /Users/your-user-name/.m2/settings.xml. The contents of the settings.xml file should look like the snippet below.

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
	<localRepository>${user.home}/.m2/repository</localRepository>
	<profiles>
		<profile>
			<id>development</id>
			<activation>
				<activeByDefault>true</activeByDefault>
			</activation>
			<properties>
			</properties>
		</profile>
	</profiles>
	<proxies>
		<proxy>
			<active>true</active>
			<protocol>http</protocol>
			<host>proxy</host>
			<port>8080</port>
		</proxy>
	</proxies>
</settings>

Note! For most people the proxy value doesn’t need to be set, you can remove the entire proxy section from the snippet, but if you are working behind a proxy, then it should be set as per you environment.

3.Clone Git repository and import Maven project

Open https://github.com/SAP/cloud-espm-v2 with your web browser.
Click on the Copy to clipboard so that the Git repository URL of the opened GitHub repository is copied to your clipboard.

In Eclipse, open the Git perspective. From the Eclipse IDE main menu, choose Window > Open Perspective > Other.... Select Git and choose Ok to open the Git perspective.
In this perspective you have the Git Repositories view on the left. As long as there is no Git Repository defined you will see 3 links (as shown here) to add a repository to the view.

In the corresponding menu (top-right of the view), click on the Clone a Git repository link.
Because you copied before the ESPM repository URL to your clipboard, the fields (URI, Host, Repository path and Protocol) of the opened dialog are filled automatically with the correct values.
Do not change anything, just click Next >.
On this wizard page check that the base branch is selected and click again on Next >.
On the last wizard page you can adjust the location of the local Git Repository, but for the scope of this tutorial we'll just leave the default as-is.
Click on Finish so that the remote ESPM repository (source code) is cloned to the local location specified on the last wizard page.
In Eclipse, open File->Import->Existing Maven projects and import the Maven project.

4.Update dependencies and build Maven project

Instruction to run update dependencies for the Maven project
- Right click on the web project in ESPM > and choose Maven > Click on Update Project
Note! If you face errors you need to modify the parent pom.xml for certain property values depending on your environment:
- local.server.proxy.settings - delete this if you are not behind a proxy server, else update your proxy settings here
- browser.proxy.settings - delete this if your browser is not using a proxy, else update your browser proxy settings here
- sap.cloud.sdk.version - The SAP Business Technology Platform SDK for Java Web Tomcat 8 version that you intend to run the application with,is version 3.20.3.1
- olingo.version - The Apache Olingo version that you intend the application to run with, the minimum version supported is 2.0.6

The application can be built with the maven command to the parent pom.xml

clean install

After building the application update the Maven Project :

Right click on the web project in ESPM > and choose Maven > Click on Update Project

The unit tests and the integration tests are run by default when building the project with goal "clean install"

5.Deploy the application on local Cloud Runtime

i)Run the application in BTP Java Web Tomcat 8 Server

Right click on the web project in ESPM > and choose the Run on Server option

Make sure that Manually define a new server is selected and choose SAP > Java Web Tomcat 8 Server as server type. Leave all other settings unchanged and choose Finish

Now a local server is started that has your espm application deployed.

ii)Create Users and Assign Role

To enable local users to access the Retailer UI, you need to define user IDs in the local user store and assigned the role “Retailer” to this user.

Create a user with the below information
```
      		ID	Name	 Password	Role
      		ret   	ret       123	       Retailer
```

The eCommerce site can be accessed via the URL: https://localhost:<port>/espm-cloud-web/webshop
The Retailer UI can be accessed via the URL: https://localhost:<port>/espm-cloud-web/retailer

6.Deploy the application on SAP BTP via the cockpit

Note! The application name must be "espm", else the above URL will change based on the application name given during deployment

Deploy the application in your SAP Business Technology Platform Trial account.

1.Go to BTP Cockpit --> Click on Java Application under Applications --> Click on Deploy Application

2.Add War File Location, Give Application Name "espm" ,select Runtime Name "Java Web Tomcat 8" and JVM Version "JRE 8"

3.After Successful Deployment , Click on Start

Configure the application role assignments from the cockpit. You basically need to add the "Retailer" role to your SAP Business Technology Platform user to access the Retailer UI

You can access the application from the URL

The eCommerce site can be accessed via the URL: https://espm\<account>.hanatrial.ondemand.com/espm-cloud-web/webshop
The Retailer UI can be accessed via the URL: https://espm\<account>.hanatrial.ondemand.com/espm-cloud-web/retailer

Note! The application name must be "espm", else the above URL will change bsaed on the application name given during deployment

7.Bind the database to espm application and start espm application

Below is the process to bind the database to the java application in BTP trial account using a Shared HANA database

In the cockpit, select an account and choose Persistence -> Databases & Schemas -> in the navigation area.
Click on the new button
In the popup window, fill the mandatory details

In the cockpit, select an account and choose Applications -> Java Application -> Click on the name of the espm application that you deployed
In the navigation area in the cockpit, select Configuration -> Data Source Bindings
Click "New Binding" button in detail plane
In the popup window, fill the mandatory details. Make sure to use "SYSTEM" as the Database user and also uncheck the "Verify credentials" checkbox before saving.

Now you need to restart your espm application ( stop(if already started) and start the application) from the cockpit.

Demo script for ESPM Webshop

Demo script for ESPM Retailer-SalesorderApproval

Demo script for ESPM Retailer-StockUpdate

Documentation for Document Service

Documentation for SAP JAM Integration

2.Deep-dive guide

Architecture Overview

The following diagram provides an overview of the ESPM Sample application architecture:

Reading the above architecture diagram from top to bottom, we have the following components

SAPUI5 layer - All the front-end code of the application is written in SAPUI5. The end user accesses the application using web browser (preferably latest Google Chrome)
OData layer - The ESPM application services are implemented in OData version 2.0. We use Apache Olingo for transforming JPA Models into OData Services. For more information on Apache Olingo JPA Models transformation to OData services, see Details
JPA Layer - The persistence of the application is implemented using Java JPA. We use EclipseLink as the persistence provider
Persistence - The persistence used for the application is SAP HANA DB in Cloud (BTP). All the tables modelled in Java JPA are created in the HANA DB

The ESPM Sample Application is a Maven based project which has a parent pom.xml file and 2 sub projects as below

espm-cloud-jpa - This project contains the source code implementation for the backend/JPA along with unit tests. Below is the JPA Class diagram.
espm-cloud-web - This project contains the source code implementation for generating the odata services for JPA entities implemented in "espm-cloud-jpa" and front end of the application created using SAPUI5. The OData integration tests are also implemented in this package

The JPA Class diagram

ESPM Source Code packages

The espm-cloud-jpa has the following packages:

src/main/java
- com.sap.espm.model - JPA Model classes for persistence
- com.sap.espm.model.data - Data loader classes to populate the master data for the eCommerce site like Product information etc
- com.sap.espm.model.util - The utility classses
src/main/resources
- com.sap.espm.model.data - XML files containing master data for the eCommerce site like Products, Product Categories etc
src/test/java
- com.sap.espm.model - The Unit tests for the database entities
- com.sap.espm.model.util - The test factory class

espm-cloud-web has the following packages:

src/main/java
- com.sap.espm.model.function.impl - The classes for function import implementation for odata services using Apache Olingo
- com.sap.espm.model.web - the Startup servlet and Apache Olingo OData service implementation classes
src/test/java
- com.sap.espm.model.web - The OData integration tests classes
- com.sap.espm.model.web.util - The utility classes for the tests
src/test/resources
- com.sap.espm.model.web - The XML files for the OData Integration tests

The UI is located in webapps folder. The frontend is implemented in SAPUI5.

Securing OData Services

The ESPM application consists of 2 parts - ESPM Webshop and ESPM Retailer. The application is split into 2 parts by a secure URL and non-secure URL.

  Secure URL:
  http://<appname><accountname>.hana.ondemand.com/espm-cloud-web/espm.svc/secure
  
  Non secure URL
  http://<appname><accountname>.hana.ondemand.com/espm-cloud-web/espm.svc/

The WebShop application uses non secure URL as any user without any logon credentials can create a sales order. The Retailer application uses secure URL as only a user with Java EE Web role Retailer can access it. To implement security we use a mix of Java EE Web roles and Servlet Filter

Any access to the secure entity and respective HTTP method via secure url (../espm.svc/secure/)is secured by Java EE Web role Retailer. The form authentication is specified for this Retailer and url-pattern /espm.svc/secure is restricted to this role. This is translated to SAML authentication on deploying in cloud

Any access to secure entity and respective HTTP via non-secure url is restricted by a servlet filter. The servlet filter is defined under the package com.sap.espm.model.web as EspmServiceFactoryFilter class and specified in the web.xml. The logic for restricting access to secure entities via non-secure url is implemented in isPathRestricted()

After deploying the application in BTP, assign the Retailer role to the user who will act as the retailer of the eCommerce site. Please refer to documentation of SAP Business Technology Platform on how to assign roles to users.

Important Disclaimers on Security and Legal Aspects

This document is for informational purposes only. Its content is subject to change without notice, and SAP does not warrant that it is error-free. SAP MAKES NO WARRANTIES, EXPRESS OR IMPLIED, OR OF MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.

Coding Samples

Any software coding and/or code lines / strings ("Code") included in this documentation are only examples and are not intended to be used in a productive system environment. The Code is only intended to better explain and visualize the syntax and phrasing rules of certain coding. SAP does not warrant the correctness and completeness of the Code given herein, and SAP shall not be liable for errors or damages caused by the usage of the Code, unless damages were caused by SAP intentionally or by SAP's gross negligence.

Copyright and License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this work except in compliance with the License. You may obtain a copy of the License in the LICENSE file, or at: http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

SAP-archive/cloud-espm-v2