Exercise: Building a BP Address Manager Extension Using Java

Create, build and run the initial HelloWorld application, based on the scp-cf-spring maven archetype.

1. Checkout the initial Git branch javadman_v1.0_hello. To do this, open a Terminal and run the following commands:

   Code snippet

   Copy code

   cd ~/projects/cloud-sdk-learning-journey
   git checkout -f javadman_v1.0_hello

   Expand

   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 snippet

   Copy code

   mvn 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"

   Expand

2. To build and run the application, execute the following commands:

   Code snippet

   Copy code

   cd java-adman-spring
   mvn clean install
   cd application
   mvn spring-boot:run

   Expand

3. The Welcome screen of SAP Cloud SDK appears in a separate tab. Click on the HelloWorldController link to get {"hello":"world"}.

4. Back to the Terminal, choose Ctrl+C to stop the program.

Build and run the application.

1. In the terminal (Terminal → New Terminal), execute the following commands:

   Code snippet

   Copy code

   cd ~/projects/cloud-sdk-learning-journey/java-adman-spring
   mvn clean install -U
   cd application
   mvn spring-boot:run

   Expand

   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.

2. Return to the terminal, choose Ctrl+C to stop the Tomcat server.

Review the project content.

1. 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 a GET 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.

2. 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.

3. 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.

4. 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.

5. 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 line 26. 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.

1. Open the application/src/main/java/com/example/Application.java file.

2. Choose the small Debug command that appears just before the Main() method definition.

3. 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.

4. 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.

5. In the welcome screen, choose HelloWorldController. The controller runs and the execution stops in the debugger at the breakpoint.

6. In the Debugger, choose Continue(in the Debug page). hello: "world" appears in the application page.

7. In the HelloWorldController.java, click on the red dot to remove the breakpoint.

8. Choose Stop.

Deploy the application to Cloud Foundry.

1. Choose Terminal → New Terminal. A terminal window appears in the lower part of the screen.

2. If required, login to the Cloud Foundry CLI by executing the following commands

   Code snippet

   Copy code

   cf login
   

   Expand

   Enter your SAP BTP API endpoint, e-mail and password.

3. In the terminal, make sure you are in the project root folder, then run the following command:

   Code snippet

   Copy code

   cd ~/projects/cloud-sdk-learning-journey/java-adman-spring
   cf push

   Expand

   At the end of the deployment process, you will get a text, such as the following:

   Code snippet

   Copy code

        state     since                  cpu     memory         disk           details
   #0   running   2020-04-24T17:25:03Z   66.4%   167.5M of 1G   152.4M of 1G

   Expand

Look for the running application in the SAP BTP Cockpit and open it.

1. 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.

2. In the SAP BTP Cockpit, navigate to the training Subaccount. Navigate to the dev space.

3. Choose the java-adman-spring application name.

4. 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.

1. Choose Run → Add Configuration... The launch.json file is opened.

2. Replace the full content of the file with the following:

   Code snippet

   Copy code

   {
       "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}" ] 
           } 
       ]
   }

   Expand

Attach the debugger of SAP Business Application Studio to the remote application running in Cloud Foundry.

1. Open a terminal, make sure that the current directory is the project root folder.

2. To enable the remote application for debug, execute the following commands:

   Code snippet

   Copy code

   cf 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

   Expand

   Ignore eventual messages proposing you to expose port 5005.

3. 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 line 26. 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.

1. 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.

2. Open the Web browser in the SAP BTP Cockpit at the welcome page of the java-adman-spring application you just deployed.

3. 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).

4. In the Debugger, choose Continue. hello: 'world' appears in the browser.

5. In the HelloWorldController.java, click on the red dot to remove the breakpoint.

6. Disconnect the debugger.

7. In the Terminal, chooseCtrl+C to interrupt the cf ssh command.

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:

1. Checkout the initial Git branch javadman_v2.0_crud. To do this, open a Terminal and run the following commands:

   Code snippet

   Copy code

   cd ~/projects/cloud-sdk-learning-journey
   git checkout -f javadman_v2.0_crud

   Expand

Build, run the application and open the Address Manager page.

1. In the terminal run the following command:

   Code snippet

   Copy code

   cd java-adman-spring
   mvn clean install -U

   Expand

   The application project is built including the latest changes.

2. 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.

3. 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.

4. 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.

5. Close the application window, stop the running application.

Log on to your SAP S/4HANA Cloud tenant.

1. 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.

1. In the Home page, choose Search and search for the Maintain Business Users app.

2. In the app, search for your user and display its details by selecting the line of the list.

3. In the user detail screen, scroll down and check the Assigned Business Roles section.

4. 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.

5. Select the SAP logo to navigate back to the Home page.

6. 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:

1. In the home page, search for and open the Manage Business Partner Master Data app.

2. Choose Create → Person.

3. In the Create Person dialog, enter the information provided in the table.

4. Choose OK

5. Choose Create.

6. 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.

1. Edit the .vscode/launch.json file.

2. In the Launch Application - s4cloud configuration, assign proper values to URL, User and Password.

3. 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.

4. Choose Open in New Tab. The application is opened. Click on the Address Manager link.

5. 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:

   Code snippet

   Copy code

   /address-manager/index.html#/businessPartners/1000000

   Expand

   Replace 1000000 with your business partner ID.

6. Stop the application.

Deploy the application to Cloud Foundry.

1. Choose Terminal → New Terminal. A terminal window appears in the lower part of the screen.

2. if Cloud Foundry CLI login is required, execute the following commands

   Code snippet

   Copy code

   cf login
   

   Expand

   Enter your SAP BTP API endpoint, e-mail, and password.

3. In the Terminal, run the following commands:

   Code snippet

   Copy code

   cd ~/projects/cloud-sdk-learning-journey/java-adman-spring
   mvn clean install -U
   cf push

   Expand

   At the end of the deployment process, you will get a text such as the following:

   Code snippet

   Copy code

        state     since                  cpu     memory         disk           details
   #0   running   2020-04-24T17:25:03Z   66.4%   167.5M of 1G   152.4M of 1G

   Expand

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.

1. 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.

2. Choose the training subaccount, that you created in a previous exercise.

3. Navigate to the dev space.

4. Choose the java-adman-spring application name.

5. 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.

6. 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<<<

7. Go to the Overview tab.

8. Restart the application.

9. Choose the Application Route. The application opens in the Welcome page.

10. 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.

1. In the SAP BTP Cockpit, navigate to the trial subaccount, then to the dev space.

2. In the dev space, navigate to Services → Instances tab.

3. 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.

1. In the SAP BTP Cockpit, navigate to the dev space, then to the java-adman-spring application.

2. In the Application: java-adman-spring - Overview page, go to the Service Bindings page.

3. Choose Bind Service.

4. Select Service from the catalog. Choose Next.

5. Choose the Destination service. Choose Next.

6. Choose the Re-use existing instance. Select the my-destinations Instance. Choose Next.

7. 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.

1. Return to the main page of the dev space, navigate to Services → Instances page. Choose the my-destinations instance. Click on Manage Instance

2. Choose the Destinations page.

3. 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.

1. Navigate to the dev space, then to your application, then to the User-Provided Variables tab.

2. Delete the S4_URL variable.

3. Enter a new variable with the S4_DESTINATION name and sandbox value .

4. Go to the Overview page.

5. Restart the application.

6. Choose the Application Route. The application opens.

7. 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.

1. Return to the main page of the dev space, navigate to Services → Instances page. Choose the my-destinations instance. Click on Manage Instance

2. Choose the Destinations view.

3. 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.

1. Navigate to the dev space, then to your application, then to the User-Provided Variables tab.

2. Change the value of the S4_DESTINATION variable to s4cloud.

   Optionally, delete the S4_APIKEY variable.

3. Go to the Overview tab.

4. Restart the application.

5. Choose Application Route. The application opens

6. Choose the Address Manager link

7. 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.