Skip to Content

The following steps will explain how to include the SAP S/4HANA Cloud SDK in existing Java web application projects.

Note: This post is part of a series. For a complete overview visit the SAP S/4HANA Cloud SDK Overview.

Goal of this blog post

The goal of this post is to show the various options for a developer to include the public libraries to his newly created or already existing project.

  1. Software requirements and recommendations
  2. Best practice for enabling SAP S/4HANA Cloud SDK
  3. Head start with Maven archetypes
  4. Library functionalities and software artifacts
  5. Example: Spring Boot

This blog post exists as part of general help articles outside of the continuous course starting from  Step 1 (Setup). We highly recommend following this series in order to understand feature scope and expected usability of the SAP S/4HANA Cloud SDK.

 

Software requirements and recommendations

The compiled libraries of SAP S/4HANA Cloud SDK are publicly available and can be used in any Java web application which uses the Java Servlet API. The following properties may be applicable to your software project.

Required:

  • Java Runtime version 1.7+
  • Maven, Java dependency management tool to easily include SAP S/4Hana Cloud SDK artifacts. It dynamically downloads any required Java libraries to realize the build process.

Recommended:

  • Multi module project setup for your software, to ensure a consistent application development structure.
  • Supported Servlet 3.0 API to have all features activated automatically during application startup. It enables the web application to be configured by Java annotations.

Best practice

The SAP S/4HANA Cloud SDK provides an extensive set of tools to enable, organize and secure the communication between your web application and your ERP system. These tools are publicly provided as Maven artifacts.

How to start

  • Add an entry to your dependencyManagement of your application POM. In case you have a multi-module Maven setup in place, please consider adding this to the parent module. This way inconsistencies and redundancies in your software can be avoided.
    <project>
        ...
        <dependencyManagement>
            <dependencies>
    
                <!-- S/4HANA Cloud SDK dependencies import -->
                <dependency>
                    <groupId>com.sap.cloud.s4hana</groupId>
                    <artifactId>sdk-bom</artifactId>
                    <version>1.1.2</version>
                    <type>pom</type>
                    <scope>import</scope>
                </dependency>
    
            </dependencies>
        </dependencyManagement>
        ...
    </project>​

    Now you can easily include any dependency of the SAP S/4HANA Cloud SDK to your respective Maven module. Please notice the version concrete version number. Specifying a dependency version is highly recommended, because using anything else (e.g. LATEST) could bring incompatibilities sometime in the future.

  • Depending on your target deployment platform, you can choose between CloudFoundry (scp-cf) and Neo (scp-neo). Since you added the dependency import previously, you can omit any further version declaration of the SAP S/4HANA Cloud SDK. Notice the different artifact identifier on the first dependency each:
    • CloudFoundry (scp-cf)
      <project>
          ...
          <dependencies>
      
              <!-- SAP S/4HANA Cloud SDK dependencies for CloudFoundry -->
              <dependency>
                  <groupId>com.sap.cloud.s4hana.cloudplatform</groupId>
                  <artifactId>scp-cf</artifactId>
              </dependency>
              <dependency>
                  <groupId>com.sap.cloud.s4hana</groupId>
                  <artifactId>s4hana-all</artifactId>
              </dependency>
      
              ...
          </dependencies>
          ...
      </project>
      ​
    • Neo (scp-neo)
      <project>
          ...
          <dependencies>
      
              <!-- SAP S/4HANA Cloud SDK dependencies for Neo -->
              <dependency>
                  <groupId>com.sap.cloud.s4hana.cloudplatform</groupId>
                  <artifactId>scp-neo</artifactId>
              </dependency>
              <dependency>
                  <groupId>com.sap.cloud.s4hana</groupId>
                  <artifactId>s4hana-all</artifactId>
              </dependency>
      
              ...
          </dependencies>
          ...
      </project>​

Unit tests and integration tests

For testing an application, the SAP S/4HANA Cloud SDK provides a test utility, which enables you to access real and mocked ERP systems. The recommended way is to have one or more dedicated modules for unit tests and integration tests.

  • Each can have the following dependencies attached:
    <project>
        ...
        <dependencies>
    
            <!-- SAP S/4HANA Cloud SDK Testing dependencies -->
            <dependency>
                <groupId>com.sap.cloud.s4hana</groupId>
                <artifactId>testutil</artifactId>
                <scope>test</scope>
            </dependency>
            <dependency>
                <groupId>com.sap.cloud.s4hana.quality</groupId>
                <artifactId>listeners-all</artifactId>
                <scope>test</scope>
            </dependency>
            ...
        </dependencies>
        ...
    </project>​

You can find more about automated testing in the respective blog post: Automated Testing.

 

Head start with Maven archetypes

Boost your project building process with Maven archetypes!

When you consider starting a new project or migrating an already existing one, please find the SAP S/4HANA Cloud SDK archetypes. With these you can easily create a new Maven project and migrate your existing files to a functional environment. Currently there are four supported archetypes for different runtimes; three of them with a well-established CloudFoundry support.

They all feature advanced testing setups for unit tests and integration tests, as well as code quality checks. Also a build pipeline is provided for continuous integration and delivery. And for debugging and deploying all required options are prepared.

 

Spring Boot

In case your application is or will be based on Spring Boot, we highly recommend using the dedicated Spring archetype which has already been prepared for SAP S/4HANA Cloud SDK. In an empty location run the following command:

mvn archetype:generate -DarchetypeGroupId=com.sap.cloud.s4hana.archetypes -DarchetypeArtifactId=scp-cf-spring -DarchetypeVersion=LATEST

You will be asked for groupId, artifactId, package and uniqueHostname. The last one represents a unique identifier to determine your initial project URL on CloudFoundry. It can be easily changed later. The project stub which is generated from the archetype contains the ideal project architecture with most of Cloud SDK features already in place. It is a quick start to a deployable web application.

  • Easy debugging, e.g. with executing main()
  • Run application locally with mvn spring-boot:run
  • Run packaged application anywhere with java -jar

 

Apache Tomee

If your application requires a Java Enterprise Edition of Apache Tomcat, you can use the following archetype:

mvn archetype:generate -DarchetypeGroupId=com.sap.cloud.s4hana.archetypes -DarchetypeArtifactId=scp-cf-tomee -DarchetypeVersion=LATEST
  • Run application locally with mvn package tomee:run
  • Debug with remote debugging to localhost

This archetype has already been introduced in the blog post for Hello World on SCP CloudFoundry.

 

Apache Tomcat

Probably the most popular application, to run Servlet based application, is Tomcat. You can create a new project stub with Tomcat support by running the following command:

mvn archetype:generate -DarchetypeGroupId=com.sap.cloud.s4hana.archetypes -DarchetypeArtifactId=scp-cf-tomcat -DarchetypeVersion=LATEST
  • Run application locally with mvn jetty:run
  • Debug with remote debugging to localhost

 

Java EE6

If your target application platform is Neo, then you would need to create the software stub with the following archetype:

mvn archetype:generate -DarchetypeGroupId=com.sap.cloud.s4hana.archetypes -DarchetypeArtifactId=scp-neo-javaee6 -DarchetypeVersion=LATEST
  • Deploy and run application locally with mvn package scp:push
  • Stop local application with mvn clean scp:clean
  • Debug with remote debugging to localhost

This archetype has already been introduced in the blog post for Hello World on SCP Neo.

 

Functionality and library artifacts

The functionality of SAP S/4HANA Cloud SDK is provided by Maven artifacts. By specifying dependencies in your application, you can take advantage of most of its features. When including “s4hana-all” like shown before, you already have them attached. Most of the feature bearing artifacts are distributed by the following Maven artifacts:

Feature Description Maven Group ID Maven Artifact ID
S/4HANA Bundle of all S/4HANA modules, including OData V2 connectivity, can be used on both Neo and Cloud Foundry com.sap.cloud.s4hana s4hana-all
S/4HANA – Core Basic functionality for S/4HANA such as data types and serialization com.sap.cloud.s4hana core
S/4HANA – Connectivity Establish and manage connection to S/4HANA using customer-supplied information via Cloud Platform abstractions. Includes security, caching, resilience. com.sap.cloud.s4hana connectivity
S/4HANA – Data Model Typed data model of OData and BAPI services (as exposed by S/4HANA Cloud), allows easy access via a fluent business object-oriented API. com.sap.cloud.s4hana datamodel
S/4HANA – Fluent Result API Fluent interface for handling various types of query results, including type conversion components. com.sap.cloud.s4hana fluent-result
S/4HANA – RFC Queries Call BAPIs / RFMs in S/4HANA easily with a high level of abstraction. com.sap.cloud.s4hana rfc
S/4HANA – Test Utilities Utility classes for testing ERP-related functionality, also for easy mocking of Cloud Platform entities in general. com.sap.cloud.s4hana testutil

Please notice, that s4hana-all includes all the other artifacts from the table, except for testutil. The test utility should only be added to testing modules and environments. To enable the S/4HANA communication, please remember to also include either scp-cf or scp-neo from group com.sap.cloud.s4hana.cloudplatform.

 

Project examples

If your software already relies on a set of dependency imports, it becomes important to structure the import order accordingly. The entries are enumerated with decreasing priority. Please find the example for a parent POM below:

<project>
    ...
    <dependencyManagement>
        <dependencies>
            <!-- dependency artifacts with enforced version -->
            <!-- ... --->

            <!-- original dependencies import -->
            <!-- ... --->

            <!-- S/4HANA Cloud SDK dependencies import -->
            <dependency>
                <groupId>com.sap.cloud.s4hana</groupId>
                <artifactId>sdk-bom</artifactId>
                <version>1.1.2</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>

        </dependencies>
    </dependencyManagement>
    ...
</project>

As you can see, the original dependency versions given by your application will be in favor of the ones given by SAP S/4HANA Cloud SDK. To solve a potential Maven dependency conflict, you can also specify a preferred version above. This will enforce specific version numbers, if none are provided.

 

Spring Boot

If your software is built with the Spring Boot framework, make sure to also have the dependency spring-boot-starter-web included. Otherwise the required ServletContext will not be accessible internally. You can find a sophisticated Spring Boot example in our public repository: The Costcenter Controller for CloudFoundry. It follows our best practice principles.

The first thing to do, is to include the dependencyManagement entry to your Maven root POM just like it was showed above. Now it could look like this:

<project>
    ...
    <dependencyManagement>
        <dependencies>
            <!-- Newer versions to meet S/4HANA Cloud SDK requirements. -->
            <!-- Required for Spring Boot version earlier than 2.0.0 -->
            <dependency>
                <groupId>org.json</groupId>
                <artifactId>json</artifactId>
                <version>20170516</version>
            </dependency>
            <dependency>
                <groupId>org.mockito</groupId>
                <artifactId>mockito-core</artifactId>
                <version>2.10.0</version>
            </dependency>

            <!-- (Optional) if Spring Boot dependencies are missing -->
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-dependencies</artifactId>
                <version>1.5.7.RELEASE</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>

            <!-- S/4HANA Cloud SDK dependencies -->
            <dependency>
                <groupId>com.sap.cloud.s4hana</groupId>
                <artifactId>sdk-bom</artifactId>
                <version>1.1.2</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement> 
    ...
</project>

A dependency version will be determined by the priority, the order in which dependency imports are enumerated. Here the dependency versions of Spring Boot will be preferred to the ones of the SAP S/4HANA Cloud SDK. The only exceptions are two dependencies listed above, they fix version conflicts.

Spring Initializr

In case you are using the Spring Initializr, do not forget adding “Web” as dependency. This ensures having the required dependency in your web application:

 

If you have used the Spring initializr, you were given a very basic project stub. It is a single Maven module with a “starter-parent” definition in the top. Although this is not the recommended software architecture, it is an easy and straight forward starting point. Now with the additions discussed before, the single POM file could look like this:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<groupId>com.example</groupId>
	<artifactId>demo</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<packaging>jar</packaging>
	<name>demo</name>
	<description>Demo project for Spring Boot</description>

	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>1.5.7.RELEASE</version>
		<relativePath/> <!-- lookup parent from repository -->
	</parent>

	<properties>
		<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
		<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
		<java.version>1.7</java.version>
	</properties>

	<dependencyManagement>
		<dependencies>
			<dependency>
				<groupId>com.sap.cloud.s4hana</groupId>
				<artifactId>sdk-bom</artifactId>
				<version>1.1.2</version>
				<type>pom</type>
				<scope>import</scope>
			</dependency>
		</dependencies>
	</dependencyManagement>

	<dependencies>
		<!-- Newer versions to meet S/4HANA Cloud SDK requirements. -->
		<!-- Required for Spring Boot version earlier than 2.0.0 -->
		<dependency>
			<groupId>org.json</groupId>
			<artifactId>json</artifactId>
			<version>20170516</version>
		</dependency>

		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter</artifactId>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>

		<!-- SAP S/4HANA Cloud SDK dependencies for CloudFoundry -->
		<dependency>
			<groupId>com.sap.cloud.s4hana.cloudplatform</groupId>
			<artifactId>scp-cf</artifactId>
		</dependency>
		<dependency>
			<groupId>com.sap.cloud.s4hana</groupId>
			<artifactId>s4hana-all</artifactId>
		</dependency>
		<dependency>
			<groupId>com.sap.cloud.s4hana</groupId>
			<artifactId>datamodel</artifactId>
		</dependency>

		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-test</artifactId>
			<scope>test</scope>
		</dependency>

		<!-- SAP S/4HANA Cloud SDK Testing dependencies -->
		<dependency>
			<groupId>com.sap.cloud.s4hana</groupId>
			<artifactId>testutil</artifactId>
			<scope>test</scope>
		</dependency>
		<dependency>
			<groupId>com.sap.cloud.s4hana.quality</groupId>
			<artifactId>listeners-all</artifactId>
			<scope>test</scope>
		</dependency>
	</dependencies>
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
			</plugin>
		</plugins>
	</build>
</project>

 

Stay tuned for further updates and integration examples.

To report this post you need to login first.

Be the first to leave a comment

You must be Logged on to comment or reply to a post.

Leave a Reply