Goal of this blog post

HenningH · ‎10-09-2017

Disclaimer: This blog post describes the state as of 2018 and may be outdated. Feel free to check out our other tutorials on the SAP Cloud SDK.

The following steps will explain how to provide multi-tenant web applications in an SAP Fiori Launchpad on SAP Cloud Platform Cloud Foundry. We will explain the necessary steps at the example of the application developed with the SAP S/4HANA Cloud SDK in the previous steps of this tutorial.

Note: This post is part of a series. For a complete overview visit the SAP S/4HANA Cloud SDK Overview.

Goal of this blog post

The SAP Fiori Launchpad provides a common entry point to SAP Fiori apps for all users. A Launchpad shell hosts SAP Fiori apps, makes them avaialble as tiles, and provides those apps with navigation, personalization, and other services.

This tutorial will cover how to create a Fiori Launchpad on SAP Cloud Platform Cloud Foundry similar to the screenshot below. The Launchpad will provide the Business Partner Explorer application as one tile that can be launched within the Launchpad. The Launchpad will be deployed on Cloud Foundry and refer to the application hosted on Cloud Foundry at run time. In order to create and configure the Launchpad, we will use the Portal Service on Cloud Platform Neo at design time.

We will describe how a provider of Cloud Platform applications can use the Launchpad to provide a unified entry point to his suite of applications for his customers. We will not consider the use case of a customer of different applications who wants to unify access to those applications on his self-created Launchpad. Stay tuned for updates on the latter use case in the future, once the corresponding functionality becomes available on SAP Cloud Platform Cloud Foundry.

Based on this use case of a single provider with many customers (that is, many tenants), the Launchpad will be multi-tenant: each customer (tenant) is served by the same application, and therein isolated from other tenants. While it is possible to have a dedicated Launchpad for a single tenant, Cloud native Software-as-a-service should be multi-tenant-enabled from the start, which is why we will focus on that scenario in the following.

The tutorial proceeds along the following sections:

Subscribe to the Portal service on Neo

Prepare the Fiori Launchpad in your Cloud Foundry account

Create the Fiori Launchpad in the Portal service on Neo

Configure the Fiori Launchpad

Deploy the Fiori Launchpad to your Cloud Foundry account

Prerequisites

You have completed the tutorial step 4 (Call an OData Service).

You have completed the tutorial step 9 (Frontend Application) with the microservice approach.

You have created an SAP Cloud Platform Cloud Foundry (trial) account as explained in step 3 of this tutorial series and deployed the tutorial application to this account. That is, you have two separate applications in your Cloud Foundry space - one for the backend and a separate one for the frontend.

You have created an SAP Cloud Platform Neo (trial) account as for example explained at the beginning of step 2. The Neo account will only be used to access the Fiori Configuration Cockpit. You do not need to have developed or deployed any application on Neo.

Step 7 is optional (in fact, the Fiori Launchpad will replace the approuter introduced therein), but is highly recommended in order to protect your application properly and understand the security-related concepts mentioned in the following.

Subscribe to the Portal Service on Neo

The Portal service available on Cloud Platform Neo provides the design time environment to create SAP Fiori Launchpad sites. Enable it for your account on Neo as follows:

Navigate to your Neo account (created in step 2) in the SAP Cloud Platform cockpit, which is typically called <yourUserID>trial. You can also click Neo Trial on the Home page of the cockpit.

In the menu pane on the left, choose Services.

On the service overview page, look for the service called Portal and click on that tile.

On the page for the Portal service, click Enable.

Wait until the service has been enabled for your account.

Click on the link Go to Service. This will launch the SAP Cloud Platform Portal service.

Note down the URL, which will usually start with https://flpportal-<yourNeoAccount>.dispatcher.hanatrial.ondemand.com - the highlighted part of the hostname is the Portal application ID.

Now that you have subscribed to the Portal service on Neo you are ready to design your Launchpad site. As we want to later deploy this Launchpad to Cloud Foundry, we will first create a representation of that Launchpad in Cloud Foundry and return to the Portal service afterwards.

Prepare the Fiori Launchpad site on Cloud Foundry

The SAP Cloud Platform cockpit offers an easy access to Portal sites such as Launchpad sites from Cloud Foundry.

Navigate to your Cloud Foundry account (created in step 3) in the SAP Cloud Platform cockpit, which is typically called <yourUserID>trial. You can also click Go to Cloud Foundry Trial on the Home page of the cockpit.

Navigate to the trial subaccount and therein to the space dev where your backend and frontend application from the previous steps are deployed.

In the menu pane on the left, choose Portal.

Click on New Site. This will launch the dialog that allows us to create a new Portal site. This site will later be hosted in this Cloud Foundry account.

Enter flp-tutorial as the name and a description for the site.

Next, we have to specify the Neo account where we have subscribed to the Portal service in the previous section. Select the region of the Neo account – in this example based on the previous tutorials: Europe (Rot) - Trial – and enter the Portal application ID (visible in the URL of the Portal service, see above), e.g., flpportal-<yourNeoAccount>.

Click on Create.

You should now see a tile representing the just created site that does not yet have any deployed content. The tile gives us a single place to access activities necessary for populating this site, which we will use in the following.

Create the Fiori Launchpad site

So far, we have only created a blank representation of the Launchpad site to-be on Cloud Foundry. Now we will design the actual Launchpad within the Portal service. The just created Portal tile in your Cloud Foundry account gives quick access to the site in the Portal service on Neo.

Click on the edit icon (a pen sign) to navigate to the portal service.
- Make sure that you don't block the popup window. Alternatively, you should now also see the just created site if you navigate to the URL of the portal service directly.

You should now see the Dashboard for your site in the Neo Portal service.

Each tile on the Fiori Launchpad will be modeled as an App in the site. We will now create two "apps": first, the one for our Business Partner application, and second (optionally), a tile that links to an external web page.

Create the Business Partner app tile

From the Dashboard, navigate to the Apps section (part of the Content Management section) via the menu pane on the left. You should see an empty list of apps.

Click on the add icon (a plus sign) to create a new app

Enter the following properties for the new app:
- App Title: e.g. Business Partner Explorer
- Semantic Object: e.g. BusinessPartner
- Action: e.g. Explore (Semantic object and action could later be used for navigating to your app from other apps within the Launchpad)
- App Type: SAPUI5
- Component URL: e.g. /explore-bupa (We will again use this value later when defining the route for the frontend destination, so make sure to keep it consistent. It is used to navigate to the frontend application within the shell.)
- SAPUI5 Component: sdk-tutorial-frontend (This value has to correspond to the project name used in WebIDE during Step 9 for the frontend application. It is used to locate the central UI5 component of your app. As such, it is also identical to the namespace of the Component.js file of the frontend application.)

Switch to the Catalogs tab, click the add icon above the table, select the Sample Catalog, click OK, select the checkmark next to Sample Catalog.

Switch to the Groups tab, click the add icon above the table, select the Sample Group, click OK, select the Sample Group.

Click Save.

You now have defined your first app that will appear as a tile in the Fiori Launchpad. We still need to configure the Launchpad so that it knows where to find the actual application and how to route requests made to the backend. We will do this in the next section. Before, you can experiment a bit with the visualization of your tile (for example, add an icon to the tile) and preview your Launchpad site using the Site preview icon (a monitor sign) in the top header. You may also want to add a simple tile that launches a URL as explained in the following subsection.

Create the URL tile (optional)

Create a new app similar to the steps above, but with the following properties:

App Title: SAP S/4HANA Cloud SDK

App Subtitle: Website

App Type: URL

URL: https://www.sap.com/s4sdk

Assign it to the same catalog and group and save the app. Afterwards, your list of apps should look as follows.

Configure the Fiori Launchpad

So far, we have designed the tiles that appear on the Fiori Launchpad. We have not yet configured how the Launchpad deals with the UI5 app that we have configured. We need to configure this as part of the package that we will later deploy to Cloud Foundry.

Navigate to Services and Tools by choosing the corresponding section in the menu pane on the left of the Portal service.

On the Site Services overview, click on Package Deployer.

This will open the Package Deployer page where we now configure the components of the package as explained in the next subsections in the following order:

xs-app.json: defines the route mapping to frontend and backend destinations on Cloud Foundry

User Account and Authorization (UAA) service: you can reuse the UAA service instance that you may have created as part of tutorial step 4 or step 7.

mtad.yaml: this is the deployment descriptor for the deployment tool on Cloud Foundry. Here, we will define the actual destinations (URLs) of frontend and backend.

Configure xs-app.json

While creating the Business Partner Explorer app tile in the Launchpad, we have defined that the component for this app shall be located at the path /explore-bupa. Furthermore, the UI as implemented in step 9 will call our business partners service at the path /businesspartners.

Hence, we need to map source path /explore-bupa to the frontend and /businesspartners to the backend destination. We will later define as part of the deployment descriptor where frontend and backend are actually located.

To define the route mapping, proceed as follows:

On the Package Deployer page, click on the link xs-app.json to download the xs-app.json file and store it on your local computer.

Open the downloaded file in a text editor and modify it by adding the two routes for frontend and backend. Including the route for themes that is already present in the downloaded file, the xs-app.json should look as follows after adding the two additional routes.

{

    "routes": [

        {

            "localDir": "themes",

            "source": "/themes/(.*)",

            "cacheControl": "public, max-age=31536000,must-revalidate",

            "target": "$1"

        },

        {

            "source": "^/explore-bupa/(.*)",

            "target": "$1",

            "destination": "frontend"

        },

        {

            "source": "^/businesspartners",

            "destination": "backend"

        }

    ]

}

Upload the modified xs-app.json file to the Package Deployer page by clicking on the Upload button next to the xs-app.json file and selecting the file that you have just modified.

We have now defined that the Launchpad should route calls to /explore-bupa to the destination frontend and just pass on the path after /explore-bupa to the target ($1 refers to the first group of the regular expression in source). Calls to /businesspartners shall be routed to backend. We will define the actual URL of the destinations as part of the mtad.yaml file below. Before, you need to define the UAA service instance for use as authentication service of your Launchpad site.

Configure UAA service

The Authorization and Trust Management service (aka User Account and Authentication, UAA) deals with authentication and authorization of users. Please refer to step 7 of this tutorial series for a detailed explanation.

If you have already created your own instance of the UAA service in your Cloud Foundry space as explained in step 7, you can skip the next subsection and continue with the subsection "Configure UAA service instance for Launchpad" to use that instance for the Launchpad.

Create UAA service instance

If you have not yet created an instance of the UAA service in the space where you will deploy the Launchpad, proceed as follows:

Create a file called xs-security.json in a folder of your choice. We will use this file to configure the UAA service instance. Put the following content into the file and provide a unique xsappname, for example by replacing <USERNAME> with your account name on SAP Cloud Platform Cloud Foundry (e.g. p1234567890trial). With this, we configure that the app will be multi-tenant (tenant-mode: shared) and define a scope and corresponding role-template to be used for authorization.
```
{

  "xsappname": "firstapp-<USERNAME>",

  "tenant-mode": "shared",

  "scopes": [

    {

      "name": "$XSAPPNAME.Display",

      "description": "display"

    }

  ],

  "role-templates": [

    {

      "name": "Viewer",

      "description": "Required to view things in our solution",

      "scope-references"     : [

        "$XSAPPNAME.Display"

      ]

    }

  ]

}
```

Run the following commands from your command line in the folder where you placed the xs-security.json file to create a service instance called my-xsuaa and bind it to your backend application (here called firstapp), which you need to restart afterwards. Binding the instance to your backend is necessary to later include proper authorization in this setup.
```
cf create-service xsuaa application my-xsuaa -c xs-security.json

cf bind-service firstapp my-xsuaa

cf restart firstapp
```

Configure UAA service instance for Launchpad

Afterwards, proceed as follows in both cases - reuse or newly created service instance:

Click on the Edit button next to UAA Service Name.

Enter the name of your service instance of the XSUAA service on SAP Cloud Platform Cloud Foundry: my-xsuaa if you have followed the instructions above or in step 7.

Click Save.

Configure mtad.yaml

Based on the previous subsections, we have now configured the Launchpad site (independent of the particular space where it will be deployed) and prepared the UAA service in your Cloud Foundry account. The deployment requires further information about the environment in which the Launchpad will be running, for example, where to find the abstract destinations mentioned in the routes of the xs-app.json file. The following figure illustrates the overall architecture of how the requests will be routed and which microservices are involved.

We will provide this and similar information in a file called mtad.yaml:

On the Package Deployer page, click on the link mtad.yaml to download the mtad.yaml file and store it on your local computer.

Open the downloaded file in a text editor to modify it as outlined in the following.

Your Launchpad will have a specific identifier that is already appended to several names in the mtad.yaml file, for example, portal-site-9ba4f1e0-a9e6-11e7-9e2f-6b0f982f8dfd. We will refer to this identifier as <flpID> in the following. In your case, this should always be your specific identifier that you can see in the mtad.yaml file.

Locate the section that defines the module site-entry and add a properties key with the TENANT_HOST_PATTERN as follows. Adapt the TENANT_HOST_PATTERN to the host of the Cloud Foundry region you will be deploying on; the below assumes "Europe - Frankfurt" (eu10).
```
  - name: site-entry-<flpID>

    type: javascript.nodejs

    path: site-entry/

    properties:

      TENANT_HOST_PATTERN: '(.*)-flp-tutorial.cfapps.eu10.hana.ondemand.com'

    parameters:

      memory: 256M
```
Make sure that properties is indented using spaces on the same level as the path and that the TENANT_HOST_PATTERN is indented by two additional spaces.

Locate the requires list of the site-entry module and add the definition of two destinations tutorial-frontend and tutorial-backend to the end of this list:

  - name: site-entry-<flpID>

    ...

    requires:

      - name: tutorial-frontend

        group: destinations

        properties:

          name: frontend

          url: ~{url}

      - name: tutorial-backend

        group: destinations

        properties:

          name: backend

          url: ~{url}

          forwardAuthToken: true

      - name: site-host-<flpID>

      ...

Again, carefully align the indentation using spaces.

Locate the section resources section at the end of the mtad.yaml file and add the two destinations at the end. Provide the URLs to your frontend (e.g., firstapp-frontend-USERNAME.cfapps.eu10.hana.ondemand.com) and backend application (e.g., firstapp-USERNAME.cfapps.eu10.hana.ondemand.com) deployed in the previous steps.
```
resources:

  ...

  - name: tutorial-frontend

    properties:

      url: https://<URL-of-frontend>/

  - name: tutorial-backend

    properties:

      url: https://<URL-of-backend>/
```

You may want to check that the name of the service instance configured in the previous section appears in the resources section as value of the parameter service-name of the portal-uaa resource. Here, it is called my-xsuaa as defined above:
```
  - name: portal-uaa

    type: org.cloudfoundry.existing-service

    parameters:

      service-name: my-xsuaa
```

Upload the modified mtad.yaml file to the Package Deployer page by clicking on the Upload button next to the mtad.yaml file and selecting the file that you have just modified.
- For your reference, you can find the complete mtad.yaml file of this example at the end of this blog post.

Click on Download to download the Launchpad package and save the file with the extension .mtar on your local computer.

The .mtar file bundles both the Launchpad that we have defined (apps, catalogs, groups, ...) and the additional configuration. Thus, it contains all required information to deploy our Launchpad site to Cloud Foundry, which we will do in the next section.

Deploy the Launchpad to Cloud Foundry

We have now completely configured the Fiori Launchpad and have a deployable .mtar file, so it's time to deploy the site to our Cloud Foundry account. In the following, we explain how to deploy using the Cloud Platform Cockpit. Please note that there is also a command line tool available to deploy the so-called Multi Target Application (MTA). We explain the usage of the command line tool in the appendix of this blog post.

For the following, you only need the SAP Cloud Platform Cockpit web page.

- Please make sure that you have at least 384 MB of free memory quota in your space - if you have previously done step 7, you may need to stop the approuter application at least during the deployment. The Fiori Launchpad will provide similar functionality as the approuter*. To stop an application, navigate to the Cloud Foundry space and click on the stop icon (a square within a circle) next to the application.
  - * In our setup we do not use a separate approuter for our application for the sake of simplicity. Placing an approuter between Launchpad and application components can still be beneficial to hide the inner mechanics of the application.

Go to your Portal page in your Cloud Foundry space, where we initially created the representation for our Launchpad site in Cloud Foundry during the section "Prepare the Fiori Launchpad site on Cloud Foundry".

Click on the deploy icon (an upward pointing arrow sign) of the flp-tutorial tile we created in the second section of this tutorial.

The dialog Deploy Portal Site appears with a field called Portal Site (*.mtar). Next to it, click on Browse... and select the .mtar file on your local file system that you have downloaded in the previous section.

In the dialog, click Deploy.

The deployment will take some time. Wait for the deployment to finish.
- If you run into trouble while deploying, carefully check the setup described in the previous sections. Ahead of a new deployment, you need to delete the two applications created during the deployment (site-content-<flpID> and site-entry-<flpId>) and the two service instances (site-client-<flpID> and site-host<flpID>). To do so, navigate to the list of applications in your Cloud Foundry space and click on the delete icon (a trash bin sign). Do the same on the Service Instances overview page.

Afterwards, we need to create a route to our Launchpad site that matches the TENANT_HOST_PATTERN configured above in the mtad.yaml file. Run the following command on your command line, replace <flpID> as explained above and <accountSubdomain> with the subdomain of the account that hosts the application (typically, something like p1234567890trial with your user name).
```
cf map-route site-entry-<flpID> cfapps.eu10.hana.ondemand.com -n <accountSubdomain>-flp-tutorial
```
Note: with this, we essentially "subscribe" the hosting account to the application as the first tenant. With the same mechanism, it will be possible to add further routes for other tenants in the future. However, those tenants would need to be associated with the same UAA service instance, something which is only possible by manual intervention of SAP today. For testing purposes, using the hosting account in this way is sufficient.
- With the above multi-tenant setup in place, you should now remove the ALLOW_MOCKED_AUTH_HEADER environment variable that you may have introduced in your backend application as part of Step 5 of this tutorial series. Execute the following command:
```
cf unset-env firstapp ALLOW_MOCKED_AUTH_HEADER
```

The output of the command will include a response similar to the following. Take note of the route mentioned therein. You can access your Launchpad site using this route as the host name.
```
Adding route <accountSubdomain>-flp-tutorial.cfapps.eu10.hana.ondemand.com to app ...
```

After successful deployment, you need to access the just created route (e.g., https://<accountSubdomain>-flp-tutorial.cfapps.eu10.hana.ondemand.com/) to navigate to your new Fiori Launchpad site. You will be prompted for the e-mail address and password of the account you use for SAP Cloud Platform Cloud Foundry.

After the login screen, you will see the Launchpad. You can launch the Business Partner Explorer from the corresponding tile on the Launchpad.

Congratulations! You have integrated your app into the Fiori Launchpad, where it could now be accessible next to other apps, including navigation between apps. Users can benefit from a unified experience and enjoy the advantages of the SAP Fiori Launchpad, including the new features of the Launchpad in SAP Fiori 2.0 like the viewport concept, the Me and Notification area, and much more.

Stay tuned for upcoming blog posts about the SAP S/4HANA Cloud SDK. In the meantime, take the opportunity and experiment with the features of the SAP Fiori Launchpad or the SAP S/4HANA Cloud SDK. You can also read on in the appendix to understand how you can integrate authorization in the Launchpad setup or how to optimize your frontend layout for the Launchpad.

Appendix

Configure authorization

If you have followed step 7, your backend application will already be protected against unauthorized access and only allow users with the Display scope. It makes sense to apply the same authorization also on the level of the Fiori Launchpad. With the current configuration of the apps on our Launchpad site, users that do not have the authorization will still be able to launch the Business Partner Explorer app, but would then see an empty list of business partners (assuming you require the Display scope for the /businesspartners path).

Go to the Portal service in your Neo account (see above).

Navigate to the Apps list.

Select the Business Partner Explorer app in the list.

Click on Edit.

Switch to the tab Scopes.

Click on the add icon above the list of assigned scopes.

In the Select Scopes dialog, you need to add a new scope with the name defined before in the xs-security.json file. Click on New.

Enter $XSAPPNAME.Display as the Name and click OK.

Select the checkbox next to the newly created scope and click OK.

Click Save.

Redeploy the app as outlined in the section "Deploy the Launchpad to Cloud Foundry". Make sure that you remove the previously created artifacts as explained in that section.

Now, the Business Partner Explorer tile will only be shown to users that have the Display scope assigned to their roles in order (see step 7 on how to assign this to your users). All others only see the URL tile (if you have created it for your site) or a blank Launchpad.

Optimize the frontend for the Launchpad

Previously, the frontend was a standalone application that had its own title. The launchpad displays a title in the shell above the app area. Hence, we can remove the header bar from the app itself and should supply a speaking title:

Modify the file i18n/i18n.properties located in your webapp folder: set the appTitle property to an appropriate name, for example, Business Partner Explorer. This name will be shown in the shell bar above the app in the Launchpad.

Modify the file view/View1.view.xml: add the attribute showHeader="false" to the Page element.

Redeploy the front-end with cf push.

Deploy Launchpad site package via command line

Instead of using the Cloud Platform cockpit, you can also use the MTA plugin provided by SAP to deploy .mtar file via the command line. First, you need to install the MTA plugin by following the procedure outlined the help pages.

Afterwards, you can deploy the downloaded .mtar file via the following command (give the path to your .mtar file as the last parameter as shown below):

cf deploy SAP_downloaded_site_<flpID>.mtar

The deployment process will take some time and finish with the output "Process finished." Now you can proceed with the remaining steps as explained above.

Complete mtad.yaml deployment descriptor file

For your reference, please find below the complete mtad.yaml file used in the instructions above. As mentioned, replace <flpID> with the identifier of your Launchpad site.

_schema-version: '2.0'

ID: portal-site-<flpID>

version: 1.2.0

modules:

  - name: site-entry-<flpID>

    type: javascript.nodejs

    path: site-entry/

    properties:

      TENANT_HOST_PATTERN: '(.*)-flp-tutorial.cfapps.sap.hana.ondemand.com'

    parameters:

      memory: 256M

    requires:

      - name: tutorial-frontend

        group: destinations

        properties:

          name: frontend

          url: ~{url}

      - name: tutorial-backend

        group: destinations

        properties:

          name: backend

          url: ~{url}

          forwardAuthToken: true

      - name: site-host-<flpID>

      - name: portal-uaa

      - name: sapui5-provider

        properties:

          sapui5url: '~{url}'

  - name: site-content-<flpID>

    type: com.sap.portal.site-content

    path: site-content/

    parameters:

      health-check-type: none

      memory: 128M

    requires:

      - name: site-client-<flpID>

      - name: portal-uaa

resources:

  - name: site-host-<flpID>

    type: org.cloudfoundry.managed-service

    parameters:

      service: portal-services

      service-plan: site-host

      config:

        siteId: <flpID>

  - name: portal-uaa

    type: org.cloudfoundry.existing-service

    parameters:

      service-name: my-xsuaa

  - name: sapui5-provider

    properties:

      url: 'https://sapui5.hana.ondemand.com'

  - name: site-client-<flpID>

    type: org.cloudfoundry.managed-service

    parameters:

      service: portal-services

      service-plan: site-content

      config:

        siteId: <flpID>

  - name: tutorial-frontend

    properties:

      url: https://<URL-of-frontend>/

  - name: tutorial-backend

    properties:

      url: https://<URL-of-backend>/

Step 18 with SAP Cloud SDK: Your Multi-Tenant Application in SAP Fiori Launchpad on SAP Cloud Platform Cloud Foundry

Goal of this blog post

Prerequisites

Subscribe to the Portal Service on Neo

Prepare the Fiori Launchpad site on Cloud Foundry

Create the Fiori Launchpad site

Create the Business Partner app tile

Create the URL tile (optional)

Configure the Fiori Launchpad

Configure xs-app.json

Configure UAA service

Create UAA service instance

Configure UAA service instance for Launchpad

Configure mtad.yaml

Deploy the Launchpad to Cloud Foundry

Appendix

Configure authorization

Optimize the frontend for the Launchpad

Deploy Launchpad site package via command line

Complete mtad.yaml deployment descriptor file

Get Your SAP HANA Idea Incubator Badge Today!

SCN Mission - SAP HANA Quiz Challenge is now retired

Share your #HANAStory and Win