Exercise: Building a BP address manager extension using TypeScript

In a local folder (folder N:\workspace if you are in the SAP Learning System), use the Nest CLI to generate a new extension application named: ts-adman.

1. Open the Windows PowerShell Change directory to the workspace folder where you wish to create the project sub folder. Execute the following command:

   Code snippet

   Copy code

   nest new ts-adman

   Copy code

   Note

   If the nest command is not available in your environment, then use the following command:

   Code snippet

   Copy code

   npx -p @nestjs/cli nest new ts-adman

   Copy code

   This way the @nestjs/cli module will be directly downloaded from the npmjs.com store and immediately executed.

   Provide the following answers to the questions you are asked during the creation process:

   Question	Answer
   Which package manager would you like to use?	npm

   The initial application is created. The process will last several minutes as all of the dependent node packages are downloaded from the internet. The final result is a Hello World application based on TypeScript and the Nest framework.

Build and start the application from the command line. Open it in the browser, then stop the application.

1. In the PowerShell, run the following commands:

   Code snippet

   Copy code

   cd ts-adman
   npm install
   npm run build
   npm start

   Copy code

   Wait till the following message appears: Nest application successfully started.

2. Open the Web browser (for example, Google Chrome) at the following URL: http://localhost:3000

   The browser returns Hello World!.

3. Back to the PowerShell, choose Ctrl+C, then choose Y to terminate the batch job.

Open the application with Visual Studio Code.

1. In the PowerShell, run the following command:

   Code snippet

   Copy code

   code .

   Copy code

   Visual Studio Code is opened, displaying the project folder content.

Review the main project files.

1. Review the following files:

   • The package.json file: containing project dependencies on external node packages.
   • All the files in the src folder: containing the TypeScript application, based on the Nest framework.

In Visual Studio Code, build the application, then run it with debug and watch options.

1. In the Visual Studio Code, choose Terminal → New Terminal.

2. In the terminal, run:

   Code snippet

   Copy code

   npm run build

   Copy code

   The TypeScript files are converted to JavaScript and stored in the dist folder.

3. Choose Run → Add Configuration ... → Node.js. The launch.json file is opened.

4. In the launch.json file, replace the existing configuration with the following one (that is, replace the whole content in the square brackets with the following):

   Code snippet

   Copy code

   {
               "name": "Launch Application",
               "type": "node-terminal",
               "request": "launch",
               "command": "npm run start:debug",
               "cwd": "${workspaceFolder}"
           }

   Copy code

   As an alternative, you can copy the full ts_adman_01_launch_json.txt file [download], and replace the full content of the launch.json file.

5. Switch to the Run and Debug tab. Choose Start Debugging (F5) aside the Launch Application configuration.

6. Wait till the application starts and the following message appears in the terminal : Nest application successfully started (eventually switch to terminal in the lower part of the Visual Studio Code window).

Switch to the Explorertab, open the src/app.controller.ts file and set a breakpoint at line 10. The open the application and verify that the execution stops at the breakpoint.

1. In the VS Code Explorer tab, open the src/app.controller.ts file and click on the border of the editor window, on the left side of the line number 10. A red dot appears.

2. Open the Web browser (for example, Google Chrome) at the following URL: http://localhost:3000

   The program execution stops at the breakpoint in Visual Studio Code.

3. In Visual Studio Code, choose Continue (F5). The program execution continues and Hello World! appears in the browser.

4. Click on the red dot beside line 10 and remove the breakpoint.

Verify that the watch mode works properly. Open the src/app.service.ts file and change Hello World! to Hello SAP!. The change will be identified and the application re-runs automatically.

1. Open the src/app.service.ts file.

2. Replace Hello World! with Hello SAP!.

3. Save (Ctrl+S). Observe in the terminal that the application is automatically re-started.

4. Open the Web browser at the following URL: http://localhost:3000

   The browser returns Hello SAP!.

   Note

   During application development, the watch automatic mechanism can fail and the generated JavaScript code is not in sync anymore with the source TypeScript code. If you realize this is happening, stop the application, then build and run it again as per the previous exercise steps.

5. Choose Stop to stop execution and close the terminal window.

Commit changes in Source Control.

1. Choose the Source Control tab.

2. In the Message field, enter any text (for example initial), choose Commit.

3. In case a popup window appears, choose Always.

4. Switch back to the Explorer tab.

Adapt the project for deployment to Cloud Foundry.

1. Open the src/main.ts file.

   Find this line:

   Code snippet

   Copy code

   await app.listen(3000);

   Copy code

   and replace it with the following line:

   Code snippet

   Copy code

   await app.listen( process.env.PORT || 3000 );

   Copy code

   Then save the file.

2. In the root project folder, create a new file with name manifest.yml, containing the following text.

   Code snippet

   Copy code

   applications:
     - name: ts-adman
       path: ./
       buildpacks:
         - nodejs_buildpack
       memory: 256M
       command: npm run start:prod
       random-route: true

   Copy code

   This text can also be found in the provided ts_adman_02_manifest_yml.txt file [download].

3. In the root project folder, create a new file with name .cfignore, containing the following text.

   Code snippet

   Copy code

   node_modules

   Copy code

Deploy the application to Cloud Foundry.

1. In the Visual Studio Code, if a Terminal window is not opened yet, choose Terminal → New Terminal.

2. If required, in the Windows PowerShell, execute the following command:

   Code snippet

   Copy code

   cf login
   

   Copy code

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

3. In the terminal, run:

   Code snippet

   Copy code

   npm run build

   Copy code

   The TypeScript files are converted to JavaScript and stored in the dist folder.

4. In the terminal, run:

   Code snippet

   Copy code

   cf push

   Copy code

   The application is uploaded to Cloud Foundry, installed and run.

   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

   Copy code

In the SAP BTP Cockpit, navigate to the running application 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 ts-adman application name.

4. Choose the Application Route. The application opens and Hello SAP! is returned in the browser page.

In Visual Studio Code, commit changes in Source Control.

1. Choose the Source Control tab.

2. In the Message field, enter any text (for example Deployed to Cloud Foundry), choose Commit.

3. Switch back to the Explorer tab.

In Visual Studio Code, create a debug configuration to attach the remote Nest application in Cloud Foundry.

1. In Visual Studio Code, choose Run → Open Configurations. The launch.json file is opened.

2. In the launch.json file, add the following debug configuration (for simplicity, you can copy the entire contents of the ts_adman_03_launch_json.txt file [download] ):

   Code snippet

   Copy code

   {
               "name": "Attach Application",
               "type": "node",
               "request": "attach",
               "port": 9229,
               "localRoot": "${workspaceFolder}",
               "remoteRoot": "/home/vcap/app"
           }

   Copy code

Optional: Debug the application in Cloud Foundry using Visual Studio Code: Set a breakpoint and make an execution stop at line 10 of the src/app.controller.ts file.

Note

This step cannot be performed by multiple users simultaneously on the same system.

1. In Visual Studio Code, open the manifest.yml file and observe the command to run the application in Cloud Foundry:

   Code snippet

   Copy code

   command: npm run start:prod

   Copy code

2. Open the package.json file and search for the following line:

   Code snippet

   Copy code

   "start:prod": "node dist/main",

   Copy code

   To enable the application for debugging, add a --inspect option in the command, so that it becomes the following:

   Code snippet

   Copy code

   "start:prod": "node --inspect dist/main",

   Copy code

3. Deploy the previous change. In Visual Studio Code. In the terminal window, run:

   Code snippet

   Copy code

   cf push

   Copy code

4. To enable the application for debug, in the terminal, execute the following commands (you can find them in the ts_adman_enable_cf_debug.txt file [download] ):

   Code snippet

   Copy code

   cf enable-ssh ts-adman
   cf restage ts-adman
   cf ssh -N -T -L 9229:localhost:9229 ts-adman

   Copy code

5. In Visual Studio Code, in the Run window, run the Attach Application configuration. The debugger attaches to the remote application.

6. Open the src/app.controller.ts file and set a breakpoint (red dot aside the line number) at line 10:

   Code snippet

   Copy code

   return this.appService.getHello();

   Copy code

7. Switch back to the application tab (containing Hello SAP!) and refresh the browser window.

   The program execution stops at the breakpoint. Switch the tab back to Visual Studio Code.

8. In Visual Studio Code, choose Continue (F5). The execution is resumed.

9. In Visual Studio Code, disconnect the debugger.

10. In the terminal, choose Ctrl + C and terminate the cf ssh command.

In Visual Studio Code, commit changes in Source Control.

1. Choose the Source Control tab.

2. In the Message field, enter any text (for example Ready for remote debugging), choose Commit.

3. Switch back to the Explorer tab.

Open the SAP Business Application Studio, open the training development space.

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. Choose Services → Instances and Subscriptions.

4. Choose SAP Business Application Studio.

5. Eventually start the training development space.

6. Once the space is running, click on training to enter the development space.

Open a terminal window and verify if the Nest CLI is already installed (in the global NPM packages). If it is missing, install it.

1. Choose File → Open Workspace... (Ctrl+Alt+W), choose the projects folder and choose Open.

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

3. In the terminal, execute the following command:

   Code snippet

   Copy code

   npm list -g --depth=0

   Copy code

   A list of NPM global packages displays with their version.

4. If the list does not contain package: @nestjs/cli, execute the following command:

   Code snippet

   Copy code

   npm install -g @nestjs/cli

   Copy code

5. List the packages again; the list now contains the new package.

In your projects folder, use the Nest CLI to generate a new application named ts-adman.

1. In the terminal, execute the following command:

   Code snippet

   Copy code

   nest new ts-adman

   Copy code

   Provide the following answers to the questions you are asked during the creation process:

   Question	Answer
   Which package manager would you like to use?	npm

   The initial application is created. The process will last several minutes as all of the dependent node packages are downloaded from the internet. The final result is a Hello World application based on TypeScript and the Nest framework.

Open the projects/ts-adman folder as a workspace.

1. Choose File → Open Folder..., choose the projects/ts-adman folder and choose Open.

Review the main project files.

1. Review the following files:

   • The package.json file: containing project dependencies on external node packages.
   • All the files in the src folder: containing the TypeScript application, based on the Nest framework.

By default, the application uses port 3000, this won't work in SAP Business Application Studio. Change the application port to 3002.

1. In the src/main.ts file, replace the 3000 with 3002.

Build and start the application from the command line. Open it in the browser, then stop the application.

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

2. In the terminal, run the following commands:

   Code snippet

   Copy code

   npm install
   npm run build
   npm start

   Copy code

   Wait till a pop-up window appears: A service is listening to port 3002. Choose Expose and Open then press enter. A new tab is opened in the browser, showing Hello World!.

3. Back to the terminal, choose Ctrl+C, to terminate the batch job.

In SAP Business Application Studio, build the application, then run it in debug mode.

1. In the terminal, run:

   Code snippet

   Copy code

   npm run build

   Copy code

   The TypeScript files are converted to JavaScript and stored in the dist folder.

2. Choose Run → Add Configuration ... → Node.js. The launch.json file is opened.

3. In the launch.json file, replace the existing configuration with the following code block (replace the entire content in the square brackets with the following):

   Code snippet

   Copy code

   {
         "name": "Launch Application",
         "type": "pwa-node",
         "request": "launch",
         "program": "${workspaceFolder}/dist/main",
         "skipFiles": [
             "<node_internals>/**"
         ]
       }

   Copy code

   As an alternative, you can copy the full ts_adman_01b_launch_json.txt file [download], and replace the full content of the launch.json file.

4. Choose F5 (Run → Start Debugging). Wait till a pop-up window appears: A service is listening to port 3002. Choose Open in New Tab. A new tab is opened in the browser, showing Hello World!.

Open the src/app.controller.ts file and set a breakpoint at line 10. Refresh the application page and verify that the execution stops at the breakpoint.

1. In the Explorertab, open the src/app.controller.ts file and click on the border of the editor window, on the left side of the line number 10. A red dot appears.

2. Switch back to the application tab (containing Hello World!) and refresh the browser window.

   The program execution stops at the breakpoint. Switch the tab back to SAP Business Application Studio.

3. In SAP Business Application Studio, choose Continue (F5). The program execution continues and Hello World! appears in the application tab.

4. Return to the src/app.controller.ts file, click on the red dot aside line 10 and remove the breakpoint.

5. Choose Stop to stop the application execution.

Commit changes in Source Control.

1. Choose the Source Control tab.

2. In the Message field, enter any text (for example initial), choose Commit.

3. Switch back to the Explorer tab.

Adapt the project for deployment to Cloud Foundry.

1. Open the src/main.ts file.

   Find this line:

   Code snippet

   Copy code

   await app.listen(3002);

   Copy code

   and replace it with the following line:

   Code snippet

   Copy code

   await app.listen( process.env.PORT || 3002 );

   Copy code

   Then save the file.

2. In the root project folder, create a new file with name manifest.yml, containing the following text.

   Code snippet

   Copy code

   applications:
     - name: ts-adman
       path: ./
       buildpacks:
         - nodejs_buildpack
       memory: 256M
       command: npm run start:prod
       random-route: true

   Copy code

   This text can also be found in the provided ts_adman_02_manifest_yml.txt file [download].

3. In the root project folder, create a new file with name .cfignore, containing the following text.

   Code snippet

   Copy code

   node_modules

   Copy code

Deploy the application to Cloud Foundry.

1. In the Visual Studio Code, if a Terminal window is not opened yet, choose Terminal → New Terminal.

2. If required, in the Windows PowerShell, execute the following command:

   Code snippet

   Copy code

   cf login
   

   Copy code

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

3. In the terminal, run:

   Code snippet

   Copy code

   npm run build

   Copy code

   The TypeScript files are converted to JavaScript and stored in the dist folder.

4. In the terminal, run:

   Code snippet

   Copy code

   cf push

   Copy code

   The application is uploaded to Cloud Foundry, installed and run.

   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

   Copy code

In the SAP BTP Cockpit, navigate to the running application 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 ts-adman application name.

4. Choose the Application Route. The application opens and Hello SAP! is returned in the browser page.

In SAP Business Application Studio, commit changes in Source Control.

1. Choose the Source Control tab.

2. In the Message field, enter any text (for example Deployed to Cloud Foundry), choose Commit.

3. Switch back to the Explorer tab.

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

1. Choose Run → Open Configurations. The launch.json file is opened.

2. In the launch.json file, add the following debug configuration (you can copy the entire content of the ts_adman_03b_launch_json.txt file [download] ):

   Code snippet

   Copy code

   {
               "name": "Attach Application",
               "type": "pwa-node",
               "request": "attach",
               "port": 9229,
               "localRoot": "${workspaceFolder}",
               "remoteRoot": "/home/vcap/app",
               "skipFiles": [
                   "<node_internals>/**"
               ]
           }

   Copy code

Debug the remote application running in Cloud Foundry using the debugger in SAP Business Application Studio: set a breakpoint and make execution stop at line 10 of the src/app.controller.ts file.

1. Open the manifest.yml file and observe the command to run the application in Cloud Foundry:

   Code snippet

   Copy code

   command: npm run start:prod

   Copy code

2. Open the package.json file and search for the following line:

   Code snippet

   Copy code

   "start:prod": "node dist/main",

   Copy code

   To enable the application for debugging, add a --inspect option in the command, so that it becomes the following:

   Code snippet

   Copy code

   "start:prod": "node --inspect dist/main",

   Copy code

3. Deploy the previous change. In Visual Studio Code. In the terminal window, run:

   Code snippet

   Copy code

   cf push

   Copy code

4. To enable the application for debug, execute the following commands (you can find them in the ts_adman_enable_cf_debug.txt file [download] ):

   Code snippet

   Copy code

   cf enable-ssh ts-adman
   cf restage ts-adman
   cf ssh -N -T -L 9229:localhost:9229 ts-adman

   Copy code

   Ignore the proposal to "Open in a New Tab" the service listening to port 9229.

5. In SAP Business Application Studio, in the Debug window, run the Attach Application configuration. The debugger attaches to the remote application.

6. In the Run window, run the new configuration. The debugger attaches to the remote application.

7. Open the src/app.controller.ts file and set a breakpoint (red dot aside the line number) at line 10:

   Code snippet

   Copy code

   return this.appService.getHello();

   Copy code

8. Switch back to the application tab (containing Hello SAP!) and refresh the browser window.

   The program execution stops at the breakpoint. Switch the tab back to SAP Business Application Studio.

9. In the SAP Business Application Studio, choose Continue (F5). The program execution continues and Hello SAP! appears in the application tab.

10. In SAP Business Application Studio, stop the debugger.

11. In the Terminal, choose Ctrl + C and terminate the cf ssh command.

In SAP Business Application Studio, commit changes in Source Control.

1. Choose the Source Control tab.

2. In the Message field, enter any text (for example Ready for remote debugging), choose Commit.

3. Switch back to the Explorer tab.

Back to the application project in Visual Studio Code, add the following packages in the dependencies then install them so they are available for the application programs.

1. Open the package.json file.

2. In the file, at the end of the dependencies section, add the following text:

   Code snippet

   Copy code

   ,
       "@sap-cloud-sdk/connectivity": "^2.11.0",
       "@sap-cloud-sdk/odata-v2": "^2.11.0",
       "@sap/cloud-sdk-vdm-business-partner-service": "^2.1.0"

   Copy code

3. Choose Terminal → New Terminal. In the Terminal, run the following command:

   Code snippet

   Copy code

   npm install

   Copy code

   The dependent node modules are downloaded to the node_modules folder.

On top of the initial application, create an Address Manager back-end application. The Address Manager is able to maintain the address information of SAP S/4HANA Cloud business partners. The application code for the back-end is provided in the ts_adman_backend.zip file [download] .

1. Right-click on the ts-adman/src folder, choose Reveal in File Explorer, extract the content of the ts_adman_backend.zip archive [download] to the src folder.

2. In Visual Studio Code, verify that the new src/adman folder is visible. The folder contains the following TypeScript source files:

   Note

   To better analyze the following source code, we recommend you review the following sections in the standard SAP Cloud SDK documentation:

   • Executing a Request Using a Generated OData v2/v4 Client
   • Use the OData v2 Type-safe Client API

   Content of backend-connector.ts

   Code snippet

   Copy code

   import { DestinationOrFetchOptions } from '@sap-cloud-sdk/connectivity';
   
   export class BackendConnector {
       
       private static destination: DestinationOrFetchOptions;
       private static apikey: string;
   
       public static getDestination(): DestinationOrFetchOptions {
   
           if (this.destination == null) {
               // Get the environment variables
               let destinationName: string = process.env.S4_DESTINATION;
               let url: string = process.env.S4_URL;
               let username: string = process.env.S4_USERNAME;
               let password: string = process.env.S4_PASSWORD;
               
               if (destinationName != null){
                   // Get the destination via the Destination service
                   // of Cloud Foundry, in the SCP.
                   this.destination = {
                       destinationName: destinationName
                   };
               }
               else {
                   // Create the destination at run time,
                   // using the URI and credentials
                   // provided in the environment variables.
                   if(username != null && password != null) {
   
                       // BasicAuthentication
                       this.destination = {
                           url: url,
                           username: username,
                           password: password
                       };
                   }
                   else {
                       // NoAuthentication
                       this.destination = {
                           url: url
                       }
                   }
               }
           }
           return this.destination;
       }
   
       public static getApikey(): string {
           if (this.apikey == null) {
               if (process.env.S4_APIKEY == null) 
                   this.apikey = "";
               else
                   this.apikey = process.env.S4_APIKEY;
           }
           return this.apikey;
       }
   }

   Copy code

   Content of business-partner.service.ts

   Code snippet

   Copy code

   import { Injectable } from '@nestjs/common';
   import { BusinessPartner, businessPartnerService } from '@sap/cloud-sdk-vdm-business-partner-service';
   import { BackendConnector } from './backend-connector'
   import { asc } from '@sap-cloud-sdk/odata-v2';
   
   const { businessPartnerApi, businessPartnerAddressApi } = businessPartnerService();
   
   @Injectable()
   export class BusinessPartnerService {
   
       static findAll(): Promise<BusinessPartner[]> {
           return businessPartnerApi.requestBuilder()
               .getAll()
               .select(
                   businessPartnerApi.schema.BUSINESS_PARTNER,
                   businessPartnerApi.schema.LAST_NAME,
                   businessPartnerApi.schema.FIRST_NAME
               )
               .filter(
                   businessPartnerApi.schema.BUSINESS_PARTNER_CATEGORY
                       .equals("1")
               )
               .orderBy(asc(businessPartnerApi.schema.LAST_NAME))
               .addCustomHeaders({
                   APIKey: BackendConnector.getApikey()
               })
               .execute( BackendConnector.getDestination() );
       }
   
       static findById(id: string): Promise<BusinessPartner> {
           return businessPartnerApi.requestBuilder()
           .getByKey(id)
           .select(businessPartnerApi.schema.BUSINESS_PARTNER,
               businessPartnerApi.schema.LAST_NAME,
               businessPartnerApi.schema.FIRST_NAME,
               businessPartnerApi.schema.IS_MALE,
               businessPartnerApi.schema.IS_FEMALE,
               businessPartnerApi.schema.CREATION_DATE,
               businessPartnerApi.schema.TO_BUSINESS_PARTNER_ADDRESS
                       .select(
                   businessPartnerAddressApi.schema.BUSINESS_PARTNER,
                   businessPartnerAddressApi.schema.ADDRESS_ID,
                   businessPartnerAddressApi.schema.COUNTRY,
                   businessPartnerAddressApi.schema.POSTAL_CODE,
                   businessPartnerAddressApi.schema.CITY_NAME,
                   businessPartnerAddressApi.schema.STREET_NAME,
                   businessPartnerAddressApi.schema.HOUSE_NUMBER))
           .addCustomHeaders({
               APIKey: BackendConnector.getApikey()
           })
           .execute( BackendConnector.getDestination() );
       }
   
   }

   Copy code

   Content of business-partner.controller.ts

   Code snippet

   Copy code

   import { Controller, Get, Query } from '@nestjs/common';
   import { BusinessPartnerService } from './business-partner.service';
   import { BusinessPartner } from '@sap/cloud-sdk-vdm-business-partner-service';
   
   @Controller('api/business-partners')
   export class BusinessPartnerController {
   
     @Get()
     async getBusinessPartners(@Query('id') id: string)
       : Promise<BusinessPartner[] | BusinessPartner> {
       if (id == null) {
         return BusinessPartnerService.findAll()
           .catch(error => {
             console.log(`Failed to get business partners - ${error.message}`);
             return null;
           });
       }
       else {
         return BusinessPartnerService.findById(id)
         .catch(error => {
           console.log(`Failed to get business partner ${id} - ${error.message}`);
           return null;
         });
       }
     }
   }

   Copy code

   Content of business-partner-address.service.ts

   Code snippet

   Copy code

   import { Injectable } from '@nestjs/common';
   import { BusinessPartnerAddress, businessPartnerService } from '@sap/cloud-sdk-vdm-business-partner-service';
   import { BackendConnector } from './backend-connector'
   
   const { businessPartnerAddressApi } = businessPartnerService();
   
   @Injectable()
   export class BusinessPartnerAddressService {
   
       public static async create(address: BusinessPartnerAddress) : Promise<BusinessPartnerAddress> {
           return businessPartnerAddressApi.requestBuilder()
               .create(address)
               .addCustomHeaders({
                   APIKey: BackendConnector.getApikey()
                   })
               .execute( BackendConnector.getDestination() );
       }
   
       public static update(address: BusinessPartnerAddress) : Promise<BusinessPartnerAddress> {
           return businessPartnerAddressApi.requestBuilder()
               .update(address)
               .ignoreVersionIdentifier()
               .addCustomHeaders({
                   APIKey: BackendConnector.getApikey()
                   })
               .execute( BackendConnector.getDestination() );
       }
   
       public static delete(businessPartner: string, addressId: string) 
           : Promise<void> {
           return businessPartnerAddressApi.requestBuilder()
               .delete(businessPartner, addressId)
               .addCustomHeaders({
                   APIKey: BackendConnector.getApikey()
                   })
               .execute( BackendConnector.getDestination() );
       }
   
   }

   Copy code

   Content of business-partner-address.controller.ts

   Code snippet

   Copy code

   import { Controller, Post, Body, Patch, Delete, Query } from '@nestjs/common';
   import { BusinessPartnerAddressService } from './business-partner-address.service';
   import { businessPartnerService } from '@sap/cloud-sdk-vdm-business-partner-service';
   
   const { businessPartnerAddressApi } = businessPartnerService();
   
   @Controller('api/addresses')
   export class BusinessPartnerAddressController {
   
     @Post()
     async postBusinessPartnerAddress( @Body() body ) {
       let bpa = businessPartnerAddressApi.entityBuilder().fromJson(body); //BusinessPartnerAddress.builder().fromJson(body);
       await BusinessPartnerAddressService.create(bpa)
         .catch(error => {
           console.log(`Failed to create business partner address - ${error.message}`);
         });
     }
   
     @Patch()
     async patchBusinessPartnerAddress( @Body() body ) {
       let bpa = businessPartnerAddressApi.entityBuilder().fromJson(body); //BusinessPartnerAddress.builder().fromJson(body);
       await BusinessPartnerAddressService.update(bpa)
         .catch(error => {
           console.log(`Failed to update business partner address ` 
               + `${bpa.addressId} of business partner ${bpa.businessPartner} ` 
               + ` - ${error.message}`);
         });
       }
   
       @Delete()
       async deleteBusinessPartnerAddress(
         @Query('businessPartnerId') businessPartnerId: string,
         @Query('addressId') addressId: string) {
         
           await BusinessPartnerAddressService.delete(businessPartnerId, addressId)
             .catch(error => {
               console.log(`Failed to update business partner address ` 
                   + `${addressId} of business partner ${businessPartnerId} ` 
                   + ` - ${error.message}`);
         });
   
       }
   
   }

   Copy code

3. Open the src/app.module.ts file and add the controllers and providers of the new application (with corresponding import statements). You can pick (from the provided exercise files) the content of the ts_adman_04_app_module_ts.txt file [download] , and copy it in the project of the src/app.module.ts file.

   Code snippet

   Copy code

   import { Module } from '@nestjs/common';
   import { AppController } from './app.controller';
   import { AppService } from './app.service';
   import { BusinessPartnerController } 
     from './adman/business-partner.controller';
   import { BusinessPartnerService } 
     from './adman/business-partner.service';
   import { BusinessPartnerAddressController } 
     from './adman/business-partner-address.controller';
   import { BusinessPartnerAddressService } 
     from './adman/business-partner-address.service';
   
   @Module({
     imports: [],
     controllers: [
       AppController, 
       BusinessPartnerController, 
       BusinessPartnerAddressController],
     providers: [
       AppService, 
       BusinessPartnerService, 
       BusinessPartnerAddressService],
   })
   export class AppModule {}

   Copy code

4. In the terminal, run:

   Code snippet

   Copy code

   npm run build

   Copy code

   The TypeScript files are converted to JavaScript and stored in the dist folder.

Run the application against the SAP API Business Hub sandbox.

1. Start the application with the following environment variables set (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):

   Name	Value
   S4_URL	https://sandbox.api.sap.com/s4hanacloud
   S4_APIKEY	>>>YOUR API KEY<<<

2. Open the .vscode/launch.json file.

3. In the Launch Application configuration, add the values of environment variables (replace >>>YOUR API KEY<<< with your own API Key, for example, FDqbnElM7mgmgqbIKBFHRpS1dvpt6sHD).

   Code snippet

   Copy code

   {
               "name": "Launch Application",
               "type": "pwa-node",
               "request": "launch",
               "program": "${workspaceFolder}/dist/main",
               "skipFiles": [
                   "<node_internals>/**"
               ],
               "env": {
                   "S4_APIKEY": ">>>YOUR API KEY<<<",
                   "S4_URL": "https://sandbox.api.sap.com/s4hanacloud"
                 

   Copy code

   As an alternative, you can copy the entire ts_adman_05_launch_json.txt file [download] , and replace the full content of the launch.json file (replace >>>YOUR API KEY<<< with your own API Key).

4. In Visual Studio Code, in the Run and Debug tab, run the Launch Application configuration.

5. Open the browser at http://localhost:3000, the page shows Hello World!.

6. In the browser, in the application page, edit the URL and add the following suffix:

   Code snippet

   Copy code

   /api/business-partners

   Copy code

   The service you defined in the business-partner.service.ts file is executed and the business partner information is extracted in JSON format.

   

7. In Visual Studio Code, choose Stop (Shift+F5). The application execution is stopped.

In Visual Studio Code, commit changes in Source Control.

1. Choose the Source Control tab.

2. In the Message field, enter any text (for example Back-end service is working.), choose Commit.

3. Switch back to the Explorer tab.

Re-map the Hello World service to the /hello path, to avoid impacting the next step.

1. In the /src/app.controller.ts file, replace the @Get() statement with @Get('hello').

Enable the application to serve static HTML content, using the Nest's @nestjs/serve-static module. The HTML content will be stored in the project within a folder named client.

1. Open the package.json file.

2. In the file, look for the following text:

   Code snippet

   Copy code

       "@nestjs/platform-express": "^9.0.0",

   Copy code

   Just after this text, insert the new dependency line:

   Code snippet

   Copy code

   "@nestjs/serve-static": "^3.0.0",

   Copy code

   The new text will look like the following:

   Code snippet

   Copy code

       "@nestjs/platform-express": "^9.0.0",
       "@nestjs/serve-static": "^3.0.0",

   Copy code

3. In the Terminal, run the following command:

   Code snippet

   Copy code

   npm install

   Copy code

   The new node package is downloaded to the node_modules folder. Once the action is complete, close the terminal window.

4. Open the tsconfig.json file (main configuration file for TypeScript).

5. In the file, look for the following code:

   Code snippet

   Copy code

       "noFallthroughCasesInSwitch": false
     }

   Copy code

   Just before the last curly bracket, add the following code:

   Code snippet

   Copy code

   ,
     "include": ["src/**/*"]

   Copy code

   The final result will look like the following:

   Code snippet

   Copy code

       "noFallthroughCasesInSwitch": false
     },
     "include": ["src/**/*"]
   }

   Copy code

6. In the project root folder, create a sub-folder called client.

7. In the client folder, create a index.html containing the following HTML code:

   Code snippet

   Copy code

   <!DOCTYPE html>
   <html>
   <body>
       <a href="address-manager">Address Manager</a>
   </body>
   </html>

   Copy code

   Copy the content of the ts_adman_06_index_html.txt file [download] , to the project client/index.html file.

8. Open the app.module.ts file.

9. Add the following import statements at the beginning of the file:

   Code snippet

   Copy code

   import { ServeStaticModule } from '@nestjs/serve-static';
   import { join } from 'path';

   Copy code

   Look for the following statement:

   Code snippet

   Copy code

   @Module({
     imports: [],

   Copy code

   Modify it in this way:

   Code snippet

   Copy code

   @Module({
     imports: [
       ServeStaticModule.forRoot({
         rootPath: join(__dirname, '..', 'client'),
       }),
     ],

   Copy code

   You can pick (from the provided exercise files) the content of the ts_adman_06_app_module_ts.txt file [download], and copy it to the project src/app.module.ts file.

Create the Address Manager front-end application, then build and open it. The application code for the front-end is provided in the ts_adman_frontend.zip file [download] .

1. Right-click on the ts-adman/client folder, choose Reveal in File Explorer,

2. Extract the content of the ts_adman_frontend.zip archive [download]to the client folder. The archive contains an address-manager sub folder.

3. In the terminal, run:

   Code snippet

   Copy code

   npm run build

   Copy code

   The TypeScript files are converted to JavaScript and stored in the dist folder.

4. in the Run and Debug tab, run the Launch Application configuration.

5. Open the browser at http://localhost:3000, the page shows the Address Manager link..

6. Click on Address Manager.

   The Address Manager application is opened. You can browse business partners and addresses, but you cannot modify addresses as the SAP API Business Hub sandbox is read-only.

   

7. Close the application page.

8. In Visual Studio Code, choose Stop (Shift+F5) twice. The application execution is stopped.

In Visual Studio Code, commit changes in Source Control.

1. Choose the Source Control tab.

2. In the Message field, enter any text (for example User interface is working.), choose Commit.

3. Switch back to the Explorer tab.

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 the 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 the BR_BUPA_MASTER_SPECIALIST is missing from the list, choose Add.

5. Search for the BR_BUPA_MASTER_SPECIALIST role, select the box beside it and choose OK. Choose Save.

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

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

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. Open the .vscode/launch.json file.

2. In the Launch Application configuration, replace the values of the environment variables:

   Code snippet

   Copy code

   {
               "name": "Launch Application",
               "type": "pwa-node",
               "request": "launch",
               "program": "${workspaceFolder}/dist/main",
               "skipFiles": [
                   "<node_internals>/**"
               ],
               "env": {
                   "S4_URL": "https://my000000.s4hana.ondemand.com",
                   "S4_USERNAME": "ADDRESS_MANAGER_###",
                   "S4_PASSWORD": "WelcomeToTheClouds1!"
               }
           }

   Copy code

   As an alternative, copy the full ts_adman_07_launch_json.txt file [download] , and replace the full content of the launch.json file.

3. Choose F5 (Run → Start Debugging).

4. Open the browser at http://localhost:3000, the page shows the Address Manager link..

5. Click Address Manager.. The Address Manager application is opened. Search your John Doe ### business partner and add a new address to it.

6. Close the application page.

7. In Visual Studio Code, choose Stop (Shift+F5) twice. The application execution is stopped.

Deploy the application to Cloud Foundry.

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

2. In the Terminal, execute the following command:

   Code snippet

   Copy code

   cf login
   

   Copy code

   If required, enter your SAP BTP API endpoint, e-mail, and password.

3. In the Terminal, execute the following command:

   Code snippet

   Copy code

   npm run build
   cf push
   

   Copy code

   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

   Copy code

Navigate to the running application in the SAP BTP Cockpit. Configure the environment variables for it to run against the SAP API Business Hub sandbox, then 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 ts-adman application name.

4. In the Application: ts-adman - 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<<<

5. Go to the Overview tab and restart the application.

6. Choose the Application Route. The application is opened.

7. Click on Address Manager. 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 Authorization & Trust Management service with name my-xsuaa.

1. In Visual Studio Code, in the project root folder, create a new file named xs-security.json with the following content:

   Code snippet

   Copy code

   {
       "xsappname": "ts-adman",
       "tenant-mode": "shared"
   }

   Copy code

   You can pick (from the provided exercise files) the content of the ts_adman_08_xs_security_json.txt file [download] , and copy it in the project to the xs-security.json file.

2. In the SAP BTP Cockpit, navigate to the trial sub-account, then to the dev space.

3. In the dev space, navigate to Services → Service Marketplace tab. Choose the Authorization & Trust Management tile.

4. In the Authorization & Trust Management screen, choose Create. Create a new instance based on the following information:

   Field	Value
   Service	Authorization & Trust Management
   Plan	application
   Instance Name	my-xsuaa
   Specify Parameters in JSON format	{ "xsappname": "ts-adman", "tenant-mode": "shared" }

Connect the my-xsuaa service to the ts-adman application.

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

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

3. Choose Bind Service.

4. Select Service from the catalog. Choose Next.

5. Choose the Authorization & Trust Management service. Choose Next.

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

7. Choose Finish.

In Cloud Foundry, in the case it does not exist yet, create an instance of the Destination service named my-destinations.

1. In the SAP BTP Cockpit, navigate to the trial sub-account, then navigate to the dev space.

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

3. In the Service Instances screen, choose Create Instance. Create a new instance based on the following information:

   Field	Value
   Service	Destination
   Service Plan	lite
   Instance Name	my-destinations

Bind the my-destinations service to the ts-adman application.

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

2. In the Application: ts-adman - 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 the case it does not exist yet, create a destination named sandbox, referring to the SAP API Business Hub sandbox.

1. In the SAP BTP Cockpit, navigate to the dev space, then to the Services → Service Instances tab.

2. In the Service Instances screen, choose the my-destinations instance.

3. In the my-destinations pane, choose More information is available for this instance. See here

4. Choose the Destinations tab.

5. 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
   Use default JDK truststore	checked

   Once you have saved the destination, choose Check Connection to verify that the destination can be reached.

Adapt the environment variables of your application so that it reads the system information from the destination service. Then restart and open the application again.

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

2. Delete the S4_URL variable.

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

4. Go to the Overview tab and restart the application.

5. Choose the Application Route. The application opens in the Address Manager link page.

6. Click Address Manager. 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 required.

1. Return to the main page of the dev space, navigate to Services → Service Instances page. Choose the my-destinations instance. Click on More information is available for this instance. See here

2. Choose the Destinations page.

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.

3. Optionally, delete the S4_APIKEY variable.

4. Go to the Overview tab.

5. Restart the application.

6. Choose the Application Route. The application opens on the Address Manager link page.

7. Click Address manager. 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.