Description
Create the Address Manager application using the Spring framework. Run it connected to the SAP API Business Hub sandbox, connect it to an SAP S/4HANA Cloud system, deploy it to Cloud Foundry, and then finally create a Destination service and use it to connect the application to the back-end.
Information for execution
The application reads the following environment variables, such variables need to be properly set for the application to interact with the back-end service:
Variable | Content |
---|---|
S4_DESTINATION | The name of the destination defined within the Destination service of Cloud Foundry. Use it when running in Cloud Foundry. |
S4_URL | The URL of the backend ERP system. Use it when running locally. |
S4_USERNAME | The user name to access the backend ERP system. Use it when running locally. |
S4_PASSWORD | The user name to access the backend ERP system. Use it when running locally. |
S4_APIKEY | Your API Key identifier, required to access the SAP API Business Hub. You can get your apikey at https://api.sap.com . |
Two authentication methods are possible. Based on the method, you will provide the corresponding environment variables:
- Basic user and password authentication: used by the S/4HANA Cloud system.
- No Authentication plus API key: used by the SAP API Business Hub Sandbox system.
Prerequisites
For the complete execution of current exercise, you must execute the following activities first:
- Execute the following exercises:
- Creating your Pay-As-You-Go Account in SAP BTP
- Activating the APIs in SAP S/4HANA Cloud: this exercise activates the required API in the S/4HANA Cloud tenant.
Open SAP Business Application Studio and clone the course GitHub repository (in case this was already done in a previous exercise, you can skip this step):
Use the following URL:
Information Value GitHub repository URL https://github.com/SAP-samples/cloud-sdk-learning-journey.git To clone, close any open folder, then open a Terminal (Terminal → New Terminal) and run the following commands:
Code snippetExpandcd ~/projects git clone https://github.com/SAP-samples/cloud-sdk-learning-journey.git
- Open the project folder
~/projects/cloud-sdk-learning-journey
(use File → Open Folder).
Task 1: Creating the Spring Boot Development Project
Steps
Create, build and run the initial HelloWorld application, based on the scp-cf-spring maven archetype.
Checkout the initial Git branch
javadman_v1.0_hello
. To do this, open a Terminal and run the following commands:Note
The code in this Git branch is a pre-generated version of the code you get using the maven template.
You can generate the same code directly from the template, just delete the
java-adman-spring
folder, then run the following command:Code snippetExpandmvn archetype:generate "-DarchetypeGroupId=com.sap.cloud.sdk.archetypes" "-DarchetypeArtifactId=scp-cf-spring" "-DarchetypeVersion=RELEASE" "-DgroupId=com.example" "-DartifactId=java-adman-spring" "-Dversion=1.0-SNAPSHOT"
To build and run the application, execute the following commands:
The Welcome screen of SAP Cloud SDK appears in a separate tab. Click on the HelloWorldController link to get
{"hello":"world"}
.Back to the Terminal, choose Ctrl+C to stop the program.
Build and run the application.
In the terminal (Terminal → New Terminal), execute the following commands:
Code snippetExpandcd ~/projects/cloud-sdk-learning-journey/java-adman-spring mvn clean install -U cd application mvn spring-boot:run
Wait until the Tomcat server starts. After a few seconds a pop-up window appears with the following message:
A service is listening to port 8080.
Choose Expose and Open, then press enter. The Welcome application is opened.Return to the terminal, choose Ctrl+C to stop the Tomcat server.
Review the project content.
Open
java-adman-spring/application/src/main/java/com/example/
and review the project files in the sub-folders.The
HelloWorldController
listens in the context of/hello
for incoming HTTP requests. When aGET
request is sent to this resource, it logs the string'I am running'
and returns a response based on the HelloWorldResponse class. As expected in Spring programming, the Model-View-Controller pattern is applied, so the controller object is separated from the model one.Open the
java-adman-spring/application/src/main/resources/static/index.html
file and review the code.The index file that we see here helps us to validate a fresh deployment of our app. It welcomes every visitor who sends a request to our application base URL with a generic landing page.
Open the
java-adman-spring/application/src/test/java/com/example/UnitTest.java
file and review the code.We use the unit-tests module for tests that ensure the functional correctness of small functional units of our application, typically on Java API level.
Open the
java-adman-spring/integration-tests/src/test/java/com/example/HelloWorldControllerTest.java
file and review the code.The integration test module holds tests that typically test multiple parts of the application and their interplay. These tests are often written on the level of HTTP requests and expected responses.
Open the
manifest.yml
file and review the code.The
manifest.yml
file is used to tell the Cloud foundry environment which resources our application needs to run. This is interpreted by Cloud Foundry when deploying the application. The following figure shows an example of the memory requirements, environment variable definitions, and instances of platform services that should be bound to our app.
Run the application in debug mode. Set a breakpoint in the
HelloWorldController.java
file at line26
. Open the application in the browser and verify that the execution stops at the breakpoint. Continue the execution to the end. Remove the breakpoint. Stop the application.Open the
application/src/main/java/com/example/Application.java
file.Choose the small Debug command that appears just before the
Main()
method definition.Once the application has started, a pop up window appears stating
A service is listening to port 8080.
Choose Open in New Tab. A new tab is opened showing the application welcome screen.Open the
application/src/main/java/com/example/controllers/HelloWorldController.java
file. Create a breakpoint by selecting aside line number 26. A red dot appears beside the number.In the welcome screen, choose HelloWorldController. The controller runs and the execution stops in the debugger at the breakpoint.
In the Debugger, choose Continue(in the Debug page).
hello: "world"
appears in the application page.In the
HelloWorldController.java
, click on the red dot to remove the breakpoint.Choose Stop.
Deploy the application to Cloud Foundry.
Choose Terminal → New Terminal. A terminal window appears in the lower part of the screen.
If required, login to the Cloud Foundry CLI by executing the following commands
Enter your SAP BTP API endpoint, e-mail and password.In the terminal, make sure you are in the project root folder, then run the following command:
Look for the running application in the SAP BTP Cockpit and open it.
In a web browser, open your SAP BTP Cockpit based on the url you received at subscription time (for example: https://cockpit.eu20.hana.ondemand.com. If required, enter your e-mail and password.
In the SAP BTP Cockpit, navigate to the training Subaccount. Navigate to the dev space.
Choose the java-adman-spring application name.
Choose the Application Route. The application opens in the Welcome page.
In SAP Business Application Studio, create a debug configuration to attach the remote Java application in Cloud Foundry.
Choose Run → Add Configuration... The
launch.json
file is opened.Replace the full content of the file with the following:
Code snippetExpand{ "version": "0.2.0", "configurations": [ { "type": "java", "name": "Launch Application", "request": "launch", "mainClass": "com.example.Application", "projectName": "java-adman-spring-application" }, { "type": "java", "name": "Attach Application", "request": "attach", "hostName": "localhost", "port": 5005, "sourcePaths": [ "${workspaceFolder}" ] } ] }
Attach the debugger of SAP Business Application Studio to the remote application running in Cloud Foundry.
Open a terminal, make sure that the current directory is the project root folder.
To enable the remote application for debug, execute the following commands:
Ignore eventual messages proposing you to expose port 5005.Code snippetExpandcf set-env java-adman-spring JBP_CONFIG_JAVA_OPTS "[java_opts: '-Xdebug -Xrunjdwp:server=y,transport=dt_socket,address=8000,suspend=n']" cf enable-ssh java-adman-spring cf restage java-adman-spring cf ssh -N -T -L 5005:localhost:8000 java-adman-spring
In SAP Business Application Studio, in the Debug tab, run the Attach Application configuration. The debugger attaches to the remote application.
Set a breakpoint in the
HelloWorldController.java
file at line26
. Open the application in the browser and verify that the execution stops at the breakpoint. Continue the execution to the end. Remove the breakpoint. Stop the application.Open the
application/src/main/java/com/example/controllers/HelloWorldController.java
file. Create a breakpoint by selecting aside line number 26. A red dot appears beside the number.Open the Web browser in the SAP BTP Cockpit at the welcome page of the java-adman-spring application you just deployed.
In the welcome screen, choose
HelloWorldController
. The controller runs and the execution stops in the debugger, at the breakpoint (switch back to SAP Business Application Studio).In the Debugger, choose Continue.
hello: 'world'
appears in the browser.In the
HelloWorldController.java
, click on the red dot to remove the breakpoint.Disconnect the debugger.
In the Terminal, chooseCtrl+C to interrupt the
cf ssh
command.
Task 2: Create the Address Manager Application
Steps
Starting from the existing project, create an Address Manager application that maintains the SAP S/4HANA Cloud business partners address information. The application is provided in the exercise files, and includes the following parts:
Checkout the initial Git branch
javadman_v2.0_crud
. To do this, open a Terminal and run the following commands:
Build, run the application and open the Address Manager page.
In the terminal run the following command:
The application project is built including the latest changes.Edit the
.vscode/launch.json
file. Replace >>>YOUR API KEY<<< with your API Key. To get your API Key, open https://api.sap.com/api/API_BUSINESS_PARTNER, then log on, and choose Show API Key.Go to the Debug tab, select the Launch Application - sandbox configuration, choose Start Debugging. After a few seconds a pop-up window advises you that
A service is listening to port 8080.
Choose Open in New Tab. The application is opened. Click on the Address Manager link.
The SAP API Business hub sandbox is accessible in read-only mode, so you cannot modify addresses here.Close the application window, stop the running application.
Log on to your SAP S/4HANA Cloud tenant.
In the Web browser (for example, Google Chrome), on your SAP S/4HANA Cloud tenant, access the SAP Fiori Launchpad at
[S/4HANA tenant url]/ui
, for example (https://my000000.s4hana.ondemand.com/ui
). If requested, enter your user and password.
In SAP S/4HANA Cloud, if it is not yet assigned, assign role BR_BUPA_MASTER_SPECIALIST to your user.
In the Home page, choose Search and search for the Maintain Business Users app.
In the app, search for your user and display its details by selecting the line of the list.
In the user detail screen, scroll down and check the Assigned Business Roles section.
If BR_BUPA_MASTER_SPECIALIST is missing from the list, choose Add, search for the BR_BUPA_MASTER_SPECIALIST role, select the box beside it, choose OK, and choose Save.
Select the SAP logo to navigate back to the Home page.
Refresh the Web browser page to see the additional apps provided with the new role.
In SAP S/4HANA Cloud, in the Manage Business Partner Master Data app, create a new business partner based on the following information (replace ### with your user number) if it doesn't already exist:
Field Value Grouping Internal numbering for standard use BP Role CRM000 Sold-to-party First Name John Last Name Doe ### City New York Country US Language EN In the home page, search for and open the Manage Business Partner Master Data app.
Choose Create → Person.
In the Create Person dialog, enter the information provided in the table.
Choose OK
Choose Create.
Select the SAP logo to navigate back to the Home page.
Run the application against your SAP S/4HANA Cloud tenant. Use the following environment variables to configure the connection information (replace ### with your user number):
Name Value S4_URL Your S/4HANA Client tenant URL, for example https://my000000.s4hana.ondemand.com S4_USERNAME ADDRESS_MANAGER_### S4_PASSWORD WelcomeToTheClouds1! Note
As a prerequisite, for this API to be accessible in the S/4HANA Cloud tenant, you need to execute the previous exercise: Activating the APIs in SAP S/4HANA Cloud.Edit the
.vscode/launch.json
file.In the Launch Application - s4cloud configuration, assign proper values to URL, User and Password.
Go to the Debug tab, select the Launch Application - s4cloud configuration, choose Start Debugging. After a few seconds a pop-up window displays the following:
A service is listening to port 8080.
Choose Open in New Tab. The application is opened. Click on the Address Manager link.
The Address Manager application is opened in read-write mode. Search your John Doe ### business partner and add a new address to it.
Note
If the search feature doesn't work, try to access the business partner using the following suffix in the application URL:Replace 1000000 with your business partner ID.Stop the application.
Deploy the application to Cloud Foundry.
Choose Terminal → New Terminal. A terminal window appears in the lower part of the screen.
if Cloud Foundry CLI login is required, execute the following commands
Enter your SAP BTP API endpoint, e-mail, and password.In the Terminal, run the following commands:
At the end of the deployment process, you will get a text such as the following:Code snippetExpandcd ~/projects/cloud-sdk-learning-journey/java-adman-spring mvn clean install -U cf push
Code snippetExpandstate since cpu memory disk details #0 running 2020-04-24T17:25:03Z 66.4% 167.5M of 1G 152.4M of 1G
In the SAP BTP Cockpit, in the application, configure the environment variables to run against the SAP API Business Hub Sandbox, then open the application.
In your Web browser (for example, Google Chrome), open your SAP BTP Cockpit based on the link you received at subscription time (for example: https://cockpit.eu20.hana.ondemand.com). If requested, enter your user and password.
Choose the training subaccount, that you created in a previous exercise.
Navigate to the dev space.
Choose the java-adman-spring application name.
In the Application: java-adman-spring - Overview page, go to the User-Provided Variables tab. Add the following variables (replace >>>YOUR API KEY<<< with your own API Key, for example
FDqbnElM7mgmgqbIKBFHRpS1dvpt6sHD
.To get your API Key, open https://api.sap.com/api/API_BUSINESS_PARTNER, then log on, and choose Show API Key):
Key Value S4_URL https://sandbox.api.sap.com/s4hanacloud/ S4_APIKEY >>>YOUR API KEY<<< Go to the Overview tab.
Restart the application.
Choose the Application Route. The application opens in the Welcome page.
Add
/address-manager/index.html
at the end of the browser URL. The Address Manager application is opened, reading the data from the SAP API Business Hub Sandbox system.
In Cloud Foundry, create an instance of the Destination service named my-destinations if it doesn't exist already.
In the SAP BTP Cockpit, navigate to the trial subaccount, then to the dev space.
In the dev space, navigate to Services → Instances tab.
In the Space:dev - Service Instances screen, Choose Create. Create a new instance based on the following information:
Field Value Service Destination Service Service Plan lite Instance Name my-destinations
Bind the my-destinations service to the java-adman-spring application.
In the SAP BTP Cockpit, navigate to the dev space, then to the java-adman-spring application.
In the Application: java-adman-spring - Overview page, go to the Service Bindings page.
Choose Bind Service.
Select Service from the catalog. Choose Next.
Choose the Destination service. Choose Next.
Choose the Re-use existing instance. Select the my-destinations Instance. Choose Next.
Choose Finish.
In the my-destinations service, in case it doesn't already exist, create a destination named sandbox, referring to the SAP API Business Hub Sandbox.
Return to the main page of the dev space, navigate to Services → Instances page. Choose the my-destinations instance. Click on Manage Instance
Choose the Destinations page.
Chose New Destination create a destination based on the following information:
Field Value Name sandbox Type HTTP Description SAP API Business Hub sandbox system URL https://sandbox.api.sap.com/s4hanacloud Proxy Type Internet Authentication NoAuthentication
Adapt the environment variables of your application so that it reads the system information from the Destination Service. Restart and open the application again.
Navigate to the dev space, then to your application, then to the User-Provided Variables tab.
Delete the S4_URL variable.
Enter a new variable with the S4_DESTINATION name and sandbox value .
Go to the Overview page.
Restart the application.
Choose the Application Route. The application opens.
Choose the Address Manager link. The Address Manager application is opened, reading the data from the SAP API Business Hub Sandbox system, configured via the sandbox destination in the my-destinations service.
In the my-destinations service, create a destination named s4cloud, referring to your SAP S/4HANA Cloud tenant if it doesn't already exist.
Return to the main page of the dev space, navigate to Services → Instances page. Choose the my-destinations instance. Click on Manage Instance
Choose the Destinations view.
Chose New Destination create a destination based on the following information (replace ### with your user number, replace the URL value with your own SAP S/4HANA Cloud tenant URL):
Field Value Name s4cloud Type HTTP Description SAP S/4HANA Cloud tenant URL Your S/4HANA Client tenant URL, for example https://my000000.s4hana.ondemand.com Proxy Type Internet Authentication BasicAuthentication User ADDRESS_MANAGER_### Password WelcomeToTheClouds1!
Adapt the environment variables of your application so that it reads the s4cloud system information from the Destination service. Restart and open the application again.
Navigate to the dev space, then to your application, then to the User-Provided Variables tab.
Change the value of the S4_DESTINATION variable to s4cloud.
Optionally, delete the S4_APIKEY variable.
Go to the Overview tab.
Restart the application.
Choose Application Route. The application opens
Choose the Address Manager link
The Address Manager application is opened, reading the data from your SAP S/4HANA Cloud tenant, configured via the s4cloud destination in the my-destinations service. Search your John Doe ### business partner and add a new address to it.