Exercise: Building a BP Address Manager Extension Using Java

Objectives
After completing this lesson, you will be able to:

After completing this lesson, you will be able to:

  • Using the Java language and the Spring framework, build a Business Partner address manager extension application

Building a BP Address Manager extension using Java and the Spring Framework

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:

VariableContent
S4_DESTINATIONThe name of the destination defined within the Destination service of Cloud Foundry. Use it when running in Cloud Foundry.
S4_URLThe URL of the backend ERP system. Use it when running locally.
S4_USERNAMEThe user name to access the backend ERP system. Use it when running locally.
S4_PASSWORDThe user name to access the backend ERP system. Use it when running locally.
S4_APIKEYYour 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:

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

    InformationValue
    GitHub repository URLhttps://github.com/SAP-samples/cloud-sdk-learning-journey.git

    To clone, close any open folder, then open a Terminal (TerminalNew Terminal) and run the following commands:

    Code snippet
    cd ~/projects
    git clone https://github.com/SAP-samples/cloud-sdk-learning-journey.git
    Expand
  3. Open the project folder ~/projects/cloud-sdk-learning-journey (use FileOpen Folder).

Task 1: Creating the Spring Boot Development Project

Steps

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

  2. Build and run the application.

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

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

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

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

  5. Deploy the application to Cloud Foundry.

    1. Choose TerminalNew 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
      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
      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
           state     since                  cpu     memory         disk           details
      #0   running   2020-04-24T17:25:03Z   66.4%   167.5M of 1G   152.4M of 1G
      Expand

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

  7. In SAP Business Application Studio, create a debug configuration to attach the remote Java application in Cloud Foundry.

    1. Choose RunAdd Configuration... The launch.json file is opened.

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

      Code snippet
      {
          "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
  8. 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
      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.

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

Task 2: Create the Address Manager Application

Steps

  1. 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
      cd ~/projects/cloud-sdk-learning-journey
      git checkout -f javadman_v2.0_crud
      Expand
  2. Build, run the application and open the Address Manager page.

    1. In the terminal run the following command:

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

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

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

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

    FieldValue
    GroupingInternal numbering for standard use
    BP RoleCRM000 Sold-to-party
    First NameJohn
    Last NameDoe ###
    CityNew York
    CountryUS
    LanguageEN
    1. In the home page, search for and open the Manage Business Partner Master Data app.

    2. Choose CreatePerson.

    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.

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

    NameValue
    S4_URLYour S/4HANA Client tenant URL, for example https://my000000.s4hana.ondemand.com
    S4_USERNAMEADDRESS_MANAGER_###
    S4_PASSWORDWelcomeToTheClouds1!
    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
      /address-manager/index.html#/businessPartners/1000000
      Expand
      Replace 1000000 with your business partner ID.
    6. Stop the application.

  7. Deploy the application to Cloud Foundry.

    1. Choose TerminalNew 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
      cf login
      
      Expand
      Enter your SAP BTP API endpoint, e-mail, and password.

    3. In the Terminal, run the following commands:

      Code snippet
      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
           state     since                  cpu     memory         disk           details
      #0   running   2020-04-24T17:25:03Z   66.4%   167.5M of 1G   152.4M of 1G
      Expand

  8. 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):

      KeyValue
      S4_URLhttps://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.

  9. 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 ServicesInstances tab.

    3. In the Space:dev - Service Instances screen, Choose Create. Create a new instance based on the following information:

      FieldValue
      ServiceDestination Service
      Service Planlite
      Instance Namemy-destinations
  10. 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.

  11. 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 ServicesInstances 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:

      FieldValue
      Namesandbox
      TypeHTTP
      DescriptionSAP API Business Hub sandbox system
      URLhttps://sandbox.api.sap.com/s4hanacloud
      Proxy TypeInternet
      AuthenticationNoAuthentication
  12. 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.

  13. 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 ServicesInstances 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):

      FieldValue
      Names4cloud
      TypeHTTP
      DescriptionSAP S/4HANA Cloud tenant
      URLYour S/4HANA Client tenant URL, for example https://my000000.s4hana.ondemand.com
      Proxy TypeInternet
      AuthenticationBasicAuthentication
      UserADDRESS_MANAGER_###
      PasswordWelcomeToTheClouds1!
  14. 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.

Log in to track your progress & complete quizzes