Download_and_Installation_Instructions.md

How to Download and Install the Sample App

Prerequisites

• You understand the concepts of multitenancy in the Cloud Foundry environment; see this blog.
• You understand the domain model (account structure) of SAP Cloud Platform; see this blog.
• You know how to develop a Multi-Target Application (MTAR) on SAP Cloud Platform, Cloud Foundry environment; see here

Deploying the application to SAP Cloud Platform

In this section, we'll cover the steps that are needed deploy the sample multitenant business application to your Cloud Foundry space in your SAP Cloud Platform account.

1. Open SAP Web IDE and clone the project that is available here.

   

2. Take a second to study structure of the project:

   • Basic file structure (inventoryManagementApp):

     

   • Server app file structure (…\inventorymanagementbackend):

     

   • UI app file structure (…\inventorymanagementui):

     

3. Using your WEB IDE Files explorer open mta.yaml file as shown in the image.

4. Add the CF Domain in your Tenant Host Pattern and save your changes.

5. Now that you have cloned the repository and made the necessary code changes, you need to build an MTAR:

   1. Locate the inventoryManagementApp project entry in the file structure.
   2. Right-click on the project entry and choose Build → Build

6. Once the build is completed, you should see a new folder created in your file explorer:

   

7. Now, right click on the newly created .mtar file and choose Deploy → Deploy to SAP Cloud Platform

8. Enter in the SAP Cloud Platform, Cloud Foundry environment details where you want to deploy the application. The subaccount to which you deploy the application is referred to as the provider subaccount.

   The app deployment process starts. Once the app is deployed successfully, you'll see progress notifications on the top righthand corner.

   

Making the application available in the CF SaaS registry

In this section, we'll cover the steps that you need to do so that your application is registered and available in SAP Cloud Platform as a multitenant application. Your hosted application will then visible to other consumer subaccounts (tenants) and allow them to subscribe to it.

1. Using the project explorer in SAP Web IDE, go to config.json in the mtconfig folder.

   

2. Make sure the file contains the following code:

   {
       "appId": "<XS-App name goes here>",
       "displayName": "Inventory Management App",
       "description": "An app to manage your inventory",
       "category": "Provider XYZ",
       "appUrls": {
           "onSubscription": "https://<Your back-end app URL>/callback/v1.0/tenants/{tenantId}"
       }
   }

   We'll be filling in some of the necessary information in the next steps.

3. Using the cf CLI, connect to your space in your Cloud Foundry landscape.

4. View the environment variables of your application by executing the following command in the cf CLI:

   cf env inventorymanagementbackend

5. Copy the value of VCAP_SERVICES.xsuaa.credentials.xsappname to the <XS-App name goes here> placeholder in your mtconfig/config.json file.

6. In the mtconfig/config.json file, replace the <Your back-end app URL> placeholder with your backend app’s URL including the CF domain.

   The URL for your onSubscription parameter should now look something like this:

   https://inventorymanagementbackend.<CF Domain>/callback/v1.0/tenants/{tenantId}

7. Using the project explorer, go to index.js in the inventorymanagementbackend/routes folder.

8. Make sure the index.js file contains the following code:

       router.put('/callback/v1.0/tenants/*', function (req, res) {
           var consumerSubdomain = req.body.subscribedSubdomain;
           var tenantAppURL = "https:\/\/" + consumerSubdomain + "-inventorymanagementui." + "<Your CF Domain>";
           res.status(200).send(tenantAppURL);
       });

9. In the index.js file, replace the <Your CF Domain> placeholder with your backend app’s URL including the CF domain. Do not include the HTTP/HTTPS protocol.

   Your tenantAppURL parameter should now look something like this:

   var tenantAppURL = "https:\/\/" + consumerSubdomain + "-inventorymanagementui.<CF Domain>";

10. In some of the steps that follow, you'll be using the cf CLI tool. To execute these commands, navigate your terminal's working directory to inventoryManagementApp, where your .yaml file resides.

11. Create a new service instance of the SaaS registry by executing this command:

    cf cs saas-registry application mt-im-app-lps-registry -c mtconfig/config.json
    

12. Bind the app to the SaaS registry service instance by executing this command:

    cf bs inventorymanagementbackend mt-im-app-lps-registry
    

13. Re-stage the app by executing this command:

    cf restage inventorymanagementbackend
    

Subscribe your consumer accounts to the deployed multitenant business application

1. Sign in to the SAP Cloud Platform.

2. Navigate to the global account where you deployed the sample multitenant business application.

3. Create a Cloud Foundry subaccount for the application consumer (tenant). There's no need to create a Cloud Foundry org and space.

4. Navigate to the new consumer subaccount and open the Subscriptions tab. You should see the Inventory Management App under the Provider XYZ category.

   

5. Click on the Inventory Management App tile and then on the Subscribe button.

6. Once the subscription process is completed, click on the Go to Application link to open the consumer app.

7. If you are unable to access the application and are observing the issue, as highlighted in the image, please do the following:

   • Go to SAP Cloud Platform Cockpit → Subaccount → Space and click on Routes.
   • Click on New Route
   • In the pop-up that appears enter the following details and click on Save.

     Domain: <Select the CF Domain of your tenant URL>
     Host Name: <Enter the tenant app-host name>
     Path: Empty
     

     
   • Now search for the new route that you've created and click on Map Route action as shown in the image.
   • In the popup that appears, select the inventorymanagementui app (App Router app) and click on Save
   • Now that you're route is mapped to your application, you can navigate to the app using the tenant URL by clicking on the Launch Route action as shown in the image.

8. You can create additional consumer subaccounts and subscribe to the same sample multitenant business application.

   Add unique items to the product inventory in each consumer application and note that the stored information is isolated and secured per tenant.

Additional Information

For detailed documentation about these steps, including guidelines for creating tenant-aware applications, refer to Developing Multitenant Business Applications in the Cloud Foundry Environment on SAP Help Portal.